@sjawhar/pi-legion-envoy 1.32.0 → 1.34.0

package/dist/envoy.js

@@ -29649,6 +29649,7 @@ function date4(params) {
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
 // ../contracts/src/dispatch-api.ts
+var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 function searchOwnerOf(result) {
   return result.owner ?? { kind: "issue", key: result.issue.key };
 }
@@ -29731,6 +29732,8 @@ var CommentEventPayloadSchema = object({
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   ask_state: _enum2(["open", "answered", "resolved"]).optional(),
+  ask_waiting_on: _enum2(["human", "agent"]).optional(),
+  turn: _enum2(["human", "agent"]).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(),
@@ -29757,7 +29760,7 @@ var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
 var MessageDeliveryEventPayloadSchema = object({
   message_id: string2().optional(),
   attempt: number2().int().positive().optional(),
-  delivery: _enum2(["btw", "aside", "steer"]).optional(),
+  delivery: _enum2(DELIVERY_CAPABILITIES).optional(),
   session_id: string2().optional(),
   target: string2().optional(),
   title: string2().optional(),
@@ -29848,6 +29851,16 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
     message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
+var commentValidation = (() => {
+  const owner = documentOwnerValidation(true);
+  return {
+    check: (value) => {
+      const input = value;
+      return owner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
+    },
+    message: `${owner.message} turn requires reply_to_ask.`
+  };
+})();
 var SPEC_SECTIONS = [
   "Summary",
   "Decisions needed",
@@ -29943,9 +29956,10 @@ var dispatchToolSpecs = [
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
       reply_to: z.string().describe("Full id of a comment to reply to; replying to any comment in a thread continues that " + "thread (an ask's clarification thread included).").optional(),
-      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional()
+      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
+      turn: z.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: commentValidation
   },
   {
     name: "dispatch_suggest",
@@ -30308,6 +30322,19 @@ var stateRole = strictObject({
   launchFailures: number2().int().nonnegative().optional(),
   locator: stateLocator.optional()
 });
+var stateQueuedWorkerIdentity = {
+  roleToken: nonEmptyString,
+  issue: nonEmptyString,
+  role: nonEmptyString
+};
+var stateQueuedWorker = union([
+  strictObject(stateQueuedWorkerIdentity),
+  strictObject({
+    ...stateQueuedWorkerIdentity,
+    kind: _enum2(["assignment", "catchup"]),
+    queuedAt: nonEmptyString
+  })
+]);
 var LegionDaemonApi = {
   State: {
     response: strictObject({
@@ -30324,7 +30351,8 @@ var LegionDaemonApi = {
       controllerLocator: stateLocator.optional(),
       roles: record(string2(), stateRole),
       controllerPendingNotices: number2().int().nonnegative(),
-      pendingStatusWrites: array(nonEmptyString)
+      pendingStatusWrites: array(nonEmptyString),
+      workerAdmission: strictObject({ queue: array(stateQueuedWorker) })
     })
   },
   ControllerReady: {
@@ -30411,7 +30439,8 @@ var LegionDaemonApi = {
     request: architectCapability.extend({
       issue: nonEmptyString,
       role: legionRole,
-      task: nonEmptyString
+      task: nonEmptyString,
+      requestId: uuid2()
     }),
     response: object({
       status: _enum2(["spawned", "resumed", "queued"]),
@@ -31088,7 +31117,7 @@ var TolerantInboundEnvelopeSchema = object({
 }).passthrough();
 var DispatchDeliveryRequestSchema = object({
   attempt: number2().int().positive(),
-  mode: _enum2(["btw", "aside", "steer"])
+  mode: _enum2(DELIVERY_CAPABILITIES)
 });
 var DispatchTargetedFrameSchema = object({
   event: DispatchEventSchema,
@@ -32580,21 +32609,34 @@ async function executeDispatchTool(input) {
       if (replyTo !== undefined && replyToAsk !== undefined) {
         throw new Error("reply_to and reply_to_ask cannot both be set");
       }
+      const requestedTurn = optionalString(args, "turn");
+      if (requestedTurn !== undefined && replyToAsk === undefined) {
+        throw new Error("turn requires reply_to_ask");
+      }
+      if (requestedTurn !== undefined && requestedTurn !== "agent" && requestedTurn !== "human") {
+        throw new Error("turn must be agent or human");
+      }
       const commentInput = {
         body: stringArg(args, "body"),
         ...anchored === undefined ? {} : { anchor: anchored },
         ...replyTo === undefined ? {} : { reply_to: replyTo },
         ...replyToAsk === undefined ? {} : { ask_id: replyToAsk },
+        ...requestedTurn === undefined ? {} : { turn: requestedTurn },
         actor
       };
       const comment = resolved?.owner.kind === "project" ? await client.artifactComment(resolved.artifact.id, commentInput) : await client.comment(issue(), commentInput);
+      const askState = comment.turn === null ? "" : ` (ask now waiting on ${comment.turn})`;
       return {
-        text: `Posted comment ${comment.id}`,
+        text: `Posted comment ${comment.id}${askState}`,
         details: resolved === undefined ? {
           issue: comment.issue_key,
           topic: dispatchIssueSubject(issue(), ">"),
-          comment: comment.id
-        } : writeResultDetails(resolved, { comment: comment.id })
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        } : writeResultDetails(resolved, {
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        })
       };
     }
     case "dispatch_suggest": {
@@ -33275,6 +33317,8 @@ async function copySessionID(copyToClipboard, sessionID) {
 // extensions/envoy.ts
 var codec2 = import_nats.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
+var ALL_CAPABILITIES = DELIVERY_CAPABILITIES;
+var CAPABILITIES_WITHOUT_BTW = DELIVERY_CAPABILITIES.filter((capability) => capability !== "btw");
 var ROLE_CLAIM_ENTRY = "envoy-role-claim";
 var OPEN_ASKS_TIMEOUT_MS = 3000;
 function isRoleClaimEntry(entry) {
@@ -33533,7 +33577,7 @@ function envoyExtension(pi) {
     topics: [...new Set([agentSubject(sessionID), ...subscriptions.keys()])],
     port: 0,
     title: activeSessionContext?.sessionManager.getSessionName?.() ?? "",
-    capabilities: typeof pi.askEphemeral === "function" ? ["aside", "btw"] : ["aside"],
+    capabilities: typeof pi.askEphemeral === "function" ? ALL_CAPABILITIES : CAPABILITIES_WITHOUT_BTW,
     driving: false,
     selfSubscribed: true
   });

package/dist/legion.js

@@ -16112,7 +16112,7 @@ var require_mod4 = __commonJS(function(exports) {
 });
 
 // extensions/legion.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import fs from "fs";
 import path4 from "path";
 
@@ -29649,6 +29649,7 @@ function date4(params) {
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
 // ../contracts/src/dispatch-api.ts
+var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 function searchOwnerOf(result) {
   return result.owner ?? { kind: "issue", key: result.issue.key };
 }
@@ -29731,6 +29732,8 @@ var CommentEventPayloadSchema = object({
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   ask_state: _enum2(["open", "answered", "resolved"]).optional(),
+  ask_waiting_on: _enum2(["human", "agent"]).optional(),
+  turn: _enum2(["human", "agent"]).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(),
@@ -29757,7 +29760,7 @@ var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
 var MessageDeliveryEventPayloadSchema = object({
   message_id: string2().optional(),
   attempt: number2().int().positive().optional(),
-  delivery: _enum2(["btw", "aside", "steer"]).optional(),
+  delivery: _enum2(DELIVERY_CAPABILITIES).optional(),
   session_id: string2().optional(),
   target: string2().optional(),
   title: string2().optional(),
@@ -29848,6 +29851,16 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
     message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
+var commentValidation = (() => {
+  const owner = documentOwnerValidation(true);
+  return {
+    check: (value) => {
+      const input = value;
+      return owner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
+    },
+    message: `${owner.message} turn requires reply_to_ask.`
+  };
+})();
 var SPEC_SECTIONS = [
   "Summary",
   "Decisions needed",
@@ -29943,9 +29956,10 @@ var dispatchToolSpecs = [
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
       reply_to: z.string().describe("Full id of a comment to reply to; replying to any comment in a thread continues that " + "thread (an ask's clarification thread included).").optional(),
-      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional()
+      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
+      turn: z.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: commentValidation
   },
   {
     name: "dispatch_suggest",
@@ -30308,6 +30322,19 @@ var stateRole = strictObject({
   launchFailures: number2().int().nonnegative().optional(),
   locator: stateLocator.optional()
 });
+var stateQueuedWorkerIdentity = {
+  roleToken: nonEmptyString,
+  issue: nonEmptyString,
+  role: nonEmptyString
+};
+var stateQueuedWorker = union([
+  strictObject(stateQueuedWorkerIdentity),
+  strictObject({
+    ...stateQueuedWorkerIdentity,
+    kind: _enum2(["assignment", "catchup"]),
+    queuedAt: nonEmptyString
+  })
+]);
 var LegionDaemonApi = {
   State: {
     response: strictObject({
@@ -30324,7 +30351,8 @@ var LegionDaemonApi = {
       controllerLocator: stateLocator.optional(),
       roles: record(string2(), stateRole),
       controllerPendingNotices: number2().int().nonnegative(),
-      pendingStatusWrites: array(nonEmptyString)
+      pendingStatusWrites: array(nonEmptyString),
+      workerAdmission: strictObject({ queue: array(stateQueuedWorker) })
     })
   },
   ControllerReady: {
@@ -30411,7 +30439,8 @@ var LegionDaemonApi = {
     request: architectCapability.extend({
       issue: nonEmptyString,
       role: legionRole,
-      task: nonEmptyString
+      task: nonEmptyString,
+      requestId: uuid2()
     }),
     response: object({
       status: _enum2(["spawned", "resumed", "queued"]),
@@ -30637,6 +30666,14 @@ function parseControlDirective(raw) {
 }
 
 // src/legion/daemon-client.ts
+function defaultSleep(ms) {
+  const { promise, resolve } = Promise.withResolvers();
+  setTimeout(resolve, ms);
+  return promise;
+}
+var SPAWN_WORKER_RETRY_DELAYS_MS = [2000, 5000];
+var SPAWN_WORKER_ATTEMPTS = SPAWN_WORKER_RETRY_DELAYS_MS.length + 1;
+
 class LegionDaemonApiError extends Error {
   method;
   path;
@@ -30650,6 +30687,30 @@ class LegionDaemonApiError extends Error {
     this.responseBody = responseBody;
   }
 }
+
+class LegionDaemonTransportError extends Error {
+  path;
+  requestId;
+  attempts;
+  constructor(path, requestId, attempts, cause) {
+    super(`POST ${path} got no response in ${attempts} attempts (request ${requestId}): ${messageFor(cause)}. The daemon may have received the request; read legion state (workerAdmission.queue and the role's claim) before sending it again.`, { cause });
+    this.path = path;
+    this.requestId = requestId;
+    this.attempts = attempts;
+    this.name = "LegionDaemonTransportError";
+  }
+}
+
+class LegionDaemonResponseReadError extends Error {
+  path;
+  requestId;
+  constructor(path, requestId, cause) {
+    super(`POST ${path} response body could not be read (request ${requestId}): ${messageFor(cause)}. The daemon may have received the request; read legion state (workerAdmission.queue and the role's claim) before sending it again.`, { cause });
+    this.path = path;
+    this.requestId = requestId;
+    this.name = "LegionDaemonResponseReadError";
+  }
+}
 function isInvalidSessionSecret(error) {
   if (!(error instanceof LegionDaemonApiError) || error.status !== 403)
     return false;
@@ -30668,19 +30729,42 @@ function sessionCapability(body) {
   return { sessionId: candidate.sessionId, secret: candidate.secret };
 }
 var WORKER_SESSION_PATH = "/legion/v1/worker-session";
-function createLegionDaemonClient(baseUrl, fetchFn = fetch, recovery) {
+function createLegionDaemonClient(baseUrl, fetchFn = fetch, recovery, sleep = defaultSleep) {
   const endpoint = baseUrl.replace(/\/+$/, "");
-  const postOnce = async (path, body, schema) => {
-    const response = await fetchFn(`${endpoint}${path}`, {
+  const postOnce = async (path, body, schema, fetchImpl = fetchFn, onResponseReadError) => {
+    const response = await fetchImpl(`${endpoint}${path}`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body)
     });
-    const responseBody = await response.text();
+    let responseBody;
+    try {
+      responseBody = await response.text();
+    } catch (error) {
+      throw onResponseReadError?.(error) ?? error;
+    }
     if (!response.ok)
       throw new LegionDaemonApiError("POST", path, response.status, responseBody);
     return schema.parse(JSON.parse(responseBody));
   };
+  const transportRetryingFetch = (path, requestId) => {
+    let transportFailures = 0;
+    return async (input, init) => {
+      for (;; ) {
+        try {
+          return await fetchFn(input, init);
+        } catch (error) {
+          transportFailures += 1;
+          const delay = SPAWN_WORKER_RETRY_DELAYS_MS[transportFailures - 1];
+          if (delay === undefined) {
+            throw new LegionDaemonTransportError(path, requestId, transportFailures, error);
+          }
+          console.error(`[legion] POST ${path} attempt ${transportFailures}/${SPAWN_WORKER_ATTEMPTS} got no response (${messageFor(error)}); retrying request ${requestId} in ${delay} ms`);
+          await sleep(delay);
+        }
+      }
+    };
+  };
   const recoveries = new Map;
   const secretAfterRefusal = async (active, sessionId, refusedSecret) => {
     let record = recoveries.get(sessionId);
@@ -30705,16 +30789,16 @@ function createLegionDaemonClient(baseUrl, fetchFn = fetch, recovery) {
     }
     return (await record.inFlight).secret;
   };
-  const post = async (path, body, schema) => {
+  const post = async (path, body, schema, fetchImpl = fetchFn, onResponseReadError) => {
     try {
-      return await postOnce(path, body, schema);
+      return await postOnce(path, body, schema, fetchImpl, onResponseReadError);
     } catch (error) {
       const capability = sessionCapability(body);
       if (path === WORKER_SESSION_PATH || recovery === undefined || capability === undefined || !isInvalidSessionSecret(error)) {
         throw error;
       }
       const secret = await secretAfterRefusal(recovery, capability.sessionId, capability.secret);
-      return await postOnce(path, { ...body, secret }, schema);
+      return await postOnce(path, { ...body, secret }, schema, fetchImpl, onResponseReadError);
     }
   };
   const get = async (path, schema) => {
@@ -30734,7 +30818,7 @@ function createLegionDaemonClient(baseUrl, fetchFn = fetch, recovery) {
     processReady: (input) => noContent("/legion/v1/process/ready", input, LegionDaemonApi.ProcessReady.response),
     workerStarted: (input) => post("/legion/v1/worker/started", input, LegionDaemonApi.WorkerStarted.response),
     workerReady: (input) => noContent("/legion/v1/worker/ready", input, LegionDaemonApi.WorkerReady.response),
-    spawnWorker: (input) => post("/legion/v1/worker/spawn", input, LegionDaemonApi.SpawnWorker.response),
+    spawnWorker: (input) => post("/legion/v1/worker/spawn", input, LegionDaemonApi.SpawnWorker.response, transportRetryingFetch("/legion/v1/worker/spawn", input.requestId), (error) => new LegionDaemonResponseReadError("/legion/v1/worker/spawn", input.requestId, error)),
     releaseWave: (input) => post("/legion/v1/waves/release", input, LegionDaemonApi.WaveRelease.response),
     provisioningCredential: (input) => post("/legion/v1/provisioning-credential", input, LegionDaemonApi.ProvisioningCredential.response),
     escalate: (input) => noContent("/legion/v1/escalate", input, LegionDaemonApi.Escalate.response),
@@ -30813,6 +30897,9 @@ commit_trailers = '"Omp-Session: ${id}"'
   }
 }
 
+// src/legion/tools.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
 // src/tool-result.ts
 function toolSuccess(text, details = {}) {
   return { content: [{ type: "text", text }], details };
@@ -30868,7 +30955,7 @@ function createLegionTool(deps) {
   return {
     name: "legion",
     label: "legion",
-    description: "Perform a Legion lifecycle write through the Legion daemon. " + "register_gate records the root spec document a human must approve: `artifactId` is the " + "document id (a UUID) and `version` the version number, both copied from the `artifact` and " + "`version` fields of dispatch_request_approval's result \u2014 never the slug or file name you " + "passed to that tool. " + `spawn_worker's response "status" means: "spawned" \u2014 a fresh pane just opened and is ` + 'running now; "resumed" \u2014 an existing worker was prompted directly over its live socket ' + "and its turn started, or (if its boot has not confirmed yet) its task was recorded to " + 'deliver once that boot completes; "queued" \u2014 the task was recorded and this role will ' + "start on its own: either the running-worker cap is full, or the live worker acknowledged " + "the task without starting a turn and the daemon is retrying it. Never re-spawn a role " + 'after "resumed" or "queued" \u2014 wait for the worker-started notification instead.',
+    description: "Perform a Legion lifecycle write through the Legion daemon. " + "register_gate records the root spec document a human must approve: `artifactId` is the " + "document id (a UUID) and `version` the version number, both copied from the `artifact` and " + "`version` fields of dispatch_request_approval's result \u2014 never the slug or file name you " + "passed to that tool. " + `spawn_worker's response "status" means: "spawned" \u2014 a fresh pane just opened and is ` + 'running now; "resumed" \u2014 an existing worker was prompted directly over its live socket ' + "and its turn started, or (if its boot has not confirmed yet) its task was recorded to " + 'deliver once that boot completes; "queued" \u2014 the task was recorded and this role will ' + "start on its own: either the running-worker cap is full, or the live worker acknowledged " + "the task without starting a turn and the daemon is retrying it. Never re-spawn a role " + 'after "resumed" or "queued" \u2014 wait for the worker-started notification instead. A call ' + 'that fails with "got no response in 3 attempts" was retried by the plugin with one ' + "request id; the daemon may still have received it \u2014 read legion state " + "(workerAdmission.queue, and the role in roles) before sending it again. A spawn_worker " + "identical to the task already queued for the role changes nothing and is not announced again.",
     defaultInactive: true,
     parameters: legionToolSchema(pi),
     execute: async (_id, parameters, _signal, _onUpdate, context) => {
@@ -30958,13 +31045,15 @@ function createLegionTool(deps) {
             if (typeof role !== "string" || !LEGION_ROLES.includes(role)) {
               throw new Error("spawn_worker requires a valid Legion role");
             }
+            const requestId = randomUUID2();
             return jsonSuccess(await daemon.spawnWorker({
               tree: architect.tree,
               sessionId,
               secret: architect.secret,
               issue: stringInput("issue"),
               role,
-              task: stringInput("task")
+              task: stringInput("task"),
+              requestId
             }));
           }
           default:
@@ -31541,7 +31630,7 @@ var TolerantInboundEnvelopeSchema = object({
 }).passthrough();
 var DispatchDeliveryRequestSchema = object({
   attempt: number2().int().positive(),
-  mode: _enum2(["btw", "aside", "steer"])
+  mode: _enum2(DELIVERY_CAPABILITIES)
 });
 var DispatchTargetedFrameSchema = object({
   event: DispatchEventSchema,
@@ -33011,21 +33100,34 @@ async function executeDispatchTool(input) {
       if (replyTo !== undefined && replyToAsk !== undefined) {
         throw new Error("reply_to and reply_to_ask cannot both be set");
       }
+      const requestedTurn = optionalString(args, "turn");
+      if (requestedTurn !== undefined && replyToAsk === undefined) {
+        throw new Error("turn requires reply_to_ask");
+      }
+      if (requestedTurn !== undefined && requestedTurn !== "agent" && requestedTurn !== "human") {
+        throw new Error("turn must be agent or human");
+      }
       const commentInput = {
         body: stringArg(args, "body"),
         ...anchored === undefined ? {} : { anchor: anchored },
         ...replyTo === undefined ? {} : { reply_to: replyTo },
         ...replyToAsk === undefined ? {} : { ask_id: replyToAsk },
+        ...requestedTurn === undefined ? {} : { turn: requestedTurn },
         actor
       };
       const comment = resolved?.owner.kind === "project" ? await client.artifactComment(resolved.artifact.id, commentInput) : await client.comment(issue(), commentInput);
+      const askState = comment.turn === null ? "" : ` (ask now waiting on ${comment.turn})`;
       return {
-        text: `Posted comment ${comment.id}`,
+        text: `Posted comment ${comment.id}${askState}`,
         details: resolved === undefined ? {
           issue: comment.issue_key,
           topic: dispatchIssueSubject(issue(), ">"),
-          comment: comment.id
-        } : writeResultDetails(resolved, { comment: comment.id })
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        } : writeResultDetails(resolved, {
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        })
       };
     }
     case "dispatch_suggest": {
@@ -33698,6 +33800,8 @@ async function copySessionID(copyToClipboard, sessionID) {
 // extensions/envoy.ts
 var codec2 = import_nats.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
+var ALL_CAPABILITIES = DELIVERY_CAPABILITIES;
+var CAPABILITIES_WITHOUT_BTW = DELIVERY_CAPABILITIES.filter((capability) => capability !== "btw");
 var ROLE_CLAIM_ENTRY = "envoy-role-claim";
 var OPEN_ASKS_TIMEOUT_MS = 3000;
 function isRoleClaimEntry(entry) {
@@ -33956,7 +34060,7 @@ function envoyExtension(pi) {
     topics: [...new Set([agentSubject(sessionID), ...subscriptions.keys()])],
     port: 0,
     title: activeSessionContext?.sessionManager.getSessionName?.() ?? "",
-    capabilities: typeof pi.askEphemeral === "function" ? ["aside", "btw"] : ["aside"],
+    capabilities: typeof pi.askEphemeral === "function" ? ALL_CAPABILITIES : CAPABILITIES_WITHOUT_BTW,
     driving: false,
     selfSubscribed: true
   });
@@ -34707,7 +34811,7 @@ function isToolDeviceInvocation(toolCall) {
   return toolCall.toolName === "write" && typeof toolCall.input.path === "string" && toolCall.input.path.startsWith("xd://");
 }
 function legionExtension(pi) {
-  const instance = randomUUID2().slice(0, 8);
+  const instance = randomUUID3().slice(0, 8);
   logger2.debug("extension instance loaded", { extension: import.meta.url, instance });
   globalThis[LEGION_LOADED_MARKER] = import.meta.url;
   const defaults = envoyDefaultsFromEnvironment(process.env);

package/dist/skills/dispatch/SKILL.md

@@ -42,6 +42,16 @@ agent's `envoy.json` to set the GitHub OAuth callback origin: the value must
 be the exact URL humans type in their browser, and the GitHub App callback is
 `<DISPATCH_SERVER_URL>/auth/callback`.
 
+### Finding a route
+
+The tools cover the everyday surface. For anything else, ask the server: `GET /api/v1` (no
+credential) returns every route as `{method, path, auth, description}` sorted by path — `auth`
+is `public`, `any` (a human or a bearer), `human` (a bearer gets `403 HUMAN_ONLY`), or `bearer`.
+A path Dispatch does not serve under `/api` or `/v1` answers
+`404 {"code":"NOT_FOUND","error":"no route for GET /v1/issues","hint":"GET /api/v1 lists every
+route"}`; when you see that, you typed the path wrong — read the index rather than guessing. Every
+`/api/v1` error body carries a `code`; branch on the code, never on the text.
+
 ## Writing a spec
 
 A spec has two readers: the human who decides reads the top; the implementer who builds reads the
@@ -194,6 +204,14 @@ an answer: the human did not understand the question or needs more before choosi
 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.
 
+Every reply to an open ask says whose turn it is next, and the Inbox files the ask by that, not by who spoke last. Your plain reply
+(`turn` omitted, or `turn: "human"`) hands the turn to the human: the ask returns to their `Waiting on you`. When you are not done
+yet — "dispatched two auditors, back with results", "checking the release branch, back shortly", any working-on-it note — reply with
+`turn: "agent"`: the note lands in the thread, the ask stays under `Waiting on agents`, and the human is not told to act. Use
+`turn: "agent"` for every progress note and `turn: "human"` (the default) only when you need them. A human's reply always hands the
+turn to you. The result names the state (`ask now waiting on agent` / `human`), the delivered `comment.created` carries it as
+`ask_waiting_on`, and every ask read carries it as `waiting_on`.
+
 ## Approval of a spec
 
 Approval is a property of a document, not a question you phrase: a human approves a specific version, the way a pull-request
@@ -300,7 +318,7 @@ an ask block without a question or with a blank option is rejected with `INVALID
 Add feedback with:
 
 ```ts
-dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
+dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask?, turn? })
 ```
 
 It returns issue or project-document owner details plus `comment` and, for writes, `topic`.
@@ -309,8 +327,10 @@ It returns issue or project-document owner details plus `comment` and, for write
 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
+question asked with `dispatch_ask`; `turn` (only with `reply_to_ask`) says who holds the turn after
+the reply — `agent` for a progress note that keeps the ask waiting on you, `human` (the default) when
+the human needs to act; see [Asking](#asking). 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:
@@ -395,7 +415,10 @@ dispatch_message({
 delivery can post its answer automatically; use this call when the frame asks the primary agent to
 reply. `dispatch_message` itself never carries `target` or `delivery`: agent-to-agent traffic goes
 through Envoy or the hub. A bearer that targets over HTTP names its own session in `actor`
-(`{kind: "session", id}`), and the card shows that session as the author.
+(`{kind: "session", id}`), and the card shows that session as the author. `GET /api/v1/agents`
+(any authenticated caller) lists live sessions with their capabilities (`aside`, `btw`, `steer`);
+target only a session that advertises the mode you want. Sending to a session with no issue
+(`POST /api/v1/agents/{session_id}/messages`) stays human-only.
 
 ## What comes back
 

package/dist/skills/envoy/SKILL.md

@@ -90,6 +90,16 @@ envoy_send(
 )
 ```
 
+### Delivery capabilities
+
+Each session row from `envoy_sessions` carries `capabilities`, the targeted-delivery modes that
+session's host honours: `aside` (a message queued beside the model's work), `btw` (an ephemeral
+question the host answers without disturbing the current turn), and `steer` (an interjection at
+the next tool boundary). An OMP session advertises `aside`, `btw`, and `steer` (`aside` and
+`steer` on a host without `askEphemeral`); a Claude Code session advertises `aside` only, because
+its channel notifications queue for the next turn. Target a session only with a mode it
+advertises.
+
 ## Waiting for CI or a merge
 
 Subscribe to `notifications.github.example-org.example-repo.pr.42.>` and end the turn. The single

package/dist/skills/legion-architect/SKILL.md

@@ -301,7 +301,7 @@ active phase worker.
 | `design-approved` | Payload `{type:"design-approved"}`. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
 | `design-changes-requested` | Payload `{type:"design-changes-requested", version, reason, author?}`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec, call `dispatch_request_approval` again, and stay parked; the gate is closed. |
 | `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. A `reviewer` completion whose GitHub review is `CHANGES_REQUESTED` (the daemon returns the issue's Dispatch status to `in_progress` for this, on the reviewer's completion and again when you spawn the corrective implementer unless the daemon already knows the issue is `in_progress`) means `spawn_worker` the **implementer** again with the review findings — thread URLs and blocking items — as its task, then route back through tester and reviewer in order; never `spawn_worker` the reviewer directly off this wake and never proceed to retro on this verdict. A reviewer completion with an `APPROVED` review proceeds to retro (step 5). A `reviewer` completion after a conflict-forced rebase whose review body names an unchanged fingerprint is a confirmation, not a round: if retro already completed, `spawn_worker` the merger; otherwise resume the step you were on. An `implementer` completion that follows the merge is its production report: read the record on the pull request and the issue, then run step 7 — the issue is already at `retro`, the daemon writes no status for this completion, and you set `done` yourself. A `tester` completion whose handoff carries `implementerProof.verdict: "rejected"`, or a failure naming the production-like proof, goes back to the **implementer** with that finding — never forward to the reviewer, and never by supplying the proof from another role. A worker that reports no surface reaches the changed path gets a child issue in this tree (infrastructure, tooling, or a skill) and a resume once it lands; that report is never a reason to advance the phase. |
-| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. This role's task is queued for promotion — either the deployment's worker cap is full, or the live worker acknowledged the task without starting a turn and the daemon is retrying it (counted; the worker is replaced after three such failures, still with the same task). Do not respawn or retry — wait for `worker-started`. |
+| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. This role's task is queued for promotion — either the deployment's worker cap is full, or the live worker acknowledged the task without starting a turn and the daemon is retrying it (counted; the worker is replaced after three such failures, still with the same task). Do not respawn or retry — wait for `worker-started`. `legion state` shows the queue (`workerAdmission.queue`: role token, issue, role, kind, and the time the task was first queued — never the task text); read it before re-sending. A `spawn_worker` identical to the queued task changes nothing and is not announced again. Different text replaces the queued task silently in the same FIFO slot and retains its original queue time. A `spawn_worker` that fails with "got no response in 3 attempts" was already retried by the plugin under one request id and may still have reached the daemon: read the queue and the role's claim in `legion state` before sending it again. |
 | `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/merger order only for that current head. |
 | `pr-review` | Payload `{type:"pr-review", state, author, body}`. Delivered to whichever role is currently active for the issue, falling back to you when no worker phase is active. Follows the same verdict rule as a reviewer's `phase-complete`: `state: "changes_requested"` sends the implementer back in with the review findings, then tester, then reviewer — never the reviewer again and never retro; that `spawn_worker` returns the issue to `in_progress` on its own (the daemon writes it for a corrective implementer whenever the PR's latest recorded review is changes requested, a human's after approval included), so you set nothing by hand; `state: "approved"` proceeds toward retro (step 5) once the step 6 integration/merge-gate conditions are met. `state: "approved"` on a rebased head whose body names an unchanged fingerprint is that confirmation: proceed to retro if it has not run, otherwise to the merger — never to a second retro or test round. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "type": "module",
   "omp": {
     "extensions": [
@@ -12,7 +12,7 @@
     ]
   },
   "legion": {
-    "daemonApiVersion": 3
+    "daemonApiVersion": 4
   },
   "repository": {
     "type": "git",