@sjawhar/pi-envoy 10.6.2 → 10.7.0

package/README.md

@@ -12,7 +12,8 @@ described in `packages/pi-shared/AGENTS.md`.
 Normal topic subscriptions are direct NATS subscriptions owned by this extension. A role claim is
 different: the listener arbitrates the core-NATS role lane for the current live holder, then sends
 a receipt-backed request with the original role topic to the holder's direct agent subject.
-`envoy_unsubscribe` manages only normal topic subscriptions; it does not relinquish a held role.
+`envoy_unsubscribe` manages only normal topic subscriptions; it does not relinquish a held role,
+and it keeps open, listing them as kept, the subscriptions another plugin holds for that role.
 The agent pump replies after accepting the envelope; without a receipt within two seconds the
 listener emits a `delivery_failed` exception. Role messages are live only; they are not retained
 for a later claimant.

package/dist/envoy.js

@@ -34054,7 +34054,7 @@ var envoyToolSpecs = [
   },
   {
     name: "envoy_unsubscribe",
-    description: "Unsubscribe this session from Envoy topics, or remove all current subscriptions if topics are omitted.",
+    description: "Unsubscribe this session from Envoy topics, or remove all current subscriptions if topics are omitted. A subscription another plugin holds for this session's role stays, and the result lists it as kept.",
     arguments: (schema) => ({ topics: schema.array(schema.string()).optional() }),
     operation: EnvoyToolOperation.unsubscribe
   },
@@ -34087,7 +34087,7 @@ var envoyToolSpecs = [
   },
   {
     name: "envoy_role_set",
-    description: "Set the current session as the holder of a named role. Messages published to notifications.role.<role> route to this session.",
+    description: "Set the current session as the holder of a named role. Messages published to notifications.role.<role> route to this session. Moving to a different role is refused while another plugin holds subscriptions that last only as long as this session keeps its current role.",
     arguments: (schema) => ({ role: schema.string() }),
     operation: EnvoyToolOperation.setRole
   },
@@ -35266,6 +35266,19 @@ import("@oh-my-pi/pi-coding-agent/extensibility/extensions/send-user-input-handl
 var codec2 = import_nats2.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
 var DELIVERY_PICTURES_TIMEOUT_MS = 20000;
+function serialQueue() {
+  let tail = Promise.resolve();
+  return {
+    run(task) {
+      const next = tail.then(task);
+      tail = next.catch(() => {
+        return;
+      });
+      return next;
+    },
+    settled: () => tail
+  };
+}
 function timedDispatchClient(timeoutMs) {
   const config2 = activeDispatchSettings(sessionDispatchSettings(CONFIG_FILE, process.env, { cwd: process.cwd() }).dispatch);
   return config2 === null ? undefined : new DispatchClient(config2.url, config2.token, fetch, AbortSignal.timeout(timeoutMs));
@@ -35332,6 +35345,20 @@ function isLegionManagedEntry(entry) {
     return false;
   return "session_id" in entry.data && typeof entry.data.session_id === "string";
 }
+
+class SessionLeftError extends Error {
+}
+
+class RegistrationError extends Error {
+}
+
+class InboundError extends Error {
+  decided;
+  constructor(message, decided, options) {
+    super(message, options);
+    this.decided = decided;
+  }
+}
 function isRoleClaimEntry(entry) {
   if (typeof entry !== "object" || entry === null)
     return false;
@@ -35401,10 +35428,31 @@ function envoyExtension(pi) {
   let sessionID = "";
   let recordedSessionKey;
   let heartbeatRegistered = false;
+  let announced;
+  let runUnderAnnouncement;
+  const continues = new Map;
+  const continuedBy = (id) => {
+    const lineage = [id];
+    for (let at = continues.get(id);at !== undefined && !lineage.includes(at); ) {
+      lineage.push(at);
+      at = continues.get(at);
+    }
+    return lineage;
+  };
+  let establishedSession = "";
+  const notifiedSessions = new Set;
   let claimedRoleTopic;
   let claimedRoleSessionID;
+  let holdUnconfirmed = false;
+  const pendingHandBacks = new Map;
+  const abandonedHolds = new Map;
+  const refusedRoles = new Map;
+  let roleNoticesFor;
   const roleNoticeSubjects = new Set;
   let roleEnds = 0;
+  const roleMoves = serialQueue();
+  const isRoleBound = (subject2) => roleNoticeSubjects.has(subject2);
+  const heldRole = () => claimedRoleTopic?.slice(ROLE_TOPIC_PREFIX.length);
   let activeSessionContext;
   const inbox = [];
   let askAwareness = {
@@ -35741,9 +35789,25 @@ function envoyExtension(pi) {
     subscriptions.delete(topic);
     return true;
   };
+  const lineageOf = (id) => {
+    const lineage = continuedBy(id);
+    return announced !== undefined && announced.from !== id && carriesSession(announced.reason) && !lineage.includes(announced.from) ? [...lineage, announced.from] : lineage;
+  };
+  const replacedSessionTopic = (topic) => {
+    if (!topic.startsWith(agentSubject("")))
+      return false;
+    const host3 = hostSessionID();
+    return host3 !== "" && !lineageOf(host3).some((id) => topic === agentSubject(id));
+  };
   const pump = async (topic, subscription) => {
     try {
       for await (const message of subscription) {
+        if (replacedSessionTopic(topic)) {
+          logger3.warn("envoy: frame for a session a switch replaced left undelivered", {
+            subject: message.subject
+          });
+          continue;
+        }
         try {
           await deliver(message.subject, codec2.decode(message.data), message.reply ?? "");
         } catch {}
@@ -35913,12 +35977,27 @@ function envoyExtension(pi) {
       closeIntentionally(subject2);
     roleNoticeSubjects.clear();
   };
-  const endOutgoingRole = () => {
-    if (claimedRoleSessionID !== sessionID)
-      endRole();
+  const handBackRole = async () => {
+    const role = heldRole();
+    const holdID = claimedRoleSessionID;
+    const topic = claimedRoleTopic;
+    if (role === undefined || topic === undefined)
+      return;
+    const pluginHeld = roleNoticeSubjects.size > 0;
+    endRole();
+    if (holdID !== undefined && holdID !== "") {
+      await requireEnvoy().client.unsubscribe({ sessionID: holdID, topics: [topic] }).catch((error48) => logger3.warn("envoy: a role this process gave up was not handed back", {
+        role,
+        sessionID: holdID,
+        error: messageFor(error48)
+      }));
+    }
+    return { role, pluginHeld };
   };
+  const hostSessionID = () => activeSessionContext?.sessionManager.getSessionId() ?? sessionID;
+  const sessionOpen = (id) => sessionID === id && hostSessionID() === id;
   const roleSnapshot = (topic) => ({
-    roleBound: expandSubscriptionTopics([topic]).some((subject2) => roleNoticeSubjects.has(subject2)),
+    roleBound: expandSubscriptionTopics([topic]).some(isRoleBound),
     endsBefore: roleEnds
   });
   const subscribeUnlessRoleEnds = async (topic, snapshot) => {
@@ -35932,54 +36011,58 @@ function envoyExtension(pi) {
       closeIntentionally(subject2);
     return false;
   };
-  const registerSession = () => requireEnvoy().client.subscribe({
-    sessionID,
-    directory: sessionDirectory2,
-    topics: [
-      ...new Set([
-        agentSubject(sessionID),
-        ...[...subscriptions.keys()].filter((subject2) => !roleNoticeSubjects.has(subject2))
-      ])
-    ],
-    port: 0,
-    title: activeSessionContext?.sessionManager.getSessionName?.() ?? "",
-    capabilities: sideTurn(activeSessionContext) === undefined ? CAPABILITIES_WITHOUT_BTW : DELIVERY_CAPABILITIES,
-    driving: false,
-    selfSubscribed: true
-  });
-  const reassertRole = async (afterOutage, context) => {
-    const topic = claimedRoleTopic;
-    if (topic === undefined)
-      return;
-    const id = sessionID;
-    const role = topic.slice(ROLE_TOPIC_PREFIX.length);
+  const registerSession = () => {
+    for (const [topic, hold] of abandonedHolds) {
+      if (hold.id !== sessionID)
+        continue;
+      abandonedHolds.delete(topic);
+      pendingHandBacks.set(`${topic}@${sessionID}`, { topic, id: sessionID });
+    }
+    return requireEnvoy().client.subscribe({
+      sessionID,
+      directory: sessionDirectory2,
+      topics: [
+        ...new Set([
+          agentSubject(sessionID),
+          ...[...subscriptions.keys()].filter((subject2) => !isRoleBound(subject2))
+        ])
+      ],
+      port: 0,
+      title: activeSessionContext?.sessionManager.getSessionName?.() ?? "",
+      capabilities: sideTurn(activeSessionContext) === undefined ? CAPABILITIES_WITHOUT_BTW : DELIVERY_CAPABILITIES,
+      driving: false,
+      selfSubscribed: true
+    });
+  };
+  const reassertRoleNow = async (id, role, afterOutage, context) => {
+    const topic = ROLE_TOPIC_PREFIX + role;
     const { client } = requireEnvoy();
     const holder = await client.getRole(role).then((info) => info.holder, (error48) => {
       if (error48 instanceof EnvoyApiError && error48.details.status === 404)
         return;
       throw error48;
     });
+    if (claimedRoleTopic !== topic || !sessionOpen(id))
+      return false;
     let reason;
     if (holder === id) {
       if (!afterOutage)
-        return;
+        return true;
       reason = "reregistered";
     } else {
       const result = await client.setRole({ sessionID: id, role, soft: true });
-      if (claimedRoleTopic !== topic || sessionID !== id) {
-        if (result.claimed)
-          await client.unsubscribe({ sessionID: id, topics: [topic] });
-        return;
-      }
+      if (claimedRoleTopic !== topic || !sessionOpen(id))
+        return false;
       if (!result.claimed) {
         endRole();
+        refusedRoles.set(id, role);
         logger3.warn("envoy: role re-assertion refused; held by another live session", {
           role,
           sessionID: id,
           holder: result.holder
         });
         context.ui.notify(`envoy: role ${role} is now held by session ${result.holder}; this session no longer holds it`, "warning");
-        return;
+        return true;
       }
       logger3.warn("envoy: role re-asserted after the listener lost the claim", {
         role,
@@ -35990,10 +36073,11 @@ function envoyExtension(pi) {
     }
     const regained = legionRoleClaimBridge().regained;
     if (regained === undefined)
-      return;
+      return true;
     Promise.resolve().then(() => regained(role, reason)).catch((error48) => {
       logger3.warn("envoy: role regain hook failed", { role, reason, error: messageFor(error48) });
     });
+    return true;
   };
   const ensureHeartbeat = (context) => {
     if (heartbeatRegistered)
@@ -36002,24 +36086,23 @@ function envoyExtension(pi) {
     let registrationFailed = false;
     let healing = false;
     context.setInterval(() => {
-      const liveSessionID = context.sessionManager.getSessionId();
-      if (liveSessionID === "")
+      if (context.sessionManager.getSessionId() === "")
         return;
-      const drifted = liveSessionID !== sessionID;
       if (healing)
         return;
       healing = true;
-      if (drifted) {
-        bindDispatchSession(liveSessionID);
-        procmgr.refreshShellConfigCache();
-      }
       const afterOutage = registrationFailed;
-      (drifted ? establishSession(context) : registerSession()).then(() => drifted ? undefined : reassertRole(afterOutage, context), (error48) => {
-        registrationFailed = true;
-        throw error48;
-      }).then(() => {
-        registrationFailed = false;
+      const settled = (decided) => {
+        if (decided)
+          registrationFailed = false;
         heartbeatOutageNotified = false;
+      };
+      reconcile(context, { heartbeat: true, afterOutage }).then(settled, (error48) => {
+        if (error48 instanceof InboundError)
+          return settled(error48.decided);
+        if (error48 instanceof RegistrationError)
+          registrationFailed = true;
+        throw error48 instanceof RegistrationError ? error48.cause : error48;
       }).catch((error48) => {
         if (heartbeatOutageNotified)
           return;
@@ -36056,34 +36139,75 @@ function envoyExtension(pi) {
       await subscribe(topic);
     }
   };
-  const setEnvoyRole = async (role, options = {}) => {
+  const observeAbandonedHold = async (topic, role, holder) => {
+    const abandoned = abandonedHolds.get(topic);
+    if (abandoned === undefined || abandoned.id !== holder)
+      return false;
+    const seen = await requireEnvoy().client.getRole(role).then((info) => info.holder === holder ? info.last_seen : undefined, () => {
+      return;
+    });
+    if (seen === undefined)
+      return true;
+    if (abandoned.lastSeen !== undefined && seen !== abandoned.lastSeen) {
+      abandonedHolds.delete(topic);
+      return false;
+    }
+    abandonedHolds.set(topic, { id: abandoned.id, lastSeen: seen });
+    return true;
+  };
+  const setEnvoyRole = async (role, forSession, options = {}) => {
+    if (!sessionOpen(forSession)) {
+      throw new SessionLeftError(`the session moved from ${forSession} to ${hostSessionID()} before its claim of role ${role} ran; nothing was claimed`);
+    }
     const topic = ROLE_TOPIC_PREFIX + role;
     const previousTopic = claimedRoleTopic;
+    const previousHoldID = claimedRoleSessionID;
+    const id = forSession;
     const { client } = requireEnvoy();
     const result = await client.setRole({
-      sessionID,
+      sessionID: id,
       role,
       soft: options.soft,
       previousSessionID: options.previousSessionID
     });
+    if (result.claimed) {
+      refusedRoles.delete(id);
+      holdUnconfirmed = false;
+      abandonedHolds.delete(topic);
+      for (const [key, hold] of pendingHandBacks) {
+        if (hold.topic === topic)
+          pendingHandBacks.delete(key);
+      }
+    }
+    if (!sessionOpen(id)) {
+      if (result.claimed) {
+        if (previousTopic !== undefined && previousTopic !== topic)
+          endRole();
+        claimedRoleTopic = topic;
+        claimedRoleSessionID = id;
+        if (previousTopic !== undefined && previousTopic !== topic && previousHoldID) {
+          await client.unsubscribe({ sessionID: previousHoldID, topics: [previousTopic] });
+        }
+      }
+      throw new SessionLeftError(`the session moved from ${id} to ${hostSessionID()} while its claim of role ${role} was in flight; ${result.claimed ? "the next pass keeps the hold for the session the host is on, or hands it back" : "nothing was claimed"}`);
+    }
     if (!result.claimed) {
-      logger3.warn("envoy: role held by another live session; not reclaimed", {
-        role,
-        sessionID,
-        holder: result.holder
-      });
       endRole();
+      const waitingOnReap = await observeAbandonedHold(topic, role, result.holder);
+      if (!waitingOnReap)
+        refusedRoles.set(id, role);
+      logger3.warn(waitingOnReap ? "envoy: role still held by a session this process left; claiming again once the listener reaps it" : "envoy: role held by another live session; not reclaimed", { role, sessionID: id, holder: result.holder });
       return false;
     }
     if (previousTopic !== undefined && previousTopic !== topic)
       endRole();
     claimedRoleTopic = topic;
-    claimedRoleSessionID = sessionID;
+    claimedRoleSessionID = id;
     pi.appendEntry(ROLE_CLAIM_ENTRY, { role });
     if (activeSessionContext !== undefined)
       ensureHeartbeat(activeSessionContext);
-    if (previousTopic !== undefined && previousTopic !== topic) {
-      await client.unsubscribe({ sessionID, topics: [previousTopic] });
+    if (previousTopic !== undefined && previousTopic !== topic && previousHoldID) {
+      await client.unsubscribe({ sessionID: previousHoldID, topics: [previousTopic] });
     }
     return true;
   };
@@ -36096,73 +36220,271 @@ function envoyExtension(pi) {
     }
     return role;
   };
-  const roleSources = (previousSessionID, carryPreviousSessionRole) => previousSessionID === "" || previousSessionID === sessionID || !carryPreviousSessionRole ? [sessionID] : [sessionID, previousSessionID];
-  const reclaimHeldRoles = async (previousSessionID, branch, carryPreviousSessionRole) => {
-    if (!carryPreviousSessionRole)
-      endOutgoingRole();
-    const remembered = transcriptClaimedRole(branch);
-    if (remembered === null) {
-      endRole();
+  const desiredRole = async (id, branch, readRows) => {
+    const want = (role) => refusedRoles.get(id) === role ? undefined : role;
+    const recorded = transcriptClaimedRole(branch);
+    if (recorded === null)
       return;
+    if (recorded !== undefined)
+      return want(recorded);
+    const held = heldRole();
+    const holdID = claimedRoleSessionID;
+    const lineage = continuedBy(id);
+    if (held !== undefined && holdID !== undefined && lineage.includes(holdID))
+      return want(held);
+    if (!readRows)
+      return;
+    const { client } = requireEnvoy();
+    for (const source of lineage) {
+      const registry2 = await client.getInterest(source).catch(() => {
+        return;
+      });
+      const topic = registry2?.topics.find((candidate) => candidate.startsWith(ROLE_TOPIC_PREFIX));
+      if (topic !== undefined)
+        return want(topic.slice(ROLE_TOPIC_PREFIX.length));
     }
-    let role = remembered ?? claimedRoleTopic?.slice(ROLE_TOPIC_PREFIX.length);
-    if (role === undefined) {
-      const { client } = requireEnvoy();
-      for (const source of roleSources(previousSessionID, carryPreviousSessionRole)) {
-        const registry2 = await client.getInterest(source).catch(() => {
-          return;
-        });
-        const topic = registry2?.topics.find((candidate) => candidate.startsWith(ROLE_TOPIC_PREFIX));
-        if (topic !== undefined) {
-          role = topic.slice(ROLE_TOPIC_PREFIX.length);
-          break;
+    return;
+  };
+  const endUnwantedRoleNow = (context) => {
+    const host3 = context.sessionManager.getSessionId();
+    const held = heldRole();
+    const topic = claimedRoleTopic;
+    const holdID = claimedRoleSessionID;
+    if (held === undefined || topic === undefined || holdID === undefined)
+      return;
+    const recorded = transcriptClaimedRole(context.sessionManager.getBranch?.() ?? []);
+    const wanted = recorded === undefined ? continuedBy(host3).includes(holdID) : recorded === held;
+    if (wanted)
+      return;
+    endRole();
+    if (holdID !== "")
+      pendingHandBacks.set(`${topic}@${holdID}`, { topic, id: holdID });
+  };
+  const tellIdChanged = (current) => {
+    const previous = continues.get(current);
+    if (previous === undefined || previous === current || notifiedSessions.has(current))
+      return;
+    notifiedSessions.add(current);
+    pi.sendMessage({
+      customType: "envoy-message",
+      content: encode3({
+        envoy: {
+          notice: "session id changed",
+          previous_session_id: previous,
+          session_id: current,
+          detail: "This conversation now lives under a new session id. Any identity you shared earlier (envoy_whoami output, session ids named in messages) is stale, and peers using the old id cannot reach you. Re-run envoy_whoami before identifying yourself and re-announce the new id to peers you already introduced yourself to."
         }
+      }),
+      display: true,
+      details: LOCAL_ENVOY_NOTICE
+    }, { deliverAs: "steer", triggerTurn: false });
+  };
+  const noteMove = (host3, reason) => {
+    if (host3 === "")
+      return;
+    if (announced !== undefined && host3 === announced.from) {
+      if (reason !== undefined)
+        announced = undefined;
+      return;
+    }
+    const from = announced?.from ?? sessionID;
+    const told = announced !== undefined || reason !== undefined;
+    const kind = announced !== undefined ? announced.reason : reason?.kind;
+    announced = undefined;
+    if (from !== "" && from !== host3) {
+      if (told) {
+        if (carriesSession(kind))
+          continues.set(host3, from);
+        else
+          continues.delete(host3);
+      } else if (!knownSessions.has(host3)) {
+        continues.set(host3, from);
+      }
+      knownSessions.add(from);
+    }
+    knownSessions.add(host3);
+  };
+  const knownSessions = new Set;
+  const passes = serialQueue();
+  const reconcile = (context, cause = {}) => passes.run(() => reconcileNow(context, cause));
+  const agentSessions = new Set;
+  let inboundOpenFor = "";
+  const reconcileNow = async (context, cause) => {
+    const host3 = context.sessionManager.getSessionId();
+    noteMove(host3);
+    if (sessionID !== host3)
+      restoreLocalSessionState(context);
+    if (establishedSession !== host3) {
+      if ((process.env.DISPATCH_SESSION_ID ?? "") !== host3) {
+        bindDispatchSession(host3);
+        procmgr.refreshShellConfigCache();
       }
+      tellIdChanged(host3);
+      if (host3 !== lastHeard)
+        lastHeard = "";
+    }
+    for (const other of agentSessions) {
+      if (other === host3)
+        continue;
+      closeIntentionally(agentSubject(other));
+      agentSessions.delete(other);
+      if (inboundOpenFor === other)
+        inboundOpenFor = "";
     }
-    if (role === undefined)
+    if (host3 === "") {
+      establishedSession = host3;
+      ensureHeartbeat(context);
+      return true;
+    }
+    let inboundFailure;
+    if (inbound && inboundOpenFor !== host3) {
+      try {
+        agentSessions.add(host3);
+        await ensureConnection();
+        await subscribe(agentSubject(host3));
+        await watchAgentStream(host3);
+        if ((context.sessionManager.getBranch?.() ?? []).length > 0) {
+          await recoverRegisteredInterests();
+        }
+        inboundOpenFor = host3;
+      } catch (error48) {
+        inboundFailure = error48;
+      }
+    }
+    if (hostSessionID() !== host3)
+      return false;
+    const registration = await registerSession().then(() => {
       return;
-    const continued = carryPreviousSessionRole && previousSessionID !== "" && previousSessionID !== sessionID ? previousSessionID : undefined;
-    await setEnvoyRole(role, { soft: true, previousSessionID: continued }).catch((error48) => {
-      logger3.warn("envoy: role reclaim failed", { role, sessionID, error: messageFor(error48) });
-    });
+    }, (error48) => ({ error: error48 }));
+    if (registration === undefined) {
+      establishedSession = host3;
+      ensureHeartbeat(context);
+    }
+    const decided = await roleMoves.run(() => settleRole(context, host3, cause, registration === undefined));
+    if (registration !== undefined) {
+      throw new RegistrationError(messageFor(registration.error), { cause: registration.error });
+    }
+    if (inboundFailure !== undefined) {
+      throw new InboundError(messageFor(inboundFailure), decided, { cause: inboundFailure });
+    }
+    return decided;
+  };
+  let roleSettledFor = "";
+  let lastHeard = "";
+  const settleEndedHolds = async (host3, wanted) => {
+    let restored = false;
+    const failed = [];
+    for (const [key, hold] of pendingHandBacks) {
+      pendingHandBacks.delete(key);
+      if (wanted !== undefined && hold.topic === ROLE_TOPIC_PREFIX + wanted) {
+        claimedRoleTopic = hold.topic;
+        claimedRoleSessionID = hold.id;
+        holdUnconfirmed = true;
+        restored = true;
+        continue;
+      }
+      await requireEnvoy().client.unsubscribe({ sessionID: hold.id, topics: [hold.topic] }).catch((error48) => {
+        failed.push({ key, ...hold });
+        logger3.warn("envoy: a role this process gave up was not handed back", {
+          topic: hold.topic,
+          sessionID: hold.id,
+          error: messageFor(error48)
+        });
+      });
+    }
+    for (const { key, topic, id } of failed) {
+      if (id === host3)
+        pendingHandBacks.set(key, { topic, id });
+      else
+        abandonedHolds.set(topic, { id });
+    }
+    return restored;
   };
-  let sessionEstablishment = Promise.resolve();
-  const establishSessionNow = async (context, options = {}, previousSessionID = sessionID) => {
-    const previousTopic = previousSessionID === "" ? undefined : agentSubject(previousSessionID);
-    if (options.carryPreviousSessionRole === false)
-      endOutgoingRole();
-    restoreLocalSessionState(context);
+  const settleRole = async (context, host3, cause, registered) => {
+    if (!sessionOpen(host3))
+      return false;
     const branch = context.sessionManager.getBranch?.() ?? [];
-    const resumed = branch.length > 0;
-    if (sessionID === "") {
-      if (previousTopic !== undefined)
-        closeIntentionally(previousTopic);
-      ensureHeartbeat(context);
-      return;
+    const readRows = roleSettledFor !== host3 && (branch.length > 0 || roleSettledFor !== "");
+    const desired = await desiredRole(host3, branch, readRows);
+    if (!sessionOpen(host3))
+      return false;
+    const unheard = lastHeard !== host3;
+    const held = heldRole();
+    if (held !== undefined && held !== desired) {
+      const ended = await handBackRole();
+      if (ended !== undefined && unheard)
+        warnRoleEnded(context, host3, ended);
+      if (!sessionOpen(host3))
+        return false;
     }
-    const currentTopic = agentSubject(sessionID);
-    if (previousTopic !== undefined && previousTopic !== currentTopic) {
-      closeIntentionally(previousTopic);
+    if (await settleEndedHolds(host3, desired) && unheard && desired !== undefined) {
+      warnNoticesClosed(context, desired);
     }
-    await ensureConnection();
-    await subscribe(currentTopic);
-    await watchAgentStream(sessionID);
-    if (resumed) {
-      await recoverRegisteredInterests();
+    if (!sessionOpen(host3))
+      return false;
+    if (!registered)
+      return false;
+    if (desired === undefined) {
+      roleSettledFor = host3;
+      return true;
     }
-    await registerSession();
-    if (resumed || previousSessionID !== "") {
-      await reclaimHeldRoles(previousSessionID, branch, options.carryPreviousSessionRole ?? true);
+    if (!holdUnconfirmed && heldRole() === desired && claimedRoleSessionID === host3) {
+      roleSettledFor = host3;
+      return cause.heartbeat === true ? reassertRoleNow(host3, desired, cause.afterOutage === true, context) : true;
     }
-    ensureHeartbeat(context);
+    if (!inbound) {
+      roleSettledFor = host3;
+      return true;
+    }
+    let supersedes = heldRole() === desired && claimedRoleSessionID !== undefined && claimedRoleSessionID !== "" ? claimedRoleSessionID : undefined;
+    const lineage = continuedBy(host3);
+    if (supersedes === undefined && lineage.length > 1) {
+      const holder = await requireEnvoy().client.getRole(desired).then((info) => info.holder, () => {
+        return;
+      });
+      if (holder !== undefined && holder !== host3 && lineage.includes(holder))
+        supersedes = holder;
+      if (!sessionOpen(host3))
+        return false;
+    }
+    try {
+      const claimed = await setEnvoyRole(desired, host3, {
+        soft: true,
+        previousSessionID: supersedes
+      });
+      if (claimed && unheard)
+        warnNoticesClosed(context, desired);
+    } catch (error48) {
+      if (error48 instanceof SessionLeftError)
+        return false;
+      logger3.warn("envoy: role reclaim failed", {
+        role: desired,
+        sessionID: host3,
+        error: messageFor(error48)
+      });
+    }
+    roleSettledFor = host3;
+    return true;
   };
-  const establishSession = (context, options = {}, previousSessionID = sessionID) => {
-    const run = sessionEstablishment.then(() => establishSessionNow(context, options, previousSessionID), () => establishSessionNow(context, options, previousSessionID));
-    sessionEstablishment = run.catch(() => {
-      return;
+  const warnRoleEnded = (context, host3, ended) => {
+    logger3.warn("envoy: role ended after a move with no session event", {
+      role: ended.role,
+      sessionID: host3
     });
-    return run;
+    context.ui.notify(ended.pluginHeld ? `envoy: role ${ended.role} ended: the host moved to session ${host3} with no session event, and that session's records do not name it; the plugin that opened its notices claims it again on its next session switch or restart` : `envoy: role ${ended.role} ended: the host moved to session ${host3} with no session event, and that session's records do not name it; if this session should hold it, run envoy_role_set`, "warning");
   };
+  const warnNoticesClosed = (context, role) => {
+    if (roleNoticesFor !== role || roleNoticeSubjects.size > 0)
+      return;
+    roleNoticesFor = undefined;
+    context.ui.notify(`envoy: role ${role} is held again, but the notices a plugin opened for it stay closed until that plugin claims it again on its next session switch or restart`, "warning");
+  };
+  const establishForBridge = (context) => reconcile(context).then(() => {
+    return;
+  }, (error48) => {
+    if (!(error48 instanceof InboundError))
+      throw error48;
+  });
   const claim = async (targetSessionID, role, callerContext) => {
     const context = callerContext ?? activeSessionContext;
     if (context === undefined || context.sessionManager.getSessionId() !== targetSessionID) {
@@ -36170,33 +36492,49 @@ function envoyExtension(pi) {
     }
     markLegionManagedSession(targetSessionID);
     requireInbound();
-    if (sessionID !== targetSessionID)
-      await establishSession(context);
+    if (establishedSession !== targetSessionID)
+      await establishForBridge(context);
     await registerSession();
-    await setEnvoyRole(role);
+    await roleMoves.run(() => setEnvoyRole(role, targetSessionID));
   };
   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);
+    if (establishedSession !== targetSessionID)
+      await establishForBridge(context);
+    const marked = [];
     if (whileHolding !== undefined) {
+      await roleMoves.settled();
       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]))
+      for (const subject2 of expandSubscriptionTopics([topic])) {
+        if (isRoleBound(subject2))
+          continue;
         roleNoticeSubjects.add(subject2);
+        marked.push(subject2);
+      }
+      roleNoticesFor = whileHolding;
+    }
+    const snapshot = roleSnapshot(topic);
+    try {
+      if (!await subscribeUnlessRoleEnds(topic, snapshot))
+        return;
+    } catch (error48) {
+      if (roleEnds === snapshot.endsBefore) {
+        for (const subject2 of marked)
+          roleNoticeSubjects.delete(subject2);
+      }
+      throw error48;
     }
-    if (!await subscribeUnlessRoleEnds(topic, roleSnapshot(topic)))
-      return;
     await registerSession();
   };
   const claimInstance = {
     claim,
     subscribe: subscribeNotice,
-    sessionID: () => activeSessionContext?.sessionManager.getSessionId() ?? sessionID
+    sessionID: hostSessionID
   };
   if (publishedInterface !== undefined)
     publishedInterface.roleClaim.instances.push(claimInstance);
@@ -36212,15 +36550,15 @@ function envoyExtension(pi) {
     if (await isSubagent(context))
       return;
     bindDispatchSession(context.sessionManager.getSessionId());
-    const previousSessionID = sessionID;
     restoreLocalSessionState(context);
+    lastHeard = context.sessionManager.getSessionId();
     if (startNotice2 !== "")
       context.ui.notify(`envoy: ${startNotice2}`, "warning");
     if (!inbound)
       return;
     let established = false;
     const establish = async () => {
-      await establishSession(context, {}, previousSessionID);
+      await reconcile(context);
       established = true;
     };
     try {
@@ -36240,36 +36578,24 @@ function envoyExtension(pi) {
       }, NATS_RETRY_INTERVAL_MS);
     }
   });
+  const carriesSession = (reason) => reason !== "new" && reason !== "resume";
   const rebind = async (reason, context) => {
     if (await isSubagent(context))
       return;
-    const previousID = sessionID;
-    restoreLocalSessionState(context);
+    const host3 = context.sessionManager.getSessionId();
+    noteMove(host3, { kind: reason });
+    lastHeard = host3;
+    refusedRoles.delete(host3);
+    if (sessionID !== host3)
+      restoreLocalSessionState(context);
+    endUnwantedRoleNow(context);
     if (!inbound)
       return;
     try {
-      const carryPreviousSessionRole = reason !== "new" && reason !== "resume";
-      await establishSession(context, { carryPreviousSessionRole }, previousID);
+      await reconcile(context);
     } catch (error48) {
       context.ui.notify(`envoy: rebind failed (${messageFor(error48)}); will recover on reconnect`, "warning");
     }
-    if (previousID === "" || previousID === sessionID)
-      return;
-    if (reason === "new" || reason === "resume")
-      return;
-    pi.sendMessage({
-      customType: "envoy-message",
-      content: encode3({
-        envoy: {
-          notice: "session id changed",
-          previous_session_id: previousID,
-          session_id: sessionID,
-          detail: "This conversation now lives under a new session id. Any identity you shared earlier (envoy_whoami output, session ids named in messages) is stale, and peers using the old id cannot reach you. Re-run envoy_whoami before identifying yourself and re-announce the new id to peers you already introduced yourself to."
-        }
-      }),
-      display: true,
-      details: LOCAL_ENVOY_NOTICE
-    }, { deliverAs: "steer", triggerTurn: false });
   };
   const rebindDispatch = async (reason, context) => {
     if (!await isSubagent(context))
@@ -36279,6 +36605,15 @@ function envoyExtension(pi) {
   pi.on("session_switch", (event, context) => rebindDispatch(event.reason, context));
   pi.on("session_branch", (_event, context) => rebindDispatch(undefined, context));
   pi.on("session_tree", (_event, context) => rebind(undefined, context));
+  const announce = (reason, context) => {
+    const from = context.sessionManager.getSessionId();
+    noteMove(from);
+    if (from === "" || sessionID === "")
+      return;
+    announced = { from, reason };
+  };
+  pi.on("session_before_switch", async (event, context) => announce(event.reason, context));
+  pi.on("session_before_branch", async (_event, context) => announce(undefined, context));
   pi.on("session_shutdown", async (_event, context) => {
     shuttingDown = true;
     if (publishedInterface !== undefined) {
@@ -36358,8 +36693,9 @@ function envoyExtension(pi) {
     }
     return;
   });
-  pi.on("agent_start", async () => {
+  pi.on("agent_start", async (_event, context) => {
     runSeq += 1;
+    runUnderAnnouncement = announced?.from === context.sessionManager.getSessionId() ? announced : undefined;
   });
   function armAskAwareness(id, asOf) {
     askAwareness = {
@@ -36374,6 +36710,12 @@ function envoyExtension(pi) {
     const id = context.sessionManager.getSessionId();
     endInjectedUserTurns(sessionID);
     const lastReply = event.messages?.findLast((message) => message.role === "assistant");
+    if (runUnderAnnouncement !== undefined && event.willContinue !== true) {
+      if (announced === runUnderAnnouncement && announced.from === id && lastReply !== undefined && lastReply.stopReason !== "aborted") {
+        announced = undefined;
+      }
+      runUnderAnnouncement = undefined;
+    }
     const ask = sideTurn(context);
     if (event.willContinue === true || lastReply?.stopReason !== "stop" || !context.hasUI || id === "" || ask === undefined || !checkOwed(id)) {
       return;
@@ -36526,14 +36868,18 @@ Warnings: ${warnings.join("; ")}`, {
         }
         case EnvoyToolOperation.unsubscribe: {
           const inbox2 = agentSubject(sessionID);
-          const targets = topicsFor(parameters, [...subscriptions.keys()]).filter((topic) => topic !== inbox2);
-          const removed = targets.filter(closeIntentionally);
+          const candidates = topicsFor(parameters, [...subscriptions.keys()]).filter((subject2) => subject2 !== inbox2);
+          const kept = candidates.filter(isRoleBound);
+          const removed = candidates.filter((subject2) => !isRoleBound(subject2)).filter(closeIntentionally);
           const registryRemoved = removed.filter((topic) => !topic.startsWith(ROLE_TOPIC_PREFIX));
           const registrationError = registryRemoved.length === 0 ? undefined : await client.unsubscribe({ sessionID, topics: registryRemoved }).then(registerSession).then(() => {
             return;
           }, messageFor);
-          return toolSuccess(`Unsubscribed: ${removed.join(", ") || "(none)"}`, {
+          const unsubscribed = `Unsubscribed: ${removed.join(", ") || "(none)"}`;
+          return toolSuccess(kept.length === 0 ? unsubscribed : `${unsubscribed}
+Kept (they last while this session holds role ${heldRole()}): ${kept.join(", ")}`, {
             removed,
+            ...kept.length === 0 ? {} : { kept },
             ...registrationError === undefined ? {} : { registrationError }
           });
         }
@@ -36582,8 +36928,16 @@ Not delivered: that holder is the session this subagent sends as, and the listen
         }
         case EnvoyToolOperation.setRole: {
           const role = stringFor(parameters, "role");
-          await setEnvoyRole(role);
-          return toolSuccess(`Now holding role: ${role}`, { role });
+          const released = await roleMoves.run(async () => {
+            const held = heldRole();
+            const moving = held !== undefined && held !== role;
+            if (moving && roleNoticeSubjects.size > 0) {
+              throw new Error(`This session holds role ${held}, and ${[...roleNoticeSubjects].join(", ")} lasts only while it does; envoy_role_set does not move it to ${role}`);
+            }
+            await setEnvoyRole(role, sessionID);
+            return moving ? held : undefined;
+          });
+          return toolSuccess(released === undefined ? `Now holding role: ${role}` : `Now holding role: ${role} (released role ${released})`, { role, ...released === undefined ? {} : { released } });
         }
         case EnvoyToolOperation.getRole: {
           const role = await client.getRole(stringFor(parameters, "role"));

package/dist/skills/envoy/SKILL.md

@@ -200,6 +200,9 @@ fork's parent). If a different live session holds it — the parent of a `/fork`
 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.
+Moving to a different role is refused while another plugin holds subscriptions that last only as
+long as this session keeps its current role (the refusal names them), and `envoy_unsubscribe`
+keeps those subscriptions open, listing them as kept.
 
 ## Legion role claims
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-envoy",
-  "version": "10.6.2",
+  "version": "10.7.0",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {