@sjawhar/pi-legion-envoy 0.16.1 → 0.18.0

package/dist/envoy.js

@@ -16117,7 +16117,7 @@ import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 
 // ../contracts/src/dispatch-tools.ts
-var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue on first use when its repository is mapped in DISPATCH_REPO_PROJECTS.";
+var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue on first use in the repository's mapped project (DISPATCH_REPO_PROJECTS) or, failing that, the default project (DISPATCH_DEFAULT_PROJECT).";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
 var DOC_EDIT_OPS = ["replace", "delete", "insert"];
 var dispatchToolSpecs = [
@@ -31684,7 +31684,7 @@ async function ensureIssue(client, issueReference, actor) {
   } catch (error) {
     if (error instanceof DispatchServiceError && error.code === "PROJECT_UNMAPPED") {
       const repository = issueReference.slice(0, issueReference.lastIndexOf("#"));
-      throw new Error(`repository ${repository} is not mapped in DISPATCH_REPO_PROJECTS`);
+      throw new Error(`repository ${repository} is not mapped in DISPATCH_REPO_PROJECTS and no DISPATCH_DEFAULT_PROJECT is configured`);
     }
     throw error;
   }
@@ -31849,6 +31849,11 @@ var RoleWireSchema = object({
   holder: string2(),
   last_seen: number2().int()
 });
+var RoleHeldWireSchema = object({
+  error: string2(),
+  role: string2(),
+  holder: string2()
+});
 var ErrorWireSchema = object({
   error: string2(),
   expected: array(string2()).optional()
@@ -31981,7 +31986,28 @@ function createEnvoyClient(config) {
     unregisterSession: async (sessionID) => {
       await request(`/v1/sessions/${encodeURIComponent(sessionID)}`, { method: "DELETE" });
     },
-    setRole: async (input) => InterestWireSchema.parse(JSON.parse(await post("/v1/roles/set", { session_id: input.sessionID, role: input.role }))),
+    setRole: async (input) => {
+      const soft = input.soft === true;
+      const previous = soft ? input.previousSessionID ?? "" : "";
+      const body = {
+        session_id: input.sessionID,
+        role: input.role,
+        ...soft ? { soft: true } : {},
+        ...previous === "" ? {} : { previous_session_id: previous }
+      };
+      let raw;
+      try {
+        raw = await post("/v1/roles/set", body);
+      } catch (error) {
+        if (error instanceof EnvoyApiError && error.details.status === 409) {
+          const held = RoleHeldWireSchema.safeParse(JSON.parse(error.details.responseBody));
+          if (held.success)
+            return { claimed: false, holder: held.data.holder };
+        }
+        throw error;
+      }
+      return { claimed: true, interest: InterestWireSchema.parse(JSON.parse(raw)) };
+    },
     getRole: async (role) => RoleWireSchema.parse(JSON.parse(await request(`/v1/roles/${encodeURIComponent(role)}`, { method: "GET" }))),
     listSessions: async (input = {}) => {
       const search = new URLSearchParams;
@@ -32077,6 +32103,20 @@ async function copySessionID(copyToClipboard, sessionID) {
 // extensions/envoy.ts
 var codec2 = import_nats.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
+var ROLE_CLAIM_ENTRY = "envoy-role-claim";
+function isRoleClaimEntry(entry) {
+  if (typeof entry !== "object" || entry === null)
+    return false;
+  if (!("type" in entry) || entry.type !== "custom")
+    return false;
+  if (!("customType" in entry) || entry.customType !== ROLE_CLAIM_ENTRY)
+    return false;
+  if (!("data" in entry) || typeof entry.data !== "object" || entry.data === null)
+    return false;
+  if (!("role" in entry.data))
+    return false;
+  return entry.data.role === null || typeof entry.data.role === "string";
+}
 var LEGION_ROLE_CLAIM_BRIDGE = Symbol.for("legion.pi-envoy.role-claim-bridge");
 function legionRoleClaimBridge() {
   const store = globalThis;
@@ -32274,8 +32314,81 @@ function envoyExtension(pi) {
       await subscribe(topic);
     }
   };
-  const establishSession = async (context) => {
+  const setEnvoyRole = async (role, options = {}) => {
+    const topic = ROLE_TOPIC_PREFIX + role;
+    const previousTopic = claimedRoleTopic;
+    const result = await client.setRole({
+      sessionID,
+      role,
+      soft: options.soft,
+      previousSessionID: options.previousSessionID
+    });
+    if (!result.claimed) {
+      logger.warn("envoy: role held by another live session; not reclaimed", {
+        role,
+        sessionID,
+        holder: result.holder
+      });
+      claimedRoleTopic = undefined;
+      return false;
+    }
+    claimedRoleTopic = topic;
+    pi.appendEntry(ROLE_CLAIM_ENTRY, { role });
+    if (activeSessionContext !== undefined)
+      ensureHeartbeat(activeSessionContext);
+    if (previousTopic !== undefined && previousTopic !== topic) {
+      await client.unsubscribe({ sessionID, topics: [previousTopic] });
+    }
+    return true;
+  };
+  const releaseClaimedRole = () => {
+    claimedRoleTopic = undefined;
+    pi.appendEntry(ROLE_CLAIM_ENTRY, { role: null });
+  };
+  const transcriptClaimedRole = (branch) => {
+    let role;
+    for (const entry of branch) {
+      if (!isRoleClaimEntry(entry))
+        continue;
+      role = entry.data.role;
+    }
+    return role;
+  };
+  const roleSources = (previousSessionID, carryPreviousSessionRole) => previousSessionID === "" || previousSessionID === sessionID || !carryPreviousSessionRole ? [sessionID] : [sessionID, previousSessionID];
+  const reclaimHeldRoles = async (previousSessionID, branch, carryPreviousSessionRole) => {
+    if (!carryPreviousSessionRole)
+      claimedRoleTopic = undefined;
+    const remembered = transcriptClaimedRole(branch);
+    if (remembered === null) {
+      claimedRoleTopic = undefined;
+      return;
+    }
+    let role = remembered ?? claimedRoleTopic?.slice(ROLE_TOPIC_PREFIX.length);
+    if (role === undefined) {
+      for (const source of roleSources(previousSessionID, carryPreviousSessionRole)) {
+        const registry = await client.getInterest(source).catch(() => {
+          return;
+        });
+        const topic = registry?.topics.find((candidate) => candidate.startsWith(ROLE_TOPIC_PREFIX));
+        if (topic !== undefined) {
+          role = topic.slice(ROLE_TOPIC_PREFIX.length);
+          break;
+        }
+      }
+    }
+    if (role === undefined)
+      return;
+    const continued = carryPreviousSessionRole && previousSessionID !== "" && previousSessionID !== sessionID ? previousSessionID : undefined;
+    await setEnvoyRole(role, { soft: true, previousSessionID: continued }).catch((error) => {
+      logger.warn("envoy: role reclaim failed", { role, sessionID, error: messageFor(error) });
+    });
+  };
+  let sessionEstablishment = Promise.resolve();
+  const establishSessionNow = async (context, options = {}) => {
+    const previousSessionID = sessionID;
     const previousTopic = sessionID === "" ? undefined : agentSubject(sessionID);
+    if (options.carryPreviousSessionRole === false)
+      claimedRoleTopic = undefined;
     sessionDirectory = context.cwd;
     sessionID = context.sessionManager.getSessionId();
     activeSessionContext = context;
@@ -32291,22 +32404,23 @@ function envoyExtension(pi) {
     }
     await ensureConnection();
     await subscribe(currentTopic);
-    if ((context.sessionManager.getBranch?.() ?? []).length > 0) {
+    const branch = context.sessionManager.getBranch?.() ?? [];
+    const resumed = branch.length > 0;
+    if (resumed) {
       await recoverRegisteredInterests();
     }
     await registerSession();
+    if (resumed || previousSessionID !== "") {
+      await reclaimHeldRoles(previousSessionID, branch, options.carryPreviousSessionRole ?? true);
+    }
     ensureHeartbeat(context);
   };
-  const setEnvoyRole = async (role) => {
-    const topic = ROLE_TOPIC_PREFIX + role;
-    const previousTopic = claimedRoleTopic;
-    await client.setRole({ sessionID, role });
-    claimedRoleTopic = topic;
-    if (activeSessionContext !== undefined)
-      ensureHeartbeat(activeSessionContext);
-    if (previousTopic !== undefined && previousTopic !== topic) {
-      await client.unsubscribe({ sessionID, topics: [previousTopic] });
-    }
+  const establishSession = (context, options = {}) => {
+    const run = sessionEstablishment.then(() => establishSessionNow(context, options), () => establishSessionNow(context, options));
+    sessionEstablishment = run.catch(() => {
+      return;
+    });
+    return run;
   };
   const bridge = legionRoleClaimBridge();
   const claim = async (targetSessionID, role, callerContext) => {
@@ -32316,8 +32430,8 @@ function envoyExtension(pi) {
     }
     if (sessionID !== targetSessionID)
       await establishSession(context);
-    await setEnvoyRole(role);
     await registerSession();
+    await setEnvoyRole(role);
   };
   bridge.claim = claim;
   bridge.ready.resolve(claim);
@@ -32359,7 +32473,8 @@ function envoyExtension(pi) {
       return;
     const previousID = sessionID;
     try {
-      await establishSession(context);
+      const carryPreviousSessionRole = reason !== "new" && reason !== "resume";
+      await establishSession(context, { carryPreviousSessionRole });
     } catch (error) {
       context.ui.notify(`envoy: rebind failed (${messageFor(error)}); will recover on reconnect`, "warning");
     }
@@ -32493,12 +32608,12 @@ Warnings: ${warnings.join("; ")}`, {
             ...claimedRoleTopic === undefined ? [] : [claimedRoleTopic]
           ]).filter((topic) => topic !== inbox);
           const removed = targets.filter((topic) => closeIntentionally(topic) || topic === claimedRoleTopic);
-          if (claimedRoleTopic !== undefined && removed.includes(claimedRoleTopic)) {
-            claimedRoleTopic = undefined;
-          }
+          const releasingRole = claimedRoleTopic !== undefined && removed.includes(claimedRoleTopic);
           const registrationError = removed.length === 0 ? undefined : await client.unsubscribe({ sessionID, topics: removed }).then(registerSession).then(() => {
             return;
           }, messageFor);
+          if (releasingRole && registrationError === undefined)
+            releaseClaimedRole();
           return toolSuccess(`Unsubscribed: ${removed.join(", ") || "(none)"}`, {
             removed,
             ...registrationError === undefined ? {} : { registrationError }

package/dist/legion.js

@@ -16115,7 +16115,7 @@ var require_mod4 = __commonJS(function(exports) {
 import path4 from "path";
 
 // ../contracts/src/dispatch-tools.ts
-var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue on first use when its repository is mapped in DISPATCH_REPO_PROJECTS.";
+var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue on first use in the repository's mapped project (DISPATCH_REPO_PROJECTS) or, failing that, the default project (DISPATCH_DEFAULT_PROJECT).";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
 var DOC_EDIT_OPS = ["replace", "delete", "insert"];
 var dispatchToolSpecs = [
@@ -32174,7 +32174,7 @@ async function ensureIssue(client, issueReference, actor) {
   } catch (error) {
     if (error instanceof DispatchServiceError && error.code === "PROJECT_UNMAPPED") {
       const repository = issueReference.slice(0, issueReference.lastIndexOf("#"));
-      throw new Error(`repository ${repository} is not mapped in DISPATCH_REPO_PROJECTS`);
+      throw new Error(`repository ${repository} is not mapped in DISPATCH_REPO_PROJECTS and no DISPATCH_DEFAULT_PROJECT is configured`);
     }
     throw error;
   }
@@ -32339,6 +32339,11 @@ var RoleWireSchema = object({
   holder: string2(),
   last_seen: number2().int()
 });
+var RoleHeldWireSchema = object({
+  error: string2(),
+  role: string2(),
+  holder: string2()
+});
 var ErrorWireSchema = object({
   error: string2(),
   expected: array(string2()).optional()
@@ -32471,7 +32476,28 @@ function createEnvoyClient(config) {
     unregisterSession: async (sessionID) => {
       await request(`/v1/sessions/${encodeURIComponent(sessionID)}`, { method: "DELETE" });
     },
-    setRole: async (input) => InterestWireSchema.parse(JSON.parse(await post("/v1/roles/set", { session_id: input.sessionID, role: input.role }))),
+    setRole: async (input) => {
+      const soft = input.soft === true;
+      const previous = soft ? input.previousSessionID ?? "" : "";
+      const body = {
+        session_id: input.sessionID,
+        role: input.role,
+        ...soft ? { soft: true } : {},
+        ...previous === "" ? {} : { previous_session_id: previous }
+      };
+      let raw;
+      try {
+        raw = await post("/v1/roles/set", body);
+      } catch (error) {
+        if (error instanceof EnvoyApiError && error.details.status === 409) {
+          const held = RoleHeldWireSchema.safeParse(JSON.parse(error.details.responseBody));
+          if (held.success)
+            return { claimed: false, holder: held.data.holder };
+        }
+        throw error;
+      }
+      return { claimed: true, interest: InterestWireSchema.parse(JSON.parse(raw)) };
+    },
     getRole: async (role) => RoleWireSchema.parse(JSON.parse(await request(`/v1/roles/${encodeURIComponent(role)}`, { method: "GET" }))),
     listSessions: async (input = {}) => {
       const search = new URLSearchParams;
@@ -32559,6 +32585,20 @@ async function copySessionID(copyToClipboard, sessionID) {
 // extensions/envoy.ts
 var codec2 = import_nats.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
+var ROLE_CLAIM_ENTRY = "envoy-role-claim";
+function isRoleClaimEntry(entry) {
+  if (typeof entry !== "object" || entry === null)
+    return false;
+  if (!("type" in entry) || entry.type !== "custom")
+    return false;
+  if (!("customType" in entry) || entry.customType !== ROLE_CLAIM_ENTRY)
+    return false;
+  if (!("data" in entry) || typeof entry.data !== "object" || entry.data === null)
+    return false;
+  if (!("role" in entry.data))
+    return false;
+  return entry.data.role === null || typeof entry.data.role === "string";
+}
 var LEGION_ROLE_CLAIM_BRIDGE = Symbol.for("legion.pi-envoy.role-claim-bridge");
 function legionRoleClaimBridge() {
   const store = globalThis;
@@ -32756,8 +32796,81 @@ function envoyExtension(pi) {
       await subscribe(topic);
     }
   };
-  const establishSession = async (context) => {
+  const setEnvoyRole = async (role, options = {}) => {
+    const topic = ROLE_TOPIC_PREFIX + role;
+    const previousTopic = claimedRoleTopic;
+    const result = await client.setRole({
+      sessionID,
+      role,
+      soft: options.soft,
+      previousSessionID: options.previousSessionID
+    });
+    if (!result.claimed) {
+      logger.warn("envoy: role held by another live session; not reclaimed", {
+        role,
+        sessionID,
+        holder: result.holder
+      });
+      claimedRoleTopic = undefined;
+      return false;
+    }
+    claimedRoleTopic = topic;
+    pi.appendEntry(ROLE_CLAIM_ENTRY, { role });
+    if (activeSessionContext !== undefined)
+      ensureHeartbeat(activeSessionContext);
+    if (previousTopic !== undefined && previousTopic !== topic) {
+      await client.unsubscribe({ sessionID, topics: [previousTopic] });
+    }
+    return true;
+  };
+  const releaseClaimedRole = () => {
+    claimedRoleTopic = undefined;
+    pi.appendEntry(ROLE_CLAIM_ENTRY, { role: null });
+  };
+  const transcriptClaimedRole = (branch) => {
+    let role;
+    for (const entry of branch) {
+      if (!isRoleClaimEntry(entry))
+        continue;
+      role = entry.data.role;
+    }
+    return role;
+  };
+  const roleSources = (previousSessionID, carryPreviousSessionRole) => previousSessionID === "" || previousSessionID === sessionID || !carryPreviousSessionRole ? [sessionID] : [sessionID, previousSessionID];
+  const reclaimHeldRoles = async (previousSessionID, branch, carryPreviousSessionRole) => {
+    if (!carryPreviousSessionRole)
+      claimedRoleTopic = undefined;
+    const remembered = transcriptClaimedRole(branch);
+    if (remembered === null) {
+      claimedRoleTopic = undefined;
+      return;
+    }
+    let role = remembered ?? claimedRoleTopic?.slice(ROLE_TOPIC_PREFIX.length);
+    if (role === undefined) {
+      for (const source of roleSources(previousSessionID, carryPreviousSessionRole)) {
+        const registry = await client.getInterest(source).catch(() => {
+          return;
+        });
+        const topic = registry?.topics.find((candidate) => candidate.startsWith(ROLE_TOPIC_PREFIX));
+        if (topic !== undefined) {
+          role = topic.slice(ROLE_TOPIC_PREFIX.length);
+          break;
+        }
+      }
+    }
+    if (role === undefined)
+      return;
+    const continued = carryPreviousSessionRole && previousSessionID !== "" && previousSessionID !== sessionID ? previousSessionID : undefined;
+    await setEnvoyRole(role, { soft: true, previousSessionID: continued }).catch((error) => {
+      logger.warn("envoy: role reclaim failed", { role, sessionID, error: messageFor(error) });
+    });
+  };
+  let sessionEstablishment = Promise.resolve();
+  const establishSessionNow = async (context, options = {}) => {
+    const previousSessionID = sessionID;
     const previousTopic = sessionID === "" ? undefined : agentSubject(sessionID);
+    if (options.carryPreviousSessionRole === false)
+      claimedRoleTopic = undefined;
     sessionDirectory = context.cwd;
     sessionID = context.sessionManager.getSessionId();
     activeSessionContext = context;
@@ -32773,22 +32886,23 @@ function envoyExtension(pi) {
     }
     await ensureConnection();
     await subscribe(currentTopic);
-    if ((context.sessionManager.getBranch?.() ?? []).length > 0) {
+    const branch = context.sessionManager.getBranch?.() ?? [];
+    const resumed = branch.length > 0;
+    if (resumed) {
       await recoverRegisteredInterests();
     }
     await registerSession();
+    if (resumed || previousSessionID !== "") {
+      await reclaimHeldRoles(previousSessionID, branch, options.carryPreviousSessionRole ?? true);
+    }
     ensureHeartbeat(context);
   };
-  const setEnvoyRole = async (role) => {
-    const topic = ROLE_TOPIC_PREFIX + role;
-    const previousTopic = claimedRoleTopic;
-    await client.setRole({ sessionID, role });
-    claimedRoleTopic = topic;
-    if (activeSessionContext !== undefined)
-      ensureHeartbeat(activeSessionContext);
-    if (previousTopic !== undefined && previousTopic !== topic) {
-      await client.unsubscribe({ sessionID, topics: [previousTopic] });
-    }
+  const establishSession = (context, options = {}) => {
+    const run = sessionEstablishment.then(() => establishSessionNow(context, options), () => establishSessionNow(context, options));
+    sessionEstablishment = run.catch(() => {
+      return;
+    });
+    return run;
   };
   const bridge = legionRoleClaimBridge();
   const claim = async (targetSessionID, role, callerContext) => {
@@ -32798,8 +32912,8 @@ function envoyExtension(pi) {
     }
     if (sessionID !== targetSessionID)
       await establishSession(context);
-    await setEnvoyRole(role);
     await registerSession();
+    await setEnvoyRole(role);
   };
   bridge.claim = claim;
   bridge.ready.resolve(claim);
@@ -32841,7 +32955,8 @@ function envoyExtension(pi) {
       return;
     const previousID = sessionID;
     try {
-      await establishSession(context);
+      const carryPreviousSessionRole = reason !== "new" && reason !== "resume";
+      await establishSession(context, { carryPreviousSessionRole });
     } catch (error) {
       context.ui.notify(`envoy: rebind failed (${messageFor(error)}); will recover on reconnect`, "warning");
     }
@@ -32975,12 +33090,12 @@ Warnings: ${warnings.join("; ")}`, {
             ...claimedRoleTopic === undefined ? [] : [claimedRoleTopic]
           ]).filter((topic) => topic !== inbox);
           const removed = targets.filter((topic) => closeIntentionally(topic) || topic === claimedRoleTopic);
-          if (claimedRoleTopic !== undefined && removed.includes(claimedRoleTopic)) {
-            claimedRoleTopic = undefined;
-          }
+          const releasingRole = claimedRoleTopic !== undefined && removed.includes(claimedRoleTopic);
           const registrationError = removed.length === 0 ? undefined : await client.unsubscribe({ sessionID, topics: removed }).then(registerSession).then(() => {
             return;
           }, messageFor);
+          if (releasingRole && registrationError === undefined)
+            releaseClaimedRole();
           return toolSuccess(`Unsubscribed: ${removed.join(", ") || "(none)"}`, {
             removed,
             ...registrationError === undefined ? {} : { registrationError }

package/dist/skills/envoy/SKILL.md

@@ -123,6 +123,21 @@ Publish to a role; do not subscribe as its holder. A successful `envoy_publish`
 its live `holder`; an unheld role returns an error. Use `envoy_role_get(role="reviewer")` to find
 the live holder first when you need one.
 
+A claim belongs to the session, not the process. `omp --resume` re-claims the role recorded in
+the session transcript, including after the listener's stale-interest reaper has removed the old
+row. A `/fork`, `/branch`, `/handoff`, or other transcript-carrying switch checks the
+previous id and moves any held role to the new id while establishing the new session. A `/new`
+or `/resume` switch installs an unrelated transcript and carries nothing. A process that dies and
+is never resumed does not stay a live holder; once liveness expires, role publishes return
+`no holder` until that transcript resumes or another session claims the role.
+
+Automatic reclaim never steals. It is a *soft* claim, which the listener grants only when the role
+is unheld, held by a session that is no longer live, or held by the id this session continues (a
+fork's parent). If a different live session holds it — the parent of a `/fork` whose role moved to
+the child, or a second process on the same transcript — the listener refuses atomically and the
+resumed session logs a warning and holds nothing. Only an explicit `envoy_role_set` is
+last-claim-wins. Re-running `envoy_role_set` for a role this session already holds is harmless.
+
 ## Legion role claims
 
 Legion agents receive through a daemon-minted role token. Claim the assigned role with

package/package.json

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