@sjawhar/pi-legion-envoy 1.65.2 → 1.66.0

package/dist/envoy.js

@@ -34747,6 +34747,64 @@ function messageMetadata(input) {
 import { logger } from "@oh-my-pi/pi-utils";
 var import_nats = __toESM(require_mod4(), 1);
 
+// src/legion/phase-stall.ts
+var PHASE_STALL_ENTRY = "legion-phase-stall";
+var LOCAL_ENVOY_NOTICE = { localNotice: true };
+var WAITING_REPLY = /^\W*WAITING\b/m;
+var TOOL_CALL_SHAPED = /<(?:[\w-]+:)?(?:function_calls\b|invoke\s+name\s*=|parameter\s+name\s*=)/;
+var FOLLOW_UP = "Your turn ended with your Legion phase still open: the `legion` tool's `handoff_complete` has " + "not succeeded since your assignment. If your phase's work is done, call the `legion` tool now " + "with op `handoff_complete` and the fields your role's instructions give. If you are waiting on " + "something (CI, a review, a person), reply with a line starting WAITING that names what you are " + "waiting on; nothing more will be sent until a new event arrives.";
+var TEXT_TOOL_CALL = "Your last message holds a tool call written as text, so it did not run: make it a real tool call. ";
+function stepPhaseStall(state, input) {
+  switch (input.kind) {
+    case "assignment":
+      return { state: "open" };
+    case "handoff-complete":
+      return { state: "closed" };
+    case "inbound-event":
+      return { state: state === "quiet" ? "open" : state };
+    case "settle":
+      if (state !== "open")
+        return { state };
+      if (WAITING_REPLY.test(input.lastAssistantText))
+        return { state: "quiet" };
+      return {
+        state: "quiet",
+        followUp: TOOL_CALL_SHAPED.test(input.lastAssistantText) ? TEXT_TOOL_CALL + FOLLOW_UP : FOLLOW_UP
+      };
+  }
+}
+function inboundKind(message) {
+  if (typeof message !== "object" || message === null || !("role" in message))
+    return;
+  if (message.role === "user")
+    return "assignment";
+  if (message.role === "custom" && "customType" in message && message.customType === "envoy-message" && !(("details" in message) && typeof message.details === "object" && message.details !== null && ("localNotice" in message.details) && message.details.localNotice === LOCAL_ENVOY_NOTICE.localNotice))
+    return "inbound-event";
+  return;
+}
+function assistantText(message) {
+  if (typeof message !== "object" || message === null)
+    return "";
+  if (!("role" in message) || message.role !== "assistant" || !("content" in message))
+    return "";
+  if (!Array.isArray(message.content))
+    return "";
+  return message.content.map((block) => typeof block === "object" && block !== null && ("type" in block) && block.type === "text" && ("text" in block) && typeof block.text === "string" ? block.text : "").join(`
+`);
+}
+function isPhaseStall(value) {
+  return value === "closed" || value === "open" || value === "quiet";
+}
+function restorePhaseStall(branch) {
+  for (let index = branch.length - 1;index >= 0; index -= 1) {
+    const entry = branch[index];
+    if (typeof entry === "object" && entry !== null && "type" in entry && entry.type === "custom" && "customType" in entry && entry.customType === PHASE_STALL_ENTRY && "data" in entry && typeof entry.data === "object" && entry.data !== null && "state" in entry.data && isPhaseStall(entry.data.state)) {
+      return entry.data.state;
+    }
+  }
+  return "closed";
+}
+
 // src/legion/role-claim-bridge.ts
 var LEGION_ROLE_CLAIM_BRIDGE = Symbol.for("legion.pi-envoy.role-claim-bridge");
 function legionRoleClaimBridge() {
@@ -35391,7 +35449,8 @@ function envoyExtension(pi) {
           detail: "This conversation now lives under a new session id. Any identity you shared earlier (envoy_whoami output, session ids named in messages) is stale, and peers using the old id cannot reach you. Re-run envoy_whoami before identifying yourself and re-announce the new id to peers you already introduced yourself to."
         }
       }),
-      display: true
+      display: true,
+      details: LOCAL_ENVOY_NOTICE
     }, { deliverAs: "steer", triggerTurn: false });
   };
   pi.on("session_switch", (event, context) => rebind(event.reason, context));
@@ -35496,7 +35555,7 @@ ${formatOpenAsksSummary(open.snapshot, open.url)}`,
     }
   });
   const announceFollow = createFollowAnnouncer((text) => {
-    pi.sendMessage({ customType: "envoy-message", content: text, display: true }, { deliverAs: "steer", triggerTurn: false });
+    pi.sendMessage({ customType: "envoy-message", content: text, display: true, details: LOCAL_ENVOY_NOTICE }, { deliverAs: "steer", triggerTurn: false });
   });
   pi.on("tool_result", async (event) => {
     if (event.isError)

package/dist/legion.js

@@ -16142,7 +16142,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "1.65.2",
+  version: "1.66.0",
   type: "module",
   omp: {
     extensions: [
@@ -31326,6 +31326,13 @@ async function writeGrantFile(file2, grantId) {
     throw new Error(`LEGION_GRANT_FILE ${file2} could not be written: ${messageFor(error48)}`);
   }
 }
+async function writeMintedGrant(mint) {
+  const file2 = process.env.LEGION_GRANT_FILE;
+  if (file2 === undefined || file2.trim() === "") {
+    throw new Error("LEGION_GRANT_FILE is not set on this pane: the daemon that launched it predates this plugin; restart the daemon on the matching release");
+  }
+  await writeGrantFile(file2, await mint());
+}
 
 // src/legion/go-bootstrap.ts
 import path3 from "path";
@@ -31799,6 +31806,141 @@ function toolFailure(error48) {
   return { content: [{ type: "text", text: messageFor(error48) }], details: {}, isError: true };
 }
 
+// src/legion/handoff-actions.ts
+import { execFile as execFile2 } from "child_process";
+var HANDOFF_OPERATION_FIELDS = {
+  handoff_write: ["phase", "data"],
+  handoff_read: ["phase"],
+  handoff_message: ["sender", "recipient", "body"],
+  handoff_complete: ["summary", "verdict", "ready", "phase"]
+};
+var HANDOFF_OPERATIONS = Object.keys(HANDOFF_OPERATION_FIELDS);
+function isHandoffOperation(operation) {
+  return Object.hasOwn(HANDOFF_OPERATION_FIELDS, operation);
+}
+function handoffSchemaFields(z2) {
+  return {
+    phase: z2.enum(HANDOFF_PHASES).optional(),
+    data: z2.unknown().optional(),
+    sender: z2.enum(HANDOFF_PHASES).optional(),
+    recipient: z2.enum(HANDOFF_PHASES).optional(),
+    body: z2.string().optional(),
+    summary: z2.string().optional(),
+    verdict: z2.enum(["pass", "fail"]).optional(),
+    ready: z2.boolean().optional()
+  };
+}
+var HANDOFF_DESCRIPTION = "Handoff actions (phase workers and sub-architects): handoff_write writes this phase's handoff " + "(`phase`, and `data`: the phase-specific fields as a JSON object) to `.legion/<phase>.json` in " + "the issue workspace; handoff_read returns the handoffs (every phase, or `phase`); " + "handoff_message leaves a message for another phase (`sender`, `recipient`, `body`); " + "handoff_complete reports this phase complete to the daemon (`summary`: two sentences for the " + "architect; `verdict` pass|fail when your role's instructions require one; `ready: true` for " + "the merger's READY; no `phase` is needed, and one other than your own is refused). Each " + "returns the command's output; a failed action changed nothing.";
+var ROLE_HANDOFF_PHASE = {
+  architect: "architect",
+  planner: "plan",
+  plan: "plan",
+  implementer: "implement",
+  implement: "implement",
+  tester: "test",
+  test: "test",
+  reviewer: "review",
+  review: "review"
+};
+var COMMAND_TIMEOUT_MS = 300000;
+function required2(parameters, operation, name) {
+  const value = parameters[name];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${operation} requires ${name}`);
+  }
+  return value;
+}
+function commandArguments(operation, parameters) {
+  const accepted = HANDOFF_OPERATION_FIELDS[operation];
+  for (const name of Object.keys(parameters)) {
+    if (name !== "op" && !accepted.includes(name)) {
+      throw new Error(`${operation} does not accept field "${name}"`);
+    }
+  }
+  switch (operation) {
+    case "handoff_write": {
+      const data = parameters.data;
+      if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        throw new Error("handoff_write requires data: the phase's handoff fields as a JSON object");
+      }
+      const phase = required2(parameters, operation, "phase");
+      return ["handoff", "write", "--phase", phase, "--data", JSON.stringify(data)];
+    }
+    case "handoff_read":
+      return parameters.phase === undefined ? ["handoff", "read"] : ["handoff", "read", "--phase", required2(parameters, operation, "phase")];
+    case "handoff_message":
+      return [
+        "handoff",
+        "message",
+        "--from",
+        required2(parameters, operation, "sender"),
+        "--to",
+        required2(parameters, operation, "recipient"),
+        "--body",
+        required2(parameters, operation, "body")
+      ];
+    case "handoff_complete": {
+      const command = [
+        "handoff",
+        "complete",
+        "--summary",
+        required2(parameters, operation, "summary")
+      ];
+      const { verdict, ready, phase } = parameters;
+      if (phase !== undefined) {
+        const role = requiredEnvironment(process.env, "LEGION_ROLE");
+        const own = ROLE_HANDOFF_PHASE[role];
+        if (own === undefined) {
+          throw new Error(`handoff_complete takes no phase for a ${role}, which writes no handoff`);
+        }
+        if (phase !== own) {
+          throw new Error(`handoff_complete's phase is "${own}" for a ${role}: omit phase, or pass "${own}"`);
+        }
+      }
+      if (verdict !== undefined) {
+        if (verdict !== "pass" && verdict !== "fail") {
+          throw new Error("handoff_complete's verdict is pass or fail");
+        }
+        command.push("--verdict", verdict);
+      }
+      if (ready !== undefined && typeof ready !== "boolean") {
+        throw new Error("handoff_complete's ready is true or false");
+      }
+      if (ready === true)
+        command.push("--ready");
+      return command;
+    }
+  }
+}
+function runLegion(args, cwd, signal) {
+  const { promise: promise2, resolve, reject } = Promise.withResolvers();
+  execFile2("legion", args, { cwd, env: process.env, signal, timeout: COMMAND_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }, (error48, stdout, stderr) => {
+    const output = [stdout, stderr].map((text) => text.trimEnd()).filter((text) => text !== "").join(`
+`);
+    if (error48 === null) {
+      resolve({ exitCode: 0, output });
+    } else if (typeof error48.code === "number") {
+      resolve({ exitCode: error48.code, output });
+    } else {
+      reject(new Error(`legion ${args.slice(0, 2).join(" ")} did not run: ${messageFor(error48)}`));
+    }
+  });
+  return promise2;
+}
+async function runHandoffAction(input) {
+  const args = commandArguments(input.operation, input.parameters);
+  if (input.operation === "handoff_complete")
+    await writeMintedGrant(input.mintGrant);
+  const { exitCode, output } = await runLegion(args, requiredEnvironment(process.env, "LEGION_WORKSPACE"), input.signal);
+  const text = output === "" ? `legion ${args.slice(0, 2).join(" ")} exited ${exitCode}` : output;
+  const details = { operation: input.operation, exitCode };
+  if (exitCode !== 0)
+    return { content: [{ type: "text", text }], details, isError: true };
+  if (input.operation === "handoff_complete")
+    input.onPhaseCompleted();
+  return { content: [{ type: "text", text }], details };
+}
+
 // src/legion/go-tools.ts
 var OPERATIONS = {
   architect: [
@@ -31829,7 +31971,8 @@ function toolSchema(pi) {
       "request_backward_move",
       "retry_or_escalate",
       "sign_off",
-      "read_record"
+      "read_record",
+      ...HANDOFF_OPERATIONS
     ]),
     issue: z2.string().optional(),
     artifactId: z2.string().optional(),
@@ -31837,7 +31980,8 @@ function toolSchema(pi) {
     issues: z2.array(z2.string()).optional(),
     to: z2.enum(LEGION_GO_PHASES).optional(),
     reason: z2.string().optional(),
-    decision: z2.enum(["retry", "escalate"]).optional()
+    decision: z2.enum(["retry", "escalate"]).optional(),
+    ...handoffSchemaFields(z2)
   });
 }
 function requiredString(parameters, operation, name) {
@@ -31874,17 +32018,29 @@ function recordFrom(state, issue2) {
   return record2;
 }
 function createGoLegionTool(deps) {
-  const { pi, daemon, session } = deps;
+  const { pi, daemon, session, onPhaseCompleted } = deps;
   return {
     name: "legion",
     label: "legion",
-    description: "Perform the workflow operation the Go Legion daemon assigned this role. The daemon advances phases; this tool cannot spawn workers.",
+    description: "Perform the workflow operation the Go Legion daemon assigned this role. The daemon advances phases; this tool cannot spawn workers. " + HANDOFF_DESCRIPTION,
     defaultInactive: true,
     parameters: toolSchema(pi),
-    execute: async (_id, parameters, _signal, _onUpdate, context) => {
+    execute: async (_id, parameters, signal, _onUpdate, context) => {
       try {
         const active = session(context);
         const operation = requiredString(parameters, "legion", "op");
+        if (isHandoffOperation(operation)) {
+          if (active.kind === "architect" && active.issue === active.tree) {
+            throw new Error(`${operation} is not available to a root architect session`);
+          }
+          return await runHandoffAction({
+            operation,
+            parameters,
+            signal,
+            mintGrant: () => grantFor(daemon(), active),
+            onPhaseCompleted: () => onPhaseCompleted(context)
+          });
+        }
         if (!OPERATIONS[active.kind].includes(operation)) {
           throw new Error(`${operation} is not available to a ${active.kind} session`);
         }
@@ -31957,13 +32113,71 @@ function createGoLegionTool(deps) {
   };
 }
 
+// src/legion/phase-stall.ts
+var PHASE_STALL_ENTRY = "legion-phase-stall";
+var LOCAL_ENVOY_NOTICE = { localNotice: true };
+var WAITING_REPLY = /^\W*WAITING\b/m;
+var TOOL_CALL_SHAPED = /<(?:[\w-]+:)?(?:function_calls\b|invoke\s+name\s*=|parameter\s+name\s*=)/;
+var FOLLOW_UP = "Your turn ended with your Legion phase still open: the `legion` tool's `handoff_complete` has " + "not succeeded since your assignment. If your phase's work is done, call the `legion` tool now " + "with op `handoff_complete` and the fields your role's instructions give. If you are waiting on " + "something (CI, a review, a person), reply with a line starting WAITING that names what you are " + "waiting on; nothing more will be sent until a new event arrives.";
+var TEXT_TOOL_CALL = "Your last message holds a tool call written as text, so it did not run: make it a real tool call. ";
+function stepPhaseStall(state, input) {
+  switch (input.kind) {
+    case "assignment":
+      return { state: "open" };
+    case "handoff-complete":
+      return { state: "closed" };
+    case "inbound-event":
+      return { state: state === "quiet" ? "open" : state };
+    case "settle":
+      if (state !== "open")
+        return { state };
+      if (WAITING_REPLY.test(input.lastAssistantText))
+        return { state: "quiet" };
+      return {
+        state: "quiet",
+        followUp: TOOL_CALL_SHAPED.test(input.lastAssistantText) ? TEXT_TOOL_CALL + FOLLOW_UP : FOLLOW_UP
+      };
+  }
+}
+function inboundKind(message) {
+  if (typeof message !== "object" || message === null || !("role" in message))
+    return;
+  if (message.role === "user")
+    return "assignment";
+  if (message.role === "custom" && "customType" in message && message.customType === "envoy-message" && !(("details" in message) && typeof message.details === "object" && message.details !== null && ("localNotice" in message.details) && message.details.localNotice === LOCAL_ENVOY_NOTICE.localNotice))
+    return "inbound-event";
+  return;
+}
+function assistantText(message) {
+  if (typeof message !== "object" || message === null)
+    return "";
+  if (!("role" in message) || message.role !== "assistant" || !("content" in message))
+    return "";
+  if (!Array.isArray(message.content))
+    return "";
+  return message.content.map((block) => typeof block === "object" && block !== null && ("type" in block) && block.type === "text" && ("text" in block) && typeof block.text === "string" ? block.text : "").join(`
+`);
+}
+function isPhaseStall(value) {
+  return value === "closed" || value === "open" || value === "quiet";
+}
+function restorePhaseStall(branch) {
+  for (let index = branch.length - 1;index >= 0; index -= 1) {
+    const entry = branch[index];
+    if (typeof entry === "object" && entry !== null && "type" in entry && entry.type === "custom" && "customType" in entry && entry.customType === PHASE_STALL_ENTRY && "data" in entry && typeof entry.data === "object" && entry.data !== null && "state" in entry.data && isPhaseStall(entry.data.state)) {
+      return entry.data.state;
+    }
+  }
+  return "closed";
+}
+
 // src/legion/tools.ts
 import { randomUUID as randomUUID2 } from "crypto";
 var jsonSuccess2 = (details) => toolSuccess(JSON.stringify(details), details);
 function isDispatchArtifactId(value) {
   return LegionDaemonApi.GatesRegister.request.shape.artifactId.safeParse(value).success;
 }
-var LEGION_OP_FIELDS = {
+var ARCHITECT_OP_FIELDS = {
   set_status: ["issue", "status"],
   register_gate: ["issue", "artifactId", "version"],
   release_wave: ["issues"],
@@ -31973,7 +32187,7 @@ var LEGION_OP_FIELDS = {
 function legionToolSchema(pi) {
   const z2 = pi.zod;
   return z2.object({
-    op: z2.enum(["set_status", "register_gate", "release_wave", "escalate", "spawn_worker"]),
+    op: z2.enum([...Object.keys(ARCHITECT_OP_FIELDS), ...HANDOFF_OPERATIONS]),
     issue: z2.string().optional(),
     status: z2.enum(ISSUE_STATUSES).optional(),
     artifactId: z2.string().optional(),
@@ -31983,30 +32197,51 @@ function legionToolSchema(pi) {
     issues: z2.array(z2.string()).optional(),
     rationale: z2.string().optional(),
     role: z2.enum(LEGION_ROLES).optional(),
-    task: z2.string().optional()
+    task: z2.string().optional(),
+    ...handoffSchemaFields(z2)
   });
 }
 function createLegionTool(deps) {
-  const { pi, roleDaemon, architectSession } = deps;
+  const { pi, roleDaemon, session, onPhaseCompleted } = 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. 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.",
+    description: "Perform a Legion lifecycle write through the Legion daemon. " + "Architect operations (set_status, register_gate, release_wave, escalate, spawn_worker): " + "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. " + HANDOFF_DESCRIPTION,
     defaultInactive: true,
     parameters: legionToolSchema(pi),
-    execute: async (_id, parameters, _signal, _onUpdate, context) => {
+    execute: async (_id, parameters, signal, _onUpdate, context) => {
       try {
-        const architect = architectSession(context);
-        const daemon = roleDaemon();
+        const active = session(context);
         const sessionId = context.sessionManager.getSessionId();
+        const op = String(parameters.op);
+        if (isHandoffOperation(op)) {
+          if (active.kind !== "phase-worker") {
+            throw new Error(`${op} is not available to a root architect session`);
+          }
+          return await runHandoffAction({
+            operation: op,
+            parameters,
+            signal,
+            mintGrant: async () => (await roleDaemon().grant({
+              tree: active.tree,
+              issue: active.issue,
+              sessionId,
+              secret: active.secret
+            })).grantId,
+            onPhaseCompleted: () => onPhaseCompleted(context)
+          });
+        }
+        if (active.role !== "architect") {
+          throw new Error(`${op} is not available to a ${active.role} session`);
+        }
+        const daemon = roleDaemon();
         const stringInput = (name) => {
           const value = parameters[name];
           if (typeof value !== "string")
             throw new Error(`${String(parameters.op)} requires ${name}`);
           return value;
         };
-        const op = String(parameters.op);
-        const allowedFields = LEGION_OP_FIELDS[op];
+        const allowedFields = ARCHITECT_OP_FIELDS[op];
         if (allowedFields) {
           for (const key of Object.keys(parameters)) {
             if (key !== "op" && !allowedFields.includes(key)) {
@@ -32021,9 +32256,9 @@ function createLegionTool(deps) {
               throw new Error("set_status requires a valid Legion issue status");
             }
             await daemon.issueStatus({
-              tree: architect.tree,
+              tree: active.tree,
               sessionId,
-              secret: architect.secret,
+              secret: active.secret,
               issue: stringInput("issue"),
               status
             });
@@ -32039,9 +32274,9 @@ function createLegionTool(deps) {
               throw new Error(`register_gate requires artifactId to be the document id (a UUID) from dispatch_request_approval's result, not "${artifactId}"`);
             }
             await daemon.gatesRegister({
-              tree: architect.tree,
+              tree: active.tree,
               sessionId,
-              secret: architect.secret,
+              secret: active.secret,
               issue: stringInput("issue"),
               artifactId,
               version: version2
@@ -32054,10 +32289,10 @@ function createLegionTool(deps) {
               throw new Error("release_wave requires issues");
             }
             return jsonSuccess2(await daemon.releaseWave({
-              tree: architect.tree,
+              tree: active.tree,
               issues,
               sessionId,
-              secret: architect.secret
+              secret: active.secret
             }));
           }
           case "escalate": {
@@ -32068,11 +32303,11 @@ function createLegionTool(deps) {
             if (!("context" in parameters) || parameters.context === undefined)
               throw new Error("escalate requires context");
             await daemon.escalate({
-              tree: architect.tree,
+              tree: active.tree,
               kind,
               context: parameters.context,
               sessionId,
-              secret: architect.secret
+              secret: active.secret
             });
             return jsonSuccess2({});
           }
@@ -32083,9 +32318,9 @@ function createLegionTool(deps) {
             }
             const requestId = randomUUID2();
             return jsonSuccess2(await daemon.spawnWorker({
-              tree: architect.tree,
+              tree: active.tree,
               sessionId,
-              secret: architect.secret,
+              secret: active.secret,
               issue: stringInput("issue"),
               role,
               task: stringInput("task"),
@@ -32180,16 +32415,8 @@ var callReadyWithRetry = async (label, call) => {
   }
 };
 async function wrapBashWithGrant(mint) {
-  const grantFile = process.env.LEGION_GRANT_FILE;
-  if (grantFile === undefined || grantFile.trim() === "") {
-    return {
-      block: true,
-      reason: "LEGION_GRANT_FILE is not set on this pane: the daemon that launched it predates this plugin; restart the daemon on the matching release"
-    };
-  }
   try {
-    const grant = await mint();
-    await writeGrantFile(grantFile, grant.grantId);
+    await writeMintedGrant(async () => (await mint()).grantId);
     return;
   } catch (error48) {
     return { block: true, reason: messageFor(error48) };
@@ -32355,6 +32582,16 @@ function legionExtension(pi) {
   let bootstrap;
   const checkSubagentSession = subagentSessionCheck();
   let phaseWorkerPane;
+  let phaseStall = "closed";
+  const phaseWorkerSession = (context) => capability !== undefined && capability.sessionID === context.sessionManager.getSessionId() && capability.role !== "architect";
+  const advancePhaseStall = (input) => {
+    const step = stepPhaseStall(phaseStall, input);
+    if (step.state !== phaseStall) {
+      phaseStall = step.state;
+      pi.appendEntry(PHASE_STALL_ENTRY, { state: phaseStall });
+    }
+    return step.followUp;
+  };
   let daemonClient;
   const roleDaemon = () => {
     daemonClient ??= createLegionDaemonClient(requiredEnvironment(process.env, "LEGION_DAEMON_URL"), fetch, {
@@ -32504,7 +32741,7 @@ function legionExtension(pi) {
             generation: generation(process.env)
           }));
         });
-        registerArchitectTools();
+        registerLegionTool();
         await activateLegionTool();
       } catch (error48) {
         if (error48 instanceof LegionDaemonApiError && (error48.status === 401 || error48.status === 403)) {
@@ -32560,10 +32797,8 @@ function legionExtension(pi) {
           secret: started.secret
         };
         await claimEnvoyRole(sessionID, started.roleToken, context);
-        if (role === "architect") {
-          registerArchitectTools();
-          await activateLegionTool();
-        }
+        registerLegionTool();
+        await activateLegionTool();
         await callReadyWithRetry("worker/ready", () => roleDaemon().workerReady({
           tree,
           issue: issue2,
@@ -32591,6 +32826,7 @@ function legionExtension(pi) {
   pi.on("session_start", async (_event, context) => {
     if (await checkSubagentSession(context))
       return;
+    phaseStall = restorePhaseStall(context.sessionManager.getBranch?.() ?? []);
     if (process.env.LEGION_DAEMON_API === "go") {
       await bootstrapGoClaim(context, {
         capability: () => capability,
@@ -32695,6 +32931,22 @@ function legionExtension(pi) {
       secret: active.secret
     }));
   });
+  pi.on("message_start", async (event, context) => {
+    if (!phaseWorkerSession(context))
+      return;
+    const kind = inboundKind(event.message);
+    if (kind !== undefined)
+      advancePhaseStall({ kind });
+  });
+  pi.on("session_stop", async (event, context) => {
+    if (event.signal.aborted || !phaseWorkerSession(context))
+      return;
+    const followUp = advancePhaseStall({
+      kind: "settle",
+      lastAssistantText: assistantText(event.last_assistant_message)
+    });
+    return followUp === undefined ? undefined : { continue: true, additionalContext: followUp };
+  });
   pi.on("session_shutdown", async (_event, context) => {
     const sessionID = context.sessionManager.getSessionId();
     if (capability === undefined || capability.kind !== "root-architect" || capability.sessionID !== sessionID) {
@@ -32714,17 +32966,22 @@ function legionExtension(pi) {
       controlConnection = undefined;
     }
   });
-  const architectSession = (context) => {
+  const toolSession = (context) => {
     const sessionID = context.sessionManager.getSessionId();
-    if (capability !== undefined && capability.sessionID === sessionID && capability.role === "architect") {
-      return {
-        tree: capability.tree,
-        issue: capability.issue,
-        role: capability.role,
-        secret: capability.secret
-      };
+    if (capability === undefined || capability.sessionID !== sessionID) {
+      throw new Error("legion is available only to this session's registered Legion role");
     }
-    throw new Error("legion is available only to root and sub-architect sessions");
+    return {
+      kind: capability.kind,
+      tree: capability.tree,
+      issue: capability.issue,
+      role: capability.role,
+      secret: capability.secret
+    };
+  };
+  const onPhaseCompleted = (context) => {
+    if (phaseWorkerSession(context))
+      advancePhaseStall({ kind: "handoff-complete" });
   };
   const activateLegionTool = async () => {
     const activeTools = pi.getActiveTools();
@@ -32732,12 +32989,12 @@ function legionExtension(pi) {
       return;
     await pi.setActiveTools([...activeTools, "legion"]);
   };
-  let architectToolsRegistered = false;
-  const registerArchitectTools = () => {
-    if (architectToolsRegistered)
+  let legionToolRegistered = false;
+  const registerLegionTool = () => {
+    if (legionToolRegistered)
       return;
-    architectToolsRegistered = true;
-    pi.registerTool(createLegionTool({ pi, roleDaemon, architectSession }));
+    legionToolRegistered = true;
+    pi.registerTool(createLegionTool({ pi, roleDaemon, session: toolSession, onPhaseCompleted }));
   };
   let goToolsRegistered = false;
   const registerGoTools = () => {
@@ -32760,7 +33017,8 @@ function legionExtension(pi) {
           issue: active.issue,
           secret: active.secret
         };
-      }
+      },
+      onPhaseCompleted
     }));
   };
   pi.registerCommand("legion-claim-controller", {

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

@@ -21,7 +21,7 @@ separate coordinator to finish necessary work.
   instead of starting a fresh one. Phases on one issue are strictly sequential -- one role
   is the issue's active phase at a time, and calling `spawn_worker` for a different role
   while a phase is active supersedes that phase: the superseded worker's
-  `legion handoff complete` is then refused, so finish (or deliberately abandon) one role
+  `handoff_complete` is then refused, so finish (or deliberately abandon) one role
   before assigning the next. Phase workers escalate lifecycle, scope, and
   cross-phase matters the same way: `envoy_publish` to your own encoded token. Any role
   may use `dispatch_ask` directly for a standalone human question; replies return to the

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

@@ -108,8 +108,8 @@ dispatch_message({
 
 The Dispatch message and the `docs/solutions/` commit are the only retro outputs. Never write a
 handoff, phase artifact, local feedback log, or completion label; `.legion/` was deleted before
-retro and nothing recreates it. Report completion with `legion handoff complete` alone (its
-summary: two sentences for the architect) — no `legion handoff write`.
+retro and nothing recreates it. Report completion with the `legion` tool's `handoff_complete` alone (its
+summary: two sentences for the architect) — no `handoff_write`.
 
 ## Completion check
 

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

@@ -105,7 +105,7 @@ Read only files that precede the assigned phase. Every handoff is validated when
 `validatePhaseHandoff` (`packages/contracts/src/handoff-schema.ts`) checks the file, and the
 ledger (`packages/daemon/src/handoff/ledger.ts`) treats a file that fails validation as missing.
 Undeclared fields pass validation untouched and reach the next worker; a declared field of the
-wrong type fails the whole file, so `legion handoff read` returns null for that phase.
+wrong type fails the whole file, so the `legion` tool's `handoff_read` returns null for that phase.
 Write the phase-specific fields the next phase and the architect need, consistent with what
 predecessor phases already wrote. The durable copy lives in
 `$LEGION_WORKSPACE/.legion/<phase>.json`. If a committed handoff conflicts with memory or a prior
@@ -190,8 +190,9 @@ comments live on that path too, so edit them with `gh pr comment`) — printing
 Legion never reads or writes a GitHub issue (LEGION-78). `pr comment`, `pr review`,
 `api …/pulls/…`, `api graphql`, and issue reads are unaffected. The credential reaches `legion`
 through the file `$LEGION_GRANT_FILE` names, written before each of your bash commands by the
-extension; never `cat`, `echo`, copy, or `export` it — `legion credential`, `legion gh`,
-`jj git push`, and `legion handoff complete` read it themselves. The file is the pane's, not the
+extension (and by the `legion` tool before its `handoff_complete`); never `cat`, `echo`, copy, or
+`export` it — `legion credential`, `legion gh`, `jj git push`, and `handoff_complete` read it
+themselves. The file is the pane's, not the
 command's: a `task` subagent, an `eval` subprocess, or a background job in your pane reads the
 grant your last bash command minted, so its `legion gh` or `jj git push` succeeds only within 60
 seconds of that call and 403s afterwards — a timing artifact, not a broken credential; run
@@ -343,7 +344,7 @@ this proof.
   hides an error, or breaks a gate lands in this PR.
 - **The implementer proves the change before its phase completes, and writes the `E2E (implementer)` line when the pull request opens.**
   The proof is the one defined above. It goes into `.legion/implement.json` as the required `proof`
-  array (`legion handoff write --phase implement` refuses a payload without one, or with a blank or
+  array (`handoff_write` for phase `implement` refuses a payload without one, or with a blank or
   whitespace-only field, and names the field), and into the PR body, because the reviewer and the
   merger verify facts on GitHub and never from a handoff.
 - **The tester verifies the implementer's proof and adds its own `E2E (tester)` line.** It re-runs
@@ -352,10 +353,10 @@ this proof.
   A test handoff whose predecessor carried no proof is a test failure, not a gap for the tester to fill:
   record it in `failures` with `implementerProof.verdict: "rejected"`, complete the phase, and let
   the architect return the issue to the implementer — the agent that developed the change owns
-  proving it (`legion handoff write --phase test` refuses a rejected verdict, or `failed > 0`,
+  proving it (`handoff_write` for phase `test` refuses a rejected verdict, or `failed > 0`,
   with no recorded failure). Otherwise, add your own proof before completing — a proof as defined
-  above — as the `E2E (tester)` line and the `proof` array `legion handoff write --phase test`
-  requires whenever you report no failure. A code path whose first execution is after merge — a
+  above — as the `E2E (tester)` line and the `proof` array `handoff_write` for
+  phase `test` requires whenever you report no failure. A code path whose first execution is after merge — a
   deploy workflow's inline step, a post-merge helper, a production-only resource — is untested
   until the implementer has executed it against a devN stack; if no surface can reach it, the
   tester names that missing surface as the blocker instead of passing the phase. Environment or
@@ -502,14 +503,11 @@ above.
 
 ## Completion gate: handoff write, verification, and persistence
 
-Write the phase-specific handoff:
+Write the phase-specific handoff: call the `legion` tool with `op: "handoff_write"`, `phase: "<p>"`,
+and `data`: a JSON object of the phase-specific fields only. It runs `legion handoff write` in
+`$LEGION_WORKSPACE` and returns its output.
 
-```bash
-cd -- "$LEGION_WORKSPACE" && \
-  legion handoff write --phase <p> --data '<JSON object of phase-specific fields only>'
-```
-
-`legion handoff write` validates the payload against the phase's schema before writing: an
+`handoff_write` validates the payload against the phase's schema before writing: an
 implement handoff without a well-formed `proof`, or a test handoff that reports no failure and
 carries no `proof` of its own, exits 1 naming the field and writes nothing.
 
@@ -554,17 +552,15 @@ that deletion at the reviewer's direction. No other phase removes it — and onc
 (`jj -R "$LEGION_WORKSPACE" file list -r @- .legion` prints nothing on stdout; jj warns on
 stderr), this gate no longer applies: a later rebase, bare-gate re-check, confirmation, retro, or
 the post-merge production check writes no `.legion/<phase>.json`, commits no handoff, and reports
-with `legion handoff complete` alone (below). Recreating `.legion/` after its deletion changes the
+with `handoff_complete` alone (below). Recreating `.legion/` after its deletion changes the
 approved head and restarts the review loop this rule exists to end.
 
 ## Completion: report to the architect, then stay
 
-Report completion to the architect with:
-
-```bash
-cd -- "$LEGION_WORKSPACE" && \
-  legion handoff complete --summary '<two sentences for the architect>'
-```
+Report completion to the architect: call the `legion` tool with `op: "handoff_complete"` and
+`summary`: two sentences for the architect. A worker never runs `legion handoff` from bash: the
+tool call is what the extension records, and a turn that ends with the phase still open gets one
+reminder.
 
 This publishes your phase's completion to the architect's role and clears the daemon's
 record of this issue's active phase. Do not add pipeline labels, run a controller loop, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "1.65.2",
+  "version": "1.66.0",
   "type": "module",
   "omp": {
     "extensions": [