seamux dispatch

Each piece of work gets its own top-level session, visible and drivable on the seamux board. You declare the whole set first, spawn it, then wait on a barrier that returns every handback at once, keyed by worker. You never react to results one at a time as they arrive.

The CLI is {{SEAMUX_BIN}}.

When to use it

Use it when the pieces are independent: no piece needs another's output to start. If a piece is small enough to finish in a few tool calls, do it yourself instead. If pieces depend on each other, dispatch the first stage, wait, then dispatch the next.

1. Declare the set

Write a manifest. Every worker needs a key (lowercase, digits, -, _), an absolute cwd (or one starting ~/), and a self-contained prompt: the worker starts with none of your context, so say exactly what to do and where to write its output. Give each worker its own output path, so no two workers write the same file.

{
  "title": "Classify firms, batches 1-3",
  "workers": [
    { "key": "batch-01", "cwd": "~/project", "prompt": "Classify the firms in inbox/batch-01.md ... Write results to out/batch-01.md." },
    { "key": "batch-02", "cwd": "~/project", "prompt": "..." },
    { "key": "batch-03", "cwd": "~/project", "prompt": "...", "worktree": true }
  ]
}

Set "worktree": true for a worker that edits a git repo alongside other workers in the same repo, so each gets its own worktree.

2. Spawn it

{{SEAMUX_BIN}} fanout manifest.json

It writes the manifest before spawning anything, starts each worker as its own session with instructions for reporting back, and prints the dispatch id.

3. Wait on the barrier

Run the wait in the background, so you are notified once, when every worker has reported or its session has ended:

{{SEAMUX_BIN}} wait <dispatch-id>

It exits 0 once no worker is left to wait for, and 2 on timeout (default one hour, --timeout <seconds>), printing JSON either way:

{ "complete": true, "pending": [], "gone": ["batch-03"], "failed": ["batch-02"],
  "handbacks": { "batch-01": { "status": "ok", "summary": "...", "result": "out/batch-01.md" }, ... } }

A worker in gone had its session closed without reporting, so it has no handback and never will. A worker is never counted gone in the first few minutes after fanout starts it, while its session may not show yet.

Check progress without blocking with {{SEAMUX_BIN}} status <dispatch-id>.

4. Merge

• Read results only from workers whose handback says ok. A worker reports only after its outputs are fully written, so a result file existing is never the signal; the handback is.
• Merge by worker key, and make the merge idempotent: running it twice gives the same result. Never overwrite hand-authored entries in the target.
• For a failed worker, read its summary, then fix and re-dispatch just that piece as a new, smaller set.
• Treat a gone worker's piece as not done: look at what it left behind before trusting any of it, and re-dispatch it if it's needed.

Worker side

Workers get their reporting instructions appended to their prompt. For reference, a worker reports with:

{{SEAMUX_BIN}} done <dispatch-id> <worker-key> --summary "<what it did and found>" [--result <path>] [--status failed]