@sjawhar/opencode-legion-envoy 1.23.0 → 1.25.0

package/dist/src/server.js

@@ -13552,6 +13552,7 @@ function date4(params) {
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
 // ../contracts/src/dispatch-api.ts
+var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 function searchOwnerOf(result) {
   return result.owner ?? { kind: "issue", key: result.issue.key };
 }
@@ -13634,6 +13635,8 @@ var CommentEventPayloadSchema = object({
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   ask_state: _enum2(["open", "answered", "resolved"]).optional(),
+  ask_waiting_on: _enum2(["human", "agent"]).optional(),
+  turn: _enum2(["human", "agent"]).nullish(),
   anchor: object({ block_id: string2().nullable().optional(), quote: string2().optional() }).nullish(),
   suggestion: object({ replace_with: string2().optional() }).nullish(),
   author: object({ kind: string2(), id: string2() }).optional(),
@@ -13660,7 +13663,7 @@ var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
 var MessageDeliveryEventPayloadSchema = object({
   message_id: string2().optional(),
   attempt: number2().int().positive().optional(),
-  delivery: _enum2(["btw", "aside", "steer"]).optional(),
+  delivery: _enum2(DELIVERY_CAPABILITIES).optional(),
   session_id: string2().optional(),
   target: string2().optional(),
   title: string2().optional(),
@@ -13751,6 +13754,16 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
     message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
+var commentValidation = (() => {
+  const owner = documentOwnerValidation(true);
+  return {
+    check: (value) => {
+      const input = value;
+      return owner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
+    },
+    message: `${owner.message} turn requires reply_to_ask.`
+  };
+})();
 var SPEC_SECTIONS = [
   "Summary",
   "Decisions needed",
@@ -13846,9 +13859,10 @@ var dispatchToolSpecs = [
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
       reply_to: z.string().describe("Full id of a comment to reply to; replying to any comment in a thread continues that " + "thread (an ask's clarification thread included).").optional(),
-      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional()
+      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
+      turn: z.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: commentValidation
   },
   {
     name: "dispatch_suggest",
@@ -14220,7 +14234,7 @@ var LegionDaemonApi = {
         queue: array(nonEmptyString)
       }),
       gates: record(string2(), stateGate),
-      controllerLocator: stateLocator.optional(),
+      controllerLocator: stateTreeLocator.optional(),
       roles: record(string2(), stateRole),
       controllerPendingNotices: number2().int().nonnegative(),
       pendingStatusWrites: array(nonEmptyString),
@@ -14228,7 +14242,11 @@ var LegionDaemonApi = {
     })
   },
   ControllerReady: {
-    request: strictObject({ secret: nonEmptyString, sessionId: nonEmptyString }),
+    request: strictObject({
+      secret: nonEmptyString,
+      sessionId: nonEmptyString,
+      ompSessionFile: nonEmptyString.optional()
+    }),
     response: object({})
   },
   ProcessStarted: {
@@ -14348,17 +14366,23 @@ var LegionDaemonApi = {
     response: object({})
   },
   Grant: {
-    request: strictObject({
-      tree: nonEmptyString,
-      issue: nonEmptyString,
-      sessionId: nonEmptyString,
-      secret: nonEmptyString
-    }),
+    request: union([
+      strictObject({
+        sessionId: nonEmptyString,
+        secret: nonEmptyString,
+        tree: nonEmptyString,
+        issue: nonEmptyString
+      }),
+      strictObject({ sessionId: nonEmptyString, secret: nonEmptyString })
+    ]),
     response: object({ grantId: nonEmptyString, expiresAt: nonEmptyString })
   },
   GitHubToken: {
-    request: strictObject({ grantId: nonEmptyString }),
+    request: strictObject({ grantId: nonEmptyString, merge: literal(true).optional() }),
     response: object({ token: nonEmptyString, appLogin: string2().endsWith("[bot]") })
+  },
+  GitCredential: {
+    request: strictObject({ grantId: nonEmptyString })
   }
 };
 // ../contracts/src/repo.ts
@@ -15613,21 +15637,34 @@ async function executeDispatchTool(input) {
       if (replyTo !== undefined && replyToAsk !== undefined) {
         throw new Error("reply_to and reply_to_ask cannot both be set");
       }
+      const requestedTurn = optionalString(args, "turn");
+      if (requestedTurn !== undefined && replyToAsk === undefined) {
+        throw new Error("turn requires reply_to_ask");
+      }
+      if (requestedTurn !== undefined && requestedTurn !== "agent" && requestedTurn !== "human") {
+        throw new Error("turn must be agent or human");
+      }
       const commentInput = {
         body: stringArg(args, "body"),
         ...anchored === undefined ? {} : { anchor: anchored },
         ...replyTo === undefined ? {} : { reply_to: replyTo },
         ...replyToAsk === undefined ? {} : { ask_id: replyToAsk },
+        ...requestedTurn === undefined ? {} : { turn: requestedTurn },
         actor
       };
       const comment = resolved?.owner.kind === "project" ? await client.artifactComment(resolved.artifact.id, commentInput) : await client.comment(issue(), commentInput);
+      const askState = comment.turn === null ? "" : ` (ask now waiting on ${comment.turn})`;
       return {
-        text: `Posted comment ${comment.id}`,
+        text: `Posted comment ${comment.id}${askState}`,
         details: resolved === undefined ? {
           issue: comment.issue_key,
           topic: dispatchIssueSubject(issue(), ">"),
-          comment: comment.id
-        } : writeResultDetails(resolved, { comment: comment.id })
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        } : writeResultDetails(resolved, {
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        })
       };
     }
     case "dispatch_suggest": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -42,6 +42,16 @@ agent's `envoy.json` to set the GitHub OAuth callback origin: the value must
 be the exact URL humans type in their browser, and the GitHub App callback is
 `<DISPATCH_SERVER_URL>/auth/callback`.
 
+### Finding a route
+
+The tools cover the everyday surface. For anything else, ask the server: `GET /api/v1` (no
+credential) returns every route as `{method, path, auth, description}` sorted by path — `auth`
+is `public`, `any` (a human or a bearer), `human` (a bearer gets `403 HUMAN_ONLY`), or `bearer`.
+A path Dispatch does not serve under `/api` or `/v1` answers
+`404 {"code":"NOT_FOUND","error":"no route for GET /v1/issues","hint":"GET /api/v1 lists every
+route"}`; when you see that, you typed the path wrong — read the index rather than guessing. Every
+`/api/v1` error body carries a `code`; branch on the code, never on the text.
+
 ## Writing a spec
 
 A spec has two readers: the human who decides reads the top; the implementer who builds reads the
@@ -194,6 +204,14 @@ an answer: the human did not understand the question or needs more before choosi
 in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with `dispatch_edit_ask` when the wording
 was the problem; either puts the ask back in front of them. Do not open a second ask.
 
+Every reply to an open ask says whose turn it is next, and the Inbox files the ask by that, not by who spoke last. Your plain reply
+(`turn` omitted, or `turn: "human"`) hands the turn to the human: the ask returns to their `Waiting on you`. When you are not done
+yet — "dispatched two auditors, back with results", "checking the release branch, back shortly", any working-on-it note — reply with
+`turn: "agent"`: the note lands in the thread, the ask stays under `Waiting on agents`, and the human is not told to act. Use
+`turn: "agent"` for every progress note and `turn: "human"` (the default) only when you need them. A human's reply always hands the
+turn to you. The result names the state (`ask now waiting on agent` / `human`), the delivered `comment.created` carries it as
+`ask_waiting_on`, and every ask read carries it as `waiting_on`.
+
 ## Approval of a spec
 
 Approval is a property of a document, not a question you phrase: a human approves a specific version, the way a pull-request
@@ -300,7 +318,7 @@ an ask block without a question or with a blank option is rejected with `INVALID
 Add feedback with:
 
 ```ts
-dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
+dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask?, turn? })
 ```
 
 It returns issue or project-document owner details plus `comment` and, for writes, `topic`.
@@ -309,8 +327,10 @@ It returns issue or project-document owner details plus `comment` and, for write
 for display. Omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no
 `quote`; it belongs to its parent's anchor. Reply to any comment in a thread; the server keeps
 threads flat. A reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a
-question asked with `dispatch_ask`. Comments are edited only by their author from the dashboard. A
-delivered `comment.created` event carries the comment `id`; reply to it with
+question asked with `dispatch_ask`; `turn` (only with `reply_to_ask`) says who holds the turn after
+the reply — `agent` for a progress note that keeps the ask waiting on you, `human` (the default) when
+the human needs to act; see [Asking](#asking). Comments are edited only by their author from the
+dashboard. A delivered `comment.created` event carries the comment `id`; reply to it with
 `dispatch_comment({ reply_to: <id> })`.
 
 Propose an exact replacement instead of describing it:
@@ -395,7 +415,10 @@ dispatch_message({
 delivery can post its answer automatically; use this call when the frame asks the primary agent to
 reply. `dispatch_message` itself never carries `target` or `delivery`: agent-to-agent traffic goes
 through Envoy or the hub. A bearer that targets over HTTP names its own session in `actor`
-(`{kind: "session", id}`), and the card shows that session as the author.
+(`{kind: "session", id}`), and the card shows that session as the author. `GET /api/v1/agents`
+(any authenticated caller) lists live sessions with their capabilities (`aside`, `btw`, `steer`);
+target only a session that advertises the mode you want. Sending to a session with no issue
+(`POST /api/v1/agents/{session_id}/messages`) stays human-only.
 
 ## What comes back
 

package/skills/envoy/SKILL.md

@@ -90,6 +90,16 @@ envoy_send(
 )
 ```
 
+### Delivery capabilities
+
+Each session row from `envoy_sessions` carries `capabilities`, the targeted-delivery modes that
+session's host honours: `aside` (a message queued beside the model's work), `btw` (an ephemeral
+question the host answers without disturbing the current turn), and `steer` (an interjection at
+the next tool boundary). An OMP session advertises `aside`, `btw`, and `steer` (`aside` and
+`steer` on a host without `askEphemeral`); a Claude Code session advertises `aside` only, because
+its channel notifications queue for the next turn. Target a session only with a mode it
+advertises.
+
 ## Waiting for CI or a merge
 
 Subscribe to `notifications.github.example-org.example-repo.pr.42.>` and end the turn. The single

package/skills/legion-architect/SKILL.md

@@ -28,9 +28,9 @@ separate coordinator to finish necessary work.
   asking session.
 - The daemon spawns each role as its own process with the issue's context already in its
   environment. Never hand-format a role token: the daemon encodes one as
-  `legion-<project>-<KEY>-<role>`; for example, project `acme`, issue `LEGION-41`, role
-  `architect` encodes to `legion-acme-LEGION-41-architect`. Reuse a token you already
-  hold (your own, or one `spawn_worker` returned) or compute another with the
+  `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`. Reuse a
+  token you already hold (your own, or one `spawn_worker` returned) or compute another with the
   `roleToken` helper from `@legion/contracts` exactly the way the daemon does.
 - There is no label vocabulary. Dispatch status replaces the board, and the design gate
   is a human approving the root spec document at a version in Dispatch, requested with
@@ -240,11 +240,18 @@ Preserve this order exactly:
    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 publishes `READY #<n> at <sha>` to `notifications.role.pr-queue`; it never
-   merges. The merge queue merges under its own authority and the repository's own rules
-   (branch protection, CODEOWNERS); whether a human must approve first is that repository's
-   setting, not Legion's, and you never ask for or wait on such an approval.
-5. the merge queue merges; you then `spawn_worker` the **implementer** once more with the
+   and publishes `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
+   to the project's controller topic (the merge queue; named in its `Legion addressing` line);
+   it never merges. The controller verifies the gates against live GitHub — the current head,
+   required checks, review threads, mergeability, that only `.legion/` deletions lie between the
+   head the `## Verification` block names and the approved sha, that only `docs/solutions/`
+   changed between the approved and current shas, and that the block is complete at the head it
+   names — and merges the current sha, pinned, under the implement App's identity and the
+   repository's own rules (branch protection, CODEOWNERS); it does not check the approval itself,
+   and whether a human must approve first is that repository's setting, not Legion's, so you never
+   ask for or wait on such an approval. If the controller reports a failed gate to you, treat it
+   like `pr-blocked`: fix through the phases, never bypass.
+5. the controller merges; you then `spawn_worker` the **implementer** once more with the
    production-check task. It drives the changed path in production through the user's own access
    path and records what it saw on the pull request and on this issue. Close only after the implementer's production report exists.
    A defect it finds is a corrective child issue of this tree, not a note on a closed one; a deploy
@@ -306,7 +313,7 @@ active phase worker.
 | `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/merger order only for that current head. |
 | `pr-review` | Payload `{type:"pr-review", state, author, body}`. Delivered to whichever role is currently active for the issue, falling back to you when no worker phase is active. Follows the same verdict rule as a reviewer's `phase-complete`: `state: "changes_requested"` sends the implementer back in with the review findings, then tester, then reviewer — never the reviewer again and never retro; that `spawn_worker` returns the issue to `in_progress` on its own (the daemon writes it for a corrective implementer whenever the PR's latest recorded review is changes requested, a human's after approval included), so you set nothing by hand; `state: "approved"` proceeds toward retro (step 5) once the step 6 integration/merge-gate conditions are met. `state: "approved"` on a rebased head whose body names an unchanged fingerprint is that confirmation: proceed to retro if it has not run, otherwise to the merger — never to a second retro or test round. |
 | `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 the daemon cannot classify (a listener without `changed_paths`, a list capped at 100, 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. Assign a focused implementer or corrective child, then return it through testing and review; do not treat the blocked PR as final. |
-| `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The merge queue landed the PR. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
+| `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The controller merged the PR. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether to reopen the work, send a fresh implementer, or cancel it 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. Answer it, 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-complete` wake, then compare `childCounts[LEGION_ISSUE].open` with `legion state` and Dispatch before deciding the next action. |

package/skills/legion-controller/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: legion-controller
-description: Use when handling Legion controller wakes for root-issue triage, backlog admission, architect escalation, resync healing, or human interaction.
+description: Use when handling Legion controller wakes for root-issue triage, backlog admission, architect escalation, resync healing, merge-queue READY handling, or human interaction.
 ---
 
 # Legion Controller
@@ -14,21 +14,52 @@ routes raw events into an architect.
 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.
 
-For an interactive takeover, start OMP with `LEGION_CONTROLLER_SECRET` (or
-`LEGION_CONTROLLER_SECRET_FILE`, a path to a file holding it) and `LEGION_DAEMON_URL` in its
-environment, then run:
+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`; Sami 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). Sami may attach and
+type into this session at any time. The pane carries the same credential environment as a
+worker's — `LEGION_GRANT_FILE`, `GH_CONFIG_DIR`, the GitHub token variables emptied; the
+`<state_dir>/worker-bin`-first `PATH` the daemon renders reaches no pane today (tmux drops the
+`-e PATH=` pair at pane creation, LEGION-91), so a bare `gh` is whatever the box has — so
+`legion gh -- <args>` works here exactly as it does for a phase worker (`legion` resolves through
+`<state_dir>/bin`, which the pane inherits from the daemon's own `PATH`):
+before every `bash` call the extension mints a short-lived controller grant and writes it to
+the file `LEGION_GRANT_FILE` names (never into the command text or the tool's `env`), `legion`
+reads it from there, and that grant is the only one the daemon lets merge 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`
+(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:
 
 ```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. It retains the environment
-capability for `legion({ op: "set_status", issue, status })`. 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.
+session, and posts readiness before controller commands can act. From then on this session's
+shell commands are wrapped with a controller grant exactly like the daemon pane's, so
+`legion gh -- <args>` works here; `legion status <KEY> <status>` works too, but 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
+`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.
@@ -59,14 +90,16 @@ override a Sami ruling quoted here.
 
 | Wake | Content | Controller action |
 |---|---|---|
-| New issue created in the Dispatch project (`issue.created`, status `triage`; resync heals misses) | issue key + triage context (incl. pre-existing children) | Triage: `legion({ op: "set_status", issue, status: "todo" })` to admit, or set `backlog`/`icebox` to park |
+| New issue created in the Dispatch project (`issue.created`, status `triage`; resync heals misses) | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
 | Backlog eligibility | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch_ask` from the owning architect, not here |
 | 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 |
-| Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion({ op: "set_status", issue: root, status: "todo" })`; otherwise no action — the event is not held or redelivered |
+| READY from a merger (`notifications.role.<controller token>`) | `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` + gate facts | Run the Merge queue gates against live GitHub; merge, or report the failed gate to the tree's architect |
+| `pr.<n>.checks` settled on a PR with a pending READY | check rollup for the head | Re-run the Merge queue gates for that READY; merge, report, or keep waiting only if still pending |
+| 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
@@ -77,17 +110,17 @@ override a Sami ruling quoted here.
 2. If it should run now, admit the root issue:
 
    ```text
-   legion({ op: "set_status", issue: "<issue>", status: "todo" })
+   legion status <issue> todo
    ```
 
 3. If it should deliberately wait, move it to a parked status instead of leaving it in
    `triage`:
 
    ```text
-   legion({ op: "set_status", issue: "<issue>", status: "backlog" })
+   legion status <issue> backlog
    ```
 
-   (or `status: "icebox"` for longer-term deferral). Dispatch status is the durable record;
+   (or `icebox` for longer-term deferral). Dispatch status is the durable record;
    there is no separate marker to maintain. Do not triage a system-created child as a root
    issue.
 
@@ -95,7 +128,7 @@ override a Sami ruling quoted here.
 
 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({ op: "set_status", issue, status: "todo" })`. Moving an item to or from `backlog`/
+`legion status <KEY> todo`. Moving an item to or from `backlog`/
 `icebox` is a deliberate controller decision, not a no-op.
 
 ## Architect escalation
@@ -110,7 +143,7 @@ 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`).
    `project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`) — not
    the role-token `<project>` (the daemon's own project, e.g. `acme`), a different string.
-2. Park the child (`legion({ op: "set_status", issue: child, status: "icebox" })`) and leave
+2. Park the child (`legion status <child> icebox`) and leave
    a pointer to the new root issue. The controller's capability is `todo`/`backlog`/`icebox`
    only — only the owning architect or the daemon closes an issue as `done`.
 3. Admit or deliberately backlog the new root through the normal triage procedure.
@@ -141,3 +174,188 @@ gate at all runs `gates.design: off` in its `legion.yaml`. Otherwise resolve the
 owning architect role and route the verified context with `envoy_publish`. Do not route raw
 event traffic or invent a role token from a partial issue reference.
 
+## Merge queue
+
+The controller is the project's merge queue. A merger reports a pull request ready by
+publishing to the controller topic; the controller re-reads every gate from live GitHub and
+merges, or tells the tree's architect exactly which gate failed. The merger's report is a
+claim, never evidence.
+
+**READY message shape.** Defined once in `packages/pi-envoy/roles/merger.md` and mirrored here
+verbatim. The first line is
+`READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`: the pull
+request number, the sha of the pull request's current head, the sha the reviewer's head-pinned
+approval names, the issue key, and the pull request URL. The rest of the message is the PR
+body's gate facts (the `## Verification` block). You need every field: the URL addresses the
+pull request from this pane's working directory (which is not a checkout), the key finds the
+tree's architect (below), the current sha is the only head you may merge, and the approved sha
+anchors the two path-only compares in gates 5 and 6. The controller never verifies the
+approval itself: whether a review must exist before merge is the repository's own
+branch-protection or CODEOWNERS rule, which GitHub enforces at `pr merge` time and Legion
+neither reads nor writes.
+
+**Three shas.** This repository's flow leaves three commits that matter, and they are normally
+all different. The *verified* sha is the head the tester and the reviewer worked at: the
+`## Verification` block's own `CI`, `Thermo`, and `E2E` lines name it, and they must agree. After
+that head is found clean the implementer pushes the `.legion/` handoff deletion and the reviewer
+approves *that* head by name — the *approved* sha, one commit later. Retro then commits its
+`docs/solutions/` learning on top — the *current* sha. READY carries the current and approved
+shas; the verified sha you read from the block. The gates check the block at the verified sha
+and prove, with two compares, that nothing but the `.legion/` deletion lies between verified and
+approved, and nothing but `docs/solutions/` between approved and current.
+
+**Gates.** Read them from live GitHub, never from the message or the PR body alone. Every `gh`
+command takes the pull request URL, or `--repo <owner>/<repo>` taken from it, because this
+session's working directory has no git remote to resolve a bare number against:
+
+```text
+legion gh -- pr view <pr url> --json headRefOid,baseRefName,mergeable,body,files
+legion gh -- pr checks <pr url> --required --json name,state,bucket,link
+legion gh -- api repos/<owner>/<repo>/rules/branches/<baseRefName from pr view> --jq '[.[] | select(.type=="required_status_checks") | .parameters.required_status_checks[].context]'
+legion gh -- api repos/<owner>/<repo>/branches/<baseRefName from pr view> --jq '.protection.required_status_checks.contexts'
+legion gh -- api graphql -f query='query($owner:String!,$repo:String!,$n:Int!,$after:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor}nodes{isResolved}}}}}' -F owner=<owner> -F repo=<repo> -F n=<n> -F after=<null for the first page>
+legion gh -- api repos/<owner>/<repo>/compare/<verified sha>...<approved sha> --jq '{status, files: [.files[].filename]}'
+legion gh -- api repos/<owner>/<repo>/compare/<approved sha>...<current sha> --jq '{status, files: [.files[].filename]}'
+```
+
+1. **head**: `headRefOid` equals the `<current sha>` in the READY. Any other head is a different
+   pull request as far as this READY is concerned.
+2. **checks**: `pr checks --required --json …` exits 0 with at least one row, and every row's
+   `bucket` is `pass` or `skipping`. That is the only green. The five buckets the CLI emits
+   (`gh pr checks --help`): `pass` and `skipping` are green — a job skipped by its `if:` (a
+   path-filtered workflow skips the jobs whose paths a pull request does not touch, and GitHub
+   treats a skipped job as satisfying a required check);
+   `pending` is pending; `fail` and `cancel` never merge (the Flake rule applies to both). With
+   `--json` the command exits 0 whenever rows exist, whatever their buckets, so the buckets
+   decide, never the exit code. Exit 1 comes only with no rows: `no checks reported on the
+   '<branch>' branch` when nothing has reported at the head yet (a freshly pushed head has no
+   check runs for a few seconds; a head that conflicts with the base never gets any, but that
+   head fails gate 4 — report it, do not subscribe), or `no required checks reported on the
+   '<branch>' branch` when checks exist but none is required. Either message is **pending**,
+   never green: subscribe to the pull request's `pr.<n>` and `pr.<n>.checks` topics exactly as
+   the Pending READY paragraph below says, and re-run the gates on that wake. (Without `--json`
+   the CLI exits 8 for pending rows and 1 for a failing row or no rows; you never run it that
+   way — the rows are what you read.) Two exceptions, both read from the repository, never from
+   the absence of rows:
+   - A repository that genuinely requires no checks. Required checks live in two places, and
+     both must be empty: the `rules/branches/<baseRefName>` query above (rulesets) returns `[]`
+     **and** the `branches/<baseRefName>` query above (the classic branch-protection summary,
+     which the implement App can read; the admin endpoint
+     `branches/<baseRefName>/protection/required_status_checks` is not readable under your credentials
+     and is not used) returns `[]`. Only then does the `no required checks reported` exit let
+     this gate hold with no check rows. A repository whose required checks are classic
+     protection answers `[]` for rulesets and the check names in the classic summary; `null`
+     from the classic query (no `protection` object in the answer) is not `[]` and leaves this
+     gate pending.
+   - A private repository on GitHub's free plan cannot define required checks at all: the
+     rulesets query answers HTTP 403 with a JSON body whose `message` **contains** the phrase
+     `make this repository public to enable this feature` (`gh` prints the whole message with
+     `(HTTP 403)` appended). Match that phrase as a substring — it is the stable tail; the head
+     names the plan (`Upgrade to GitHub Pro` for a user-owned repository, `Upgrade to GitHub
+     Team` for an organization-owned one) and the sentence ends with a period inside a JSON
+     wrapper, so literal equality never matches. Any other 403 — `Resource not accessible by
+     integration` included — is a permission error and stays an error, never "no required
+     checks". Under this exception gate 2 requires every check reported on the head to be green
+     instead: `legion gh -- pr checks <pr url> --json name,state,bucket,link` (without
+     `--required`) exits 0 with at least one row and every row's `bucket` is `pass` or
+     `skipping`. A `pending` row is pending, a `fail` or `cancel` row never merges, and no rows
+     (the exit-1 `no checks reported`) stays pending exactly as above. This is stricter than
+     "no required checks, merge", and GitHub still enforces whatever protection the repository
+     does have at `pr merge` time, so a wrong read costs a refused merge reported to the
+     architect, never an unprotected one.
+   Where each of these reads was observed — the CLI version, the two repositories, the exact
+   answers — is recorded in
+   `docs/solutions/legion/controller-gate-2-required-checks-live-reads.md`. The rule above is
+   what you execute; the live answers are what you read.
+3. **threads**: zero unresolved review threads across every page. Start with `after: null`, then
+   repeat the query with the prior page's `pageInfo.endCursor` until `hasNextPage` is false; the
+   count of `isResolved: false` across all pages must be 0. A missing `pageInfo`, a missing cursor
+   while `hasNextPage` is true, or any failed page is a failed gate: do not merge. This follows the
+   pagination `legion threads resolve` uses, but the controller reads only and never resolves a
+   review thread.
+4. **mergeable**: `mergeable` is not `CONFLICTING` and not `UNKNOWN`.
+5. **cleanup only**: `compare/<verified sha>...<approved sha>` reports `status` `identical` or
+   `ahead`, and every path in `files` starts with `.legion/` — the handoff deletion the reviewer
+   directed, and nothing else. Anything else between the two is the failed gate
+   `cleanup changed more than .legion`.
+6. **retro only**: `compare/<approved sha>...<current sha>` reports `status` `identical` or
+   `ahead`, and every path in `files` starts with `docs/solutions/`. Anything else between the
+   two is the failed gate `head moved beyond retro`: the approval no longer covers the head.
+7. **verification block**: the PR body's `## Verification` block (the template in
+   `skills/legion-worker/SKILL.md`) is complete and current at the verified sha. The tester
+   fills the `E2E` line before review; the reviewer writes the `Thermo` line at the head it
+   audited; approval lands one commit later on the cleanup head; so the block names the verified
+   sha, never the approved or the current one. Line by line: the `CI` line names a run and
+   reports success at one sha; the `Thermo` line names the same sha and a verdict, unless the
+   pull request is docs-only, in which case the template omits that line entirely — docs-only
+   is a fact you read, never one you take from the omission itself: every `path` in the `files`
+   list of the `pr view` command above starts with `docs/` or ends with `.md`
+   (`--jq '[.files[].path | select((startswith("docs/") or endswith(".md")) | not)]'` is `[]`);
+   a missing `Thermo` line on any other pull request fails this gate; the `E2E`
+   line names the same sha and has a `Negative control` line — those lines agreeing on one sha
+   is what defines the verified sha; the `Threads` line reports `0 unresolved` (its per-thread
+   lines name fixing commits, never the head — do not look for a sha there); the `Fast-follow`
+   and `Chain` lines are filled in. No `<placeholder>` text remains anywhere in the block.
+
+When all seven hold, merge:
+`legion gh -- pr merge <pr url> --squash --match-head-commit <current sha>`. The head pin makes
+GitHub refuse the merge if a push landed after gate 1 read the head; that refusal is a failed
+`head` gate, reported like any other. The grant your `bash` call carries is the controller's
+own, the only grant the daemon honours for a merge; the merge runs under the implement App's
+identity and the repository's own rules (branch protection, CODEOWNERS). Whether a human must
+approve first is that repository's setting — you neither read nor bypass it, and you never
+admin-merge without an explicit deployment grant from Sami for that specific merge.
+
+**Failed gate.** Reply to the tree's architect naming the gate (`head`, `checks`, `threads`,
+`mergeable`, `cleanup changed more than .legion`, `head moved beyond retro`, or
+`verification block`) and the evidence you read (the shas, the check name and run link, the
+thread count, the `mergeable` value, the offending paths from the compare). Do not merge, do not
+retry on a timer. The architect fixes through the phases.
+
+**Flake.** A required check that failed or was cancelled (`bucket` `fail` or `cancel`) for a
+reason unrelated to the change (a runner outage, a rate limit, a known-flaky job) may be rerun
+once: `legion gh -- run rerun <run-id> --failed --repo <owner>/<repo>`, the run id taken from
+the failing row's `link` (`https://github.com/<owner>/<repo>/actions/runs/<run-id>/job/<job-id>`).
+Then stop. The rerun's result reaches you as a `pr.<n>.checks` wake; re-run the gates then.
+A second failure is a failed gate, reported as above.
+
+**Conflicts and unknown mergeability.** `mergeable == CONFLICTING` is the only reason to ask
+for a rebase: reply to the tree's architect asking for one. Never request a rebase for any other
+reason — the CI queue is long and slow, and an unnecessary rebase clogs it for every other pull
+request. `mergeable == UNKNOWN` means GitHub has not finished computing it: do not merge, do
+not poll; re-read on the next `pr.<n>.checks` wake.
+
+**Pending READY.** A READY that cannot merge yet only because checks are still running (a
+`pending` row), none has reported at the head yet (gate 2's `no checks reported` exit), a flake
+rerun was issued, or `mergeable` is `UNKNOWN` is pending. Subscribe to that pull request's
+events so its settlement wakes you:
+
+```text
+envoy_subscribe({ topics: ["notifications.github.<owner>.<repo>.pr.<n>", "notifications.github.<owner>.<repo>.pr.<n>.checks"] })
+```
+
+On that wake, re-run the gates against the shas from the READY in your conversation, then
+`envoy_unsubscribe` those topics once you have merged or reported a failed gate. The controller
+never polls; READY and `pr.<n>.checks` are the only wakes. If you were resumed and no longer
+have the READY in your conversation, ask that issue's merger (its token is the `roles` key in
+`legion state --json` whose `issue` is `<KEY>` and whose `role` is `merger`; publish to
+`notifications.role.` followed by that key) to republish it; never guess a sha.
+
+**Finding the tree's architect.** Never hand-format a role token: the daemon lower-cases the
+issue key inside it (`LEGION-16` becomes `legion-16`) and rejects any other shape, so a token
+you assemble from `<KEY>` never matches a live role. Read it instead: `legion state --json`
+gives `issues[<KEY>].parent`; follow `parent` until it is absent — that key is the root (the
+`trees` map lists the same roots). Then take the `roles` key whose `issue` equals that root and
+whose `role` is `architect`, and publish to `notifications.role.` followed by that exact key.
+Every registered root architect and phase worker appears in `roles`, so the lookup is
+unambiguous. (Phase workers get an addressing line in their system prompt; the controller does
+not, so state is your only source.)
+
+**After a successful merge, publish nothing to the architect.** The daemon derives
+`{type:"pr-merged", pr, mergeCommitSha}` from GitHub's own merged webhook and routes it to the
+tree's architect itself. A second copy from you would make the architect run its sign-off twice.
+
+**Policy questions go to Sami.** Whether a pull request should merge at all, whether an admin
+merge is warranted, or a gate that looks wrong for this repository is not a controller judgment:
+ask with `dispatch_ask` on the issue, in plain sentences, and leave the READY pending until the
+answer arrives.

package/skills/legion-worker/SKILL.md

@@ -404,11 +404,15 @@ Verified the implementer's proof by <re-running its command | driving the same s
   `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. Then it publishes `READY #<n> at <tip-sha>` naming the approved
-  head, the tip, and that summary, plus the PR body's gate facts, to the merge queue's role
-  (`notifications.role.pr-queue`) with `envoy_publish`. The READY packet names both the
-  implementer's and the tester's `E2E` lines; a missing one is reported to the architect instead
-  of published. The merger never merges; the queue merges under its own authority.
+  which must print nothing. Then it publishes
+  `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` (the shape
+  `packages/pi-envoy/roles/merger.md` defines) with that summary and the PR body's gate facts to
+  the project's controller topic (the merge queue, named in the `Legion addressing` line at the
+  end of the system prompt) with `envoy_publish`; on a 404 no-holder it publishes the same `READY`
+  to the architect's topic and stays idle. The READY packet names both the implementer's and the
+  tester's `E2E` lines; a missing one is reported to the architect instead of published. The
+  merger never merges; the controller verifies the
+  gates against live GitHub and merges under its own authority.
 - **After the queue merges, the implementer verifies in production.** Sami, 2026-09-13,
   verbatim: "the agent that developed it should be responsible for testing in production."
   The architect sends the implementer back once the merge lands; the implementer watches the