session: a session whose runner died can be reclaimed deliberately

[Shashankss1205]

Closes #19. Design decisions were posted as a comment on the issue first, as it asked; this is the implementation of them.

The defect, reproduced on main

status: running  runner_pid: 58011  alive: False
WEDGED: session 'crashme' is running; expected one of ['idle', 'interrupted', ...]
release methods available: NONE
manager methods: NONE

The row keeps the dead runner_pid, so the store knows who died holding it and had no way to act on that. Every later run() raised SessionBusy forever, and the only remedy was sqlite3 ... UPDATE, which skips the lifecycle check and writes no transition row — corrupting the audit trail the store exists to keep.

The decisions

failed, not interrupted. interrupted says a turn stopped somewhere it can be picked up from; a runner that died left no such point. failed says the turn did not settle, which is true, and is already in RESUMABLE.

Open holds survive. pending_approval is untouched, so a session waiting on a human is still waiting afterwards — reclaiming a wedged session must not be a way past an approval gate. Asserted.

The liveness check is inside BEGIN IMMEDIATE, not before it, so two operators reclaiming at once serialise on it. A check outside the write lock is the same deferred-read race _transaction's docstring already describes for claiming.

Nothing calls it automatically. Pid liveness is host-local and pids are recycled; an automatic sweep would be a way for two live runners to fight over one session, which is exactly what the claim exists to prevent.

Four refusals, each tested

Condition	Why
not running	there is no claim to release
pid alive (incl. PermissionError → read as alive)	a live pid does not prove the runner lives, but proves it might
pid is this process	a caller bug, not a crash
running with no runner_pid	the row is inconsistent in its own right; papering over it hides a different bug

Pid reuse is not solved and is not pretended to be: a recycled pid reads as alive, which produces a refusal — the safe direction.

The tests are real, not mocked

• The crash is a child that claims the session and os._exits, skipping every cleanup path — what a SIGKILL looks like from the store's side. (stdout is flushed by hand, because _exit will not.)
• The alive-refusal test parks a real child on a file barrier rather than inventing a pid, and asserts the refusal left no transition row and no status move.
• The dead pid used in the hold test is spawned and reaped rather than guessed: a made-up number can belong to something, and the check under test refuses a live pid, so an unlucky guess would pass or fail for the wrong reason.

All five are red without the source change.

Docs

The three honesty paragraphs this obsoletes are updated: store.transition's docstring, session/runtime.py's limitations list, and the deep dive's. The issue pointed at README.md:499, but that sentence has since moved to the deep dive — checked rather than assumed.

Out of scope, as the issue set it

A cross-host heartbeat/expiry lease, and any automatic background sweeper.

Verified

2,210 selected, 13 deselected, ruff check . clean; the session suite is 48 green.

🤖 Generated with Claude Code