@erclx/canon 5.40.0 → 5.42.0

package/claude/skills/role-orchestrator/references/orchestrator-cloud-launch.md

@@ -7,7 +7,10 @@ description: The cloud build and review shapes, being the launch prompt that car
 
 Run this once `orchestrator-dispatch.md` has cleared a row and picked cloud for it. The worker runs on a Claude Code cloud VM that clones the repository from GitHub, loads no plugin, and cannot see this machine's `.canon/`.
 
-The shape needs a `SessionStart` hook in the repository that, on the VM alone, copies the plugin skills into `.claude/skills/` and puts `canon` on the path. A repository without one cannot take this shape, so fall back to a local worker there. Where the hook exists, the launch prompt calls `/auto-ship` with no `canon:` prefix, since the copied skills list as project skills.
+The shape needs a `SessionStart` hook in the repository that, on the VM alone, copies the plugin skills into `.claude/skills/` and puts `canon` on the path.
+
+- A repository without one cannot take this shape, so fall back to a local worker there
+- Where the hook exists, the prompt calls `/auto-ship` with no `canon:` prefix, since the copied skills list as project skills
 
 ## Contents
 
@@ -19,7 +22,9 @@ The shape needs a `SessionStart` hook in the repository that, on the VM alone, c
 
 ## Check the row is unclaimed
 
-A cloud worker never appears in `canon sessions list` and never pushes the derived branch, since the cloud assigns it a `claude/` branch of its own. So the roster and the refs read clear on a row a cloud worker is already building. Run the local check in `orchestrator-dispatch.md` anyway, since a local worker on the same row still collides, then read the two places a cloud worker does show:
+A cloud worker never appears in `canon sessions list` and never pushes the derived branch, since the cloud assigns it a `claude/` branch of its own, so the roster and the refs read clear on a row it is building.
+
+Run the local check in `orchestrator-dispatch.md` anyway, since a local worker on the same row still collides, then read the two places a cloud worker does show:
 
 ```bash
 prs=$(gh api 'repos/{owner}/{repo}/pulls?state=open&per_page=100' --jq '.[] | select(.head.ref | startswith("claude/")) | .number') || { echo 'unreadable: the open pull request list'; exit 1; }
@@ -37,7 +42,8 @@ Branch on the line it prints rather than on the exit, which a shell function wra
 
 - `claimed: #<n>`: a cloud worker's pull request names the plan slug. Treat the row as claimed and report each number.
 - `clear`, and this pass's launched record holds no cloud session for the row: the row is clear of cloud workers.
-- `unreadable: <what>`: the list or a comment read failed, so nothing was checked. Treat the candidate as unverified and fall back to the human-launch line, the same as a refused local check in `orchestrator-dispatch.md`. Never read it as clear, since an empty answer from a failed read is the collision this check exists to catch.
+- `unreadable: <what>`: nothing was checked, so treat the candidate as unverified and fall back to the human-launch line, as for a refused local check
+- Never read `unreadable` as clear, since an empty answer from a failed read is the collision this check exists to catch
 
 The launched record covers the minutes before the pull request opens, when nothing on GitHub names the row yet. It is this session's alone, so a second dispatcher sees only the pull request list, which is the window `orchestrator-dispatch.md` already states for local workers under `## Hold what this pass already launched`.
 
@@ -67,15 +73,26 @@ session=$(grep -A 2 'Created cloud session:' "$dir/create.typescript" | grep -o
 printf 'session=%s\n' "$session"
 ```
 
-Run it from the main worktree root, since the session targets whichever repository that checkout's `origin` names. That folder is already trusted, so the create screen shows no trust prompt. From a checkout this machine has not trusted, such as a fresh clone of another repository, the screen asks first, and piped keys answer it: replace `<(sleep 30)` with `<(sleep 4; printf '\033[B'; sleep 1; printf '\r'; sleep 30)`. Either way stdin stays open for the create, which is the shape the wrapper was measured in, since an early end of input can reach the terminal before the create screen settles.
+Run it from the main worktree root, since the session targets whichever repository that checkout's `origin` names. That folder is already trusted, so the create screen shows no trust prompt.
+
+- From an untrusted checkout, such as a fresh clone of another repository, the screen asks first, and piped keys answer it
+- Replace `<(sleep 30)` with `<(sleep 4; printf '\033[B'; sleep 1; printf '\r'; sleep 30)` there
+- Either way stdin stays open for the create, the measured shape, since an early end of input can reach the terminal before the screen settles
+
+### The readout
 
-The readout is the text `Created cloud session: <title>`, unanchored since a terminal capture can open a line with escape codes, followed by a `View:` address carrying the `session_...` id. Anything else is a failed create, including a run that exits zero. Report the typescript's last lines and fall back to the human-launch line in `orchestrator-dispatch.md` rather than recording a session that does not exist. The wrapper is a stopgap: any change to the interactive create screen breaks it, which is why the readout fails loudly instead of guessing.
+The readout is the text `Created cloud session: <title>`, unanchored since a terminal capture can open a line with escape codes, followed by a `View:` address carrying the `session_...` id. Anything else is a failed create, including a run that exits zero.
 
-Record `session` beside the row's branch in this pass's launched record. A cloud worker never registers in `canon sessions list`, so that record and the pull request list are the only two readings that know it exists. Report the dispatch the way the local shape does, naming the row, the plan, the repository, and the session id in place of a session name.
+- On a failed create, report the typescript's last lines and fall back to the human-launch line in `orchestrator-dispatch.md`
+- The wrapper is a stopgap any change to the interactive create screen breaks, which is why the readout fails loudly instead of guessing
+- Record `session` beside the row's branch in this pass's launched record, since that and the pull request list are the only readings that know it exists
+- Report the dispatch as the local shape does, naming the row, the plan, the repository, and the session id in place of a session name
 
 ## Recognize the pull request
 
-A cloud worker cannot message this session and never appears in the roster `watch.ts` reads, so its pull request and its `ANNOUNCE:` comment are the announcement. Start the poll in `orchestrator-poll.md` when the cloud dispatch goes out, rather than at that runbook's thirty-minute fallback. A pull request on a `claude/` head is this row's when one of its commits carries a `Claude-Session:` trailer naming the session id the create recorded:
+A cloud worker cannot message this session and never appears in the roster `watch.ts` reads, so its pull request and its `ANNOUNCE:` comment are the announcement. Start the poll in `orchestrator-poll.md` when the cloud dispatch goes out, rather than at its thirty-minute fallback.
+
+A pull request on a `claude/` head is this row's when one of its commits carries a `Claude-Session:` trailer naming the session id the create recorded:
 
 ```bash
 gh api 'repos/{owner}/{repo}/pulls/<number>/commits' --jq '.[].commit.message' | grep -c 'Claude-Session:.*<session>'
@@ -85,15 +102,31 @@ A count above zero matches the row. A count of zero is someone else's pull reque
 
 ## Dispatch a review to a cloud reviewer
 
-Run this once `orchestrator-review-dispatch.md` has sent a code review to a dispatched reviewer and the operator picked cloud for it. The reviewer needs the same `SessionStart` hook as the build shape, and a `canon` on the VM whose `pr` reads run on REST, since the proxy refuses GraphQL. A UI review never takes this shape, because it drives a browser the VM does not have.
+Run this once `orchestrator-review-dispatch.md` has sent a code review to a dispatched reviewer and the operator picked cloud for it. A UI review never takes this shape, because it drives a browser the VM does not have.
+
+- The reviewer needs the same `SessionStart` hook as the build shape
+- It needs a `canon` on the VM whose `pr` reads run on REST, since the proxy refuses GraphQL
+
+### Confirm the REST reads
 
-Confirm the VM's `canon` reads over REST before dispatching. In this repository the setup hook links the checkout's own CLI, so a pushed branch carries the reads. Any other repository's VM installs `canon` from npm, so its `pr` reads run on REST only once a release carrying them is published, and its copied skills carry the REST lookups only once that repository's skills are re-scaffolded from that release.
+Confirm the VM's `canon` reads over REST before dispatching. In this repository the setup hook links the checkout's own CLI, so a pushed branch carries the reads.
 
-Read `npm view @erclx/canon version` against the first release whose changelog names the REST reads, and check the target's copied `review-pr` the same way, by running `grep -rnE 'gh pr (list|view|review|diff|comment)'` over it and expecting no output. A version short of that release, or a hit, dispatches a reviewer that fails on its first GraphQL call, so take the local shape instead.
+- Any other repository's VM installs `canon` from npm, so its `pr` reads run on REST only once a release carrying them is published
+- Its copied skills carry the REST lookups only once that repository's skills are re-scaffolded from that release
+- Read `npm view @erclx/canon version` against the first release whose changelog names the REST reads
+- Run `grep -rnE 'gh pr (list|view|review|diff|comment)'` over the target's copied `review-pr` and expect no output
+- A version short of that release, or a hit, dispatches a reviewer that fails on its first GraphQL call, so take the local shape instead
 
-Check this pass's launched record for a cloud reviewer already holding the number, and run `canon pr review-state <number> --json` for a pass already posted. A cloud reviewer never appears in `canon sessions list`, so the live-session check the local shape runs reads clear on a pull request one already holds.
+### Before the create
 
-The create targets whichever repository the checkout it runs from names as `origin`. For a pull request in this repository, write the prompt to `.canon/tmp/cloud-review-<number>/prompt.md` at the main worktree root and run the create there. For a pull request in another repository, run the create from a checkout of that repository and write the prompt under that checkout's own `.canon/tmp/cloud-review-<number>/`, which its `.gitignore` has to cover before the create runs. A fresh clone made for this is untrusted, so the create takes the trust-prompt key variant under `## The create`:
+Check this pass's launched record for a cloud reviewer already holding the number, and run `canon pr review-state <number> --json` for a pass already posted. A cloud reviewer never appears in `canon sessions list`, so the local shape's live-session check reads clear on one.
+
+The create targets whichever repository the checkout it runs from names as `origin`.
+
+- For a pull request in this repository, write the prompt to `.canon/tmp/cloud-review-<number>/prompt.md` at the main worktree root and create there
+- For another repository, run the create from its checkout and write the prompt under that checkout's own `.canon/tmp/cloud-review-<number>/`
+- That checkout's `.gitignore` has to cover the folder before the create runs
+- A fresh clone made for this is untrusted, so the create takes the trust-prompt key variant under `## The create`:
 
 ```plaintext
 /role-reviewer
@@ -104,12 +137,29 @@ Your controller cannot receive a message from this session. The review you post
 
 The cross-branch facts are the ones `### What the brief may carry` in `orchestrator-launch.md` allows a reviewer brief, and nothing of this session's own read. Neither skill carries the invocation flag, so no position-zero expansion is at stake and the bare names reach the copied project skills.
 
-Create the session with the wrapper under `## The create`, setting `dir` to that prompt's folder, and keep its readout rule: no `session_` id means nothing was dispatched. Record the session id beside the number in this pass's launched record, and name the number, the repository, and the session id in the dispatch report.
+### Create and record
+
+Create the session with the wrapper under `## The create`, setting `dir` to that prompt's folder, and keep its readout rule, so no `session_` id means nothing was dispatched.
+
+- Record the session id beside the number in this pass's launched record, and name the number, the repository, and the session id in the report
+- `poll.ts` reads every open pull request's review state from this machine, so the posted `## Review` reaches the next poll like a local reviewer's
+- Start the poll when the dispatch goes out rather than at its fallback
+- A `QUESTION: review <number>` comment reaches the same poll as an unclassified reply, so answer it on the pull request
+
+### Checking the transcript
+
+The pull request is the record to act on, and the transcript is read back only to check for a refused call. Search the capture for `HTTP 403` and `graphql`, and report a hit as a finding naming a call still on GraphQL rather than reading the review as clean.
 
-`poll.ts` lists every open pull request from this machine and reads each one's review state, so the posted `## Review` reaches the next poll like a local reviewer's. Start the poll when the dispatch goes out rather than at its fallback. A `QUESTION: review <number>` comment reaches the same poll as an unclassified reply, so answer it on the pull request.
+- Run `claude --teleport <session>` under `script` from a throwaway clone of the target outside this repository
+- Answer its trust prompt with the same piped keys
+- Set the terminal to 500 rows first, since only the screen tail is captured otherwise
 
-The pull request is the record to act on, and the transcript is read back only to check for a refused call. Run `claude --teleport <session>` under `script` from a throwaway clone of the target outside this repository, answer its trust prompt with the same piped keys, and set the terminal to 500 rows first, since only the screen tail is captured otherwise. Search the capture for `HTTP 403` and `graphql`. A hit names a call still on GraphQL, so report it as a finding rather than reading the posted review as clean.
+### What a cloud reviewer cannot do
 
-A cloud reviewer cannot be messaged after it posts, and it cannot message the worker either. `poll.ts` reports nothing when a code review posts on an unchanged head, so the poll's cloud-reviewer rule reads `canon pr review-state <number> --json` on every run for each pull request one holds, and sends the `review-address` dispatch from this session when that read shows an open pass. A re-review after the worker's address pass is a fresh dispatch, local or cloud by the same pick, rather than the message a worker sends a live local reviewer.
+A cloud reviewer cannot be messaged after it posts, and it cannot message the worker either. `poll.ts` reports nothing when a code review posts on an unchanged head, so the poll's cloud-reviewer rule reads `canon pr review-state <number> --json` on every run for each pull request one holds.
 
-A cloud reviewer cannot lift the draft mark, since `canon pr lift` makes its one write through the GraphQL mutation the proxy refuses. Leave the lift out of its prompt. The same per-run read runs the verb from this session once the review reads closed at the head on a pull request still a draft. A local reviewer whose run refused reports that refusal in its close message, which reaches loop step 6 rather than the poll.
+- That read sends the `review-address` dispatch from this session when it shows an open pass
+- A re-review after the worker's address pass is a fresh dispatch, local or cloud by the same pick
+- It cannot lift the draft mark, since `canon pr lift` writes through the GraphQL mutation the proxy refuses, so leave the lift out of its prompt
+- The same per-run read runs the verb from this session once the review reads closed at the head on a pull request still a draft
+- A local reviewer whose run refused reports that in its close message, which reaches loop step 6 rather than the poll

package/claude/skills/role-orchestrator/references/orchestrator-dispatch.md

@@ -20,54 +20,65 @@ Run this at loop step 4, for a `## Run now` row whose plan is verified, in place
 
 ## Derive the candidate
 
-Run `canon tasks plan-branch <plan> --json` against the row's plan file and read `branch`, `type`, `slug`, and `conforms` off the record.
+Run `canon tasks plan-branch <plan> --json` against the row's plan file and read `branch`, `type`, `slug`, and `conforms` off the record. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
 
 - `conforms: true`: take `branch` as the candidate, and take `type` and `slug` from the same record for the check below.
-- `conforms: false`: the plan's own filename breaks a cap in `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`. Report which, and hand the row to the human-launch line below rather than shortening the slug here. A rename parts the branch from the plan filename that `session-worktree` tier 1 and `git-pr`'s plan lookup both read back.
-- `reason: archived`, `no-plan`, or `bad-input`: the row does not cite a live plan. Repoint the row or fix the citation rather than dispatching, since `auto-ship` Step 1 refuses the same file and the worker would meet that refusal after the launch spent.
-- Anything else, including a record carrying no `branch` key and an installed binary carrying no `plan-branch` subcommand: treat the candidate as unverified rather than clear, name which reading could not be taken, and fall back to the human-launch line below. Re-deriving by prose here rebuilds the defect the verb closes, and does it quietly.
+- `conforms: false`: the plan's filename breaks a cap in `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`. Report which, and hand the row to the human-launch line below.
+- `reason: archived`, `no-plan`, or `bad-input`: the row cites no live plan, so repoint the row or fix the citation, since `auto-ship` Step 1 refuses the same file
+- Anything else, including no `branch` key or a binary lacking `plan-branch`: treat the candidate as unverified, name the missing reading, and fall back to the human
 
-Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
+### Why the verb decides
 
-The worker calls the same verb on the same plan at `auto-ship` Step 0, so the branch this gate checks and the branch that session takes are one string by construction rather than two readings of one paragraph. Two readings of one plan part on the slug and on the type alike, and a check against a branch nobody uses verifies nothing.
+Never shorten a non-conforming slug here, since a rename parts the branch from the plan filename that `session-worktree` tier 1 and `git-pr`'s plan lookup read back. Re-deriving by prose rebuilds the defect the verb closes, quietly.
 
-The type the verb reports is fixed at `feat`, which is safe because a branch type is cosmetic: `git-stage` and `git-pr` read their types off the diff, and nothing a release reads passes through the branch name. The cost is a worktree listing where every dispatched branch reads `feat/`.
+- The worker calls the same verb on the same plan at `auto-ship` Step 0, so the checked branch and the taken branch are one string by construction
+- Two readings of one plan part on the slug and the type alike, and a check against a branch nobody uses verifies nothing
+- The type is fixed at `feat`, which is safe because `git-stage` and `git-pr` read types off the diff and no release reads the branch name
+- The cost is a worktree listing where every dispatched branch reads `feat/`
 
 ## Check the plan waits on nobody
 
-Run `canon tasks plan-answers <plan> --json` and read `launchable` off the record.
+Run `canon tasks plan-answers <plan> --json` and read `launchable` off the record. Branch on `launchable` rather than on the exit code, which a wrapping shell function can flatten to zero and so read a held row as clear.
 
 - `launchable: true`: the plan answers itself, so proceed to the branch check.
-- `launchable: false`: the row is not dispatchable. Report every entry in `open`, each carrying the question label and the reason its suggestion gave for needing a person, and hand the row to the human-launch line below. Never fill the slot on the operator's behalf, the one move the plan standard forbids outright.
-- `reason: archived`: the row's plan sits in `.canon/plans/archive/` and describes work that already shipped. Repoint the row at a live plan rather than dispatching, since `auto-ship` Step 1 refuses the same file and the worker would meet that refusal after the launch spent.
+- `launchable: false`: report every entry in `open`, each with its question label and stated reason, and hand the row to the human-launch line below
+- Never fill the slot on the operator's behalf, the one move the plan standard forbids outright
+- `reason: archived`: the plan sits in `.canon/plans/archive/` and describes shipped work, so repoint the row, since `auto-ship` Step 1 refuses the same file
 
 ### Refusals and staging
 
-- The command refuses for any other reason, or the record carries no `launchable` key: treat the row as unverified rather than clear, name what could not be read, and fall back to the human. A gate that reads nothing and proceeds is the gate not running.
-- The same read also refuses a plan still staging its batches in one file with `**Batch N**` sub-headings. That reports as an entry in `open` labeled `Batch staging`, so a staged plan reads as `launchable: false` the same way an unanswered operator call does, and the row waits on a split rather than on the operator.
-- An entry labeled `Stacked sibling` means the plan stacks on a live sibling it mostly shares files with, so the row waits on a fold into that sibling or on a `Judged apart from` constraint line, and not on the operator.
+A refusal or a staged plan holds the row as surely as an open question.
 
-Branch on `launchable` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero and so read a held row as a clear one.
+- Any other refusal, or no `launchable` key: treat the row as unverified, name what could not be read, and fall back, since a gate reading nothing is not running
+- A plan still staging batches in one file with `**Batch N**` sub-headings reports an `open` entry labeled `Batch staging`, so the row waits on a split
+- A `Fan-in` entry holds a fan-in set, per `batches.md` in `plan-feature`
+- A `Stacked sibling` entry means the plan stacks on a live sibling it mostly shares files with, so the row waits on a fold or a `Judged apart from` line
 
-This gate runs first because it is the cheapest reading, needing no roster and no ref, and the only one asking about the row itself. It reads the plan rather than a cell describing one, since the conflict check reads sets a dispatcher wrote, and a cell omitting a renamed path clears a check the tree would fail.
+### What the gate reads
 
-A blank `- Answer:` is not an unanswered question. `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` fixes an empty slot as accepting the `- Suggested:` line above it, which is what makes a plan decision-ready in one pass. The narrow case this reads is `- Suggested: needs your call, <why>` and its two demonstrated paraphrases, `needs operator's call` and `needs the operator's call`, over an empty slot, the form that same standard writes where the answer turns on preference rather than on a technical default. A gate reading every blank slot as open would refuse every plan in the folder.
+This gate runs first because it is the cheapest reading, needing no roster and no ref, and the only one asking about the row itself. It reads the plan rather than a cell describing one, since a cell omitting a renamed path clears a check the tree would fail.
 
-What it prevents is a halt nobody is watching for. `role-worker` instructs a session to stop on a question written as needing the operator's call, correctly and by its own body, so a dispatch that never reads the plan lands a worker in a wait for a person who does not know it is waiting. The worker's halt is not the defect, and the dispatch that made it necessary is.
+A blank `- Answer:` is not an unanswered question, since `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` fixes an empty slot as accepting the suggestion. A gate reading every blank slot as open would refuse every plan in the folder.
+
+- The narrow case is `- Suggested: needs your call, <why>` over an empty slot, the form the standard writes where the answer turns on preference
+- Two demonstrated paraphrases read the same, `needs operator's call` and `needs the operator's call`
+
+The gate prevents a halt nobody is watching for. `role-worker` correctly stops a session on a question written as needing the operator's call, so a dispatch that never reads the plan lands a worker waiting for a person who does not know it. The dispatch is the defect, not the halt.
 
 ## Check the branch is unclaimed
 
-Run `canon sessions list --branch <type>/<slug> --json` and read `claimed` off the record.
+Run `canon sessions list --branch <type>/<slug> --json` and read `claimed` off the record. The field is already the composed answer across the worktree listing, the live roster, and the refs naming the branch, so nothing here re-derives the OR.
 
-- `claimed: true`: the row is not free. Report what holds it, `worktree` when it names a path, `sessions` when it carries a row, and `refs` when the branch already exists. Move to the next candidate rather than colliding.
+- `claimed: true`: report what holds it, `worktree` naming a path, `sessions` carrying a row, or `refs` when the branch exists, and move to the next candidate
 - `claimed: false`, `sessionsReadable: true`, and `refsReadable: true`: proceed to the conflict check.
-- `claimed: false` with either flag false, or the command refuses, or the record carries no `claimed` key (`reason` reads `no-registry` or `no-repository`): treat the candidate as unverified rather than clear. Report which reading could not be taken and fall back to the human-launch line below. Dispatching on a check that could not be read reproduces the exact collision this exists to prevent.
+- `claimed: false` with either flag false, a refusal, or no `claimed` key, such as `no-registry` or `no-repository`: treat it as unverified and fall back to the human
+- Dispatching on a check that could not be read reproduces the exact collision this exists to prevent
 
-Reading `claimed` off the record is what keeps this a check rather than a rule a session can talk itself out of. The field is already the composed answer across the worktree listing, the live session roster, and the refs that name the branch, so nothing here re-derives the OR.
+### The refs reading
 
-`refs` is the reading that catches a shipped row. A branch behind a merged pull request has no worktree and no session, so the check answered clear on one until a worker refused the instruction and named the consequences: a second pull request against a head GitHub shows merged, a row whose pull-request line points at two numbers, and the `ambiguous` refusal `canon tasks archive` documents.
+`refs` catches a shipped row, since a branch behind a merged pull request has no worktree and no session. Without it the check answered clear until a worker refused and named the cost: a second pull request against a merged head, a row citing two numbers, and `canon tasks archive`'s `ambiguous` refusal.
 
-What the ref read cannot see is a branch pushed from another machine since the last fetch. A `git ls-remote` per dispatch costs 0.438s against 0.001s, so the gap is recorded rather than closed.
+The ref read cannot see a branch pushed from another machine since the last fetch. A `git ls-remote` per dispatch costs 0.438s against 0.001s, so the gap is recorded rather than closed.
 
 ### A cloud worker's claim
 
@@ -77,32 +88,55 @@ A cloud worker never appears in the roster and never pushes the derived branch,
 
 A worker registers with `branch: main` and the main worktree as its `cwd` until `auto-ship` Step 0 moves it, which took several seconds on both measured runs. Neither the roster nor the refs name the candidate during that window, so a second check inside it reads clear.
 
-Keep the branch of every row this pass has launched and treat a candidate matching one as claimed, without re-running the check. That closes the window for this dispatcher and only for it. A second dispatcher in another session reads git and the roster alone, sees none of this record, and can still take the same row. Say so when reporting, rather than implying the window is shut.
+Keep the branch of every row this pass has launched and treat a candidate matching one as claimed, without re-running the check. That closes the window for this dispatcher alone, since a second dispatcher reads only git and the roster, so say so when reporting.
 
 ## Check for a conflict with the tracks in flight
 
 No count binds this, and a shared file does not either. Hold a candidate behind a track in flight when any of these five holds, naming the hold and the track, and dispatch it otherwise:
 
-1. Dependency. The row or plan cites the track as something it waits on or builds over, including a stacked slice based on the other's branch.
-2. Contract. One plan changes a contract the other consumes, such as an exported signature, a CLI verb's flags or JSON record, a skill step another skill cites, or a config or frontmatter key, read off the changing plan's `**Risks:**`.
-3. Relocation. One plan moves, renames, splits, or deletes a path the other writes or reads, which a rebase cannot settle mechanically. Both sides of a rename sit before the colon of a `**Files to touch:**` entry, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
-4. Sweep. One plan rewrites a file or folder wholesale, such as a terminology pass or a `canon/context/` reflow, and the other writes inside it.
-5. A stated reason, written on the hold: a singleton resource, or tracks interacting where no file reading shows, as a row creating a skill does with one counting that catalog. Nothing verifies the reason, so this hold stands only while the dispatcher applies it.
+- **Dependency.** The row or plan cites the track as something it waits on or builds over, including a stacked slice on the other's branch.
+- **Contract.** One plan changes a contract the other consumes, such as an exported signature, a verb's flags or record, a cited skill step, or a config key.
+- **Relocation.** One plan moves, renames, splits, or deletes a path the other writes or reads, which a rebase cannot settle mechanically.
+- **Sweep.** One plan rewrites a file or folder wholesale, such as a terminology pass or a `canon/context/` reflow, and the other writes inside it.
+- **A stated reason.** A singleton resource, or tracks interacting where no file reading shows, as a row creating a skill does with one counting that catalog.
+
+Read a contract off the changing plan's `**Risks:**`, and both sides of a rename before the colon of a `**Files to touch:**` entry, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. Nothing verifies a stated reason, so it stands only while the dispatcher applies it.
+
+### A shared file is not a hold
+
+Dispatch both and name the shared paths, so the merge order and the second branch's rebase are planned rather than discovered. The branch merging second resolves after the first merges, never against a sibling still building.
+
+- It resolves by running `review-address` in the session that built it, whose Step 5 rebases the branch once it no longer merges
+- A hunk needing a decision the tree does not carry goes to the controller
+- A branch no live session holds gets the review-address shape in `orchestrator-launch.md`
 
-A shared file with none of the five is not a hold. Dispatch both and name the shared paths, so the merge order and the second branch's rebase are planned rather than discovered. The branch merging second resolves after the first merges, never against a sibling still building, by running `review-address` in the session that built it, whose Step 5 rebases the branch once it no longer merges. A hunk needing a decision the tree does not carry goes to the controller, and a branch no live session holds gets the review-address shape in `orchestrator-launch.md`.
+### The evidence
 
-No practitioner source serializes on a shared file. Each builds in parallel and tests at integration, where the merge surfaces a textual conflict and the suite run over the merged result surfaces a semantic one. Fowler's [branching patterns](https://martinfowler.com/articles/branching-patterns.html) have whoever integrates second pull mainline in and check health "even if it's a clean merge", his [Semantic Conflict](https://martinfowler.com/bliki/SemanticConflict.html) names self-testing code as the first defense, [DORA](https://dora.dev/capabilities/trunk-based-development/) keeps branches to a few hours, and GitHub's [merge queue](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) tests each pull request against everything queued ahead of it. A candidate has no commits to trial-merge, so `git merge-tree` runs at integration and this check reads what a plan declares.
+No practitioner source serializes on a shared file. Each builds in parallel and tests at integration, where the merge surfaces a textual conflict and the suite over the merged result a semantic one.
 
-Read `canon sessions list --json` for the branches in flight as well as the board, since a track a person launched by hand carries no row, and read the plan of any branch no row names. `canon tasks validate` and `canon tasks plan-reach` report the paths two rows share, which is a candidate list for the five holds and the paths the dispatch names. A shared folder means a Touches cell claimed it bare, so narrow that cell rather than reading the folder as a sweep.
+- Fowler's [branching patterns](https://martinfowler.com/articles/branching-patterns.html) have the second integrator pull mainline in and check health "even if it's a clean merge"
+- His [Semantic Conflict](https://martinfowler.com/bliki/SemanticConflict.html) names self-testing code as the first defense, and [DORA](https://dora.dev/capabilities/trunk-based-development/) keeps branches to a few hours
+- GitHub's [merge queue](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) tests each pull request against everything queued ahead of it
+- A candidate has no commits to trial-merge, so `git merge-tree` runs at integration and this check reads what a plan declares
 
-A declared set predicts what a branch writes rather than bounding it, since `canon:context-fold`, `canon:docs-sync`, and the regenerated drift stages write past every plan. Such a crossing changes what the second branch rebases over rather than whether a row holds, and `canon tasks plan-reach` at `canon:git-ship` step 5 names it before the pull request opens. What binds past the five holds is review attention, which `## Parallelism` in the skill body states. The one number this skill carries is the review dispatch's count of three in `orchestrator-review-dispatch.md`, which moves a review rather than binding a track, and this runbook carries none.
+### Reading the tracks
+
+Read `canon sessions list --json` for the branches in flight as well as the board, since a hand-launched track carries no row, and read the plan of any branch no row names.
+
+- `canon tasks validate` and `canon tasks plan-reach` report the paths two rows share, a candidate list for the five holds and the paths a dispatch names
+- A shared folder means a Touches cell claimed it bare, so narrow that cell rather than reading the folder as a sweep
+- A declared set predicts rather than bounds, since `canon:context-fold`, `canon:docs-sync`, and the drift stages write past every plan
+- Such a crossing changes what the second branch rebases over, not whether a row holds, and `canon tasks plan-reach` at `canon:git-ship` step 5 names it
+
+What binds past the five holds is review attention, which `## Parallelism` in the skill body states.
 
 ## Pick the model
 
 This section binds every launch shape that names `<model>`, the planner and both reviewers as well as the step 4 build, none of which pass through that step.
 
-A `claude --bg` session inherits the launching session's model, so an orchestrator on the larger model spends it on every session it launches. Name `<model>` on each launch with one test: `opus` where a wrong result is costly and nothing automatic would catch it, `sonnet` otherwise, never `haiku`. Read the role's worst failure and whether a test, gate, or later review stops it, and never the folder or the plan's length.
+A `claude --bg` session inherits the launching session's model, so an orchestrator on the larger model spends it on every launch. Name `<model>` on each with one test: `opus` where a wrong result is costly and nothing automatic would catch it, `sonnet` otherwise, never `haiku`.
 
+- Read the role's worst failure and whether a test, gate, or review stops it, never the folder or the plan's length
 - Planner: `opus` for a row that changes a contract others consume, spans modules, or needs slicing. `sonnet` for a narrow row, even one inside a hook or governance folder.
 - Worker, and the review-address pass against the findings in hand: `opus` where the plan leaves a cross-module call tests will not settle. `sonnet` where it pins the fix, however long.
 - Code reviewer: `opus` where a miss would ship unseen, a change to behavior no test or gate exercises that other surfaces read. `sonnet` otherwise, a one-line hook edit included.
@@ -116,18 +150,25 @@ A row qualifies for that pick when its plan carries no open question and touches
 
 ## Dispatch
 
-Read `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md` once every check above clears, and launch from its build template. That runbook also holds the review-address and planning shapes, which skip the checks above. A row the operator picked for cloud launches from `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md` instead, since the cloud VM shares neither the plugin nor the board with this machine.
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md` once every check above clears, and launch from its build template, which sits beside the review-address and planning shapes that skip these checks. A cloud row launches from `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md`, since the VM shares no plugin or board.
 
 ## Fall back to the human
 
-Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one: the plan still waits on the operator, the plan-answer read could not be taken, the collision check refused, or the row holds behind a track already out under the conflict check, on a dependency, a contract, a relocation, a sweep, or a stated reason. A shared file alone is not listed.
+Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one. A shared file alone is not listed.
+
+- The plan still waits on the operator
+- The plan-answer read could not be taken, or the collision check refused
+- The row holds behind a track already out on a dependency, a contract, a relocation, a sweep, or a stated reason
+
+The first is the one that reaches a person rather than the board. A row held on its branch or under the conflict check waits on the wave clearing, and one held on its plan waits on an answer only the operator can give, so hand it over with the question label and its stated reason attached.
 
-The first of those four is the one that reaches a person rather than the board. A row held on its branch or under the conflict check waits on the wave clearing, where a row held on its plan waits on an answer only the operator can give, so hand that one over with the question label and its stated reason attached rather than as a name and a refusal.
+### The command to hand over
 
-Hand the person one command: `/canon:auto-ship <plan>`, naming the row, the plan path, and the branch together, with no worktree call ahead of it. A leading worktree call adds nothing beyond what `auto-ship` Step 0 already reaches for itself. A second command also risks a client folding two commands into one message, which reads everything after the first command's name as its own argument and drops the second, per `### Position zero` in `orchestrator-launch.md`.
+Hand the person one command, `/canon:auto-ship <plan>`, naming the row, the plan path, and the branch together, with no worktree call ahead of it. `auto-ship` Step 0 already enters the worktree.
 
-Suggest, as one line to the operator, that they rename their own session to the row's id, so a process listing shows what the session is for without a cross-reference to the board.
+- A second command risks a client folding two into one message, dropping the second, per `### Position zero` in `orchestrator-launch.md`
+- Suggest in one line that the operator rename their own session to the row's id, so a process listing shows what the session is for
 
 ## Stop the loop
 
-Wrapped in `/loop`, re-run the check against `## Run now` on each wake. Stop rather than firing again once the group is empty or every row in it reads `claimed: true`. Report that once, on the wake that finds it, and let the loop end rather than continuing to poll a board nobody is clearing. `orchestrator-poll.md` already carries this reasoning for the review trigger, and it binds a dispatcher the same way.
+Wrapped in `/loop`, re-run the check against `## Run now` on each wake, and stop once the group is empty or every row reads `claimed: true`. Report that once, on the wake that finds it, rather than polling a board nobody is clearing, the reasoning `orchestrator-poll.md` carries for the review trigger.

package/claude/skills/role-orchestrator/references/orchestrator-handback.md

@@ -7,34 +7,71 @@ Read this at loop step 6, once the poll reports a branch stale or conflicted, or
 
 ## Sending the handback
 
-- Read the threshold off `review-pr`, which states it once and governs the heading with it, so an open heading and an owed dispatch answer the same question and either one is enough to send
-- Resolve the target at the moment of sending with `canon sessions list --branch`, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour. `orchestrator-poll.md` routes on the count and the confidence it answers with
-- Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred rather than confirmed
+Read the threshold off `review-pr`, which states it once and governs the heading with it, so an open heading and an owed dispatch answer the same question and either one is enough to send.
+
+- Resolve the target at sending with `canon sessions list --branch`, never from an earlier mapping, since names rotate as sessions end
+- A mapping recorded earlier in a session has failed inside the hour. `orchestrator-poll.md` routes on the count and the confidence the verb answers with.
+- Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred
 - Name the skill for the reader to run rather than writing an invocation, which arrives as text
-- Read the pull request's own draft flag rather than the state a worker reports, and report what the read returned and when rather than the state alone. `canon pr head --help` states why a reported field can lag and say nothing about it. The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment, so a read taken between the pull request opening and that call sees a genuinely ready pull request about to become a draft and has told an operator the opposite of what the worker had said.
+
+### Reading the draft flag
+
+Read the pull request's own draft flag rather than the state a worker reports, and report what the read returned and when rather than the state alone. `canon pr head --help` states why a reported field can lag and say nothing about it.
+
+The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment. A read taken between the pull request opening and that call sees a ready pull request about to become a draft, and once told an operator the opposite of what the worker had said.
 
 ## The rebase handback
 
-A `STALE` or `CONFLICT` from the poll goes to the branch's own session the same way, with `review-address` as the skill to run, since its staleness test rebases a branch `main` moved under even when the merge is clean. Name what merged under the branch, being the pull request that landed and the files the poll listed, so the worker reads those hunks first rather than re-deriving them from `git log`.
+A `STALE` or `CONFLICT` from the poll goes to the branch's own session the same way, with `review-address` as the skill to run, since its staleness test rebases a branch `main` moved under even when the merge is clean.
 
-Say that a check failing after a clean rebase is a semantic conflict to fix on the branch, and that a hunk needing a decision the tree does not carry comes back as a message rather than as a guess. A pull request carrying review findings as well earns one message naming both, since one `review-address` run answers them together.
+- Name what merged under the branch, being the pull request that landed and the files the poll listed, so the worker reads those hunks first
+- Say that a check failing after a clean rebase is a semantic conflict to fix on the branch
+- Say that a hunk needing a decision the tree does not carry comes back as a message rather than as a guess
+- A pull request carrying review findings as well earns one message naming both, since one `review-address` run answers them together
 
 The worker that built the branch rebases it, not this session. It holds the plan behind each hunk, and a rebase made here would also write a branch this session does not own.
 
 ## Re-review and reachability
 
-A dispatched reviewer sends the `review-address` dispatch to the worker itself, carrying its own sessionId, and the worker sends the re-review request straight back to it. Neither leg passes through this session, which sends either one only as the fallback:
+A dispatched reviewer sends the `review-address` dispatch to the worker itself, carrying its own sessionId, and the worker sends the re-review request straight back to it. Neither leg passes through this session, which sends either one only as a fallback.
+
+### A cloud reviewer's pass
+
+A cloud session can send no message, and the script reports no code review posting on an unchanged head. The poll's cloud-reviewer rule reads `canon pr review-state` for each pull request a cloud reviewer holds and routes the dispatch here.
+
+### No worker resolved
+
+A reviewer reports that `canon sessions list --branch` returned no session or an unconfirmed match. Route it the way the poll's dispatch rule routes the count.
+
+- On zero, launch the review-address shape in `orchestrator-launch.md`, carrying the reviewer's sessionId so the new worker answers the reviewer directly
+- On an unconfirmed match, pick from a session listing and ask to be corrected, since a session may well hold the branch
+
+### No reviewer resolved
+
+A worker reports that the reviewer's sessionId resolved to no live session, or sends a re-review request with no reviewer named in its dispatch. Launch a fresh reviewer through the reviewer shape in `orchestrator-reviewer-launch.md`, never a pass in place, rather than messaging a name that no longer answers.
+
+A re-review this session sends goes to the reviewer that took the first pass. Find a live `reviewer-<project>-<number>` through `canon sessions list --json` by name and message it to re-run `review-pr`, launching a fresh one only when none is live.
+
+### When no session is live
+
+A session is reachable when it appears in a live listing, which reads what each session registered on disk rather than probing it. A message carries plain text and no authority.
+
+- When no live session holds the branch, launch the review-address shape in `orchestrator-launch.md`, which enters the branch's own worktree
+- Only where that launch cannot run, report the invocation for the human, naming the branch, the pull request, and the skill, then stop
+- Retrying or waiting leaves the loop believing it is open while nothing acts on it
 
-- A pass a cloud reviewer posted, since a cloud session can send no message. The script reports no code review posting on an unchanged head, so the poll's cloud-reviewer rule reads `canon pr review-state` for each pull request a cloud reviewer holds and routes the dispatch here.
-- A reviewer reporting that `canon sessions list --branch` returned no session or an unconfirmed match. Route it the way the poll's dispatch rule routes the count: on zero, launch the review-address shape in `orchestrator-launch.md`, carrying the reviewer's sessionId so the worker it launches answers the reviewer directly, and on an unconfirmed match, pick from a session listing and ask to be corrected, since a session may well hold the branch.
-- A worker reporting that the reviewer's sessionId resolved to no live session, or a re-review request from a worker whose dispatch named no reviewer. Launch a fresh reviewer through the reviewer shape in `orchestrator-reviewer-launch.md`, never a pass in place, rather than messaging a name that no longer answers.
+## The return leg
 
-A re-review this session sends goes to the reviewer that took the first pass. Find a live `reviewer-<project>-<number>` for that pull request through `canon sessions list --json` by name and message it to re-run `review-pr`, and launch a fresh one only when none is live.
+The channel runs both ways, and the return leg carries what the pull request cannot. A worker answering a finding by naming the plan question that already declined it changes the outcome in the moment, where a thread comment waits on its next reader.
 
-A session is reachable when it appears in a live listing, which reads what each session registered on disk rather than probing it, and a message carries plain text and no authority. When no live session holds the branch, launch the review-address shape in `orchestrator-launch.md`, which enters the branch's own worktree. Report the invocation for the human only where that launch cannot run, naming the branch, the pull request, and the skill to run, then stop. Retrying or waiting leaves the loop believing it is open while nothing acts on it.
+- Read what a worker volunteers as part of the review rather than as an aside, and read a refusal the same way
+- The corrections that landed on this session's model of the world arrived as a worker arguing back rather than complying
+- What the worker owes on its own side is stated in `role-worker`, being the announcement, the block message, and the board ban. Do not restate it here.
 
-The channel runs both ways and the return leg carries what the pull request cannot. A worker answering a posted finding by naming the plan question that had already declined it changes the outcome in the moment, where a thread comment waits on whoever reads it next. Read what a worker volunteers as part of the review rather than as an aside, and read a refusal the same way, since the corrections that landed on this session's model of the world arrived as a worker arguing back rather than complying.
+### Placing a reply
 
-What the worker owes on its own side is stated in the `role-worker` skill that session loads, being the pull-request announcement, the message a block goes out as before it becomes a prompt, and the ban on writing the board. Do not restate any of it here.
+What arrives does not become a record by being read, so place it by what it changes. Writing a tracked file to hold it is forbidden, which leaves the pull request and the board as the two surfaces this session writes.
 
-What arrives there does not become a record by being read, so place it by what it changes. An answer that settles a finding goes onto the pull request through the next pass, which withdraws or regrades that finding and names the fact behind it, per `review-pr`. An answer that changes what this session believes about the world instead, which is a mapping correction or a constraint on what a worker can do, settles no finding and reaches no thread, so route it the way `## Boundaries` in the skill body routes a change found while orchestrating, which lands it on the task owning the surface it describes. Writing a tracked file to hold either is forbidden here, which leaves the pull request and the board as the two surfaces this session writes.
+- An answer settling a finding goes onto the pull request through the next pass, which withdraws or regrades it and names the fact behind it, per `review-pr`
+- An answer changing what this session believes, such as a mapping correction or a constraint on a worker, settles no finding and reaches no thread
+- Route that second kind the way `## Boundaries` in the skill body routes a change found while orchestrating, onto the task owning the surface it describes