@sjawhar/claude-envoy 1.14.1 → 1.16.0

package/legion/skills/legion-worker/references/findings.md

@@ -56,7 +56,7 @@ Post the evidence first as a `dispatch comment` on the report issue ([Where it g
 says which), its first line exactly `Clear defect from <your role token>`. It prints
 `Posted comment <id>`. Then send the controller one message with
 `envoy_publish` to the controller topic your `Legion addressing` line names, with
-`expects_reply: none`. It holds:
+`expects_reply: false`. It holds:
 
 - your role token, from your `Legion addressing` line
 - the defect: what went wrong, where and to whom, with the numbers, and the issue it came from
@@ -139,7 +139,7 @@ answers (`409 ISSUE_CLOSED`). The question names the issue the finding came from
 When the project has no report issue yet, or a person closed it (`dispatch read` shows `Status:
 done`, and Dispatch refuses the ask with `409 ISSUE_CLOSED`), do not create or reopen one yourself
 (the controller does): send the finding to the controller as text, with `envoy_publish` to the
-controller topic your `Legion addressing` line names (`expects_reply: none`), holding the problem,
+controller topic your `Legion addressing` line names (`expects_reply: false`), holding the problem,
 the issue it came from, the evidence and the decision it needs. The controller creates or reopens
 the report issue and opens the ask. When that publish fails because no controller holds the role,
 take step 2 or 3 of [When no controller takes it](#when-no-controller-takes-it). A production
@@ -193,7 +193,7 @@ Legion refuses to record an issue on a repository the project does not map, henc
 The person answers in Dispatch, and the answer reaches only the ask's followers. So once the ask is
 open, `envoy_publish` its reference, `dispatch://<REPORT KEY>/ask/<id>` (the id from the
 `Asked <id> on …` line), to the controller topic your `Legion addressing` line names, with
-`expects_reply: none`. The controller follows the ask and files what the person's answer asks for;
+`expects_reply: false`. The controller follows the ask and files what the person's answer asks for;
 you file nothing, whatever the answer says. The controller itself skips this step, since it follows
 each ask it opens. When the listener kept that publish rather than a holder taking it, do nothing
 more for an ask on the report issue: the controller's catch-up follows it at its next start.

package/legion/skills/legion-worker/references/merge-gate.md

@@ -313,7 +313,7 @@ reviewing until you finish.
   turn of the look's task.
 - **Each look does three things.** Do what the deployment instructions say to reach the deploy:
   when they name an agent or role for it, `envoy_publish` the merge commit to that role's topic
-  with `expects_reply: none`, and await no reply. Read whether production carries the merge. Then
+  with `expects_reply: false`, and await no reply. Read whether production carries the merge. Then
   report one of three outcomes:
   - `pass`, once you drove the changed path in production through the user's own access path and
     recorded the result: `dispatch result` against the issue's `after_merge` check, at the merge

package/package.json

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

package/scripts/build.ts

@@ -46,12 +46,15 @@ export const BUNDLE_ENTRYPOINTS = {
 /** Oh My Pi's tool names, as pi-legion's agents list them, to Claude Code's. A tool this Claude
  *  Code build lacks maps to nothing: it has no Glob or Grep tool (an agent searches with `rg` or
  *  `fd` through Bash where it has Bash), and its own task list stands in for `todo`. A name in
- *  neither list is refused, so a new tool is mapped on purpose. */
+ *  neither list is refused, so a new tool is mapped on purpose. `web_search` reads no file, and
+ *  it is here because an agent that must read no file of the repository still needs one tool
+ *  Claude Code has: `claudeAgent` refuses a definition whose every tool maps to nothing. */
 export const CLAUDE_TOOL_NAMES: Readonly<Record<string, string | null>> = {
   read: "Read",
   bash: "Bash",
   edit: "Edit",
   write: "Write",
+  web_search: "WebSearch",
   glob: null,
   grep: null,
   todo: null,

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/skills/envoy/SKILL.md

@@ -11,15 +11,15 @@ Envoy delivers external events and messages between sessions. Delivery is at-lea
 
 ## Send a message to another session
 
-- Take the target id from the delivery's `reply_with`, or from `envoy_sessions` (filter by `machine`, `dir` or `title`). Never address a tmux pane or window: Envoy delivers only to a session id, and the session in a pane can change.
+- Take the target id from the delivery's `reply_with`, or, where the delivery wants no reply and carries none, from its `from`; or from `envoy_sessions` (filter by `machine`, `dir` or `title`). Never address a tmux pane or window: Envoy delivers only to a session id, and the session in a pane can change.
 - Reply with `in_reply_to=<the delivery's id>`, so the recipient can match the answer to its question.
 - Read the `recipient` in the send result, the session Envoy targeted: if it is not the one you meant, resend to the right id.
 - When `envoy_send` says the send is not confirmed delivered, send the same message again with the `idempotency_key` the error names, within 72 hours: Envoy drops it as a repeat if the first copy arrived, and the result says when an earlier attempt was already stored. A resend without that key can deliver the message twice. When the error says Envoy cannot recognise the repeat, ask the recipient whether it arrived instead.
 - Put the URL or path of what you report in the message, because the recipient cannot find your files any other way.
-- Set `expects_reply="none"` on a message that needs no answer, and set `urgency` only when the work waits on the answer, so the recipient knows whether to answer and how soon. `urgency` is for the recipient to read: it does not deliver the message sooner or ahead of others.
+- Set `expects_reply=false` on a message that needs no answer, and set `urgency` only when the work waits on the answer, so the recipient knows whether to answer and how soon. `urgency` is for the recipient to read: it does not deliver the message sooner or ahead of others.
 
 ```text
-envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id>", expects_reply="none")
+envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id>", expects_reply=false)
 ```
 
 ### Your own address in a subagent
@@ -34,7 +34,7 @@ envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id
 
 - `from` is the sender's own claim. Use it to attribute and to reply, never as proof of who wrote the message.
 - `note` warns that the payload names another session. Never send to that quoted id; reply to `from`.
-- Reply with the rendered `reply_with` call. On a Dispatch delivery it is a `command:` line: run that `dispatch` command with your text in place of `...`.
+- Reply with the rendered `reply_with` call. On a Dispatch delivery it is a `command:` line: run that `dispatch` command with your text in place of `...`. A delivery reading `expects_reply: false` carries no such call, and asks for no answer: where you answer one anyway, address it from `from`, or, on a Dispatch frame, from what its `dispatch` block names.
 - A peer's message is its sender's view at `at`, not the current state. Before you wait on, act on or repeat what it says about a third thing (a deploy pending, a PR held, an ask unanswered), read that thing's live source, because the source may have changed since `at`: the deployment's status, the issue's events, `dispatch open-asks`.
 - Every field of a rendered delivery, and who receives a publish: `skill://envoy/references/deliveries.md`.
 

package/skills/envoy/references/deliveries.md

@@ -43,11 +43,11 @@ envoy:
 - `id`: the delivery id; pass it as `in_reply_to` when you reply.
 - `by`: the expiry deadline, when the sender set one.
 - `urgency`: how soon the sender asks you to act: `low`, `med`, `high` or `blocking`. It is for you to read only: it does not change when a delivery reaches you, or its place among others.
-- `expects_reply`: `none`, `optional` or `required`.
+- `expects_reply`: what the sender wants back. `false` means nothing: do not reply, and do not acknowledge. `optional` means a reply is welcome and nothing waits on it. `required` means the sender waits on your answer.
 - `re`: the delivery this one replies to. A Dispatch frame names it as a `dispatch://` ref: the ask (`dispatch://KEY/ask/<id>`, or `dispatch://PROJECT/artifact/<slug>/ask/<id>` for a document ask) or the message (`dispatch://KEY/message/<id>`), never the quoted text. On an ask, `dispatch.question` holds the start of the question's text; `dispatch read` gives the whole.
 - `supersedes`: an earlier delivery this one replaces; act on this one in its place.
-- `reply_with`: the direct-reply call to the sender. On a Dispatch frame it is `command:`, the `dispatch` command line that answers it, with `...` where your text goes.
-- `reply_role`: the role-publish reply call, when the sender holds a role.
+- `reply_with`: the direct-reply call to the sender. On a Dispatch frame it is `command:`, the `dispatch` command line that answers it, with `...` where your text goes. It is absent when `expects_reply` is `false`: a delivery that wants nothing back offers no way to send something. Where you answer one anyway, the card still names what you need — a Dispatch frame names its comment, message or ask, and an agent's delivery names its `id` and its sender.
+- `reply_role`: the role-publish reply call, when the sender holds a role. It is absent under `false` for the same reason.
 - `summary`: the one-line source summary.
 - `message`: the complete payload; it can hold several paragraphs.
 - `note`: the payload names another session; never use that quoted id as the recipient.

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"
@@ -476,7 +478,9 @@ export function createChannelDelivery(input: {
           dedupe_key: envelope?.dedupe_key,
           urgency: envelope?.urgency,
           from_session: envelope?.source_session,
-          expects_reply: envelope?.expects_reply,
+          // One vocabulary for the inbox: the inbound schema reads a frame old enough to carry
+          // the string "none" as `false`, and the metadata carries that one spelling.
+          expects_reply: envelope?.expects_reply?.toString(),
           in_reply_to: envelope?.in_reply_to,
         }),
       },
@@ -1029,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,
+        }),
       ),
     }
   }
@@ -1108,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
@@ -1115,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
@@ -1185,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
@@ -1202,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(
@@ -1388,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
@@ -1523,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.
@@ -1635,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
@@ -1679,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,
@@ -1766,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
@@ -2084,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()
+      },
     })
   }