@sjawhar/opencode-legion-envoy 3.10.1 → 3.11.1

package/dist/src/server.js

@@ -13949,6 +13949,7 @@ var ISSUE_STATUSES = [
   "retro",
   "done"
 ];
+var ISSUE_ROUTE_STATUSES = ["live", "no_holder", "unknown"];
 var DOC_EDIT_OPS = [
   "replace",
   "delete",
@@ -14255,8 +14256,8 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_issues",
-    example: { project: "AGENTC", priority: [0, 1] },
-    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, and open-ask count, so you can see backlog shape without " + "opening every issue. Optionally filter by status, parent, label, priority, or how recently it " + "changed; priority takes one or more of 0-3 (P0-P3) and null for an issue with no priority, so " + "an owner's P0/P1 audit is priority [0, 1]. Do not use it to search by keyword or phrase; " + "dispatch_search remains the keyword surface. Rows are capped at limit (default 50, max 250), " + "applied to the response here, not by the server.",
+    example: { project: "AGENTC", route_status: "no_holder" },
+    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, open-ask count, and route with whether it reaches anyone, " + "so you can see backlog shape without opening every issue. Optionally filter by status, parent, " + "label, priority, route status, or how recently it changed; priority takes one or more of 0-3 " + "(P0-P3) and null for an issue with no priority, so an owner's P0/P1 audit is priority [0, 1]. " + 'route_status "no_holder" lists every open issue whose route names a role nobody holds or a ' + "session that is not running at the moment of the read, whatever its priority. A restarting " + "session is absent for minutes, so an issue is unowned only when a read ten minutes later agrees. " + "Do not use it to search by keyword or phrase; dispatch_search remains the keyword surface. " + "Rows are capped at limit (default 50, max 250), applied to the response here, not by the server.",
     arguments: (z2) => ({
       project: z2.string().describe("Project key to list issues from."),
       status: z2.enum(ISSUE_STATUSES).describe("Optional lifecycle status filter.").optional(),
@@ -14264,6 +14265,7 @@ var dispatchToolSpecs = [
       label: z2.string().describe("Optional label filter.").optional(),
       priority: z2.array(z2.number({ int: true, min: 0, max: 3 }).nullable(), { min: 1, max: 5 }).describe("Optional priority filter: one or more of 0 (P0, highest) through 3 (P3, lowest), and null " + "for an issue with no priority; an issue matching any listed value is returned.").optional(),
       updated_since: z2.string().describe("Optional RFC3339 timestamp; only issues updated at or after it.").optional(),
+      route_status: z2.enum(ISSUE_ROUTE_STATUSES).describe("Optional: only open issues whose route is in this state. live: a running session holds " + "the role or is the routed session. no_holder: nobody running holds the role, or the " + "session is not running, right now. unknown: the Envoy listener did not answer.").optional(),
       limit: z2.number({ int: true, min: 1, max: 250 }).describe("Maximum rows, 1-250; default 50.").optional()
     })
   },
@@ -16185,6 +16187,20 @@ async function liveSessionTitles(client, needed) {
 function holdsSession(claim) {
   return claim?.actor.kind === "session";
 }
+function routeHeldBySession(issue2) {
+  return issue2.route_status === "live" && issue2.route?.startsWith("role:") === true;
+}
+function routeText(issue2, titles) {
+  if (issue2.route === null)
+    return "none";
+  const holder = issue2.route_holder ?? null;
+  const reach = {
+    live: routeHeldBySession(issue2) && holder !== null ? ` (held by ${titles?.get(holder) ?? holder})` : "",
+    no_holder: issue2.route.startsWith("role:") ? " (nobody holds it right now)" : " (that session is not running right now)",
+    unknown: " (the Envoy listener did not answer, so whether it reaches anyone is unknown)"
+  };
+  return issue2.route + (issue2.route_status == null ? "" : reach[issue2.route_status]);
+}
 function issueSummary(issue2, events, references, graph, titles) {
   const asks = issue2.open_asks;
   const spec = issue2.artifacts?.find((artifact) => artifact.primary);
@@ -16206,7 +16222,7 @@ function issueSummary(issue2, events, references, graph, titles) {
     ...issue2.priority === null ? [] : [`Priority: P${issue2.priority}`],
     `Labels: ${issue2.labels.length === 0 ? "none" : issue2.labels.join(", ")}`,
     componentsLine(issue2.components),
-    `Route: ${issue2.route ?? "none"}`,
+    `Route: ${routeText(issue2, titles)}`,
     ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
     "Open asks:",
     ...asks.length === 0 ? ["- none"] : asks.map((ask) => `- ${ask.id}: ${ask.question}`),
@@ -16718,6 +16734,7 @@ async function executeDispatchTool(input) {
       const label = optionalString(args, "label");
       const priority = optionalPriorityFilter(args, "priority");
       const updatedSince = optionalString(args, "updated_since");
+      const routeStatus = optionalString(args, "route_status");
       const limit = Math.min(Math.max(optionalNumber(args, "limit") ?? 50, 1), 250);
       const issues = await client.listIssues({
         project,
@@ -16725,7 +16742,8 @@ async function executeDispatchTool(input) {
         ...parent === undefined ? {} : { parent },
         ...label === undefined ? {} : { label },
         ...priority === undefined ? {} : { priority },
-        ...updatedSince === undefined ? {} : { updated_since: updatedSince }
+        ...updatedSince === undefined ? {} : { updated_since: updatedSince },
+        ...routeStatus === undefined ? {} : { route_status: routeStatus }
       });
       const rows = issues.slice(0, limit).map((row) => ({
         key: row.key,
@@ -16736,13 +16754,16 @@ async function executeDispatchTool(input) {
         labels: row.labels ?? [],
         open_asks: row.open_asks,
         claim: row.claim ?? null,
+        route: row.route ?? null,
+        route_status: row.route_status ?? null,
+        route_holder: row.route_holder ?? null,
         updated_at: row.updated_at
       }));
       const titles = await liveSessionTitles(client, rows.some((row) => holdsSession(row.claim)));
       return {
         text: rows.length === 0 ? `No issues in ${project}.` : [
           `${rows.length} ${rows.length === 1 ? "issue" : "issues"} in ${project}` + (issues.length > rows.length ? ` (showing ${rows.length} of ${issues.length})` : ""),
-          ...rows.map((row) => `${row.key} [${row.status}]${row.priority === null ? "" : ` P${row.priority}`} ${row.title}` + (row.open_asks === 0 ? "" : ` \xB7 ${row.open_asks} open ${row.open_asks === 1 ? "ask" : "asks"}`) + (row.claim === null ? "" : ` \xB7 claimed by ${claimText(row.claim, titles)}`))
+          ...rows.map((row) => `${row.key} [${row.status}]${row.priority === null ? "" : ` P${row.priority}`} ${row.title}` + (row.open_asks === 0 ? "" : ` \xB7 ${row.open_asks} open ${row.open_asks === 1 ? "ask" : "asks"}`) + (row.claim === null ? "" : ` \xB7 claimed by ${claimText(row.claim, titles)}`) + (row.route === null || row.route_status === "live" || row.route_status === null ? "" : ` \xB7 route ${routeText(row)}`))
         ].join(`
 `),
         details: { issues: rows }
@@ -17178,7 +17199,7 @@ ${trailer.join(`
       const [references, graph, titles] = await Promise.all([
         referencesPromise,
         graphSections(client, dispatchIssueRef(read.issue.key)),
-        liveSessionTitles(client, holdsSession(read.issue.claim))
+        liveSessionTitles(client, holdsSession(read.issue.claim) || routeHeldBySession(read.issue))
       ]);
       return {
         text: issueSummary(read.issue, read.events, references, graph, titles),

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -286,13 +286,14 @@ distinction from the named issue, citing it (`dispatch://KEY`), for whoever read
 
 To see the shape of a project rather than find a phrase, list its issues:
 ```ts
-dispatch_issues({ project, status?, parent?, label?, priority?, updated_since?, limit? })
+dispatch_issues({ project, status?, parent?, label?, priority?, route_status?, updated_since?, limit? })
 ```
 Each row carries the issue key, title, status, priority, parent, labels, its open-ask count, and
 when it last changed — a roadmap or backlog pass without opening every issue. Filter with `status`
 (a lifecycle status), `parent` (one issue's children), `label`, `priority` (a list of `0`–`3`, with
-`null` for an issue with no priority: `[0, 1]` is every P0 and P1), or `updated_since` (an RFC3339
-timestamp, for "what moved this week"). `limit` caps the rows at 50 by default and 250 at most.
+`null` for an issue with no priority: `[0, 1]` is every P0 and P1), `route_status` (below), or
+`updated_since` (an RFC3339 timestamp, for "what moved this week"). `limit` caps the rows at 50 by
+default and 250 at most.
 
 This is not search: it matches no text. Use `dispatch_search` for a keyword or phrase, and
 `dispatch_issues` when you want every issue in a project and its current state.
@@ -311,7 +312,13 @@ and is not re-staffed. A todo with a finished spec reads as queued work that nob
 (LEGION-173 sat in todo for two weeks with a complete spec; AGENTC-1010's v4 plan sat in backlog
 with nobody building it).
 
-The audit finds three shapes:
+A close that says the defect cannot happen cites the code that makes it impossible. An issue
+closed because a rewrite forecloses it names the file and line in the rewrite that does so; a
+close that cannot name one is not foreclosed, it is unread. The cheapest way for a rewrite to reach
+parity is to port the code, defect included: LEGION-211's bare `git worktree prune`, filed against
+the TypeScript daemon, had been ported into the Go coordinator and was live in production.
+
+The audit finds four shapes:
 
 - **Unstaffed work.** A plan or measurement exists, and no one is building it.
 - **Unrecorded delivery.** An issue not yet in `testing` or `done`, claimed or not, has a merged PR
@@ -321,6 +328,25 @@ The audit finds three shapes:
   sits in backlog (OPS-132, done by hand on every migration merge). It leaves no plan and no PR to
   find; the tell is your own messages. Doing something by hand more than once means an issue is
   wearing the wrong status.
+- **Unreachable route.** An open issue whose route names a role nobody holds, or a session that is
+  not running, reaches nobody, whatever its priority, and the priority filter above never finds
+  it. List it on its own:
+  ```ts
+  dispatch_issues({ project, route_status: "no_holder", limit: 250 })
+  ```
+  Each row reads `route role:sre (nobody holds it right now)` or `route session:<id> (that session
+  is not running right now)`. That is one read of the listener, and one read is a restart gap as
+  often as a vacancy: an agent box that restarts or resumes keeps the session id, but the session
+  is absent from the listener for minutes, and its role with it. On 2026-09-27, 58 of 63 session
+  routes one read showed as unreachable pointed at a single session that was moving between boxes.
+  So a route is unowned only when it is `no_holder` on two reads at least ten minutes apart: list
+  again after ten minutes and act on the issues both lists name. Confirm with the second
+  `dispatch_issues` read, not `envoy_role_get`: a role lookup releases the claim of a holder whose
+  session is absent from the registry as it answers. Then staff the role, re-route the
+  issue to a live holder, or clear the route and assign it (AGENTC-1065, a P2 production listener
+  503, sat routed to an unheld `role:sre` with no assignee). `route_status: "unknown"` means the
+  listener did not answer, so a route could not be judged; a `no_holder` filter refuses rather
+  than answer an empty list then.
 
 Run the audit as a step of a coordinator's loop, at each checkpoint, not as a habit: these shapes
 are found by running the check, not by noticing them.

package/skills/legion-retro/SKILL.md

@@ -9,6 +9,9 @@ Retro is mandatory for every issue that passed review. The architect revives the
 implementer 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.
+
 ## Merge-gate ordering
 
 Follow this ordering exactly. It keeps the reviewed branch clean while preserving the

package/skills/legion-worker/SKILL.md

@@ -11,6 +11,9 @@ phase gets its own long-lived process against the same jj workspace, run in turn
 the phase assigned to you, report its completion to the architect, and leave the durable
 copy the next phase can trust.
 
+Every path this skill cites (`packages/...`, `docs/...`, `AGENTS.md`) is in sjawhar/legion, the
+Legion repository, which need not be the repository you are working in.
+
 ## Identity, scope, and role
 
 The daemon spawns you as a separate `omp --mode rpc` process (behind `legion worker-shim`,
@@ -102,8 +105,9 @@ committed predecessor handoffs in lifecycle order from `$LEGION_WORKSPACE/.legio
 5. `review.json`
 
 Read only files that precede the assigned phase. Every handoff is validated when it is read:
-`validatePhaseHandoff` (`packages/contracts/src/handoff-schema.ts`) checks the file, and the
-ledger (`packages/daemon/src/handoff/ledger.ts`) treats a file that fails validation as missing.
+`validatePhaseHandoff` (`packages/contracts/src/handoff-schema.ts`) checks the
+file, and the ledger (`packages/daemon/src/handoff/ledger.ts`) treats a file that
+fails validation as missing.
 Undeclared fields pass validation untouched and reach the next worker; a declared field of the
 wrong type fails the whole file, so the `legion` tool's `handoff_read` returns null for that phase.
 Write the phase-specific fields the next phase and the architect need, consistent with what
@@ -161,14 +165,19 @@ assignment, since `jj split`/`jj describe` keep its author). Never set or overri
 `user.name`/`user.email` in any jj or Git scope — not `jj config set`, not `--config`, not
 `git config`: `--config` outranks the pane environment and would put the wrong App back on your
 commits, and the repository-scoped jj config is one file shared by every issue workspace of the
-clone. Before a push, check
+clone. Legion has two GitHub Apps, not one per role: your role's App is the **implement** App
+if you are the implementer or the merger, and the **review** App if you are the planner, tester,
+reviewer, or an architect (in Legion's own deployment, `legion-implementer[bot]` and
+`legion-reviewer[bot]`). A planner's commits authored by the review App are right. Before a push,
+check
 `jj -R "$LEGION_WORKSPACE" log -r 'main@origin..@' -T 'author.email() ++ " | " ++ committer.email() ++ " " ++ description.first_line() ++ "\n"'`
 shows your role's App in both columns **on every commit you made** — not on the whole list:
 earlier phases' commits are legitimately authored by their own role's App, and a conflict-forced
 rebase legitimately sets the committer of every rebased commit, other roles' included, to the
-rebaser. A wrong identity on your own commit is a pane-environment problem to report to the
-architect, not something to pin (`docs/solutions/legion/shared-main-repo-hazards-for-concurrent-issue-workspaces.md`,
-Hazard 1). Your session receives the credential capability it needs; invoke GitHub through the
+rebaser. A wrong identity on your own commit, the other App or none, is a pane-environment
+problem to report to the architect, not something to pin
+(`docs/solutions/legion/shared-main-repo-hazards-for-concurrent-issue-workspaces.md`, Hazard 1).
+Your session receives the credential capability it needs; invoke GitHub through the
 credential helper:
 
 ```bash
@@ -225,8 +234,8 @@ legion gh -- pr comment <pr-number> \
 
 The plan lives in `.legion/plan.json` and the Dispatch issue document; never commit a plan or spec file to the repository.
 No `docs/plans/*`, `docs/superpowers/plans/*`, or spec markdown goes into the pull request: plan
-and spec content goes into the issue, never into a PR (the root `AGENTS.md`'s `docs/plans/` row
-is human-authored design history, not a Legion artifact). A skill step that says "save the plan
+and spec content goes into the issue, never into a PR (the root `AGENTS.md`
+calls its own `docs/plans/` human-authored design history, not a Legion artifact). A skill step that says "save the plan
 to a file" is satisfied by the handoff write in the completion gate below; the planner's only
 commit is `plan: record handoff`.
 
@@ -652,9 +661,16 @@ This publishes your phase's completion to the architect's role and clears the da
 record of this issue's active phase. Do not add pipeline labels, run a controller loop, or
 invent a different completion protocol — this is the whole contract.
 
-A reviewer's phase ends with its completion, not with its review: submit the review on GitHub
-first, then commit the handoff and complete. 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
+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
+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
+changes naming the failing checks; a request for changes does not wait, since it stands whatever CI says and the
+issue leaves reviewing with it. 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 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.
 
 **A refused completion is information, not a retry loop.** The daemon attributes your report to