Skip to content

Commit a31ae05

Browse files
mchwangclaude
andcommitted
Address F1 contract review round 27
- Machine-wide shared/exclusive lock proves no live runner before legacy cleanup; running legacy containers also block it. - F2 records the ledger inside the publication transaction after the guard; nothing is written to the Store before it. - State that this contract governs task closure until design L1 is reconciled by its owner. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent a17d980 commit a31ae05

1 file changed

Lines changed: 9 additions & 3 deletions

File tree

‎docs/implementation/runner-lifecycle.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,11 @@ The server computes `retryable` and sends it to the UI. The UI never works it ou
205205
2. Validate the output (schema, size, file-scope audit for writable attempts). Do not await anything between the last check and the transaction.
206206
3. 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 is not closed, 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.
207207
4. If step 3 refuses, reread durable state and settle the row by the rules above. Keep the original diagnostic.
208-
5. For a completed writable attempt, F2's result extraction (committing the change and recording its ledger entry) is part of step 2 above. It runs from the still-present task storage before the step-3 transaction. If step 3 then refuses, F2's rules discard the extracted commit. 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.
208+
5. For a completed writable attempt, F2's result extraction is split in two:
209+
- Step 2, before any `Store` write, makes the commit object inside the still-present task storage. It records nothing in the `Store`.
210+
- 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.
211+
212+
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.
209213

210214
**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.)
211215

@@ -244,7 +248,7 @@ The server computes `retryable` and sends it to the UI. The UI never works it ou
244248
| 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. |
245249
| 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, and F saves the returned allocation ID as `attempts.allocation_id` in the same turn. 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 left for `--remove-unowned-agent-resources`; it is never exported or removed automatically. `exportTaskDiff` and `removeTaskFilesystems` accept these handles. F never builds a `TaskFilesystems` value from report fields. |
246250
| Scoped recovery | D | `recoverLeftovers(runnerOwner): Promise<RecoveryReport>` acts only on resources whose `io.codeboost.runner` label equals the token. It stops and removes containers, egress proxies and networks, and resolves only when they are gone. **It keeps task-storage volumes** 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. |
247-
| 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, F refuses to open admission, and the CLI prints the list with the instruction to stop every codeboost process and then run `--remove-unowned-agent-resources`. That flag removes them only when no other codeboost runner lock is live on the machine. It never adopts or reuses them. |
251+
| 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, F refuses to open admission, and the CLI prints the list with the instruction to stop every codeboost process and then run `--remove-unowned-agent-resources`. That flag needs proof that no other runner is live on the machine, and per-database locks cannot give that proof. So every runner of this build also holds a **shared** lock on one machine-wide lock database (`~/.codeboost/runners.lock`), through an open read transaction, for its whole lifetime. The flag takes an **exclusive** lock on the same file, which fails while any runner holds its shared lock. Runners from older builds do not take this lock, so the flag also refuses while any codeboost-labelled container is still running. It removes only stopped containers and the networks and volumes they no longer use. If either check cannot run, it refuses. It never adopts or reuses these resources. |
248252
| When it runs | F | Only while holding this database's single-runner lock (startup recovery step 1 comes first). |
249253

250254
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.
@@ -382,7 +386,7 @@ A merged v5 task also gets its `task-closed` event, keyed by the merge attempt I
382386
| `user_actions` | `plan_key`, `action_id` (together the primary key), `kind`, `request_hash`, `response` (JSON, bounded), `created_at` |
383387
| `feedback_events` | the fields listed above, with `id` as primary key, with a unique index on `(plan_key, kind, action_id)` |
384388

385-
`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) also lists "rejected" as a way a task closes. That conflicts with step 8, and this contract follows step 8. 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.
389+
`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) also lists "rejected" as a way a task closes. That conflicts with step 8, and this contract follows step 8. **Until the design is reconciled, this contract governs** when a task closes and when J may read its feedback, for lanes F and J. The design is owned by the plan's documentation owner (rule 3 of "Ownership and integration rules"), so this PR does not edit it. Reconciling line 533 is tracked as a follow-up for that owner. 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.
386390

387391
**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.
388392

@@ -496,6 +500,8 @@ Each case needs a test that fails before the fix and passes after it. Each test
496500
| 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` |
497501
| Completed writable attempt keeps its work (review round 26) | `execute` exits 0 → F2 extracts the commit from task storage → `completed` → only then `removeTaskFilesystems` |
498502
| Suggestion cancel after a restart (review round 26) | Provider container from the crashed process → startup step 2 removes it → pending request → cancel endpoint → `cancelled` |
503+
| Legacy cleanup with a live runner (review round 27) | Runner B holds its shared machine lock → `--remove-unowned-agent-resources` → exclusive lock fails → refused. A running unlabelled container → refused |
504+
| 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 |
499505
| 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 |
500506

501507
## Decisions (approved 2026-09-25)

0 commit comments

Comments
 (0)