Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_018nX3d1jqkxbS2Bhas8tTzM
64 lines
5 KiB
Markdown
64 lines
5 KiB
Markdown
# 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.
|