@sjawhar/opencode-legion-envoy 1.13.1 → 1.14.1

package/dist/src/server.js

@@ -13594,6 +13594,11 @@ var askEventPayloadFields = {
   question: string2().optional(),
   options: array(object({ label: string2().optional() })).nullish(),
   answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish(),
+  anchor: object({
+    quote: string2().optional(),
+    mark_id: string2().optional(),
+    block_id: string2().nullable().optional()
+  }).passthrough().nullish(),
   resolution: object({
     kind: _enum2(["retracted", "resolved"]).optional(),
     reason: string2().optional(),
@@ -13628,7 +13633,7 @@ var CommentEventPayloadSchema = object({
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   ask_state: _enum2(["open", "answered", "resolved"]).optional(),
-  anchor: object({ quote: string2().optional() }).nullish(),
+  anchor: object({ block_id: string2().nullable().optional(), quote: string2().optional() }).nullish(),
   suggestion: object({ replace_with: string2().optional() }).nullish(),
   author: object({ kind: string2(), id: string2() }).optional(),
   created_at: string2().optional()
@@ -13658,7 +13663,9 @@ var ChildStatusEventPayloadSchema = object({
 var SubscriptionRemovedEventPayloadSchema = object({
   session_id: string2().optional(),
   by: object({ kind: string2(), id: string2().optional() }).passthrough().optional(),
-  topics: array(string2()).optional()
+  topics: array(string2()).optional(),
+  pending: boolean2().optional(),
+  request_event_id: number2().int().positive().optional()
 });
 // ../contracts/src/dispatch-snippet.ts
 var HTML_ENTITIES = [
@@ -13760,7 +13767,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_ask",
-    description: "Open a durable, answerable decision or human to-do on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. Use kind: action for a to-do a human must complete; it has fixed Done / Can't answers. " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". Question is at most 800 ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
+    description: "Open a durable, answerable decision or human to-do on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. Use kind: action for a to-do a human must complete; it has fixed Done / Can't answers. " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + 'reference \u2014 it must be answerable from its own text and anchor alone, never "see above". A quote anchor is pinned to its block. Question is at most 800 ' + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -13814,7 +13821,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_comment",
-    description: "Add review feedback to an issue or project document quote, or reply to a question asked with dispatch_ask. " + "Do not use it for an exact replacement; use " + `dispatch_suggest instead. Body is at most 2,000 characters. ${OWNER_REFERENCE}`,
+    description: "Add review feedback to an issue or project document quote, or reply to a question asked with dispatch_ask. " + "Do not use it for an exact replacement; use " + `dispatch_suggest instead. A quote anchor is pinned to its block. Body is at most 2,000 characters. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -14611,6 +14618,11 @@ function asErrorShape(value) {
 function isJson(response) {
   return response.headers.get("content-type")?.includes("application/json") ?? false;
 }
+var DISPATCH_TOOL_DEADLINE_MS = 60000;
+function requestSignal(signal) {
+  const deadline = AbortSignal.timeout(DISPATCH_TOOL_DEADLINE_MS);
+  return signal === undefined ? deadline : AbortSignal.any([signal, deadline]);
+}
 
 class DispatchClient {
   token;
@@ -14618,10 +14630,12 @@ class DispatchClient {
   #baseUrl;
   #resolvedIssues = new Map;
   #creatingIssues = new Map;
-  constructor(baseUrl, token, fetchImpl = fetch) {
+  #signal;
+  constructor(baseUrl, token, fetchImpl = fetch, signal) {
     this.token = token;
     this.fetchImpl = fetchImpl;
     this.#baseUrl = baseUrl.replace(/\/+$/, "");
+    this.#signal = requestSignal(signal);
   }
   async issue(input) {
     return this.#json("POST", ["api", "v1", "issues"], input);
@@ -14833,6 +14847,7 @@ class DispatchClient {
     const response = await this.fetchImpl(this.#url(path, query), {
       method,
       headers,
+      signal: this.#signal,
       ...body === undefined ? {} : { body: JSON.stringify(body) }
     });
     return this.#response(response);
@@ -14841,7 +14856,8 @@ class DispatchClient {
     const response = await this.fetchImpl(this.#url(path), {
       method,
       headers: { Accept: "application/json", Authorization: `Bearer ${this.token}` },
-      body
+      body,
+      signal: this.#signal
     });
     return this.#response(response);
   }
@@ -15306,7 +15322,7 @@ async function executeDispatchTool(input) {
   const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec);
   const args = toolSchema(input.tool).parse(ownerArguments.args);
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
-  const client = new DispatchClient(configUrl, configToken, input.fetchImpl);
+  const client = new DispatchClient(configUrl, configToken, input.fetchImpl, input.signal);
   const owner = ownerArguments.owner?.kind === "issue" ? {
     kind: "issue",
     issue: await ensureIssue(client, ownerArguments.owner.issue, actor)
@@ -15889,7 +15905,7 @@ class EnvoyApiError extends Error {
 function createEnvoyClient(config) {
   const baseUrl = normalizeEnvoyUrl(config.baseUrl);
   const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const apiToken = process.env["ENVOY_TOKEN"];
+  const { ENVOY_TOKEN: apiToken } = 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.13.1",
+  "version": "1.14.1",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -127,8 +127,10 @@ recommendation and its reason last, in `question`. Never put file paths, line nu
 numbers, document versions, or role tokens in the question; if the human needs that detail, anchor
 the ask to the document passage instead. Apply the phone test from "Writing for the human" before
 posting. Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence`
-is zero-based and selects a repeated quote, and an anchor whose quote later disappears becomes
-orphaned but stays readable against its original document version.
+is zero-based and selects a repeated quote. A quote anchor is pinned to its lowest complete
+containing block while retaining its quote as display text, so rewording the passage keeps it
+attached; a quote spanning top-level blocks, and existing anchors without a block, stay readable
+against their original document version if their quote disappears.
 
 An ask must be answerable from its own text and its anchor alone. Anchor a question about a document passage with `anchor`; thread one
 about a comment with `reply_to`; thread a follow-up on your own ask with `reply_to_ask`; cite anything else with a `dispatch://`
@@ -163,7 +165,8 @@ dispatch_edit_ask({
 })
 ```
 At least one field besides `ask` is required. Use this only while the same decision remains open: it keeps the prior text in the event
-log. An answered or resolved ask cannot be edited. If the decision is moot or superseded, retract the old ask and open a new one.
+log and invalidates any answer draft against the prior `edited_at` revision, so the human sees the new wording and explicitly reconfirms.
+An answered or resolved ask cannot be edited. If the decision is moot or superseded, retract the old ask and open a new one.
 
 An ask stays open until a human answers, unless its question no longer needs that answer. Retract a moot or superseded question, or
 self-resolve one after finding the answer:
@@ -179,10 +182,11 @@ in its Conversation card and reply thread. Resolution is not an answer: it never
 resolved. A human may reply to an open or answered ask; so may you, e.g. after finding the answer — use `reply_to_ask` on
 `dispatch_comment` (mutually exclusive with `reply_to`).
 
-A human reply while your ask is still open (the delivered `comment.created` carries `ask_state: open`) is a request for
-clarification, not an answer: the human did not understand the question or needs more before choosing. The ask now waits on you
-in their Inbox. Answer in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with
-`dispatch_edit_ask` when the wording was the problem; either puts the ask back in front of them. Do not open a second ask.
+A human answers or asks back from the same field; a question-shaped free-text answer is offered as a clarification first. A human
+reply while your ask is still open (the delivered `comment.created` carries `ask_state: open`) is a request for clarification, not
+an answer: the human did not understand the question or needs more before choosing. The ask now waits on you in their Inbox. Answer
+in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with `dispatch_edit_ask` when the wording
+was the problem; either puts the ask back in front of them. Do not open a second ask.
 
 ## Approval of a spec
 
@@ -289,11 +293,12 @@ dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body,
 
 It returns issue or project-document owner details plus `comment` and, for writes, `topic`.
 `ref` names the owner (an issue or project-document reference) in place of `issue`/`project`.
-`quote` requires `artifact`; omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`)
-takes no `quote`; it belongs to its parent's anchor. Reply to any comment in a thread; the server
-keeps threads flat. A reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly
-under a question asked with `dispatch_ask`. Comments are edited only by their author from the
-dashboard. A delivered `comment.created` event carries the comment `id`; reply to it with
+`quote` requires `artifact`; its anchor is pinned to the containing block while retaining the quote
+for display. Omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no
+`quote`; it belongs to its parent's anchor. Reply to any comment in a thread; the server keeps
+threads flat. A reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a
+question asked with `dispatch_ask`. Comments are edited only by their author from the dashboard. A
+delivered `comment.created` event carries the comment `id`; reply to it with
 `dispatch_comment({ reply_to: <id> })`.
 
 Propose an exact replacement instead of describing it:

package/skills/legion-architect/SKILL.md

@@ -127,10 +127,12 @@ legion({
 
 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.
+starting a fresh one. Keep the returned session identifiers; retro and adjustment resume
+those same sessions through `spawn_worker` (a finished worker is retired after
+`worker_idle_retire_seconds` and comes back from its session file). 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
 
@@ -160,18 +162,24 @@ review and the merge-gate sequence.
 
 ## 5. Retro
 
-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:
+Retro is mandatory for every issue that passed review, before merge. Send the implementer
+back in through the daemon — `spawn_worker` on the implementer carrying the retro task. This
+resumes the same agent whether its pane is still live or the daemon has already retired it
+idle (a finished worker is retired after `worker_idle_retire_seconds`, default 600 s, and
+resumed from its session file on its next assignment). Never `envoy_publish` to a finished
+worker's role topic for this: a retired role has no live holder and the publish is rejected
+with 404.
 
 ```text
-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."
+legion({
+  op: "spawn_worker",
+  issue: "LEGION-40",
+  role: "implementer",
+  task: "Run the legion-retro skill now. Capture durable learnings and post the issue comment; do not create a .legion handoff file."
 })
 ```
 
-Wait for the messaged implementer to report its durable retro result. Retro output is
+Wait for the 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.
 
@@ -189,7 +197,8 @@ Preserve this order exactly:
    head. The deletion must land before that approval, which is head-pinned. An implementer
    completion always writes the issue's status as `testing`; this one is not a test round,
    so on its `phase-complete` wake call `legion({ op: "set_status", issue, status: "retro" })`
-   before messaging the reviewer to approve;
+   before `spawn_worker` on the reviewer to approve that head (a finished reviewer may already
+   be retired; `spawn_worker` resumes it);
 3. retro completes without dirtying the branch beyond `docs/solutions/`;
 4. the merger verifies the current head is the reviewer-approved head plus only the retro
    commits and publishes `READY #<n> at <sha>` to `notifications.role.pr-queue`; it never

package/skills/legion-worker/SKILL.md

@@ -61,7 +61,9 @@ Reach any live role on this issue the same way you reach the architect: `envoy_p
 `notifications.role.` followed by that role's encoded token. Use it when you need context an
 earlier phase has that its handoff doesn't cover — ask the planner why a constraint was
 scoped that way, ask the implementer what a commit actually did. A role that finished its
-phase is still alive and idle in its pane; it answers.
+phase stays idle in its pane for the daemon's idle-retire window and answers; once retired (no
+live holder, a publish is rejected 404), read its committed handoff or ask the architect to
+`spawn_worker` it.
 
 ## Workspace and handoff precedence
 
@@ -316,7 +318,9 @@ record of this issue's active phase. Do not add pipeline labels, run a controlle
 invent a different completion protocol — this is the whole contract.
 
 **Stay in this session afterward.** Your process does not exit when your phase completes;
-it goes idle in its pane. Other roles on this issue may reach you through Envoy with
+it goes idle in its pane, and after `worker_idle_retire_seconds` (default 600 s) idle with no
+active phase the daemon retires it — your next assignment resumes this same session from its
+session file, so it is still you. Other roles on this issue may reach you through Envoy with
 questions about the work you did — answer them, reading `$LEGION_WORKSPACE` and your own
 committed handoff as needed, without mutating anything (see Workspace and handoff
 precedence above). You will also be the one resumed, with a new prompt in this same