@sjawhar/claude-envoy 1.15.0 → 1.17.0

package/.claude-plugin/plugin.json

@@ -2,5 +2,5 @@
   "name": "claude-envoy",
   "description": "Deliver Envoy events as Claude Code channel notifications and expose Envoy MCP tools.",
   "mcpServers": "./.mcp.json",
-  "version": "1.15.0"
+  "version": "1.17.0"
 }

package/.omp-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-envoy",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Deliver Envoy events as Claude Code channel notifications and expose Envoy MCP tools.",
   "mcpServers": {}
 }

package/AGENTS.md

@@ -119,7 +119,7 @@ Dispatch asks stay on Dispatch.
 | Real Claude Code test | `tests/answers-claude.test.ts`, `/.claude-code-pin`, `/.github/actions/install-claude-code` | The `answers` hook on the real binary: Claude Code runs with this package as `--plugin-dir`, an isolated HOME and `CLAUDE_CONFIG_DIR`, and one stand-in as its Messages endpoint (`ANTHROPIC_BASE_URL`, server-sent events as the API streams them) and Dispatch (`DISPATCH_URL`); each case reads the list off the Messages request after the moment: startup (`claude -p --session-id`), `--resume <id>`, `/compact` sent in stream-json as `legion claude-bridge` sends turns, and a subagent (the stand-in answers with an `Agent` tool call, the API name of Claude Code's Task tool). `LEGION_TEST_CLAUDE` names the binary; the test skips without it, except on GitHub Actions, where the claude-envoy job installs the release `.claude-code-pin` pins (`bun add` into the runner's temp directory). A pin bump that changes a request shape is fixed in that file. |
 | Inbound channel server | `src/envoy-channel-server.ts`, `src/envoy-off.ts` | MCP capability, notification queue, NATS registration, session-id handoff, role persistence, rejected-frame replies, and the Envoy tools, on the envoy.json Claude Code's rule picks (`@legion/envoy-client/session-settings`); why a section is off, and that inbound messages are off, goes to stderr once as `envoy-channel: <notice>`. `runEnvoyChannelServer` chooses between that server and the two reduced modes of `src/envoy-off.ts`. With Envoy off it runs `serveEnvoyOff` instead: an MCP server that lists no tool, refuses every call with `Envoy is off for this session: <why>` (the section's notice or error), opens no NATS connection and calls no listener, and exits 0 when stdin ends or on SIGTERM, SIGINT or SIGHUP. With Envoy on and inbound messages off (`inbound.off`: no NATS server, from `envoy.natsUrls` or `ENVOY_NATS_URL`, or its seed refused), it serves the tools on `inboundOffChannelSession`: no NATS connection, nothing registered with the listener, an empty inbox, `envoy_subscribe` refused naming why, and a role `envoy_role_set` claims still persisted. |
 | Channel gate | `src/claude-channel.ts` | Whether Claude Code loaded this server as a channel, which it never tells the server: the command line of the nearest ancestor whose program is `claude` (`claudeCommandLine`; Claude Code may run the server through a shell prefix or a `bun` shim), read from `/proc` (exact, with its stdout's terminal and its directory) or `ps` (split on whitespace), against Claude Code's own gate as of 2.1.301: a `plugin:claude-envoy@…` entry when `CLAUDE_PLUGIN_ROOT` says it runs as a plugin, any `server:` entry from a bare config; `--channels` entries before development ones; `--dangerously-load-development-channels` only in an interactive session (`asksForPrintMode`, the arguments skipped as Claude Code's scanner skips them, and a terminal on stdout where `/proc` shows it); the marketplace it is loaded from (`loadedMarketplace`: `inline` for `--plugin-dir`, else the cache's, compared after Claude Code's cache-name sanitizing); for `--channels`, `allowedChannelPlugins` (object or `plugin@marketplace` entries, each invalid one dropped alone) from the managed source that owns it (`remote-settings.json`, else `managed-settings.json` with its non-dot drop-ins; under `managedSourcesBehavior: "merge"` the highest that sets it). Not loaded, the session registers `capabilities: []`. `ENVOY_CHANNEL_LOADED=1`/`0` overrides it. A command line it cannot read, or no `claude` ancestor, counts as loaded, and so does one Node overwrote with `process.title = "claude"` (on Linux, the title alone followed by NUL padding, whatever the executable's name; elsewhere one word from a program named `node…`). |
-| Session identity | `src/session-identity.ts`, `src/session-state.ts`, `src/claude-session.ts` | `SessionIdentity` is the one mutable id holder; handoff file `sessions/<claude-pid>/session-id`; role file `roles/<url-encoded session id>.json` (`readPersistedRole`, `writePersistedRole`; the suffix is what keeps a session id of `.` or `..` inside `roles/`, since `encodeURIComponent` leaves a dot alone). `CLAUDE_CODE_SESSION_ID`, or explicit `ENVOY_SESSION_ID` for QA. `src/session-state.ts` holds what the state files share and nothing that imports zod: `writeAtomicStateFile`, and `pruneStateDirectory(directory, isStale)`, the one ENOENT-tolerant sweep behind all three of them — handoffs by liveness (a `sessions/<pid>` whose Claude process is gone, anything else there left alone), titles and roles by age (`writtenLongAgo`, `STATE_FILE_MAX_AGE_MS`, thirty days). The role sweep exists because exactly one path removes a role file by hand — a soft `setRole` the listener refuses with a holder that is **not** the predecessor the claim named, which says that predecessor no longer holds the role. A refusal naming the predecessor itself keeps the file, since that record belongs to the live holder, which may be another process sharing this state directory. The handoff sweep cannot reach either, keyed as it is by session id with no process left to ask about. All three run at startup in `startChannelSession`, each under its own `.catch` that logs and swallows: the heartbeat timer is not armed yet, so housekeeping must never cost a session its channel. |
+| Session identity | `src/session-identity.ts`, `src/session-state.ts`, `src/claude-session.ts` | `SessionIdentity` is the one mutable id holder; handoff file `sessions/<claude-pid>/session-id`; role file `roles/<url-encoded session id>.json` (`readPersistedRole`, `writePersistedRole`; the suffix is what keeps a session id of `.` or `..` inside `roles/`, since `encodeURIComponent` leaves a dot alone), whose record carries the writing process's `client_instance_id` beside the session id and the role, optional so a record written before the field loads unchanged. `CLAUDE_CODE_SESSION_ID`, or explicit `ENVOY_SESSION_ID` for QA. `src/session-state.ts` holds what the state files share and nothing that imports zod: `writeAtomicStateFile`, and `pruneStateDirectory(directory, isStale)`, the one ENOENT-tolerant sweep behind all three of them — handoffs by liveness (a `sessions/<pid>` whose Claude process is gone, anything else there left alone), titles and roles by age (`writtenLongAgo`, `STATE_FILE_MAX_AGE_MS`, thirty days). The role sweep exists because exactly one path removes a role file by hand — a soft `setRole` the listener refuses naming a session that is **not** the one the record is for, which says that session no longer holds the role. A refusal naming the record's own session keeps the file: the role is then held under that id by another process sharing this state directory, and the refused process goes on pressing its claim, refreshing the record's mtime on each heartbeat as a confirmed holder does, so the age sweep never reaches a record a process is still claiming for. The handoff sweep cannot reach either, keyed as it is by session id with no process left to ask about. All three run at startup in `startChannelSession`, each under its own `.catch` that logs and swallows: the heartbeat timer is not armed yet, so housekeeping must never cost a session its channel. |
 | Session title | `src/session-title.ts`, `src/session-state.ts` | The title every registration sends, which Dispatch's Agents page shows in place of the id: `ENVOY_SESSION_TITLE` on one line when it holds a character that shows; else the name the person running the session gave it (`claude -n`, `--name`, `/rename`), alone, with no short id after it, since a name a person chose needs nothing to tell it apart; else a name and the current id's first eight characters (a function of the id, so it follows a `/clear` handoff, and keeps two sessions in one tmux window apart). The chosen name is read, through `readChosenTitleSync`, from the `titles/<url-encoded session id>.txt` file the hooks write under `CLAUDE_PLUGIN_DATA` (keyed by id, like the role file, so `claude --resume <id>` finds it and a `/clear`'s new id starts without one; the suffix keeps a session id of `.` or `..` inside `titles/`, since `encodeURIComponent` leaves a dot alone), and every writer and reader goes through `sessionTitleFile` so the file the hook writes is the file the server reads; that read is synchronous and swallows every error, because a cosmetic title must leave the session on its fallback rather than fail the registration carrying it, and the name goes through the same `oneLine`/`visible` pair the other sources do, so a blank or invisible one falls through to the fallback while a multi-line one is put on one line and kept. The fallback's name is the pane's tmux name (`TMUX` and `TMUX_PANE`, one bounded `tmux -u -S <socket> display-message` at startup, used only when the answering server's pid is the one in `TMUX` and the pane's process is one of this process's ancestors (`isAncestor`); `session:window` when the window's `automatic-rename` is off, else the session, never a window index; for grouped sessions the group's name), else the project directory's name (outside tmux, a refused or missing answer, or a session named only by digits in a window nobody named). That name is worked out once as the server starts; the chosen name is asked for on every call instead, so a rename reaches the page on the session's next prompt plus a heartbeat, with no watcher anywhere. `pruneStaleSessionTitles` drops title files untouched for thirty days at startup, through the sweep the handoff and role prunes share and under the same best-effort guard, since nothing else deletes a file keyed by a session id. The listener replaces the stored title on every registration, and `register` also stamps it (`stampTitle`: `writeSessionTitle` in the session's Dispatch state directory) once per id, where the `dispatch` command reads it for the `session_title` on its writes; with inbound messages or Envoy off, nothing registers, so `runEnvoyChannelServer` stamps it once for the starting id (a `/clear` there leaves the new id unstamped); nothing is stamped when the session starts with Dispatch off or under `ENVOY_SESSION_ID`. |
 | NATS topic consumer | `src/channel-forwarder.ts` | Dedupe through the shared `createDeliveryDedupe`: a re-send by its `dedupe_key` (never by `event_id` alone, which the listener mints fresh for every send, so a Dispatch Retry would pass as new), and a second copy of one publish arriving on overlapping subscriptions by its `event_id`; surface the envelope's topic, and drain safely at shutdown. The promise the dedupe keeps is stated on `DELIVERY_DUPLICATE_WINDOW_MS` in `packages/contracts`. |
 | Consumer delivery | `src/envoy-channel-server.ts` (`openRelay`, `deliverRelayed`, `renewRelayEpoch`, `relaysCoreTopic`), `src/replay-state.ts` (the `consumer` part of `replay-<session id>.json`), `../envoy-client/src/consumer-delivery.ts`, `../../scripts/e2e/envoy-session-delivery.sh` | The listener's relay of the session's durable consumer ("Overview"): the relay subscription and epoch, each frame's `received`, `done` and `nak`, and the persisted resume point. The repository's `scripts/e2e/envoy-session-delivery.sh` is the live proof under `legion claude-bridge` (`scripts/e2e/README.md`). |
@@ -285,17 +285,50 @@ above says how to run it).
   the last signal Claude Code gives there, and the bridge's inbox answer in a Legion pane, which
   comes once Claude Code re-emits the delivery (`--replay-user-messages`).
 - Preserve the held role at `${CLAUDE_PLUGIN_DATA}/roles/<session-id>.json` (keyed by session id so
-  `claude --resume <id>` finds it); soft-reclaim it with its `previous_session_id` after
-  registration, then reassert it on each registration heartbeat. The listener grants such a claim
-  only when that predecessor has no live registry entry, when its live entry carries this
+  `claude --resume <id>` finds it), with this process's client instance id in the record beside
+  the session id and the role, since two `claude` processes of one user read one state directory
+  and a record keyed by session id alone names no writer; soft-reclaim it with its
+  `previous_session_id` after registration, then reassert it on each registration heartbeat. A
+  record another process wrote is pressed only while this process holds no role, and a record
+  from a build before the writer was named is pressed as it always was. The listener grants such
+  a claim only when that predecessor has no live registry entry, when its live entry carries this
   process's own client instance id, or when either side carries no instance id. A predecessor
   still live under another client instance keeps the role, and the claim is refused naming it.
   That refusal keeps the predecessor's role file, because the record belongs to the live holder.
-  A refusal naming any other session removes the file. The handoff directory
-  `sessions/<claude-pid>/` is pruned at startup when its pid is gone — never deleted on shutdown,
-  because Claude Code restarts the server inside the same `claude` process — and the two
-  id-keyed directories, `roles/` and `titles/`, are pruned there too at thirty days, since a
-  session that ends while it still holds its role deletes neither file itself.
+  A claim of a role already held under this session's own id is decided on the standing claim:
+  granted to the process that claim names, granted once nobody renewed it inside the listener's
+  live window, and otherwise refused naming this very session. The re-assertion confirms the
+  role only when the lookup names this session *and* this process and reports no hand-back,
+  since a claim another process made under this id is not this one's to renew and a claim the
+  listener marked handed back is nobody's to renew; a refusal naming this session keeps the role,
+  refreshes the record's mtime and asks again on the next heartbeat, and only a refusal naming a
+  different session ends the role and removes the file. The restore keeps asking on the same
+  rule: a refusal naming this session's own id leaves the restore pending on `roleTransferFrom`,
+  which every heartbeat presses again until the claim is granted, since one claim at boot and no
+  more would cost a `--resume` or a channel-server restart inside the live window its role for
+  the life of the process. The Legion pane's claim waits the same refusal out rather than
+  stopping the pane, asking every `ROLE_CLAIM_RETRY_MS` (10 s) for the live window and one
+  attempt more, so the grant lands inside the daemon's registration deadline for the pane's
+  `claims/ready` — `worker_boot_timeout_seconds` × `worker_boot_registration_deadline_intervals`
+  from the registration — and it throws only on a refusal naming a different session. The
+  lookup's rule and the record's are the client contract's own,
+  `roleHeldBy` and `mayActOnRoleRecord` in `@legion/envoy-client/transport`, which
+  `packages/pi-envoy` calls too and which read an empty instance id as none, the lookup leaving
+  `client_instance_id` out where the claim names no process. Every claim and every topic
+  hand-back states this process's instance too, so a release frees only the role claims this
+  process holds, and a release the holder's own renewal beat under each of the route's three
+  conditional deletes fails rather than reporting one it did not make. The registration that
+  renews those claims renews every one of them whatever topics it carries, and renews no claim
+  the listener has marked handed back: what says a role was given up is the mark a hand-back
+  leaves on a claim it could not free. This process writes no such mark — it gives a role up by
+  deregistering the session, not by releasing the lane — but a client built before a release
+  stated its process can leave one on this session's claim, and the re-assertion above claims
+  the role back on the next heartbeat, its grant a fresh record with no mark.
+  The handoff directory `sessions/<claude-pid>/` is pruned at startup when its pid is gone —
+  never deleted on shutdown, because Claude Code restarts the server inside the same `claude`
+  process — and the two id-keyed directories, `roles/` and `titles/`, are pruned there too at
+  thirty days, since a session that ends while it still holds its role deletes neither file
+  itself.
 - Shared logic remains shared: use `sessionDispatchSettings`, `formatOpenAsksSummary`,
   `postDeliveryReply`, `mergeInterestSources`, and `sendConfirmationText`. No Dispatch call goes
   through the MCP server; the `dispatch` command runs the shared executor, and a `dispatch_*` tool

package/README.md

@@ -186,19 +186,35 @@ events and sends them to the current Claude Code session as supported
 - A resumed server rebuilds the interests its session id already registered. `envoy_list` reports
   the union of live NATS subscriptions and registry interests with each topic's `source` (`live`,
   `registry`, `both`).
-- `envoy_role_set` persists the held role in `${CLAUDE_PLUGIN_DATA}/roles/<session-id>.json`.
+- `envoy_role_set` persists the held role in `${CLAUDE_PLUGIN_DATA}/roles/<session-id>.json`,
+  which names the writing process's client instance beside the session id and the role.
   `claude --resume <session-id>` finds that file and soft-reclaims the role with the saved
-  `previous_session_id`; a plain relaunch is a new session and inherits nothing. The listener
+  `previous_session_id`; a plain relaunch is a new session and inherits nothing. A record another
+  process wrote is pressed only while this process holds no role, since two `claude` processes of
+  one user share the state directory and a record is keyed by session id alone. The listener
   moves the role off that predecessor only when the predecessor has no live registration, when
   its live registration carries this process's own client instance id, or when either side
   carries no instance id. A predecessor another process still runs keeps the role, and the claim
   is refused naming it: this session goes on running and registered without the role, claims it
   again only on an explicit claim, and keeps the predecessor's role file, since that record
-  belongs to the live holder. Every healthy registration heartbeat checks and reasserts the role
-  if the listener lost it. Shutdown (stdin end, SIGTERM, SIGINT, or the SIGHUP a closing pane
-  sends the whole process group) drains NATS and deregisters the session, naming this process's
-  client instance id, so the listener removes the registry entry only while it still carries
-  that id or none.
+  belongs to the live holder. A claim of a role already held under this session's own id is
+  decided on the standing claim: the listener grants it to the process that claim names, grants
+  it once nobody renewed that claim inside its live window, and otherwise refuses it naming this
+  very session, which keeps the role and the record here and asks again on the next heartbeat.
+  Only a refusal naming a different session ends the role and removes the record. Every healthy
+  registration heartbeat checks and reasserts the role if the listener lost it, and it confirms
+  the role only when the lookup names this session *and* this process and reports no hand-back
+  (`handed_back`); each heartbeat also renews the claims this process holds, whatever topics
+  that registration carries, and renews no claim the listener has marked handed back. A client
+  built before a release stated its process can hand this session's role lane back without
+  freeing the claim, which the listener marks rather than frees, so the mark is read as a role
+  this process does not hold and the next heartbeat claims it back, its grant a fresh record
+  with no mark. This process hands no lane back itself. Shutdown (stdin end, SIGTERM, SIGINT, or the SIGHUP a
+  closing pane sends the whole process group) drains NATS and deregisters the session, naming
+  this process's client instance id, so the listener removes the registry entry only while it
+  still carries that id or none, and every topic hand-back names it too, so a release frees only
+  the role claims this process holds; a release the holder's own renewal beat under each of the
+  route's three conditional deletes fails rather than reporting one it did not make.
 - `/clear` mints a new Claude session id, but a stdio MCP server keeps the `CLAUDE_CODE_SESSION_ID`
   it was spawned with. The SessionStart hook writes the current id to
   `${CLAUDE_PLUGIN_DATA}/sessions/<claude-pid>/session-id` (keyed by the `claude` process both the

package/dist/dispatch.js

@@ -16821,6 +16821,7 @@ function dedupeKeyNamesItsEvent(envelope) {
 }
 // ../contracts/src/envoy-session.ts
 var SESSION_HEARTBEAT_MS = 90000;
+var SESSION_LIVE_WINDOW_MS = 300000;
 var LISTENER_CALL_TIMEOUT_MS = 5000;
 var LISTENER_CALL_RETRY_DELAY_MS = 250;
 var LISTENER_CALL_ATTEMPTS = 2;
@@ -27836,7 +27837,9 @@ var RoleWireSchema = object({
   host: string2().optional(),
   last_seen: number2().int(),
   state: WireStateSchema,
-  holder_state: SessionStateSchema.optional()
+  holder_state: SessionStateSchema.optional(),
+  client_instance_id: string2().optional(),
+  handed_back: boolean2().optional()
 });
 var RoleHeldWireSchema = object({
   error: string2(),
@@ -27915,6 +27918,21 @@ function mergeInterestSources(registryTopics, liveTopics) {
 function holderStateOf(role) {
   return role.holder_state ?? role.state;
 }
+function namedProcess(id) {
+  return id === "" ? undefined : id;
+}
+function roleHeldBy(info, sessionID, clientInstanceID) {
+  if (info === undefined || info.holder !== sessionID || info.handed_back === true)
+    return false;
+  const holding = namedProcess(info.client_instance_id);
+  return holding === undefined || holding === namedProcess(clientInstanceID);
+}
+function mayActOnRoleRecord(writer, clientInstanceID, holdsRole) {
+  const wrote = namedProcess(writer);
+  if (wrote === undefined || wrote === namedProcess(clientInstanceID))
+    return true;
+  return !holdsRole;
+}
 function newClientInstanceID() {
   return Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
@@ -28110,7 +28128,8 @@ function createEnvoyClient(config) {
     unsubscribe: async (input) => {
       await post("/v1/interests/unsubscribe", {
         session_id: input.sessionID,
-        topics: expandSubscriptionTopics(input.topics)
+        topics: expandSubscriptionTopics(input.topics),
+        ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
       }, { actingSession: input.sessionID });
     },
     getInterest: async (sessionID) => InterestWireSchema.parse(JSON.parse(await request(`/v1/interests/${sessionID}`, {}))),
@@ -28180,7 +28199,8 @@ function createEnvoyClient(config) {
         session_id: input.sessionID,
         role: input.role,
         ...soft ? { soft: true } : {},
-        ...previous === "" ? {} : { previous_session_id: previous }
+        ...previous === "" ? {} : { previous_session_id: previous },
+        ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
       };
       let raw;
       try {

package/dist/envoy-channel.js

@@ -38470,6 +38470,7 @@ function dedupeKeyNamesItsEvent(envelope) {
 }
 // ../contracts/src/envoy-session.ts
 var SESSION_HEARTBEAT_MS = 90000;
+var SESSION_LIVE_WINDOW_MS = 300000;
 var LISTENER_CALL_TIMEOUT_MS = 5000;
 var LISTENER_CALL_RETRY_DELAY_MS = 250;
 var LISTENER_CALL_ATTEMPTS = 2;
@@ -44814,7 +44815,9 @@ var RoleWireSchema = object({
   host: string2().optional(),
   last_seen: number2().int(),
   state: WireStateSchema,
-  holder_state: SessionStateSchema.optional()
+  holder_state: SessionStateSchema.optional(),
+  client_instance_id: string2().optional(),
+  handed_back: boolean2().optional()
 });
 var RoleHeldWireSchema = object({
   error: string2(),
@@ -44893,6 +44896,21 @@ function mergeInterestSources(registryTopics, liveTopics) {
 function holderStateOf(role) {
   return role.holder_state ?? role.state;
 }
+function namedProcess(id) {
+  return id === "" ? undefined : id;
+}
+function roleHeldBy(info, sessionID, clientInstanceID) {
+  if (info === undefined || info.holder !== sessionID || info.handed_back === true)
+    return false;
+  const holding = namedProcess(info.client_instance_id);
+  return holding === undefined || holding === namedProcess(clientInstanceID);
+}
+function mayActOnRoleRecord(writer, clientInstanceID, holdsRole) {
+  const wrote = namedProcess(writer);
+  if (wrote === undefined || wrote === namedProcess(clientInstanceID))
+    return true;
+  return !holdsRole;
+}
 function newClientInstanceID() {
   return Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
@@ -45088,7 +45106,8 @@ function createEnvoyClient(config) {
     unsubscribe: async (input) => {
       await post("/v1/interests/unsubscribe", {
         session_id: input.sessionID,
-        topics: expandSubscriptionTopics(input.topics)
+        topics: expandSubscriptionTopics(input.topics),
+        ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
       }, { actingSession: input.sessionID });
     },
     getInterest: async (sessionID) => InterestWireSchema.parse(JSON.parse(await request(`/v1/interests/${sessionID}`, {}))),
@@ -45158,7 +45177,8 @@ function createEnvoyClient(config) {
         session_id: input.sessionID,
         role: input.role,
         ...soft ? { soft: true } : {},
-        ...previous === "" ? {} : { previous_session_id: previous }
+        ...previous === "" ? {} : { previous_session_id: previous },
+        ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
       };
       let raw;
       try {
@@ -55191,7 +55211,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
 
 // package.json
 var name = "@sjawhar/claude-envoy";
-var version2 = "1.15.0";
+var version2 = "1.17.0";
 var legion = {
   daemonApiVersion: 56
 };
@@ -55880,7 +55900,11 @@ async function pruneStaleSessionTitles(stateDirectory) {
 }
 
 // src/session-identity.ts
-var PersistedRole = object({ session_id: string2().min(1), role: string2().min(1) });
+var PersistedRole = object({
+  session_id: string2().min(1),
+  role: string2().min(1),
+  client_instance_id: string2().min(1).optional()
+});
 
 class SessionIdentity {
   directory;
@@ -56123,9 +56147,13 @@ async function waitForSavedTranscript(transcript, signal, pollMs = 100) {
 function isFile(file) {
   return stat2(file).then((info) => info.isFile(), () => false);
 }
+var ROLE_CLAIM_RETRY_MS = 1e4;
+var ROLE_CLAIM_WAIT_MS = SESSION_LIVE_WINDOW_MS + ROLE_CLAIM_RETRY_MS;
 function startLegionClaim(deps) {
   let capability;
   const { sessionID } = deps;
+  const roleWaitMs = deps.roleWaitMs ?? ROLE_CLAIM_WAIT_MS;
+  const roleRetryMs = deps.roleRetryMs ?? ROLE_CLAIM_RETRY_MS;
   const boot = async () => {
     const transcript = await waitForTranscript(deps.pane.configDir, sessionID, deps.signal, deps.pollMs);
     if (deps.pane.launcherSaves) {
@@ -56144,16 +56172,39 @@ function startLegionClaim(deps) {
         capability = registered;
       },
       claimRole: async (role) => {
-        const claimed = await deps.client.setRole({ sessionID, role, soft: true });
-        if (!claimed.claimed) {
-          throw new Error(`Envoy role ${role} is held by live session ${claimed.holder}`);
+        const deadline = Date.now() + roleWaitMs;
+        let waited = false;
+        for (;; ) {
+          const claimed = await deps.client.setRole({
+            sessionID,
+            role,
+            soft: true,
+            clientInstanceID: deps.clientInstanceID
+          });
+          if (claimed.claimed)
+            break;
+          if (claimed.holder !== sessionID) {
+            throw new Error(`Envoy role ${role} is held by live session ${claimed.holder}`);
+          }
+          const left = deadline - Date.now();
+          if (left <= 0) {
+            throw new Error(`Envoy role ${role} is still claimed under this session by another process after ${roleWaitMs} ms of asking`);
+          }
+          if (!waited) {
+            waited = true;
+            deps.log(`Envoy role ${role} is claimed under this session by the process this pane replaced; asking again every ${roleRetryMs} ms for up to ${roleWaitMs} ms, until nobody has answered for that claim inside the listener's live window`);
+          }
+          await delay(Math.min(roleRetryMs, left), undefined, { signal: deps.signal });
         }
         await deps.session.rememberRole(role);
       },
       onRoleRegained: (listener) => deps.session.onRoleRegained(listener),
       log: deps.log,
       stopping: "stopping the pane so the daemon launches it again",
-      stop: deps.stop
+      stop: () => {
+        if (!deps.signal.aborted)
+          deps.stop();
+      }
     });
   };
   const booted = boot().catch((error) => {
@@ -57861,7 +57912,11 @@ async function startChannelSession(options) {
       relay.delivery.setFollowed(registeredTopics());
     return {
       dropping,
-      unsubscribing: serialized(() => options.client.unsubscribe({ sessionID: identity.id, topics }))
+      unsubscribing: serialized(() => options.client.unsubscribe({
+        sessionID: identity.id,
+        topics,
+        clientInstanceID: options.clientInstanceID
+      }))
     };
   }
   function registeredTopics() {
@@ -57914,27 +57969,40 @@ async function startChannelSession(options) {
     const result = await registering;
     takeDeliveryAnswer(sessionID, topics, asking, result);
   };
-  const restoreRole = async (previousSessionID = identity.id) => {
+  const writeRoleRecord = (file, role) => writePersistedRole(file, {
+    session_id: identity.id,
+    role,
+    client_instance_id: options.clientInstanceID
+  });
+  let roleTransferFrom;
+  const restoreRole = async (previousSessionID) => {
     const previousFile = roleStateFile(options.stateDirectory, previousSessionID);
     const persisted = await readPersistedRole(previousFile);
     if (persisted === undefined)
-      return;
+      return "settled";
+    if (!mayActOnRoleRecord(persisted.client_instance_id, options.clientInstanceID, heldRole !== undefined)) {
+      return "settled";
+    }
     const claim = await options.client.setRole({
       sessionID: identity.id,
       role: persisted.role,
       soft: true,
-      previousSessionID: persisted.session_id
+      previousSessionID: persisted.session_id,
+      clientInstanceID: options.clientInstanceID
     });
     if (!claim.claimed) {
+      if (claim.holder === identity.id)
+        return "pending";
       if (claim.holder !== persisted.session_id)
         await rm2(previousFile, { force: true });
-      return;
+      return "settled";
     }
     heldRole = persisted.role;
     const currentFile = roleStateFile(options.stateDirectory, identity.id);
     if (previousFile !== currentFile)
       await rm2(previousFile, { force: true });
-    await writePersistedRole(currentFile, { session_id: identity.id, role: persisted.role });
+    await writeRoleRecord(currentFile, persisted.role);
+    return "settled";
   };
   let regained;
   const fireRegained = (role, reason) => {
@@ -57964,8 +58032,8 @@ async function startChannelSession(options) {
     if (heldRole === undefined)
       return;
     const role = heldRole;
-    const holder = await options.client.getRole(role).then((info) => info.holder, undefinedOnNotFound);
-    if (holder === identity.id) {
+    const holding = await options.client.getRole(role).catch(undefinedOnNotFound);
+    if (roleHeldBy(holding, identity.id, options.clientInstanceID)) {
       await refreshRoleRecord();
       if (afterOutage)
         fireRegained(role, "reregistered");
@@ -57974,24 +58042,27 @@ async function startChannelSession(options) {
     const result = await options.client.setRole({
       sessionID: identity.id,
       role,
-      soft: true
+      soft: true,
+      clientInstanceID: options.clientInstanceID
     });
     if (!result.claimed) {
-      heldRole = undefined;
-      await rm2(roleStateFile(options.stateDirectory, identity.id), { force: true });
+      if (result.holder !== identity.id) {
+        heldRole = undefined;
+        await rm2(roleStateFile(options.stateDirectory, identity.id), { force: true });
+        return;
+      }
+      await refreshRoleRecord();
       return;
     }
     fireRegained(role, "reclaimed");
   };
-  let roleTransferFrom;
   let roleTransferFailureReported = false;
   const transferRole = async () => {
     const from = roleTransferFrom;
     if (from === undefined)
       return;
     try {
-      await restoreRole(from);
-      roleTransferFrom = undefined;
+      roleTransferFrom = await restoreRole(from) === "pending" ? from : undefined;
       roleTransferFailureReported = false;
     } catch (error) {
       if (!roleTransferFailureReported) {
@@ -58056,7 +58127,11 @@ async function startChannelSession(options) {
     const drifted = registry.topics.filter((topic) => topic !== directSubject && !topic.startsWith(ROLE_TOPIC_PREFIX) && !followed.has(topic));
     if (drifted.length === 0)
       return;
-    await options.client.unsubscribe({ sessionID: identity.id, topics: drifted });
+    await options.client.unsubscribe({
+      sessionID: identity.id,
+      topics: drifted,
+      clientInstanceID: options.clientInstanceID
+    });
   };
   let heartbeatInFlight = false;
   let heartbeatRequested = false;
@@ -58145,17 +58220,19 @@ async function startChannelSession(options) {
   await options.connection.flush();
   await serialized(async () => {
     await register();
-    await restoreRole().catch((error) => {
+    try {
+      roleTransferFrom = await restoreRole(identity.id) === "pending" ? identity.id : undefined;
+    } catch (error) {
       if (error instanceof UnparseableRoleRecordError) {
         process.stderr.write(`envoy-channel: ${messageFor(error)}; the session starts without a role
 `);
-        return;
-      }
-      roleTransferFrom = identity.id;
-      roleTransferFailureReported = true;
-      process.stderr.write(`envoy-channel: could not restore the role (${messageFor(error)}); the next heartbeat retries
+      } else {
+        roleTransferFrom = identity.id;
+        roleTransferFailureReported = true;
+        process.stderr.write(`envoy-channel: could not restore the role (${messageFor(error)}); the next heartbeat retries
 `);
-    });
+      }
+    }
   });
   triggerReplay();
   for (const prune of [
@@ -58230,10 +58307,7 @@ async function startChannelSession(options) {
     },
     async rememberRole(role) {
       heldRole = role;
-      await writePersistedRole(roleStateFile(options.stateDirectory, identity.id), {
-        session_id: identity.id,
-        role
-      });
+      await writeRoleRecord(roleStateFile(options.stateDirectory, identity.id), role);
     },
     async shutdown() {
       if (shuttingDown)
@@ -58332,7 +58406,11 @@ async function executeEnvoyTool(runtime, name, input) {
     }
     case EnvoyToolOperation.setRole: {
       const args = parseArguments(spec, input);
-      const result = await runtime.client.setRole({ sessionID: identity.id, role: args.role });
+      const result = await runtime.client.setRole({
+        sessionID: identity.id,
+        role: args.role,
+        clientInstanceID: runtime.clientInstanceID
+      });
       if (!result.claimed)
         throw new Error(`role ${args.role} is held by ${result.holder}`);
       await runtime.session.rememberRole(args.role);
@@ -58546,13 +58624,14 @@ async function runEnvoyChannelServer() {
         ...configuredValue(overrideSessionId) === undefined ? { handoffPid: process.ppid } : {}
       });
     }
-    runtime = { identity, client, session };
+    runtime = { identity, client, session, clientInstanceID };
     if (pane !== undefined && daemon !== undefined && !stopping) {
       claim = startLegionClaim({
         pane,
         sessionID: identity.id,
         daemon,
         client,
+        clientInstanceID,
         session,
         signal: booting.signal,
         log: logLegion,

package/dist/session-hook.js

@@ -15820,6 +15820,7 @@ function dedupeKeyNamesItsEvent(envelope) {
 }
 // ../contracts/src/envoy-session.ts
 var SESSION_HEARTBEAT_MS = 90000;
+var SESSION_LIVE_WINDOW_MS = 300000;
 var LISTENER_CALL_TIMEOUT_MS = 5000;
 var LISTENER_CALL_RETRY_DELAY_MS = 250;
 var LISTENER_CALL_ATTEMPTS = 2;
@@ -26872,7 +26873,11 @@ async function pruneStaleSessionTitles(stateDirectory) {
 }
 
 // src/session-identity.ts
-var PersistedRole = object({ session_id: string2().min(1), role: string2().min(1) });
+var PersistedRole = object({
+  session_id: string2().min(1),
+  role: string2().min(1),
+  client_instance_id: string2().min(1).optional()
+});
 
 class SessionIdentity {
   directory;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/claude-envoy",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "license": "Apache-2.0",
   "description": "Claude Code channel plugin for Legion's Envoy bus",
   "type": "module",

package/scripts/smoke-clear-rebind.sh

@@ -49,11 +49,16 @@ cleanup() {
       sleep 0.2
     done
   done
-  # A deregistered session keeps its interest entry until the listener reaps it; an
-  # unsubscribe with no topics removes the entry now.
+  # A deregistered session keeps its interest entry until the listener reaps it; the
+  # administrator's route removes the entry now. The empty-topics unsubscribe no longer serves a
+  # cleanup that names no process: it frees the role claims of the client instance its body
+  # states, and this script can state none — each channel server mints its own, no listener route
+  # reports it, and both processes have exited by the time this runs. DELETE
+  # /v1/interests/<session_id> removes a session's interests whoever holds them, which is what a
+  # cleanup wants.
   for id in "${session_ids[@]}"; do
-    curl --connect-timeout 2 --max-time 5 -fsS -o /dev/null -X POST -H 'Content-Type: application/json' \
-      "${envoy_url}/v1/interests/unsubscribe" --data "{\"session_id\":\"${id}\",\"topics\":[]}" || true
+    curl --connect-timeout 2 --max-time 5 -fsS -o /dev/null -X DELETE \
+      "${envoy_url}/v1/interests/${id}" || true
   done
   # Claude Code keeps a transcript directory per project path, named after it.
   rm -rf "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects/${workdir//[^A-Za-z0-9]/-}" "$workdir"

package/src/envoy-channel-server.ts

@@ -71,8 +71,10 @@ import {
   type EnvoyClient,
   expandSubscriptionTopics,
   holderStateOf,
+  mayActOnRoleRecord,
   mergeInterestSources,
   newClientInstanceID,
+  roleHeldBy,
   type SubscribeResult,
 } from "@legion/envoy-client/transport"
 import { createLegionDaemonClient } from "@legion/pi-shared/daemon-client"
@@ -1031,8 +1033,15 @@ export async function startChannelSession(options: ChannelSessionOptions): Promi
     if (relay?.sessionID === identity.id) relay.delivery.setFollowed(registeredTopics())
     return {
       dropping,
+      // The release names this process, so the listener frees the role claim of this process
+      // alone where one of these topics is a role's: a second process that resumed this session
+      // id keeps the role it holds.
       unsubscribing: serialized(() =>
-        options.client.unsubscribe({ sessionID: identity.id, topics }),
+        options.client.unsubscribe({
+          sessionID: identity.id,
+          topics,
+          clientInstanceID: options.clientInstanceID,
+        }),
       ),
     }
   }
@@ -1110,6 +1119,27 @@ export async function startChannelSession(options: ChannelSessionOptions): Promi
     takeDeliveryAnswer(sessionID, topics, asking, result)
   }
 
+  /**
+   * Writes `file` as this session's role record, naming this process as its writer, so a second
+   * `claude` reading the same state directory — one that resumed this session id — tells its own
+   * record from this one's. The destination is the caller's, because `restoreRole` resolves it
+   * before it removes the predecessor's file while the record's `session_id` is read after.
+   */
+  const writeRoleRecord = (file: string, role: string): Promise<void> =>
+    writePersistedRole(file, {
+      session_id: identity.id,
+      role,
+      client_instance_id: options.clientInstanceID,
+    })
+
+  /**
+   * The id whose role record is still to be taken back, read by `transferRole` on every
+   * heartbeat: a handoff has moved away from it, a restore of it failed, or a restore of it was
+   * refused by a standing claim under this session's own id. Written by each caller of
+   * `restoreRole` from what that call answered, and by `adoptHandoff` for the id it left.
+   */
+  let roleTransferFrom: string | undefined
+
   /**
    * Take back the role persisted for `previousSessionID` (this id on `--resume`,
    * the pre-`/clear` id on a handoff) with a soft claim naming that predecessor. The listener
@@ -1117,30 +1147,64 @@ export async function startChannelSession(options: ChannelSessionOptions): Promi
    * carries this process's own client instance id, or when either side carries none; a
    * predecessor still live under another client instance keeps the role.
    *
-   * Which is why a refusal naming the predecessor itself keeps the record: it belongs to that
-   * live holder, another process sharing this state directory, and deleting it would cost that
-   * process its only way back to the role. A refusal naming any other session says the
+   * Answers `"pending"` when the role is still to be taken back from that id and only time
+   * decides it, `"settled"` when nothing more is to be asked of that record. The caller keeps
+   * the retry: a restore writes none of its own.
+   *
+   * A record another process wrote is pressed only while this process holds no role
+   * (`mayActOnRoleRecord`, the one rule both clients read). One state directory is read by two
+   * processes whenever a second `claude` resumes a live session's id, and a record is keyed by
+   * session id alone, so the record found here can be the other process's claim rather than a
+   * predecessor of this one's (dispatch://INFRA-783). With no role of its own this process has
+   * nothing to lose by asking, and the listener decides between the two; holding one, it leaves
+   * that record where its writer can still use it. A record written before the writer was named
+   * is nobody's in particular and is pressed as it always was.
+   *
+   * A refusal naming this session's own id is the standing claim of the process this one
+   * replaced — the `claude` that `--resume` continues, or the channel server this one restarted
+   * — which renewed that claim at its last heartbeat and so still stands inside the listener's
+   * live window. The listener grants it the moment nobody has answered for it inside that
+   * window, so that refusal is the `"pending"` answer and every heartbeat asks again until it
+   * is granted: one claim at boot and no more would cost this process its role for the life of
+   * the process, on every `--resume` and every restart inside the window. The record stays
+   * where it is, because the pending claim is read back out of it.
+   *
+   * Which is why a refusal naming the predecessor itself keeps the record too: it belongs to
+   * that live holder, another process sharing this state directory, and deleting it would cost
+   * that process its only way back to the role. A refusal naming any other session says the
    * predecessor demonstrably no longer holds it, so its record goes — the one path that removes
    * a role record by hand.
    */
-  const restoreRole = async (previousSessionID = identity.id): Promise<void> => {
+  const restoreRole = async (previousSessionID: string): Promise<"settled" | "pending"> => {
     const previousFile = roleStateFile(options.stateDirectory, previousSessionID)
     const persisted = await readPersistedRole(previousFile)
-    if (persisted === undefined) return
+    if (persisted === undefined) return "settled"
+    if (
+      !mayActOnRoleRecord(
+        persisted.client_instance_id,
+        options.clientInstanceID,
+        heldRole !== undefined,
+      )
+    ) {
+      return "settled"
+    }
     const claim = await options.client.setRole({
       sessionID: identity.id,
       role: persisted.role,
       soft: true,
       previousSessionID: persisted.session_id,
+      clientInstanceID: options.clientInstanceID,
     })
     if (!claim.claimed) {
+      if (claim.holder === identity.id) return "pending"
       if (claim.holder !== persisted.session_id) await rm(previousFile, { force: true })
-      return
+      return "settled"
     }
     heldRole = persisted.role
     const currentFile = roleStateFile(options.stateDirectory, identity.id)
     if (previousFile !== currentFile) await rm(previousFile, { force: true })
-    await writePersistedRole(currentFile, { session_id: identity.id, role: persisted.role })
+    await writeRoleRecord(currentFile, persisted.role)
+    return "settled"
   }
 
   let regained: RoleRegainHook | undefined
@@ -1187,15 +1251,29 @@ export async function startChannelSession(options: ChannelSessionOptions): Promi
     }
   }
 
-  /** `afterOutage`: the last tick's registration failed, so a holder the listener still names
-   * may have been answered "no holder" meanwhile. */
+  /**
+   * Re-establishes this session as the live holder of the role it holds, on every heartbeat.
+   * `afterOutage`: the last tick's registration failed, so a holder the listener still names may
+   * have been answered "no holder" meanwhile.
+   *
+   * The lookup confirms the role only when it names this session *and* this process
+   * (`roleHeldBy`, the one rule both clients read): a claim standing under this very session id
+   * that another process made is not this one's to renew, and reading it as confirmation is how
+   * a lane kept heartbeating while a continuation's claim held the role and then lapsed
+   * (dispatch://INFRA-783). Anything else is claimed again, soft.
+   *
+   * A refusal naming a different session ends the role here: that session holds it, and this
+   * one's record is the only thing that would claim otherwise, so it goes. A refusal naming this
+   * session is the standing claim of another process under this id, which the listener grants
+   * the moment that process stops renewing it; the role and its record stay, and the next
+   * heartbeat asks again. The record's mtime is refreshed as it is on a confirmed holder, so the
+   * age sweep never expires a record this process is still pressing a claim for.
+   */
   const reassertRole = async (afterOutage: boolean): Promise<void> => {
     if (heldRole === undefined) return
     const role = heldRole
-    const holder = await options.client
-      .getRole(role)
-      .then((info) => info.holder, undefinedOnNotFound)
-    if (holder === identity.id) {
+    const holding = await options.client.getRole(role).catch(undefinedOnNotFound)
+    if (roleHeldBy(holding, identity.id, options.clientInstanceID)) {
       await refreshRoleRecord()
       if (afterOutage) fireRegained(role, "reregistered")
       return
@@ -1204,40 +1282,41 @@ export async function startChannelSession(options: ChannelSessionOptions): Promi
       sessionID: identity.id,
       role,
       soft: true,
+      clientInstanceID: options.clientInstanceID,
     })
     if (!result.claimed) {
-      heldRole = undefined
-      await rm(roleStateFile(options.stateDirectory, identity.id), { force: true })
+      if (result.holder !== identity.id) {
+        heldRole = undefined
+        await rm(roleStateFile(options.stateDirectory, identity.id), { force: true })
+        return
+      }
+      await refreshRoleRecord()
       return
     }
     fireRegained(role, "reclaimed")
   }
 
-  /**
-   * The id a handoff moved away from, until its role has been taken back; a
-   * handoff whose registration failed leaves it for the next heartbeat.
-   */
-  let roleTransferFrom: string | undefined
   /** Whether a failure to take back the queued role has been reported since the last success. */
   let roleTransferFailureReported = false
   /**
    * Best-effort, unlike `syncRegisteredInterests` behind it on the heartbeat. A failed transfer
-   * keeps its own retry, `roleTransferFrom`, which clears only once `restoreRole` resolves; a
-   * throw would add nothing to that and would end the tick before the interests reconciliation,
-   * on every tick for as long as the failure lasts — a resumed session would never adopt its
-   * subscriptions and a registry-side unsubscribe that failed would never be cleared. The
-   * session works without its role meanwhile; it does not work without its interests, whose read
-   * has no queue of its own and needs the failed tick, its report and its retry.
+   * keeps its own retry, `roleTransferFrom`, which this clears only once `restoreRole` answers
+   * that the record is settled; a throw would add nothing to that and would end the tick
+   * before the interests reconciliation, on every tick for as long as the failure lasts — a
+   * resumed session would never adopt its subscriptions and a registry-side unsubscribe that
+   * failed would never be cleared. The session works without its role meanwhile; it does not
+   * work without its interests, whose read has no queue of its own and needs the failed tick,
+   * its report and its retry.
    */
   const transferRole = async (): Promise<void> => {
     const from = roleTransferFrom
     if (from === undefined) return
     try {
-      await restoreRole(from)
-      roleTransferFrom = undefined
+      roleTransferFrom = (await restoreRole(from)) === "pending" ? from : undefined
       roleTransferFailureReported = false
     } catch (error) {
-      // Said once per failure run: every heartbeat retries it.
+      // `roleTransferFrom` is untouched, so the next heartbeat asks again.
+      // Said once per failure run.
       if (!roleTransferFailureReported) {
         roleTransferFailureReported = true
         process.stderr.write(
@@ -1390,7 +1469,11 @@ export async function startChannelSession(options: ChannelSessionOptions): Promi
         topic !== directSubject && !topic.startsWith(ROLE_TOPIC_PREFIX) && !followed.has(topic),
     )
     if (drifted.length === 0) return
-    await options.client.unsubscribe({ sessionID: identity.id, topics: drifted })
+    await options.client.unsubscribe({
+      sessionID: identity.id,
+      topics: drifted,
+      clientInstanceID: options.clientInstanceID,
+    })
   }
 
   // One tick at a time, and at most one pending behind it. `serialized` already
@@ -1525,22 +1608,31 @@ export async function startChannelSession(options: ChannelSessionOptions): Promi
     // failure but one: a listener answer that is not JSON or misses the schema, an unreadable
     // role file, any transient error. The one is a role file whose bytes cannot be parsed, which
     // only `readPersistedRole` can tell apart: no later read of the same bytes succeeds, so it is
-    // not queued, and it costs this session its role and nothing more.
-    await restoreRole().catch((error: unknown) => {
+    // not queued, and it costs this session its role and nothing more. A claim the listener
+    // refused naming this very session is queued the same way, on the `"pending"` the restore
+    // answers: the process this one resumed renewed that claim at its last heartbeat, and the
+    // role comes back from the standing claim itself rather than from the reaper, which never
+    // frees it while this process keeps that session alive. The listener grants it to a process
+    // that keeps asking once that renewal is older than the live window
+    // (`roleOwnSessionVerdict`), so the role is back one live window after that renewal, plus
+    // up to the one heartbeat tick it takes this process to ask again.
+    try {
+      roleTransferFrom = (await restoreRole(identity.id)) === "pending" ? identity.id : undefined
+    } catch (error) {
       if (error instanceof UnparseableRoleRecordError) {
         process.stderr.write(
           `envoy-channel: ${messageFor(error)}; the session starts without a role\n`,
         )
-        return
+      } else {
+        roleTransferFrom = identity.id
+        // This is the first failure of the run `transferRole` reports, so it says nothing more
+        // until the retry has succeeded once.
+        roleTransferFailureReported = true
+        process.stderr.write(
+          `envoy-channel: could not restore the role (${messageFor(error)}); the next heartbeat retries\n`,
+        )
       }
-      roleTransferFrom = identity.id
-      // This is the first failure of the run `transferRole` reports, so it says nothing more
-      // until the retry has succeeded once.
-      roleTransferFailureReported = true
-      process.stderr.write(
-        `envoy-channel: could not restore the role (${messageFor(error)}); the next heartbeat retries\n`,
-      )
-    })
+    }
   })
   // The first sweep, once the listener knows what the session follows: what was stored while it
   // was away (a resume included), or, for a new session, its cursors' start at the stream's end.
@@ -1637,10 +1729,7 @@ export async function startChannelSession(options: ChannelSessionOptions): Promi
     },
     async rememberRole(role) {
       heldRole = role
-      await writePersistedRole(roleStateFile(options.stateDirectory, identity.id), {
-        session_id: identity.id,
-        role,
-      })
+      await writeRoleRecord(roleStateFile(options.stateDirectory, identity.id), role)
     },
     async shutdown() {
       if (shuttingDown) return
@@ -1681,6 +1770,9 @@ export interface ChannelToolRuntime {
   readonly identity: SessionIdentity
   readonly client: EnvoyClient
   readonly session: ChannelSession
+  /** The process the tools act as: the id every registration and every claim of this channel
+   *  server carries (`ChannelSessionOptions.clientInstanceID`). */
+  readonly clientInstanceID: string
 }
 export async function executeEnvoyTool(
   runtime: ChannelToolRuntime,
@@ -1768,7 +1860,14 @@ export async function executeEnvoyTool(
     }
     case EnvoyToolOperation.setRole: {
       const args = parseArguments(spec, input)
-      const result = await runtime.client.setRole({ sessionID: identity.id, role: args.role })
+      // The claim names this process, as every claim this server makes does: the listener
+      // records it as the role's holder, so a second process on this session id cannot be
+      // mistaken for the one holding the role.
+      const result = await runtime.client.setRole({
+        sessionID: identity.id,
+        role: args.role,
+        clientInstanceID: runtime.clientInstanceID,
+      })
       if (!result.claimed) throw new Error(`role ${args.role} is held by ${result.holder}`)
       await runtime.session.rememberRole(args.role)
       return result.interest
@@ -2086,13 +2185,14 @@ export async function runEnvoyChannelServer(): Promise<void> {
         ...(configuredValue(overrideSessionId) === undefined ? { handoffPid: process.ppid } : {}),
       })
     }
-    runtime = { identity, client, session }
+    runtime = { identity, client, session, clientInstanceID }
     if (pane !== undefined && daemon !== undefined && !stopping) {
       claim = startLegionClaim({
         pane,
         sessionID: identity.id,
         daemon,
         client,
+        clientInstanceID,
         session,
         signal: booting.signal,
         log: logLegion,

package/src/legion-claim.ts

@@ -1,6 +1,7 @@
 import { readdir, stat } from "node:fs/promises"
 import { join } from "node:path"
 import { setTimeout as delay } from "node:timers/promises"
+import { SESSION_LIVE_WINDOW_MS } from "@legion/contracts"
 import { messageFor } from "@legion/envoy-client/errors"
 import { readSecretFile } from "@legion/envoy-client/secret-file"
 import type { EnvoyClient } from "@legion/envoy-client/transport"
@@ -132,6 +133,42 @@ function isFile(file: string): Promise<boolean> {
   )
 }
 
+/**
+ * How long apart the attempts of {@link startLegionClaim}'s wait on a claim the listener refused
+ * naming this very session are.
+ *
+ * The wait runs between `claims/register` and `claims/ready`, and the daemon retires a pane that
+ * has not said it is ready `worker_boot_timeout_seconds` ×
+ * `worker_boot_registration_deadline_intervals` after its registration armed that deadline — 120
+ * s × 3 = 360 s with the shipped defaults (`packages/daemon/internal/config/config.go`, armed by
+ * `register` through `armRegistration` in `packages/daemon/internal/supervise`). So the interval
+ * is what stands between the grant and that deadline: the listener grants the standing claim on
+ * the first attempt that falls after the live window its last renewal bought it, which is at
+ * most `SESSION_LIVE_WINDOW_MS` after this pane registered, and every part of an interval past
+ * that point is dead waiting. At a heartbeat's cadence the attempt at 270 s is still refused
+ * whenever that renewal fell inside the 30 s before the registration, and the next one is at 360
+ * s — the deadline itself. At 10 s the grant lands inside 310 s of the registration, 50 s of
+ * room for `claims/ready` and its own retries.
+ *
+ * What the shorter interval costs: one `POST /v1/roles/set` per interval, a conditional write the
+ * listener refuses without touching the claim, at most about 30 of them, and only in a pane the
+ * daemon relaunched into its predecessor's standing claim — once per such relaunch, for at most
+ * one live window.
+ */
+export const ROLE_CLAIM_RETRY_MS = 10_000
+
+/**
+ * How long that same wait keeps asking before it gives up and the pane is stopped: the live
+ * window and one attempt more, so the last attempt falls after the window the process this pane
+ * replaced could still have been answering for its claim in, even when it answered for it at the
+ * very moment this pane registered.
+ *
+ * Inside the daemon's registration deadline on purpose: a pane that cannot have its role writes
+ * why to its log and is launched again, rather than being retired by a deadline that would
+ * otherwise fire first and say nothing.
+ */
+export const ROLE_CLAIM_WAIT_MS = SESSION_LIVE_WINDOW_MS + ROLE_CLAIM_RETRY_MS
+
 export interface LegionClaim {
   /** The registered claim, or undefined until `claims/register` has answered. */
   readonly capability: () => ClaimCapability | undefined
@@ -148,22 +185,44 @@ export interface LegionClaim {
  * `claims/ready` with no capability report, again each time the heartbeat regains the role. A
  * failure the core stops on ends the pane through `stop`; a failure before a registration is
  * logged and leaves the pane to the daemon's registration deadline.
+ *
+ * A claim the listener refuses naming this very session is waited out rather than stopped on:
+ * the pane the daemon relaunched with `--resume` meets the standing claim of the process it
+ * replaced, and that claim is granted the moment nobody has answered for it inside the
+ * listener's live window (`roleWaitMs`). Stopping instead would hand the daemon a relaunch that
+ * meets the same claim, for a whole window of relaunches.
+ *
+ * The claim is asked again every {@link ROLE_CLAIM_RETRY_MS} for up to
+ * {@link ROLE_CLAIM_WAIT_MS}, both sized so the grant, and the give-up behind it, fall inside the
+ * daemon's registration deadline for this pane's `claims/ready`.
  */
 export function startLegionClaim(deps: {
   readonly pane: LegionPane
   readonly sessionID: string
   readonly daemon: LegionDaemonClient
   readonly client: Pick<EnvoyClient, "setRole">
+  /** The channel server's own client instance: the id its registrations carry, which this
+   *  claim names as the process holding the role. */
+  readonly clientInstanceID: string
   readonly session: Pick<ChannelSession, "rememberRole" | "onRoleRegained">
   readonly signal: AbortSignal
   /** Writes one line to the pane's log, the server's stderr. */
   readonly log: (line: string) => void
   /** Ends the pane's Claude Code, this server's parent, so the daemon launches the claim again. */
   readonly stop: () => void
+  /**
+   * How long a claim refused by a standing claim under this very session id keeps asking before
+   * it gives up and the pane is stopped: {@link ROLE_CLAIM_WAIT_MS}.
+   */
+  readonly roleWaitMs?: number
+  /** How long between those attempts: {@link ROLE_CLAIM_RETRY_MS}. */
+  readonly roleRetryMs?: number
   readonly pollMs?: number
 }): LegionClaim {
   let capability: ClaimCapability | undefined
   const { sessionID } = deps
+  const roleWaitMs = deps.roleWaitMs ?? ROLE_CLAIM_WAIT_MS
+  const roleRetryMs = deps.roleRetryMs ?? ROLE_CLAIM_RETRY_MS
 
   const boot = async (): Promise<void> => {
     const transcript = await waitForTranscript(
@@ -188,16 +247,56 @@ export function startLegionClaim(deps: {
         capability = registered
       },
       claimRole: async (role) => {
-        const claimed = await deps.client.setRole({ sessionID, role, soft: true })
-        if (!claimed.claimed) {
-          throw new Error(`Envoy role ${role} is held by live session ${claimed.holder}`)
+        // Soft, so a role another live session holds is left with it, and naming this process,
+        // so the listener records the claim as this process's: a second `claude` that resumed
+        // this session id can then neither be taken for the holder nor release what it holds.
+        //
+        // A refusal naming this very session is that same claim seen from the other side: the
+        // process this pane was relaunched from renewed it at its last heartbeat, so it stands
+        // inside the listener's live window and the listener grants it to nobody else until
+        // that window passes with no answer for it. So the claim is asked again on the
+        // channel server's own heartbeat cadence until it is granted. Only a refusal naming a
+        // different session throws, which stops the pane: that role is another session's, and
+        // no amount of asking changes it.
+        const deadline = Date.now() + roleWaitMs
+        let waited = false
+        for (;;) {
+          const claimed = await deps.client.setRole({
+            sessionID,
+            role,
+            soft: true,
+            clientInstanceID: deps.clientInstanceID,
+          })
+          if (claimed.claimed) break
+          if (claimed.holder !== sessionID) {
+            throw new Error(`Envoy role ${role} is held by live session ${claimed.holder}`)
+          }
+          const left = deadline - Date.now()
+          if (left <= 0) {
+            throw new Error(
+              `Envoy role ${role} is still claimed under this session by another process after ${roleWaitMs} ms of asking`,
+            )
+          }
+          if (!waited) {
+            waited = true
+            // Said once: the state is normal and self-resolving, and a line per attempt would
+            // fill the pane's log with the same sentence for a whole live window.
+            deps.log(
+              `Envoy role ${role} is claimed under this session by the process this pane replaced; asking again every ${roleRetryMs} ms for up to ${roleWaitMs} ms, until nobody has answered for that claim inside the listener's live window`,
+            )
+          }
+          await delay(Math.min(roleRetryMs, left), undefined, { signal: deps.signal })
         }
         await deps.session.rememberRole(role)
       },
       onRoleRegained: (listener) => deps.session.onRoleRegained(listener),
       log: deps.log,
       stopping: "stopping the pane so the daemon launches it again",
-      stop: deps.stop,
+      // A boot the shutdown aborted stops nothing: this server is already going, and `stop`
+      // would SIGTERM the `claude` it runs under on its way out.
+      stop: () => {
+        if (!deps.signal.aborted) deps.stop()
+      },
     })
   }
 

package/src/session-identity.ts

@@ -4,7 +4,23 @@ import { hasErrnoCode, messageFor } from "@legion/envoy-client/errors"
 import { z } from "zod"
 import { pruneStateDirectory, writeAtomicStateFile, writtenLongAgo } from "./session-state"
 
-const PersistedRole = z.object({ session_id: z.string().min(1), role: z.string().min(1) })
+/**
+ * The role record on disk: the session the role was claimed for, the role, and the process that
+ * wrote the record.
+ *
+ * `client_instance_id` is the writer's client instance — one Claude Code channel-server process,
+ * the same id its registrations and its claims carry. One state directory is read by two
+ * processes whenever a second `claude` resumes a live session's id, and the record is keyed by
+ * session id alone, so without the writer a process cannot tell its own record from the other's.
+ * It is optional because a record written before the field existed carries none: such a record
+ * loads and is read as written by no known process (`restoreRole` in the channel server presses
+ * it as it always did).
+ */
+const PersistedRole = z.object({
+  session_id: z.string().min(1),
+  role: z.string().min(1),
+  client_instance_id: z.string().min(1).optional(),
+})
 
 /**
  * The session id the channel server acts as, held once and passed by reference.
@@ -72,9 +88,10 @@ export class UnparseableRoleRecordError extends Error {
 }
 
 /**
- * The role a session held, from its role file; undefined when it has none. Bytes that do not
- * parse throw `UnparseableRoleRecordError`; every other failure to read them (`EACCES`, `EISDIR`,
- * any I/O error) propagates unchanged.
+ * The role a session held, from its role file; undefined when it has none. A record written
+ * before the writer was named carries no `client_instance_id` and loads unchanged. Bytes that do
+ * not parse throw `UnparseableRoleRecordError`; every other failure to read them (`EACCES`,
+ * `EISDIR`, any I/O error) propagates unchanged.
  */
 export async function readPersistedRole(
   roleFile: string,
@@ -137,14 +154,17 @@ export async function pruneStaleSessionHandoffs(stateDirectory: string): Promise
  * title records follow, except the record of `currentSessionId` — the session running the sweep.
  *
  * A record's mtime is when its session was last seen holding the role: every heartbeat on which
- * the listener still names the session as holder touches the record (`refreshRoleRecord` in the
- * channel server), so this age reaches only a record whose session has not confirmed its role for
- * that long — in practice one that stopped running. Only one path removes a role file by hand —
- * a soft `setRole` another live session holds off (`claimed: false`, the listener's 409), never
- * any answer of the publish route — so a session that holds its role to the end leaves its file
- * behind, and the handoff sweep cannot reach it: that one walks `sessions/<pid>/` and asks
- * the operating system about a pid, while a role file is keyed by session id and has no process
- * left to ask about.
+ * the listener still names the session as holder touches the record, and so does every heartbeat
+ * a refused process spends pressing its claim again (`refreshRoleRecord` in the channel server),
+ * so this age reaches only a record whose session has not confirmed its role for that long — in
+ * practice one that stopped running. Only one path removes a role file by hand — a soft
+ * `setRole` refused (`claimed: false`, the listener's 409) naming a session other than the one
+ * the record is for, which says that session demonstrably no longer holds the role — never any
+ * answer of the publish route, and never a refusal naming the record's own session, which is the
+ * role held under that id by another process. So a session that holds its role to the end leaves
+ * its file behind, and the handoff sweep cannot reach it: that one walks `sessions/<pid>/` and
+ * asks the operating system about a pid, while a role file is keyed by session id and has no
+ * process left to ask about.
  *
  * The sweep runs at startup, before any heartbeat has touched anything, and a session whose claim
  * the listener refused there has not touched its own record either: age alone would expire the