@sjawhar/opencode-legion-envoy 8.5.1 → 8.6.1

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.1",
+  "version": "8.6.1",
   "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

@@ -309,10 +309,11 @@ The daemon keeps this order from its fixed table; you start none of its steps:
    one final commit, the removal of `.legion/<issue>/`, so no merge carries a handoff onto the
    default branch (dispatch://LEGION-605); those commits do not void the approval and never return
    the tree to the tester or reviewer;
-4. the merger verifies the current head is the reviewer-approved head plus only retro's commits,
-   those that change `docs/solutions/` and that removal (`jj diff --from <approved-sha> --to
-   <tip-sha> --summary`, quoted in READY) and sends the READY packet with its completion, which
-   refuses a head that still carries `.legion/<issue>/`; the daemon posts
+4. the merger quotes what sits above the reviewer-approved head (`jj diff --from <approved-sha> --to
+   <tip-sha> --summary`) in READY and sends the READY packet with its completion, which refuses a
+   head carrying anything above the approved head but retro's commits, those that change
+   `docs/solutions/` and that removal (`READY_UNREVIEWED_CHANGE`), and a
+   head that still carries `.legion/<issue>/`; the daemon posts
    `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` on the Dispatch
    issue and publishes it to the project's merge queue role when one is set. The moment the daemon
    accepts READY, it submits the merge of that head itself, as the implement App and with GitHub's
@@ -324,8 +325,11 @@ The daemon keeps this order from its fixed table; you start none of its steps:
    design gate refused is submitted by the daemon once that spec version is approved; nobody is
    told to submit it. If the merger reports a failed verification,
    treat it like `pr-blocked`: the merger holds the phase, so tell it to move the issue back with
-   `request_backward_move`, naming what failed; never bypass. A READY refused because the head
-   still carries `.legion/<issue>/` goes back to `retro`, so the implementer's retro removes it.
+   `request_backward_move`, naming what failed; never bypass. A READY refused
+   `READY_UNREVIEWED_CHANGE`, or a merger task with no approved head (`READY_NOT_APPROVED`), goes
+   back to `reviewing`, the move's reason naming the code and what it found, so the reviewer runs a
+   new round. A READY refused because the head still carries `.legion/<issue>/` goes back to
+   `retro`, so the implementer's retro removes it.
 5. the merge lands under the repository's rules; the daemon then starts the **implementer** once
    more, on the production check.
    It drives the changed path in production through the user's own access path and records
@@ -403,7 +407,7 @@ 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 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-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` for a READY refusal (`READY_UNREVIEWED_CHANGE`, or `READY_NOT_APPROVED` when its task names no approved head), and the reviewer's no-fix request for changes that follows it so the tester runs the head, are 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. |

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-retro/SKILL.md

@@ -26,9 +26,9 @@ retrospective's durable output.
    issue. Retro writes **no handoff**. The removal exists because a squash merge commits the head
    merged into the base, and nothing on the base reads a handoff; the handoffs stay on the issue
    branch below that commit.
-4. The merger verifies the tip is the approved head plus retro's commits, quotes their
-   `jj diff --from <approved-sha> --to <tip-sha> --summary` in READY, and sends the READY packet
-   with its completion, which refuses a head that still carries `.legion/<issue>/`; the daemon
+4. The merger quotes retro's commits (`jj diff --from <approved-sha> --to <tip-sha> --summary`) in
+   READY, and sends the READY packet with its completion, which refuses a head with anything above
+   the approved head but those commits, or still carrying `.legion/<issue>/`; the daemon
    posts it on the Dispatch issue and publishes it to the project's merge-queue role when one is
    configured. On READY's acceptance the daemon submits the merge, and it lands under the
    repository's rules: its required reviews and checks, and its merge queue when it enables one.
@@ -40,12 +40,15 @@ retrospective's durable output.
    merge commit. A defect the production check finds becomes a corrective child issue of the same tree,
    owned by the architect and implemented by the same implementer; the parent stays open until it lands.
 
-Retro's commits sit above the reviewer's approved head and the approval stands: commits that
-change only `docs/solutions/`, and the one that removes `.legion/<issue>/`, do not void it, and the
-tree goes from retro to the merger — never back to the tester or reviewer. A conflict-forced
-rebase after retro moves these commits with the branch. Any round after retro (a conflict round, a
-round a red CI sends back, a re-review) writes `.legion/<issue>/` again, and every approval moves
-the issue to retro once more: each retro ends with the removal again, or READY is refused.
+Retro's commits sit above the reviewer's approved head and the approval stands: commits that change
+only `docs/solutions/`, and the one that removes `.legion/<issue>/`, do not void it, and the tree
+goes from retro to the merger — never back to the tester or reviewer. A conflict merge pushed above
+the approved head with no review round after it brings the base's paths above that head, so READY
+refuses it (`READY_UNREVIEWED_CHANGE`) and the reviewer reviews the new head as a new round; one the
+conflict procedure sends back through `implementing` is confirmed before READY. Any round after
+retro (a conflict round, a round a red CI sends back, a re-review) writes `.legion/<issue>/` again,
+and every approval moves the issue to retro once more: each retro ends with the removal again, or
+READY is refused.
 
 Do not start retro before step 2 or skip it because the change seems mechanical; the merger's
 `READY` comes only after step 3. The design gate is not a substitute for review and retro.
@@ -204,7 +207,7 @@ workspace stands on, the removal commit your push made, so push before you compl
 Before returning, verify all of the following:
 
 - The reviewer-approved head remains below the retro commits, and the reviewer's approval of that
-  head stands: the merger accepts the approved head plus the documentation commit and the removal.
+  head stands: READY accepts the approved head plus the documentation commit and the removal.
 - The learning documents and the Dispatch message both exist (never a GitHub issue comment).
 - The PR body carries what the repository's instructions derive from the pull request's changed
   paths at the retro head, written back before that head's push, and each line that affirms work

package/skills/legion-worker/references/conflicts-and-rewrites.md

@@ -93,9 +93,9 @@ fingerprint=$(set -o pipefail; jj -R "$LEGION_WORKSPACE" diff --from "fork_point
 
 Where each role gets its two heads: the implementer — the tip before and after its own rebase;
 the tester — the head its `E2E` line names and the new head; the reviewer — the `commit_id` of
-its last submitted review (`gh api repos/{owner}/{repo}/pulls/{n}/reviews --jq '.[] | {commit_id, state, user: .user.login}'`)
-and the new head; the merger never computes a fingerprint — it uses the `--summary` check in
-`skill://legion-worker/references/merge-gate.md`.
+its last submitted review (`gh api repos/{owner}/{repo}/pulls/{n}/reviews --jq '.[] | {commit_id, state, user: .user.login, body}'`, whose body tells a no-fix request that answered a READY refusal from any other)
+and the new head; the merger never computes a fingerprint — it quotes the `--summary` lines
+in READY, and the daemon holds the head to retro's commits.
 
 ## Rewriting pushed commits
 

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

@@ -12,8 +12,8 @@ the default branch and nothing there reads a handoff, and READY refuses a head t
 carries them. After the approval, only retro's commits leave it standing on their own: those that
 change only `docs/solutions/`, and that removal (*Retro*, below). A conflict-forced merge goes back
 to the reviewer for a confirmation or a new round, as the fingerprint decides (*The reviewer*,
-below, and `skill://legion-worker/references/conflicts-and-rewrites.md`), and any other change to
-the head voids it.
+below, and `skill://legion-worker/references/conflicts-and-rewrites.md`), unless READY refused
+it, and any other change to the head voids it.
 
 ## The reviewer
 
@@ -71,7 +71,10 @@ the head voids it.
   and the fingerprint — a confirmation, not a round; no thermo pass, no thread pass. Equal and
   that review was `COMMENT` or `REQUEST_CHANGES`: continue that round against the new head;
   nothing restarts. Different, or either run printed no fingerprint: a new round — thermo again,
-  one review.
+  one review. A return whose task's `Reason:` names a READY refusal is never a confirmation, even
+  after a rebase, and a no-fix `REQUEST_CHANGES` that answered one is never continued: the round
+  after it reviews the refused change in full from the last `APPROVE` (*Retro's commits do not
+  void the reviewer's approval* below).
 - Answer every thread you opened, and every thread a bot opened that is none of Legion's role
   Apps, as `skill://legion-worker/references/review-threads.md` says; the same reference says
   when every thread is settled enough to approve, and resolving one never gates your approval.
@@ -95,9 +98,14 @@ reviewing until you finish.
   head, its `docs/solutions/` learnings and its last commit removing `.legion/<issue>/`
   (`skill://legion-retro` gives the steps), leave the approval standing, and the tree goes to the
   merger — never back to the tester or reviewer. Anything else above the approved head does void
-  it, and the merger tells the architect the head must return to review instead of completing. A
-  conflict-forced rebase after retro moves those commits with the branch. Every approval moves the
-  issue to retro again, so each retro ends with the removal again.
+  it: READY is refused `READY_UNREVIEWED_CHANGE`, naming the paths, and the merger tells the
+  architect, who has it send the head back to review instead of completing, the move's reason
+  naming the refusal's code and what it found. A conflict merge pushed above the approved head
+  with no review round after it brings the base's paths above that head, so READY refuses it the
+  same way; one sent back through `implementing` by the conflict procedure gets its confirmation
+  before READY runs. A READY refusal's return reaches the reviewer as a new round, never a
+  fingerprint confirmation. Every approval moves the issue to
+  retro again, so each retro ends with the removal again.
 - **Retro brings the PR body's path-derived content up to date before its push.** Whatever the
   repository's instructions derive from the pull request's changed paths (a checklist named for
   each class of path, read by a required check), retro recomputes for the whole diff at its head
@@ -108,11 +116,12 @@ reviewing until you finish.
 ## The merger
 
 - The merger resolves no review thread: the reviewer's approval already judged them, and READY
-  requires no thread state beyond it. It proves the head is the approved head plus retro's commits
-  with two commands. First `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
-  "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`, whose output is quoted
-  in READY; then the same with the one fileset `'~(docs/solutions | .legion/<issue>)'` appended,
-  which must print nothing (jj unions separate path arguments, so two of them leave nothing out).
+  requires no thread state beyond it. It quotes what sits above the approved head with
+  `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
+  "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary` in READY; the daemon,
+  not the merger, holds those commits to retro's: READY reads GitHub's compare of the round's
+  approved head with READY's head and refuses any other path (`READY_UNREVIEWED_CHANGE`), and a
+  round with no recorded approval (`READY_NOT_APPROVED`).
   *The READY packet* is
   `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
   (the shape `packages/daemon/internal/prompts/roles/merger.md` defines), then the PR body's