@sjawhar/pi-legion-envoy 5.4.2 → 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}`);
@@ -34916,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;
@@ -35104,6 +35113,9 @@ function envoyExtension(pi) {
   let recordedSessionKey;
   let heartbeatRegistered = false;
   let claimedRoleTopic;
+  let claimedRoleSessionID;
+  const roleNoticeSubjects = new Set;
+  let roleEnds = 0;
   let activeSessionContext;
   const inbox = [];
   let askAwareness = {
@@ -35302,6 +35314,7 @@ function envoyExtension(pi) {
       return;
     if (intentionallyClosed.delete(topic))
       return;
+    const snapshot = roleSnapshot(topic);
     const retry = (delayMs) => {
       awaitingRetry.add(topic);
       setTimeout(() => {
@@ -35310,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);
@@ -35328,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,
@@ -35362,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,
@@ -35444,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);
@@ -35468,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);
@@ -35498,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;
@@ -35542,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 = {

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.2",
+  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/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.2",
+  "version": "5.4.3",
   "type": "module",
   "omp": {
     "extensions": [
@@ -13,7 +13,7 @@
   },
   "legion": {
     "daemonApiVersion": 8,
-    "goDaemonApiVersion": 6
+    "goDaemonApiVersion": 7
   },
   "repository": {
     "type": "git",