@sjawhar/opencode-legion-envoy 8.20.13 → 8.22.0

package/dist/dispatch.js

@@ -13930,6 +13930,7 @@ function dispatchToolSchema(spec, z2, opts) {
   return spec.validation === undefined ? z2.object(shape, schemaOptions) : z2.refineObject(shape, spec.validation.check, spec.validation.refusal ?? spec.validation.message, schemaOptions);
 }
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference. An external reference addresses an existing Dispatch issue, including one linked to that GitHub pull request; only dispatch issue with --external creates a native issue.";
+var BOARD_NEIGHBOUR_REFUSAL = "The server refuses a key that does not exist, one in another project, this issue itself, an empty value, and a pair the board does not hold in that order.";
 var OWNER_REFERENCE = "Exactly one of issue and project is required. An issue is a native KEY or external owner/repo#n reference; a project is a project key such as CORE and addresses an unlinked project document named by artifact.";
 var ASK_QUESTION_CONTRACT = "The question carries the problem the reader recognises and why it matters now, what constrains " + "the answer, and the recommendation with its reason. It asks how to solve the problem or which " + "outcome is wanted; never enumerate choices in the question.";
 var ASK_OPTIONS_CONTRACT = "Options carry the genuinely different approaches. Each option has a label, and its description " + "says what that approach costs.";
@@ -13969,7 +13970,7 @@ var commentValidation = {
   },
   message: `${commentOwner.message} turn requires reply_to_ask.`
 };
-var ISSUE_UPDATE_FIELDS_RULE = "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, components, or repo.";
+var ISSUE_UPDATE_FIELDS_RULE = "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, components, repo, before, or after.";
 var ISSUE_UPDATE_DONE_RULE = "status done requires reason, a non-empty note saying why the issue is closing, posted on the issue before it closes because a closed issue refuses messages, comments, and artifacts";
 var ISSUE_UPDATE_REASON_RULE = "reason goes only with status done";
 var ISSUE_UPDATE_RULE = `${ISSUE_UPDATE_FIELDS_RULE} ${ISSUE_UPDATE_DONE_RULE}; ${ISSUE_UPDATE_REASON_RULE}.`;
@@ -13983,7 +13984,7 @@ function issueUpdateProblem(value) {
     const status = typeof input.status === "string" ? `status ${input.status}` : "an update without status done";
     return `${ISSUE_UPDATE_REASON_RULE}: it is the note posted on the issue as it closes, and ${status} closes nothing. Drop reason, or set status done to close the issue.`;
   }
-  const changesAField = typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string";
+  const changesAField = typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string" || typeof input.before === "string" || typeof input.after === "string";
   return changesAField ? undefined : ISSUE_UPDATE_FIELDS_RULE;
 }
 var messageValidation = {
@@ -14068,10 +14069,10 @@ var dispatchToolSpecs = [
     name: "dispatch_issue_update",
     example: {
       issue: "DSP-1",
-      status: "done",
-      reason: "Shipped in owner/repo#7; verified on the production dashboard."
+      priority: 1,
+      before: "DSP-2"
     },
-    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, or set the repository it targets. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. A closed issue takes only rank, components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it; rank, the board's own order, is not " + "settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, set the repository it targets, or move it on its project's " + "board. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. A closed issue takes only a board move " + "(before, after), components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it. before and after move the issue on " + "its project's board: before puts it above that issue, after below, and both together " + "land it between them. A project's board order is one agent's to keep; in a Legion " + "deployment that is the controller. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE),
       status: z2.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
@@ -14084,7 +14085,9 @@ var dispatchToolSpecs = [
       parent: z2.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional(),
       blocked_by: z2.array(z2.string({ min: 1 }), { max: MAX_ISSUE_BLOCKERS }).describe("Replacement list of issue keys in the same project this issue waits on; [] clears it. Dispatch refuses a dependency cycle.").optional(),
       components: componentsArgument(z2).optional(),
-      repo: z2.string().describe("The repository the issue targets, owner/name, mapped to the issue's project in Settings; an empty string clears it, so the issue inherits its parent's or the project's default again.").optional()
+      repo: z2.string().describe("The repository the issue targets, owner/name, mapped to the issue's project in Settings; an empty string clears it, so the issue inherits its parent's or the project's default again.").optional(),
+      before: z2.string().describe(`Move the issue above this issue on its project's board: an issue key in the same project. With after, the issue lands between the two. ${BOARD_NEIGHBOUR_REFUSAL}`).optional(),
+      after: z2.string().describe(`Move the issue below this issue on its project's board: an issue key in the same project. With before, the issue lands between the two. ${BOARD_NEIGHBOUR_REFUSAL}`).optional()
     }),
     validation: {
       check: (value) => issueUpdateProblem(value) === undefined,
@@ -17805,6 +17808,8 @@ async function executeDispatchTool(input) {
       const parent = optionalString(args, "parent");
       const components = optionalComponents(args, "components");
       const repo2 = optionalString(args, "repo");
+      const rankBefore = optionalString(args, "before");
+      const rankAfter = optionalString(args, "after");
       const priority = optionalPriority(args, "priority");
       const labels = Array.isArray(args.labels) ? args.labels : undefined;
       const blockedBy = Array.isArray(args.blocked_by) ? args.blocked_by : undefined;
@@ -17833,6 +17838,10 @@ async function executeDispatchTool(input) {
       const linked = before.external_links.map((link) => link.url);
       const newLinks = requestedLinks?.filter((url2) => !linked.includes(url2)) ?? [];
       const sentLinks = requestedLinks === undefined ? undefined : requestedLinks.length === 0 ? [] : [...before.external_links, ...newLinks.map((url2) => ({ url: url2 }))];
+      const rank = rankBefore === undefined && rankAfter === undefined ? undefined : {
+        ...rankBefore === undefined ? {} : { before: rankBefore },
+        ...rankAfter === undefined ? {} : { after: rankAfter }
+      };
       let after;
       try {
         after = await client.updateIssue(issueKey, {
@@ -17846,6 +17855,7 @@ async function executeDispatchTool(input) {
           ...components === undefined ? {} : { components },
           ...repo2 === undefined ? {} : { repo: repo2 === "" ? null : repo2 },
           ...sentLinks === undefined ? {} : { external_links: sentLinks },
+          ...rank === undefined ? {} : { rank },
           actor
         });
       } catch (error48) {
@@ -17867,6 +17877,12 @@ async function executeDispatchTool(input) {
         ...title === undefined ? [] : [`title "${after.title}"`],
         ...labels === undefined ? [] : [after.labels.length === 0 ? "labels cleared" : `labels ${after.labels.join(", ")}`],
         ...priority === undefined ? [] : [after.priority === null ? "priority cleared" : `priority -> P${after.priority}`],
+        ...rank === undefined ? [] : [
+          `rank -> ${[
+            ...rankAfter === undefined ? [] : [`after ${rankAfter}`],
+            ...rankBefore === undefined ? [] : [`before ${rankBefore}`]
+          ].join(", ")}`
+        ],
         ...requestedLinks === undefined ? [] : [
           requestedLinks.length === 0 ? "external links cleared" : newLinks.length === 0 ? `already linked ${requestedLinks.join(", ")} ${linkCount}` : `linked ${newLinks.join(", ")} ${linkCount}`
         ],

package/dist/src/server.js

@@ -13787,6 +13787,7 @@ var SESSION_ID_PATTERN = "[^/?#\\s\\p{Z}\\p{Cc}<>\"'`\\[\\]|]+";
 var sessionIdOnly = new RegExp(`^${SESSION_ID_PATTERN}$`, "u");
 // ../contracts/src/dispatch-tools.ts
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference. An external reference addresses an existing Dispatch issue, including one linked to that GitHub pull request; only dispatch issue with --external creates a native issue.";
+var BOARD_NEIGHBOUR_REFUSAL = "The server refuses a key that does not exist, one in another project, this issue itself, an empty value, and a pair the board does not hold in that order.";
 var OWNER_REFERENCE = "Exactly one of issue and project is required. An issue is a native KEY or external owner/repo#n reference; a project is a project key such as CORE and addresses an unlinked project document named by artifact.";
 var ASK_QUESTION_CONTRACT = "The question carries the problem the reader recognises and why it matters now, what constrains " + "the answer, and the recommendation with its reason. It asks how to solve the problem or which " + "outcome is wanted; never enumerate choices in the question.";
 var ASK_OPTIONS_CONTRACT = "Options carry the genuinely different approaches. Each option has a label, and its description " + "says what that approach costs.";
@@ -13826,7 +13827,7 @@ var commentValidation = {
   },
   message: `${commentOwner.message} turn requires reply_to_ask.`
 };
-var ISSUE_UPDATE_FIELDS_RULE = "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, components, or repo.";
+var ISSUE_UPDATE_FIELDS_RULE = "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, components, repo, before, or after.";
 var ISSUE_UPDATE_DONE_RULE = "status done requires reason, a non-empty note saying why the issue is closing, posted on the issue before it closes because a closed issue refuses messages, comments, and artifacts";
 var ISSUE_UPDATE_REASON_RULE = "reason goes only with status done";
 var ISSUE_UPDATE_RULE = `${ISSUE_UPDATE_FIELDS_RULE} ${ISSUE_UPDATE_DONE_RULE}; ${ISSUE_UPDATE_REASON_RULE}.`;
@@ -13840,7 +13841,7 @@ function issueUpdateProblem(value) {
     const status = typeof input.status === "string" ? `status ${input.status}` : "an update without status done";
     return `${ISSUE_UPDATE_REASON_RULE}: it is the note posted on the issue as it closes, and ${status} closes nothing. Drop reason, or set status done to close the issue.`;
   }
-  const changesAField = typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string";
+  const changesAField = typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string" || typeof input.before === "string" || typeof input.after === "string";
   return changesAField ? undefined : ISSUE_UPDATE_FIELDS_RULE;
 }
 var messageValidation = {
@@ -13925,10 +13926,10 @@ var dispatchToolSpecs = [
     name: "dispatch_issue_update",
     example: {
       issue: "DSP-1",
-      status: "done",
-      reason: "Shipped in owner/repo#7; verified on the production dashboard."
+      priority: 1,
+      before: "DSP-2"
     },
-    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, or set the repository it targets. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. A closed issue takes only rank, components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it; rank, the board's own order, is not " + "settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, set the repository it targets, or move it on its project's " + "board. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. A closed issue takes only a board move " + "(before, after), components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it. before and after move the issue on " + "its project's board: before puts it above that issue, after below, and both together " + "land it between them. A project's board order is one agent's to keep; in a Legion " + "deployment that is the controller. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE),
       status: z2.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
@@ -13941,7 +13942,9 @@ var dispatchToolSpecs = [
       parent: z2.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional(),
       blocked_by: z2.array(z2.string({ min: 1 }), { max: MAX_ISSUE_BLOCKERS }).describe("Replacement list of issue keys in the same project this issue waits on; [] clears it. Dispatch refuses a dependency cycle.").optional(),
       components: componentsArgument(z2).optional(),
-      repo: z2.string().describe("The repository the issue targets, owner/name, mapped to the issue's project in Settings; an empty string clears it, so the issue inherits its parent's or the project's default again.").optional()
+      repo: z2.string().describe("The repository the issue targets, owner/name, mapped to the issue's project in Settings; an empty string clears it, so the issue inherits its parent's or the project's default again.").optional(),
+      before: z2.string().describe(`Move the issue above this issue on its project's board: an issue key in the same project. With after, the issue lands between the two. ${BOARD_NEIGHBOUR_REFUSAL}`).optional(),
+      after: z2.string().describe(`Move the issue below this issue on its project's board: an issue key in the same project. With before, the issue lands between the two. ${BOARD_NEIGHBOUR_REFUSAL}`).optional()
     }),
     validation: {
       check: (value) => issueUpdateProblem(value) === undefined,

package/package.json

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

package/skills/dispatch/references/issues.md

@@ -9,7 +9,8 @@ Read this to choose, claim or release an issue, or to handle `409 ISSUE_CLAIMED`
 - Hold at most three issues in flight (`in_progress`, `testing`, `needs_review`, `retro`), of any kind, per agent. A child counts on its own. Priorities decide only what you pull next. Past three: push unfinished work, say where in one comment, move it to `backlog` and clear its route.
 - An in-flight issue with no owner goes back to `backlog`. No owner means no claim or route held by a live session, no Dispatch activity in a day, and no PR moving on GitHub. The order keeper sweeps those.
 - Never write the status of an issue with the `legion` label or under one. A status you write on a running Legion root is set back and its architect is told. Only a person in the dashboard, the controller's `set_status`, or the operator stops that tree. On a child, a status out of the flow parks it and stops its workers.
-- Set priority yourself. Never reorder the board: one agent keeps the order. When the top looks wrong, or a priority's next step is not a ready issue, publish to `notifications.role.backlog-order`.
+- Set priority yourself. Never reorder the board: one agent keeps each project's order, and in a Legion deployment that agent is the controller, at `notifications.role.legion-<project>-controller`. When the top looks wrong, or a priority's next step is not a ready issue, publish it there, and say it on the issue where no Legion controller runs.
+- The keeper moves a card with `dispatch issue-update --issue <KEY> --before <OTHER>` or `--after <OTHER>`.
 
 ## Claim the issue before you work it
 
@@ -36,13 +37,13 @@ dispatch claim --issue LEGION-234 --release   # I have stopped; it is free
 ## Priority is yours to set
 
 - `0` (P0, highest) to `3` (P3), `null` clears. Set it on creation and on grooming passes over issues with none. Say what you set and why. The human overrides from the dashboard.
-- A closed issue takes only `rank`, `components`, a reopening status, and an external-links write that adds no link. Reopen first, then set priority, in two commands (`409 ISSUE_CLOSED`).
+- A closed issue takes only a board move (`--before` / `--after`), `components`, a reopening status, and an external-links write that adds no link. Reopen first, then set priority, in two commands (`409 ISSUE_CLOSED`).
 - Labels are optional. Dispatch trims them, keeps their case, and drops case-insensitive duplicates.
 
-## Board rank, priority, and assignee on a read
+## Board rank, priority, and assignee
 
 - Reads carry `rank`, nullable priority, and `assignee`: a lowercase email, or `null`. `dispatch read` prints `Assignee: unassigned` for `null`.
-- Reorder with `PATCH /api/v1/issues/{key}` and `{"rank": {"before": "<key>", "after": "<key>"}}` (either optional, same project). A bearer also sends `"actor": {"kind": "session", "id": "<your session id>"}`, or gets `ACTOR_KIND`.
+- Move a card with `dispatch issue-update --issue <KEY> --before <OTHER>`, which puts it above that issue, `--after <OTHER>`, which puts it below, or both together, which land it between them. The neighbour is an issue of the same project and never the issue itself, and the server refuses a pair the board does not hold in that order. The move rides along with any other change in the same call, and a closed issue takes it.
 
 ## Reading a project's backlog
 

package/skills/legion-architect/SKILL.md

@@ -463,7 +463,9 @@ addressing` line names: a child that looks independent of the tree (the controll
 whether to re-file it as a root of its own, and does so only on their yes), capacity, and a
 cross-tree conflict. A problem outside the tree is a `dispatch ask` you open, never an issue you
 file (`skill://legion-worker/references/findings.md`). Handle everything else in the
-tree. A product, scope, or design decision that needs the human, yours or one a worker escalated,
+tree. A tool a worker cannot get is yours to schedule (`skill://legion-worker/references/tools.md`):
+the image change is a pull request against this repository, never something a worker conjures.
+A product, scope, or design decision that needs the human, yours or one a worker escalated,
 is a decision block you write (section 1 says what one does to the root spec's gate). A standalone
 human to-do may use `dispatch ask`; workers may reach the human directly with it the same way. Do not
 create a wait loop for any wake source.

package/skills/legion-controller/references/backlog-stewardship.md

@@ -1,9 +1,9 @@
 # Backlog stewardship
 
 The controller keeps the Dispatch backlog's facts aligned with the deployment's current weekly
-plan. The plan is the source of the work order and its one-owner map; Dispatch priority and board
-rank are the executable form of that order. The deployment instructions name the weekly-planning
-issue and its `plan-week-*` artifact.
+plan. The plan is the source of the work order and its one-owner map; Dispatch board rank is the
+executable form of that order. The deployment instructions name the weekly-planning issue and its
+`plan-week-*` artifact.
 
 ## Controller routing address
 
@@ -18,12 +18,13 @@ Run this pass on the first turn of every UTC day and after every ruling from a p
 
 1. Read the weekly-planning issue and select its newest `plan-week-*` artifact by its latest
    `artifact.version` event. Read that artifact before changing any issue.
-2. For every current plan line in this deployment's project, make Dispatch's sort order exactly
-   match the line order: set the coarse priority and board rank together so the admission rule
-   (highest priority, then board rank) produces the plan's order. Keep each line's own stated
-   sequence. Do not invent a second order from a title, a stale route, or an instruction.
-   Reorder through Dispatch's board-rank API described in
-   `skill://dispatch/references/issues.md#board-rank-priority-and-assignee-on-a-read`.
+2. For every current plan line in this deployment's project, make the project's board order match
+   the line order exactly: Legion admits waiting roots by board rank alone — unlike the ready order
+   an agent takes its own next issue by, which is priority, then board rank — so board rank is what
+   carries the plan's order. Set the coarse priority too, as the signal people and filters read; it
+   changes no order. Keep each line's own stated sequence. Do not invent a second order from a
+   title, a stale route, or an instruction. Reorder with
+   `dispatch issue-update --issue <KEY> --before <OTHER>` or `--after <OTHER>`.
 3. Reconcile the plan's one-owner map. For each listed owner, verify the named session is live.
    For unowned work, find a suitable live owner with `envoy_sessions` filtered by `title` or `dir`,
    route the issue to that exact session, and tell it what it owns. Routing hands the work to that

package/skills/legion-worker/SKILL.md

@@ -28,6 +28,7 @@ with the `read` tool: a read by filesystem path stops at 300 lines.
 | You review or approve, build the READY packet, or check the merge in production | `skill://legion-worker/references/merge-gate.md` |
 | The issue renames a repository, package, or URL across the codebase | `skill://legion-worker/references/systematic-rename.md` |
 | The issue deletes code, a command, or documentation | `skill://legion-worker/references/cleanup-deletion.md` |
+| Your phase needs a tool — a client, a linter, a CLI — that the image may not carry | `skill://legion-worker/references/tools.md` |
 | You find a problem outside your issue, or the production check fails | `skill://legion-worker/references/findings.md` |
 
 ## Identity, scope, and role
@@ -136,12 +137,11 @@ committed predecessor handoffs in lifecycle order, with the `read` tool from
 4. `review.json`
 
 Read only files that precede the assigned phase. Each was checked against its phase's rules when
-its phase completed (the completion gate below): fields the phase does not declare passed
-untouched and reach the next worker.
-Write the phase-specific fields the next phase and the architect need, consistent with what
-predecessor phases already wrote. The durable copy lives in
-`$LEGION_WORKSPACE/.legion/<issue>/<phase>.json`. If a committed handoff conflicts with memory or a prior
-transcript, the committed file wins: it is the copy that survived.
+its phase completed (the completion gate below): fields the phase does not declare passed untouched
+and reach the next worker. Write the phase-specific fields the next phase and the architect need,
+consistent with what predecessor phases already wrote. The durable copy lives in
+`$LEGION_WORKSPACE/.legion/<issue>/<phase>.json`. If a committed handoff conflicts with memory or a
+prior transcript, the committed file wins: it is the copy that survived.
 
 If your task, prompt, or a message since your last turn begins `Your workspace was recreated…`, read
 your phase's committed handoff and any `.legion/<issue>/workspace-recovered.json`, and reconcile

package/skills/legion-worker/references/tools.md

@@ -0,0 +1,407 @@
+# Getting the tool your work needs
+
+Part of `skill://legion-worker`. Read it the moment your phase needs a tool the worker image may
+not carry — a database client, a linter, a one-off CLI — before you install, download, or vendor
+anything. Every path it cites is in sjawhar/legion.
+
+## The five clients the image already carries
+
+Check this list first: the worker image carries these five from the change that added them onward,
+and they are on a role's `PATH` once its deployment pins a digest at or after that change — a role
+still on an older digest finds none of them. Run `command -v psql redis-cli sqlite3 nc dig` to see
+which you have; those need no runner.
+
+- `psql` — the Dispatch browser suite (`bun run e2e`) resets its database for every spec through
+  `packages/dispatch/e2e/psql.ts`, which `seed.ts` calls, and the local stack (`bun run
+  dispatch:local`, `packages/dispatch/e2e/local-instance.ts`) refuses to start without it on
+  `PATH` — so a role whose change owes that suite can run it.
+- `redis-cli` — no repository of the project speaks Redis today; it is carried anyway, at about a
+  megabyte, because a second image roll costs more than a megabyte.
+- `sqlite3` — a repository's own SQLite fixture or database has no other way to open from a shell,
+  and Oh My Pi's own profile databases (`~/.omp/profiles/legion/agent/agent.db`, `models.db`,
+  `history.db`) are SQLite too. Your session is not one of them: it is `results.jsonl`,
+  `state.json` and `title` under `XDG_STATE_HOME`.
+- `nc` — the reachability check you would otherwise write as an inline Python loop. The name comes
+  from the alternatives system, so ask for `nc`, never `nc.openbsd`.
+- `dig` — how a role whose connection to a service name fails tells "the name does not resolve"
+  from "the packets are dropped".
+
+## Why a sixth is an image change, not an install
+
+Your container is an unprivileged user with no writable system prefix: `/usr/local/bin` and `/opt`
+are read-only, `/home` is read-only too, and `apt-get` cannot take dpkg's lock even to download.
+`$HOME` — `/home/legion`, the one writable directory under that read-only `/home` — is yours to
+write.
+
+```text
+$ apt-get install -d -y postgresql-client
+E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)
+```
+
+So that writable `$HOME`, and the issue's disk, are where an install for yourself would go, and on
+the mechanics the answer is not a flat no: `redis-cli`, `sqlite3` and `dig` did run from an
+extraction prefix under `$HOME` with `LD_LIBRARY_PATH` set, and `psql` did not — Debian's
+`/usr/bin/psql` is a Perl wrapper that loads `PgCommon.pm` through Perl's own search path, which no
+extraction prefix is on. What rules such an attempt out is not the unpacking: it is the next
+section's test ("The test: where it lands, and what it leaves resolving"), and an extraction under
+`$HOME` fails that test's first condition whatever you scope it to, because `/home/legion` is the
+container's own filesystem rather than the issue's volume — the placement `roleEnvironment`
+(`packages/daemon/internal/runtime/sandbox/manifest.go`) exists to move writes off. The sanctioned
+extraction is the harness's: onto the issue's volume, and exported around its own commands and no
+further (the Dispatch e2e stack, below, is the worked case). For everything the five do not cover,
+the one documented step is a pinned run through one of the three package runners the image already
+carries — plus `uv run --with` when what you need is a library rather than a command — and a tool
+no runner reaches is an image change ("When no runner reaches it", below).
+
+## What the withheld capability is, and what it is not
+
+The withheld row reads `installs or configures its own dependencies in the pod: Legion owns its
+dependencies` (`packages/daemon/internal/capabilities/capabilities.go`, ruling
+dispatch://LEGION-200). Read as a sentence on its own, that wording would also forbid `uvx`,
+`bunx --package` and `go run`, each of which fetches a package and writes a cache. It does not, and
+three artefacts in this repository are what draw the line — not a claim about what the ruling meant:
+
+- **What the image ships for a role to use.** `packages/daemon/docker/worker.Dockerfile` installs
+  `uv` and `uvx`, `bun` with its `bunx` link, and the Go toolchain, and the `toolchain` capability
+  row (`packages/daemon/internal/capabilities/capabilities.go`) grants them by name. A runner put
+  in the image deliberately and granted by a capability row is not a route around a withheld one.
+- **What the pod configures for those runners to write.** A role container's environment relocates
+  `UV_CACHE_DIR` and `UV_PYTHON_INSTALL_DIR` (`podkind.go`) and `BUN_INSTALL_CACHE_DIR`, `GOCACHE`
+  and `GOMODCACHE` (`roleEnvironment`, `packages/daemon/internal/runtime/sandbox/manifest.go`)
+  onto the issue's volume, shared by the issue's roles. Legion provisions the caches a pinned run
+  fills; filling them is what they are for.
+- **What Legion itself does at launch.** `installBlock`
+  (`packages/daemon/internal/runtime/sandbox/plugins.go`) renders a `bun add` under
+  `/usr/bin/flock` into that shared bun install cache on every installing launch. Fetching a pinned
+  package at run time is something Legion does, not something it withholds.
+
+So the withheld row is about a dependency **the pod carries**: something that outlives the command
+that created it, and that a later launch or another role's process then resolves *without asking
+for it*.
+
+### The test: where it lands, and what it leaves resolving
+
+An install of your own — an interpreter, a browser, a second toolchain, an extraction prefix — is
+on the sanctioned side when both of these hold: what it writes lands on the issue's own volume,
+under `/legion`, which outlives the pod and is shared by the issue's roles — whether through a
+variable the runtime sets for you there or under a path on that volume your harness names
+itself — but outside the issue's workspace (`$LEGION_WORKSPACE`, under `/legion/workspaces`) and
+the runtime's own directories (`/legion/repos`, `/legion/feed`, `/legion/sessions`); and after
+the command exits nothing else resolves differently. The workspace is excluded because its jj
+working copy tracks every new file, so a root written there is added to the change every role
+shares; the one write into it that is sanctioned is a repository's own dependency install into
+its ignored directories, below. The variables the runtime sets on the volume, where a tool's own
+cache already goes, are
+`XDG_CACHE_HOME` (`/legion/scratch/cache`), `XDG_DATA_HOME`, `XDG_STATE_HOME`, `TMPDIR`, `GOCACHE`,
+`GOMODCACHE`, `BUN_INSTALL_CACHE_DIR`, `UV_CACHE_DIR` (`/legion/uv/cache`) and
+`UV_PYTHON_INSTALL_DIR` (`/legion/uv/python/<issue>`). (`XDG_CONFIG_HOME` is set too and is not
+one of them: it is the pod's shared in-memory volume.) `$HOME` and `/tmp` are not on the volume:
+both are the container's own filesystem.
+
+It is the withheld capability when either condition fails — anything that writes into a
+system prefix, and anything that leaves a toolchain, shim or binary which a later launch or
+another role's process will resolve without asking for it. Between two installs that both land in
+the right place, the test is resolution, not disk, and it reads as scope: a second toolchain
+exported for the commands of your own run — by absolute path, or on a `PATH` your harness's own
+script sets around its own invocations — is sanctioned; the same toolchain left where a later
+launch, another role or a subagent picks it up without naming it is operator setup, whoever typed
+the command.
+
+What each shape leaves resolving:
+
+- A pinned runner run: nothing. `uvx --from httpie@3.2.4 http --version` leaves a cache entry
+  addressed by that coordinate and that version, which the next command reaches only by writing the
+  same pin; no `PATH`, no interpreter and no library search of any other process changes. That is
+  the sanctioned side, and it is the side the forms below are on.
+- A repository's own dependency set: nothing either, which is why the caches are provisioned at
+  all. `uv sync` or `bun install` in your workspace materialises what that project already
+  declares, into that project's own directory, which a process reaches by asking for that project
+  and no other way — and the runtime puts `UV_PYTHON_INSTALL_DIR` and the workspace itself on the
+  issue's volume exactly so a later pod reuses it.
+- An extraction prefix: whatever you leave resolving through it, which is yours to decide. Unpack
+  Debian packages under `$HOME`, export `LD_LIBRARY_PATH` in the shell you go on working in, and
+  you change what every later command in that shell — and every subagent that inherits the
+  environment — resolves `psql` or its libraries to, asked for or not, on a prefix nothing records,
+  pins or rebuilds: that fails both conditions, and it is the withheld capability. The harness
+  below is the shape that passes. The opposite shape is in the tree too, and superseded: telling
+  every subagent to prepend a directory to `PATH` because a subagent's shell starts without it
+  hands over an environment to processes that never named it. That is the difference between
+  standing a harness up and getting yourself a CLI.
+
+The test is about what a command leaves for other processes, never about getting the same bytes
+twice — because a pinned line does not promise the same bytes. What a pin binds is the named
+distribution at that version; its dependency closure is resolved when the command runs. With
+`UV_CACHE_DIR` emptied, `uvx -v --from httpie@3.2.4 http --version` logs `Selecting:
+requests==2.34.2 [compatible]` and resolves `urllib3` and `certifi` from ranges, where the warm run
+prints `3.2.4` at once off the cache that first run filled. When your work needs the closure pinned
+too — a comparison that has to hold across days or across pods — that is a project's own lockfile
+with `uv run` or `bun install` in a workspace, not a one-off runner line.
+
+A pinned run whose tool then installs something of its own — an interpreter, a browser, a second
+toolchain — is where the first condition does the work. `uv run --with pyyaml==6.0.2 --no-project`
+passes both: the wheel lands in `UV_CACHE_DIR`, under `wheels-v6/pypi/pyyaml/6.0.2-…`, and
+`UV_PYTHON_INSTALL_DIR` is never created, because the image's own `python3` served the run. The
+interpreter is the other run: a project whose `.python-version` names an interpreter uv must fetch
+puts about 70 MB under `UV_PYTHON_INSTALL_DIR`, where the issue's next pod finds it, while the
+cache holds no wheel. A browser download passes too, and for Playwright — the browser driver this
+repository's own Dispatch suite installs (`playwright install`, `packages/dispatch`'s
+`e2e:install`) — it passes as it stands, with nothing pointed anywhere: playwright-core resolves
+its browser registry under `XDG_CACHE_HOME`, which the runtime has already put on the issue's
+volume, so the issue's roles share one registry under the exclusive install lock that
+`docs/kubernetes.md` writes down in "Anatomy of a Sandbox pod", the paragraph on sharing the cache
+home — worth reading before an install, for the two things that follow from sharing. Pointing
+`PLAYWRIGHT_BROWSERS_PATH` elsewhere is what costs you: that shared registry, and the lock that
+makes a second role installing at the same time wait rather than race. The condition is for a tool
+whose cache the runtime does not already place — Puppeteer is one, resolving its browser cache to
+`join(homedir(), '.cache', 'puppeteer')` and so to the container's own filesystem whatever
+`XDG_CACHE_HOME` says. For that one, point the tool's own cache variable (`PUPPETEER_CACHE_DIR`
+here) at a directory under one of the paths above yourself, since an unset one leaves the download
+wherever the tool defaults, which is nowhere this runtime chose.
+
+Where it lands is what you pay. Under one of those variables it is on the issue's volume: it
+outlives the pod, and every role of the issue shares it — under every one of those variables but
+`XDG_STATE_HOME`, which is `/legion/scratch/state/<role>`, "the one directory of the issue's
+scratch that is the role's own rather than the issue's" (`roleEnvironment`), because Oh My Pi
+names its browser broker's lock from the state root and an abstract socket name is one name across
+every container of the pod — and a later pod of the issue reuses it. Under `$HOME` —
+`/home/legion`, which no volume is mounted on — it is the container's own filesystem: one copy per
+role, per pod, gone when the role relaunches, and charged to the container's ephemeral-storage
+limit, which is per role and smaller than the volume. Moving exactly these writes off that
+filesystem is what `roleEnvironment` (`packages/daemon/internal/runtime/sandbox/manifest.go`)
+exists for, after GKE Autopilot evicted issue pods that charged their caches to it — so an install
+under `$HOME` fails the first condition and is outside the sanctioned form, however little else it
+changes. The three artefacts above are the whole of that line's ground. Disk is not: every cache is
+already relocated onto the issue's volume, which has the room for them (`docs/kubernetes.md`, "The
+tools a role's own work needs", carries the figure), and a sanctioned install is paid once per
+issue, on the issue's own disk, by the issue's roles together.
+
+**The worked case, and the one a role actually meets: the Dispatch e2e stack.** A change to
+`packages/dispatch` is proved by driving its browser suite, which needs a Postgres with pgvector;
+the image carries a `psql` and no server and no pgvector, and no runner reaches either. The way
+that stack is stood up here is Debian packages unpacked with `dpkg-deb -x` into one root on the
+issue's volume — the five packages and the start sequence are in
+`docs/solutions/testing/the-real-dispatch-stack-runs-inside-a-legion-pod-with-no-postgres-no-docker-and-no-root-INFRA-42.md`,
+and
+`docs/solutions/testing/a-browser-harness-in-an-issue-pod-lives-on-the-issue-volume-INFRA-43.md`
+puts it on the volume, moves the caches with it, and writes it as one idempotent script the next
+role re-runs. That passes both conditions, and the second is the one to get right: export the
+root's `PATH` and `LD_LIBRARY_PATH` around the harness's own commands — `initdb`, `pg_ctl`, the
+server, the Playwright run — rather than into the shell you go on working in. Handing the harness
+to the next role is the same test passed again, and
+`docs/solutions/legion/a-port-held-in-an-issue-pod-is-a-sibling-roles-harness-move-your-run-with-the-five-port-variables-and-your-own-database-and-never-stop-the-holder-LEGION-695.md`
+is the illustration: it leaves the server running and records the `LD_LIBRARY_PATH`, `PATH` and
+`DATABASE_URL` in its handoff's `trickyParts`, so what crosses to the next role is a note that
+role sets deliberately rather than an environment it inherits. The suite shells out to `psql`,
+and `psql` being in the image is what makes that harness work now without your extracting a
+client for yourself at all.
+
+## The three pinned runner forms
+
+- `uvx --from <package>@<version> <command>`, for a Python tool: the distribution you pin and the
+  command you run are named separately, because they are usually different names.
+  `uvx --from httpie@3.2.4 http --version` prints `3.2.4`. Where the project's own name *is* its
+  command's — checked once, never assumed — the short `uvx <name>@<version>` runs it:
+  `uvx ruff@0.14.0 --version` prints `ruff 0.14.0`, in 1.7 s with the uv cache empty and 0.15 s
+  warm. A version that does not exist fails closed, exit 1, naming it: `uvx ruff@99.99.99
+  --version` prints `error: No solution found when resolving tool dependencies`, with `cause:
+  Because there is no version of ruff==99.99.99 …`.
+- `bunx --package <name>@<version> <binary>`, for an npm tool, naming the package and the binary
+  separately because they differ. `bunx --package @biomejs/biome@2.6.3 biome --version` prints
+  `Version: 2.6.3`, in 0.3 s with bun's cache warm; `bunx --package @biomejs/biome@99.99.99 biome
+  --version` fails closed, exit 1, with `error: No version matching "99.99.99" found for specifier
+  "@biomejs/biome" (but package exists)`.
+- `go run <module>@<version>`, for a Go tool. `go run github.com/nats-io/natscli/nats@v0.1.5
+  --version` prints `v0.1.5`, in 7.2 s with the module cache warm and 103 s on a cold module cache
+  — budget for the cold one the first time an issue runs a Go tool. `go run
+  github.com/nats-io/natscli/nats@v99.99.99 --version` fails closed, exit 1, with
+  `go: github.com/nats-io/natscli/nats@v99.99.99: invalid version: unknown revision nats/v99.99.99`.
+
+## When you need a library, not a command
+
+The three forms above run somebody else's command. When what you need is a package available to
+code of your own — PyYAML to read a file, not a CLI — the form is `uv run --with
+<package>==<version> --no-project` ahead of the program you are running:
+
+```text
+$ uv run --with pyyaml==6.0.2 --no-project python -c "import yaml; print(yaml.__version__)"
+Installed 1 package in 12ms
+6.0.2
+```
+
+That whole run is 0.597 s wall, the install included. `--no-project` keeps it off whatever
+`pyproject.toml` happens to sit above your working directory, so it behaves the same wherever you
+type it, and `--with` takes a requirement specifier (`==<version>`), not a runner coordinate
+(`@<version>`). It is on the sanctioned side for the same reason a `uvx` run is: it fills
+`UV_CACHE_DIR` and leaves nothing another process resolves. Reaching for a command runner instead
+is the mistake the next section's `uvx pyyaml@6.0.2 --version` shows — uv installs the project and
+then finds no executable, because a library has none to find.
+
+## Always write the exact coordinate and the exact version
+
+A pin has two halves, and a runner resolves what you asked for only when both are right:
+
+1. **The coordinate** — the registry name the project itself publishes, scope and all:
+   `@biomejs/biome`, not `biome`. The command's name is no evidence of the package's. Take the
+   coordinate from the project's own published installation instructions — its documentation site
+   or its repository's README, reached independently of the registry rather than through the
+   registry entry of a name you guessed. That is the step, and it is the only one that establishes
+   identity. Do it once, before the tool's first use.
+2. **The version** on that coordinate.
+
+Everything a registry can tell you afterwards is corroboration, and it is worth knowing which kind
+each piece is.
+
+**Fields the publisher writes.** `npm view <name> version description repository.url homepage`
+reads what the publisher put in its own `package.json`. npm verifies none of it: a squatter closes
+this check by copying two strings, and a legitimate package that sets no `homepage` reads like a
+squat. Evidence, never proof.
+
+**A check whose evidence the subject controls is not a check.** Carry that past npm: every line
+below the next prompt was written by the party whose identity is in question.
+
+```text
+$ npm view biome version description repository.url homepage
+version = '0.3.3'
+description = 'A simple way to manage environment variables on a per-project basis'
+$ npm view @biomejs/biome version description repository.url homepage
+version = '2.6.3'
+description = 'Biome is a toolchain for the web: formatter, linter and more'
+repository.url = 'git+https://github.com/biomejs/biome.git'
+homepage = 'https://biomejs.dev'
+```
+
+Those two answers are *consistent with* `@biomejs/biome` being the project and `biome` being
+someone else's package. What settles it is biomejs.dev telling you to install `@biomejs/biome` —
+the site you reached without npm's help.
+
+**What a registry can attest.** npm verifies a provenance attestation when it is published, so it
+is the one part of an entry a publisher cannot forge by writing a string. What it proves is *build
+origin*: the attestation binds the artifact to the repository and workflow that built it. Presence
+is not identity — a squat published from its own public Actions workflow carries a genuine
+attestation of its own repository — so the check is to read whose build it names, and compare that
+with the repository the project's own documentation gave you:
+
+```text
+$ npm view @biomejs/biome dist.attestations.url
+https://registry.npmjs.org/-/npm/v1/attestations/@biomejs%2fbiome@2.6.3
+$ curl -s "$(npm view @biomejs/biome dist.attestations.url)" \
+    | jq -r '.attestations[] | select(.predicateType=="https://slsa.dev/provenance/v1") | .bundle.dsseEnvelope.payload' \
+    | base64 -d | jq -r '.predicate.buildDefinition.externalParameters.workflow.repository'
+https://github.com/biomejs/biome
+```
+
+That field is the SLSA v1 predicate's `buildDefinition.externalParameters.workflow`, which here
+reads `{"ref": "refs/heads/main", "repository": "https://github.com/biomejs/biome", "path":
+".github/workflows/release.yml"}` — the repository biomejs.dev sent you to, building on its own
+main branch. The comparison is what makes the attestation worth anything: on its own it says only
+that *some* repository built these bytes. (`jq` in your bash tool is the harness's builtin, and a
+script gets `/usr/bin/jq`; both print this.)
+
+Its limit runs the other way: most packages publish no provenance at all — `npm view biome
+dist.attestations` prints nothing — so an absent attestation is no evidence of a squat.
+
+PyPI publishes attestations only for projects that release through a trusted publisher, and widely
+used tools do without: for `ruff 0.14.0`, `https://pypi.org/pypi/ruff/0.14.0/json` carries no
+`provenance` on any of its files and `https://pypi.org/integrity/ruff/0.14.0/<file>/provenance`
+answers 404. For a Python tool, the project's own documentation is the whole of the check.
+
+A Go module path is a domain-scoped URL, so the coordinate *is* the repository path, and you check
+it by going to that path. `sum.golang.org` pins a version's bytes once they are published, which
+stops the content changing under you later and says nothing about whether you picked the right
+module path in the first place.
+
+Pinning the version alone does not save you: it pins the squatter at a version, and obeys "write
+the version" to the letter while doing it.
+
+```text
+$ bunx biome --version
+0.3.3
+$ bunx biome@0.3.3 --version
+0.3.3
+$ bunx --package @biomejs/biome@2.6.3 biome --version
+Version: 2.6.3
+```
+
+Only the third runs the formatter, and what separates it from the second is the *name*, not the
+version. No runner exempts you from the coordinate half; each one's syntax just makes a different
+way of getting it wrong easy to type.
+
+- `bunx <binary>@<version>` resolves the token as an npm package name, which is why
+  `--package <name>@<version> <binary>` exists: a bare `bunx biome@0.3.3` is a coordinate nobody
+  checked.
+- `uvx <command>@<version>` does the same on PyPI, and carries it one step further: uv resolves
+  the token as the **project**, installs that project, and only then looks for a command of that
+  name.
+
+  ```text
+  $ uvx pyyaml@6.0.2 --version
+  Installed 1 package in 23ms
+  Package `pyyaml` does not provide any executables.
+  ```
+
+  Nothing there is about the version — `pyyaml` is a real project at a real version, and it is not
+  what you meant by typing a command's name. `uvx --help` is where the distinction lives:
+  `--from <FROM>  Use the given package to provide the command`. Hence
+  `uvx --from shellcheck-py@0.10.0.1 shellcheck --version`, which prints `ShellCheck - shell
+  script analysis tool` and `version: 0.10.0`: the distribution and the command share no name at
+  all.
+- `go run <module>@<version>` takes the coordinate as that domain-scoped URL, so a path you
+  invented usually fails to resolve rather than running someone else's code — but a module path
+  guessed from a binary's name is still a guess, and the checksum database will pin the wrong
+  module's bytes as faithfully as the right one's.
+
+Nothing refuses an unpinned command: no guard, no lint and no check stops you typing a bare `bunx
+biome`. What you are given is a correct form and a tool that is already there, not a gate — so both
+halves are yours to type.
+
+## When no runner reaches it
+
+A tool that is neither in the image nor reachable through one of the three runners is an image
+change: a pull request against sjawhar/legion that carries the same name through every site that
+spells it out, and those sites are not all held by a test.
+
+Do not work from a list of those sites. This page has carried one twice and it was wrong both
+times, so take them from the repository instead: grep for a client the image already carries,
+under both of its names — the command and the Debian package that provides it are spelled
+differently, and different sites spell each — and carry the new name through everything the two
+find.
+
+```text
+$ grep -rn redis-cli
+$ grep -rn redis-tools
+```
+
+Two kinds of hit want more than a substitution. The toolchain smoke step in
+`packages/daemon/docker/worker.Dockerfile` runs each tool once, so a new one needs its own
+invocation there (`nc` and `dig` take no `--version`); and the `THIRD_PARTY_NOTICES` intro string
+in the same file is a licence file that hand-lists the Debian packages the image installs,
+assembled into the image at `/usr/share/doc/legion/THIRD_PARTY_NOTICES`.
+
+Four of the files the grep finds are in Go, and those four are the gated ones: the `toolchain`
+name list in `packages/daemon/internal/capabilities/image.go` makes the probe require it; that
+row's summary in `packages/daemon/internal/capabilities/capabilities.go` has to name it, a test
+holding the summary to the list; the stub binaries in
+`packages/daemon/internal/capabilities/capabilitiestest/capabilitiestest.go` have to include it, or
+the capability and `probe-image` tests fail on an image that does not carry it; and
+`packages/daemon/internal/capabilities/image_test.go` spells the expected detail string out again.
+
+Miss one of those four and the suite is red, which is what makes them easy to find. Nothing holds
+a Dockerfile comment, the notices string or the smoke step to anything today, so a change that
+stops at the gated sites opens green and ships a licence file that does not name the package it
+installs. That is a fact about this build rather than a property: dispatch://INFRA-255 generates
+the package list from `dpkg-query` at build time and drops the hand-kept string, and once it lands
+the notices half of this warning goes with it while the smoke step and the comments stay yours to
+carry. It reaches a role only once a deployment pins the new image digest, as every Legion change
+does — never within your own phase.
+
+So when your work needs such a tool, say so to the architect that owns your issue (`envoy_publish`
+to its role topic), with the tool, what your phase needs it for, and the runner forms you already
+ruled out. What is not the step is improvising a CLI for your own convenience — a vendored binary,
+a hand-rolled substitute, or an extraction prefix dropped on your own `PATH`: the architect decides
+whether the image change is work to schedule. An extraction a harness builds for its own runs is
+not improvising and is not what this rules out (the Dispatch e2e stack, above): the two cases part
+on "The test: where it lands, and what it leaves resolving", which the convenience case fails.
+
+The operator's side of this — why the image carries those five clients rather than anything else,
+the five priced options with their measurements, and what the clients cost the image — is in
+`docs/kubernetes.md`, the subsection "The tools a role's own work needs".