@sjawhar/pi-legion-envoy 1.22.2 → 1.23.1

package/dist/envoy.js

@@ -30279,8 +30279,9 @@ var stateTree = strictObject({
   locator: stateTreeLocator.optional()
 });
 var stateGate = strictObject({
-  designAskId: nonEmptyString.optional(),
-  designApproved: nonEmptyString.optional()
+  artifactId: nonEmptyString,
+  latestVersion: number2().int().positive(),
+  approvedVersion: number2().int().positive().optional()
 });
 var stateRole = strictObject({
   role: nonEmptyString,
@@ -30422,7 +30423,11 @@ var LegionDaemonApi = {
     response: object({})
   },
   GatesRegister: {
-    request: architectCapability.extend({ issue: nonEmptyString, askId: nonEmptyString }),
+    request: architectCapability.extend({
+      issue: nonEmptyString,
+      artifactId: uuid2(),
+      version: number2().int().positive()
+    }),
     response: object({})
   },
   Grant: {
@@ -32629,7 +32634,7 @@ ${trailer.join(`
       const result = await client.requestApproval(resolved.artifact.id, { actor });
       if (result.ask === null) {
         return {
-          text: `${resolved.artifact.name} is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
+          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
           details: {
             ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
             artifact: resolved.artifact.id,
@@ -32639,7 +32644,7 @@ ${trailer.join(`
       }
       const details = await askResultDetails(client, result.ask, resolved);
       return {
-        text: `Approval requested for ${resolved.artifact.name} at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
+        text: `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
       };
     }

package/dist/legion.js

@@ -30279,8 +30279,9 @@ var stateTree = strictObject({
   locator: stateTreeLocator.optional()
 });
 var stateGate = strictObject({
-  designAskId: nonEmptyString.optional(),
-  designApproved: nonEmptyString.optional()
+  artifactId: nonEmptyString,
+  latestVersion: number2().int().positive(),
+  approvedVersion: number2().int().positive().optional()
 });
 var stateRole = strictObject({
   role: nonEmptyString,
@@ -30422,7 +30423,11 @@ var LegionDaemonApi = {
     response: object({})
   },
   GatesRegister: {
-    request: architectCapability.extend({ issue: nonEmptyString, askId: nonEmptyString }),
+    request: architectCapability.extend({
+      issue: nonEmptyString,
+      artifactId: uuid2(),
+      version: number2().int().positive()
+    }),
     response: object({})
   },
   Grant: {
@@ -30796,9 +30801,12 @@ var LIFECYCLE_STATUSES2 = [
 function isLifecycleStatus(value) {
   return LIFECYCLE_STATUSES2.includes(value);
 }
+function isDispatchArtifactId(value) {
+  return LegionDaemonApi.GatesRegister.request.shape.artifactId.safeParse(value).success;
+}
 var LEGION_OP_FIELDS = {
   set_status: ["issue", "status"],
-  register_gate: ["issue", "askId"],
+  register_gate: ["issue", "artifactId", "version"],
   release_wave: ["issues"],
   escalate: ["kind", "context"],
   spawn_worker: ["issue", "role", "task"]
@@ -30809,7 +30817,8 @@ function legionToolSchema(pi) {
     op: z.enum(["set_status", "register_gate", "release_wave", "escalate", "spawn_worker"]),
     issue: z.string().optional(),
     status: z.enum(LIFECYCLE_STATUSES2).optional(),
-    askId: z.string().optional(),
+    artifactId: z.string().optional(),
+    version: z.number().optional(),
     kind: z.enum(["re-file", "capacity", "cross-tree"]).optional(),
     context: z.unknown().optional(),
     issues: z.array(z.string()).optional(),
@@ -30823,7 +30832,7 @@ function createLegionTool(deps) {
   return {
     name: "legion",
     label: "legion",
-    description: "Perform a Legion lifecycle write through the Legion daemon. " + `spawn_worker's response "status" means: "spawned" \u2014 a fresh pane just opened and is ` + 'running now; "resumed" \u2014 an existing worker was prompted directly over its live socket, ' + "or (if its boot has not confirmed yet) its task was recorded to deliver once that boot " + 'completes; "queued" \u2014 the running-worker cap is full, the task was recorded and this ' + 'role will start on its own once a slot frees. Never re-spawn a role after "resumed" or ' + '"queued" \u2014 wait for the worker-started notification instead.',
+    description: "Perform a Legion lifecycle write through the Legion daemon. " + "register_gate records the root spec document a human must approve: `artifactId` is the " + "document id (a UUID) and `version` the version number, both copied from the `artifact` and " + "`version` fields of dispatch_request_approval's result \u2014 never the slug or file name you " + "passed to that tool. " + `spawn_worker's response "status" means: "spawned" \u2014 a fresh pane just opened and is ` + 'running now; "resumed" \u2014 an existing worker was prompted directly over its live socket, ' + "or (if its boot has not confirmed yet) its task was recorded to deliver once that boot " + 'completes; "queued" \u2014 the running-worker cap is full, the task was recorded and this ' + 'role will start on its own once a slot frees. Never re-spawn a role after "resumed" or ' + '"queued" \u2014 wait for the worker-started notification instead.',
     defaultInactive: true,
     parameters: legionToolSchema(pi),
     execute: async (_id, parameters, _signal, _onUpdate, context) => {
@@ -30861,15 +30870,25 @@ function createLegionTool(deps) {
             });
             return jsonSuccess({});
           }
-          case "register_gate":
+          case "register_gate": {
+            const version = parameters.version;
+            if (typeof version !== "number" || !Number.isSafeInteger(version) || version <= 0) {
+              throw new Error("register_gate requires a positive integer version");
+            }
+            const artifactId = stringInput("artifactId");
+            if (!isDispatchArtifactId(artifactId)) {
+              throw new Error(`register_gate requires artifactId to be the document id (a UUID) from dispatch_request_approval's result, not "${artifactId}"`);
+            }
             await daemon.gatesRegister({
               tree: architect.tree,
               sessionId,
               secret: architect.secret,
               issue: stringInput("issue"),
-              askId: stringInput("askId")
+              artifactId,
+              version
             });
             return jsonSuccess({});
+          }
           case "release_wave": {
             const issues = parameters.issues;
             if (!Array.isArray(issues) || !issues.every((issue) => typeof issue === "string")) {
@@ -33045,7 +33064,7 @@ ${trailer.join(`
       const result = await client.requestApproval(resolved.artifact.id, { actor });
       if (result.ask === null) {
         return {
-          text: `${resolved.artifact.name} is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
+          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
           details: {
             ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
             artifact: resolved.artifact.id,
@@ -33055,7 +33074,7 @@ ${trailer.join(`
       }
       const details = await askResultDetails(client, result.ask, resolved);
       return {
-        text: `Approval requested for ${resolved.artifact.name} at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
+        text: `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
       };
     }

package/dist/skills/legion-architect/SKILL.md

@@ -33,7 +33,8 @@ separate coordinator to finish necessary work.
   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 `dispatch_ask` answered `Approve`, not a label. Never attempt to apply a label.
+  is a human approving the root spec document at a version in Dispatch, requested with
+  `dispatch_request_approval` — not a label and not an ask. Never attempt to apply a label.
 - Deferring necessary work is failure. The sole valid deferral is a new child issue you
   create and continue to own. Re-file a genuinely independent child through the
   controller rather than treating it as an abandoned dependency.
@@ -87,34 +88,51 @@ adoption/decomposition and waves, acceptance criteria, and the integration test
 "spec" artifact beside it (`dispatch_artifact` with the primary document's name replaces the
 human's document; do not do that). Both readers described in
 [Writing for the human](../dispatch/SKILL.md#writing-for-the-human) must be able to follow it.
-When the config-armed root design gate applies, run this exact sequence **before any
-Legion-role spawn**, including a sub-architect:
+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 any Legion-role spawn**, including a sub-architect:
 
 ```text
 dispatch_doc_edit({ issue: "<root issue>", ... })   // extend the primary document in place
-askId = dispatch_ask({
+result = dispatch_request_approval({ issue: "<root issue>" })   // the primary document by default
+legion({
+  op: "register_gate",
   issue: "<root issue>",
-  question: "<what is true today, in one sentence> <what will be true when this lands, in one sentence> <how: one issue or N child issues, and what the first step is> I recommend Approve because <one reason>.",
-  options: [
-    { label: "Approve", description: "Work starts as described; the first worker is spawned now." },
-    { label: "Hold", description: "Nothing starts; reply on the issue with what should change first." },
-  ]
+  artifactId: result.details.artifact,   // the document id, a UUID such as 4e0aca36-77b3-43bd-96cf-d58890ae64e4
+  version: result.details.version,       // the version number the human is asked to approve
 })
-legion({ op: "register_gate", issue: "<root issue>", askId })
 ```
 
-Both options are required: a question with only `Approve` is not a decision. The whole ask is
-read on a phone by someone who has not read the code: no file paths, line numbers, document
-versions, or role tokens in it. Sami, 2026-09-12, on a gate ask that broke this rule: "I have no
-idea what the fuck you're talking about."
-
-Then park. Do not release a wave or spawn a Legion role until a later delivered wake
-shows `design-approved` on the root. On a deployment whose design gate is off
-(`gates.design: off` in its `legion.yaml`), the daemon satisfies the gate as you register it
-and `design-approved` arrives immediately — proceed. The daemon then closes the ask on Dispatch
-(you will see `ask.resolved` for it); that is expected and needs nothing from you. Approval
-covers the entire tree: later waves, re-scopes, and integration-failure children do not repeat
-this sequence.
+`dispatch_request_approval` opens a system question on the document with the fixed options
+`Approve` and `Request changes`; a human answers it from the Inbox or approves from the
+document's own header. Never open a `dispatch_ask` with an `Approve` option yourself: an
+ordinary question is not a gate and the daemon ignores its answer. Copy `artifactId` and
+`version` from the result of `dispatch_request_approval` — its text reads "Approval requested for
+spec.md (document id <UUID>) at version <N>" 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 a request is open returns the same open request, so it
+is safe to repeat. If its text instead reads "spec.md (document id <UUID>) is already approved at
+version <N>" — a human approved from the document header before you asked — still call
+`register_gate` with that id and version: the daemon reads the approval from Dispatch as it
+registers, opens the gate, and delivers `design-approved` at once. The same read covers a human
+who answers the question between your `dispatch_request_approval` and `register_gate` calls, so
+an approval is never lost to timing; you never approve anything yourself.
+
+Then park. Do not release a wave or spawn a Legion role until a later delivered wake shows
+`design-approved` on the root. On `design-changes-requested`, revise the spec (a new version of
+the primary document), call `dispatch_request_approval` again — it re-opens the request at the
+new version — and stay parked. Approval is pinned to the spec version: editing the root spec
+after approval closes the gate again with no wake (you made the edit, or the `artifact.version`
+event on your issue tells you), so call `dispatch_request_approval` again, and release no new
+wave and spawn no new role until the next `design-approved` arrives — work already in flight
+continues. Later waves, re-scopes, and integration-failure children that leave the root spec
+untouched need no new approval, and a child issue's spec is never gated: the root approval covers
+the tree.
 
 ## 2. Children in flight
 
@@ -186,13 +204,13 @@ legion({
   op: "spawn_worker",
   issue: "LEGION-40",
   role: "implementer",
-  task: "Run the legion-retro skill now. Capture durable learnings and post the issue comment; do not create a .legion handoff file."
+  task: "Run the legion-retro skill now. Capture durable learnings and post the retro message on the Dispatch issue with dispatch_message; do not create a .legion handoff file."
 })
 ```
 
 Wait for the implementer to report its durable retro result. Retro output is
-`docs/solutions/` plus an issue comment; it must not create a `.legion` file or rewrite
-the reviewer-approved head after cleanup.
+`docs/solutions/` plus one `dispatch_message` on the issue; it must not create a `.legion`
+file or rewrite the reviewer-approved head after cleanup.
 
 ## 6. Architect sign-off and merge
 
@@ -261,6 +279,8 @@ corresponding lifecycle procedure.
 | `child-closed` | Read the child completion and remaining open children. Re-scope or close obsolete open work; release an appropriate next wave, or await `children-complete`. |
 | `children-complete` | Execute steps 3–4: parent integration verification; failures become a new child wave, success advances to review and retro. |
 | `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, call `dispatch_request_approval` again, and stay parked; the gate is closed. |
 | `phase-complete` | Payload `{type:"phase-complete", issue, role, summary}`. May arrive live or via `catchup-overseer`'s `phaseCompletions`. Read the committed handoff for that phase, then spawn the next phase's owner, or `spawn_worker` on the same role again to resume it with corrections if the handoff shows unresolved gaps. A `reviewer` completion whose GitHub review is `CHANGES_REQUESTED` (the daemon returns the issue's Dispatch status to `in_progress` for this, on the reviewer's completion and again when you spawn the corrective implementer unless the daemon already knows the issue is `in_progress`) means `spawn_worker` the **implementer** again with the review findings — thread URLs and blocking items — as its task, then route back through tester and reviewer in order; never `spawn_worker` the reviewer directly off this wake and never proceed to retro on this verdict. A reviewer completion with an `APPROVED` review proceeds to retro (step 5). A `reviewer` completion after a conflict-forced rebase whose review body names an unchanged fingerprint is a confirmation, not a round: if retro already completed, `spawn_worker` the merger; otherwise resume the step you were on. |
 | `worker-queued` | Payload `{type:"worker-queued", issue, role}`. The deployment's worker cap is full; this role's spawn is queued. Do not respawn or retry — wait for `worker-started`. |
 | `worker-started` | Payload `{type:"worker-started", issue, role}`. A previously queued role has been promoted and is now running. Treat it exactly as a normal spawn: resume tracking that role's live session. |
@@ -270,7 +290,7 @@ corresponding lifecycle procedure.
 | `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The merge queue landed the PR. This is your cue for step 7: post the sign-off comment naming that merge commit and set the issue `done`. Nothing else follows a merge. |
 | `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 gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. |
+| `catchup-overseer` | Verify its gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. `gates[LEGION_TREE].open` is the design gate's current state: `true` means the root spec is approved at its current version and you may spawn; `false` (or no `open` key, meaning no gate is registered) means the sequence in section 1 still applies. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. |
 | `worker-died` | Payload `{type:"worker-died", issue, role}`. The daemon probed and retried this role's worker through `MAX_LAUNCH_FAILURES` attempts and could not confirm a boot — never a raw-event replay or a silent revive. Reassess the work and `spawn_worker` again for the role (it resumes the same agent via `--resume` if a session file survived) or reassign it if the failure looks environmental, not agent-specific. |
 | `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |
 

package/dist/skills/legion-controller/SKILL.md

@@ -129,7 +129,11 @@ on stale entries until their source artifact explains the anomaly.
 ## Mentions
 
 Read the mention and its artifact. Answer it when it asks the controller for triage or
-human-facing information. Otherwise resolve the authoritative 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.
+human-facing information. A human asking how to let a root proceed past its design gate
+approves the root issue's spec document in Dispatch — the `Approve` control in the document's
+header, or the approval question the architect's request opened in the Inbox. The controller
+never opens a gate and there is no operator command for it; a project that does not want the
+gate at all runs `gates.design: off` in its `legion.yaml`. Otherwise resolve the authoritative
+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.
 

package/dist/skills/legion-retro/SKILL.md

@@ -17,7 +17,8 @@ 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.
-3. Run this retro: commit durable learnings to `docs/solutions/` and post the issue comment.
+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.
 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 —
@@ -66,18 +67,22 @@ date: YYYY-MM-DD
 status: active
 module: affected-module
 related_issues:
-  - "owner/repo#123"
+  - "LEGION-123"      # the Dispatch issue
+  - "owner/repo#456"  # the pull request
 ---
 ```
 
 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 an issue comment naming
-the documents and the one-to-three most useful takeaways. The comment must carry this revived
-implementer's structured attribution footer with `phase` set to `retro`:
+that branch. 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 and the
+one-to-three most useful takeaways. The message must carry this revived implementer's structured
+attribution footer with `phase` set to `retro`; the body is capped at 2,000 characters:
 
-```bash
-legion gh -- issue comment <issue-number> \
-  --body $'## Retro Complete
+```ts
+dispatch_message({
+  issue: "<KEY>",
+  body: `## Retro Complete
 
 **Learnings documented in:**
 - docs/solutions/<path>.md
@@ -85,11 +90,11 @@ legion gh -- issue comment <issue-number> \
 **Key takeaways:**
 - <reusable lesson>
 
-<!-- legion: {"session":"<session-id>","phase":"retro"} -->' \
-  --repo <owner>/<repo>
+<!-- legion: {"session":"<session-id>","phase":"retro"} -->`,
+})
 ```
 
-The issue comment and `docs/solutions/` commit are the only retro outputs. Never write a
+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 `legion handoff complete` alone (its
 summary: two sentences for the architect) — no `legion handoff write`.
@@ -100,7 +105,7 @@ 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 learning documents and issue comment both exist.
+- The learning documents and the Dispatch message both exist.
 - No `.legion` file was created or modified by retro.
 - The fresh-eyes analysis was considered alongside the implementer's context.
 - The merger remains a subsequent step, not work performed by retro.

package/dist/skills/legion-worker/SKILL.md

@@ -152,22 +152,29 @@ that execs `legion gh -- "$@"`, so `gh …` and `legion gh -- …` are the same
 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
 refuses `pr merge` (and a raw `gh api …/merge`): no worker role merges a pull request — the merge
-queue does, under its own authority. The credential reaches `legion` through the file
-`$LEGION_GRANT_FILE` names, written before each of your bash commands by the extension; never
-`cat`, `echo`, copy, or `export` it — `legion credential`, `legion gh`, `jj git push`, and
-`legion handoff complete` read it themselves. The file is the pane's, not the command's: a `task`
-subagent, an `eval` subprocess, or a background job in your pane reads the grant your last bash
-command minted, so its `legion gh` or `jj git push` succeeds only within 60 seconds of that call
-and 403s afterwards — a timing artifact, not a broken credential; run credentialed commands from
-your own bash calls.
+queue does, under its own authority. It also refuses every GitHub-issue write — the `issue`
+subcommand's `comment`, `create`, `edit`, `close`, `reopen`, `delete`, `pin`, `unpin`, `transfer`,
+`lock`, `unlock`, and `develop`, and any raw `gh api` call to an `/issues` path whose method is not
+GET (an explicit `-X`, or the POST that `-f`/`-F`/`--input` imply; pull-request conversation
+comments live on that path too, so edit them with `gh pr comment`) — printing
+`Legion issues live on Dispatch; use dispatch_message or dispatch_comment on <your LEGION_ISSUE>`:
+Legion never reads or writes a GitHub issue (LEGION-78). `pr comment`, `pr review`,
+`api …/pulls/…`, `api graphql`, and issue reads are unaffected. The credential reaches `legion`
+through the file `$LEGION_GRANT_FILE` names, written before each of your bash commands by the
+extension; never `cat`, `echo`, copy, or `export` it — `legion credential`, `legion gh`,
+`jj git push`, and `legion handoff complete` read it themselves. The file is the pane's, not the
+command's: a `task` subagent, an `eval` subprocess, or a background job in your pane reads the
+grant your last bash command minted, so its `legion gh` or `jj git push` succeeds only within 60
+seconds of that call and 403s afterwards — a timing artifact, not a broken credential; run
+credentialed commands from your own bash calls.
 
 ## GitHub PR comment attribution
 
 Append this exact structured footer to **every** pull-request comment and review that this
 phase posts on GitHub. It preserves session provenance on the artifact itself so work stays
 attributable to the session that produced it. Dispatch comments carry session provenance
-natively through their own `actor`/`origin` fields; this footer is only for GitHub PR
-artifacts:
+natively through their own `actor`/`origin` fields; this footer is for GitHub PR artifacts and
+for the retro's Dispatch message (`skills/legion-retro`):
 
 ```html
 <!-- legion: {"session":"<session-id>","phase":"<phase>"} -->
@@ -220,7 +227,7 @@ PR opens, and every later phase keeps it current rather than replacing it:
 ```
 ## Verification
 
-**CI:** `pr-checks-result` run <run-id> — success at <head-sha>.
+**CI:** `Tests` run <run-id> — jobs lint, pr-title, typecheck, test all success at <head-sha>.
 
 **Threads:** <n> resolved, 0 unresolved. Each disposed individually, never in bulk:
 - Thread <id>: fixed in <commit-sha> — <one line>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "1.22.2",
+  "version": "1.23.1",
   "type": "module",
   "omp": {
     "extensions": [
@@ -12,7 +12,7 @@
     ]
   },
   "legion": {
-    "daemonApiVersion": 1
+    "daemonApiVersion": 2
   },
   "repository": {
     "type": "git",