sno-ai/sno-station-skills/pl-dispatch

PL · Dispatch — opening and scheduling journeys

Scripts named below run as bash "${PL_SKILL_DIR}/scripts/<name>.sh" ..., where PL_SKILL_DIR is the absolute path of the pl skill directory; set it in the same Bash call. When you write text that an executor will read, the executor has no PL_SKILL_DIR: substitute the absolute path of the pl skill's scripts directory for <PL_SKILL_DIR> when you write the dispatch.

Sub-skill of the PL role. The pl core skill invokes this EXPLICITLY when a new journey opens (the owner asks for a dispatch prompt or to open work; "owner" means whoever owns the work, often the user), when scheduling is decided (what's next / what to schedule while the owner is away), or when parallelism/capacity is in question. Core iron rules bind unchanged: never write product code; never trust report prose — disk over words; the owner is addressed in the user's own language, while agent-to-agent text uses the project's working language (English by default). Canonical scripts: the pl skill's scripts/; canonical references: the pl skill's references/. The workspace layout (TODO.md, ai-doc/ACTIVE/PL/, ledger paths) is documented once, in the pl core's State files section; the words mission, registry, ledger, journal, fence, class, close-audit, quiet hours and the rest of the vocabulary are defined in the pl core's Terms.

Writing the dispatch (owner asks for a dispatch prompt or to open work)

Read the pl skill's references/dispatch-template.md and write a dispatch prompt the owner can copy as one block. Hard requirements: the mission header is the first non-empty line, and the dispatch names the journey id and the charter path.

Then the second line depends on which kind of agent this is (core Iron rule 6). For an executor that authors or edits deliverables and works from a charter, the next non-empty line is exactly one bare skill invocation naming the charter: /deliver <charter> for Claude and Cursor, $deliver <charter> for Codex, with no task text on that line; a direct worker skill there is an illegal dispatch. When deliver is not installed, the entry instruction is the one the charter names. The spawner does not check this line; a wrong or missing entry launches and the executor starts work outside the charter — verify the line yourself before spawning. For an operational runner — the job executes something already written and authors nothing — there is no `deliver` line at all; the dispatch names the command, the working directory, and the artifact that proves it ran. Writing a deliver entry into an operational dispatch is the defect this split exists to stop.

Include a finite estimate and a test scope in the dispatch. Use available prior runtimes to estimate preparation, implementation, the affected tests, and reporting. When historical timing is unavailable, state a provisional estimate and its uncertainty; do not suspend development to build or repair an estimator. Tests cover only the changed behavior and direct consumers. By default do not add unrequested gates or run the full suite or evaluations; propose them to the owner as a question. Neither the dispatcher nor a default final-gate instruction may authorize them. The estimator (agentic-time-estimate) is used only when installed; clock times quoted to the owner come from sno report-time when installed, otherwise from date in the owner's zone, never from arithmetic.

Charter authorship is never a spawnable deliverable. A charter records OWNER decisions; it forms only in owner-participating dialogue (the charter skill). A dispatch whose task is "write/fix the charter" is illegal by construction (the spawned agent will invent the decisions the owner never made); nothing mechanical catches a charter path in a fence — the PL reads the fence before spawning and refuses it. The scope fence names the territories of parallel sessions; new journey = new session, never reuse old context; ban git add -A (when the project uses git); the close has three parts (journal, the charter's report, the ledger closed line); the last line names the next baton.

Journey id: any short unique id the PL picks — the board row's id printed by bash "${PL_SKILL_DIR}/scripts/todo.sh" add ... (for example b-0007), or a plain j-1 for work without a board row. Use that one id everywhere: callsign claim, convergence series, fence filename and the Reach X-Work header. The ledger lines for the journey (routed at opening, closed at the end) are written by the PL by hand (bash "${PL_SKILL_DIR}/scripts/todo.sh" close ... adds its own board_closed line for the board row); the PL verifies them at close.

Dispatch prompt goes to disk first: save to ai-doc/ACTIVE/PL/dispatch/<journey_id>.md (create the directory if it is absent) before framing it for the owner to copy — the verbatim intent and scope fence become citable; audits and conflict checks run against this file, not against conversational memory.

Layer routing (automatic by default; the owner can veto with one word): the default is three layers — a planning session produces the plan, a separate executor session writes code and tests, then the planning session accepts the result without having watched the build (blind acceptance). A two-layer pass (one session plans and runs to the end) requires ALL four: ① the charter is not a greenfield product or a cross-repo integration (those are always three-layer); ② the workload is mechanical and homogeneous, review-and-fix, or pure deletion (work whose scope is capped up front, so there is little room to drift); ③ estimated agent clock < 4h; ④ the plan holds no unsettled design forks. The dispatch prompt states layers: 2|3 plus the justification. If the owner has stated quiet hours, a three-layer journey's handoff stop must land before they begin, otherwise give that slot to a two-layer journey — two-layer runs naturally go long without a stop. Failure-set missions bypass this routing entirely — see §Debug-mode dispatch below.

Workspace rule

When the project uses git worktrees: every dispatch uses the checkout it is given; when a selector is required, write workspace: direct. (Other projects use the working directory they were given.) PL and every lower layer must never create, request, delegate, or arrange a new worktree. Independence, disjoint files, safety, speed, and avoiding the integration branch are not exceptions. Only COS may hand the PL an already-created worktree after the owner explicitly ordered that exact worktree in the current conversation. The dedicated PL then owns integration and may not close until it has synced the latest integration branch, merged, run the combined tests, pushed, removed the worktree, and verified only the main checkout remains.

Spawning executors yourself (the default; owner-paste is reserved for when the owner wants a visible window): write the dispatch to disk as always, then launch through the canonical spawner. Do not start executors with a bare nohup codex exec: only the spawner arms the wall, registers the seat and records the spawn. bash "${PL_SKILL_DIR}/scripts/spawn-exec.sh" --journey <j-id> --repo <repo-root> --budget-h <wall> --dispatch ai-doc/ACTIVE/PL/dispatch/<id>.md --class closure|build|operate --addr executor.<journey>@<host> [--runtime codex|claude|hermes|openclaw|cursor] [--fence <fence-file>] [--callsign <preclaimed-name>]

`--addr` IS REQUIRED AND THE SPAWNER REFUSES WITHOUT IT. It is the executor's Reach address, and it is required because an executor nobody can reach is a prohibited spawn: the runner registers that seat before the runtime starts and refuses the spawn if registration fails, which is what makes "you can always wake it" true rather than hoped for. The address is <role>.<name>@<host>, normally executor.<journey>@<host>; Reach rejects a malformed one at registration and the spawn is refused with it.

--runtime selects the coding agent and defaults to codex, so a Claude-only setup must pass --runtime claude on every spawn; claude is equally supported. hermes and openclaw (the Hermes Agent and OpenClaw CLIs) and cursor (the Cursor CLI, cursor-agent, started with --trust) are also accepted but cannot resume a session. A `claude` executor needs one extra step before the launch, or it hangs forever on a screen nobody sees: bash "${PL_SKILL_DIR}/scripts/exec-trust.sh" --repo <the checkout>. A fresh checkout is a directory that runtime has never opened, and it stops on three separate first-run screens there; that command answers all three and is safe to re-run. The same runtime selects the entry syntax: Codex accepts only a bare $deliver <charter> line; Claude and Cursor accept only the bare /deliver <charter> line. Project ids and task prose go on following lines.

--class closure|build|operate — pass it explicitly on every dispatch. The spawner does not refuse a missing value; it defaults to build, so a closure journey launched without --class closure runs under the weaker build rule. Callsign ownership is single: if you claimed one before writing the dispatch (template flow), you MUST pass it via --callsign; the spawner uses it unverified, so a wrong name binds the window to the wrong journey. If you didn't claim one, the spawner claims (and on any pre-launch failure, releases) it. The spawner appends a deadline block to the dispatch (absolute clock times for the budget T and the hard wall 1.5T), starts the runtime in its own systemd user scope, arms a separate systemd user service that sends SIGTERM at T and SIGKILL at 1.5T, and records the spawn in ~/.local/state/agent-spawns.jsonl. The executor runs inside a tmux session named by its callsign — a headless spawn stalls by construction (a read-only .git sandbox, an unwatched process, no live window). The session is a real window and the spawn receipt returns its stable seat address. Keep that address: use sno reach call and sno reach watch to send, read and follow, never raw send-keys Enter; use sno reach seats --json only to recover or confirm a seat and refuse ambiguity. This gives live supervision with no resume step, keeps double-spawn structurally refused, and leaves a wall-killed executor's session up for autopsy. When the owner is present they may prefer opening windows themselves — same rules either way, the spawn just lands in a window they can already see. The wall is enforced by the system, so you have NO extension authority; by default a run killed at the wall is relaunched only by the owner (while the owner is away: park and switch, never wait). Record the spawn on the status board; arm the heartbeat-ring (never a second heartbeat for the same seat) and, when the project uses a GPU, gpu-watch for GPU phases (both via pl-watch). Spawning is not coding — iron rule 1 is untouched. The log file is the heartbeat; a silent log past its estimate is a stall to investigate, never to wait out.

Spawn or keep? — one charter, one agent (core iron rule 7)

The rule is in the core skill; this is how it lands in a dispatch. The unit of staffing is the charter, not the journey. "New journey = new session" governs NEW work — it was never "every follow-up = new agent", and slicing one charter into journeys is a scheduling device that does not re-staff it. Sealing and then killing the agent after every slice forces every successive fix into a fresh hire — serial window churn, each newcomer re-learning context its predecessor already held.