F1b: runner coordinator for attempts, slots and shutdown

[mchwang]

Lane F, step F1, slice F1b: runner coordinator. Stacked on #53 (F1a, the Store); merge #53 first. Related: #22, #51.

What this does

Adds runner/coordinator.ts, the per-process owner of in-memory jobs, slots and unresolved markers, as specified in docs/implementation/runner-lifecycle.md. D is injected (RunnerDeps.start), so this runs against a fake D until #51 lands; nothing is wired to the server yet.

• Admission in two steps. In one synchronous turn, the coordinator checks it is open, that the task has no job or marker, and that a slot is free, then reserves the slot. Then Store.admitAttempt runs. A refused transaction releases the reservation in the same turn. Writable kinds share one slot and read-only kinds share another; both limits are configurable.
• Preparation. Host-side preparation gets an AbortSignal. The task budget timer records time-limit. The attempt deadline, before launch, fails the attempt with "Timed out" and records no first reason.
• Launch check. In one synchronous turn: the row is still pending, there is no first reason (saved or in memory), there is time left and the context is current. Then captureInvocation, then D's start. A context change during preparation ends stale without calling D. A stop during launch ends from its first reason. A start error ends failed with the launch error.
• Running. If markRunning is refused because a first reason exists, the handle is cancelled and settles normally. If the write fails with a storage error, the handle is cancelled with capture-failure, settled, and the slot stays held under a start-not-saved marker.
• Stops. The first reason wins. It is kept in memory and saved when possible; status().stopRequested.saved shows when saving failed. The slot is never freed on cancel, only after settled.
• Settlement. A clean result is validated, then the Store chooses the terminal state from the first reason, D's result and context currency. A failed terminal write leaves a result-not-saved marker that holds the slot until restart.
• Cancel task and shutdown. cancelTask goes through the Store and stops the running work. close() rejects admission, records shutdown only where no reason exists, and awaits every job with no timer. It leaves the Store open for the caller to close.

Validation (head 3767065)

• npm run typecheck: passes.

• CI's unit set (npm test minus the Docker suites): 488 passed, 0 failed. 18 of those tests are new, in test/runner-coordinator.test.ts, using a fake D whose promises the test controls, and real SQLite.

• Mutation check: six guards were broken one at a time, and each was caught:

  • a stop freeing the slot early;
  • the launch check skipping the context comparison;
  • no marker after a failed terminal write;
  • close() not waiting;
  • a later reason overwriting the first;
  • the reservation kept after a Store refusal.

• AGENTS.md race regressions covered here:

  • lease expiry or a clock jump, then a retry while the original still runs;
  • a timeout, then the provider stays unsettled, then a retry;
  • shutdown, then a new request;
  • an abort, then the subprocess settles later;
  • a context change before launch.

  The Store-level cases (an old attempt settling after a retry, two processes admitting at once) are in F1a.

• Browser tests weren't rerun: this slice doesn't touch web/.

Not in this slice

• F1c: the Store write gate, coordinator barriers and server wiring, /api/runner, and the merge-coordinator catches.
• F1d: startup recovery, the requeue claim and the OS lock.
• F1e: the planning endpoints, and feedback wiring into review actions.
• Task storage. Removing it after the terminal write is F2 (writable attempts).
• Recorded preparation process group. Saving preparation_pgid is part of F1d, together with the abortable D helpers from D follow-ups required by the F1 runner lifecycle contract #51.

🤖 Generated with Claude Code