@sjawhar/opencode-legion-envoy 1.21.0 → 1.22.0

package/dist/src/server.js

@@ -16031,10 +16031,16 @@ class EnvoyApiError extends Error {
     this.expected = parsed?.expected;
   }
 }
+function resolveEnvoyToken(env) {
+  const { ENVOY_TOKEN_FILE: file, ENVOY_TOKEN: plain } = env;
+  if (file !== undefined && file !== "")
+    return readSecretFile("ENVOY_TOKEN_FILE", file);
+  return plain || undefined;
+}
 function createEnvoyClient(config) {
   const baseUrl = normalizeEnvoyUrl(config.baseUrl);
   const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const { ENVOY_TOKEN: apiToken } = process.env;
+  const apiToken = resolveEnvoyToken(process.env);
   const request = async (path, init) => {
     const url = `${baseUrl}${path}`;
     for (let attempt = 0;attempt < 2; attempt += 1) {

package/package.json

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

package/skills/envoy/SKILL.md

@@ -148,11 +148,16 @@ not construct a token from a partial issue reference.
 
 ## Legion exception lane
 
-`no_holder` and `delivery_failed` for a Legion role are daemon liveness signals, not reasons to
-add a second subscriber or manually retry. For example, treat a `delivery_failed` wake as the
-daemon's responsibility to revive or recreate the backing worker and re-deliver; otherwise it
-resurrects the root process with derived catch-up and the workspace handoffs. Raw delivery failures
-stay out of architect context.
+`no_holder`, `delivery_failed`, and `receipt_timeout` for a Legion role are daemon liveness
+signals, not reasons to add a second subscriber or manually retry. `no_holder`: no live session
+holds the role. `delivery_failed`: the message was not forwarded at all — the holder lookup
+failed, the holder was stale, or the publish errored. `receipt_timeout`: the listener forwarded
+the message to a registered, live holder and no receipt arrived inside the window; its payload
+keeps `original_topic`, `event_id`, `payload`, and the original `dedupe_key`, so the daemon can
+re-send the same message and the receiver's dedupe drops a copy that did arrive. Treat any of
+these wakes as the daemon's responsibility to revive or recreate the backing worker and
+re-deliver; otherwise it resurrects the root process with derived catch-up and the workspace
+handoffs. Raw delivery failures stay out of architect context.
 
 ## Slack
 

package/skills/legion-architect/SKILL.md

@@ -285,7 +285,11 @@ entire end-game sequence has completed.
 ## Wake routing
 
 Handle one delivered wake by verifying the relevant live artifact and then performing the
-corresponding lifecycle procedure.
+corresponding lifecycle procedure. Architect-addressed wakes always reach the architect that owns
+the payload issue: a claimed child sub-architect, otherwise the nearest claimed ancestor, then the
+root. A wake about an architect role's own launch reaches the architect above it. `phase-complete`,
+worker lifecycle, child lifecycle, and design-gate wakes are architect-only and never go to an
+active phase worker.
 
 | Wake | Procedure |
 | --- | --- |
@@ -305,8 +309,8 @@ corresponding lifecycle procedure.
 | `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The merge queue landed the PR. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether to reopen the work, send a fresh implementer, or cancel it with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
 | `issue-comment` | Interpret the comment in the issue's design context. Answer it, adjust the plan, or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
-| `catchup-overseer` | Verify its gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. `gates[LEGION_TREE].open` is the design gate's current state: `true` means the root spec is approved at its current version and you may spawn; `false` (or no `open` key, meaning no gate is registered) means the sequence in section 1 still applies. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. Then compare `childCounts[LEGION_ISSUE].open` (the children not `done`) with `legion state` and Dispatch: any **open** released child — `todo` through `retro` — with no architect role claim gets `spawn_worker` for its architect, a `child-adopted` or `child-status` wake you missed while not live; a `done` child gets nothing, whether or not a lingering legacy tree of its own still shows in `legion state`. |
-| `worker-died` | Payload `{type:"worker-died", issue, role}`. The daemon probed and retried this role's worker through `MAX_LAUNCH_FAILURES` attempts and could not confirm a boot — never a raw-event replay or a silent revive. Reassess the work and `spawn_worker` again for the role (it resumes the same agent via `--resume` if a session file survived) or reassign it if the failure looks environmental, not agent-specific. |
+| `catchup-overseer` | Verify its child counts and PR verdicts against current artifacts, then resume the applicable lifecycle step. This is a current-state snapshot, not a raw-event replay. A root architect uses `gates[LEGION_TREE].open`: `true` means the root spec is approved and section 2 may continue; `false`, or no `open` key, means section 1 still applies. A resumed sub-architect receives `overseerCatchup(state, LEGION_ISSUE)` for its own subtree: its `gates` intentionally omits the root gate because a child spec is never gated. Do not request or register a gate; resume at section 2. Handle each `phaseCompletions` entry exactly as a `phase-complete` wake, then compare `childCounts[LEGION_ISSUE].open` with `legion state` and Dispatch before deciding the next action. |
+| `worker-died` | Payload `{type:"worker-died", issue, role}`. Two causes, one verdict: the daemon retried this role's boot through `MAX_LAUNCH_FAILURES` attempts and could not confirm it, or the worker booted and acknowledged every prompt without ever starting a turn through `MAX_PROMPT_RETIRES` retire-and-relaunch cycles (LEGION-93) — never a raw-event replay or a silent revive. Your next `spawn_worker` for the role is the retry (one cold launch, three prompts, and `worker-died` again if the agent is still broken). Reassess the work and `spawn_worker` again for the role (it resumes the same agent via `--resume` if a session file survived) or reassign it if the failure looks environmental, not agent-specific. |
 | `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |
 
 ## Escalation judgment

package/skills/legion-controller/SKILL.md

@@ -62,7 +62,8 @@ override a Sami ruling quoted here.
 | New issue created in the Dispatch project (`issue.created`, status `triage`; resync heals misses) | issue key + triage context (incl. pre-existing children) | Triage: `legion({ op: "set_status", issue, status: "todo" })` to admit, or set `backlog`/`icebox` to park |
 | Backlog eligibility | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch_ask` from the owning architect, not here |
-| Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed) | Verify against fresh state, then heal |
+| Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed, admission-drift) | Verify against fresh state, then heal |
+| Resync report: `admission-drift` entry | issue key + whether the daemon added it to, or removed it from, its admission list (the detail says which) | No action: the daemon already repaired it in the same run. An issue that reappears in consecutive reports is a live leak — file a LEGION issue on Dispatch with both reports pasted as evidence (never a GitHub issue) |
 | `child-status` | child key + status transition | Not controller-actionable by default; if the daemon could not route it to the parent's architect role, verify the transition and forward it with `envoy_publish` |
 | Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
 | Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion({ op: "set_status", issue: root, status: "todo" })`; otherwise no action — the event is not held or redelivered |
@@ -124,7 +125,10 @@ Treat a resync report as an anomaly list, not an instruction. For every zero-own
 untriaged-open, or launch-failed issue it names, verify `legion state --json` and the
 current Dispatch issue first. Then heal the verified condition: admit an eligible root, move
 an issue back to its intended status, or use the applicable daemon control path. Do not act
-on stale entries until their source artifact explains the anomaly.
+on stale entries until their source artifact explains the anomaly. An `admission-drift` entry
+needs no healing — the daemon added the tree back to (or removed it from) its admission list in
+the same run; verify only that the same issue does not recur in the next report, and file a
+LEGION issue with both reports if it does.
 
 ## Mentions
 

package/skills/legion-worker/SKILL.md

@@ -22,13 +22,14 @@ completes the boot handshake for you at session start — it registers with the
 your role, and signals readiness. You never call `envoy_role_set` yourself.
 
 Your role token is not the issue key spelled out literally. The daemon encodes it as
-`legion-<project>-<KEY>-<role>`. For example, project `acme`, issue `LEGION-41`, role
-`architect` encodes to `legion-acme-LEGION-41-architect`. Never hand-format one for another
-role: your own role topic and your tree's architect's topic are stated at the end of your
-system prompt (a "Legion addressing" line the daemon appends), a sibling role's topic is
-yours with the trailing `-<role>` replaced, and the `roleToken` helper in `@legion/contracts`
-computes any other one exactly the way the daemon does — prefer a topic you've already
-been given before recomputing one.
+`legion-<project>-<KEY>-<role>`. For example, project `acme`, issue `LEGION-41`, role `architect`
+encodes to `legion-acme-LEGION-41-architect`. Never hand-format one for another role: your own role
+topic and the topic of the architect that owns your issue are stated at the end of your system
+prompt (a "Legion addressing" line the daemon appends: on a child issue that is the child's
+sub-architect when one is claimed, else the root's), a sibling role's topic is yours with the
+trailing `-<role>` replaced, and the `roleToken` helper in `@legion/contracts` computes any other
+one exactly the way the daemon does — prefer a topic you've already been given before recomputing
+one.
 
 If the handshake fails (a rejected boot token, or a bootstrap failure after your role
 registered), the extension logs it and exits the process outright — it does not retry, and