@sjawhar/opencode-legion-envoy 8.5.0 → 8.6.0

package/dist/dispatch.js

@@ -16577,14 +16577,14 @@ function toolSchema(tool) {
   toolSchemas.set(tool, schema);
   return schema;
 }
-async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, problems) {
+async function resolveOwnerArguments(tool, input, cwd, env, exec, dashboardUrls, problems) {
   if (issueFreeTools[tool] === true)
     return { args: input, ref: null, owner: null };
   const refArgument = input.ref;
   let ref = null;
   let args = input;
   if (typeof refArgument === "string") {
-    const refText = dispatchRefFromUrl(refArgument, serverUrl) ?? refArgument;
+    const refText = dashboardUrls.map((dashboard) => dispatchRefFromUrl(refArgument, dashboard)).find((ref2) => ref2 !== undefined) ?? refArgument;
     if (refText !== refArgument)
       args = { ...input, ref: refText };
     const agentArtifact = parseAgentArtifactRef(refText);
@@ -16846,7 +16846,7 @@ function progressText(progress, sep) {
   }
   return parts.join(sep);
 }
-function issueSummary(issue2, events, references, graph, titles) {
+function issueSummary(issue2, events, references, graph, linkBase, titles) {
   const asks = issue2.open_asks;
   const spec = issue2.artifacts?.find((artifact) => artifact.primary);
   const specApproval = spec === undefined ? undefined : approvalLine(spec);
@@ -16864,6 +16864,7 @@ function issueSummary(issue2, events, references, graph, titles) {
   return [
     `Title: ${issue2.title}`,
     `Key: ${issue2.key}`,
+    `Link: ${new URL(`/issues/${encodeURIComponent(issue2.key)}`, linkBase).toString()}`,
     `Status: ${issue2.status}`,
     `Assignee: ${issue2.assignee ?? "unassigned"}`,
     `Claimed by: ${issue2.claim === null ? "nobody" : claimText(issue2.claim, titles)}`,
@@ -17328,6 +17329,7 @@ function withAccount(error48, account) {
 }
 async function executeDispatchTool(input) {
   const { url: configUrl, token: configToken } = input.config;
+  const linkBase = input.config.publicUrl ?? configUrl;
   const baseFetch = input.fetchImpl ?? fetch;
   const fetchImpl = Object.assign(async (...args2) => {
     try {
@@ -17342,7 +17344,7 @@ async function executeDispatchTool(input) {
   const env = input.env ?? process.env;
   const exec = input.exec ?? defaultExec;
   const problems = [];
-  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec, configUrl, problems);
+  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec, input.config.publicUrl === undefined ? [configUrl] : [configUrl, input.config.publicUrl], problems);
   const ownerMissing = issueFreeTools[input.tool] !== true && ownerArguments.owner === null;
   const schema = toolSchema(input.tool);
   const parsed = schema.safeParse(ownerArguments.args, { reportInput: true });
@@ -17360,13 +17362,13 @@ async function executeDispatchTool(input) {
     const project = optionalString(ownerArguments.args, "project");
     if (project !== undefined) {
       const response2 = await client2.openAsksForProject(project);
-      return { text: formatOpenAsksSummary(response2, configUrl), details: { ...response2 } };
+      return { text: formatOpenAsksSummary(response2, linkBase), details: { ...response2 } };
     }
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch open-asks");
     const response = await client2.openAsks(sessionId);
-    return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
+    return { text: formatOpenAsksSummary(response, linkBase), details: { ...response } };
   }
   if (input.tool === "dispatch_whoami") {
     const sessionId = input.sessionId?.trim();
@@ -17448,11 +17450,13 @@ async function executeDispatchTool(input) {
             isPrimarySpec: spec !== undefined
           }),
           ...componentGuidance === undefined ? [] : [componentGuidance],
-          ...renderSuggestions(created.advice?.suggestions, configUrl)
+          ...renderSuggestions(created.advice?.suggestions, linkBase)
         ];
+        const href = new URL(`/issues/${encodeURIComponent(created.key)}`, linkBase).toString();
+        const assigned = created.assignee === undefined ? "" : created.assignee === null ? "; unassigned" : `; assigned to ${created.assignee}`;
         return {
           text: [
-            `Created ${created.key}: ${created.title} ${notSubscribed(issueTopic(created.key))}`,
+            `Created ${created.key}: ${created.title} \u2192 ${href}${assigned} ${notSubscribed(issueTopic(created.key))}`,
             ...adviceLines
           ].join(`
 `),
@@ -17470,7 +17474,7 @@ async function executeDispatchTool(input) {
           text: [
             `Not created: "${title}" looks like a duplicate.`,
             ...candidates.map((candidate) => {
-              const href = new URL(candidate.href, configUrl).toString();
+              const href = new URL(candidate.href, linkBase).toString();
               return `${candidate.key} [${candidate.status}] ${candidate.title} \u2192 ${href}`;
             }),
             "Reference the existing issue, or run dispatch issue again with --force after reading it."
@@ -17611,7 +17615,7 @@ async function executeDispatchTool(input) {
         ...limit === undefined ? {} : { limit },
         ...offset === undefined ? {} : { offset }
       });
-      return searchAnswer(search, query, offset, configUrl);
+      return searchAnswer(search, query, offset, linkBase);
     }
     case "dispatch_issues": {
       const project = stringArg(args, "project");
@@ -17675,7 +17679,7 @@ async function executeDispatchTool(input) {
       } catch (error48) {
         throw refusalWithCode(error48);
       }
-      const href = new URL(`/projects/${encodeURIComponent(project.key)}`, configUrl).toString();
+      const href = new URL(`/projects/${encodeURIComponent(project.key)}`, linkBase).toString();
       return {
         text: `Created project ${project.key} (${project.name}) at ${project.created_at}: ${href}`,
         details: { project: project.key, name: project.name, created_at: project.created_at }
@@ -17768,7 +17772,7 @@ async function executeDispatchTool(input) {
       const askOwner = ask.issue_key !== null ? issueTopic(ask.issue_key) : resolved === undefined ? issueTopic(issue2()) : documentTopic(resolved.artifact);
       const adviceLines = [
         ...renderAdvice(input.tool, askOwner.label, ask.advice, {}),
-        ...renderSuggestions(ask.advice?.suggestions, configUrl)
+        ...renderSuggestions(ask.advice?.suggestions, linkBase)
       ];
       return {
         text: [
@@ -18249,7 +18253,7 @@ ${trailer.join(`
         ])
       ]);
       return {
-        text: issueSummary(read.issue, read.events, references, [...pictures2.lines, ...graph], titles),
+        text: issueSummary(read.issue, read.events, references, [...pictures2.lines, ...graph], linkBase, titles),
         details: { issue: read.issue.key },
         ...showImages(pictures2)
       };
@@ -18987,7 +18991,17 @@ function dispatchSettings(env, config2) {
     }
     const url2 = (explicitUrl ?? (source.kind === "file" ? source.server : own.serverUrl ?? DEFAULT_SERVER_URL)).replace(/\/+$/, "");
     const token = source.kind === "variable" ? source.token : fileBearer(source, url2, "DISPATCH", env);
-    return { enabled: true, url: url2, token };
+    const publicUrl = nonEmpty(env.DISPATCH_PUBLIC_URL);
+    const publicParsed = publicUrl === undefined ? undefined : httpUrl2(publicUrl);
+    if (publicUrl !== undefined && (publicParsed === undefined || publicParsed.port === "0")) {
+      return offWithError("DISPATCH_PUBLIC_URL must be an http or https URL");
+    }
+    return {
+      enabled: true,
+      url: url2,
+      token,
+      ...publicUrl === undefined ? {} : { publicUrl: publicUrl.replace(/\/+$/, "") }
+    };
   } catch (error48) {
     return offWithError(messageFor(error48));
   }

package/dist/src/server.js

@@ -14317,6 +14317,8 @@ var DISPATCH_DOCUMENT_TOPIC_PREFIX = `${DISPATCH_TOPIC_PREFIX}document.`;
 function agentSubject(session) {
   return `${AGENT_TOPIC_PREFIX}${session}`;
 }
+// ../contracts/src/slack.ts
+var SLACK_POST_TEXT_MAX = 4000;
 // ../contracts/src/tool-schema.ts
 function overCapMessage(length, max) {
   return `is ${length - max} characters over the ${max}-character limit (${length}/${max})`;
@@ -14925,7 +14927,17 @@ function dispatchSettings(env, config2) {
     }
     const url2 = (explicitUrl ?? (source.kind === "file" ? source.server : own.serverUrl ?? DEFAULT_SERVER_URL)).replace(/\/+$/, "");
     const token = source.kind === "variable" ? source.token : fileBearer(source, url2, "DISPATCH", env);
-    return { enabled: true, url: url2, token };
+    const publicUrl = nonEmpty(env.DISPATCH_PUBLIC_URL);
+    const publicParsed = publicUrl === undefined ? undefined : httpUrl2(publicUrl);
+    if (publicUrl !== undefined && (publicParsed === undefined || publicParsed.port === "0")) {
+      return offWithError("DISPATCH_PUBLIC_URL must be an http or https URL");
+    }
+    return {
+      enabled: true,
+      url: url2,
+      token,
+      ...publicUrl === undefined ? {} : { publicUrl: publicUrl.replace(/\/+$/, "") }
+    };
   } catch (error48) {
     return offWithError(messageFor(error48));
   }
@@ -15129,7 +15141,8 @@ var EnvoyToolOperation = {
   setRole: "setRole",
   getRole: "getRole",
   whoami: "whoami",
-  listSessions: "listSessions"
+  listSessions: "listSessions",
+  slackPost: "slackPost"
 };
 var envoyToolSpecs = [
   {
@@ -15200,6 +15213,16 @@ var envoyToolSpecs = [
       title: schema.string().optional()
     }),
     operation: EnvoyToolOperation.listSessions
+  },
+  {
+    name: "slack_post",
+    description: "Reply in a Slack thread as the Legion Slack app, with the bot token the secrets broker grants this session (LEGION_SLACK_BOT_TOKEN); the session never holds it. channel is the Slack channel id (a mention's channel_id); thread_ts is the thread's root ts: the mention's thread_ts, or its own ts when it has none. Answers the new message's ts. A refusal carries Slack's own error code (not_in_channel: the app is not in that channel) or the broker's state (waiting for approval, denied). Sent once and never retried: after 'Slack did not answer' the reply may already be in the thread, so do not post it again.",
+    arguments: (schema) => ({
+      channel: schema.string({ min: 1 }).describe("Slack channel id, such as C0123ABCD."),
+      thread_ts: schema.string({ min: 1 }).describe("The thread's root ts, which keeps the reply in the mention's thread."),
+      text: schema.string({ min: 1, max: SLACK_POST_TEXT_MAX }).describe(`The reply, in Slack mrkdwn, at most ${SLACK_POST_TEXT_MAX} characters.`)
+    }),
+    operation: EnvoyToolOperation.slackPost
   }
 ];
 var envoyToolSchemas = new Map;

package/package.json

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

package/skills/dispatch/references/reading.md

@@ -57,8 +57,9 @@ dispatch://PROJECT/artifact/<document-ref>/comment/<id>
 ```
 
 A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records. `dispatch read` also
-accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server (it maps to the
-`dispatch://` form above), and an ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
+accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server, or on its public
+dashboard when `DISPATCH_PUBLIC_URL` names one (it maps to the `dispatch://` form above), and an issue's read names its page
+(`Link:`, on that public dashboard when there is one), the link to hand a person. An ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
 full uuid. A non-uuid id on `GET /asks/{id}`, `/comments/{id}`, or `/issues/{key}/messages/{id}` is a 400 `ASK_ID_INPUT` /
 `COMMENT_ID_INPUT` / `MESSAGE_ID_INPUT`, never a 500.
 

package/skills/envoy/SKILL.md

@@ -237,6 +237,12 @@ envoy_subscribe([
 This follows every message and mention in one thread. Channel-level topics end in `.message` or
 `.mention`; thread timestamps replace dots with underscores.
 
+Reply in a thread with `slack_post(channel=<channel_id>, thread_ts=<the message's thread_ts, or
+its ts>, text=…)`, which posts as the Legion Slack app with the bot token the secrets broker grants
+the session (`LEGION_SLACK_BOT_TOKEN`). A refusal carries Slack's own error code, or the broker's
+state when it has not granted the token. The post is sent once; when the answer is that Slack did
+not answer, the reply may already be there, so do not post it again.
+
 ## Ghost Wispr
 
 Ghost Wispr topics are `notifications.ghostwispr.<session>.<kind>`, where `kind` is

package/skills/legion-architect/SKILL.md

@@ -403,11 +403,12 @@ active phase worker.
 | `design-approved` | Its `version` is the approved one. A human approved the root spec document at its current version; the gate is open. Proceed to section 2 — except on a root whose catch-up said `handed_over`: its workers already run their phases, so start nothing; the approval releases any READY the gate refused. One whose `version` is the version a human's own answer to a decision block wrote, after an earlier approval (Dispatch carried that approval to it, section 1), opens nothing new: carry on, and release no wave because of it. |
 | `design-changes-requested` | Its `version` and `reason`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec as the reason asks and request approval again as section 1 says; stay parked; the gate is closed. |
 | `phase-finished` | The daemon has already moved the issue to its next phase by its fixed table and started that phase's role; you start nothing. Read the committed handoff for the finishing phase; if it shows unresolved gaps, tell the role now working the issue (`envoy_publish` to its role topic). A `planner` notice that names a departure from the spec's design defers to section 1's full condition: when the approved Summary, Acceptance, scope and settled decisions still hold, the plan is the record; otherwise change the root spec and request approval again as section 1 says. A `reviewer` notice whose GitHub review is `CHANGES_REQUESTED` needs nothing from you: the daemon has returned the issue to `implementing` (Dispatch `in_progress`) and started the **implementer**, whose correction goes through the tester and the reviewer again, never straight to retro. A `reviewer` notice with an `APPROVED` review means the daemon has started retro (step 5). An `implementer` notice for `production_check` is its production report: read the record on the pull request and the issue, then run step 7. A `tester` notice with `verdict: "fail"` — its handoff carries `implementerProof.verdict: "rejected"`, or a failure naming the production-like proof — has gone back to the **implementer** by the daemon's table; never supply the proof from another role. A worker that reports no surface reaches the changed path sends that report instead of completing its phase, so the daemon starts nothing more on that issue and the worker stays idle in its session, not suspended: file a child issue in this tree to build the surface (infrastructure, tooling, or a skill), and when that child's `child-closed` arrives, tell the waiting worker to continue with `envoy_publish` to its role topic. That report is never a reason to advance the phase. |
-| `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached, or reads `Issue reached review_round_cap=<N>.` (the end of this row). The count is of heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. The notice moves nothing, and no later CI red within the attempt that ran the count out (the counted head, and every head pushed on top of it until a push lands on a head CI judged green, the tester's red tests and handoff onto the held red included) sends the work back from `testing`, `reviewing`, `retro` or `merging` either: the issue stays in its phase until you move it, or a worker's own decision does (a tester's `fail`, a reviewer's request for changes). A head pushed onto green CI leaves that attempt, so its red still comes as a `checks-red`. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. A `review_round_cap` reason is the implementer's round count instead: every move back to an earlier phase counts one, and the notice comes again with each round past the cap. It moves nothing either, since the round that reached the cap has already started its worker. Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names either a conflict (`the head conflicts with <base>`) or the required checks that failed (`CI is red at <head>`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker. Judge the cap by the rounds that are not conflicts. Conflict returns need nothing from you beyond the next round. Tester fails, requests for changes and CI-red returns (a `checks-red` notice is raised for CI only when a required check fails on code the branch pushed) are the work going in circles: narrow it, re-plan it with the responsible worker, or ask a human with `dispatch ask`. Judge a worker's backward move by the reason that worker gives. A move you ordered for a conflict found before `awaiting_merge` (section 6) is a conflict return. The merger's move back to `reviewing` because its task names no approved head is not the work going in circles either. A move that sends back code found wrong counts with the tester fails. |
+| `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached, or reads `Issue reached review_round_cap=<N>.` (the end of this row). The count is of heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. The notice moves nothing, and no later CI red within the attempt that ran the count out (the counted head, and every head pushed on top of it until a push lands on a head CI judged green, the tester's red tests and handoff onto the held red included) sends the work back from `testing`, `reviewing`, `retro` or `merging` either: the issue stays in its phase until you move it, or a worker's own decision does (a tester's `fail`, a reviewer's request for changes). A head pushed onto green CI leaves that attempt, so its red still comes as a `checks-red`. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. A `review_round_cap` reason is the implementer's round count instead: every move back to an earlier phase counts one, and the notice comes again with each round past the cap. It moves nothing either, since the round that reached the cap has already started its worker. Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names a conflict (`the head conflicts with <base>`), the required checks that failed (`CI is red at <head>`), or the merge queue's failed merge and its failing run (`the merge queue took pull request #<n> out at READY's head …`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker. Judge the cap by the rounds that are not conflicts. Conflict returns need nothing from you beyond the next round. Tester fails, requests for changes and CI-red returns (a `checks-red` notice is raised for CI only when a required check fails on code the branch pushed, or when the merge queue fails the merge) are the work going in circles: narrow it, re-plan it with the responsible worker, or ask a human with `dispatch ask`. Judge a worker's backward move by the reason that worker gives. A move you ordered for a conflict found before `awaiting_merge` (section 6) is a conflict return. The merger's move back to `reviewing` because its task names no approved head is not the work going in circles either. A move that sends back code found wrong counts with the tester fails. |
 | `pr-merged` | Its `reason` names the pull request. The PR merged, under the repository's rules, before the issue reached `awaiting_merge`. The workflow runs on and asks no one to merge it: the daemon starts the **implementer** on the production check once the issue gets there, and you start nothing. Its `phase-finished` for `production_check` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it with `sign_off`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (`park_child` then `rerun_child`, for a child), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
 | `merge-refused` | Its `reason` names the pull request, READY's head, what the daemon asked GitHub to do (merge, enqueue, or enable auto-merge for it), and GitHub's refusal, which a retry would meet again (squash merges disabled, a permission the implement App lacks). The daemon has stopped submitting that merge; the issue stays in `awaiting_merge`. The cause is a repository setting or an App permission, a person's to change: ask one with `dispatch ask`, naming the refusal and the pull request at READY's head, which that person merges under the repository's rules once it is fixed. The merge moves the issue on to its production check. Never bypass a rule. |
 | `merge-stalled` | Its `reason` names the pull request, the state and head GitHub shows (closed, or another head), since when GitHub has shown it, and READY's head, which the record still awaits. GitHub's last change to the pull request is more than 10 minutes old and the record never heard of it, so its webhook never reached the daemon: the daemon has stopped submitting that merge, and the issue stays in `awaiting_merge`. Read the pull request on GitHub. Open at READY's head, GitHub has caught up: a person merges it under the repository's rules, and the merge moves the issue on to its production check. Closed, or at another head the daemon never recorded: ask a person with `dispatch ask`, naming the pull request, what GitHub shows, and READY's head. Never bypass a rule. |
+| `merge-removed` | Its `reason` names who took the pull request out of the merge queue or turned its auto-merge off at READY's head after the daemon submitted it, or says GitHub turned it off on its own (over a repository setting such as a merge method the repository blocks) and names the App that submitted the merge, which GitHub names as the actor of its own disables; then what was removed, GitHub's reason (`manual`, `merge_conflict`, `manually_disabled`, `merge_commit_blocked`, …), when, and READY's head. It was not a failed merge, which comes as a `checks-red` instead. The daemon submits that merge no further, so the removal stands, and the issue stays in `awaiting_merge`. Read the pull request on GitHub. A `merge_conflict` conflicts with the base or with a pull request queued ahead of it: once the conflict is on the base, the daemon's own conflict check sends the issue back to `implementing` by itself. Otherwise ask a person with `dispatch ask` (the one who removed it, when the reason names a person rather than GitHub on its own), naming the pull request at READY's head and the reason; that person merges or queues it again under the repository's rules, and the merge moves the issue on to its production check. Never bypass a rule. |
 | A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch comment --reply-to <comment id>`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `--reply-to-ask <ask id> --turn agent`, since a default-turn reply hands that request back to the human and a corrected `--summary` is then refused), then adjust the plan or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
 | `worker-died` | Its `role` and `phase`. That role's claim failed: its launches or prompts ran out. For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. |
 | `held` | Its `role` and `phase` (the phase the issue left), or `phase` with `reason: "escalated"`. Without `reason`, that phase's worker ran out of launches or prompts: the issue is held (phase `held`), the `worker-died` that comes with it is yours to answer with `retry_or_escalate` as that row says, and the controller hears of the hold too. With `reason: "escalated"`, it records your own `escalate`: the controller has the issue now, and you start nothing for it. |

package/skills/legion-controller/SKILL.md

@@ -404,7 +404,8 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 | `todo on <KEY>` from the Go daemon (payload `{kind: "todo"}`) | an issue not handed to Legion that changed while in `todo` and a slot stood free, sent half a minute later | Verify a free slot, then walk the whole `todo` list ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | `tick on <PROJECT>` from the Go daemon (payload `{kind: "tick", openCapabilities?: [<name>, …]}`) | the project key; the daemon's periodic wake, whatever the slots; `openCapabilities` names the deployment capabilities with no decision, each with its detail and `capabilities.decided.<name>` line under `capabilities` in `read_state`, and the live capabilities a running session's check failed, each with the detail naming the session (pod or pane), role, issue and fact, and no `configLine` | Recheck the trees waiting on a claim, then walk if a slot is free — a gap never stops the walk; post the day's report if this is the day's first turn, naming each open capability in it (the operator closes or decides a deployment row; the operator or the issue's architect fixes a live row's session; you take no other action) |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; the owning architect writes an issue-design decision as a decision block and opens `dispatch ask` only for a human to-do |
-| Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
+| Mention | GitHub PR @mention text | Answer, or route to the owning issue's architect role |
+| Slack mention (`from: slack`) | the mention's `channel_id`, `user_id`, `text`, `ts`, `thread_ts` | Nothing when your `Slack channels:` line does not name its `channel_id`; otherwise answer in its thread with `slack_post`: a state question from `read_state`, a work request filed as a Dispatch issue, an architect's question routed to that architect ([Slack mentions](skill://legion-controller/references/slack-mentions.md)) |
 | `held on <KEY>` from the Go daemon (payload `{kind: "held", phase, role?, reason?}`) | the held issue, the phase it left, and the role whose claim failed, or `reason: "escalated"` | Verify the hold in `read_state` (the issue's phase is `held`). Without `reason`, a phase worker's launches or prompts ran out and the tree's architect decides retry or escalate: no action. With `reason: "escalated"` (on the record, `issues.<KEY>.holdReason` is `escalated`), the architect sent it to you: handle it as an architect escalation below. Parking the tree is `set_status` of the root to `backlog`; setting the root back to `todo` later re-admits it as a new generation, which starts again from its architect |
 | `worker-died on <KEY>` from the Go daemon with `role: "architect"` | the tree root whose architect's claim failed, and the phase the root was in | The tree's architect ran out of launches or prompts and the daemon relaunches nothing; every other notice of the tree goes to that architect, so nobody inside the tree can act. Verify in `read_state` (`issues.<KEY>.architect.state` is `failed`); if the root's phase is `done`, the tree is already parked: no action. Otherwise re-admit the tree (`set_status` of the root to `backlog`, then to `todo`: a new generation, whose architect starts again with fresh budgets) or leave it parked and say why on the issue |
 | Direct user message | — | Always first |
@@ -482,12 +483,13 @@ judgments.
 
 ## Mentions
 
-Read the mention and its artifact. Answer it when it asks the controller for triage or
-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.
+Read the mention and its artifact; a Slack mention follows [Slack
+mentions](skill://legion-controller/references/slack-mentions.md). Answer it when it asks the
+controller for triage or 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/skills/legion-controller/references/slack-mentions.md

@@ -0,0 +1,94 @@
+# Slack mentions
+
+A person who mentions the Legion Slack app in one of the project's Slack channels is talking to
+you, and you answer in that thread. The `Slack channels:` line of your system prompt names each
+channel `legion.yaml` gives the project (`projects.<KEY>.slack_channels`). Only the controller the
+daemon launches has one: the Slack bot token is the Legion daemon service's, which the secrets
+broker grants to that service's own pods alone. With no such line the project has no channel, and
+nothing here applies.
+
+## Your session subscribes for you
+
+Your session hears each listed channel's mentions by itself, on
+`notifications.slack.*.<channel>.mention`, for as long as it holds the controller role: a resumed or
+relaunched session hears the channels its launch names and no others, and drops every Slack topic an
+earlier session subscribed to by hand. Never `envoy_subscribe` a Slack topic yourself.
+
+A delivery from Slack whose `channel_id` the line does not name is not yours: do nothing with it.
+
+A mention published while no controller ran never arrives: Envoy hands a session no copy of an
+event from before it subscribed. Nothing tells you about one, so there is nothing to catch up. When
+the project's `slack_channels` change, the daemon relaunches you into this session with the new
+line.
+
+## What a mention carries
+
+The delivery's `message` holds Slack's fields: `channel_id`, `user_id` (a Slack user id such as
+`U0123ABCD`), `text` (the mention itself appears in it as `<@U…>`, the app's own id), `ts` (the
+mention's own timestamp), `thread_ts` (the thread's root, only when the mention was posted inside a
+thread), and `bot_id` and `bot_name` when a bot posted it.
+
+## Answer in the thread
+
+Every answer is one `slack_post` call:
+
+- `channel` is the mention's `channel_id`.
+- `thread_ts` is the mention's `thread_ts`, or its `ts` when it has none. Either keeps the reply in
+  the thread the mention opened or joined, never at the channel's top level.
+- `text` is what you say, at most 4,000 characters, written as `skill://dispatch`'s "Writing for
+  the human" says. Address the author as `<@user_id>` (by `bot_name` when a bot posted the mention
+  with no `user_id`) and give every issue as its key, its title and its Dispatch link exactly as
+  `dispatch` printed it (the `Link:` line of `dispatch read`, the link on a `Created` line or a
+  search hit): it points at Dispatch's dashboard, and `slack_post` refuses a reply linking an
+  address inside the cluster. Never build a link yourself. Say only what Dispatch shows: an issue's
+  assignee is the one `dispatch` names, never one you assume.
+
+`slack_post` is sent once and never retried. When it answers that Slack did not answer, the reply
+may already be in the thread: do not post it again. When it answers with Slack's refusal, the
+reply is not posted: `not_in_channel` means the app has not been added to that channel, which only
+a person in the workspace can fix, so say so in your next report rather than retrying. When it
+answers that the secrets broker has not granted `LEGION_SLACK_BOT_TOKEN` (its request waits for
+approval, or was denied), nothing was posted and no reply can be until the operator stores the
+token with owner `legion-daemon` and tier `agent`: name the error in your next report.
+
+## Decide what the person wants
+
+Read the mention's `text`. When it names an issue key, read the issue with `dispatch read` before
+answering. Then take the first of these that fits.
+
+- **A question about state.** "What is Legion working on?", "Where is ACME-12?", "Why is it held?"
+  Answer from `read_state` and Dispatch as they stand now, never from memory: each issue's
+  `issues.<KEY>.phase`, its pull request, `admission.active` and `admission.waiting`. Say what you
+  read, not what you infer.
+- **A request for work.** Someone wants a change made, a bug fixed, something investigated. Search
+  first (`skill://dispatch-first`): when an open issue already tracks it, reply with that issue and
+  file nothing. Otherwise file one issue in the project:
+
+  ```text
+  dispatch issue --project <PROJECT> --title '<the request, as a title>' --spec-file - <<'EOF'
+  ## Summary
+
+  <what the person asked for, in your words, and why if they said>
+
+  Asked in Slack by <@user_id> in channel <channel_id>, message <ts>.
+  EOF
+  ```
+
+  Add `--label legion` only when the person asks Legion to do the work ("Legion, fix…", "can
+  Legion take…"); a request for someone to look at something, or one that does not say who, gets
+  no label and waits for a person to hand it over. Never label a request outside the scope the
+  deployment instructions state. Reply with the new issue's key, its title, the link and assignee
+  the `Created` line names (Dispatch assigns the issue to your token's owner when you name nobody),
+  and whether Legion will take it.
+- **Something an issue's architect owns.** A question about a tree's design, a change of direction,
+  a decision only the tree's architect can make about an issue Legion runs. Find the tree: follow
+  `Links:` up through each `child_of` parent with `dispatch read` until you reach the issue
+  `read_state` records with an `architect`. When `issues.<ROOT>.architect.locator.claim` is there,
+  `envoy_publish` the person's words to `notifications.role.` followed by it, with the channel id
+  and `thread_ts` you reply on, and reply in the thread that you passed it to the architect that
+  owns `<ROOT>`, which answers on the issue. When the architect is not running (no locator), say
+  that in the thread instead and what `read_state` shows for the tree. Never invent a role token.
+- **Anything else** (a greeting, a question about Legion itself): answer it briefly in the thread.
+
+A request to approve a design is answered as the skill's "Mentions" section says: a person
+approves the spec in Dispatch, and you never open a gate.

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

@@ -137,23 +137,36 @@ reviewing until you finish.
 - **The daemon submits the merge the moment READY is accepted, unless the answer says a person
   merges it.** It queues a `ready_merge` outbox row for the head READY named, and the row, as the
   implement App, reads GitHub and then the record: while the issue still awaits that READY head, a
-  base with a merge queue gets the pull request enqueued; otherwise a pull request GitHub reports
-  mergeable now (`CLEAN`, `UNSTABLE` or `HAS_HOOKS`) is squash-merged, and one in a repository that
-  allows auto-merge is armed. Every request carries READY's head as GitHub's expected head, so
-  GitHub refuses it once the head has moved. In a repository that allows neither, the row waits,
-  reading GitHub again on the outbox's backoff, until GitHub reports the pull request mergeable —
-  a required check finishing, a required review a person gives — and then merges it. An arm or a
-  queue entry is not the end: the row keeps reading GitHub until GitHub reports the pull request
-  merged at READY's head, and submits again when the arm or entry is gone while the record still
-  awaits READY (a disarm sent before READY that GitHub applied late). GitHub's
-  rules decide each answer: the daemon bypasses none, and a person may merge it first. A refusal a
-  retry would meet again (squash merges disabled, a permission the App lacks) ends the row and is
-  told to the architect once (`merge-refused`), with GitHub's message. While the record still
-  awaits READY's head, GitHub showing the pull request closed or at another head is a webhook not
-  yet applied, so the row waits for the two to agree. Only once GitHub's last change to the pull
-  request is more than 10 minutes old, however long the row waited before, does the row end and
-  tell the architect once (`merge-stalled`). A reopen at READY's head reuses the row and takes it
-  from a run that read the record before the reopen. Any other failure retries.
+  base with a merge queue gets the pull request enqueued once GitHub reports it mergeable now
+  (`CLEAN`, `UNSTABLE` or `HAS_HOOKS`); otherwise a pull request GitHub reports mergeable now is
+  squash-merged, and one in a repository that allows auto-merge is armed. Every request carries
+  READY's head as GitHub's expected head, so GitHub refuses it once the head has moved. On a
+  merge-queue base the row never arms auto-merge: while a required check still runs, or anything
+  else keeps GitHub from reporting the pull request mergeable, it waits, reading GitHub again on
+  the outbox's backoff, and enters the queue once GitHub does. In a repository that allows neither a
+  merge queue nor auto-merge, the row waits the same way until GitHub reports the pull request
+  mergeable — a required check finishing, a required review a person gives — and then merges it. An
+  arm or a queue entry is not the end: the row keeps reading GitHub until GitHub reports the pull
+  request merged at READY's head. Once it has seen the arm or entry, it never submits that head
+  again after someone else removes it: the merge queue taking the pull request out because the merge
+  failed (GitHub's reason `failed_checks`, or an unexplained reason with a check that failed, timed
+  out, failed to start, needed action or went stale on the commit the queue built for its
+  `merge_group` CI) sends the issue back to `implementing`, the implementer's task naming each
+  failing check and its run, as a red head does; any other removal (a person dequeues it,
+  cancelling its runs, or turns auto-merge off, GitHub turns it off, the queue finds a conflict)
+  ends the row and is told to the architect once
+  (`merge-removed`). Two removals are submitted again: the implement App's own disarm sent before
+  READY that GitHub applied late (auto-merge `manually_disabled`, or a `manual` dequeue, by that
+  App), and auto-merge a close turned off, which the reopen at READY's head undid. GitHub's
+  rules decide each answer: the daemon bypasses
+  none, and a person may merge it first. A refusal a retry would meet again (squash merges disabled,
+  a permission the App lacks) ends the row and is told to the architect once (`merge-refused`), with
+  GitHub's message. While the record still awaits READY's head, GitHub showing the pull request
+  closed or at another head is a webhook not yet applied, so the row waits for the two to agree.
+  Only once GitHub's last change to the pull request is more than 10 minutes old, however long the
+  row waited before, does the row end and tell the architect once (`merge-stalled`). A reopen at
+  READY's head reuses the row, starts it over as though nothing had been armed, and takes it from a
+  run that read the record before the reopen. Any other failure retries.
   No role runs `gh pr merge`. When the answer's `note` begins `MANUAL_MERGE_REQUIRED:` (the pull
   request touches a path the project's `merge.by_hand` names), READY stands but the daemon submits
   nothing: the merger tells the architect the note and the head, and a person merges under the