runner-lifecycle.md

F1 runner lifecycle and state-holder contract

Status: contract proposed; the four open decisions are approved (2026-09-25). Nothing in this document is implemented yet. Lane and step: lane F (runner and pre-merge automation), step F1. Related issue: #22. Baseline: main at af8f3c2 (D1–D5 merged). The D changes this contract needs are tracked in #51.

About this document

Who it is for. People who build or review lanes F, G, I, J and K, and the agent that implements F1.

What it is for. The plan requires F1 to publish and review its lifecycle contract before any F1 code is written. This document is that contract. It says:

• which states a runner job can be in, and which changes between states are legal;
• which part of the program owns each piece of state, and when that owner may let go of it;
• when a retry is allowed;
• the order of steps when the program shuts down;
• the feedback events that the learning lane (J) will read.

When implementation starts. The plan starts F implementation after D5 merges, and D5 merged as #50. F1 code can start now. The attempt lifecycle itself uses only the D interface already on main (agents/contract.ts), which D4 (#47) did not change. Preparation, shutdown and startup recovery need D changes that do not exist yet: bounded settlement; runnerOwner (and the attempt ID) on InvocationInput and on every allocator that runs before an invocation; a scoped recoverLeftovers API that returns authenticated storage handles; and asynchronous, abortable versions of both preparation helpers, createTaskClone and prepareTaskFilesystems. They are listed as prerequisites under "Shutdown". D5 delivered none of them: it did not change agents/contract.ts, and its hand-off doc confirms that the supervisor still retries cleanup until settlement (docs/implementation/agent-isolation.md). They are tracked in #51. The F1 implementation may start against fakes, but it must not merge until #51's pre-F1 items land.

Summary

1. Every agent run or runner command is an attempt. An attempt has one ID, which is never reused. A retry is a new attempt.
2. An attempt moves through pending → running → completed | failed | cancelled | stale. The runner as a whole is open or closing.
3. For attempts that can write to the task folder, the durable record becomes terminal only after the container has stopped. "Cancel" first records the reason and shows "Stopping". It does not free anything.
4. A result is saved only if a compare-and-swap succeeds: the attempt ID must still be the task's current attempt, and the captured context (including the context generation) must still be current. Late results are thrown away, but their container must still stop before its slot is freed.
5. Retry is allowed only when the last attempt is terminal on disk, nothing for that task is still running in this process, and its captured context still matches the current code, plan and assignment. Otherwise the user must start a new request.
6. Shutdown order: reject new work → drain HTTP requests (with a time limit) → abort and await request-owned work → cancel and await runner jobs → write terminal states → close storage → release the runner lock.
7. Each piece of user feedback becomes one append-only feedback event, written in the same transaction as the user action, or, for a merge, in the same transaction as the confirmed outcome. Lane J reads these events after a task closes.

Terms used

Term	Meaning in this document
Task	One run of one GitHub issue through its plan, from start to merge or cancel. A task is identified by its full PlanIdentity (repositoryId, taskId, planId, from core/identity.ts), stored as its identityKey (the plan key). A bare taskId is never used alone, because it is unique only inside its repository and plan.
Attempt	One agent invocation or one runner command for a task. Has a unique attemptId, which the Store generates as a lowercase UUID v4. Any stored value that does not match ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ is refused before it is used anywhere, including as a directory name.
Phase	D's invocation profile, from the closed Phase union in agents/contract.ts: planning, questions, review, execute, fix. captureInvocation rejects any other value.
Attempt kind	F's own label for an attempt, stored on the attempt row. Each kind runs under exactly one D phase (see the table below).
Writable attempt	An attempt whose D phase is execute or fix. It can change the task folder.
Captured context	The InvocationContext saved when an attempt is admitted: snapshot ID, plan ID, plan revision, assignment ID, referenced-code hash, and the task's context generation (sent in D's stateVersion field).
State version	A number stored on each task. It goes up by one on every durable change to the task or its attempts, including an attempt's own lifecycle changes. The UI and user actions use it for ordering and compare-and-swap. It is not part of the captured context.
Context generation	A second number stored on each task. It goes up only when something an attempt depends on changes: the plan revision, the snapshot, the assignment or the referenced code. Every such change also increases the state version in the same transaction, so UI ordering and user-action checks see it too. Attempt lifecycle changes increase only the state version, never the context generation. F puts it in InvocationContext.stateVersion.
Current	A captured context is current when its snapshot ID, plan ID, plan revision, assignment ID, referenced-code hash and context generation all match the task's present durable values. An attempt's own transitions therefore never make it non-current.
Settled	D's InvocationHandle.settled promise has resolved. The container and its output capture have stopped.
First reason	The first stop reason recorded for an attempt: cancelled, shutdown, stale or time-limit. Later reasons never replace it.
Slot	The in-memory right to run an attempt. A limited number of slots exist.
Admission	The point where the runner accepts new work and writes the pending attempt.
Feedback event	An append-only record of one piece of feedback that the user wrote or chose.

Attempt kinds and D phases

F never sends D a phase outside D's union. Runner-only work is modelled as an attempt kind that maps to an existing D phase.

Attempt kind	D phase	Why this phase
planning	planning	Read-only authoring
question	questions	Read-only answer
review	review	Read-only review agent
check	review	Runs only the approved cmd: argv through D's dispatcher, on the read-only mount
execute	execute	Carries out one plan item on a writable mount
fix	fix	Fixes one review problem on a writable mount
rebase-fix	fix	Resolves one rebase conflict. F's post-run audit refuses changes outside the conflicting files.

If F3 needs a D profile that no existing phase provides, that is a change to agents/contract.ts. It goes through D's owner and its contract tests before F3 uses it.

State holders and owners

AGENTS.md requires these five holders to be treated separately. Each one has exactly one owner.

Holder	What it holds	Owner	It lets go when
Durable records	Task rows, attempt rows, feedback events (SQLite through runner/store.ts)	Store. It is the only writer.	Never deleted by the lifecycle. Terminal rows stay as history.
In-memory jobs	One Job per active attempt: attempt ID, handle, first reason, settlement promise	The runner coordinator (one instance per process)	After D's settled resolves and the terminal durable write has succeeded. If that write fails, the job becomes an unresolved marker (see "Slots and concurrency", rule 5) and is not removed.
Agent containers and their processes	The agent container, capture processes, egress proxy and network, and their cleanup	D (the adapter behind InvocationHandle)	When settled resolves. F never signals or kills these directly.
Task storage	The task-storage volumes and keeper container for one attempt	F holds the capability (TaskFilesystems from prepareTaskFilesystems, or a recovery handle); D implements the operations	It outlives settled. Order for every writable attempt, whatever its outcome: settled → the partial-output export if the attempt did not complete (a completed attempt's work is taken out by F2's commit step instead) → the terminal write, which stores diagnostic_ref → removeTaskFilesystems → the slot is freed. If removal fails, the slot stays held under an unresolved marker, and startup recovery removes the storage. D never removes it at settlement.
Preparation subprocesses and files	Host-side work F runs before launch, such as git clone, and the attempt directory it fills	F (the job, then startup recovery)	When the process group has exited and the attempt directory has been captured and removed (see "Launch").
Admitted HTTP requests	Requests that have passed the token and admission checks	web/server.ts (activeRequests)	After the response ends, or after it is aborted during shutdown
Rendered UI	What the browser shows, drafts, selections, the latest state version seen	web/public/app.js	It never owns durable truth. It shows server state and keeps unsent input.

Attempt states

States

State	Meaning	Durable?	UI label
pending	Admitted and saved. The container has not started yet.	yes	Waiting to start
running	D returned a handle. The container may be running.	yes	Running, or Stopping if a stop reason is recorded
completed	The result passed validation and was saved by compare-and-swap.	yes, terminal	Done
failed	Non-zero exit, timeout, output limit, capture failure, invalid output, or interrupted by a crash.	yes, terminal	Failed: reason
cancelled	Stopped by a user, a hard stop, or shutdown.	yes, terminal	Cancelled: reason
stale	Its captured context stopped being current before its result was saved.	yes, terminal	Out of date: cause

closing is a state of the whole coordinator (open → closing), not of one attempt.

Legal transitions

Any change not in this table is illegal. The Store refuses it.

From	To	Trigger	Guard
—	pending	Admission	In memory, first: coordinator is open, no job or unresolved marker for the task, and a slot is free; then reserve the slot. In one Store transaction: the task's status is running or queued; task state version equals the caller's expected version; no non-terminal attempt exists for the task; captured context is current.
pending	running	D returns a handle	Attempt ID is the task's current attempt; state is pending; no first reason recorded. The launch check (see "Launch") ran immediately before the D start call.
pending	cancelled	Stop before or during launch	Same attempt ID; state is pending; first reason is cancelled, shutdown or time-limit
pending	stale	Context changed before launch	Same attempt ID; state is pending; first reason is stale, or no first reason and the context is no longer current
pending	failed	Preparation or launch error	Same attempt ID; state is pending; no first reason recorded; captured context still current (otherwise the row takes stale)
pending → pending, running → running	same state, first reason set	A stop request ("Stopping")	Same attempt ID; state unchanged; first reason is null. It sets the first reason, and the attempt's state stays the same. The state version increases. This is how rule 1 of "Rules for the running state" becomes durable.
running	completed	Validated result	Attempt ID is current; state is running; no first reason recorded; captured context still current; task status is running and cancel_requested is null
running	failed	Settled with an error or invalid output	Attempt ID is current; state is running; captured context still current (otherwise the row takes stale); and either no first reason recorded, or first reason shutdown with a D stopReason of timeout, output-limit or capture-failure (D stopped first; see rule 2)
running	cancelled	Settled after a user, hard-stop, shutdown or time-limit reason	Attempt ID is current; state is running; first reason is cancelled, shutdown or time-limit
running	stale	Settled after the context changed	Attempt ID is current; state is running; first reason is stale, or no first reason is recorded and the context is no longer current (a change made by another transaction that the runner had not yet seen)
pending or running	terminal state from the first reason, or failed if there is none	Startup recovery (the previous process died). Uses the same first-reason mapping as settlement.	Runs before admission opens, after D's recovery has removed leftover containers

A task's status does not change while it has an active attempt. While an attempt is pending or running, the task stays running. The only status changes allowed then are the ones this contract makes in the same transaction as the attempt's terminal write: needs human from the time limit, and cancelled from a pending cancel task. Every other status change, including to a human-gated status, is refused until the attempt is terminal. F2 moves a task to needs amendment or needs human only after its attempt has settled. As a second safeguard, the completion guard requires status running; if it somehow is not, the attempt ends cancelled ("The task left the running state before the result was saved.").

Admission requires an active task. Every admission, not only a retry, needs task status running or queued. A closed task (merged, cancelled) never admits work. A human-gated task must first be moved back by its own explicit user action, which is a separate transition in F2 or lane I.

Admission is two steps. SQLite cannot check in-memory facts, so the coordinator first checks open, the task's job or marker, and slot capacity, and reserves a slot, all in one synchronous turn with no await. It then runs the Store transaction. If the transaction refuses or throws, the coordinator releases the reservation in the same turn. Two admissions therefore cannot both see the same free slot.

These guards enforce the first-reason precedence in "Rules for the running state", rule 2: once a first reason is recorded, only the matching terminal state is legal.

Every legal change increases the task's state version by one. Recording a first reason on a running row is also a durable change and increases it, so a poll can show "Stopping".

Launch: ending an attempt that has no handle

A pending attempt has no settled promise, so the slot rules need a separate release path for it. Between admission and launch, F may prepare resources such as the task clone and the prompt. The in-memory job tracks that preparation as its own promise, with the same ownership rules as an invocation:

• Preparation receives an AbortSignal from the job. Stopping a pending attempt aborts that signal with the first reason.
• Preparation files have a durable owner. The attempt ID is used as a directory name only after it passes the UUID check under "Terms used", so it cannot contain / or ... Before preparation creates anything, F uses the fixed attempt directory <runner root>/<runner owner token>/attempts/<attemptId>/, and passes it as the parent to the clone helper. The helper names its clone with mkdtemp, so the fixed parent is what makes the clone findable after a crash. Today's createTaskClone (git/clone.ts) runs git with synchronous execFileSync. It cannot be aborted and would block the event loop, so F1 cannot use it for preparation as it is. D, which owns git/clone.ts, must add an asynchronous variant that takes an AbortSignal, spawns git in its own process group, and exposes that group's ID (third prerequisite under "Shutdown").
• Preparation processes have a durable owner. Right after spawning a preparation child, in the same synchronous turn, F saves the process group ID and the child's start time on the attempt row (preparation_pgid, preparation_started_at). A process group outlives the runner if the runner crashes, so startup recovery uses these fields to stop it (step 4). To close the gap between spawn and that write, F first saves preparation_started_at with a null preparation_pgid (preparation starting), then spawns, then saves the group ID. If recovery finds an attempt that is marked as starting but has no group ID, a child may exist that nobody can identify. Recovery then fails closed: it does not open admission, it leaves that attempt directory in place, and the CLI names the attempt and its directory. The user must stop the unknown process and then confirm with --release-preparation <attemptId>. A quiet directory proves nothing, because a blocked process may resume later, so codeboost does not rely on it. Before removing anything, it checks that no process has a file open or a working directory inside the attempt directory, using lsof +D on macOS or /proc/*/fd and /proc/*/cwd on Linux. If a process is found, or the check cannot run, it refuses and keeps admission closed. The path comes only from IDs that are already saved, so a crash cannot leave an unknown path. The job removes the directory when the attempt ends. Startup recovery handles the rest (step 4).
• An AbortSignal does not stop a child process by itself. Every preparation subprocess (for example git clone) is started in its own process group, owned by the job. On abort, F sends SIGTERM to the group, waits a fixed grace period (5 seconds), then sends SIGKILL, and awaits the close event. Preparation settles only after that. A child that ignores SIGTERM is therefore still bounded by the kill. Preparation never leaves work running after it settles.
• Preparation counts against two limits, so it cannot hold a slot forever. The task budget is already running during preparation: the admission transaction of the task's first attempt moves the task to running and sets budget_deadline (see "Proposed storage additions"), before preparation starts. If the task time budget runs out first, the job records the first reason time-limit, then aborts the signal; the pending row ends cancelled and the task goes to needs human, as for a running attempt. If the attempt deadline passes first, the job aborts the signal with timeout and records no first reason; the row ends failed "Timed out while preparing".
• Shutdown aborts every preparation signal in step 4.

Case	What F does	When the slot is freed
Preparation fails before the D start call (for example the clone fails)	Preparation has already stopped its own subprocesses before rejecting (rule above). Remove only its host-side files (the attempt directory and clone). Write the terminal state from the first reason if one is recorded; otherwise write failed with the bounded preparation error.	After that terminal write succeeds
Stop or context change before the D start call	Record the first reason. Await the preparation promise and remove only its host-side files. Then write the terminal state (cancelled or stale).	After that terminal write succeeds
The D start call throws	Write the terminal state from the first reason if one is recorded (a stop can be recorded while preparation is finishing); otherwise write failed with the launch error. D4's adapters throw only after their setup cleanup has succeeded. If cleanup is still unfinished, they return a handle instead, which settles when cleanup ends. So nothing is left running.	After that terminal write succeeds
The D start call returns a handle	Write pending → running. From here the running-state rules apply, even if the handle comes from failed setup that is still cleaning up.	After settled resolves and the terminal write succeeds
The handle arrives, but pending → running is refused because a first reason is now recorded (a stop landed while preparation finished)	This is a normal stop, not a storage failure. Call handle.cancel(...) with the matching D reason, await settled, then write the terminal state from the first reason (pending → cancelled or stale).	After settled and that terminal write, as usual
The handle arrives but the pending → running write fails for any other reason (for example a storage error)	Keep the job with its handle, call handle.cancel('capture-failure'), and await settled. Then keep an unresolved marker for the task, because the row is still pending.	Only at startup recovery

Launch check. Immediately before the D start call, in one synchronous turn with no await between them, F reads the task and plan rows (the Store is synchronous) and confirms that the attempt is still pending, has no first reason, has a current captured context, and has time left. For the time check it reads the clock in the same turn: if the task budget is spent, it records time-limit and ends the row cancelled (the task goes to needs human); if the attempt deadline has passed, it ends the row failed "Timed out while preparing". In both cases D is not called. Only when every check passes does it call D's start, which is also synchronous. If the context is no longer current, F takes pending → stale without launching. A writable invocation therefore never starts against an old plan, snapshot, assignment or referenced code. The later publish check cannot undo filesystem changes.

Task storage is never removed before the terminal write, not even here. If preparation had already allocated task storage, it follows the holder order: terminal write → removeTaskFilesystems → free the slot. So a failed terminal write still leaves the storage recoverable.

In every case, a failed terminal write leaves an unresolved marker (see "Slots and concurrency", rule 5).

Launch setup must not block the server. The D4 adapters do their Docker setup synchronously inside the start call: createVendorNetwork, profile creation and startProfileInvocation use execFileSync and spawnSync (agents/network/network.ts, agents/container/). While that runs, the event loop cannot set closing, cancel the launch, or begin the HTTP drain. Prerequisite: D's start call must return its handle at once and do the Docker setup asynchronously inside that handle's lifecycle. Then cancel() works during setup, and settled resolves only after setup cleanup. It is listed with the other D prerequisites under "Shutdown".

Rule for D. D's start call must keep this shape: it either throws with nothing left running, or it returns a handle that settles only after everything it started has stopped. An adapter that needs an asynchronous start must still follow this rule. Changing it is a change to D's contract.

Rules for the running state

1. Stop requests do not end the attempt. A cancel, hard stop, shutdown, time limit or detected staleness sets the first reason on the in-memory job, writes it onto the row, and calls handle.cancel(...). The row stays running, and the UI shows "Stopping".

   The in-memory job is the source of the first reason until the terminal write. The terminal write stores the job's first reason and the terminal state together in one transaction. So if the earlier reason write fails, nothing is lost while the process lives, and the UI shows "Stopping (not saved yet)". If that terminal write also fails, the unresolved marker keeps the reason in memory. The one case that loses it is a crash after a failed reason write and before a successful terminal write. Startup recovery then records failed "Interrupted" and adds "a stop may have been requested" to the diagnostic. It cannot recover a reason that was never saved.

2. The terminal state comes from the first reason. When settled resolves, the terminal state is chosen in this order:

   First reason recorded by F	D result	Terminal state
   cancelled (user or hard stop)	any	cancelled
   shutdown	stopReason is timeout, output-limit or capture-failure	D's reason wins. D keeps the first reason it received, so a non-shutdown stopReason proves D stopped the attempt before the shutdown request reached it. The row ends failed with D's reason, and it is not requeued as a shutdown cancellation
   shutdown	any other	cancelled, with the reason "Stopped by shutdown"
   stale (context change)	any	stale, with the cause (for example "plan revision 4 replaced 3")
   time-limit	any	cancelled, reason "Task time limit reached"; the same transaction sets the task's status to needs human, but only if the task is not closed and cancel_requested is null. A pending cancel task wins: the same transaction closes the task as cancelled and inserts task-closed, and the time limit only supplies the attempt's diagnostic. A closed status never changes.
   none, and the captured context is not current	any	stale, with the cause. This row comes before every D stop reason, so a timeout that coincides with a context change always ends stale
   none	stopReason timeout	failed, reason "Timed out after n minutes"
   none	stopReason output-limit or capture-failure	failed, with D's bounded diagnostic
   none	exit 0 and output passes validation	completed (if the compare-and-swap succeeds)
   none	anything else	failed, with the bounded exit and stderr summary

3. F keeps its own reason. D's StopReason has no stale value. F passes cancelled to D for staleness, and keeps the real cause in its own first-reason field. No layer may replace an actionable reason with generic cancellation text.

4. Timeouts are D's job. F sets deadline in InvocationInput and does not run a second timer that settles early. F also enforces a whole-task time budget (default 2 hours). When the budget runs out, F follows rule 1: it records the first reason time-limit and calls handle.cancel('timeout'). The row stays running and the slot stays held. After settled resolves, one transaction writes terminal cancelled and sets the task to needs human. Startup recovery applies the same mapping, so a crash before settlement still ends in needs human, and the retry guard refuses it.

5. Late results lose. If the compare-and-swap for completed fails, the result is discarded and the row is settled by the table above. Discarded output still waits for settled before its slot is freed.

Exception for existing read-only lifecycles

E3 suggestions (requests table) write cancelled to disk when the stop is requested, before the provider settles. This is acceptable for read-only phases, because they share no writable folder with a later attempt and E3's coordinator still blocks a new start until the provider settles. New F records use the stricter rule above for every phase. The table under "Existing lifecycles" records how each one maps.

Slots and concurrency

1. A slot is taken at admission. For an attempt that got a handle, it is freed only in the finally step that runs after settled resolves. For an attempt that ended without a handle, it is freed by the "Launch" table above. In both cases the terminal write must have succeeded first. Cancel does not free a slot. Lease expiry and clock changes do not free a slot.
2. At most one non-terminal attempt exists per task.
3. codeboost 1.0 runs one task at a time. Writable attempts therefore share one global slot.
4. Existing limits stay: two question slots (runner/questions.ts); one suggestion request per plan identity (E3).
5. A slot is freed only after the terminal durable write succeeds. If settled has resolved but the write fails, or its outcome is unknown, the coordinator keeps an unresolved marker for that task in place of the job. The marker holds the slot and blocks admission and retry for the task. The UI shows "Needs restart: result could not be saved". Only startup recovery clears the marker, because it runs before admission and reconciles the durable row. The coordinator never removes a marker on its own.

Retry

A retry is a new attempt with a new attempt ID. The runner allows it only when all of these are true:

Check	Where it is checked
The last attempt for the task is failed or cancelled on disk, and the task's status is running or queued, and requeue_pending is false	Store transaction
No in-memory job and no unresolved marker exists for the task	Coordinator, synchronously before the transaction
The caller's expected state version and attempt ID match the task's current values	Store transaction (prevents a double retry from two tabs)
The last attempt's captured context is still current: snapshot ID, plan ID, plan revision, assignment ID, referenced-code hash and context generation (every field in "Current")	Store transaction
The coordinator is open	Coordinator

Closed and human-gated tasks are never retryable. If the task is closed (merged or cancelled) or waits for a person (needs human, needs amendment, needs approval, possibly already fixed), retry is refused. Leaving a human-gated status needs its own explicit user action, such as sending the task back with guidance or approving a continuation. That action belongs to F2 or lane I, not to retry. A closed task never reopens. The task time limit moves the task to needs human, so a timed-out task cannot be retried this way either.

A stale attempt can never be retried. The UI instead offers "Run again on the current code". That creates a new request, which captures a fresh context.

The server computes retryable and sends it to the UI. The UI never works it out itself.

Publishing a result

1. Wait for settled.

2. Validate the output (schema, size, file-scope audit for writable attempts). Do not await anything between the last check and the transaction.

3. If the job holds an in-memory first reason (its earlier write failed), skip publication: settle the row through the first-reason mapping in rule 2, passing that reason. Otherwise, in one Store transaction: confirm that the attempt ID is the task's current attempt, the state is running, there is no first reason, the captured context is still current, the task's status is running, and tasks.cancel_requested is null (the same guard as the running → completed row). Do not compare the task's state version here; the attempt's own transitions have increased it. Then write completed and the result, and increase the state version.

4. If step 3 refuses, reread durable state and settle the row by the rules above. Keep the original diagnostic.

5. For a completed writable attempt, F2's result extraction is split in two:

   • Step 2, before any Store write, makes the commit object inside the still-present task storage. It records nothing in the Store.
   • The step-3 transaction first runs every guard against the captured context. Then, in the same transaction, it writes completed and records the ledger entry (recordHistory), which increases the context generation. Because the guard runs before that increase inside one transaction, the attempt's own ledger write never makes it non-current.

   If step 3 refuses, nothing reaches the Store, and the unpublished commit is discarded when the task storage is removed. Then, for every writable attempt, call removeTaskFilesystems after the terminal write, whatever the outcome. Free the slot only after it succeeds. If it fails, keep an unresolved marker, and startup recovery removes the storage.

Irreversible actions. Before each commit, push, PR open or merge, re-read the task's state version, the plan's review_version (which saveReview and addReviewNote advance) and the coordinator's closing flag after the final await. Stop if any of them changed. For a merge this means an approval or choice edit made during the final GitHub check blocks the merge. A check made before an await does not count. (This follows the AGENTS.md rules on guarded external actions.)

Shutdown

web/server.ts close() and the runner coordinator follow this order. Part of step 1 and all of steps 2 and 3 already exist. F1 adds the coordinator barrier in step 1, steps 4 and 5, and step 8.

Step	Action	Existing?
1	Set stopping on the server and closing on every coordinator (runner, questions, suggestions, merge), in the same synchronous turn, before any active-work list is copied. New API requests get HTTP 503. Every coordinator's start method checks closing synchronously and throws, so a request admitted before shutdown cannot start new work after it.	server flag: yes. Coordinator barrier: new. Today close() sets only stopping, and questions.close() runs later, so a request that was still reading its body can call questions.start() after shutdown began. The server also rechecks stopping after reading a body only for merge, so service.act, setQuestionProvider and future planning writers can still change the Store. F1 adds a stopping check after the body is read and before every mutating dispatch, returning HTTP 503, and adds regressions for each writer. Two GET handlers also write: /api/review (ReviewService.load() calls recordHistory when HEAD moved) and /api/merge (queue polling records merge observations and outcomes). /api/review can also write after an await: merges.displayStatus() checks GitHub and can then record a direct merge (finishMergeAttempt, runner/merge.ts). Per-handler checks would miss paths like this, so F1 adds a write gate on the Store. Step 1 closes the gate in the same synchronous turn. After that, every Store write method throws "Shutting down" unless the caller passes the shutdown capability. The server hands that capability at construction to each coordinator's own settlement and close() code: the runner, questions (finishAnswer after abort), suggestions (settleSuggestion in E3's close()) and merge. Startup recovery holds it too. HTTP handlers and ReviewService never receive it. So after step 1, only work that is settling can write, and it can still record its terminal rows before step 7 closes the Store. The gate throws a distinct ShuttingDownError, which the server maps to HTTP 503 "The review server is shutting down.", never to the 409 used for review errors. So an admitted /api/review whose load() reaches recordHistory after step 1 returns 503 with no view, and the UI treats it like any other 503 during shutdown. There is no partial or read-only view. Merge reconciliation and queue polling hit the same gate. Today both catch every error and turn it into a status (displayStatus() and #pollQueue() in runner/merge.ts), which would swallow the gate error and answer HTTP 200. F1 changes each of these catch blocks to rethrow ShuttingDownError first, before any other handling, so these paths also end with 503. The next startup checks GitHub again, so a skipped merge observation is recovered, not lost. Regressions cover /api/review history, /api/review direct-merge reconciliation during the GitHub await, and /api/merge polling.
2	Stop accepting connections, and wait for admitted requests up to the drain limit (at most 14.5 s, below the 15 s request timeout).	yes
3	After the drain limit, abort the signals of the remaining requests, destroy requests that are still reading a body, then await request-owned work (the merge coordinator).	yes
4	For every pending and running attempt that has an in-memory job, record the first reason shutdown only if no first reason is set yet. A job already marked cancelled, stale or time-limit keeps its reason. For running, call cancel('shutdown') and await settled. For pending, await its preparation promise (and the D start call if it is in progress), remove only its host-side preparation files (task storage waits for the terminal write, as in step 5), and cancel any handle that start returned, then await its settled (the "Launch" table). F does not abandon a job after a timer (decision 4). This is not yet guaranteed to end: D4's supervisor escalates to a forced kill, but it retries unfinished container, network or setup cleanup every second with no limit (agents/adapters/supervisor.ts). If Docker is unreachable, settled never resolves and shutdown waits with the Store open. See the prerequisite below.	new
5	For each attempt from step 4, in the order set by the task-storage holder row: the partial-output export (writable attempts), then the terminal state from its first reason (a shutdown reason gives cancelled "Stopped by shutdown") with its diagnostic_ref, then removeTaskFilesystems, and only then free its slot. A failed write leaves the row non-terminal, and a failed removal keeps the slot held. Startup recovery handles both.	new
6	Await server closure; await the question and suggestion coordinators' close().	yes (questions); suggestions: new wiring
7	Close the Store.	yes
8	Release the single-runner lock (decision 1). Release it on every exit path after it was taken, including a startup failure.	new

Partial output and interrupted rebases. The design requires a hard stop to keep partial output for diagnosis, and to cancel an interrupted rebase before the workspace is rebuilt.

Holder	Owner	Rule
Partial output of a stopped writable attempt	F, using a new D export	The task filesystems are Docker volumes behind a keeper container. F allocates them with prepareTaskFilesystems and removes them with removeTaskFilesystems; D's supervisor does not remove them at settlement. But F cannot read a volume from the host. So the order is: settled → a D-provided bounded export (a new D operation, for example exportTaskDiff(filesystems, maxBytes), which runs git diff against the last codeboost commit in a read-only container and returns at most 1 MiB) → F saves it → the terminal write stores diagnostic_ref → removeTaskFilesystems → the slot is freed. The export has an overall deadline (60 seconds, passed to D as an AbortSignal), because maxBytes bounds only the returned data, not the Docker work. On timeout or any export failure, F records "Partial output could not be exported: " as the diagnostic and continues with the terminal write and removal; shutdown and recovery never wait on an export past its deadline. F saves the export to a runner-owned diagnostics directory, with a total byte cap. Retention never deletes a file an attempt row still references. When the cap is exceeded, retention first deletes unreferenced files, oldest first. If that is not enough, it takes the oldest referenced file and, in one transaction, sets that row's diagnostic_ref to null and appends "(partial output removed by retention)" to its diagnostic. Only after that commit does it delete the file. No row is ever left pointing at a missing file. The attempt row references it as diagnostic_ref. If the capture fails, the row records that it failed. The task filesystem is never reused.
Interrupted rebase	F3	F3 records rebase in progress durably before starting a rebase and clears it after. It is stored as tasks.rebase_in_progress: null, or JSON { attemptId, oldHead, onto, startedAt }. F3 sets it by compare-and-swap from null, and clears it by compare-and-swap on the same attemptId. Startup recovery aborts every recorded rebase through the runner before it hands the task to I3.
Workspace rebuild	I3	I3 never rebuilds before both rows above are resolved for the task.

Process shutdown is a hard stop. When the process stops, the running task does not finish. Its attempt ends cancelled with the reason "Stopped by shutdown". Restart recovery (lane I3) puts the task back in the queue. This is different from "Stop the queue" (lane I), which lets the running task finish.

First prerequisite before F1 merges: settlement ends. Settlement must be proven to end. D5, or a D follow-up, must either bound cleanup retries and settle with a terminal cleanup-failure result, or show in the real-Docker suite that every cleanup path ends, including when the Docker daemon is unreachable. Until one of these lands, decision 4 stays conditional, and the F1 implementation PR must not merge. F1 does not add its own timer to work around this.

Second prerequisite before F1 merges: a D recovery API scoped to one database. Decision 1 allows one runner per database, so several databases can have live runners on the same machine at once. Recovery must therefore never touch another database's resources. D's current labels (io.codeboost.invocation, io.codeboost.task-storage, io.codeboost.allocation, io.codeboost.egress) do not say which database owns a resource, so they are not enough.

Part	Owner	Rule
Runner owner token	F	A random ID of exactly 32 lowercase hexadecimal characters (^[0-9a-f]{32}$), stored in the database (app_settings). A stored value that does not match is refused before it is used as a label or in any path, and startup exits. It is stored together with the database file's device and inode numbers. It is read, or created, in startup recovery step 2, after the lock is taken and the Store is opened. If the stored device and inode don't match the open file (the database was copied), F creates a new token. So a copy never shares a token with its original.
Token in every request	D contract	InvocationInput gains a runnerOwner field, and so does every allocator that runs before an invocation exists: prepareTaskFilesystems (which today takes no owner, agents/container/storage.ts) and vendor network creation. Every resource D creates carries the label io.codeboost.runner=<token>: containers, networks, egress proxies, task-storage volumes and allocations.
Recovered storage handles	D	D tracks task-storage ownership in a process-local WeakMap, which is empty after a restart. So recoverLeftovers returns, for each kept volume set, an authenticated recovery handle that D registers in its ownership map after checking the volumes' runner and allocation labels. Binding to an attempt: task-storage volumes also carry io.codeboost.attempt=<attemptId>, set by prepareTaskFilesystems from a new attemptId parameter. F chooses the allocation ID, not D. F generates it (a lowercase UUID v4) and saves it as attempts.allocation_id before it starts the asynchronous allocation, then passes it to prepareTaskFilesystems, which labels the volumes and keeper with it (io.codeboost.allocation). So a crash in the middle of allocation still leaves a row that matches whatever D created. The D prerequisite includes accepting a caller-provided allocation ID. The handle carries both IDs. F uses a handle only if its attempt ID and allocation ID both match one attempt row of this database. A handle that matches no row, or disagrees with the row, is reported and listed by --list-unowned-agent-resources for the user to remove by hand; it is never exported or removed automatically. exportTaskDiff and removeTaskFilesystems accept these handles. F never builds a TaskFilesystems value from report fields.
Scoped recovery	D	recoverLeftovers(runnerOwner): Promise<RecoveryReport> acts only on resources whose io.codeboost.runner label equals the token. It stops and removes agent containers, egress proxies and networks, and resolves only when they are gone. It keeps task storage whole: the volumes and their keeper container, which it recognises by its task-storage labels. The recovery handle depends on that keeper and lists them in the report by allocation, so F can export partial output first. F then calls removeTaskFilesystems for each one (startup recovery step 4). It rejects with a bounded diagnostic if anything cannot be stopped or removed.
Unowned resources	D and F	Resources with codeboost labels but no io.codeboost.runner label (from builds before this change) fail closed. The report lists them, and F refuses to open admission while any exist. codeboost never removes them itself, because it cannot prove that no older-build runner is alive: older builds take no lock this build can see, and an idle older runner may have no container running at the moment of a check. So --list-unowned-agent-resources prints each resource and the exact docker rm / docker network rm / docker volume rm commands. The user stops every older codeboost process, runs those commands, and starts again. There is no machine-wide lock.
When it runs	F	Only while holding this database's single-runner lock (startup recovery step 1 comes first).

This belongs to D (D5 or a D follow-up), not F. It changes agents/contract.ts, so it goes through D's contract tests.

Also before F1 merges: asynchronous launch. D's start call must return a handle immediately and run its Docker setup asynchronously and abortably (see "Launch setup must not block the server").

Third prerequisite before F1 merges: abortable preparation helpers. Both preparation helpers are synchronous today. createTaskClone runs git with execFileSync, and prepareTaskFilesystems runs docker with execFileSync and spawnSync (agents/container/storage.ts). Either would block the event loop, and cancel or shutdown could not abort it. D must add asynchronous variants of both that take an AbortSignal, spawn their subprocesses in their own process group, expose the group ID, and settle only after those processes have exited. Storage allocation must also label its volumes with the runner owner and attempt ID before it returns (see "Recovered storage handles"), so that storage allocated just before a crash is found by recovery.

Prerequisite before F2's writable attempts: a bounded task-volume export. D must add a bounded diff export over the task volumes (see "Partial output and interrupted rebases"). F1 does not need it: F1 runs only read-only attempts, and their task storage is removed without an export.

A second Ctrl+C does not skip steps 4 to 8. The CLI prints "Still stopping agents…" and keeps waiting.

Startup recovery

This runs before the coordinator opens.

1. Take the single-runner lock for this database (decision 1), before opening the Store, because opening runs migrations. If another process holds it, exit with "Another codeboost runner is using this database." The OS lock cannot name the holder, so the message does not claim to. Do not serve the review screen: it is not read-only, because ReviewService.load() records history when HEAD moves (runner/review.ts) and act() writes review actions. A true read-only mode would need Store-level write refusal and is out of scope for F1.
2. After the lock, in this exact order:
   • 2a. Open the Store. Migrations run here, under the lock. Read the runner owner token, or create it (see the table under "Shutdown").
   • 2b. Stop leftover preparation. For every attempt row with a saved preparation_pgid: if a process group with that ID and start time is still alive, send SIGTERM, then SIGKILL after the grace period, and wait until it has exited. A crashed clone or storage allocator could otherwise still be creating or writing resources while D's recovery scans them, or while F exports and removes them.
   • 2c. Call D's startup recovery with the token, and await it.
   • 2d. If D's recovery rejects, startup stops here, before step 3 finalizes any row or step 6 hands anything to I3: close the Store, release the lock, and exit with D's diagnostic. The next start retries.
3. Export phase, outside any transaction. Every attempt kind gets task storage from D, including read-only ones, so recovery can find handles for any kind. Export only for writable attempts (execute, fix, rebase-fix) whose row is not completed. The partial-output rule applies only to stopped writable attempts. For each matching handle, run the bounded partial-output export. Write it to the diagnostics directory under the fixed name <attemptId>.diff, so a retry overwrites instead of duplicating. Each export has the same 60-second deadline as above; a timeout counts as an export failure. An export failure is kept in memory as that attempt's diagnostic ("Partial output could not be exported: …"), with no file. This phase makes no database writes. Before F2 there are no writable attempts, so this phase exports nothing, but read-only attempts can still leave handles to remove in step 4. Then finalize the unclean leftovers. These are pending or running rows left by a crash, or by a shutdown whose terminal write failed. Finalization phase: one transaction that only finalizes rows and stores each diagnostic_ref (or the export-failure diagnostic). It does no D or file work. If it fails, for example because of a storage error, startup stops there: it does not run step 4, does not open admission, closes the Store, releases the lock, and exits with the error. The next start runs recovery again from step 1, and its export phase rewrites the same fixed-name files. A diagnostics file whose attempt row never got a diagnostic_ref is removed by the diagnostics directory's normal retention. Finalize each one, storing its diagnostic_ref from the export in the same transaction, using the first-reason table in "Rules for the running state", rule 2:
   • first reason cancelled → cancelled; stale → stale with its cause;
   • first reason shutdown: if the row has a saved D stop_reason of timeout, output-limit or capture-failure, D's reason wins → failed, as at settlement. Otherwise → cancelled "Stopped by shutdown". Limit: D's InvocationHandle reports its stop reason only in the settled result, and F saves it only with the terminal write. If the process dies after D stopped for its own reason but before settlement, D's reason is lost with the process. Recovery then cannot see it and maps the row to a shutdown cancellation, which is requeued. The next attempt has its own deadline, so a lost timeout costs one bounded re-run, not an unbounded one. Keeping D's reason across a crash would need D to report it before settlement; that is not a prerequisite;
   • no first reason, and the captured context is no longer current → stale with its cause (the change happened, but the runner died before it recorded the reason). This is checked first, before both deadline fallbacks below, matching the settlement precedence;
   • no first reason, context current, and the task's budget_deadline has passed → the time-limit mapping (task needs human);
   • no first reason, context current, and the attempt's deadline has passed → failed "Timed out", not requeued;
   • no first reason and the context still current → failed "Interrupted: codeboost stopped while this was running".
   • first reason time-limit → cancelled, and in the same finalization transaction the task goes to needs human only if it is not closed and cancel_requested is null. A pending cancel task wins and closes the task as cancelled with its task-closed event, exactly as at settlement (rule 2).
4. Clear every unresolved marker (these exist only in memory, so a restart has already cleared them; step 3 reconciles their rows). Abort every recorded interrupted rebase (F3). For every task-storage handle D's recovery returned that matches an attempt row, whether or not step 3 exported it, call removeTaskFilesystems. Step 3's transaction already stored the diagnostic_ref of each exported one. The coordinator does not open (step 8) until every removal has succeeded. Then (preparation groups were already stopped in step 2b), for every directory under <runner root>/<runner owner token>/attempts/ whose attempt is not marked as starting with a null group ID (step 7) (all attempts are terminal after step 3): check ownership (a real directory on the same device, not a symlink, named by a known attempt ID of this database), save a bounded partial-output diagnostic as for a hard stop, and remove it. Unknown entries are reported and left alone.
5. Insert any missing task-closed events. This applies only to tasks with a confirmed merged merge attempt (feedback-event rule 2). An attempt's terminal state never closes a task: a cancelled or failed attempt means only that the attempt ended. Cancel attempt (stop the current run; the task stays open) and cancel task (close the task and discard its workspace) are different user actions. Only cancel task closes a task. If a runner attempt is pending or running, cancel task does not close the task at once. It records the first reason cancelled on that attempt, and in the same transaction it sets tasks.cancel_requested to its actionId. The response says "Stopping, then cancelling". When that attempt settles, one transaction writes the attempt's terminal state, sets the task to cancelled and inserts task-closed. Only after that does F discard the workspace. With no active attempt, cancel task closes the task and writes task-closed in one local transaction. Either way it never needs reconciliation. Startup recovery finishes a pending cancel_requested in the same way after step 3. Cancel task is refused while a merge attempt is submitting or queued, including when its outcome is unclear. GitHub may still merge, and a closed task can never change to merged. The user can cancel the task after the merge coordinator records merged, removed or failed. If the result is merged, the task closes as merged instead. "Reject with feedback" never closes a task (see the status list).
6. Requeue input. Hand lane I3 every task whose status is not closed (merged or cancelled) and not human-gated, and whose latest attempt is either (a) cancelled with first reason shutdown, whether written by clean shutdown or by step 3, or (b) failed "Interrupted" by step 3. Attempts that end cancelled by the user or stale are not requeued; they wait for a user action. I3 rebuilds the workspace and requeues. F1 only makes the attempt rows terminal and produces this list. Requeue claim: the same transaction as step 3 sets tasks.requeue_pending = true for each listed task. While it is set, retry and every other admission for that task are refused, so recovery and a user retry cannot both start work on it. Exactly one path clears it, by an atomic compare-and-swap from true to false in the same transaction that admits the next attempt: I3's requeue, or, until lane I exists, the user's explicit "Resume" action (a user_actions row). The loser of that compare-and-swap is refused.
7. Unowned preparation check. If any attempt has preparation_started_at set and preparation_pgid null (see "Launch"), stop here: do not open the coordinator, name each attempt and directory, and wait for --release-preparation. Step 4 does not remove those directories.
8. Open the coordinator.

HTTP and UI contract

Status reads. GET /api/runner returns only the task and attempt rows plus stateVersion, retryable, unresolved and stopRequested. stopRequested comes from the in-memory job: null, or { attemptId, reason, saved }, where saved is false while the first-reason write has failed. The UI shows "Stopping (not saved yet)" only from this field. It does not change stateVersion, so user actions still compare against the durable state version. unresolved is computed by the server from the in-memory marker: null, or { attemptId, reason: "result-not-saved" | "start-not-saved" }. The UI shows "Needs restart: result could not be saved" only from this field, because the durable row alone may still look active. It does not rebuild Git history or the full review.

User actions. Cancel, retry and "run again" requests send attemptId, expectedStateVersion and an actionId idempotency key (see "Feedback-event contract"). A replayed actionId returns the saved outcome. The server takes the plan identity from its trusted configuration, never from the request, and every Store call is scoped by that identity. A mismatch returns HTTP 409 with the current state. The UI then shows that state and keeps any draft.

UI rules (from AGENTS.md "Async review UI"):

Rule	How
An old poll cannot overwrite newer state	Apply a response only if its stateVersion is at least the one already shown, and only if it answers the newest request.
Stale results stay visible	Show terminal stale attempts with their cause. Do not hide them.
Drafts survive	A response never clears the feedback composer. It clears it only if the current text and attachment still equal what was sent.
Polling backs off	Back off to a capped interval. Reset only on a lifecycle change or a user action.
Selection is announced	The selected task or attempt row uses aria-current.

Planning API for lane G

Every POST below follows the user-action protocol in "Feedback-event contract": it carries an actionId, and a replay returns the saved response.

F1 owns the production planning endpoints that G4 needs. They wrap E3's coordinator and the existing Store methods. They do not add a second writer.

Endpoint	Store or coordinator call	Guard
POST /api/plan/import	Store.importRevision	expected revision
POST /api/plan/suggestions	E3 coordinator start (beginSuggestions)	expected revision and snapshot
GET /api/plan/suggestions/:id	Store.getSuggestions	reads only the request row
POST /api/plan/suggestions/:id/cancel	pending: handle.cancel(reason) on the SuggestionHandle that SuggestionCoordinator.start() returned. E3's coordinator has no cancel-by-ID method, so F keeps a map from request ID to handle, adds each handle when it starts the request, and removes it only after the handle's outcome settles. If the request is pending but F holds no handle (for example after a restart), F calls Store.cancelSuggestions. It is safe to do so because startup recovery has already stopped the crashed process's provider. A live planning provider runs only through D (G4 after D5), in a container labelled with this database's runner owner, and D's recoverLeftovers (startup step 2) stops it before admission opens. Until D5 there is no live planning provider at all ("Planning agent not available yet"). If a planning provider ever runs outside D, this endpoint must refuse such a request instead, until startup has reconciled it. ready: Store.cancelSuggestions (dismiss), because no invocation is running.	request is pending or ready, as Store.cancelSuggestions already allows
POST /api/plan/suggestions/:id/apply	Store.applySuggestion	request ready and bound to the current revision and snapshot

Live planning invocation waits for D5. Until then, the server returns "Planning agent not available yet" instead of using a fake provider.

Feedback-event contract (for lane J)

What becomes an event. Only feedback the user wrote or chose. Issue text, issue comments and agent output never become events.

actionId identifies the one user action (or confirmed external outcome) that caused the event. For user actions it is an idempotency key the UI generates (a UUID) when the user acts. The server validates it before opening any transaction: it must be a lowercase UUID v4 (the same regular expression as attempt IDs, 36 characters), or the request is refused with HTTP 400 and nothing is stored. The UI generates it and resends unchanged if it retries after a lost response. Every writing user action goes through one user_actions table, keyed by (planKey, actionId). That covers notes, choice changes, finding acceptance, rejection, cancel, retry, "run again", starting a merge, and every planning endpoint that writes: plan import, suggestion start, suggestion cancel and suggestion apply. Each planning request carries an actionId; its user_actions row is inserted in the same transaction as the Store call it wraps, and the saved response includes the request ID or plan revision it produced. For a merge, the user_actions row is inserted in the same transaction as beginMergeAttempt, and it saves the merge attempt ID with the response "in progress". When the merge coordinator records the outcome, the same transaction updates that saved response. A replayed merge click therefore returns the same attempt's current outcome and never starts a second attempt. The row holds the action kind, a hash of the request body and the bounded response. The first definite outcome is recorded, including a refusal. If the action applies, its row is inserted in the same transaction. If a guard refuses it (for example HTTP 409 for a stale state version), the refusal and its response are recorded in their own transaction. Only outcomes that applied nothing for a passing reason are not recorded, so the UI may resend them: HTTP 503 during shutdown, and a storage error. A replay is handled before any other guard:

• the same actionId with the same request hash returns the saved response and applies nothing, even though the state version has since moved on;
• the same actionId with a different request hash (including a different action kind) is refused with HTTP 409 "Action ID already used" and applies nothing.

So neither an action nor its events can be duplicated, including a retry that would otherwise admit a second attempt. For a merge task-closed it is the merge attempt ID. A later change to the same source is a new user action with a new actionId.

Which actions produce feedback. This list is complete; the event kinds are in the table below.

Action	Event
Reject with feedback	reject
Change note on a plan item	change-request
Accept a segment	segment-accept
Assign a segment	segment-assign
Accept an open problem	finding-accept
Guidance when sending a needs-human task back	needs-human-guidance
Cancel task	task-closed (at close, which may come after the attempt settles)
Confirmed merge (external outcome, not a user action)	task-closed

Every other writing action is idempotency-only: it has a user_actions row and produces no event. That covers cancel attempt, retry, "run again", settings changes, questions, merge initiation (its event waits for the confirmed outcome), plan import, and suggestion start, cancel and apply.

Event kind	Source action	sourceRef
reject	"Reject with feedback"	the rejection's note IDs
change-request	A change note on a plan item	note ID
segment-accept	Accepting an Ambiguous or Unplanned segment	choice key
segment-assign	Assigning a segment to a plan item	choice key
finding-accept	Marking an open problem "accepted"	finding ID
needs-human-guidance	Guidance added when sending a needs-human task back	note ID
task-closed	Confirmed merge, or the user's cancel task	plan key

Fields: id, planKey (the task's full identity), actionId, planRevision, snapshotId, item (or null), kind, text (user text only, 4000 characters or fewer, or null), sourceRef, supersedes (or null), createdAt.

Rules:

1. Local actions. For each feedback-producing action, write its event in the same Store transaction as the action. There is never an event without its action, or a feedback-producing action without its event.
2. External actions. A GitHub merge cannot share a SQLite transaction. For a merge, one transaction records the confirmed outcome (finishMergeAttempt with state merged), sets tasks.status to merged, and inserts task-closed. Never write any of them when the merge is submitted, queued or ambiguous. Startup recovery also runs a reconciliation step: for every task with a confirmed merged merge attempt whose status or event is missing, one transaction sets the status and inserts the event. The uniqueness rule below makes this safe to repeat.
3. Events are append-only. If a choice changes later, write a new event with supersedes set to the earlier event. J uses the newest event for each sourceRef.
4. Replaying the same action or reconciliation does not duplicate an event: (planKey, kind, actionId) is unique. Each action produces at most one event, and it is applied only once, because user_actions holds one row per (planKey, actionId). A superseding event for the same sourceRef has a new actionId, so it is never rejected. Note and choice IDs are only unique inside their plan identity, so the key must include the full plan key.
5. J reads events only through Store.feedbackEvents(identity: PlanIdentity), which scopes every row by identityKey(identity), and only after that task's task-closed event exists.

Proposed storage additions

This is the smallest schema that holds the contract. The F1 implementation PR sets the final column names. The migration increases user_version from 5 to 6.

Backfill in the same migration transaction. Every existing plans row gets one tasks row:

Column	Initial value
status	merged if its latest merge attempt is merged; otherwise in review (v5 data only comes from the review screen)
state_version, context_generation	0
assignment_id	unassigned, the value F uses until F2 assigns work
referenced_code_hash	the head SHA of the plan's current snapshot, or none if it has no snapshot
current_attempt_id	null (v5 has no attempt rows)
requeue_pending	false
cancel_requested	null
rebase_in_progress	null
budget_deadline	null. The budget has not started; it starts on the task's first move to running. Every deadline check treats null as "not started", never as expired.
created_at, updated_at	the migration time

A merged v5 task also gets its task-closed event, keyed by the merge attempt ID. A test migrates a v5 fixture with an open and a merged plan, checks every column of both rows, and then checks that retry, recovery and the time-limit check treat the migrated open task as not expired and not requeue-pending.

Table	Key columns
tasks	plan_key (primary key, references plans(key)), status, requeue_pending (boolean), rebase_in_progress (JSON or null; see "Partial output and interrupted rebases"), budget_deadline (absolute time the task budget ends; null until the budget starts: the admission transaction of the task's first attempt moves the task to running and sets it to that time plus the configured budget, so the budget covers preparation), cancel_requested (action ID or null), state_version, context_generation, assignment_id, referenced_code_hash, current_attempt_id (nullable; the composite foreign key (plan_key, current_attempt_id) references attempts(plan_key, id), so a task can only point at its own attempt), created_at, updated_at
attempts	id (primary key; never reused), deadline (the attempt's absolute deadline, saved at admission), plan_key (references tasks(plan_key); (plan_key, id) is also unique, for the composite key), kind, phase, item, state, context (JSON), first_reason, stop_reason, exit_code, signal, result (JSON, only for completed, 1 MiB or less), diagnostic (bounded), diagnostic_ref (partial-output file, or null), preparation_pgid and preparation_started_at (or null), allocation_id (task storage, or null), created_at, started_at, settled_at
user_actions	plan_key, action_id (together the primary key), kind, request_hash, response (JSON, bounded), created_at
feedback_events	the fields listed above, with id as primary key, with a unique index on (plan_key, kind, action_id)

tasks.status holds the product states from the design (queued, running, needs human, needs amendment, needs approval, possibly already fixed, in review, approved but merge blocked, merged, cancelled). Closed means merged or cancelled (by the user's cancel task); a closed status never changes again. Reject with feedback is not a closed status. Following the design's step 8, it creates the next plan revision, marks the affected items to run again, and moves the task from in review to queued, in one transaction with its reject event. The design's learning section (L1) agrees: a task closes only when it is merged or cancelled, and reject rounds stay with the task. J therefore distills a task's feedback, including every reject round, when it closes by merge or cancel. Human-gated means needs human, needs amendment, needs approval or possibly already fixed. F1 defines the list and its invariants. F2 adds the per-item transitions. I1 adds queue admission and scheduling.

Where the current context lives. The Current check reads two rows in one transaction: plans (plan revision, snapshot ID) and tasks (assignment ID, referenced-code hash, context generation). The plan ID comes from the plan key. Every Store method that changes any of these fields increases tasks.context_generation in the same transaction. That covers importRevision, applySuggestion, recordHistory, recordRebase, and any new method that reassigns work or changes the referenced code. A regression test lists these methods and fails if one of them changes a context field without increasing the generation. An assignment change that keeps the same plan revision and snapshot therefore still makes old attempts non-current.

Where results live. attempts.result holds the validated structured result of a completed attempt: for example review findings, a question answer or check outcomes. It is limited to 1 MiB, the same as the plan-document limit after extraction. Larger or already-owned artifacts stay with their existing owners, and result references them by ID. Commits go in the ledger and snapshots (recordHistory), and continuation evidence goes in checkpoints. Raw stdout and stderr are never kept beyond the bounded diagnostic.

Existing lifecycles and how they map

Lifecycle	Current states	Maps to	Gap and owner
Questions (runner/questions.ts, QuestionAnswer)	pending, complete, failed; 125 s persisted lease	running, completed, failed	No durable cancelled or stale; stale is only worked out when the screen renders. The lease allows a second process to start after 125 s. Fixed when F moves Ask onto D's contract after D5.
Suggestions (E3, requests)	pending, ready, consumed, failed, cancelled, invalidated	running, completed, completed (applied), failed, cancelled, stale	Durable cancelled before settlement (allowed for read-only phases; see the exception above). No change.
Merge attempts (C and K, merge_attempts)	submitting, queued, merged, removed, failed	running, running (external), completed, and removed/failed as terminal failures for display only	Excluded from F's generic retry and state machine. Merge attempts keep their own states and guards in MergeCoordinator, including requiresFreshReview after removed. F's retry rule never applies to them, and the mapping is only for the shared UI vocabulary. When the outcome is unclear, ownership is kept, as AGENTS.md requires. F6 integrates.

Required race regressions for the F1 implementation

Each case needs a test that fails before the fix and passes after it. Each test checks both the returned or visible result and the durable row. Use controllable promises, clocks and a fake InvocationHandle with real SQLite.

AGENTS.md case	F1 test
Old poll returns after a user action	Poll starts → user cancels → old poll response has a lower stateVersion → UI keeps "Stopping"
Lease expires while the original still runs	Move the clock past any persisted time → retry is refused while settled is unresolved
Timeout, then the provider stays unsettled, then retry	D reports timeout but settled is held → retry refused → release → row failed with the timeout reason → retry allowed
Shutdown, then a new request	closing set → admission throws; HTTP returns 503
Partially received request, then shutdown	Body half-sent → shutdown → request destroyed after the drain limit → no attempt row created
Abort, then subprocess close arrives later	cancel → slot still held → settled resolves → slot freed → row cancelled with the first reason
Submit, then the user edits, then the response returns	Feedback submitted → user types more → response arrives → draft kept
Code reassigned or snapshot changed, then retry or render	Snapshot advances during a run → result discarded → row stale with the cause → retry disabled; "run again" allowed
Terminal write fails after settlement (review finding)	settled resolves → the terminal write throws → slot and unresolved marker remain → retry and admission refused → restart recovery makes the row terminal
Request admitted, then shutdown, then the request tries to start work (review finding)	Question body half-sent → shutdown sets closing → body completes → questions.start() throws → no answer attempt is saved
Merge confirmed, then the event write is lost (review finding)	merged recorded without task-closed → restart → reconciliation inserts exactly one event → a second restart inserts none
Attempt's own transitions, then publish (review round 2)	Admit → pending → running (the state version rises each time) → with no context change, a valid result publishes completed; the context generation is unchanged
Two admissions race for one slot (review round 2)	Two admissions in the same tick for different tasks with one free slot → exactly one reserves and saves pending; a refused Store transaction releases its reservation
Second process starts (review round 2)	Runner A holds the lock → process B exits before opening the Store; no migration or history write occurs
Two plans emit the same source ID (review round 2)	Two plan identities with the same taskId in different repositories both record task-closed at revision 1 → both events are saved, and feedbackEvents for each identity returns only its own
Stop before launch, and launch error (review round 3)	(a) Stop while the clone is being prepared → preparation settles and is removed → row cancelled → slot freed → next task admitted. (b) D start throws → row failed with the launch error → slot freed. (c) The pending → running write fails → slot and marker remain until restart
First reason wins at settlement (review round 5)	(a) User cancels → provider then exits with an error → row cancelled, not failed. (b) User cancels → plan revision changes → row cancelled, not stale
Shutdown during preparation (review round 5)	Attempt pending while its clone is prepared → shutdown → preparation awaited and removed → row cancelled "Stopped by shutdown" → Store closes → restart lists the task for requeue and writes no task-closed
Choice changed twice at one revision (review round 5)	Assign segment to P1 → reassign to P2 at the same revision → two events saved, the second supersedes the first; replaying the second request adds none
Preparation hangs, then cancel (review round 6)	Clone preparation blocks → user cancels → the signal aborts and the clone subprocess is awaited → row cancelled → slot freed
Crash with a recorded first reason (review round 6)	User cancels (first reason saved) → process killed before settlement → restart → row cancelled, not failed, and not requeued
Clean stop, then restart (review round 6)	Shutdown completes → the lock connection is closed and the OS lock released; the lock file is still there → a new process takes the lock and starts
Preparation fails (review round 7)	Clone fails before the D start call → partial clone removed → row failed with the clone error → slot freed
Retry a closed or gated task (review round 7)	Task cancelled by cancel task (or needs human after the time limit) with a cancelled last attempt → retry refused; restart does not requeue it
Assignment changes alone (review round 7)	Work reassigned without a plan-revision or snapshot change → generation increases in the same transaction → the old attempt's result is refused and the row becomes stale
Two databases, one crashes (review round 8)	Runners for databases A and B are live → A crashes and restarts → recovery removes only resources labelled with A's token; B's container, network, egress proxy and volume keep running
Context changes during preparation (review round 9)	Admit a writable attempt → assignment changes while the clone is prepared → launch check fails → row stale; D start is never called
Stop during launch, then the start throws (review round 9)	User cancels while preparation finishes → D start throws → row cancelled, not failed
Reason write fails (review round 9)	The first-reason write throws → settlement → the terminal write stores cancelled with the reason from memory
Time limit, then crash (review round 9)	time-limit saved → process killed → restart → row cancelled, task needs human, retry refused
Admitted write after shutdown (review round 9)	For each of act, setQuestionProvider and the planning writers: body half-sent → shutdown → body completes → HTTP 503 and no Store change
Stale, then shutdown (review round 9)	Attempt marked stale → shutdown → row stale, not requeued
Copied database (review round 9)	Copy the database file → start the copy → new token; recovery for the copy leaves the original's resources alone
Review edit during the final merge check (review round 10)	Merge passes its GitHub checks → approval changed before the final re-read → merge refused
Writing GET after shutdown (review round 10)	/api/review with a moved HEAD, and /api/merge with a queue result, both admitted → shutdown → neither writes to the Store
Legacy resource present (review round 10)	An agent container without a runner label exists → startup refuses admission and lists it
Lost response, then replay (review round 10)	Add a note → the transaction commits → the response is lost → resend with the same actionId → one note, one event, same response
v5 upgrade (review round 10)	Migrate a v5 database with an open and a merged plan → two task rows with the backfill values; the merged one has one task-closed
Path alias (review round 10)	Start through a symlinked parent directory while a runner holds the lock through the real path → the second start exits
Unresolved marker is visible (review round 10)	Terminal write fails → GET /api/runner returns unresolved → the UI shows the restart message
Lost retry response, then replay (review round 11)	Retry commits a new attempt → the response is lost → resend with the same actionId → the saved response comes back, and there is no second attempt and no 409
Action ID reused for another action (review round 11)	Send a note with actionId X → send a reject with X → HTTP 409, nothing applied
Task budget runs out during preparation (review round 12)	Budget ends while the clone is prepared → time-limit recorded → preparation aborted → row cancelled, task needs human, retry refused
Deadline already passed at launch (review round 12)	Timer delayed → launch check sees an expired deadline → row failed "Timed out while preparing"; D is not called
Time limit versus cancel task (review round 12)	time-limit recorded → user cancels the task → provider settles → row cancelled, task stays cancelled, one task-closed
Refused action, then replay (review round 12)	Retry refused with 409 → the response is lost → the state changes → replay with the same actionId → the same 409 comes back and nothing is applied
Reject reopens the task (review round 12)	Reject with feedback → next revision, affected items marked, task queued, one reject event, no task-closed
Admit work on a closed task (review round 13)	Task cancelled → a fresh (not retry) admission → refused, no attempt row
Question settling after the gate closes (review round 13)	Question running → shutdown → the abort path's finishAnswer writes through the capability → row failed with the shutdown reason; questions.close() resolves
Hard-link alias (review round 13)	Hard-link the database to a second name → start through either name → refused
First start with no database (review round 13)	Start with a missing database path → lock created → database created → identity written into the lock → a concurrent second start exits at step 1
Preparation child ignores SIGTERM (review round 14)	Clone subprocess ignores SIGTERM → cancel → SIGKILL after the grace period → close awaited → row cancelled → slot freed; shutdown completes
Cancel task during a merge (review round 14)	Merge attempt queued → cancel task → refused; after the merge is recorded as merged, the task is merged with one task-closed
Retry after queue removal (review round 14)	Merge attempt removed with requiresFreshReview → F's retry endpoint does not offer or accept a merge retry
Cancel task while an attempt runs (review round 15)	Attempt running → cancel task → the task stays open with cancel_requested, "Stopping, then cancelling" → the provider returns a valid result → not published → one transaction: row cancelled, task cancelled, one task-closed → then removeTaskFilesystems → then the slot is freed
Review load hits the gate (review round 15)	/api/review admitted with a moved HEAD → shutdown → recordHistory throws ShuttingDownError → HTTP 503, not 409
Crash during preparation (review round 15)	Clone half-written in the attempt directory → process killed → restart → diagnostic saved, directory removed, an unknown sibling directory left and reported
Cancel task recorded after the final await (review round 16)	Result validated → cancel task commits cancel_requested → publication transaction refuses completed → row cancelled, task cancelled
Crash with a live clone child (review round 16)	Clone child running → runner killed → restart → recovery kills and awaits the saved process group before capturing and removing the directory
Lost merge response (review round 16)	Merge click → attempt started → response lost → replay with the same actionId → the same attempt's status returns; beginMergeAttempt is not called again
Symlink swap at first start (review round 16)	Parent directory writable by others → startup exits. With a safe parent: a symlink placed at the path before creation → O_NOFOLLOW create fails → exit
Unsaved stop is visible (review round 16)	First-reason write throws → GET /api/runner returns stopRequested.saved = false → UI shows "Stopping (not saved yet)"
Preparation started but no group ID saved (review round 17)	Crash after "preparation starting" and before the group ID → restart → admission stays closed and the attempt is named; --release-preparation removes the directory only after it stays unchanged
Time limit versus pending cancel task (review round 17)	cancel_requested set → the time-limit settlement arrives → task cancelled with one task-closed, never needs human
Recovery transaction fails (review round 17)	Storage error in step 3 → no directory removed, no admission, Store closed, lock released, non-zero exit
Planning replay (review round 17)	Suggestion apply commits → response lost → replay with the same actionId → the same new revision returns, and no second apply
Unsafe stored attempt ID (review round 18)	An attempt row with ID ../x → recovery refuses it, reports it and touches no path
Stop reason recorded on a running row (review round 18)	Cancel → running row gets its first reason, state version +1, state still running; a second cancel changes nothing
Gate error inside merge status (review round 18)	/api/review → displayStatus → direct-merge reconciliation throws ShuttingDownError → HTTP 503, not 200 with a blocker; the same for /api/merge polling
D recovery fails (review round 18)	recoverLeftovers rejects → no row finalized, nothing handed to I3, lock released, non-zero exit
Context changed, then crash with no reason (review round 18)	Plan revision advances → runner killed before recording stale → restart → row stale, not requeued
Stop recorded, then the handle arrives (review round 19)	First reason saved on a pending row → D returns a handle → pending → running refused → handle cancelled and settled → row cancelled
Provider error after a context change (review round 19)	Plan revision advances → provider exits with an error → row stale, not failed
D timeout, then a context change, then settlement (review round 19)	D stops the attempt with timeout → the snapshot changes while cleanup runs → settled → row stale
D timeout, then shutdown (review round 19)	D stops with timeout and cleanup keeps settled pending → shutdown records shutdown → settlement → row failed with the timeout; not requeued
Corrupt runner token (review round 19)	app_settings token is ../x → startup exits before any label or path use
Crash after the budget ran out (review round 19)	budget_deadline passes → runner killed before saving time-limit → restart → row cancelled, task needs human
Hard link before migrations (review round 19)	Hard-linked database name → step 1 refuses before SQLite opens it; no migration runs
Recovered volume bound to its attempt (review round 20)	Crash with task storage for attempt A → restart → the handle's attempt and allocation IDs match A's row → export saved as A's diagnostic_ref → volumes removed; a volume whose labels match no row is reported and kept
Unsafe parent before the lock (review round 20)	Parent writable by others and a lock file pre-created by another user → startup exits at step 0 without opening, removing or trusting that lock
Expired and non-current after a crash (review round 20)	Budget passed and plan revision advanced, no reason recorded → restart → row stale, not time-limit
Task storage outlives settlement (review round 21)	Writable attempt cancelled → settled → the volumes still exist → export runs → terminal write with diagnostic_ref → removeTaskFilesystems → slot freed. The order is asserted, and a completed writable attempt also ends with its storage removed
Storage removal fails (review round 22)	Terminal write succeeds → removeTaskFilesystems throws → slot held, unresolved marker shown → restart removes the storage before admission
Storage allocation is abortable (review round 23)	Cancel while prepareTaskFilesystems is waiting on Docker → the async variant aborts, its process group exits, and the event loop keeps serving /api/runner meanwhile → row cancelled
Shutdown frees slots only after storage removal (review round 23)	Writable attempt → shutdown → export → terminal write → removal fails → slot stays held → Store closes → restart removes the storage
Cancel a pending suggestion (review round 23)	Suggestion running → cancel endpoint → the saved handle's cancel is called → provider settles → request cancelled, coordinator slot free
Invalid action ID (review round 23)	A 10 KB actionId, and one that is not a UUID → HTTP 400; no user_actions row
Two starters after a crash (review round 23)	Runner killed (the OS releases its lock) → two processes start at once → exactly one gets the exclusive lock and the other exits; the lock file is never deleted
Retry versus recovery requeue (review round 24)	Restart lists the task and sets requeue_pending → user retry → refused → "Resume" and I3 requeue race → exactly one admits an attempt
Crash during a rebase (review round 25)	F3 sets rebase_in_progress → runner killed → restart → step 4 aborts that rebase and clears the field by compare-and-swap on its attemptId → only then is the task listed for I3
Release an unknown preparation (review round 26)	A process still has a file open in the attempt directory → --release-preparation refuses and admission stays closed; after the process exits → released
Shutdown during launch setup (review round 26)	D start returns its handle → Docker setup still running → shutdown → /api/runner keeps answering, cancel reaches setup → setup cleanup → settled
Completed writable attempt keeps its work (review round 26)	execute exits 0 → F2 extracts the commit from task storage → completed → only then removeTaskFilesystems
Suggestion cancel after a restart (review round 26)	Provider container from the crashed process → startup step 2 removes it → pending request → cancel endpoint → cancelled
Legacy resources are never removed automatically (review rounds 27–28)	Unlabelled resources exist → startup refuses admission and lists them with removal commands; no codeboost code path deletes them; after manual removal, the next start opens admission
Ledger write in the publication transaction (review round 27)	Completed execute → the step-3 guard passes → completed and recordHistory in one transaction → generation +1. A stale variant → refused, no ledger entry, the commit is discarded with the storage
D timeout, then shutdown, then crash (review round 28)	(a) Row with a saved stop_reason of timeout and first reason shutdown → restart → failed, not requeued. (b) D timed out, then shutdown, then a crash before settlement (no stop_reason saved) → restart → cancelled "Stopped by shutdown" and requeued once; the requeued attempt has a fresh finite deadline
Recovery keeps the keeper (review round 29)	Crash with task storage → recoverLeftovers → the agent container and network are gone, but the volumes and their keeper container remain → export succeeds → removeTaskFilesystems removes both
Crash during async allocation (review round 30)	allocation_id saved → allocation starts → process killed → restart → the handle's attempt and allocation IDs match the row → exported and removed; never classed as unowned
Recovery finalization fails after export (review round 30)	Export writes <attemptId>.diff → the finalization transaction fails → exit → next start re-exports to the same name and finalizes once
Preparation still writing at restart (review round 32)	Crashed storage allocator's group still alive → restart → step 2b kills and awaits it → only then D recovery and export run
Renamed database (review rounds 32–33)	Runner A holds the lock → the database file is renamed, and separately moved to another directory on the same filesystem → runner B starts through the new path → same device and inode, same lock file → B exits
Export hangs (review round 32)	Docker export never returns → the 60-second deadline aborts it → diagnostic "Partial output could not be exported" → terminal write and removal continue; shutdown finishes
Time limit versus closed task in recovery (review round 32)	time-limit saved, then cancel task recorded, then crash → restart → task cancelled with one task-closed, never needs human
In-memory cancel, then a valid result (review round 33)	The first-reason write fails after cancel → the provider returns a valid result → publication is skipped → row cancelled with the in-memory reason
Retention with referenced files (review round 33)	The cap is exceeded by referenced files only → the oldest row's diagnostic_ref is cleared and noted first → then the file is deleted; no row points at a missing file
Recovered read-only storage (review round 34)	Crash with a running review attempt's task storage → restart → no export runs → storage removed → no diagnostics file; a crashed execute attempt's storage is exported, then removed
Human-gated change during settlement (review round 35)	Attempt running → a request to move the task to needs amendment → refused while the attempt is active; with the status forced by raw SQL → a valid result ends cancelled, never completed
Stop after storage allocation, before launch (review round 36)	Task storage allocated → cancel before the D start call → host-side files removed → storage still present → terminal write → removeTaskFilesystems → slot freed; with the terminal write failing, the storage remains for recovery
Old attempt settles after a retry (D/F contract)	Attempt A cancelled and settled → retry B admitted → a late publish from A is refused → B's row and the visible status are unchanged

Decisions (approved 2026-09-25)

The user approved the proposal for each of these four questions.

#	Question	Decision	What F1 must do
1	How is one runner per database enforced across processes?	An exclusive lock file next to the database. Updated in review round 23: the lock is an operating-system lock held on that file, not a process-ID check. The approved proposal used a process ID and start time, but taking over a stale lock of that kind is not race-safe: two starters could both judge it stale, and one could delete the other's new lock.	Derive the lock path from the canonical database path: resolve the parent directory with realpath, and refuse a database path that is itself a symlink. Refuse a database file whose hard-link count is more than 1, both before and after opening, because two hard-linked names would give two lock paths for one file. Startup order, which also covers a database that does not exist yet:

0. Before the lock file is opened: resolve the parent directory with realpath, and check that it is owned by the current user and not writable by group or others. Otherwise exit. Only then is the lock path a safe boundary.
1. Identify the database file before locking. If it exists, open it with O_NOFOLLOW, fstat the descriptor, and refuse anything that is not a regular file or has a link count above 1. If it does not exist, create it with O_CREAT | O_EXCL | O_NOFOLLOW (an empty file is a valid new SQLite database). If that creation fails with EEXIST because another starter won the race, open the existing file as above. Keep the descriptor. Updated in review round 32: the lock is keyed by this file's identity, not its name, because a name-based lock lets a renamed database get a second lock while the first runner still holds the old one.
2. Open the lock file ~/.codeboost/locks/<device>-<inode>.runner-lock, creating the directory with mode 0700 if needed and applying the same owner and mode check as step 0. The location does not depend on the database's directory, so a database moved to another directory on the same filesystem, which keeps its inode, still meets the same lock. Moving it to another filesystem copies it and gives it a new inode, so it becomes a different database. Open the lock file as a small, dedicated SQLite database. Set PRAGMA locking_mode = EXCLUSIVE, and start a write transaction to take SQLite's exclusive POSIX lock on it. If that fails with SQLITE_BUSY, another runner holds it: exit. The operating system releases this lock when the process exits or crashes. There is no stale lock and no takeover: lock files are never deleted, and a new starter only ever tries to take the OS lock. A leftover lock file for a deleted database is harmless, because no process holds its lock. The lock database stores no owner details: while one process holds the exclusive lock, another cannot read it, so an owner record could never be shown.
3. Open the Store under the lock. Migrations run here. node:sqlite can open a database only by path, not by descriptor. What this defends against, and what it does not. Because only this user can change the directory, another user cannot swap the path. A swap by the user's own processes between step 1 and SQLite's open is not prevented; step 4 detects it only afterwards, and migrations may already have run on the other file. Startup then exits before admission. This is accepted: the same user can already write the database file directly, so the lock guards against accidental double starts, not against the user's own processes.
4. lstat the database path and compare it with step 1's descriptor: same device and inode, a regular file, and a link count of 1. Exit on a mismatch. Keep the lock connection, and so the OS lock, open until shutdown step 8.

Renames (including moves between directories on the same filesystem), symlink aliases and relative paths therefore meet the same lock, because they reach the same device and inode. Hard-link aliases are refused. A copy is a different file with a different inode, so it is a different database with its own lock and its own runner owner token. Take the lock at startup and release it at the end of shutdown, by closing the lock connection. Lock files must be on a local filesystem, because POSIX locks are unreliable on network filesystems, so startup refuses a network mount. Do not use a lease row in the main database, because lease expiry could release a live runner. | | 2 | Does E3 keep writing cancelled before the provider settles? | Yes. This exception applies only to read-only phases. | Leave E3 unchanged. New F records use "terminal only after settlement" for every phase. Revisit this when G4 wires the planning endpoints. | | 3 | Is process shutdown a hard stop? | Yes. | Stopping the process cancels the running task with the reason "Stopped by shutdown". It does not wait for the task to finish. Restart recovery requeues the task. | | 4 | Does F set its own time limit on settlement at shutdown? | No. F waits for D's forced-kill escalation. | Do not abandon a job after a timer. The D5 real-Docker suite must prove that settlement always ends, including for a child process that ignores SIGTERM. D4 does not yet prove it: its cleanup retries have no limit (see the prerequisite under "Shutdown"). If D5 cannot prove it, reopen this decision before F1 merges. |

Out of scope for F1

• Per-item execution, review rounds, PR opening (F2); rebase and ledger mapping (F3–F4); head-bound checks (F5); merge handoff (F6).
• Queue admission, run windows, workspace rebuild (lane I).
• Lesson distillation and the Lessons inbox (lane J). F1 only records the events.
• Moving Ask onto D's contract. This is F's job, but it happens after D5 and is not part of F1.

Testing this document with a reader

Before approval, ask one reviewer from lane G or I, who did not write this document, to answer these from the document alone:

1. A user clicks Cancel on a running fix attempt. What does the UI show, and when does the retry button turn on?
2. The plan revision changes while an execute attempt runs. Which terminal state does the attempt get, and can it be retried?
3. What happens, in order, when the user presses Ctrl+C with one running attempt and one open poll?
4. Which user actions create feedback events, and when may lane J read them?

If any answer differs from the intended one, fix the section that caused it before approval.