@sjawhar/pi-legion-envoy 5.4.1 → 5.4.3

package/dist/envoy.js

@@ -30520,6 +30520,9 @@ var LEGION_NOTICE_TOPIC_PREFIX = "notifications.legion.";
 function legionNoticeSubject(project, issue2) {
   return `${LEGION_NOTICE_TOPIC_PREFIX}${project}.${issue2}`;
 }
+function legionControllerNoticeSubject(project) {
+  return legionNoticeSubject(project, "controller");
+}
 var DISPATCH_TOPIC_PREFIX = "notifications.dispatch.";
 var DISPATCH_ISSUE_TOPIC_PREFIX = `${DISPATCH_TOPIC_PREFIX}issue.`;
 var DISPATCH_DOCUMENT_TOPIC_PREFIX = `${DISPATCH_TOPIC_PREFIX}document.`;
@@ -30549,6 +30552,12 @@ function isLegionRole(role) {
 function isLegionProjectToken(project) {
   return PROJECT_TOKEN.test(project);
 }
+function legionProjectToken(value, field) {
+  const project = value.toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (!project)
+    throw new Error(`${field} must include at least one alphanumeric character`);
+  return project;
+}
 function assertLegionProjectToken(project) {
   if (!isLegionProjectToken(project)) {
     throw new Error(`Invalid Legion project token: ${project}`);
@@ -34509,7 +34518,7 @@ var envoyToolSpecs = [
   },
   {
     name: "envoy_whoami",
-    description: "Returns this session's Envoy identity: session ID, machine ID, port, and directory.",
+    description: "Returns this session's Envoy identity: session ID, machine ID, port, and directory. session_id is the address a reply reaches. Where a host runs a task subagent inside its parent's process, such a subagent registers no Envoy session of its own, so its session_id is the parent session that spawned it and the result says so.",
     arguments: () => ({}),
     operation: EnvoyToolOperation.whoami,
     requiresSubscriptionCapability: false
@@ -34706,7 +34715,7 @@ function createEnvoyClient(config2) {
       const idempotencyKey = input.idempotencyKey ?? crypto.randomUUID();
       const response = EnvelopeResponseSchema.parse(JSON.parse(await post("/v1/messages/send", {
         source: input.source ?? "agent",
-        ...input.sourceSessionID === undefined ? {} : { source_session: input.sourceSessionID },
+        ...sourceSession(input.sourceSessionID),
         target_session: input.targetSessionID,
         message: input.message,
         idempotency_key: idempotencyKey,
@@ -34722,7 +34731,7 @@ function createEnvoyClient(config2) {
       const idempotencyKey = input.idempotencyKey ?? crypto.randomUUID();
       const response = EnvelopeResponseSchema.parse(JSON.parse(await post("/v1/messages/publish", {
         source: input.source ?? "agent",
-        ...input.sourceSessionID === undefined ? {} : { source_session: input.sourceSessionID },
+        ...sourceSession(input.sourceSessionID),
         topic: input.topic,
         message: input.message,
         ...input.payload === undefined ? {} : { payload: input.payload },
@@ -34785,11 +34794,56 @@ function messageMetadata(input) {
     ...input.expiresAt === undefined ? {} : { expires_at: input.expiresAt }
   };
 }
+function sourceSession(sessionID) {
+  return sessionID === undefined || sessionID === "" ? {} : { source_session: sessionID };
+}
 
 // extensions/envoy.ts
 import { logger } from "@oh-my-pi/pi-utils";
 var import_nats = __toESM(require_mod4(), 1);
 
+// src/envoy-session.ts
+import path2 from "path";
+var ENVOY_SESSIONS = Symbol.for("legion.pi-envoy.envoy-session");
+var store = globalThis;
+function recordedSessions() {
+  const existing = store[ENVOY_SESSIONS];
+  if (existing !== undefined)
+    return existing;
+  const created = new Map;
+  store[ENVOY_SESSIONS] = created;
+  return created;
+}
+function recordEnvoySession(entry) {
+  const sessions = recordedSessions();
+  const key = entry.sessionFile ?? (entry.sessionID === "" ? undefined : `session:${entry.sessionID}`);
+  if (entry.previousKey !== undefined && entry.previousKey !== key) {
+    sessions.delete(entry.previousKey);
+  }
+  if (key === undefined)
+    return;
+  sessions.set(key, entry.sessionID);
+  return key;
+}
+function resolveEnvoySession(sessionFile) {
+  const sessions = recordedSessions();
+  for (let candidate = sessionFile;candidate !== undefined; ) {
+    const directory = path2.dirname(candidate);
+    const parent = `${directory}.jsonl`;
+    if (parent === candidate)
+      break;
+    const recorded = sessions.get(parent);
+    if (recorded !== undefined)
+      return recorded;
+    if (path2.dirname(directory) === directory)
+      break;
+    candidate = parent;
+  }
+  if (sessions.size !== 1)
+    return "";
+  return [...sessions.values()][0] ?? "";
+}
+
 // src/legion/phase-stall.ts
 var PHASE_STALL_ENTRY = "legion-phase-stall";
 var LOCAL_ENVOY_NOTICE = { localNotice: true };
@@ -34851,8 +34905,8 @@ function restorePhaseStall(branch) {
 // src/legion/role-claim-bridge.ts
 var LEGION_ROLE_CLAIM_BRIDGE = Symbol.for("legion.pi-envoy.role-claim-bridge");
 function legionRoleClaimBridge() {
-  const store = globalThis;
-  const bridge = store[LEGION_ROLE_CLAIM_BRIDGE];
+  const store2 = globalThis;
+  const bridge = store2[LEGION_ROLE_CLAIM_BRIDGE];
   if (bridge)
     return bridge;
   const createdBridge = {
@@ -34860,7 +34914,7 @@ function legionRoleClaimBridge() {
     managedSessions: new Set,
     regained: undefined
   };
-  store[LEGION_ROLE_CLAIM_BRIDGE] = createdBridge;
+  store2[LEGION_ROLE_CLAIM_BRIDGE] = createdBridge;
   return createdBridge;
 }
 async function claimEnvoyRole(sessionID, role, context) {
@@ -34871,12 +34925,12 @@ async function claimEnvoyRole(sessionID, role, context) {
     throw new Error("Envoy has no bound instance for a role claim");
   await instance.claim(sessionID, role, context);
 }
-async function subscribeLegionNotice(sessionID, topic, context) {
+async function subscribeLegionNotice(sessionID, topic, context, whileHolding) {
   const bridge = legionRoleClaimBridge();
   const instance = bridge.instances.findLast((candidate) => candidate.sessionID() === sessionID) ?? bridge.instances.at(-1);
   if (instance === undefined)
     throw new Error("Envoy has no bound instance for a notice subscription");
-  await instance.subscribe(sessionID, topic, context);
+  await instance.subscribe(sessionID, topic, context, whileHolding);
 }
 function onEnvoyRoleRegained(listener) {
   legionRoleClaimBridge().regained = listener;
@@ -34884,7 +34938,7 @@ function onEnvoyRoleRegained(listener) {
 
 // src/subagent-session.ts
 import fs from "fs";
-import path2 from "path";
+import path3 from "path";
 import * as host from "@oh-my-pi/pi-coding-agent";
 var LEGION_BOOTSTRAPPED_SESSION = Symbol.for("legion.pi-envoy.bootstrapped-session");
 var bootstrappedSessionStore = globalThis;
@@ -34895,7 +34949,7 @@ async function isSubagentSession(context) {
   await context.sessionManager.ensureOnDisk();
   const sessionFile = context.sessionManager.getSessionFile();
   if (sessionFile !== undefined && fs.existsSync(sessionFile)) {
-    return fs.existsSync(`${path2.dirname(sessionFile)}.jsonl`);
+    return fs.existsSync(`${path3.dirname(sessionFile)}.jsonl`);
   }
   const bootstrapped = bootstrappedSessionStore[LEGION_BOOTSTRAPPED_SESSION];
   return bootstrapped !== undefined && bootstrapped !== sessionFile;
@@ -34954,11 +35008,11 @@ function registerEnvoyMessageRenderer(pi) {
 
 // extensions/envoy-whoami-command.ts
 import { copyToClipboard } from "@oh-my-pi/pi-coding-agent";
-function registerEnvoyWhoamiCommand(api2, cachedSessionID) {
+function registerEnvoyWhoamiCommand(api2, replyAddress) {
   api2.registerCommand("whoami", {
     description: "Copy session ID",
     handler: async (_args, context) => {
-      const sessionID = context.sessionManager.getSessionId() || cachedSessionID();
+      const sessionID = await replyAddress(context, context.sessionManager.getSessionId());
       if (sessionID === "") {
         context.ui.notify("No active session", "warning");
         return;
@@ -35056,8 +35110,12 @@ function envoyExtension(pi) {
   let connection;
   let sessionDirectory = "";
   let sessionID = "";
+  let recordedSessionKey;
   let heartbeatRegistered = false;
   let claimedRoleTopic;
+  let claimedRoleSessionID;
+  const roleNoticeSubjects = new Set;
+  let roleEnds = 0;
   let activeSessionContext;
   const inbox = [];
   let askAwareness = {
@@ -35122,6 +35180,11 @@ function envoyExtension(pi) {
   const restoreLocalSessionState = (context) => {
     sessionDirectory = context.cwd;
     sessionID = context.sessionManager.getSessionId();
+    recordedSessionKey = recordEnvoySession({
+      previousKey: recordedSessionKey,
+      sessionFile: context.sessionManager.getSessionFile(),
+      sessionID
+    });
     activeSessionContext = context;
     const branch = context.sessionManager.getBranch?.() ?? [];
     if (askAwareness.session_id !== sessionID) {
@@ -35251,6 +35314,7 @@ function envoyExtension(pi) {
       return;
     if (intentionallyClosed.delete(topic))
       return;
+    const snapshot = roleSnapshot(topic);
     const retry = (delayMs) => {
       awaitingRetry.add(topic);
       setTimeout(() => {
@@ -35259,7 +35323,7 @@ function envoyExtension(pi) {
           return;
         if (intentionallyClosed.delete(topic))
           return;
-        subscribe(topic).catch(() => retry(NATS_RETRY_INTERVAL_MS));
+        subscribeUnlessRoleEnds(topic, snapshot).catch(() => retry(NATS_RETRY_INTERVAL_MS));
       }, delayMs);
     };
     retry(RESUBSCRIBE_DELAY_MS);
@@ -35277,10 +35341,42 @@ function envoyExtension(pi) {
     }
     return true;
   };
+  const endRole = () => {
+    claimedRoleTopic = undefined;
+    claimedRoleSessionID = undefined;
+    roleEnds += 1;
+    for (const subject2 of roleNoticeSubjects)
+      closeIntentionally(subject2);
+    roleNoticeSubjects.clear();
+  };
+  const endOutgoingRole = () => {
+    if (claimedRoleSessionID !== sessionID)
+      endRole();
+  };
+  const roleSnapshot = (topic) => ({
+    roleBound: expandSubscriptionTopics([topic]).some((subject2) => roleNoticeSubjects.has(subject2)),
+    endsBefore: roleEnds
+  });
+  const subscribeUnlessRoleEnds = async (topic, snapshot) => {
+    const roleEnded = () => snapshot.roleBound && roleEnds !== snapshot.endsBefore;
+    if (roleEnded())
+      return false;
+    await subscribe(topic);
+    if (!roleEnded())
+      return true;
+    for (const subject2 of expandSubscriptionTopics([topic]))
+      closeIntentionally(subject2);
+    return false;
+  };
   const registerSession = () => client.subscribe({
     sessionID,
     directory: sessionDirectory,
-    topics: [...new Set([agentSubject(sessionID), ...subscriptions.keys()])],
+    topics: [
+      ...new Set([
+        agentSubject(sessionID),
+        ...[...subscriptions.keys()].filter((subject2) => !roleNoticeSubjects.has(subject2))
+      ])
+    ],
     port: 0,
     title: activeSessionContext?.sessionManager.getSessionName?.() ?? "",
     capabilities: typeof pi.askEphemeral === "function" ? DELIVERY_CAPABILITIES : CAPABILITIES_WITHOUT_BTW,
@@ -35311,7 +35407,7 @@ function envoyExtension(pi) {
         return;
       }
       if (!result.claimed) {
-        claimedRoleTopic = undefined;
+        endRole();
         logger.warn("envoy: role re-assertion refused; held by another live session", {
           role,
           sessionID: id,
@@ -35393,10 +35489,13 @@ function envoyExtension(pi) {
         sessionID,
         holder: result.holder
       });
-      claimedRoleTopic = undefined;
+      endRole();
       return false;
     }
+    if (previousTopic !== undefined && previousTopic !== topic)
+      endRole();
     claimedRoleTopic = topic;
+    claimedRoleSessionID = sessionID;
     pi.appendEntry(ROLE_CLAIM_ENTRY, { role });
     if (activeSessionContext !== undefined)
       ensureHeartbeat(activeSessionContext);
@@ -35417,10 +35516,10 @@ function envoyExtension(pi) {
   const roleSources = (previousSessionID, carryPreviousSessionRole) => previousSessionID === "" || previousSessionID === sessionID || !carryPreviousSessionRole ? [sessionID] : [sessionID, previousSessionID];
   const reclaimHeldRoles = async (previousSessionID, branch, carryPreviousSessionRole) => {
     if (!carryPreviousSessionRole)
-      claimedRoleTopic = undefined;
+      endOutgoingRole();
     const remembered = transcriptClaimedRole(branch);
     if (remembered === null) {
-      claimedRoleTopic = undefined;
+      endRole();
       return;
     }
     let role = remembered ?? claimedRoleTopic?.slice(ROLE_TOPIC_PREFIX.length);
@@ -35447,7 +35546,7 @@ function envoyExtension(pi) {
   const establishSessionNow = async (context, options = {}, previousSessionID = sessionID) => {
     const previousTopic = previousSessionID === "" ? undefined : agentSubject(previousSessionID);
     if (options.carryPreviousSessionRole === false)
-      claimedRoleTopic = undefined;
+      endOutgoingRole();
     restoreLocalSessionState(context);
     const branch = context.sessionManager.getBranch?.() ?? [];
     const resumed = branch.length > 0;
@@ -35491,14 +35590,22 @@ function envoyExtension(pi) {
     await registerSession();
     await setEnvoyRole(role);
   };
-  const subscribeNotice = async (targetSessionID, topic, callerContext) => {
+  const subscribeNotice = async (targetSessionID, topic, callerContext, whileHolding) => {
     const context = callerContext ?? activeSessionContext;
     if (context === undefined || context.sessionManager.getSessionId() !== targetSessionID) {
       throw new Error(`Envoy has no active session for Legion notice subscription: ${targetSessionID}`);
     }
     if (sessionID !== targetSessionID)
       await establishSession(context);
-    await subscribe(topic);
+    if (whileHolding !== undefined) {
+      if (claimedRoleTopic !== ROLE_TOPIC_PREFIX + whileHolding) {
+        throw new Error(`Envoy session ${targetSessionID} does not hold role ${whileHolding} for a notice subscription`);
+      }
+      for (const subject2 of expandSubscriptionTopics([topic]))
+        roleNoticeSubjects.add(subject2);
+    }
+    if (!await subscribeUnlessRoleEnds(topic, roleSnapshot(topic)))
+      return;
     await registerSession();
   };
   const claimInstance = {
@@ -35509,6 +35616,13 @@ function envoyExtension(pi) {
   bridge.instances.push(claimInstance);
   const isSubagentTranscript = subagentSessionCheck();
   const isSubagent = async (context) => await isSubagentTranscript(context) || isRegisteredSubagent(context);
+  const replyAddress = async (context, liveSessionID = "") => {
+    if (sessionID !== "")
+      return liveSessionID || sessionID;
+    if (!await isSubagent(context))
+      return liveSessionID;
+    return resolveEnvoySession(context.sessionManager.getSessionFile());
+  };
   pi.on("session_start", async (_event, context) => {
     if (await isSubagent(context))
       return;
@@ -35585,6 +35699,11 @@ function envoyExtension(pi) {
     const bound = bridge.instances.indexOf(claimInstance);
     if (bound !== -1)
       bridge.instances.splice(bound, 1);
+    recordedSessionKey = recordEnvoySession({
+      previousKey: recordedSessionKey,
+      sessionFile: undefined,
+      sessionID: ""
+    });
     const deadline = Promise.withResolvers();
     const timer = setTimeout(deadline.resolve, 1000);
     try {
@@ -35616,7 +35735,7 @@ function envoyExtension(pi) {
       description: spec.description,
       parameters: schemaFor(pi, spec.operation),
       lenientArgValidation: true,
-      execute: async (_id, parameters) => execute(spec.operation, parameters)
+      execute: async (_id, parameters, _signal, _onUpdate, context) => execute(spec.operation, parameters, context)
     });
   }
   if (dispatchConfig.enabled) {
@@ -35648,7 +35767,7 @@ function envoyExtension(pi) {
       });
     }
   }
-  registerEnvoyWhoamiCommand(pi, () => sessionID);
+  registerEnvoyWhoamiCommand(pi, replyAddress);
   pi.on("before_agent_start", async (event, context) => {
     const id = context.sessionManager.getSessionId();
     if (id === "" || event.prompt.trim() === "" || !context.hasUI || askEphemeral === undefined || legionManaged(id)) {
@@ -35796,7 +35915,7 @@ function envoyExtension(pi) {
     }
     announceFollow(event.details);
   });
-  async function execute(operation, rawParameters) {
+  async function execute(operation, rawParameters, context) {
     try {
       const parameters = parseEnvoyToolArguments(operation, rawParameters);
       switch (operation) {
@@ -35849,7 +35968,7 @@ Warnings: ${warnings.join("; ")}`, {
         case EnvoyToolOperation.send: {
           const targetSessionID = stringFor(parameters, "session_id");
           const result = await client.send({
-            sourceSessionID: sessionID,
+            sourceSessionID: await replyAddress(context),
             targetSessionID,
             message: stringFor(parameters, "message"),
             ...toMessageMetadata(parameters)
@@ -35862,16 +35981,21 @@ Warnings: ${warnings.join("; ")}`, {
         }
         case EnvoyToolOperation.publish: {
           const topic = stringFor(parameters, "topic");
+          const source = await replyAddress(context);
           const result = await client.publish({
-            sourceSessionID: sessionID,
+            sourceSessionID: source,
             topic,
             message: stringFor(parameters, "message"),
             ...toMessageMetadata(parameters)
           });
-          return toolSuccess(result.holder === undefined ? `published ${result.envelope.event_id}` : `published ${result.envelope.event_id}; holder ${result.holder}`, {
+          const undelivered = source !== "" && result.holder === source && await isSubagent(context);
+          const published = result.holder === undefined ? `published ${result.envelope.event_id}` : `published ${result.envelope.event_id}; holder ${result.holder}`;
+          return toolSuccess(undelivered ? `${published}
+Not delivered: that holder is the session this subagent sends as, and the listener drops a message whose source session is its recipient, so the agent that spawned you did not receive it. Reach it over hub instead.` : published, {
             event_id: result.envelope.event_id,
             topic,
-            ...result.holder === undefined ? {} : { holder: result.holder }
+            ...result.holder === undefined ? {} : { holder: result.holder },
+            ...undelivered ? { undelivered_echo: true } : {}
           });
         }
         case EnvoyToolOperation.setRole: {
@@ -35884,9 +36008,21 @@ Warnings: ${warnings.join("; ")}`, {
           return toolSuccess(JSON.stringify(role, null, 2), role);
         }
         case EnvoyToolOperation.whoami: {
-          return toolSuccess(JSON.stringify({ session_id: sessionID, machine_id: machineID(), dir: sessionDirectory }, null, 2), {
-            sessionID,
-            topics: [...subscriptions.keys()]
+          const inSubagent = await isSubagent(context);
+          const address = await replyAddress(context);
+          const subagent = inSubagent ? {
+            session_id: context.sessionManager.getSessionId(),
+            note: address === "" ? "This session is a task subagent and registers no Envoy session of its own, and this process records no top-level session its transcript traces back to, so it has no reply address at all: say who you are in the message body, and reach the agent that spawned you over hub." : "This session is a task subagent and registers no Envoy session of its own; a reply to session_id reaches the agent that spawned it, which relays over hub. Your own envoy_publish never reaches that agent \u2014 use hub for that hop."
+          } : undefined;
+          return toolSuccess(JSON.stringify({
+            session_id: address,
+            machine_id: machineID(),
+            dir: sessionDirectory || context.cwd,
+            ...subagent === undefined ? {} : { subagent }
+          }, null, 2), {
+            sessionID: address,
+            topics: [...subscriptions.keys()],
+            ...subagent === undefined ? {} : { subagent }
           });
         }
         case EnvoyToolOperation.listSessions: {

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: "5.4.1",
+  version: "5.4.3",
   type: "module",
   omp: {
     extensions: [
@@ -16155,7 +16155,7 @@ var package_default = {
   },
   legion: {
     daemonApiVersion: 8,
-    goDaemonApiVersion: 6
+    goDaemonApiVersion: 7
   },
   repository: {
     type: "git",
@@ -30593,6 +30593,9 @@ var LEGION_NOTICE_TOPIC_PREFIX = "notifications.legion.";
 function legionNoticeSubject(project, issue2) {
   return `${LEGION_NOTICE_TOPIC_PREFIX}${project}.${issue2}`;
 }
+function legionControllerNoticeSubject(project) {
+  return legionNoticeSubject(project, "controller");
+}
 var DISPATCH_TOPIC_PREFIX = "notifications.dispatch.";
 var DISPATCH_ISSUE_TOPIC_PREFIX = `${DISPATCH_TOPIC_PREFIX}issue.`;
 var DISPATCH_DOCUMENT_TOPIC_PREFIX = `${DISPATCH_TOPIC_PREFIX}document.`;
@@ -30622,6 +30625,12 @@ function isLegionRole(role) {
 function isLegionProjectToken(project) {
   return PROJECT_TOKEN.test(project);
 }
+function legionProjectToken(value, field) {
+  const project = value.toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (!project)
+    throw new Error(`${field} must include at least one alphanumeric character`);
+  return project;
+}
 function assertLegionProjectToken(project) {
   if (!isLegionProjectToken(project)) {
     throw new Error(`Invalid Legion project token: ${project}`);
@@ -31234,12 +31243,12 @@ async function claimEnvoyRole(sessionID, role, context) {
     throw new Error("Envoy has no bound instance for a role claim");
   await instance.claim(sessionID, role, context);
 }
-async function subscribeLegionNotice(sessionID, topic, context) {
+async function subscribeLegionNotice(sessionID, topic, context, whileHolding) {
   const bridge = legionRoleClaimBridge();
   const instance = bridge.instances.findLast((candidate) => candidate.sessionID() === sessionID) ?? bridge.instances.at(-1);
   if (instance === undefined)
     throw new Error("Envoy has no bound instance for a notice subscription");
-  await instance.subscribe(sessionID, topic, context);
+  await instance.subscribe(sessionID, topic, context, whileHolding);
 }
 function onEnvoyRoleRegained(listener) {
   legionRoleClaimBridge().regained = listener;
@@ -31429,6 +31438,7 @@ var legionGoIssue = exports_external.strictObject({
   generation: exports_external.number().int().nonnegative(),
   phase: exports_external.enum(LEGION_GO_PHASES),
   status: nonEmptyString2,
+  holdReason: exports_external.literal("escalated").optional(),
   architect: legionGoClaimView.optional(),
   workers: exports_external.partialRecord(exports_external.enum(LEGION_ROLES), legionGoPhaseView),
   pullRequest: legionGoPullRequestView.optional(),
@@ -31765,8 +31775,14 @@ async function callGoReadyWithRetry(label, call) {
 function goControllerDaemon(daemon, transcript) {
   return {
     claim: async ({ sessionID, capability, context }) => {
-      const { sessionFile, agentId } = await transcript(context);
+      const project = requiredEnvironment(process.env, "LEGION_PROJECT");
       const client = daemon();
+      const { daemon: served } = await client.state();
+      const servedRole = controllerToken(legionProjectToken(served.project, "the daemon's project"));
+      if (controllerToken(project) !== servedRole) {
+        throw new Error(`LEGION_PROJECT ${project} names controller role ${controllerToken(project)}, but the daemon at ${requiredEnvironment(process.env, "LEGION_DAEMON_URL")} serves project ${served.project}, whose controller role is ${servedRole}`);
+      }
+      const { sessionFile, agentId } = await transcript(context);
       const registration = await client.registerController({
         bootToken: capability,
         sessionId: sessionID,
@@ -31779,7 +31795,12 @@ function goControllerDaemon(daemon, transcript) {
         }
         throw error48;
       });
-      await claimEnvoyRole(sessionID, registration.claimToken, "setInterval" in context ? context : undefined);
+      if (controllerToken(project) !== registration.claimToken) {
+        throw new Error(`LEGION_PROJECT ${project} names controller role ${controllerToken(project)}, but the daemon registered this controller as ${registration.claimToken}`);
+      }
+      const envoyContext = "setInterval" in context ? context : undefined;
+      await claimEnvoyRole(sessionID, registration.claimToken, envoyContext);
+      await subscribeLegionNotice(sessionID, legionControllerNoticeSubject(project), envoyContext, registration.claimToken);
       return () => client.controllerGrant({ sessionId: sessionID, secret: registration.secret });
     }
   };

package/dist/skills/envoy/SKILL.md

@@ -106,6 +106,25 @@ envoy_send(
 )
 ```
 
+### Your own address, and a subagent's
+
+`envoy_whoami`'s `session_id` is the address a reply to you reaches. Inside a `task` subagent it
+is the session that spawned you: a subagent registers no Envoy session of its own, so a peer
+answering it reaches that session, which relays to you over hub. The `subagent` field in that
+output carries your own host session id — it is not an address, so never hand it to a peer.
+
+`session_id` is empty when nothing can be reached: a process that took no Envoy identity, or a
+subagent whose spawning session this process can no longer place (it forked away, and other
+top-level sessions are running). Then your messages carry no sender either, so say who you are
+in the message body. An empty address is deliberate — being handed an unrelated live session
+would send your peers to an agent that never spawned you.
+
+Your own `envoy_publish` never reaches the agent that spawned you. The listener delivers nothing
+to the session a message names as its source, and inside a subagent that source is your parent,
+so a publish to a role it holds — or to any topic it subscribes to — is accepted and delivered to
+nobody. Use hub for that one hop. `envoy_send` to any other session, including a reply, is
+unaffected.
+
 ### Delivery capabilities
 
 Each session row from `envoy_sessions` carries `capabilities`, the targeted-delivery modes that

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

@@ -71,9 +71,11 @@ launcher, and started you with `LEGION_CONTROLLER=1` and the same environment a
 carries, so nothing changes in how you handle wakes. Under the TypeScript daemon the extension
 claims the role and calls `/controller/ready` exactly as under tmux; under the Go daemon
 (`LEGION_DAEMON_API=go` in your environment) it registers on `/legion/v1/claims/register` with the
-secret, then claims the role. The daemon records you as `controllerLocator: {runtime, external:
-true, sessionId, registeredAt}`, `runtime` being the daemon's own (`kubernetes`, or `tmux` under the
-Go daemon). The TypeScript daemon reads your liveness from the Envoy role registry (the holder of
+secret, claims the role, then subscribes to `notifications.legion.<project>.controller`, where the
+Go daemon publishes the two Go rows of the wake routing table. The daemon records you as
+`controllerLocator: {runtime, external: true, sessionId, registeredAt}`, `runtime` being the
+daemon's own (`kubernetes`, or `tmux` under the Go daemon). The TypeScript daemon reads your
+liveness from the Envoy role registry (the holder of
 `legion-<project>-controller` and its `last_seen`), not from a pane: keep the session running.
 Exiting it leaves the project without a controller until the operator runs the command again —
 the TypeScript daemon logs `controller not registered; run legion controller start` once per
@@ -81,6 +83,20 @@ boot-timeout interval and launches nothing itself. `legion state` and `legion st
 <status>` work here over `LEGION_DAEMON_URL`. A second `legion controller start` replaces you: it
 mints a new secret, so your grants stop working and the role moves to the new session.
 
+### What happened before you started (Go daemon)
+
+The Go daemon's controller topic is a wake for a session that is running when it is published.
+Envoy hands an Oh My Pi session no retained copy of a notice published before it subscribed, so a
+hold or a tree architect's failed claim from while no controller ran never arrives as a wake. At
+every start, before anything else, read `legion state --json` and handle each issue whose
+`issues.<KEY>.phase` is `held` (its `issues.<KEY>.holdReason` is `escalated` when its architect
+sent it to you, and absent while the architect is still deciding or while its tree lingers or is
+closed, where the hold waits for the tree's re-admission and needs nothing from you), and each
+tree root whose `issues.<KEY>.architect.state` is `failed` and whose `issues.<KEY>.phase` is not
+`done`, exactly as the matching wake below. A parked tree (root phase `done`: it lingers or is
+closed) needs nothing from you: a failed architect ignores the park and reads `failed` until the
+tree closes. The issue record is the truth; the topic is the wake.
+
 ## Deployment instructions
 
 Deployment instructions, when present, are the operator's standing rules for this repository —
@@ -116,6 +132,8 @@ quoted here.
 | Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
 | READY packet seen on a Dispatch issue (via issue subscription) | READY line + gate facts | No action: a human merges; the merger has already notified the queue role if the project has one |
 | `worker-recovered` (role `architect`) from the daemon | issue, fromRef | A root architect's tree volume was lost; it restarted as a new session. Verify the tree is active in `legion state` and that the architect posts its next step on the issue within one resync interval; otherwise treat it as an anomaly. |
+| `held on <KEY>` from the Go daemon (payload `{kind: "held", phase, role?, reason?}`) | the held issue, the phase it left, and the role whose claim failed, or `reason: "escalated"` | Verify the hold in `legion state` (the issue's phase is `held`). Without `reason`, a phase worker's launches or prompts ran out and the tree's architect decides retry or escalate: no action. With `reason: "escalated"` (on the record, `issues.<KEY>.holdReason` is `escalated`), the architect sent it to you: handle it as an architect escalation below. Parking the tree is `legion status <root> backlog`; setting the root back to `todo` later re-admits it as a new generation, which starts again from its architect |
+| `worker-died on <KEY>` from the Go daemon with `role: "architect"` | the tree root whose architect's claim failed, and the phase the root was in | The tree's architect ran out of launches or prompts and the daemon relaunches nothing; every other notice of the tree goes to that architect, so nobody inside the tree can act. Verify in `legion state` (`issues.<KEY>.architect.state` is `failed`); if the root's phase is `done`, the tree is already parked: no action. Otherwise re-admit the tree (`legion status <root> backlog`, then `todo`: a new generation, whose architect starts again with fresh budgets) or leave it parked and say why on the issue |
 | Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion status <root> todo`; otherwise no action — the event is not held or redelivered |
 | Direct user message | — | Always first |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "5.4.1",
+  "version": "5.4.3",
   "type": "module",
   "omp": {
     "extensions": [
@@ -13,7 +13,7 @@
   },
   "legion": {
     "daemonApiVersion": 8,
-    "goDaemonApiVersion": 6
+    "goDaemonApiVersion": 7
   },
   "repository": {
     "type": "git",