pi-dispatch

pi-dispatch — offload usage

${CLAUDE_PLUGIN_ROOT}/scripts/pi-agent.sh is the name-addressed unified entry point over the pi worker primitives. The registry is the filesystem: $PI_RUNS_DIR/agents/<NAME> symlinks to the run's RUNDIR. Main (the orchestrator) reads this whole file; the ## Operator usage section at the end is what it embeds into a builder brief, and the builder operates those verbs as a pure operator.

How main uses this

1. Decompose the work into self-contained briefs (one observable outcome each). For code-writing tasks, create one worktree per task, put its ABSOLUTE path in the brief, and launch with PI_CWD=<worktree> ${CLAUDE_PLUGIN_ROOT}/scripts/pi-agent.sh start …. The brief tells the worker where to work; only PI_CWD makes it start there, and it is what arms the worktree fence (git shim + write/edit extension). A fresh dispatch without it is refused (exit 2). To run a worker in the current directory on purpose, say so with PI_CWD="$PWD". Every create flag is required:

   ${CLAUDE_PLUGIN_ROOT}/scripts/pi-worktree.sh create \
     --repo_root <repo root> --branch_name <new branch> \
     --base_ref <BASE_REF sha> --base_branch <branch to diff against> \
     --work_path <worktree path> --diff_out <diff file> \
     --cleanup_out <cleanup script> --rundir-file <rundir file>
   

   It prints the worktree path and appends a cleanup block to <cleanup script>. After start, write the worker's RUNDIR into <rundir file> (start prints it as RUNDIR=…; pipe through sed -n 's/^RUNDIR=//p') so cleanup can kill a live worker; an empty file skips the kill. When the work is merged or dropped, run ${CLAUDE_PLUGIN_ROOT}/scripts/pi-worktree.sh clean <cleanup script>: it saves the diff to <diff file> and removes the worktree.

2. Embed the ## Operator usage section — from its heading to the end of this file — verbatim, plus the per-task brief, into a builder dispatch. The builder runs ${CLAUDE_PLUGIN_ROOT}/scripts/pi-agent.sh start per task and ${CLAUDE_PLUGIN_ROOT}/scripts/pi-agent.sh watch as its main loop, and runs each worker's acceptance check when it settles.

3. Terminal status lines persist in the RUNDIR and replay on re-poll; raw stream is kept as pi.stream.jsonl, distilled final text as result.md.

4. stop NAME once a worker's result is consumed. The registry never self-prunes, and every watch re-prints each of ITS named terminal agents on its first sweep.

5. watch requires the names because the registry is machine-wide: an unscoped watch would report on — and quota-abort — another dispatch's workers. ls is the global view.

6. When a batch ends on QUOTA or QUOTA-WINDOW (see the provider wall below), re-dispatch the SAME brief, minus the operator usage, to a Claude builder in self-do mode (${CLAUDE_PLUGIN_ROOT}/docs/main-orchestration.md §6) on the same worktree. One shot: if that fails too, the task is failed.