pi-config/extensions/pi-crew/docs/live-mailbox-runtime.md

Live Mailbox Runtime Direction

pi-crew currently uses workflow child-process orchestration: a run materializes tasks, executes them through the scheduler, writes artifacts/events, and optionally launches child Pi workers.

A full live mailbox runtime is intentionally out of scope for the current stable surface. Current foundational mailbox files are intentionally simple and local:

{stateRoot}/mailbox/inbox.jsonl
{stateRoot}/mailbox/outbox.jsonl
{stateRoot}/mailbox/delivery.json
{stateRoot}/mailbox/tasks/{taskId}/inbox.jsonl
{stateRoot}/mailbox/tasks/{taskId}/outbox.jsonl

They are exposed through safe API operations (read-mailbox, send-message, ack-message, read-delivery, validate-mailbox) but do not yet imply always-on long-lived workers. If a full runtime is added later, it should build on the foundations already present:

• src/state/contracts.ts for status/event contracts
• src/state/task-claims.ts for claim/lease safety
• src/runtime/worker-heartbeat.ts for liveness
• src/state/locks.ts for run-level mutation safety
• action: "api" for safe interop boundaries

Proposed phases

1. Read-only interop — already started with api operations.
2. Heartbeat writers — allow workers to update heartbeat/progress safely.
3. Claim-safe task lifecycle — expose claim/release/transition operations with tokens.
4. Mailbox — add worker inbox/leader inbox files and delivery state.
5. Live workers — only after the above contracts are stable.

Non-goals for now

• No always-on background worker pool.
• No automatic destructive cleanup of dirty worktrees.
• No recursive team spawning by workers.
• No mailbox mutation without locks and schema validation.