UK

Claude session arbiter

Rule: one Claude works on a session at a time. Two agents thinking on the same session fork it and create conflicts. The single source of truth is ide/src/Claude/SessionArbiter.php (IDE PHP process). The page only displays it and asks it.

Algorithm

State per session id (conv -> session alias table; a conversation without an id yet is conv:<key> and is merged when claude names its session). Two owners, panel (claude -p, kept open between turns) and terminal (interactive claude). Remote devices, retry, /compact, History, mode changes never own: they go through the owner.

idle --acquirePanel--> panel --(process exits)--> idle
idle|panel --requestTerminal--> handoff(from -> terminal) --(exit confirmed, no foreign claude)--> terminal
terminal --(claude gone | tab closed)--> handoff(terminal -> idle) --> idle (queue replayed to the panel)
panel --(new settings / stale process)--> handoff(panel -> panel) --> panel under a new epoch
any --(foreign claude / unknown writer)--> conflict --(resolved)--> idle

Handoff protocol (never blocks the frame: it advances in Ide::tick() and claude.lease.get):

  1. Freeze: state handoff; every new input goes to the ordered queue of the session (never dropped, never interleaved).
  2. Stop the leaving owner (SIGTERM) and wait for the confirmed exit (/proc/<pid>/stat, a zombie counts as gone); after 2.5 s SIGKILL of the whole process tree; after 6 s still alive: conflict.
  3. Verify: scan the system for another claude on the session (Linux /proc, macOS ps; Windows: no command lines, only the file guard). Strong match: its command line names the session id (--resume, --session-id, -r) or is -c/--continue in the project folder. Weak match: a claude in the project folder with no session on its command line, counted only while the session file moved in the last 20 s. The panel's own processes and the claude of the leased Terminal tab never count. A foreign claude: no handoff, conflict with its pid / terminal / folder, and the person's click "Stop it" (SIGTERM, then SIGKILL of its tree) or "Check again".
  4. Grant to the new owner: epoch = ++global_epoch.
  5. Replay the queue in order: to the Terminal (claude.lease.drain, typed one by one by the page), or to the panel (claude.queue.sent).

Invariants:

  • At most one live panel claude per session, and none while the Terminal owns it. A panel process whose epoch differs from the lease's is killed by the tick.
  • Every spawn, every write into a panel process (assertPanel) and every terminal drain carries the epoch; a stale one is refused (LeaseRefused).
  • A new panel process starts only after every older process of the session (other settings, stopped but not gone) is gone: its message waits in the queue (handoff panel -> panel).
  • The queue is FIFO per session whatever the conversation key; a message typed during a handoff or a conflict is delivered to the new owner, in order.
  • The Terminal lease needs proof of life: the probe looks for a claude on the terminal's device (/proc/<pid>/fd/0). Seen then gone (/exit, Ctrl+C, the shell stays) = lease released by itself, the panel gets the conversation back (rcBack). Never started in 60 s, or never attached: released.
  • File guard: the session file grows while the lease says nobody (idle) or the owner is not there: conflict (foreign-writer), the panel's process is stopped, a notification is shown. An unknown writer clears after the file has been still for 8 s.

Session id

claude -p --resume <id> and an interactive claude --resume <id> keep the same id in Claude Code 2.1.x (checked: a throwaway project, 40 session files of this project: file name = every sessionId inside). A fork only happens with --fork-session, which the IDE never passes. The IDE never passes --session-id either (it needs a UUID and a new session). If a conversation is told another id, learn() moves its lease to the new id.

Events and commands

claude.lease {session, conv, owner, state, epoch, reason, queued, conflict}, claude.queue.sent {conv, id, text}; commands claude.lease.get / request / attach / ready / ended / drain / submit / resolve. The panel shows a badge (Panel / Terminal / Switching… / Conflict) and the input box says what happens to a message typed during a handoff.

What cannot be guaranteed

  • A claude on another computer on the same session (Remote Control from claude.ai/code, the phone, a synced folder): only the file guard can notice, and only when the file is on this computer.
  • An interactive claude started by hand that picked this session after start (/resume inside it) has no session id on its command line: the weak match and the file guard catch it, not the scan.
  • Windows: no command-line scan; the page's word (tab ended) and the file guard remain.
  • The claude --bg background sessions keep working after their terminal closes: caught by the scan only when their command line names the session.