winzik/docs/claude-session-arbiter.md

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.