@sjawhar/opencode-legion-envoy 5.6.1 → 5.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "5.6.1",
+  "version": "5.6.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/AGENTS.md

@@ -6,7 +6,7 @@ event intake, process lifecycle, credentials, and role delivery.
 
 | Skill | Who reads it | What it owns |
 | --- | --- | --- |
-| `ce-simplify-code/` | the implementer, once per pull request | the behaviour-preserving simplify pass before the reviewer's final pass (Legion's copy of the MIT-licensed Compound Engineering skill; `LICENSE` beside it) |
+| `ce-simplify-code/` | the implementer, once per pull request | the behaviour-preserving simplify pass, in the implementer's first implementing round (Legion's copy of the MIT-licensed Compound Engineering skill; `LICENSE` beside it) |
 | `dispatch/` | every role, and any session writing to Dispatch | specs, asks, comments, artifacts, and messages on native Dispatch |
 | `dispatch-brainstorming/` | any session with Dispatch that starts a design conversation or writes a plan, as `dispatch-first` directs | the design conversation in the issue's spec, turn by turn to one approval, and the plan as the issue's `plan.md`; in a session with Dispatch it replaces superpowers' `brainstorming` and `writing-plans` |
 | `dispatch-first/` | every session with Dispatch configured, injected by each host plugin on every request (Oh My Pi), on every `SessionStart` (startup, resume, clear, compact, fork) and `SubagentStart` (Claude Code), or as an instruction file (OpenCode) | searching Dispatch before acting, extending the existing issue, citing decisions, closing duplicates; kept under 60 lines and 6,000 characters |

package/skills/legion-architect/SKILL.md

@@ -77,24 +77,24 @@ exercise a criterion end to end, building that path is a child issue of this tre
   answers the tree's asks); under a personal token it goes to that token's owner, whom
   `dispatch_whoami` names. Set it only when a human told you a specific person owns that child.
 
-Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](../dispatch/SKILL.md#writing-a-spec).
+Specifications written into Dispatch follow `skill://dispatch`'s "Writing a spec" section.
 Wave releases, child closures, and your own status are visible from the issue tree and the
-handoffs; do not narrate them into the spec or a `dispatch_message`. A to-do only a human can clear
-is a `dispatch_ask`.
+handoffs; do not narrate them into the spec or a `dispatch_message`. A to-do only a human can
+clear is a `dispatch_ask`.
 
 The issue's primary document **is** the root specification. Extend it in place: a new version
 that adds only the evidence each decision needs and what the human decides, each as a
-[decision block](../dispatch/SKILL.md#decision-blocks). The decomposition and its waves, how each
+decision block (`skill://dispatch`, "Decision blocks"). The decomposition and its waves, how each
 outcome is proven, and the integration test are your own calls: they go in the child issues and
 the planner's `.legion/plan.json`, not the root spec. Never post a second "spec" artifact beside
 it (`dispatch_artifact` with the primary document's name replaces the human's document; do not do
 that).
-The design gate runs only when the "Design gate policy" line at the end of your system prompt
-says `gates.design: root-issues`. When it says `gates.design: off`, write the spec and continue
-to section 2 with no approval step at all: do not request approval, do not register a gate, and
-do not wait for `design-approved`. A sub-architect on a child issue has no policy line and never
-runs the gate either: the root approval covers the tree. When the gate is armed, run this exact
-sequence **before the tree's work starts**:
+The design gate's approval step runs only when the `Design gate policy` sentence of your
+`Legion addressing` line says `gates.design: root-issues`. When it says `gates.design: off`, write
+the spec and register it with `register_gate` at its current version, with no approval step: do
+not request approval and do not wait for `design-approved`; the gate opens at registration. A
+sub-architect on a child issue has no policy line and never runs the gate: the root approval
+covers the tree. When the gate is armed, run this exact sequence **before the tree's work starts**:
 
 ```text
 dispatch_doc_edit({ issue: "<root issue>", ... })   // extend the primary document in place
@@ -112,7 +112,7 @@ legion({
 ```
 
 The decision blocks come first: settle every one as
-[Approval of a spec](../dispatch/SKILL.md#approval-of-a-spec) says before you request approval;
+"Approval of a spec" (`skill://dispatch`) says before you request approval;
 `dispatch_request_approval` refuses while one is open. Each answer reaches you, since you follow
 every ask you open. An approval request carries nothing new: request it only once the human has
 agreed to every point in the spec, so a point they have not agreed to gets its own decision block
@@ -127,8 +127,8 @@ ordinary question is not a gate and the daemon ignores its answer. Copy `artifac
 spec.md (document id <UUID>) at version <N> (ask <id>)", followed by the question the human's
 Inbox shows, and its `details.artifact` / `details.version` carry the same two values. The
 document id is never the slug or file name you passed in (`spec`, `spec.md`): the daemon
-recognizes the document's approval events by that id, and both the `legion` tool and the daemon
-refuse a value that is not a UUID. Calling `dispatch_request_approval` again while that request
+recognizes the document's approval events by that id and takes no other value; the `legion` tool
+looks a slug or file name up in Dispatch and hands the daemon the id. Calling `dispatch_request_approval` again while that request
 waits on the human, with the same `summary`, changes nothing and returns it (its text says
 it "already waits on the human"), so it is safe to repeat; a different `summary` is refused then.
 A newer version of the spec moves the open request to that version and leaves it waiting on you,
@@ -181,8 +181,9 @@ legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })
 The daemon moves each released child to `todo` and, while the root's design gate is open, starts
 its phases itself from its fixed workflow table, each phase worker as its own process with the
 child's context already in its environment; it starts no sub-architect, and you start no worker.
-Park while children are in flight. On each child closure, re-scope open work, close obsolete work
-with a reason, and release the next wave only when it now makes sense. There is no inter-child
+Park while children are in flight. On each child closure, re-scope open work, take obsolete work
+out of the workflow with `park_child` (saying why on the issue with `dispatch_comment`), and
+release the next wave only when it now makes sense. There is no inter-child
 dependency mechanism to encode.
 
 Release admits nothing. A child never takes an admission slot or becomes a root tree of its own
@@ -221,7 +222,7 @@ worker's role topic to start retro: a suspended role is not running to receive i
 
 Wait for the implementer to report its durable retro result. Retro output is
 `docs/solutions/` plus one `dispatch_message` on the issue; it must not create a `.legion`
-file or rewrite the reviewer-approved head after cleanup.
+file or rewrite the reviewer-approved head.
 
 ## 6. Architect sign-off and merge
 
@@ -235,16 +236,15 @@ The daemon keeps this order from its fixed table; you start none of its steps:
 
 1. tester green and review cycles complete;
 2. on a clean review, the reviewer approves the head by SHA, and the daemon moves the issue to
-   `retro`. Under this daemon no role pushes the `.legion/` deletion: the approved head still
-   carries `.legion/`, and the operator removes it from the default branch in a follow-up pull
-   request after the merge;
+   `retro`. No role pushes a `.legion/` deletion: the approved head still carries `.legion/`, and
+   the operator removes it from the default branch in a follow-up pull request after the merge;
 3. retro commits its learnings under `docs/solutions/` on top of the approved head; that
    commit does not void the approval and never returns the tree to the tester or reviewer;
 4. the merger verifies the current head is the reviewer-approved head plus only commits that
    change `docs/solutions/` (`jj diff --from <approved-sha> --to <tip-sha> --summary`, quoted in
-   READY) and posts `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
-   on the Dispatch issue. When its `Legion addressing` line names the project's merge queue, it
-   publishes the same packet there too. Legion never merges; a human merges under the repository's
+   READY) and sends the READY packet with its completion; the daemon posts
+   `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` on the Dispatch
+   issue and publishes it to the project's merge queue role when one is set. Legion never merges; a human merges under the repository's
    GitHub branch-protection and CODEOWNERS rules. If the merger reports a failed verification,
    treat it like `pr-blocked`: the merger holds the phase, so tell it to move the issue back with
    `request_backward_move`, naming what failed; never bypass.
@@ -268,19 +268,19 @@ never a rebase, since a rebase rewrites every descendant of the chain's fork poi
 another tree's branch stacked on it), pushes it with the ordinary push procedure (a genuine
 fast-forward), and posts the before/after fingerprints; the tester re-runs the bare gates only;
 the reviewer confirms and approves the new head by SHA (or continues its round if it had not
-approved); the daemon carries the issue on through retro to the merger, which republishes READY.
+approved); the daemon carries the issue on through retro to the merger, whose new READY packet the daemon posts.
 This merge happens only when GitHub reports `CONFLICTING`
 (`legion gh -- pr view <n> --json mergeable,mergeStateStatus`); read that on every end-game
-wake — `pr-ready`, `phase-finished`, `catchup-overseer` — because a `CONFLICTING`
+wake — `phase-finished`, `catch-up`, `checks-red`, `review-stuck` — because a `CONFLICTING`
 PR gets no CI and no wake announces it. The moment you see it, tell the worker holding the issue's
 phase (`envoy_publish` to its role topic) to move the issue back to `implementing` with
 `request_backward_move`; in `awaiting_merge`, where no worker holds a phase, open a `dispatch_ask`
-naming the conflict for the human who merges. Do not let the merger publish `READY` for an
+naming the conflict for the human who merges. Do not let the merger send a READY packet for an
 obsolete approval.
 
 If a worker reports that `legion threads resolve` exited 1 naming a review thread GitHub refused
 to resolve, open a `dispatch_ask` that names the thread's URL and GitHub's message for a human to
-resolve it by hand, with options for resolved / could not; the merger does not publish while it
+resolve it by hand, with options for resolved / could not; the merger does not complete while it
 is open. That is the one review-thread step a human takes: the review App cannot resolve a thread
 on a pull request the implementer opened, and the implementer's and merger's runs of the command
 close every accepted one.
@@ -317,19 +317,17 @@ active phase worker.
 | Wake | Procedure |
 | --- | --- |
 | `child-status` | A child of your tree left the workflow or re-entered it; the notice's reason names the child and its new status. `todo` (a human's move, your `release_children`, or your `rerun_child`) means the child runs again under your tree from planning, and the daemon starts it; you start nothing. `backlog`, `icebox` or `triage` (a human's move, or your `park_child`) means the daemon has suspended the child's workers, and it advances no further until it is set back to `todo`. What the rest of the tree does is your decision. |
-| `child-closed` | Read the child completion and remaining open children. Re-scope or close obsolete open work; release an appropriate next wave with `release_children`. When a worker waits on this child for a missing surface (see `phase-finished`), tell it to continue with `envoy_publish` to its role topic. The last child's close is not the end-game (section 3). |
-| `child-reopened` | Treat the completion edge as reset. Reassess the reopened child and return the tree to children-in-flight; do not continue an already-started end-game. |
-| `design-approved` | Payload `{type:"design-approved"}`. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
-| `design-changes-requested` | Payload `{type:"design-changes-requested", version, reason, author?}`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec as the reason asks and request approval again as section 1 says; stay parked; the gate is closed. |
+| `child-closed` | Read the child completion and remaining open children. Re-scope open work, park obsolete work with `park_child`, and release an appropriate next wave with `release_children`. When a worker waits on this child for a missing surface (see `phase-finished`), tell it to continue with `envoy_publish` to its role topic. The last child's close is not the end-game (section 3). |
+| `design-approved` | Its `version` is the approved one. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
+| `design-changes-requested` | Its `version` and `reason`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec as the reason asks and request approval again as section 1 says; stay parked; the gate is closed. |
 | `phase-finished` | The daemon has already moved the issue to its next phase by its fixed table and started that phase's role; you start nothing. Read the committed handoff for the finishing phase; if it shows unresolved gaps, tell the role now working the issue (`envoy_publish` to its role topic). A `planner` notice that names a departure from the spec's design defers to section 1's full condition: when the approved Summary, Acceptance, scope and settled decisions still hold, the plan is the record; otherwise change the root spec and request approval again as section 1 says. A `reviewer` notice whose GitHub review is `CHANGES_REQUESTED` needs nothing from you: the daemon has returned the issue to `implementing` (Dispatch `in_progress`) and started the **implementer**, whose correction goes through the tester and the reviewer again, never straight to retro. A `reviewer` notice with an `APPROVED` review means the daemon has started retro (step 5). An `implementer` notice for `production_check` is its production report: read the record on the pull request and the issue, then run step 7. A `tester` notice with `verdict: "fail"` — its handoff carries `implementerProof.verdict: "rejected"`, or a failure naming the production-like proof — has gone back to the **implementer** by the daemon's table; never supply the proof from another role. A worker that reports no surface reaches the changed path sends that report instead of completing its phase, so the daemon starts nothing more on that issue and the worker stays idle in its session, not suspended: file a child issue in this tree to build the surface (infrastructure, tooling, or a skill), and when that child's `child-closed` arrives, tell the waiting worker to continue with `envoy_publish` to its role topic. That report is never a reason to advance the phase. |
-| `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/merger order only for that current head. |
-| `pr-blocked` | Payload `{type:"pr-blocked", pr, attempts}`. `attempts` counts heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. The notice moves nothing: the issue stays in its phase, and only the worker holding that phase is running; an earlier phase's worker is suspended. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch_ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. |
-| `pr-merged` | Payload `{kind:"pr-merged", reason}`. The PR merged, under the repository's rules, before the issue reached `awaiting_merge`. The workflow runs on and asks no one to merge it: the daemon starts the **implementer** on the production check once the issue gets there, and you start nothing. Its `phase-finished` for `production_check` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it with `sign_off`. A merge is not the close. |
+| `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached. The count is of heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. The notice moves nothing: the issue stays in its phase, and only the worker holding that phase is running; an earlier phase's worker is suspended. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch_ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. |
+| `pr-merged` | Its `reason` names the pull request. The PR merged, under the repository's rules, before the issue reached `awaiting_merge`. The workflow runs on and asks no one to merge it: the daemon starts the **implementer** on the production check once the issue gets there, and you start nothing. Its `phase-finished` for `production_check` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it with `sign_off`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (`park_child` then `rerun_child`, for a child), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
-| `issue-comment` | Interpret the comment in the issue's design context. Reply in its thread (`dispatch_comment` with `reply_to`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `reply_to_ask` with `turn: "agent"`, since a default-turn reply hands that request back to the human and a corrected `summary` is then refused), then adjust the plan or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
-| `catchup-overseer` | Verify its child counts and PR verdicts against current artifacts, then resume the applicable lifecycle step. This is a current-state snapshot, not a raw-event replay. A root architect uses `gates[LEGION_TREE].open`: `true` means the root spec is approved and section 2 may continue; `false`, or no `open` key, means section 1 still applies. A resumed sub-architect receives `overseerCatchup(state, LEGION_ISSUE)` for its own subtree: its `gates` intentionally omits the root gate because a child spec is never gated. Do not request or register a gate; resume at section 2. Handle each `phaseCompletions` entry exactly as a `phase-finished` wake, then compare `childCounts[LEGION_ISSUE].open` with `legion state` and Dispatch before deciding the next action. |
-| `worker-died` | Payload `{kind:"worker-died", role, phase}`. That role's claim failed: its launches or prompts ran out. For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. |
-| `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |
+| A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch_comment` with `reply_to`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `reply_to_ask` with `turn: "agent"`, since a default-turn reply hands that request back to the human and a corrected `summary` is then refused), then adjust the plan or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
+| `worker-died` | Its `role` and `phase`. That role's claim failed: its launches or prompts ran out. For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. |
+| `held` | Its `role` and `phase` (the phase the issue left), or `phase` with `reason: "escalated"`. Without `reason`, that phase's worker ran out of launches or prompts: the issue is held (phase `held`), the `worker-died` that comes with it is yours to answer with `retry_or_escalate` as that row says, and the controller hears of the hold too. With `reason: "escalated"`, it records your own `escalate`: the controller has the issue now, and you start nothing for it. |
+| `ready-refused` | Its `version` and `reason`. The merger's READY was refused. A `reason` of `READY refused: approve design version <N> before requesting READY.` (or, with `version` 0, `no design version is approved`) means the design gate is closed: get that version approved (section 1), and the daemon advances the merge and posts the packet the merger sent once it is; nothing else is needed. A `reason` starting `READY_PACKET_MISSING` names a READY refused before the daemon kept packets: that READY is void and the issue stays in merging, so start it over (`park_child` then `rerun_child`, for a child) or end it. |
 
 ## Escalation judgment
 

package/skills/legion-controller/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: legion-controller
-description: Use when handling Legion controller wakes for root-issue triage, keeping the admission slots full from `todo` issues, the daily report, architect escalation, resync healing, or human interaction.
+description: Use when handling Legion controller wakes for root-issue triage, keeping the admission slots full from `todo` issues, the daily report, architect escalation, or human interaction.
 ---
 
 # Legion Controller
@@ -12,73 +12,63 @@ architect.
 
 ## Start and claim the controller role
 
-The Legion extension claims `legion-<project>-controller` and registers controller readiness
-with the daemon during session startup. Do not handle a wake unless that startup succeeded.
+The Legion extension registers this session with the daemon as the controller and claims
+`legion-<project>-controller` during session startup. Do not handle a wake unless that startup
+succeeded.
 
-The daemon runs the controller as an interactive OMP terminal session in its private tmux
-server (the pane runs plain `omp`, not `--mode rpc`, and no `legion worker-shim`; the operator reaches
-it with `tmux -L legion-<project> select-window -t <window id> \; attach -t legion-<project>`,
-the window id being `controllerLocator.tmuxWindowId` in `legion state --json` — every window
-opens detached, so a bare `attach` lands on whichever window is current). The operator may attach and
-type into this session at any time. The pane carries no GitHub credential: its GitHub token
-variables are emptied, and both `legion gh -- <args>` and `legion threads resolve` are refused.
-The controller reads Dispatch and applies its controller capability with `legion status <KEY>
-<status>`; it never reads GitHub or merges a pull request.
+The session carries no GitHub credential: its GitHub token variables are emptied, and both
+`legion gh -- <args>` and `legion threads resolve` are refused. The controller reads Dispatch and
+applies its controller capability with `legion status <KEY> <status>`; it never reads GitHub or
+merges a pull request.
 
 For an interactive takeover from a hand-started OMP session, start OMP with
 `LEGION_CONTROLLER_SECRET` (or `LEGION_CONTROLLER_SECRET_FILE`, a path to a file holding it),
-`LEGION_DAEMON_URL`, `LEGION_STATE_DIR` (the daemon's state directory), and `LEGION_GRANT_FILE`
+`LEGION_DAEMON_URL`, `LEGION_PROJECT` (the daemon's project), `LEGION_STATE_DIR`, and `LEGION_GRANT_FILE`
 (an absolute path to a file only you can read, under a 0700 directory; the extension writes
 each command's grant there and every `bash` call is blocked without it) in its environment. Do
-not set `LEGION_CONTROLLER=1` — that marker is the daemon pane's own, and a session carrying it
-claims at startup and reports its transcript as the pane's. Then run:
+not set `LEGION_CONTROLLER=1` — that marker is `legion controller start`'s own, and a session
+carrying it claims at startup. Then run:
 
 ```text
 /legion-claim-controller
 ```
 
-The command resolves the project from daemon state, claims the Envoy role for the current
-session, and posts readiness before controller commands can act. From then on this session's
+The command checks that `LEGION_PROJECT` is the daemon's project, registers this session with the
+daemon, and claims the Envoy role for it before controller commands can act. From then on this session's
 shell commands are wrapped with a controller grant, but the grant holds no GitHub credential;
 `legion status <KEY> <status>` works through the controller secret in this session's environment
 (`LEGION_CONTROLLER_SECRET` or its `_FILE`), not the grant — if it fails, that is the variable to check.
-The takeover moves the role
-and the daemon's recorded session id to this session; it never replaces the transcript the
-daemon recorded for its own pane, so a later respawn of that pane resumes the pane's own
-conversation, not yours. Never pass a secret as a command argument or copy it into a transcript.
-The claim is kept alive automatically afterwards: the Envoy registration heartbeat re-asserts it
-and re-posts readiness whenever the listener loses sight of this session, so
-`/legion-claim-controller` is the manual override, not a routine step after a listener restart.
-
-Two limits of a takeover session. It caches the controller secret it started with: after the
-daemon respawns its own pane the secret rotates, every `bash` call in the takeover session then
-fails with a 403 from the grant mint, and the fix is to start a fresh OMP with the new secret,
-not to retry. And the role does not follow `/new` or `/fork` in a takeover session — without
+The takeover moves the role and the daemon's recorded session id to this session. Never pass a
+secret as a command argument or copy it into a transcript. The Envoy registration heartbeat keeps
+the role afterwards, so `/legion-claim-controller` is the manual override, not a routine step after
+a listener restart.
+
+Two limits of a takeover session. It caches the controller secret it started with: the next
+`legion controller start` mints a new secret, every `bash` call in the takeover session then fails
+with a 403 from the grant mint, and the fix is to start a fresh OMP with the new secret, not to
+retry. And the role does not follow `/new` or `/fork` in a takeover session — without
 `LEGION_CONTROLLER=1` the new session is not a Legion session to the extension — so after either
 command run `/legion-claim-controller` again.
 
-This handshake lets the daemon redeliver held controller work. It does not turn the controller
-into a state holder: daemon state and the Dispatch project remain authoritative.
+The daemon holds nothing for a controller: daemon state and the Dispatch project remain
+authoritative, and the start procedure below reads what happened while no controller ran.
 
 ### Started by the operator
 
-When the daemon cannot open a terminal for you — the Go daemon, under either runtime, since it
-launches no controller — nobody launched your
-pane: the operator ran `legion controller start --config controller.yaml [--daemon-url <url>]` on
+The daemon launches no controller, under either runtime: the operator ran
+`legion controller start --config controller.yaml [--daemon-url <url>]` on
 their own machine, and you are that foreground OMP session. The command fetched a fresh controller
 secret from the daemon with the operator's token, wrote it to a 0600 file under `LEGION_STATE_DIR`
 (`~/.local/state/legion/<project>-controller` by default) beside the `gh` shim and the `legion`
-launcher, and started you with `LEGION_CONTROLLER=1` and the same environment a tmux controller pane
-carries, so nothing changes in how you handle wakes. The extension registers on
-`/legion/v1/claims/register` with the
+launcher, and started you with `LEGION_CONTROLLER=1` and the controller's environment. The
+extension registers on `/legion/v1/claims/register` with the
 secret, claims the role, then subscribes to `notifications.legion.<project>.controller`, where the
-Go daemon publishes the rows marked from the Go daemon in the wake routing table. The daemon records
+daemon publishes the rows marked from the Go daemon in the wake routing table. The daemon records
 you as `controllerLocator: {runtime, external: true, sessionId, registeredAt}`, `runtime` being the
-daemon's own (`kubernetes`, or `tmux` under the Go daemon). The TypeScript daemon reads your
-liveness from the Envoy role registry (the holder of
-`legion-<project>-controller` and its `last_seen`), not from a pane: keep the session running.
+daemon's own (`kubernetes` or `tmux`). The daemon reads your liveness from the Envoy role registry
+(the holder of `legion-<project>-controller` and its `last_seen`): keep the session running.
 Exiting it leaves the project without a controller until the operator runs the command again —
-the TypeScript daemon logs `controller not registered; run legion controller start` once per
+the daemon logs `controller not registered; run legion controller start` once per
 boot-timeout interval and launches nothing itself. `legion state` and `legion status <KEY>
 <status>` work here over `LEGION_DAEMON_URL`. A second `legion controller start` replaces you: it
 mints a new secret, so your grants stop working and the role moves to the new session.
@@ -214,7 +204,7 @@ leans on `External links:`, and the label row is the one that never depends on h
 | It has any child | `dispatch_read({ ref: "dispatch://<KEY>/children" })` lists any child, open or `done`. It is an umbrella, and a finished umbrella is still no leaf. That also skips an issue whose only child is done, which is accepted. Its open children are candidates themselves, each in its own place in the order. |
 | An ancestor is Legion's | Follow `Links:` up through each `child_of` parent, reading each one, and skip when any ancestor carries the `legion` label or is recorded under `issues` in `legion state --json`, whatever its status: a Legion tree, running or parked, owns its children. An ancestor's claim or route does not skip the issue: a coordinator holding an umbrella files `todo` leaves for others to pick up, and the claim on the issue itself is what keeps two sessions off the same work. A `child_of` under `Referenced by:` is a child of this issue, not its parent. |
 | Someone is designing it | `Open asks:` lists any ask, a `Spec approval: awaiting …` line shows the spec waits on a human, or `Events:` show an `artifact.version` or an `ask.opened` from the last seven days: a session or a person is shaping it even when nobody claims or routes it. |
-| Legion ran it without the label now on it | `legion state --json` records it under `issues`, whatever its status, or `Events:` show a status write by `session legion-daemon:<PROJECT>`, the daemon's actor on every `legion status` (yours included) and on its own `in_progress` at admission. That covers a root a person took the label off, and one that ran before the daemon required the label and never had it. Name each one you skip for this in your summary. The walk never sends a root Legion already ran back into Legion: a person does that with the label and `todo`, and you do it only when a wake below says to (`worker-died`, closed-tree activity). |
+| Legion ran it without the label now on it | `legion state --json` records it under `issues`, whatever its status, or `Events:` show a status write by `session legion-daemon:<PROJECT>`, the daemon's actor on every `legion status` (yours included) and on its own `in_progress` at admission. That covers a root a person took the label off, and one that ran before the daemon required the label and never had it. Name each one you skip for this in your summary. The walk never sends a root Legion already ran back into Legion: a person does that with the label and `todo`, and you do it only when a wake below says to (`worker-died`). |
 | A running session or a person claims it | `Claimed by:` names anyone and does not end `· not running`. `· liveness unknown` counts as claimed: the agent registry could not be read, so nothing says the holder stopped. A claim ending `· not running` has lapsed, and the issue is free. |
 | Its route reaches a running session | `Route:` names a route with nothing after it, or with `(held by …)`. `(nobody holds it right now)` and `(that session is not running right now)` reach nobody; `(the Envoy listener did not answer, …)` counts as reaching someone. `Route: none` is free. |
 | A pull request is linked or named | `External links:` lists a pull request (kind `github_pr`, or a URL ending `/pull/<n>`), or a comment or message among `Events:` names one. You cannot read GitHub, so an open, merged, or closed pull request all count. A person who wants Legion on it anyway hands it over themselves: the label, then `todo`. |
@@ -302,7 +292,7 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
   it before handling every other wake.
 - **One wake = one turn.** Handle exactly the wake's implication, then end the turn. Never
   poll, idle-loop, or wait for another event. Two additions, after any direct user message: every
-  turn under the Go daemon first rechecks the [trees waiting on a root
+  turn first rechecks the [trees waiting on a root
   claim](#trees-waiting-on-a-root-claim-go-daemon), and your first turn of each UTC day, whatever
   woke you, also posts the day's report ([Daily report](#daily-report-go-daemon)).
 - **Wakes are advisory.** Before any side effect, verify the current daemon state and the
@@ -318,21 +308,14 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 
 | Wake | Content | Controller action |
 |---|---|---|
-| New issue created in the Dispatch project (`issue.created`, status `triage`; under the TypeScript daemon resync heals misses, under the Go daemon the boot step above does). From the Go daemon: `triage on <KEY>` (payload `{kind: "triage"}`) on the controller topic, for an unrecorded root carrying the `legion` label only ("Issues handed to Legion" above) | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
-| Backlog eligibility (TypeScript daemon) | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
+| New issue created in the Dispatch project, status `triage`: `triage on <KEY>` (payload `{kind: "triage"}`) on the controller topic, for an unrecorded root carrying the `legion` label only ("Issues handed to Legion" above); the start procedure above catches one sent while no controller ran | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
 | `slot-free on <KEY>` from the Go daemon (payload `{kind: "slot-free"}`) | the root whose slot the daemon released with no waiting root to take it | Verify a free slot in `legion state --json`, then fill it ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | `todo on <KEY>` from the Go daemon (payload `{kind: "todo"}`) | an issue not handed to Legion that changed while in `todo` and a slot stood free, sent half a minute later | Verify a free slot, then walk the whole `todo` list ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | `tick on <PROJECT>` from the Go daemon (payload `{kind: "tick"}`) | the project key; the daemon's periodic wake, whatever the slots | Recheck the trees waiting on a claim, then walk if a slot is free; post the day's report if this is the day's first turn |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; the owning architect writes an issue-design decision as a decision block and opens `dispatch_ask` only for a human to-do |
-| Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed, admission-drift) | Verify against fresh state, then heal |
-| Resync report: `admission-drift` entry | issue key + whether the daemon added it to, or removed it from, its admission list (the detail says which) | No action: the daemon already repaired it in the same run. An issue that reappears in consecutive reports is a live leak — file a LEGION issue on Dispatch with both reports pasted as evidence (never a GitHub issue) |
-| `child-status` | child key + status transition | Not controller-actionable by default; if the daemon could not route it to the parent's architect role, verify the transition and forward it with `envoy_publish` |
 | Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
-| READY packet seen on a Dispatch issue (via issue subscription) | READY line + gate facts | No action: a human merges; the merger has already notified the queue role if the project has one |
-| `worker-recovered` (role `architect`) from the daemon | issue, fromRef | A root architect's tree volume was lost; it restarted as a new session. Verify the tree is active in `legion state` and that the architect posts its next step on the issue within one resync interval; otherwise treat it as an anomaly. |
 | `held on <KEY>` from the Go daemon (payload `{kind: "held", phase, role?, reason?}`) | the held issue, the phase it left, and the role whose claim failed, or `reason: "escalated"` | Verify the hold in `legion state` (the issue's phase is `held`). Without `reason`, a phase worker's launches or prompts ran out and the tree's architect decides retry or escalate: no action. With `reason: "escalated"` (on the record, `issues.<KEY>.holdReason` is `escalated`), the architect sent it to you: handle it as an architect escalation below. Parking the tree is `legion status <root> backlog`; setting the root back to `todo` later re-admits it as a new generation, which starts again from its architect |
 | `worker-died on <KEY>` from the Go daemon with `role: "architect"` | the tree root whose architect's claim failed, and the phase the root was in | The tree's architect ran out of launches or prompts and the daemon relaunches nothing; every other notice of the tree goes to that architect, so nobody inside the tree can act. Verify in `legion state` (`issues.<KEY>.architect.state` is `failed`); if the root's phase is `done`, the tree is already parked: no action. Otherwise re-admit the tree (`legion status <root> backlog`, then `todo`: a new generation, whose architect starts again with fresh budgets) or leave it parked and say why on the issue |
-| Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion status <root> todo`; otherwise no action — the event is not held or redelivered |
 | Direct user message | — | Always first |
 
 ## New issue triage
@@ -357,8 +340,8 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
    ```
 
    (or `icebox` for longer-term deferral). Dispatch status is the durable record; there is no
-   other marker to maintain, beyond the Go daemon's `legion` label, which parking leaves in
-   place. Under the Go daemon a root never waits for capacity in `backlog`: in `todo` the
+   other marker to maintain, beyond the `legion` label, which parking leaves in
+   place. A root never waits for capacity in `backlog`: in `todo` the
    daemon's admission queue holds it (`admission.waiting`), so park only a root that should not
    run now. Do not triage a system-created child as a root issue.
 4. When you post a triage note (a `dispatch_comment` on the issue saying what you decided and
@@ -374,18 +357,13 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 
 ## Backlog eligibility
 
-Under the Go daemon nothing reconsiders `backlog` or `icebox` on its own: [Keeping the slots
+Nothing reconsiders `backlog` or `icebox` on its own: [Keeping the slots
 full](#keeping-the-slots-full-go-daemon) takes only `todo` issues, since an issue that waits on a
 deploy or a decision belongs in `backlog` (`skill://dispatch`, "Choosing what to work on"). A
 handed-over root waits for a slot in `todo`, where the daemon's
 admission queue holds it (`admission.waiting`), so a park means "should not run now", and a
 parked root keeps its `legion` label. A parked issue runs again when a person sets it to `todo`,
-or when a wake tells you to re-admit it (`worker-died`, closed-tree activity).
-
-Under the TypeScript daemon, when a slot frees or priority changes, use `legion state --json` and
-the current Dispatch issue to reconsider parked roots. Admit the selected root with
-`legion status <KEY> todo`. Moving an item to or from `backlog`/`icebox` is a deliberate
-controller decision, not a no-op.
+or when a wake tells you to re-admit it (`worker-died`).
 
 ## Architect escalation
 
@@ -397,7 +375,7 @@ For an independence judgment, verify the child and its parent against current da
 and the Dispatch issue. If the work belongs in an independent root:
 
 1. File a **fresh root issue** with `dispatch_issue({ project, title, spec })` (no `parent`;
-   under the Go daemon add `labels: ["legion"]`, without which it is never admitted).
+   add `labels: ["legion"]`, without which it is never admitted).
    `project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`): the
    project key exactly as `legion.yaml` writes it, which `legion state --json` shows as
    `daemon.project`. It is not the lowercase project token in role names such as
@@ -411,17 +389,6 @@ Never promote a child in place. Resolve capacity and cross-tree conflicts from v
 state, routing design decisions back to the owning architect when they are not controller
 judgments.
 
-## Resync report
-
-Treat a resync report as an anomaly list, not an instruction. For every zero-owner tree,
-untriaged-open, or launch-failed issue it names, verify `legion state --json` and the
-current Dispatch issue first. Then heal the verified condition: admit an eligible root, move
-an issue back to its intended status, or use the applicable daemon control path. Do not act
-on stale entries until their source artifact explains the anomaly. An `admission-drift` entry
-needs no healing — the daemon added the tree back to (or removed it from) its admission list in
-the same run; verify only that the same issue does not recur in the next report, and file a
-LEGION issue with both reports if it does.
-
 ## Mentions
 
 Read the mention and its artifact. Answer it when it asks the controller for triage or

package/skills/legion-retro/SKILL.md

@@ -5,9 +5,9 @@ description: Use when an issue has passed review and its parked implementer is r
 
 # Legion Retro
 
-Retro is mandatory for every issue that passed review. The architect revives the parked
-implementer so the person with implementation context performs the retrospective, and the
-skill obtains a separate fresh-eyes perspective. Retro runs before merge.
+Retro is mandatory for every issue that passed review. The daemon starts the implementer on it
+once the reviewer approves, so the person with implementation context performs the retrospective,
+and the skill obtains a separate fresh-eyes perspective. Retro runs before merge.
 
 Every path this skill cites (`packages/...`, `docs/...`) is in sjawhar/legion, the Legion
 repository, which need not be the repository you are working in.
@@ -18,16 +18,17 @@ Follow this ordering exactly. It keeps the reviewed branch clean while preservin
 retrospective's durable output.
 
 1. Tester green and all code-review cycles finish.
-2. The implementer pushes the `.legion/` deletion at the reviewer's direction, and the reviewer
-   approves that head.
+2. The reviewer approves the head. It still carries `.legion/`: no role removes it before the
+   merge, and the operator removes it from the default branch after the merge.
 3. Run this retro: commit durable learnings to `docs/solutions/` and post the retro message on
    the Dispatch issue.
-   Retro writes **no `.legion` file**, so it never re-dirties the cleaned handoff tree.
+   Retro writes **no `.legion` file**, so it never changes the approved head's handoffs.
 4. The merger verifies the tip is the approved head plus commits that change only
    `docs/solutions/` — `jj diff --from <approved-sha> --to <tip-sha> --summary`, quoted in READY —
-   posts `READY` on the Dispatch issue, and publishes the same packet to the project's merge-queue
-   role when configured. A human merges under the repository's GitHub branch-protection and
-   CODEOWNERS requirements; GitHub's merge queue participates only when the repository enables it.
+   and sends the READY packet with its completion; the daemon posts it on the Dispatch issue and
+   publishes it to the project's merge-queue role when one is configured. A human merges under the
+   repository's GitHub branch-protection and CODEOWNERS requirements; GitHub's merge queue
+   participates only when the repository enables it.
 5. After that merge, the implementer — not the reviewer or merger — verifies the change in production
    and records it on the PR and the issue: the agent that developed it is responsible for testing
    in production. The architect's sign-off waits for that record.
@@ -41,14 +42,14 @@ changes only `docs/solutions/` does not void it, and the tree goes from retro to
 never back to the tester or reviewer. A conflict-forced rebase after retro moves these documents
 with the branch; retro does not re-run.
 
-Do not start retro before step 2, skip it because the change seems mechanical, or publish `READY`
-before step 3. The design gate is not a substitute for review and retro.
+Do not start retro before step 2 or skip it because the change seems mechanical; the merger's
+`READY` comes only after step 3. The design gate is not a substitute for review and retro.
 
 ## Two perspectives
 
 1. Re-read the issue, its acceptance criteria, the PR, test evidence, and review evidence.
    Confirm the PR carries both proofs: the implementer's own `E2E (implementer)` line and the tester's `E2E (tester)` line,
-   each naming a production-like surface (the daemon's test harness (`packages/daemon/src/daemon/__tests__/`) and real-process fixtures; a live check at the operator's next daemon restart, recorded on the PR; a sandbox repository, a devN
+   each naming a production-like surface (the daemon's real-process tests and the live proofs under `scripts/e2e/`; a live check at the operator's next daemon restart, recorded on the PR; a sandbox repository, a devN
    stack, staging, or a local stack with real migrations), a command or run id, an observation, a head
    SHA, and a negative control. If either is missing, or links only a unit suite, the retro's first
    durable learning is that gap and the issue goes back — to the implementer for its own proof, to the
@@ -87,8 +88,8 @@ related_issues:
 ---
 ```
 
-Commit the documentation on the existing issue branch, advance its existing bookmark, and push
-that branch. Do not create a replacement branch or bookmark. Then post one Dispatch message on
+Commit the documentation on the existing issue branch and push it with `legion push`. Do not
+create a replacement branch or bookmark. Then post one Dispatch message on
 the issue — `issue` is your `LEGION_ISSUE`; Legion issues live on Dispatch, never on a GitHub
 issue, and the `gh` shim refuses every GitHub-issue write — naming the documents, the
 one-to-three most useful takeaways, the two proofs you read, and the production check that
@@ -115,16 +116,16 @@ dispatch_message({
 ```
 
 The Dispatch message and the `docs/solutions/` commit are the only retro outputs. Never write a
-handoff, phase artifact, local feedback log, or completion label; `.legion/` was deleted before
-retro and nothing recreates it. Report completion with the `legion` tool's `handoff_complete` alone (its
+handoff, phase artifact, local feedback log, or completion label, and add or change nothing under
+`.legion/`. Report completion with the `legion` tool's `handoff_complete` alone (its
 summary: two sentences for the architect) — no `handoff_write`.
 
 ## Completion check
 
 Before returning, verify all of the following:
 
-- The reviewer cleanup commit remains below the retro documentation commit, and the reviewer's
-  approval of that cleanup head stands: the merger accepts the approved head plus this commit.
+- The reviewer-approved head remains below the retro documentation commit, and the reviewer's
+  approval of that head stands: the merger accepts the approved head plus this commit.
 - The learning documents and the Dispatch message both exist (never a GitHub issue comment).
 - Both proofs were read, and any gap in either is recorded as a learning.
 - No `.legion` file was created or modified by retro.

package/skills/legion-worker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: legion-worker
-description: Use when dispatched as a per-process Legion phase worker — architect (on a child issue), planner, implementer, tester, reviewer, or merger — booted from the daemon's LEGION_* environment.
+description: Use when dispatched as a per-process Legion phase worker — planner, implementer, tester, reviewer, or merger — booted from the daemon's LEGION_* environment.
 ---
 
 # Legion Phase Worker
@@ -24,26 +24,26 @@ with the `read` tool: a read by filesystem path stops at 300 lines.
 | You write or edit the PR body, record a proof (an `E2E` line or a handoff `proof` array), verify another phase's proof, or run the simplify pass | `skill://legion-worker/references/pr-body.md` |
 | You reply to, accept, or resolve a review thread, or run `legion threads resolve` | `skill://legion-worker/references/review-threads.md` |
 | GitHub reports a conflict, the pull request is retargeted, you compare heads after a conflict merge, or you would rewrite a pushed commit | `skill://legion-worker/references/conflicts-and-rewrites.md` |
-| You review or approve, push the `.legion/` deletion, publish READY, or check the merge in production | `skill://legion-worker/references/merge-gate.md` |
+| You review or approve, build the READY packet, or check the merge in production | `skill://legion-worker/references/merge-gate.md` |
 | The issue renames a repository, package, or URL across the codebase | `skill://legion-worker/references/systematic-rename.md` |
 | The issue deletes code, a command, or documentation | `skill://legion-worker/references/cleanup-deletion.md` |
 
 ## Identity, scope, and role
 
 The daemon spawns you as a separate `omp --mode rpc` process (behind `legion worker-shim`,
-in a tmux pane) with `LEGION_TREE`, `LEGION_ISSUE`, `LEGION_ROLE`, `LEGION_GENERATION`,
-`LEGION_BOOT_TOKEN_FILE` (a 0600 file under `$LEGION_STATE_DIR/secrets` holding your boot token;
-the extension reads it for you), `LEGION_DAEMON_URL`, `LEGION_STATE_DIR`, and `LEGION_WORKSPACE`
-in your environment (`LEGION_PROJECT` is also supplied, but nothing reads it). The extension
+in a tmux pane or an Agent Sandbox pod) with `LEGION_TREE`, `LEGION_ISSUE`, `LEGION_ROLE`,
+`LEGION_GENERATION`, `LEGION_PROJECT`, `LEGION_BOOT_TOKEN_FILE` (the file holding your boot
+token; the extension reads it for you), `LEGION_DAEMON_URL`, `LEGION_STATE_DIR`, and
+`LEGION_WORKSPACE` in your environment. The extension
 completes the boot handshake for you at session start — it registers with the daemon, claims
 your role, and signals readiness. You never call `envoy_role_set` yourself.
 
 Your role token is not the issue key spelled out literally. The daemon encodes it as
 `legion-<project>-<key>-<role>` with the issue key lower-cased. For example, project `acme`, issue
 `LEGION-41`, role `architect` encodes to `legion-acme-legion-41-architect`. Never hand-format one for another role: your own role
-topic and the topic of the architect that owns your issue are stated at the end of your system
-prompt (a "Legion addressing" line the daemon appends: on a child issue that is the child's
-sub-architect when one is claimed, else the root's), a sibling role's topic is yours with the
+topic and the topic of the architect that owns your issue are in the `Legion addressing` line of
+your system prompt (the daemon appends it; it names the tree root's architect, also on a child
+issue), a sibling role's topic is yours with the
 trailing `-<role>` replaced, and the `roleToken` helper in `@legion/contracts` computes any other
 one exactly the way the daemon does — prefer a topic you've already been given before recomputing
 one.
@@ -166,7 +166,7 @@ other tree paused.
 
 ## Phase work
 
-Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](../dispatch/SKILL.md#writing-a-spec), except that a phase worker writes no decision block: it sends an open product, scope or design decision to its architect, which writes the block.
+Specifications written into Dispatch follow `skill://dispatch`'s "Writing a spec" section, except that a phase worker writes no decision block: it sends an open product, scope or design decision to its architect, which writes the block.
 
 Follow the repository's normal engineering workflow and the assigned issue's acceptance
 criteria. Your phase's own charter and the predecessor handoffs you read define the phase
@@ -214,7 +214,7 @@ legion gh -- <gh args…>
 ```
 
 Four facts about `gh` in a worker pane. The `gh` on your `PATH` is a shim
-(`<state_dir>/worker-bin/gh`, installed by the daemon at startup — `packages/daemon/src/daemon/worker-bin.ts`)
+(`<state_dir>/worker-bin/gh`, installed by the daemon at startup — `packages/daemon/internal/runtime/workerbin/workerbin.go`)
 that execs `legion gh -- "$@"`, so `gh …` and `legion gh -- …` are the same call, and each call
 redeems a fresh token from your session's grant — identity is supplied per call, never stored.
 Never run `gh auth login` or `gh auth setup-git`; there is no login state to create. The shim
@@ -282,8 +282,8 @@ pushes the issue branch under this exact name with the one push procedure every
 (*Every role pushes its own commits*, below).
 
 The provisioned issue workspace configures `credential.helper` with the daemon's absolute
-credential command, so `jj -R "$LEGION_WORKSPACE" git push` authenticates transparently
-through the same session capability. Never handle a token.
+credential command, so `legion push` authenticates transparently through the same session
+capability. Never handle a token.
 
 Then open the pull request with `legion gh -- pr create`. The PR body **must** contain the
 line `Dispatch: <KEY>` — the daemon's fallback link from a PR to its Dispatch issue when the
@@ -314,9 +314,9 @@ line), the full definition of a proof, what the tester verifies, and the simplif
 - **A conflict or a retarget** is the only reason to bring the base into the branch, always as a
   forward merge and never `jj rebase`; the unchanged-diff fingerprint each role compares
   afterwards is in the same reference: `skill://legion-worker/references/conflicts-and-rewrites.md`.
-- **The merge gate**, in order: the tester's evidence green → the implementer's `.legion/`
-  deletion push → the reviewer's approval of that head → retro → the merger's READY → the human
-  merge → the implementer's production check. Legion never merges. The reviewer's submissions,
+- **The merge gate**, in order: the tester's evidence green → the reviewer's approval of the head
+  → retro → the merger's READY → the human merge → the implementer's production check. Legion
+  never merges. The reviewer's submissions,
   retro's commit, the merger's READY, and the production check follow
   `skill://legion-worker/references/merge-gate.md`.
 - **No surface reaches the changed path** is a report to the architect, never a reason to
@@ -359,58 +359,25 @@ cd -- "$LEGION_WORKSPACE" && \
 ```
 
 **Every role pushes its own commits.** After the handoff commit — and, for the tester, the red
-tests it wrote — advance the issue bookmark and push it with the provisioned credential helper,
-which authenticates as your role's App (`appRoleForLegionRole` in
-`packages/daemon/src/daemon/github-apps.ts`).
-
-**Under the Go daemon, every push is `legion push`,** run from bash in your workspace in place of
-the commands below. It runs this same procedure on `@-`: the ancestry check, against the remote
-branch or the tip you recorded before rewriting pushed commits (below), then the bookmark and the
-push. It also decides whether the push skips CI. A push skips CI only when none of its commits
-touches anything but handoffs whose phase guarantees a later push: the planner's
-`.legion/plan.json`, the tester's `.legion/test.json`, and a reviewer's `.legion/review.json` whose
-`verdict` is `"changes_requested"`. Its head then ends with GitHub's `skip-checks: true` trailer,
-and the Go daemon carries the code head's verdict to it. Every other push runs CI in full. Never
-add or remove that trailer yourself, never write one of GitHub's bracket keywords (`[skip ci]`,
-`[ci skip]`, `[no ci]`, `[skip actions]`, `[actions skip]`) into a commit message, and never push
-the issue branch with the commands below under the Go daemon: a hand-run push of a handoff that
-could skip CI runs it in full, and a hand-added trailer or keyword on any other push skips CI on a
-head a human may merge. `legion push` refuses a head whose message carries a keyword and pushes
-nothing until you take it out. Under the TypeScript daemon, whose `legion` has no `push` command,
-run the commands below yourself.
-
-`-r @-` puts the bookmark on the commit you just
-split off: the working copy left above it has no description, and `jj git push` refuses a
-commit without one. `--allow-backwards` is for that local step alone: after a split the bookmark
-can sit on the undescribed working copy above `@-`. `--bookmark` also publishes the locally
-provisioned bookmark on its first push — a bookmark not yet tracking a remote one is tracked
-automatically. This is the one push procedure, run as `legion push` under the Go daemon and by
-hand under the TypeScript daemon; every push of the issue branch uses it:
+tests it wrote — push the issue branch with `legion push`, run from bash in your workspace:
 
 ```bash
-cd -- "$LEGION_WORKSPACE" && \
-  tip_file="${TMPDIR:-/tmp}/legion-<KEY>-$LEGION_ROLE-rewritten-tip" && \
-  old=$(cat -- "$tip_file" 2>/dev/null || true) && \
-  behind=$(jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id.short() ++ "\n"' \
-    -r "remote_bookmarks(exact:\"legion/<KEY>\", exact:\"origin\") ~ (::@-${old:+ | $old})") && \
-  { [ -z "$behind" ] || { echo "legion/<KEY>@origin is at $behind, which @- does not descend from" >&2; false; }; } && \
-  jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> -r @- --allow-backwards && \
-  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY> && \
-  rm -f -- "$tip_file"
+cd -- "$LEGION_WORKSPACE" && legion push
 ```
 
-The `behind` check refuses unless `@-` descends from `legion/<KEY>@origin` (or the branch is not
-on GitHub yet). Every issue workspace shares one clone, so another role's push moves
-`legion/<KEY>@origin` here at once. With the flag and no check, `jj git push` then moves the
-remote branch sideways onto your commit and drops theirs (jj 0.45.1:
-`bookmark: legion/K [move sideways from <theirs> to <yours>]`). A clone that has not seen the other
-push is refused by jj itself (`unexpectedly moved on the remote`).
+It pushes `@-` through the provisioned credential helper, which authenticates as your role's App
+(`appauth.AppRoleFor` in `packages/daemon/internal/appauth/identity.go`). Your system prompt says
+which pushes skip CI and which commit-message keywords it refuses. Its ancestry check refuses
+unless `@-` descends from `legion/<KEY>@origin` (or the branch is not on GitHub yet): every issue
+workspace shares one clone, so another role's push moves `legion/<KEY>@origin` here at once, and
+a push that did not descend from it would move the remote branch sideways onto your commit and
+drop theirs.
 
 Before any rewrite of a commit you already pushed — a `jj squash --into` one, or any other
 rewrite — read *Rewriting pushed commits* in
 `skill://legion-worker/references/conflicts-and-rewrites.md`: it checks that no other tree's work
-is built on that commit and records the pushed tip `$tip_file` above reads, the only case in which
-the push above lets the remote branch move off its current tip.
+is built on that commit and records the pushed tip `legion push` reads, the only case in which a
+push lets the remote branch move off its current tip.
 
 Before the push, check ancestry and identity as above: the chain carries every earlier phase's
 commits, and pushing them with yours is expected. A refusal, and a push the remote rejects, is a
@@ -418,14 +385,10 @@ report to the architect with the output, never a force-push. The merger makes no
 pushes nothing.
 
 Do not report phase completion until the write, existence check, handoff commit, and push
-succeed. This is the committed copy the next phase
-reads after revival. It is removed once, at the end of a clean review: the implementer pushes
-that deletion at the reviewer's direction. No other phase removes it — and once it is gone
-(`jj -R "$LEGION_WORKSPACE" file list -r @- .legion` prints nothing on stdout; jj warns on
-stderr), this gate no longer applies: a later rebase, bare-gate re-check, confirmation, retro, or
-the post-merge production check writes no `.legion/<phase>.json`, commits no handoff, and reports
-with `handoff_complete` alone (below). Recreating `.legion/` after its deletion changes the
-approved head and restarts the review loop this rule exists to end.
+succeed. This is the committed copy the next phase reads after revival. No phase removes
+`.legion/`: the reviewer approves a head that carries it, and the operator removes it from the
+default branch after the merge. Retro and the post-merge production check write no
+`.legion/<phase>.json`, commit no handoff, and report with `handoff_complete` alone (below).
 
 ## Completion: report to the architect, then stay
 

package/skills/legion-worker/references/merge-gate.md

@@ -1,35 +1,32 @@
 # The merge gate: review, retro, READY, and the production check
 
 Part of `skill://legion-worker`. Read it when you are the reviewer submitting a review or an
-approval, the implementer pushing the `.legion/` deletion or recording the production check, or
-the merger publishing READY. Every path it cites is in sjawhar/legion.
+approval, the implementer recording the production check, or the merger building READY. Every
+path it cites is in sjawhar/legion.
 
-The order, in full: the tester's evidence green → the implementer's `.legion/` deletion push →
-the reviewer's approval of that head → retro → the merger's READY → the human merge → the
-implementer's production check. After the approval, only retro's `docs/solutions/` commit leaves
-it standing on its own (*Retro*, below). A conflict-forced merge goes back to the reviewer for a
-confirmation or a new round, as the fingerprint decides (*The reviewer*, below, and
-`skill://legion-worker/references/conflicts-and-rewrites.md`), and any other change voids it.
+The order, in full: the tester's evidence green → the reviewer's approval of the head →
+retro → the merger's READY → the human merge → the implementer's production check. No role
+removes `.legion/` before the merge: the approved head carries it, and the operator removes it
+from the default branch after the merge. After the approval, only retro's `docs/solutions/`
+commit leaves it standing on its own (*Retro*, below). A conflict-forced merge goes back to the
+reviewer for a confirmation or a new round, as the fingerprint decides (*The reviewer*, below,
+and `skill://legion-worker/references/conflicts-and-rewrites.md`), and any other change voids it.
 
 ## The reviewer
 
 - The reviewer verifies the `CI`, `Threads`, and `E2E` facts against GitHub directly —
   never from a handoff — then runs `task(agent="thermonuclear-deep-review")` and
-  `task(agent="thermonuclear-code-quality")` once at that head — the head the implementer's
-  simplify pass left final — and records the verdict.
+  `task(agent="thermonuclear-code-quality")` once at that head — the head the round reviews —
+  and records the verdict.
   Approval is refused while either `E2E (implementer)` or `E2E (tester)` is missing: `REQUEST_CHANGES` naming the missing line.
   Skip the `Thermo` line entirely on a docs-only PR. Submit **one review per round** —
-  `REQUEST_CHANGES` when any correctness finding stands, otherwise `COMMENT` while the head
-  still carries `.legion/`; `APPROVE` only for a head that carries no `.legion/` — the head
-  that differs from the reviewed one by the `.legion/` deletion alone, or, after a
-  conflict-forced rebase, the new head whose fingerprint equals the approved head's — always
-  named by SHA — carrying every inline comment in that single
+  `REQUEST_CHANGES` when any correctness finding stands, otherwise `APPROVE` of the head you
+  reviewed — always named by SHA — carrying every inline comment in that single
   call: `legion gh -- api --method POST repos/{owner}/{repo}/pulls/{number}/reviews --input body.json`
-  with `commit_id`, `event` (`REQUEST_CHANGES`, `COMMENT`, or `APPROVE`), `body` (with the
+  with `commit_id`, `event` (`REQUEST_CHANGES` or `APPROVE`), `body` (with the
   Legion footer), and a `comments[]` array of `{path, line, side, body}`, one entry per
   finding — never one `pr review` call per finding (each submission fires a `pr-review` wake).
-  Then return the issue to the architect; when clean, have the architect send the implementer
-  back to push the `.legion/` deletion, then review **that** head and approve it by name. After a
+  A `COMMENT` decides nothing. After a
   conflict-forced rebase, compute the fingerprint (*The unchanged-diff check* in
   `skill://legion-worker/references/conflicts-and-rewrites.md`) at the
   `commit_id` of your last submitted review and at the new head. Equal and that review was
@@ -41,8 +38,8 @@ confirmation or a new round, as the fingerprint decides (*The reviewer*, below,
   Apps, as `skill://legion-worker/references/review-threads.md` says; the same reference says
   when every thread is settled enough to approve, and resolving one never gates your approval.
 
-A reviewer's phase ends with its completion, not with its review. A round that writes a handoff
-takes this order: write, commit and push the handoff; submit the review of the head that push
+A reviewer's phase ends with its completion, not with its review. Every round writes a handoff
+and takes this order: write, commit and push the handoff; submit the review of the head that push
 made, by its SHA; then complete. An approval waits for the CI verdict to settle green at that head
 before you submit it, since an approval stands only on green checks and GitHub can dismiss one
 once the head moves, and a verdict that settles red there makes the round's decision a request for
@@ -57,40 +54,39 @@ require. A required check that was cancelled, or that the head's checks
 settled without, leaves no verdict until a later settlement decides it, since a run can be
 cancelled or not yet queued when the head settles; a required workflow's run on the head that is
 still going or has not happened leaves none either. A review of a head the handoff push
-then replaces names a head the pull request no longer has. A round that writes none (the final
-approval of the `.legion/` deletion head) reviews the head as it is. The daemon moves the issue
+then replaces names a head the pull request no longer has. The daemon moves the issue
 once both are in — the decision GitHub reports and your completion, in either order — so a
 review posted without a completion leaves the issue in reviewing until you finish.
 
 ## Retro
 
 - **Retro's commit does not void the reviewer's approval.** After the reviewer approves the
-  cleaned head, retro commits its learnings under `docs/solutions/` on top of it; that commit
+  head, retro commits its learnings under `docs/solutions/` on top of it; that commit
   stays, the approval stands, and the tree goes to the merger — never back to the tester or
   reviewer. Anything else above the approved head does void it, and the merger tells the
-  architect the head must return to review instead of publishing. A conflict-forced rebase
+  architect the head must return to review instead of completing. A conflict-forced rebase
   after retro moves those documents with the branch; retro never re-runs.
 
 ## The merger
 
 - The merger runs `legion threads resolve --pr <n> --repo <owner>/<repo>` (it acts as the same
   code-writing App as the implementer; resolving a thread changes no commit, so this run never
-  invalidates the approval), does not publish while any `left open` line remains or the command
+  invalidates the approval), does not complete while any `left open` line remains or the command
   exits 1 (report the thread to the architect instead), then proves that rule with two commands.
   First `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
   "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`, whose output is quoted
   in READY (an empty output is quoted as `no file changes above the approved head`); then the same
-  with `'~docs/solutions'` appended, which must print nothing. *The READY packet*: the merger
-  always posts `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
+  with `'~docs/solutions'` appended, which must print nothing. *The READY packet* is
+  `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
   (the shape `packages/daemon/internal/prompts/roles/merger.md` defines), then the PR body's
   `Outcome:` line and its `Not proven / risk:` value — every bullet under that label joined with
   `; ` on the one READY line, or `none` — quoted from the `## For the reviewer` block at that same
-  head (or one line saying the body carries no brief — the packet still publishes), then the
-  `--summary` output and the PR body's gate facts, as a `dispatch_message` on the issue. When the
-  `Legion addressing` line names a merge queue, it also publishes the same packet there with
-  `envoy_publish`; a 404 means the Dispatch message remains the durable notice and the merger
-  stays idle. The READY packet names both the implementer's and tester's `E2E` lines; a missing
-  one is reported to the architect instead of published. Legion never merges.
+  head (or one line saying the body carries no brief — the packet still goes out), then the
+  `--summary` output and the PR body's gate facts. The merger sends it as the `summary` of its
+  `handoff_complete` with `ready: true`; the daemon posts it as a `dispatch_message` on the issue,
+  publishes it to the project's merge queue role when one is set, and says on the issue when that
+  role has no live holder. The READY packet names both the implementer's and tester's `E2E` lines;
+  a missing one is reported to the architect instead of completing. Legion never merges.
 
 ## After the human merge
 

package/skills/legion-worker/references/pr-body.md

@@ -36,7 +36,7 @@ left open <thread URL> — newest reply by <login> is not an acceptance
 left open <thread URL> — newest reply by <login> is an unsubmitted draft in a pending review
 left open <thread URL> — newest reply by <login> is not its opener's or the Legion reviewer's acceptance
 
-**Thermo:** `ce-simplify-code` once at <head-sha>: <0 applied | applied → new head <sha>>; thermonuclear pair at the final head <sha>:
+**Thermo:** `ce-simplify-code` once at <head-sha>: <0 applied | applied → new head <sha>>; thermonuclear pair at the reviewed head <sha>:
 <verdict>. (omitted entirely on a docs-only PR — there is no code for either pass, so neither runs)
 
 **E2E (implementer):** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
@@ -66,7 +66,7 @@ repos/{owner}/{repo}/pulls/{number} --jq .body`, edit, then `--method PATCH ...
 `Not proven / risk` copies every claim recorded as unproven before READY — the tester's
 `failures`, the reviewer's own review, any proof-check comment already on the pull request —
 word for word, and `none` is a finding while one stands. The merger quotes `Outcome` and
-`Not proven / risk` from the body at the published head in the READY packet
+`Not proven / risk` from the body at the head its READY packet names
 (*The READY packet* in `skill://legion-worker/references/merge-gate.md`); a stale `Outcome` that no
 longer describes the diff is a finding against the implementer, not a line the merger rewrites.
 
@@ -95,8 +95,8 @@ and the tester's proof below are both this proof.
   the implementer's command or drives the same surface independently, and records the verdict in
   `.legion/test.json` as `implementerProof` (`{verdict, how}`).
   A test handoff whose predecessor carried no proof is a test failure, not a gap for the tester to fill:
-  record it in `failures` with `implementerProof.verdict: "rejected"`, complete the phase, and let
-  the architect return the issue to the implementer — the agent that developed the change owns
+  record it in `failures` with `implementerProof.verdict: "rejected"`, complete the phase with
+  `verdict: "fail"`, and the daemon returns the issue to the implementer — the agent that developed the change owns
   proving it (`handoff_write` for phase `test` refuses a rejected verdict, or `failed > 0`,
   with no recorded failure). Otherwise, add your own proof before completing — a proof as defined
   above — as the `E2E (tester)` line and the `proof` array `handoff_write` for
@@ -114,18 +114,17 @@ and the tester's proof below are both this proof.
   `E2E` line's head to the new SHA with
   `rebase re-check <old-sha> → <new-sha>: fingerprint unchanged, bare gates only`; the
   real-surface verification is not repeated. Different: a full test round.
-- **The implementer runs `skill://ce-simplify-code` once per pull request, after the last review round
-  closes and before the reviewer's final pass, when the diff touches runtime code; a docs-only
-  diff gets none.** It is scoped to the pull request's own diff, at the head where the last review
-  round closed: nothing applied leaves that head final; applied → the applied head is the final
-  head: CI runs on it, the pair runs once on it, and the E2E proof re-runs on it for the surface
-  the simplify diff touched, since a refactor that "preserves behaviour" is a claim until it is
-  executed. That cost is
-  why 0-applied is the expected outcome and a pass that applies is spent sparingly. At the applied
-  head the implementer re-cites the `CI` line and re-runs its own proof into `E2E (implementer)`,
-  and the tester re-runs its proof for the touched surface into `E2E (tester)`, before the
-  reviewer's final pass. Simplify is the last code change; the pair is the last review. Record it
-  in the `Thermo` line.
+- **The implementer runs `skill://ce-simplify-code` once per pull request, in its first
+  implementing round, after its own proof and before it completes that round, when the diff
+  touches runtime code; a docs-only diff gets none.** The daemon starts no implementing round
+  between a clean review and the approval, so this is the one slot before the tester and the
+  reviewer read the head; a later round answering a review runs no second pass. It is scoped to
+  the pull request's own diff at that head: nothing applied leaves the head as it is; applied →
+  the implementer re-runs the repository's checks and its own proof on the applied head for the
+  surface the simplify diff touched, since a refactor that "preserves behaviour" is a claim until
+  it is executed, and re-cites the `CI` line and `E2E (implementer)` there before it completes.
+  That cost is why 0-applied is the expected outcome and a pass that applies is spent sparingly.
+  The reviewer's pair runs at the head each round reviews. Record both in the `Thermo` line.
 - **No deferrals** is the body's rule (*PR body, review, and the merge gate* in
   `skill://legion-worker`): the `Fast-follow:` line holds naming, duplication, or wording cleanup
   only. A base frozen for others to stack on is never rewritten (*Rewriting pushed commits* in

package/skills/legion-worker/references/review-threads.md

@@ -35,8 +35,7 @@ Every path it cites is in sjawhar/legion.
   your own `gh`; where no `legion` command is installed, use `gh api graphql` with the session's
   GitHub credential and the fallback below.
   In a Legion pane, the **implementer** runs the command after every push that answers a review
-  (the corrective push, and the final `.legion/` deletion push where the daemon has one) and
-  before its `handoff_complete`, and pastes its output, stamped with the head it just pushed, into
+  and before its `handoff_complete`, and pastes its output, stamped with the head it just pushed, into
   the `Threads` section. The output is then recorded against the head the reviewer will read, and
   nothing reads thread state before the implementer's completion. The command resolves each
   unresolved thread whose newest submitted comment is the opener's own `Accepted:` reply. On a
@@ -80,8 +79,8 @@ Every path it cites is in sjawhar/legion.
 
   Re-read `reviewThreads` and confirm that thread's `isResolved` is true. In either route, report
   a refused resolution to the architect, which opens an ask for a human to resolve the thread by
-  hand — never skip it silently. The merger runs the command once more before publishing READY
-  and does not publish while any `left open` line remains. That run is where every accepted
+  hand — never skip it silently. The merger runs the command once more before its READY
+  completion and does not complete while any `left open` line remains. That run is where every accepted
   thread's resolution is guaranteed, since the merge queue's gate counts the unresolved threads at
   the head. Acceptances posted after the implementer's last run are resolved here.
 
@@ -99,4 +98,4 @@ Every path it cites is in sjawhar/legion.
   workflow passes on a re-run only once its threads are resolved, so you run `legion threads
   resolve` (the daemon resolves the bot threads you accepted) and re-run the failed run before you
   approve, as your role prompt says.
-  The merger resolves accepted threads that remain open before publishing READY.
+  The merger resolves accepted threads that remain open before its READY completion.