@sjawhar/pi-legion-envoy 0.16.0 → 0.17.0

package/dist/envoy.js

@@ -30785,147 +30785,37 @@ var ChildStatusPayloadSchema = object({
   from: string2().optional(),
   to: string2().optional()
 });
-function dispatchActorLabel(actor) {
-  return `${actor.kind} ${actor.id ?? "unknown"}`;
-}
-function dispatchBody(event) {
-  const lines = [];
-  switch (event.type) {
-    case "issue.created":
-    case "issue.updated":
-    case "issue.closed": {
-      const parsed = IssuePayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      if (parsed.data.title)
-        lines.push(`Title: ${parsed.data.title}`);
-      if (parsed.data.status)
-        lines.push(`Status: ${parsed.data.status}`);
-      if (parsed.data.route)
-        lines.push(`Route: ${parsed.data.route}`);
-      break;
-    }
-    case "artifact.created": {
-      const parsed = ArtifactCreatedPayloadSchema.safeParse(event.payload);
-      const name = parsed.success ? parsed.data.artifact?.name : undefined;
-      if (name)
-        lines.push(`Artifact: ${name}`);
-      break;
-    }
-    case "artifact.version": {
-      const parsed = ArtifactVersionPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      const version = parsed.data.version;
-      if (parsed.data.name)
-        lines.push(`Artifact: ${parsed.data.name}`);
-      if (version?.number !== undefined)
-        lines.push(`Version: ${version.number}`);
-      if (version?.summary)
-        lines.push(`Summary: ${version.summary}`);
-      if (parsed.data.diff)
-        lines.push("Diff:", parsed.data.diff);
-      break;
-    }
-    case "ask.opened":
-    case "ask.answered": {
-      const parsed = AskPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      if (parsed.data.question)
-        lines.push(`Question: ${parsed.data.question}`);
-      if (event.type === "ask.opened") {
-        const options = (parsed.data.options ?? []).map((option) => option.label).filter((label) => label !== undefined);
-        if (options.length > 0)
-          lines.push(`Options: ${options.join(", ")}`);
-        break;
-      }
-      const answer = parsed.data.answer;
-      lines.push(`Selected: ${answer?.selected?.join(", ") || "none"}`);
-      if (answer?.text)
-        lines.push(`Text: ${answer.text}`);
-      break;
-    }
-    case "comment.created":
-    case "comment.resolved": {
-      const parsed = CommentPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      const quote = parsed.data.anchor?.quote;
-      if (parsed.data.artifact_name)
-        lines.push(`Artifact: ${parsed.data.artifact_name}`);
-      if (quote)
-        lines.push(`> ${quote}`);
-      if (parsed.data.reply_to)
-        lines.push(`Reply chain: ${parsed.data.reply_to}`);
-      if (parsed.data.body)
-        lines.push(`Body: ${parsed.data.body}`);
-      break;
-    }
-    case "suggestion.accepted":
-    case "suggestion.rejected": {
-      const parsed = CommentPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      const quote = parsed.data.anchor?.quote;
-      const replacement = parsed.data.suggestion?.replace_with;
-      if (parsed.data.artifact_name)
-        lines.push(`Artifact: ${parsed.data.artifact_name}`);
-      if (quote)
-        lines.push(`> ${quote}`);
-      if (quote && replacement)
-        lines.push(`${quote} \u2192 ${replacement}`);
-      break;
-    }
-    case "message.created": {
-      const parsed = MessagePayloadSchema.safeParse(event.payload);
-      const body = parsed.success ? parsed.data.body : undefined;
-      if (body)
-        lines.push(`Body: ${body}`);
-      break;
-    }
-    case "child.status": {
-      const parsed = ChildStatusPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      const { child_key: child, from, to } = parsed.data;
-      if (child && from && to)
-        lines.push(`Child: ${child} ${from} \u2192 ${to}`);
-      break;
-    }
-  }
-  return lines;
-}
-function renderDispatch(envelope, sessionID) {
-  const invalid = () => ({
-    skip: false,
-    content: "dispatch: invalid event",
-    envelope
-  });
-  if (envelope.payload === undefined)
-    return invalid();
-  let rawEvent;
+var DISPATCH_PAYLOAD_SCHEMAS = {
+  "issue.created": IssuePayloadSchema,
+  "issue.updated": IssuePayloadSchema,
+  "issue.closed": IssuePayloadSchema,
+  "artifact.created": ArtifactCreatedPayloadSchema,
+  "artifact.version": ArtifactVersionPayloadSchema,
+  "ask.opened": AskPayloadSchema,
+  "ask.answered": AskPayloadSchema,
+  "comment.created": CommentPayloadSchema,
+  "comment.resolved": CommentPayloadSchema,
+  "suggestion.accepted": CommentPayloadSchema,
+  "suggestion.rejected": CommentPayloadSchema,
+  "message.created": MessagePayloadSchema,
+  "child.status": ChildStatusPayloadSchema
+};
+function dispatchPayload(event) {
+  const schema = DISPATCH_PAYLOAD_SCHEMAS[event.type];
+  if (schema === undefined)
+    return event.payload;
+  const parsed = schema.safeParse(event.payload);
+  return parsed.success ? parsed.data : event.payload;
+}
+function parseDispatchFrame(rawPayload) {
+  let value;
   try {
-    rawEvent = JSON.parse(envelope.payload);
+    value = JSON.parse(rawPayload);
   } catch {
-    return invalid();
-  }
-  const parsed = DispatchEventSchema.safeParse(rawEvent);
-  if (!parsed.success)
-    return invalid();
-  const event = parsed.data;
-  if (event.actor.kind === "session" && event.actor.id === sessionID) {
-    return { skip: true, content: "", envelope };
+    return { raw: rawPayload };
   }
-  return {
-    skip: false,
-    content: [
-      `dispatch ${event.issue_key} \xB7 ${event.type} \xB7 by ${dispatchActorLabel(event.actor)}`,
-      ...dispatchBody(event)
-    ].join(`
-`),
-    envelope
-  };
+  const parsed = DispatchEventSchema.safeParse(value);
+  return parsed.success ? { event: parsed.data } : { raw: value };
 }
 function inboundTimestamp(milliseconds) {
   if (milliseconds === undefined)
@@ -30961,13 +30851,31 @@ function renderInbound(raw, sessionID, subject) {
     const data = tolerant.data;
     envelope = { ...data, source: data.source ?? "unknown" };
   }
+  let dispatchEvent;
+  let dispatchIssue;
+  const dispatchRendered = envelope.source === "dispatch" && envelope.payload !== undefined;
   if (envelope.source === "dispatch") {
-    const renderedDispatch = renderDispatch(envelope, sessionID);
-    if (renderedDispatch !== null)
-      return renderedDispatch;
+    if (envelope.payload === undefined) {
+      dispatchIssue = "payload";
+    } else {
+      const frame = parseDispatchFrame(envelope.payload);
+      if ("event" in frame) {
+        if (frame.event.actor.kind === "session" && frame.event.actor.id === sessionID) {
+          return { skip: true, content: "", envelope };
+        }
+        dispatchEvent = {
+          issue_key: frame.event.issue_key,
+          type: frame.event.type,
+          actor: frame.event.actor,
+          payload: dispatchPayload(frame.event)
+        };
+      } else {
+        dispatchEvent = frame.raw;
+      }
+    }
   }
   let parsedPayload;
-  if (envelope.payload !== undefined && (envelope.source === "github" || envelope.payload !== envelope.payload_summary)) {
+  if (!dispatchRendered && envelope.payload !== undefined && (envelope.source === "github" || envelope.payload !== envelope.payload_summary)) {
     try {
       parsedPayload = JSON.parse(envelope.payload);
     } catch {
@@ -30975,7 +30883,7 @@ function renderInbound(raw, sessionID, subject) {
     }
   }
   const payloadSummary = envelope.payload_summary ?? "unknown";
-  const message = envelope.payload !== undefined && envelope.payload !== envelope.payload_summary ? parsedPayload : undefined;
+  const message = !dispatchRendered && envelope.payload !== undefined && envelope.payload !== envelope.payload_summary ? parsedPayload : undefined;
   const summaryIsHead = typeof message === "string" && envelope.payload_summary !== undefined && message.startsWith(envelope.payload_summary.endsWith("\u2026") ? envelope.payload_summary.slice(0, -1) : envelope.payload_summary);
   const body = `${envelope.payload_summary ?? ""}
 ${envelope.payload ?? ""}`;
@@ -30989,7 +30897,11 @@ ${envelope.payload ?? ""}`;
   const role = envelope.sender?.roles?.[0];
   const reply = replyWith(envelope);
   const sourceIssue = parseIssues.includes("source") || KNOWN_SOURCES[envelope.source] !== undefined ? undefined : `source=${envelope.source}`;
-  const unrecognised = [...parseIssues, ...sourceIssue === undefined ? [] : [sourceIssue]].join(", ") || undefined;
+  const unrecognised = [
+    ...parseIssues,
+    ...sourceIssue === undefined ? [] : [sourceIssue],
+    ...dispatchIssue === undefined ? [] : [dispatchIssue]
+  ].join(", ") || undefined;
   const rendered = {
     ...envelope.topic === agentSubject(sessionID) ? { to: `you (${sessionID.slice(0, 4)}\u2026)` } : {},
     from: senderLabel(envelope),
@@ -31004,8 +30916,10 @@ ${envelope.payload ?? ""}`;
     ...role === undefined ? {} : {
       reply_role: `envoy_publish(topic="notifications.role.${role}", message="...")`
     },
-    ...summaryIsHead ? {} : { summary: payloadSummary },
-    ...message === undefined ? {} : { message },
+    ...dispatchRendered ? { dispatch: dispatchEvent } : {
+      ...summaryIsHead ? {} : { summary: payloadSummary },
+      ...message === undefined ? {} : { message }
+    },
     ...foreignSession === undefined ? {} : {
       note: `body names session ${foreignSession}; the sender is ${envelope.source_session ?? "unknown"}`
     },
@@ -31935,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()
@@ -32067,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;
@@ -32163,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;
@@ -32360,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;
@@ -32377,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) => {
@@ -32402,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);
@@ -32445,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");
     }
@@ -32579,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

@@ -31282,147 +31282,37 @@ var ChildStatusPayloadSchema = object({
   from: string2().optional(),
   to: string2().optional()
 });
-function dispatchActorLabel(actor) {
-  return `${actor.kind} ${actor.id ?? "unknown"}`;
-}
-function dispatchBody(event) {
-  const lines = [];
-  switch (event.type) {
-    case "issue.created":
-    case "issue.updated":
-    case "issue.closed": {
-      const parsed = IssuePayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      if (parsed.data.title)
-        lines.push(`Title: ${parsed.data.title}`);
-      if (parsed.data.status)
-        lines.push(`Status: ${parsed.data.status}`);
-      if (parsed.data.route)
-        lines.push(`Route: ${parsed.data.route}`);
-      break;
-    }
-    case "artifact.created": {
-      const parsed = ArtifactCreatedPayloadSchema.safeParse(event.payload);
-      const name = parsed.success ? parsed.data.artifact?.name : undefined;
-      if (name)
-        lines.push(`Artifact: ${name}`);
-      break;
-    }
-    case "artifact.version": {
-      const parsed = ArtifactVersionPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      const version = parsed.data.version;
-      if (parsed.data.name)
-        lines.push(`Artifact: ${parsed.data.name}`);
-      if (version?.number !== undefined)
-        lines.push(`Version: ${version.number}`);
-      if (version?.summary)
-        lines.push(`Summary: ${version.summary}`);
-      if (parsed.data.diff)
-        lines.push("Diff:", parsed.data.diff);
-      break;
-    }
-    case "ask.opened":
-    case "ask.answered": {
-      const parsed = AskPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      if (parsed.data.question)
-        lines.push(`Question: ${parsed.data.question}`);
-      if (event.type === "ask.opened") {
-        const options = (parsed.data.options ?? []).map((option) => option.label).filter((label) => label !== undefined);
-        if (options.length > 0)
-          lines.push(`Options: ${options.join(", ")}`);
-        break;
-      }
-      const answer = parsed.data.answer;
-      lines.push(`Selected: ${answer?.selected?.join(", ") || "none"}`);
-      if (answer?.text)
-        lines.push(`Text: ${answer.text}`);
-      break;
-    }
-    case "comment.created":
-    case "comment.resolved": {
-      const parsed = CommentPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      const quote = parsed.data.anchor?.quote;
-      if (parsed.data.artifact_name)
-        lines.push(`Artifact: ${parsed.data.artifact_name}`);
-      if (quote)
-        lines.push(`> ${quote}`);
-      if (parsed.data.reply_to)
-        lines.push(`Reply chain: ${parsed.data.reply_to}`);
-      if (parsed.data.body)
-        lines.push(`Body: ${parsed.data.body}`);
-      break;
-    }
-    case "suggestion.accepted":
-    case "suggestion.rejected": {
-      const parsed = CommentPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      const quote = parsed.data.anchor?.quote;
-      const replacement = parsed.data.suggestion?.replace_with;
-      if (parsed.data.artifact_name)
-        lines.push(`Artifact: ${parsed.data.artifact_name}`);
-      if (quote)
-        lines.push(`> ${quote}`);
-      if (quote && replacement)
-        lines.push(`${quote} \u2192 ${replacement}`);
-      break;
-    }
-    case "message.created": {
-      const parsed = MessagePayloadSchema.safeParse(event.payload);
-      const body = parsed.success ? parsed.data.body : undefined;
-      if (body)
-        lines.push(`Body: ${body}`);
-      break;
-    }
-    case "child.status": {
-      const parsed = ChildStatusPayloadSchema.safeParse(event.payload);
-      if (!parsed.success)
-        break;
-      const { child_key: child, from, to } = parsed.data;
-      if (child && from && to)
-        lines.push(`Child: ${child} ${from} \u2192 ${to}`);
-      break;
-    }
-  }
-  return lines;
-}
-function renderDispatch(envelope, sessionID) {
-  const invalid = () => ({
-    skip: false,
-    content: "dispatch: invalid event",
-    envelope
-  });
-  if (envelope.payload === undefined)
-    return invalid();
-  let rawEvent;
+var DISPATCH_PAYLOAD_SCHEMAS = {
+  "issue.created": IssuePayloadSchema,
+  "issue.updated": IssuePayloadSchema,
+  "issue.closed": IssuePayloadSchema,
+  "artifact.created": ArtifactCreatedPayloadSchema,
+  "artifact.version": ArtifactVersionPayloadSchema,
+  "ask.opened": AskPayloadSchema,
+  "ask.answered": AskPayloadSchema,
+  "comment.created": CommentPayloadSchema,
+  "comment.resolved": CommentPayloadSchema,
+  "suggestion.accepted": CommentPayloadSchema,
+  "suggestion.rejected": CommentPayloadSchema,
+  "message.created": MessagePayloadSchema,
+  "child.status": ChildStatusPayloadSchema
+};
+function dispatchPayload(event) {
+  const schema = DISPATCH_PAYLOAD_SCHEMAS[event.type];
+  if (schema === undefined)
+    return event.payload;
+  const parsed = schema.safeParse(event.payload);
+  return parsed.success ? parsed.data : event.payload;
+}
+function parseDispatchFrame(rawPayload) {
+  let value;
   try {
-    rawEvent = JSON.parse(envelope.payload);
+    value = JSON.parse(rawPayload);
   } catch {
-    return invalid();
-  }
-  const parsed = DispatchEventSchema.safeParse(rawEvent);
-  if (!parsed.success)
-    return invalid();
-  const event = parsed.data;
-  if (event.actor.kind === "session" && event.actor.id === sessionID) {
-    return { skip: true, content: "", envelope };
+    return { raw: rawPayload };
   }
-  return {
-    skip: false,
-    content: [
-      `dispatch ${event.issue_key} \xB7 ${event.type} \xB7 by ${dispatchActorLabel(event.actor)}`,
-      ...dispatchBody(event)
-    ].join(`
-`),
-    envelope
-  };
+  const parsed = DispatchEventSchema.safeParse(value);
+  return parsed.success ? { event: parsed.data } : { raw: value };
 }
 function inboundTimestamp(milliseconds) {
   if (milliseconds === undefined)
@@ -31458,13 +31348,31 @@ function renderInbound(raw, sessionID, subject) {
     const data = tolerant.data;
     envelope = { ...data, source: data.source ?? "unknown" };
   }
+  let dispatchEvent;
+  let dispatchIssue;
+  const dispatchRendered = envelope.source === "dispatch" && envelope.payload !== undefined;
   if (envelope.source === "dispatch") {
-    const renderedDispatch = renderDispatch(envelope, sessionID);
-    if (renderedDispatch !== null)
-      return renderedDispatch;
+    if (envelope.payload === undefined) {
+      dispatchIssue = "payload";
+    } else {
+      const frame = parseDispatchFrame(envelope.payload);
+      if ("event" in frame) {
+        if (frame.event.actor.kind === "session" && frame.event.actor.id === sessionID) {
+          return { skip: true, content: "", envelope };
+        }
+        dispatchEvent = {
+          issue_key: frame.event.issue_key,
+          type: frame.event.type,
+          actor: frame.event.actor,
+          payload: dispatchPayload(frame.event)
+        };
+      } else {
+        dispatchEvent = frame.raw;
+      }
+    }
   }
   let parsedPayload;
-  if (envelope.payload !== undefined && (envelope.source === "github" || envelope.payload !== envelope.payload_summary)) {
+  if (!dispatchRendered && envelope.payload !== undefined && (envelope.source === "github" || envelope.payload !== envelope.payload_summary)) {
     try {
       parsedPayload = JSON.parse(envelope.payload);
     } catch {
@@ -31472,7 +31380,7 @@ function renderInbound(raw, sessionID, subject) {
     }
   }
   const payloadSummary = envelope.payload_summary ?? "unknown";
-  const message = envelope.payload !== undefined && envelope.payload !== envelope.payload_summary ? parsedPayload : undefined;
+  const message = !dispatchRendered && envelope.payload !== undefined && envelope.payload !== envelope.payload_summary ? parsedPayload : undefined;
   const summaryIsHead = typeof message === "string" && envelope.payload_summary !== undefined && message.startsWith(envelope.payload_summary.endsWith("\u2026") ? envelope.payload_summary.slice(0, -1) : envelope.payload_summary);
   const body = `${envelope.payload_summary ?? ""}
 ${envelope.payload ?? ""}`;
@@ -31486,7 +31394,11 @@ ${envelope.payload ?? ""}`;
   const role = envelope.sender?.roles?.[0];
   const reply = replyWith(envelope);
   const sourceIssue = parseIssues.includes("source") || KNOWN_SOURCES[envelope.source] !== undefined ? undefined : `source=${envelope.source}`;
-  const unrecognised = [...parseIssues, ...sourceIssue === undefined ? [] : [sourceIssue]].join(", ") || undefined;
+  const unrecognised = [
+    ...parseIssues,
+    ...sourceIssue === undefined ? [] : [sourceIssue],
+    ...dispatchIssue === undefined ? [] : [dispatchIssue]
+  ].join(", ") || undefined;
   const rendered = {
     ...envelope.topic === agentSubject(sessionID) ? { to: `you (${sessionID.slice(0, 4)}\u2026)` } : {},
     from: senderLabel(envelope),
@@ -31501,8 +31413,10 @@ ${envelope.payload ?? ""}`;
     ...role === undefined ? {} : {
       reply_role: `envoy_publish(topic="notifications.role.${role}", message="...")`
     },
-    ...summaryIsHead ? {} : { summary: payloadSummary },
-    ...message === undefined ? {} : { message },
+    ...dispatchRendered ? { dispatch: dispatchEvent } : {
+      ...summaryIsHead ? {} : { summary: payloadSummary },
+      ...message === undefined ? {} : { message }
+    },
     ...foreignSession === undefined ? {} : {
       note: `body names session ${foreignSession}; the sender is ${envelope.source_session ?? "unknown"}`
     },
@@ -32425,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()
@@ -32557,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;
@@ -32645,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;
@@ -32842,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;
@@ -32859,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) => {
@@ -32884,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);
@@ -32927,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");
     }
@@ -33061,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.0",
+  "version": "0.17.0",
   "type": "module",
   "omp": {
     "extensions": [