@sjawhar/opencode-legion-envoy 0.15.0 → 0.17.0

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -1,255 +1,224 @@
 ---
 name: dispatch
-description: Use when you need a human decision from Sami or the user — asking a question, waiting on approval, saying "let me know", writing an end-of-message question block, picking between options with tradeoffs, or starting unattended/long-running work that will need input later. Raises the question as a durable GitHub-issue thread instead of a transcript question nobody will see.
+description: "Use when asking Sami a question, updating the spec, commenting on a document, attaching an artifact, or calling a dispatch_* tool."
 ---
 
 # Dispatch
 
-`dispatch` turns a question into a durable, dashboard-visible GitHub-issue thread instead
-of a line buried in a transcript. A thread is **one decision, held as a conversation**: it
-opens with your question, the human replies, and if the reply changes the question you ask
-again on the same thread. It closes when the decision is settled, not when the first reply
-lands. Use it any time you would otherwise leave a question for a human to notice on their
-own.
-
-## When to dispatch
-
-- Any question not answerable at the keyboard in seconds.
-- Anything decision-shaped: a fork in approach, a tradeoff only the human can weigh, an
-  approval gate.
-- Anything you would otherwise write as an end-of-message question block and hope someone
-  reads.
-- Before you park on a blocker. Never leave a session idle on an unasked question.
-- Unattended or long-running work (Legion roles, background agents) that will need input
-  later — dispatch the question as soon as you know you'll need it, don't wait to be asked.
-
-## When NOT to dispatch
-
-- A one-word clarification the human is actively typing with you right now, in the same
-  turn — use the built-in `ask` tool instead. `dispatch` is for questions the reader has
-  not seen your transcript for; `ask` is for questions inside a live conversation.
-- Anything you can resolve yourself from tools or repo context. Dispatch is for genuine
-  human decisions, not a substitute for research.
-
-## Writing for the reader
-
-The reader has not seen your transcript. They are looking at a card on a dashboard between
-other things, and they will answer the question you wrote, not the one you meant.
-
-- **No nouns you coined this session.** No "the list above", "those items", "lane B",
-  "the eval-set thing". No internal identifiers — eval-set ids, lane names, hashes,
-  session ids — unless the question is about them. Expand every identifier on first use.
-  GitHub references may be bare: `#482`, `acme-org/example-repo#17`, or a URL — the
-  dashboard unfurls them into their titles.
-- **Structure over paragraphs.** `context` is at most three short paragraphs or a bullet
-  list, one idea each: what you are doing, what you found, why you are stuck. `question`
-  is a list: current state → desired state → your recommendation and why; the options
-  themselves go in `ask`, each tradeoff as its `description`. Don't just describe the
-  fork — say which branch you'd take and why.
-- **Options are buttons.** If you are offering choices, put them in `ask`; never enumerate
-  them in prose. A human answers a button in one click and the answer arrives structured;
-  a choice buried in a paragraph arrives as a sentence you have to interpret.
-- **Length caps.** `context` is at most 1200 characters, `question` at most 800. The
-  service refuses a longer call before anything reaches GitHub, naming the field and the
-  limit (`context is 1450 characters; the limit is 1200`); nothing is truncated. When you
-  hit a cap: move the choices into `ask`, cut background the reader does not need to
-  decide, and if there really are two decisions, open two threads.
-
-### Before / after
-
-A real thread, as first written — one block, coined nouns, options in prose:
-
-```
-subject:  "e2e submitter"
-context:  "So I've been going through the e2e harness like we discussed and the submitter
-           identity thing from earlier is still broken because the fixture in lane B uses
-           the shared bot account which means the assertions in eval-set 7f3a can't tell
-           who submitted, and the thing I mentioned about the env var not being set in CI
-           is also true so basically the list above doesn't apply until we pick one, and I
-           looked at how the other repo does it and they hardcode it which is fine for them
-           but not us, also the token minting issue is related but separate."
-question: "should I add E2E_SUBMITTER_EMAIL or use the bot or something else? I think
-           probably the env var but not sure, or maybe the hardcode thing, or the third
-           option where the harness reads it from git config. Let me know."
-```
-
-The same decision, written for the reader:
-
-```
-subject:  "E2E harness: which identity submits test PRs?"
-context:  "- The end-to-end test harness (acme-org/example-repo#17158) submits PRs as the
-             shared bot account, so a run cannot tell test submissions apart from real ones.
-           - CI sets no submitter identity today; the harness has no setting for one."
-question: "- Current: every test PR is authored by the shared bot.
-           - Desired: each run's PRs carry an identity that marks them as test submissions.
-           - Recommendation: a dedicated identity from one CI environment variable —
-             smallest change, no per-machine setup."
-ask:      [{ header: "Test submitter identity",
-             question: "Which identity should the harness use?",
-             options: [
-               { label: "Env var E2E_SUBMITTER_EMAIL", description: "one CI variable; the harness reads it" },
-               { label: "Shared bot (status quo)",      description: "no change; runs stay indistinguishable" },
-               { label: "Read from git config",         description: "per-machine setup; drifts" } ] }]
-```
-
-## How
-
-### Opening a thread
-
-```
-dispatch({
-  subject:  "Postgres migration: run online or take a maintenance window?",
-  context:  "- Implementing the users-table index migration for #482.
-             - The table has 40M rows; a plain CREATE INDEX locks writes for ~6 minutes
-               in the staging timing test I just ran.",
-  question: "- Current: no online-migration tooling in this repo's deploy pipeline.
-             - Desired: index added without a customer-visible write outage.
-             - Recommendation: the maintenance window — smaller blast radius, no
-               migration-runner change, inside the existing SLA.",
-  ask:      [{ header: "Approach", question: "Which way?",
-               options: [
-                 { label: "CREATE INDEX CONCURRENTLY", description: "no lock, ~25 min, needs a migration-runner change" },
-                 { label: "6-minute window at 03:00 UTC", description: "runner unchanged, brief write outage" } ] }],
-  urgency:  "med"
+Dispatch is your issue's living spec, asks, comments, and artifacts. The transcript is your
+scratch pad. Anything meant for a human goes through a `dispatch_*` tool.
+
+The server enforces high signal: an ask question is at most 800 characters with at most eight
+options; comment and message bodies are at most 2,000 characters; an artifact is at most 25 MiB.
+It refuses over-limit input; it never truncates it. GitHub threads and markers no longer exist.
+
+## Your issue
+
+Every session works on an issue. Legion pre-fills `issue` from `LEGION_ISSUE`: use a native issue key
+such as `LEGION-3`, an external `owner/repo#n` reference, or a bare positive number (resolved
+against the cwd repository). Otherwise pass the issue to every issue-scoped tool as its native key
+or an external `owner/repo#n` reference. On first use, an external reference creates its native issue in the
+project mapped by `DISPATCH_REPO_PROJECTS`.
+
+Architects create newly tracked child work with:
+```ts
+dispatch_issue({ project, title, parent?, external?, spec? })
+```
+It returns `details` `{ issue, topic }`. Use `dispatch_issue` only to create an issue; never use
+it to park a question.
+
+## Asking
+
+Open a decision with:
+```ts
+dispatch_ask({
+  issue,
+  question,
+  options?: { label, description? }[],
+  multiple?,
+  custom?,
+  urgency?,
+  anchor?: { artifact, quote, occurrence? },
 })
 ```
+It returns `details` `{ issue, topic, ask }`. Options are buttons: never enumerate choices in
+prose. Put the recommendation in `question`, and put each selectable choice in `options`.
+Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence` is
+zero-based and selects a repeated quote. An anchor whose quote disappears becomes orphaned but
+remains readable against its original document version. An ask stays open until a human answers;
+you cannot withdraw it. Ask once and well. The host steers you when a human answers.
+## The spec is where narrative goes
+
+Read the current document before changing it:
+
+```ts
+dispatch_doc_read({ issue?, artifact?, version?, ref? })
+```
+It returns live or versioned markdown with open marks and `details` `{ issue }`; omit `artifact`
+with `issue` to read the primary document. Then write narrative with:
 
-- `subject`: one line, the decision — this is the issue title and the dashboard row.
-- `context` (required, ≤ 1200 chars): what you are doing, what you found, why you are stuck.
-- `question` (required, ≤ 800 chars): current → desired → recommendation (options live in
-  `ask`).
-- `ask` (optional): a list of `{ question, header?, options: [{ label, description? }],
-  multiple?, custom? }`. These render as buttons, always with an "Other (specify)"
-  free-text field beside them (`custom` does not change this); a plain reply on the thread
-  is also possible but arrives unstructured.
-- `urgency` (optional, default `med`): `low` — whenever convenient; `med` — needed today;
-  `high` — something will stall soon; `blocking` — you cannot proceed at all right now.
-- `repo` (optional): only to target a **different** repo than your working directory's
-  GitHub remote; the tool fills it from the cwd otherwise.
-- `parent` (optional): only when a real issue exists to attach to — `<n>` in the resolved
-  repo or `owner/name#<n>` elsewhere; `owner/name#<n>#<commentId>` also appends a
-  breadcrumb to that comment. For Legion roles, `parent` is the root issue you're working
-  under. Omitting it creates a standalone thread; don't invent a parent.
-
-The tool returns `{"thread": N, "url": "..."}`; that URL is the durable record.
-
-### Continuing a thread
-
-When the reply changes the question — the human challenged the premise, ruled out your
-recommendation, or asked for a variant you had not offered — re-ask **on the same thread**:
-
-```
-dispatch({
-  thread:   "482",                      // or "owner/name#482"
-  context:  "- You ruled out the maintenance window: the 03:00 UTC slot is now used by
-               the nightly export.
-             - CONCURRENTLY needs the migration runner to run outside a transaction.",
-  question: "- Current: the runner wraps every migration in a transaction.
-             - Desired: this one index built online.
-             - Recommendation: a one-off flag on the runner for non-transactional
-               migrations, used only by this migration.",
-  ask:      [{ header: "Runner change", question: "Add the non-transactional flag?",
-               options: [{ label: "Yes, one-off flag" }, { label: "No, hand-run the index" }] }]
-})
+```ts
+dispatch_doc_edit({ issue, artifact, ops, summary? })
 ```
+It returns `details` `{ issue, topic, applied, version? }`. `ops` is an array of this exact
+`EditOp` shape:
+
+```ts
+type EditOp = {
+  op: "replace" | "delete" | "insert";
+  find?: string;
+  with?: string;
+  occurrence?: number;
+  markdown?: string;
+  after?: string;
+  before?: string;
+};
+```
+
+Target edits by quote: `replace` requires `find` and `with`; `delete` requires `find`; `insert`
+requires `markdown` and exactly one of `after` or `before`. An insert anchor is a quote,
+`"start"`, `"end"`, or `"heading:Title"`. Use zero-based `occurrence` for a repeated `find`.
+When a decision lands, pass `summary` to name the resulting version. Never paste progress into a
+message.
+
+## Comments and suggestions
+
+Add feedback with:
+
+```ts
+dispatch_comment({ issue, artifact?, quote?, occurrence?, body, reply_to? })
+```
+
+It returns `details` `{ issue, topic, comment }`. `quote` requires `artifact`; omit both for a
+floating issue comment. Use `reply_to` to continue a comment.
 
-- `thread` replaces `subject`; `urgency`, `repo`, and `parent` are not accepted with it.
-  `thread` names an open issue in the repo; a plain work issue is adopted as a thread on
-  first use. The issue must be open and not a pull request, or the tool says so
-  (`#N is not a dispatch thread`, `#N is closed; open a new thread`).
-- Same decision → same thread. A genuinely new decision → a new thread, even if it came
-  up in the reply.
-- **A follow-up supersedes the thread's earlier unanswered questions.** The dashboard
-  offers an answer only for the latest turn; earlier open questions read "superseded by a
-  later follow-up". If an earlier question still stands, restate it in the follow-up's
-  `ask` list. A follow-up with no `ask` list is one free-text question — the text under
-  its `## Question` — and the human answers it in prose.
-- **Ask once.** An unanswered question is not a reason to post again. New facts that do
-  not change the decision go in a plain `gh issue comment` on the thread, not a new
-  `dispatch` call; a follow-up is for a changed question. A thread that fills with
-  restated asks is noise for the human and hides the decision it is waiting on.
-- **Read a challenge as an answer.** "Why not the bot?" is not a request for more prose;
-  it is the human declining your framing. Say what you now know, then ask the narrowed
-  question with new options — unless the challenge itself decides ("Why not the bot? Just
-  use the bot."), in which case act on it and re-ask nothing. A follow-up carries your
-  session's identity, so the human sees which conversation is asking even after a handoff.
-- The tool returns `{"thread": N, "url": "...", "comment": "..."}`.
+Propose an exact replacement instead of describing it:
 
-## After dispatching
+```ts
+dispatch_suggest({ issue, artifact, quote, replace_with, body?, occurrence? })
+```
+
+It returns `details` `{ issue, topic, comment }`. A human accepts or rejects a suggestion. On
+`TARGET_AMBIGUOUS`, add zero-based `occurrence`. On `TARGET_NOT_FOUND`, re-read the document
+before retrying. `INVALID_OP` names a malformed edit; `CAP_EXCEEDED` never truncates;
+`ISSUE_CLOSED` rejects a write. `ACTOR_KIND`, `ROUTE_INVALID`, and `PRIMARY_NOT_DOC` reject an
+invalid actor, route, or primary artifact.
 
-The reply arrives back in your own session as a steer — you do not fetch it. Keep every
-other non-blocked lane of work moving while you wait; a dispatch is not a reason to go
-idle. Never poll GitHub for the reply and never set up a watcher, cron, or retry loop to
-check on it — the delivery mechanism is already push-based. Each answer names the question
-it answers, so a thread with two open questions delivers two steers.
+## Artifacts
 
-If the tool errors because it can't resolve a repo (cwd has no GitHub remote and no
-qualified `parent` or `thread`), pass `repo=owner/name` (opening) or
-`thread=owner/name#<n>` (continuing) and retry.
+Attach an image, diagram, or file with:
 
-**Named risk:** a thread created in a repo where the Envoy GitHub App is not installed
-gets created successfully, but replies to it never route back to your session — you'll
-wait forever for a steer that can't arrive. The App is installed per account and per repo,
-not org-wide, and coverage changes; before relying on a reply from a repo you have not
-dispatched to before, check it: `gh api /repos/<owner>/<name>/installation` returns 200 when
-the App is installed there and 404 when it is not.
+```ts
+dispatch_artifact({ issue, name, path, primary?, summary? })
+```
 
-## Manual fallback: the marker format
+It returns `details` `{ issue, topic, artifact, version }`. `path` is the local file to upload.
+Uploading the same `name` creates its next version. Set `primary: true` only for a markdown file
+to make it the issue's spec.
 
-If the tool itself is unavailable, the dashboard still understands a hand-written turn.
-Every dispatch marker is an HTML comment at the very start of the body — invisible on
-GitHub — followed by a blank line and the readable text.
+## Messages
 
-A follow-up question, posted with `gh issue comment <n> --body-file <file>`:
+Use the escape valve only for a note that fits nowhere else:
 
+```ts
+dispatch_message({ issue, body })
 ```
-<!-- dispatch:ask
-requestId: <16 lowercase hex chars, unique to this follow-up>
-ask:
-    - askId: <the same 16 chars>
-      question: <the question>
-      header: <short header>
-      options:
-        - label: <label>
-          description: <one line>
--->
 
-## Context
+It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 characters. Your
+message does not wake anyone. Do not use it for status, a decision, or document feedback.
 
-<context>
+## What comes back
 
-## Question
+A write result's `details.topic` subscribes the host to the issue. Events render as:
 
-<question>
+```text
+dispatch <KEY> · <type> · by <actor>
 ```
 
-A new thread, posted with `gh issue create --label dispatch-thread --title "<subject>" --body-file <file>`:
+Human-authored events reach you, except an unnamed artifact version; child-status events also
+reach you. Session-authored events never wake sessions. After a restart, catch up with:
+
+```ts
+dispatch_read({ issue?, ref? })
+```
+
+With an issue ref, it returns the issue summary, open asks, and recent events with `details`
+`{ issue }`. With an ask ref, it returns that ask's question, options, state, and answer. With a
+comment ref, it returns that comment and its quoted reply chain. Use `dispatch_doc_read` for
+document contents.
+
+## References
 
+Use these in document, ask, comment, and message bodies; Dispatch unfurls them:
+
+```text
+dispatch://KEY
+dispatch://KEY/spec
+dispatch://KEY/artifact/<slug>[@vN]
+dispatch://KEY/ask/<id>
+dispatch://KEY/comment/<id>
 ```
-<!-- dispatch:thread
-requestId: <16 lowercase hex chars>
-urgency: med
-ask:
-    - askId: <the same 16 chars>
-      question: <the question>
-      options:
-        - label: <label>
--->
 
-**<subject>**
+## Before / after
 
-## Context
+Before — a wall of text hides the decision and makes the choices unclickable:
 
-<context>
+```text
+We need to settle the release gate because the deploy branch has the migration and the
+dashboard changes, I checked the staging result and it is fine except the release notes are
+not reviewed, so should we ship today, wait for docs, or cut the dashboard from this release?
+I think waiting is safest but the customer demo is tomorrow and the list above is probably stale.
+```
 
-## Question
+After — anchor the decision and make each option a button:
+
+```ts
+dispatch_ask({
+  issue: "LEGION-815",
+  question:
+    "Choose the release gate. Recommendation: ship after release-note review because the tested deployment is otherwise ready.",
+  options: [
+    {
+      label: "Review notes, then ship",
+      description: "Keeps the tested release intact and publishes reviewed instructions.",
+    },
+    {
+      label: "Ship now",
+      description: "Meets the demo deadline; release notes follow separately.",
+    },
+    {
+      label: "Remove dashboard changes",
+      description: "Narrows the release but requires another deployment test.",
+    },
+  ],
+  custom: false,
+  urgency: "high",
+  anchor: {
+    artifact: "spec",
+    quote: "Release requires reviewed operator instructions before deployment.",
+  },
+})
+```
 
-<question>
+Before — a status message loses the durable outcome:
+
+```text
+Done, PR merged.
 ```
 
-`ask` may be omitted when there are no buttons to offer. A second ask on the same turn has
-`askId: <requestId>.1`, a third `.2`. A hand-posted turn carries no `origin`, so the
-dashboard cannot say which session asked, and nothing subscribes your session to a
-hand-created thread — subscribe it yourself with `envoy_subscribe` to
-`notifications.github.<owner>.<name>.issue.<n>.>` or the reply never arrives. Prefer the
-tool.
+After — record the result in the spec and name its version:
+
+```ts
+dispatch_doc_edit({
+  issue: "LEGION-815",
+  artifact: "spec",
+  ops: [
+    {
+      op: "replace",
+      find: "## Delivery\n\nRelease pending.",
+      with: "## Delivery\n\nRelease merged and ready for deployment.",
+    },
+  ],
+  summary: "Recorded merged release",
+})
+```

package/skills/legion-architect/SKILL.md

@@ -14,12 +14,22 @@ separate coordinator to finish necessary work.
 
 - Use the `legion` tool for lifecycle writes. Its issue key format is
   `owner/repo#number`.
-- Use `task` for every Legion role spawn and `hub` to direct or revive a known phase
-  worker. Phase workers escalate lifecycle, scope, and cross-phase matters inward to you
-  through hub. Any role may use `dispatch` directly for a standalone human question;
-  replies return to the asking session.
-- The runtime, not you, appends a machine `<legion-spawn>` block. Each Legion `task`
-  text must start with `Legion-Issue: <owner/repo#n>` on its first line.
+- Use `legion({ op: "spawn_worker", issue, role, task })` for every Legion role spawn.
+  Message a known phase worker with `envoy_publish` to `notifications.role.` followed by
+  its encoded role token (the token `spawn_worker` returned for it); re-assign it by
+  calling `spawn_worker` again on the same existing role, which resumes the same process
+  instead of starting a fresh one. Phase workers escalate lifecycle, scope, and
+  cross-phase matters the same way: `envoy_publish` to your own encoded token. Any role
+  may use `dispatch` directly for a standalone human question; replies return to the
+  asking session.
+- The daemon spawns each role as its own process with the issue's context already in its
+  environment. Never hand-format a role token: the daemon encodes one as
+  `legion-<project>-<encoded-owner>__<encoded-repo>-<number>-<role>` (escaping `_`, `.`,
+  and `-` within the owner/repo names); for example, project `acme`, issue
+  `sjawhar/legion#41`, role `architect` encodes to `legion-acme-sjawhar__legion-41-architect`.
+  Reuse a token you already hold (your own, or one `spawn_worker` returned) or compute
+  another with the `roleToken` helper from `@legion/contracts` exactly the way the daemon
+  does.
 - Use only the live label vocabulary: `needs-approval`, `human-approved`,
   `legion-child`, and `legion-backlog`. Do not attempt to apply a label whose ownership
   belongs to the controller or Sami.
@@ -30,12 +40,16 @@ separate coordinator to finish necessary work.
 ## 1. Decompose or adopt
 
 Inspect the root issue, acceptance criteria, existing children, and current handoffs.
+Decomposition is complete only when every child issue names the real surface its acceptance
+criteria are proven on and the repository skill that drives it; if the repository cannot
+exercise a criterion end to end, building that path is a child issue of this tree.
 
 - **Existing children:** adopt them. Do not replace or re-decompose human-created work.
   Put every adopted child into the initial wave. **You MUST call**
   `legion({ op: "wave_release", children: ["owner/repo#41", "owner/repo#42"] })`
-  **before any `task` spawn for an adopted child.** Until release, the daemon holds that
-  child's role activity. Then spawn each child's in-process `legion-architect` owner.
+  **before any `spawn_worker` call for an adopted child.** Until release, the daemon
+  holds that child's role activity. Then spawn each child's daemon-managed sub-architect
+  owner.
 - **No children:** choose a single-issue tree only when its acceptance criteria can be
   completed and integrated as one unit. Otherwise create complete child issues with:
 
@@ -81,32 +95,37 @@ explicit lifecycle write:
 legion({ op: "wave_release", children: ["owner/repo#41", "owner/repo#42"] })
 ```
 
-After release, spawn each relevant owner with an issue-prefixed task; for example:
+After release, spawn each relevant owner; for example:
 
 ```text
- task({
-   agent: "legion-architect",
-   task: "Legion-Issue: owner/repo#41\nOwn this child through its lifecycle and report its evidence."
- })
+legion({
+  op: "spawn_worker",
+  issue: "owner/repo#41",
+  role: "architect",
+  task: "Own this child through its lifecycle and report its evidence."
+})
 ```
 
-Do not add a `<legion-spawn>` block. Keep the child agent IDs and session identifiers
-returned by `task`, because retro and adjustment use those live sessions. Park while
-children are in flight. On each child closure, re-scope open work, close obsolete work
-with a reason, and release the next wave only when it now makes sense. There is no
-inter-child dependency mechanism to encode.
+The daemon spawns that sub-architect as its own process with the child's context already
+in its environment; a resume of an existing role continues the same process instead of
+starting a fresh one. Keep the returned session identifiers, because retro and adjustment
+use those live sessions. Park while children are in flight. On each child closure,
+re-scope open work, close obsolete work with a reason, and release the next wave only
+when it now makes sense. There is no inter-child dependency mechanism to encode.
 
 ## 3. Children complete
 
 Treat `children-complete` as the edge into the end-game, not as a reason to close the
-parent. Launch one **fresh** `legion-tester` for the parent, scoped to the parent's own
-acceptance criteria and current `main` integration surface:
+parent. Spawn the parent's `tester` role, scoped to the parent's own acceptance criteria
+and current `main` integration surface:
 
 ```text
- task({
-   agent: "legion-tester",
-   task: "Legion-Issue: owner/repo#40\nFreshly verify this parent issue against its acceptance criteria on current main; return reproducible integration evidence."
- })
+legion({
+  op: "spawn_worker",
+  issue: "owner/repo#40",
+  role: "tester",
+  task: "Verify this parent issue against its acceptance criteria on current main; return reproducible integration evidence."
+})
 ```
 
 If that tester finds a failure, create and release a new corrective child wave, then
@@ -115,25 +134,25 @@ failure forward.
 
 ## 4. Integration verification
 
-Read the fresh tester's evidence, not merely a child PR's check status. The parent test
+Read the tester's evidence, not merely a child PR's check status. The parent test
 is successful only when every parent acceptance criterion has evidence against current
 main. Route a failed criterion into a corrective child wave; route a passing result to
 review and the merge-gate sequence.
 
 ## 5. Retro
 
-Retro is mandatory for every issue that passed review, before merge. Revive the parked
-implementer that owns the reviewed work through `hub`, naming the skill in the message:
+Retro is mandatory for every issue that passed review, before merge. Message the
+implementer's live session (idle since it completed its phase; the daemon never tears
+it down) with `envoy_publish` to its role token, naming the skill:
 
 ```text
-hub({
-  op: "send",
-  to: "<implementer agent identifier>",
+envoy_publish({
+  topic: "notifications.role.<implementer's encoded token>",
   message: "Run the legion-retro skill now. Capture durable learnings and post the issue comment; do not create a .legion handoff file."
 })
 ```
 
-Wait for the revived implementer to report its durable retro result. Retro output is
+Wait for the messaged implementer to report its durable retro result. Retro output is
 `docs/solutions/` plus an issue comment; it must not create a `.legion` file or change
 the reviewer-approved head after cleanup.
 
@@ -154,10 +173,11 @@ When the config-armed final merge gate applies, preserve this order exactly:
    approval already satisfies the gate and you immediately continue to the merger; do not
    wait for a new wake. If it returns `approved: false`, request or retain Sami approval
    and park for a later `pr-ready` wake. Do not poll or retry this check;
-5. `legion-merger` verifies the approved head and squash-merges without pushing.
+5. The merger verifies the approved head and publishes `READY #<n> at <sha>` to
+   `notifications.role.pr-queue`; it never merges. The merge queue approves and merges under its own authority.
 
-If anything changes the approved head, return to review; do not ask the merger to merge
-an obsolete approval.
+If anything changes the approved head, return to review; do not let the merger publish
+`READY` for an obsolete approval.
 
 ## 7. Close
 
@@ -183,14 +203,17 @@ corresponding lifecycle procedure.
 | Wake | Procedure |
 | --- | --- |
 | `child-closed` | Read the child completion and remaining open children. Re-scope or close obsolete open work; release an appropriate next wave, or await `children-complete`. |
-| `children-complete` | Execute steps 3–4: fresh parent integration verification; failures become a new child wave, success advances to review and retro. |
+| `children-complete` | Execute steps 3–4: parent integration verification; failures become a new child wave, success advances to review and retro. |
 | `child-reopened` | Treat the completion edge as reset. Reassess the reopened child and return the tree to children-in-flight; do not continue an already-started end-game. |
+| `phase-complete` | Payload `{type:"phase-complete", issue, role, summary}`. May arrive live or via `catchup-overseer`'s `phaseCompletions`. Read the committed handoff for that phase, then spawn the next phase's owner, or `spawn_worker` on the same role again to resume it with corrections if the handoff shows unresolved gaps. |
+| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. The deployment's worker cap is full; this role's spawn is queued. Do not respawn or retry — wait for `worker-started`. |
+| `worker-started` | Payload `{type:"worker-started", issue, role}`. A previously queued role has been promoted and is now running. Treat it exactly as a normal spawn: resume tracking that role's live session. |
 | `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/Sami/merger order only for that current head. |
 | `pr-blocked` | Read the failed CI evidence and recovery attempts. Assign a focused implementer or corrective child, then return it through testing and review; do not treat the blocked PR as final. |
 | `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 through `hub` to the responsible worker; 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. |
-| `revive-worker` | The extension has revived the backed worker. Do not create a duplicate; direct the restored worker through `hub` if action is needed and rely on its committed handoff over recollection. |
+| `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. 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. |
+| `revive-worker` | The extension has revived the backed worker. Do not create a duplicate; message the restored worker via `envoy_publish` to its role token if action is needed and rely on its committed handoff over recollection. |
 | `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-retro/SKILL.md

@@ -19,7 +19,7 @@ retrospective's durable output.
 3. Run this retro: commit durable learnings to `docs/solutions/` and post the issue comment.
    Retro writes **no `.legion` file**, so it never re-dirties the cleaned handoff tree.
 4. Sami approves the final reviewed head.
-5. The merger squash-merges and pushes nothing.
+5. The merger verifies the approved head, publishes `READY`, and pushes nothing; the merge queue merges.
 
 Do not start retro before step 2, skip it because the change seems mechanical, or merge before
 steps 3 and 4. The design gate is not a substitute for this final merge gate.