diff --git a/.docket.example.yml b/.docket.example.yml index e39340fbf..7030f29a4 100644 --- a/.docket.example.yml +++ b/.docket.example.yml @@ -130,6 +130,14 @@ run: # scope: any layer max_attempts: 2 + # max_consecutive_halts — how many changes picked from the queue may halt in a row before a + # tracked implement-next loop stops. A halted change always waits for a person; under this limit + # the loop moves on to the next build-ready change instead of ending the drain. 2 by default; + # 1 stops the loop at the first halt. A clean build resets the count, and so does + # `docket run reset-halts`. A whole number of 1 or more. + # scope: any layer + max_consecutive_halts: 2 + # ═══ review — what implement-next fixes after review ══════════════════════════════════════ diff --git a/AGENTS.md b/AGENTS.md index 8f238f3d4..df9498a51 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,6 +38,9 @@ broken: surface it, never rebuild the run tracker by hand. or dispatch `docket-implement-next` again with the explicit change id, the continuation id, and the same key, and run `run.verdict` with `` again. Every `run-stop` and every `run-observe` forbids re-dispatch; `run-halted` means a human is needed. + `run-next run-halted ` also forbids re-dispatching that change; only a loop driver + (`/loop`) may go on to its next run, with a fresh `run.start`; a single dispatch stops, as on + `run-stop`. ## Stopping a dispatched run — there is no automatic Stop button diff --git a/cursor-rules/run-tracker.md b/cursor-rules/run-tracker.md index 1cb7da5c3..d52d59dfe 100644 --- a/cursor-rules/run-tracker.md +++ b/cursor-rules/run-tracker.md @@ -24,6 +24,9 @@ broken: surface it, never rebuild the run tracker by hand. or dispatch `docket-implement-next` again with the explicit change id, the continuation id, and the same key, and run `run.verdict` with `` again. Every `run-stop` and every `run-observe` forbids re-dispatch; `run-halted` means a human is needed. + `run-next run-halted ` also forbids re-dispatching that change; only a loop driver + (`/loop`) may go on to its next run, with a fresh `run.start`; a single dispatch stops, as on + `run-stop`. ## Stopping a dispatched run — there is no automatic Stop button diff --git a/docs/concepts/run-tracker.md b/docs/concepts/run-tracker.md index cf7b644a4..6d06ef97b 100644 --- a/docs/concepts/run-tracker.md +++ b/docs/concepts/run-tracker.md @@ -50,6 +50,9 @@ verdict, not the worker's report, says what may happen next. ├─ run-continue ────► the same attempt is still working: resume it or │ dispatch again with its continuation id; │ same key, spends no retry + ├─ run-next ────────► this change needs a human; never re-dispatch it. + │ A loop may start its next run (fresh run start); + │ a single dispatch stops ├─ run-stop ────────► no re-dispatch; run-stop … run-halted means the │ change needs a human └─ run-observe ─────► an unattributed read (no key); never authorizes @@ -94,6 +97,21 @@ verdict, not the worker's report, says what may happen next. again with the change id and the continuation id it names, keeping the same key and spending no retry. Every `run-stop` and every `run-observe` forbids a re-dispatch. +- **The halt count.** The tracker keeps one count per repository of + implement-next runs in a row that halted on a change picked from the + queue (no id, or a set of two or more ids — a loop, or a one-off + "implement the next change"). A halt on a named run or a resume never touches it. + While the count stays under `run.max_consecutive_halts` (default 2), such + a halt prints `run-next run-halted ` instead of + `run-stop run-halted `: the halted change is never + re-dispatched, but a loop may start a fresh run for the next change. The + halt that reaches the limit prints `run-stop … run-halted` with a note + asking the person whether to reset the count. Only a clean build + (`run-done … run-complete`), named or picked, sets the count back to 0, + and so does `docket run reset-halts`, which runs only on the person's explicit yes, never on the agent's own. Each run + changes the count at most once, however often its verdict is read again. + The count lives in the repository's state folder, so every session and + worktree shares it. - **Verifying a change** (`docket run verify --id `) checks one change's run against its postconditions — workspace and remote heads, build evidence, the pull request, the plan and results files, the claim @@ -176,6 +194,8 @@ blocks as `mutation-pending:`. than guessing. - Only `run-retry-once` and `run-continue` authorize another dispatch; every stop or observe line forbids it. +- A halt never re-dispatches its change: `run-next` only lets a loop start + a new run for the next change, and only the person resets the halt count. - The verdict always exits 0; the decision lives in the report line, not the exit code. - A probe that cannot prove a process is alive is not evidence that it diff --git a/docs/guide/building-without-supervision.md b/docs/guide/building-without-supervision.md index 7512dbafa..ce481d43a 100644 --- a/docs/guide/building-without-supervision.md +++ b/docs/guide/building-without-supervision.md @@ -151,7 +151,9 @@ whatever starts them keys on the outcome each run declares. Every run ends by de - **halted** — something needs a human (an escalation, an invalidated design, a broken precondition). A driver keys on these with one simple rule: **continue on `advanced` or `contended`, stop on -`drained` or `halted`.** The contract is deliberately driver-agnostic — a human re-issuing the +`drained` or `halted`** — except that a tracked loop carries on past `halted` when the run +tracker's verdict is `run-next` (see [When a change halts mid-drain](#when-a-change-halts-mid-drain)). +The contract is deliberately driver-agnostic — a human re-issuing the plain request between runs satisfies it exactly as well as any automated driver, so nothing here depends on a particular tool. @@ -167,8 +169,8 @@ build work stays isolated and the driver's own context stays small: A change on [hold](../reference/glossary.md#hold) is skipped by both drains; it is built only when you name it alone. -Budget and iteration caps belong to the driver, not to docket, which does not reimplement them. The -one invariant the driver never breaks is the PR handoff: **a build run never merges.** A dependency +Iteration caps belong to the driver, not to docket, which does not reimplement them; the one limit +docket keeps itself is the halt limit below. The one invariant the driver never breaks is the PR handoff: **a build run never merges.** A dependency on a `pr` change therefore only clears between drains, once its pull request is merged outside the drain — you clicking Merge, or a separate close-out drain ([Landing changes safely](./landing-changes.md)) — and the change reaches `done`. A dependency on a @@ -177,6 +179,10 @@ unattended; `/loop` behavior is version- and mode-specific. The bookkeeping that launched it, whether it finished, whether a re-dispatch is allowed — is the run tracker, described in [The run tracker and attribution](../concepts/run-tracker.md). +docket supports **one implement loop and one finalize loop at a time**; the two may run side by +side. A second implement loop is unsupported: both loops would share one halt count, and one loop's +clean builds would keep resetting the other's halts, so a broken setup would never reach the limit. + The run tracker follows a run only when the session starts it: with a plain request in the session (for example "implement 412") or with `/loop docket-implement-next`. In Claude Code the implement-next skill runs forked, so a typed command goes straight to the implementer and the @@ -184,3 +190,31 @@ session never takes the turn that would start a tracked run. A typed `/docket-implement-next` runs untracked. It still builds to a PR, but if it stops partway there is no automatic retry, resume, or cancel, and its outcome can only be read unattributed (`docket run verdict --unattributed`). + +### When a change halts mid-drain + +A halt usually concerns one change, such as a spec with a logical error that needs you. The change +is already marked as needing you on the board, so a tracked loop does not stop the whole drain for +it. When a run halts on a change it picked from the queue, the run tracker's verdict is +`run-next run-halted `: the halted change is never re-dispatched, and the loop starts a +fresh run for the next build-ready change. + +A setup problem would halt every change the same way, so the run tracker keeps a **count of halts +in a row** and stops the loop at `run.max_consecutive_halts` (default 2). The halt that reaches the +limit prints `run-stop run-halted ` with a note, and the session asks you whether to reset +the count. It never resets the count on its own; on your yes it runs `docket run reset-halts`, which +you can also run yourself at any time. Set the limit to `1` to stop a loop at its first halt. + +- **Which runs count.** A run that picked its change from the queue: no id, or a set of two or more + ids. That includes a one-off "implement the next change". A halt on a named run (a single id) or a resume + never reads or changes the count; that halt stops as before. +- **What resets it.** A clean build (`run-done … run-complete`) sets the count back to 0, whether + the change was named or picked, and so does `docket run reset-halts`. Nothing else does: a run + that claimed nothing, including one that halted before its claim, leaves the count alone. +- **It outlives the loop.** The count is shared by every session and worktree of the repository. + A loop stopped at the limit leaves the count there until a clean build or a reset, so the next + loop stops at its first halt. A visibility switch moves the state folder, and the count moves with + it. +- **Halted runs stay active.** Each halted run stays active so it can be resumed. A visibility + switch refuses while any run is still active, and a loop can leave up to the limit's worth of + halted runs behind; cancel each (`docket run cancel --key --reason `) before switching. diff --git a/docs/guide/capturing-work.md b/docs/guide/capturing-work.md index c0efe50c0..557fb9c25 100644 --- a/docs/guide/capturing-work.md +++ b/docs/guide/capturing-work.md @@ -91,7 +91,7 @@ Every docket write re-renders the board, so there is no separate step to regener One honest caveat about dependencies: chains serialize on the PR handoff. A change that depends on another cannot start until that dependency is `done` — its pull request merged and the change -closed out, or, for a results-artifact dependency, the change completed. Unrelated changes drain freely in parallel around it — only the dependent one waits. +closed out, or, for a results-artifact dependency, the change completed. Unrelated changes keep draining around it — only the dependent one waits. ## Priorities, types, and dependencies @@ -110,7 +110,7 @@ Three manifest fields shape *what gets built when*, and none of them is a hard s that the second change would be built against code that is not there yet. Record a dependency whenever one change genuinely needs another's merged code or decision. Leave -it empty when the two pieces of work are independent — that is what lets them drain in parallel. +it empty when the two pieces of work are independent — that is what lets them drain in any order. ## Capturing an idea: designed, rough, or discovered diff --git a/docs/guide/landing-changes.md b/docs/guide/landing-changes.md index 4f06c1c2c..488ee5a7c 100644 --- a/docs/guide/landing-changes.md +++ b/docs/guide/landing-changes.md @@ -49,8 +49,12 @@ in [Proving the build](./proving-the-build.md). `docket-finalize-change` ends every run declaring one of four run outcomes — `advanced` (merged one change and closed it out), `contended` (another writer got there first, nothing merged), `drained` (nothing eligible in scope), or `halted` (needs a human). implement-next ends with the same four -words, so a single driver keys on both drains the same way: **continue on `advanced`/`contended`, -stop on `drained`/`halted`.** The built-in `/loop` is the recommended driver: +words. A finalize driver keys on them with one rule: **continue on `advanced`/`contended`, stop on +`drained`/`halted`** — on every `halted`. An implement-next loop differs in one way: it may carry +on past a halted change when the run tracker's verdict is `run-next` +([When a change halts mid-drain](./building-without-supervision.md#when-a-change-halts-mid-drain)). +docket supports one implement loop and one finalize loop at a time; the two may run side by side. +The built-in `/loop` is the recommended driver: - `/loop docket-finalize-change` — closes out every eligible `implemented` change, **one merge per iteration**, stopping on `drained`. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index df4edce47..54072843a 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -54,7 +54,8 @@ Each line is a pointer: the command, what its verbs govern, and where to read th commands, and fast-forward the primary checkout to the integration branch. Verbs: `docket repository --help`. - **`docket run`** — track dispatched runs and verify a change's run from claim to its handoff - (implemented with a PR, or a completed results artifact). + (implemented with a PR, or a completed results artifact); also reset the count of implement-next + halts in a row (`docket run reset-halts`). Verbs: `docket run --help`. - **`docket schema`** — emit request/result payload schemas and allowed values (read-only, repository-independent). Verbs: `docket schema --help`. diff --git a/docs/reference/config-keys.md b/docs/reference/config-keys.md index 1f769db7c..6bb6d2669 100644 --- a/docs/reference/config-keys.md +++ b/docs/reference/config-keys.md @@ -47,6 +47,7 @@ Each key has one scope: | `build.test_command` | `""` (unconfigured) | any layer | the suite the build gate runs | | `build.max_attempts` | `4` | any layer | full suite runs a build may spend, repairs included | | `run.max_attempts` | `2` | any layer | attempts a tracked implement-next run may make on one change | +| `run.max_consecutive_halts` | `2` | any layer | halts in a row, on changes a loop picked from the queue, before the loop stops | | `review.min_fix_severity` | `minor` | any layer | the lowest review-finding severity the fix pass repairs | | `review.max_fix_tasks` | `10` | any layer | the most non-blocker fix tasks one fix pass dispatches | | `reclaim.lease_ttl` | `72` | any layer | hours a claim on an in-progress change lasts | diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index e61299684..99f58cbe3 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -1138,6 +1138,7 @@ code or the child's prose. |---|---| | `run-retry-once …` | The only line that authorises another dispatch — once, same key, for the id and unmet conditions it names. Granted at most `run.max_attempts - 1` times. | | `run-continue run-waiting ` | Non-terminal: the same attempt still owns work. Resume it with the continuation id; spends no retry. | +| `run-next run-halted ` | The change halted and needs a human; never re-dispatch it. Printed only for a change picked from the queue while the halt count is under `run.max_consecutive_halts`. A loop may start its next run with a fresh `run.start`; a single dispatch stops. | | `run-done …` | Finished (e.g. `run-done run-complete`). | | `run-stop …` | Stop; no re-dispatch (e.g. `run-stop run-tracker-unavailable takeover-ambiguous`). | | `run-observe …` | Observe only; no re-dispatch (e.g. `run-observe run-incomplete`). | @@ -1389,7 +1390,8 @@ docket finalize clear-block --id 412 --revision --head --pr-number 301 Every finalize run ends with one of four outcomes: `advanced` (it closed a change out), `contended` (another writer got there first), `drained` (nothing eligible), or `halted` (a human is needed). A driver continues on `advanced`/`contended` and stops on `drained`/`halted`, which are the same four -words implement-next uses. +words implement-next uses. A finalize loop stops on every `halted`; only an implement-next loop may +carry on past a halted change, when its verdict is `run-next`. **Used for:** closing out hands-free, one merge per iteration. Unlike implement-next, the finalize drain **does merge**. Naming ids bounds the run and authorizes merges `require_pr_approval` would hold. @@ -1985,10 +1987,18 @@ post-rebase repair. next run or phase you start, never one already running. Explicit halts need a human whatever the budget. A cancel spends no attempt. +The **halt count** is a separate limit on a loop, not on a change. `run.max_consecutive_halts` (default 2, minimum 1) +caps how many implement-next runs in a row may halt on a change picked from the queue before the loop stops. A halt +under the limit prints `run-next`; the halt that reaches it prints `run-stop … run-halted` with a note asking the +person whether to reset the count. A halt on a named run or a resume never touches the count; a clean build (`run-complete`) +sets it back to 0, and so does `docket run reset-halts`, which runs only on the person's explicit yes, never on the agent's own. The limit is read when the verdict +is printed, so a new value applies to the next halt. `1` stops a loop at its first halt. + ```yaml # .docket.yml run: max_attempts: 2 + max_consecutive_halts: 2 build: max_attempts: 4 ``` diff --git a/docs/superpowers/specs/2026-10-19-let-a-loop-carry-on-past-a-halt-that-concerns-only-one-chang-design.md b/docs/superpowers/specs/2026-10-19-let-a-loop-carry-on-past-a-halt-that-concerns-only-one-chang-design.md new file mode 100644 index 000000000..d8c34a4e5 --- /dev/null +++ b/docs/superpowers/specs/2026-10-19-let-a-loop-carry-on-past-a-halt-that-concerns-only-one-chang-design.md @@ -0,0 +1,255 @@ +# Let a loop carry on past a halt that concerns only one change — design + +Change 0570 — Let a loop carry on past a halt that concerns only one change + +Change #570, groomed 2026-10-19. + +## Intent + +An overnight `/loop docket-implement-next` drain ends at the first halt. The typical halt is one the +build finds mid-run in a single change, such as a logical error in its spec that needs a person. The +change is already marked "run halted — needs you" on the board, so stopping the whole drain for it +throws away a night of work on the other build-ready changes. + +After this change, a loop carries on past a halt recorded on a change it picked from the queue and +moves to the next build-ready change. A setup problem would halt every change the same way, so a limit +on halts in a row stops the loop before it walks the whole queue. + +## Goals + +- A tracked implement-next loop continues after a run that halted with a recorded `## Run halted` + marker on a change the loop picked, while the count of halts in a row is under the limit. +- The loop stops when the count reaches `run.max_consecutive_halts` (default 2), and the person is + asked whether to reset the count. +- The loop still stops on any halt that left no marker (every pre-claim halt) and on every other + `run-stop`, as it does today. +- **Nothing outside a loop changes.** A named run, a resume, a retry or continuation, an untracked + run, and finalize print exactly today's verdict lines and see no new refusal. *(Human's + requirement; confirmed by a code review of this design — see *Isolation guarantees*.)* + +## Non-goals + +- **No halt reason or classification.** The stub proposed a typed halt reason and sorting every halt + point into "this change" and "every change". Dropped: the marker plus the halt limit is enough. A + setup-wide problem is caught by the limit rather than predicted per halt point. The cost is a + couple of halted changes before the loop stops, which the human accepted. +- **No change to `change.halt`**, the `## Run halted` section, `run.verify`, or the board. +- **Finalize is untouched.** Its `## Finalize blocked` note never removes a change from finalize + selection, so an unscoped finalize loop that carried on would re-pick the same blocked change. + Carrying a finalize loop past a block is a separate change, captured as its own stub. Finalize is + not bracketed by the run tracker (`run.start` accepts only `implement-next`), and every finalize + `halted` still stops the driver. +- **No change to pre-claim halts.** They write nothing and the run tracker reports them as + `run-done no-attributable-claim`; the child declares `halted` and the loop stops, as today. +- **No loop identity.** Resetting the count when a loop starts was considered and rejected: docket + cannot see a loop start (`/loop` re-fires the same prompt every iteration), so the reset would rest + on the agent judging "this is the first iteration"; a wrong judgment resets every iteration and the + limit never trips. A restarted loop would also get a fresh limit with nothing fixed. + +## Anti-goals + +- An agent must never reset the halt count on its own. A loop that could clear its own limit + defeats the backstop. +- Halts under the limit must never be re-dispatched. Carrying on means starting a *new* run for the + next change, never retrying the halted one. +- No new text in the everyday path beyond one sentence in the dispatch block. The reset prompt is + carried by the verdict output at the moment it applies. +- No new refusal anywhere: nothing in this change may make `run.start`, `change.claim`, + `run.verdict`, finalize, `status`, the board, `repository.check`/`repair`, `resume-halted`, or + `set-visibility` refuse, stop, or report differently for a run that is not a loop-picked halt. + +## Design (settled with the human) + +### 1. Which runs count: loop-picked vs named + +implement-next already has two ways of choosing a change: the **selection path** (no id, or an id +allowlist of two or more ids — what a loop drives, and also a one-off "implement the next change") and +the **named path** (a single explicit id, or a `run.start --resume`). + +- **Recording the mode.** Today the claim cannot tell the two apart: `ChangeClaimRequest` + (`internal/app/change_claim.go`) carries only `ID`, `Revision` and `RunContext`, and both paths call + `context.implementation --id` then `change.claim --id`. So the selection path passes a new + **optional** claim input naming its mode. + - Absent or unrecognised → recorded as `unknown`. It **never refuses a claim**, so an older skill + copy (a session not restarted after install) keeps claiming exactly as today. + - It is not part of `claimDigestPayload` or `claimRequestID`, so it never changes claim identity or + idempotence. + - It is stored in the committed claim receipt (`changeClaimReceipt`) as an additive field, so it + survives a lost local binding and the verdict's receipt-recovery path, and is mirrored on the + binding. A named claim's command line and outcomes are unchanged. +- **A resume is named by construction.** `run.start --resume` binds the attributed id up front and + never claims (`resumeAttributed()`); the verdict reads such a record as named from the run-tracker + record itself, never from a claim. +- **Retries and continuations** keep the first claim's mode: the binding is bind-once, and + `run.continue` does not claim. +- **Three modes, three behaviours:** + - **loop-picked** (selection path recorded): a halt adds one to the count and may print `run-next`. + - **named**: a halt never reads or touches the count and prints today's line. + - **unknown**: a halt **adds one to the count** but prints **today's line** with no note. A loop + never carries on without positive evidence, and a named run never sees the new line — safe both + ways. +- A one-off unnamed run ("implement the next change") is selection-path, so it counts like a loop + run. The docs say so. *(Groomer's call, from the review.)* + +### 2. The halt count + +- The run tracker keeps one count of **halts in a row** per repository, in the per-repo state folder + under the git common dir, so every worktree and every session sees the same count (a new Claude Code + session does not reset it). Keep it outside `/run-tracker/` — the precedent is + `acquireResumeLock`'s `run-tracker-resume/` — so the scanners that walk run-key folders never see it. +- `run.verdict` (keyed mode) updates it when it settles a run: + - a `run-halted` outcome on a **loop-picked or unknown** change adds one; + - only a **clean build** resets it to 0: the `run-complete` outcome (a change built to an open PR, + or a results-artifact change completed), **named or loop-picked alike**, since a clean build + proves the setup works; + - every other outcome leaves it unchanged — including `run-unclaimed` and `no-attributable-claim`. + `no-attributable-claim` covers an empty queue, a lost claim race, *and* every pre-claim halt, and + the verdict cannot tell them apart; leaving the count alone means a pre-claim setup failure never + hands the next loop a fresh limit. Also unchanged: `run-incomplete`, `run-continue`, + `run-tracker-unavailable`, `ambiguous-claims`. +- **Once per key, both ways.** A run's effect on the count — an increment *or* a reset — applies at + most once, however often `run.verdict` is re-run for that key. Save the decision (`run-next` or + `run-stop`, and the count it saw) with the counted marker and replay it, so a replay after a later + reset or halt never flips the line, and replaying an old `run-complete` never re-zeroes the count. +- Do **not** derive the count from persisted verdicts: `PruneRunTrackerRecords` deletes terminal + records after 7 days and would silently shrink it. +- Unattributed (`--unattributed`) observe mode never reads or writes the count. +- **One loop per stage.** docket supports one implement loop and one finalize loop at a time (they may + run side by side). Two implement loops at once are unsupported: they would share one count, and a + healthy loop's clean builds would keep resetting a broken loop's halts. No gate prevents it — the + docs state the support boundary instead. *(Human's decision.)* +- `repository.set-visibility` moves the state folder, which effectively resets the count. That only + affects loops; document it. + +### 3. The setting + +- New config key **`run.max_consecutive_halts`**, integer, default **2**, minimum **1**. It layers + like every other key (repo-local > repo-committed > global > built-in). +- `1` reproduces today's behaviour for loops: the first halt stops the loop. +- An invalid value (`0`, `-1`, `"two"`) is a config error exactly like any other int key's (for + example `run.max_attempts: 0` today): it blocks config-reading operations until fixed. That is the + uniform config rule, not a gate this change introduces; never clamp silently. An older binary only + warns about the key as unknown. +- Read it at verdict time, or snapshot it at `run.start` the way `run.max_attempts` is — builder's + call, **subject to *Isolation guarantees***: no record or binding schema bump, and a missing value + falls back to resolved config or the default. + +### 4. The verdict line + +- **Loop-picked halt under the limit** (count after this halt < `run.max_consecutive_halts`): a new + decision, **`run-next run-halted `**. It means: the change needs a person; never + re-dispatch it; a loop driver may start its next run with a fresh `run.start`; a single dispatch + stops, as on `run-stop`. + - It goes through the existing halted branch (`persistRunVerdict`), never `runTrackerCompleteRun`, + and keeps `terminal: true`. The run stays `active` exactly as a halted run does today + (ADR-0148), so resume works unchanged. +- **Loop-picked halt at the limit:** **`run-stop run-halted `**, as today, followed by a + note line telling the coordinating session to ask the person, worded without assuming a loop (for + example: *"2 changes picked from the queue halted in a row. Reset the halt count to 0?"*), with the + reset command and the instruction never to run it without a yes. +- **Named or unknown halt:** exactly today's `run-stop run-halted `, no note. +- JSON gains the decision value `run-next` and fields for the count and the limit (for example + `halts_in_a_row`, `halt_limit`), **on loop-picked verdicts only**. +- No retry is spent on any halt, as today (ADR-0115). + +### 5. Resetting the count + +- New operation **`run.reset-halts`** (`docket run reset-halts`), effect `local-write`. It sets the + count to 0 and reports what it was. It is safe to run at any time, typed by a person or run by the + agent on the person's explicit yes. +- Without a reset, only a clean build (`run-complete`) brings the count back to 0. Consequence the + human accepted: if a loop stopped at the limit and nobody resets, the next loop — in any session — + stops at its first halt. +- An overnight loop gets no answer to the prompt. The loop has already stopped; the question waits + for the person. + +### 6. Where the loop logic lives + +- **Dispatch block** (`internal/assets/embedded/tree/cursor-rules/run-tracker.md`, step 3): one + sentence — `run-next` forbids re-dispatching that change; only a loop driver (`/loop`) may start its + next run with a fresh `run.start`; a single dispatch stops, as on `run-stop`. This is the only + always-loaded addition. Re-sync installs through the normal generator. +- **Verdict output:** the at-limit note carries the reset prompt, read only when it applies. +- **implement-next driver contract** (*Terminal disposition (driver contract)* in + `skills/docket-implement-next/SKILL.md`): the `halted` row's driver action becomes "stop + surface; + a loop whose tracked verdict is `run-next` continues", and the "The driver's decision is binary" + sentence is edited to match. The four dispositions stay four; the child still declares `halted`. An + untracked driver (a person re-issuing the request, or a run without `run.start`) has no verdict and + keeps stopping on `halted`. +- **implement-next selection path:** passes the new claim mode input (§1). The named path passes + nothing. +- Run `go generate ./internal/assets/` after the skill and asset edits. + +## Isolation guarantees (from the design review) + +These are requirements, not suggestions; each closes a path by which the counter could affect a run +that is not a loop-picked halt. + +1. **No schema bump** of the run-tracker record (`runTrackerSchemaVersion`) or the claim binding + (`bindingSchemaVersion`). `decodeRunTrackerRecord` and `readRunTrackerClaimBinding` reject any + other version, so a bump would break every run in flight across the install — named runs, retries + and continuations included (`run-tracker-unavailable corrupt-record`, `run-context-invalid` claims, + `binding-unreadable`). New fields are additive and optional, with **no save-time guard** on them + (unlike `writeRunTrackerRecordAtomic`'s `AttemptLimit < 1` refusal, which a copied guard would turn + into `report-unpersisted` on old-shape records). +2. **Count faults never change a report line.** Failing to read or write the count or the counted + marker never produces `run-tracker-unavailable`: + - on a loop-picked halt, a fault prints today's `run-stop … run-halted `; + - on `run-complete`, the reset is best-effort and happens only after the `run-done` line is final + (after the checked save); if the closeout is blocked, nothing resets; + - named halts do not read the count at all; + - any lock on the count is bounded and never blocks a verdict. +3. **The claim input never refuses** (§1). +4. **A named run can never see `run-next` or the at-limit note** — named and unknown modes print + today's line (§1, §4). + +Per-path result with these in place: + +| Path | Verdict line | Different from today? | +|---|---|---| +| Named run (single id) that halts | `run-stop run-halted ` | No — the count is never read | +| Named run that builds cleanly | `run-done … run-complete` | No — the reset is a best-effort side effect | +| `--resume` | named by construction → today's lines | No | +| `run-retry-once` / `run-continue` of a named run | today's lines | No | +| Untracked run | no verdict; stops on `halted` | No | +| `--unattributed` observe | no count access | No | +| Finalize | not run-tracked | No | +| One-off unnamed run that halts | counts; may print `run-next`, and the coordinator stops | Count only | +| Loop-picked halt | `run-next` under the limit, today's line + note at it | Yes — the feature | + +## Docs + +Describe current behaviour only (no change or PR citations): + +- `docs/guide/building-without-supervision.md` (*Draining the queue hands-free*): the loop carries + past a halted change it picked, up to the limit; which runs count (picked from the queue, including + a one-off unnamed run; not a named run or a resume); what resets the count; how to reset; that + docket supports one loop per stage (one implement loop and one finalize loop at a time, side by side + is fine) and why a second implement loop breaks the halt limit; that `set-visibility` resets the + count and refuses while halted runs are still active (each must be cancelled first — an existing + rule, now with up to the limit's worth of halted runs instead of one). Check the other guides and + concepts for wording that implies concurrent same-stage loops are supported, and correct it. +- `docs/guide/landing-changes.md` (*Closing out hands-free with `/loop`*): it currently says + implement and finalize share one stop rule — finalize still stops on every `halted`; implement's + tracked loop may continue on `run-next`. +- `docs/concepts/run-tracker.md`: the verdict flow diagram gains `run-next`; the halt count. +- `docs/reference/config-keys.md`, `docs/reference/cli.md`, `docs/reference/outcomes.md`, + `docs/reference/glossary.md` as applicable. + +## Constraints + +- The run tracker owns the accounting; the coordinator never counts halts itself (CLAUDE.md run + tracker rules). +- Config keys behave uniformly — no single-layer scoping for the new key. +- No new blocking gate: the limit only *stops a loop*, which is today's behaviour on every halt. +- Guards are mutation-tested; the whole suite runs at the build gate. Each isolation guarantee gets a + test that a named run's verdict line is byte-identical to today's under a count fault, a high count, + and an old-shape record. + +## Left to the builder + +- The on-disk form of the count and its counted markers, within §2 and the isolation guarantees. +- The exact name and values of the claim mode input, the JSON field names, and the exact wording of + the at-limit note, within the meaning above. +- Whether the decision is worth an ADR (likely yes: it amends ADR-0153's "every `halted` stops the + driver" context and extends ADR-0115's run accounting). diff --git a/internal/app/change_claim.go b/internal/app/change_claim.go index 6baa18e62..b385fc867 100644 --- a/internal/app/change_claim.go +++ b/internal/app/change_claim.go @@ -84,6 +84,32 @@ type ChangeClaimRequest struct { // (the digest, and a prefix in the request id — see claimRequestID) and // recorded as the durable claim proof (change 0407). RunContext string `json:"run_context,omitempty"` + // Selection says how the run chose this change: ClaimSelectionQueue (picked + // from the build-ready queue) or ClaimSelectionNamed (the run named it). It is + // optional and never refuses a claim: any other value, or none at all (an + // older skill copy), is recorded as unknown. It is deliberately outside + // claimDigestPayload and claimRequestID, so it never changes claim identity + // or idempotence; it is recorded in the committed receipt and mirrored on the + // run's claim binding, where the keyed verdict reads it when a run halts. + Selection string `json:"selection,omitempty"` +} + +// The recognised claim selections. Anything else normalizes to "" (unknown). +const ( + ClaimSelectionQueue = "queue" + ClaimSelectionNamed = "named" +) + +// claimSelection normalizes a caller-supplied selection: a recognised mode +// (after trimming surrounding space) passes through, anything else is "" — +// unknown, never a refusal. +func claimSelection(raw string) string { + switch v := strings.TrimSpace(raw); v { + case ClaimSelectionQueue, ClaimSelectionNamed: + return v + default: + return "" + } } // claimDigestPayload is the semantic content of a claim request — everything @@ -159,7 +185,12 @@ type changeClaimReceipt struct { ID int `json:"id"` Lease string `json:"lease"` Op string `json:"op"` - Status string `json:"status"` + // Selection is how the run chose this change (claimSelection's normalized + // value), omitted when unknown so an unknown claim's receipt is byte-identical + // to one written before the field existed. Placed between op and status to + // keep the json keys alphabetical. + Selection string `json:"selection,omitempty"` + Status string `json:"status"` } // ChangeClaim validates the request, pins authoritative context, fetches the @@ -202,6 +233,7 @@ func ChangeClaim(ctx context.Context, deps PlanningDeps, repoDir string, req Cha // is a typed refusal — never an ungated claim — and the gatedrive scope // capability the test-drive operations consume is untouched. var runKey, gateHash string + sel := claimSelection(req.Selection) if req.RunContext != "" { gateHash = runTrackerHashToken(req.RunContext) key, gateRec, ferr := FindRunTrackerRecordByContextHash(repoDir, gateHash) @@ -224,7 +256,7 @@ func ChangeClaim(ctx context.Context, deps PlanningDeps, repoDir string, req Cha }) } runKey = key - if rerr := ReserveRunTrackerClaim(repoDir, runKey, req.ID, claimRequestID(req)); rerr != nil { + if rerr := ReserveRunTrackerClaimSelection(repoDir, runKey, req.ID, claimRequestID(req), sel); rerr != nil { return newChangeClaimResult(OperationChangeClaim, ResultInvalidState, ChangeClaimResult{ Disposition: ClaimDispositionRunContextConflict, Findings: []StatusFinding{lifecycleFinding(FindingCode(ClaimDispositionRunContextConflict), @@ -250,6 +282,7 @@ func ChangeClaim(ctx context.Context, deps PlanningDeps, repoDir string, req Cha link: linkContextOf(pin), changesDir: eff.ChangesDir.Value, runContextHash: gateHash, + selection: sel, } res, execErr := deps.Engine.Execute(ctx, transaction.Request{ @@ -565,6 +598,9 @@ type changeClaimOp struct { // receipt as the durable ownership proof (change 0407); the raw token never // reaches this struct. runContextHash string + // selection is the normalized claim selection ("" = unknown, and always "" + // for a refresh), folded into the committed claim receipt. + selection string } func (o changeClaimOp) Key() transaction.OperationKey { return transaction.OperationKey(o.opKey) } @@ -687,6 +723,7 @@ func (o changeClaimOp) Plan(ctx context.Context, st transaction.AttemptState) (t ID: o.changeID, Lease: lease, Op: o.opKey, + Selection: o.selection, Status: string(result.Change.Status()), }) if err != nil { diff --git a/internal/app/change_claim_integration_test.go b/internal/app/change_claim_integration_test.go index 9584b2eeb..884a106cb 100644 --- a/internal/app/change_claim_integration_test.go +++ b/internal/app/change_claim_integration_test.go @@ -153,6 +153,73 @@ func TestIntegrationRecordOpsClaimRunContextReservesAndConfirms(t *testing.T) { } } +// TestIntegrationRecordOpsClaimSelectionRecordedInBindingAndReceipt: the +// optional selection input records how the change was chosen on the run's +// claim binding and in the committed receipt. "queue" and "named" pass through; +// anything else (an unrecognised value, or nothing at all from an older skill +// copy) is recorded as unknown (""). It never refuses a claim and never touches +// claim identity: the digest and request id are exactly what they were without it. +func TestIntegrationRecordOpsClaimSelectionRecordedInBindingAndReceipt(t *testing.T) { + for _, tc := range []struct{ in, want string }{ + {"queue", ClaimSelectionQueue}, + {"named", ClaimSelectionNamed}, + {" queue ", ClaimSelectionQueue}, + {"loop", ""}, + {"", ""}, + } { + t.Run(fmt.Sprintf("%q", tc.in), func(t *testing.T) { + repoDir := newRunTrackerRepo(t) + hash := runTrackerHashToken("tok") + key := mintRunTrackerWithHash(t, repoDir, hash, false) + engine := &claimGateEngine{result: appliedGateResult(t, 3)} + deps := gateClaimDeps(t, engine, []StatusBlob{changeBlob(3, "widget", "feat", "high", "")}) + + res := ChangeClaim(context.Background(), deps, repoDir, + ChangeClaimRequest{ID: 3, Revision: gateClaimRevision, RunContext: "tok", Selection: tc.in}) + if res.Result != ResultApplied { + t.Fatalf("result = %q, want applied — the selection input never refuses (findings %v)", res.Result, res.Findings) + } + + b, ok, err := LoadRunTrackerClaimBinding(repoDir, key) + if err != nil || !ok || !b.Confirmed || b.Selection != tc.want { + t.Fatalf("post-claim binding = %+v ok=%v err=%v; want confirmed with selection %q", b, ok, err, tc.want) + } + + if len(engine.calls) != 1 { + t.Fatalf("engine calls = %d, want 1", len(engine.calls)) + } + wantDigest, err := canonicalDigest(OperationChangeClaim, claimDigestPayload{ID: 3, Revision: gateClaimRevision, RunContextHash: hash}) + if err != nil { + t.Fatalf("canonicalDigest: %v", err) + } + if got := engine.calls[0].Idempotency.Digest; got != wantDigest { + t.Errorf("digest = %q, want %q (selection must not change claim identity)", got, wantDigest) + } + wantRID := claimRequestID(ChangeClaimRequest{ID: 3, Revision: gateClaimRevision, RunContext: "tok"}) + if got := engine.calls[0].Idempotency.RequestID; got != wantRID { + t.Errorf("request id = %q, want %q (selection must not change claim identity)", got, wantRID) + } + + op := engine.calls[0].Operation.(changeClaimOp) + if op.selection != tc.want { + t.Errorf("op.selection = %q, want %q", op.selection, tc.want) + } + plan, opRes := claimPlanFor(t, map[string]string{groomPath(3, "widget"): claimableChange(3, "widget")}, op) + if opRes.Refused { + t.Fatalf("unexpected refusal building the receipt: %v", opRes.Findings) + } + receipt := string(plan.Receipt) + if tc.want != "" { + if !strings.Contains(receipt, `"selection":"`+tc.want+`"`) { + t.Errorf("receipt missing selection %q:\n%s", tc.want, receipt) + } + } else if strings.Contains(receipt, `"selection"`) { + t.Errorf("unknown selection must leave no selection key in the receipt:\n%s", receipt) + } + }) + } +} + // TestIntegrationRecordOpsClaimRunContextConflictRefused: a second claim for a DIFFERENT change id // under the same context is refused run-context-conflict before its // transaction (criterion 3: one context cannot claim two changes). diff --git a/internal/app/claim_proof.go b/internal/app/claim_proof.go index 4a9104daa..e04b9b6fb 100644 --- a/internal/app/claim_proof.go +++ b/internal/app/claim_proof.go @@ -36,6 +36,7 @@ type ClaimProof struct { ChangeID int // receipt id RunContextHash string // receipt gate_context_hash ("" = ungated claim) Revision string // commit hash carrying the receipt + Selection string // receipt selection: how the run chose the change ("" = unknown) } // ClaimProofScanner is the verdict path's read-only seam onto committed claim @@ -119,6 +120,7 @@ func (s gitClaimProofScanner) ScanClaimProofs(ctx context.Context, repoDir strin ChangeID: rec.ID, RunContextHash: rec.RunContextHash, Revision: string(ct.Commit), + Selection: rec.Selection, }) } return proofs, nil diff --git a/internal/app/claim_proof_git_integration_test.go b/internal/app/claim_proof_git_integration_test.go index 8e08fcbbb..75158a5d3 100644 --- a/internal/app/claim_proof_git_integration_test.go +++ b/internal/app/claim_proof_git_integration_test.go @@ -29,6 +29,7 @@ type wireClaimReceipt struct { ID int `json:"id"` Lease string `json:"lease"` Op string `json:"op"` + Selection string `json:"selection,omitempty"` Status string `json:"status"` } @@ -123,3 +124,49 @@ func TestIntegrationRecordOpsScanClaimProofsReadsCommittedReceipt(t *testing.T) } } } + +// TestIntegrationRecordOpsScanClaimProofsReadsSelection: the selection a claim +// recorded in its committed receipt is read back onto the proof, so the verdict's +// receipt-recovery path keeps how the change was chosen; a receipt without one +// (an older claim, or an unknown selection) reads back as "". +func TestIntegrationRecordOpsScanClaimProofsReadsSelection(t *testing.T) { + repo := newRunTrackerRepo(t) + + commitClaimTrailers(t, repo, "claim 3", + "Docket-Transaction-ID: t1", + "Docket-Operation: "+OperationChangeClaim, + "Docket-Request-ID: claim-3-v1", + "Docket-Request-Digest: sha256:aaaa", + "Docket-Result: "+encodeClaimReceipt(t, wireClaimReceipt{ + Branch: "fix/x", ClaimedAt: "2026-09-07T00:00:00Z", RunContextHash: "h3", + ID: 3, Lease: "live", Op: OperationChangeClaim, Status: "in-progress", + })) + tip := commitClaimTrailers(t, repo, "claim 4", + "Docket-Transaction-ID: t2", + "Docket-Operation: "+OperationChangeClaim, + "Docket-Request-ID: claim-4-v2", + "Docket-Request-Digest: sha256:bbbb", + "Docket-Result: "+encodeClaimReceipt(t, wireClaimReceipt{ + Branch: "fix/y", ClaimedAt: "2026-09-07T01:00:00Z", RunContextHash: "h4", + ID: 4, Lease: "live", Op: OperationChangeClaim, Selection: ClaimSelectionQueue, Status: "in-progress", + })) + + deps := PlanningDeps{ + Client: newGitClient(t), + Reader: &fakeChangeReader{pin: StatusPin{MetadataRevision: tip}}, + Clock: testClock(), + } + proofs, err := NewClaimProofScanner(deps).ScanClaimProofs(context.Background(), repo) + if err != nil { + t.Fatalf("ScanClaimProofs: %v", err) + } + if len(proofs) != 2 { + t.Fatalf("got %d proofs, want 2:\n%+v", len(proofs), proofs) + } + if proofs[0].ChangeID != 4 || proofs[0].Selection != ClaimSelectionQueue { + t.Errorf("newest proof = %+v, want change 4 with selection queue", proofs[0]) + } + if proofs[1].ChangeID != 3 || proofs[1].Selection != "" { + t.Errorf("older proof = %+v, want change 3 with no selection", proofs[1]) + } +} diff --git a/internal/app/config.go b/internal/app/config.go index 4ddf7adef..e8aa34b46 100644 --- a/internal/app/config.go +++ b/internal/app/config.go @@ -250,6 +250,7 @@ func effectiveLines(eff *config.Effective) []effectiveLine { leafLine("build.test_command", textValue(eff.Build.TestCommand.Value), eff.Build.TestCommand.Provenance), leafLine("build.max_attempts", strconv.Itoa(eff.Build.MaxAttempts.Value), eff.Build.MaxAttempts.Provenance), leafLine("run.max_attempts", strconv.Itoa(eff.Run.MaxAttempts.Value), eff.Run.MaxAttempts.Provenance), + leafLine("run.max_consecutive_halts", strconv.Itoa(eff.Run.MaxConsecutiveHalts.Value), eff.Run.MaxConsecutiveHalts.Provenance), leafLine("learnings.enabled", strconv.FormatBool(eff.Learnings.Enabled.Value), eff.Learnings.Enabled.Provenance), leafLine("reclaim.lease_ttl", strconv.Itoa(eff.Reclaim.LeaseTTL.Value), eff.Reclaim.LeaseTTL.Provenance), leafLine("reclaim.auto", strconv.FormatBool(eff.Reclaim.Auto.Value), eff.Reclaim.Auto.Provenance), diff --git a/internal/app/config_test.go b/internal/app/config_test.go index 437684e8a..b0aba2f36 100644 --- a/internal/app/config_test.go +++ b/internal/app/config_test.go @@ -809,6 +809,12 @@ func TestConfigDiagnosticsAttemptLimitsSurface(t *testing.T) { if h := def.HumanText(); !strings.Contains(h, "run.max_attempts = 2 [built-in]") { t.Errorf("human effective block lacks the built-in run attempt-limit line:\n%s", h) } + if got := def.Effective.Run.MaxConsecutiveHalts.Value; got != 2 { + t.Errorf("effective JSON run.max_consecutive_halts = %d, want the built-in default 2", got) + } + if h := def.HumanText(); !strings.Contains(h, "run.max_consecutive_halts = 2 [built-in]") { + t.Errorf("human effective block lacks the built-in run halt-limit line:\n%s", h) + } // Explicit repository-layer settings → 6/3 on both halves. sources := []config.Source{{ diff --git a/internal/app/runtracker_halts.go b/internal/app/runtracker_halts.go new file mode 100644 index 000000000..53d5eb660 --- /dev/null +++ b/internal/app/runtracker_halts.go @@ -0,0 +1,408 @@ +// The per-repository halt count: how many implement-next runs in a row ended in a +// halt. A tracked loop reads it to decide whether a halt on a change it picked from +// the queue lets it move on (run-next) or stops it (run-stop) once the count reaches +// run.max_consecutive_halts. A clean build (run-complete) and the run.reset-halts +// operation bring it back to 0. +// +// WHERE: /run-tracker-halts/, beside — never inside — the +// run-tracker root. The scanners that walk run-key directories under run-tracker/ +// therefore never see it, for the same reason acquireResumeLock keeps its locks under +// run-tracker-resume/. The folder holds: +// +// count.json {"schema":1,"halts_in_a_row":N} +// counted/.halt.json the saved haltCounted outcome of that key's halt +// counted/.reset.json {"schema":1}: that key's run-complete already reset the count +// lock the flock file serializing every read-modify-write +// +// ONCE PER KEY: a key's halt is counted at most once and its run-complete resets at +// most once. A replayed recordHalt returns the saved outcome unchanged, so re-running +// a verdict after the count moved (a reset, other halts) never flips run-next and +// run-stop; a replayed recordReset never re-zeroes a count that has since grown. +// +// FAULTS: a count that cannot be read is an error, never read as 0, and every +// failure leaves the files as they were. The lock wait is bounded by haltLockWait, so +// a holder that never lets go turns into errHaltCountBusy instead of a hung verdict. +// Callers treat any error here as "print today's line". +// +// CRASH ORDERS: every file is replaced through a same-directory temp file and a +// rename, so a reader sees a whole old or new document. Between two writes a crash +// can still leave one done without the other, and each order is chosen so the +// leftover state stops a loop sooner, never later: +// - recordHalt writes the count first, then the marker. A crash between them +// re-counts that key on replay: an over-count. +// - recordReset writes the marker first, then the zero count. A crash between them +// leaves the count high. +package app + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "syscall" + "time" +) + +const ( + runTrackerHaltsDirName = "run-tracker-halts" + haltCountFileName = "count.json" + haltCountedDirName = "counted" + haltLockFileName = "lock" + haltMarkerSuffix = ".halt.json" + resetMarkerSuffix = ".reset.json" + haltStoreSchema = 1 + haltLockPoll = 20 * time.Millisecond +) + +// haltLockWait bounds how long any halt-count operation waits for the lock before it +// gives up with errHaltCountBusy. Tests shorten it (restoring it in t.Cleanup) and +// never run in parallel while they do. +var haltLockWait = 2 * time.Second + +// errHaltCountBusy reports that another process held the halt-count lock for longer +// than haltLockWait. +var errHaltCountBusy = errors.New("halt count busy") + +// OperationRunResetHalts is the operation key `run reset-halts` records in its envelope. +const OperationRunResetHalts = "run.reset-halts" + +// RunResetHaltsResult is the outcome of run.reset-halts. Previous is the count before +// the reset; PreviousUnreadable marks a count that could not be read (and that the +// reset repaired). A failed reset carries a Reason token and a Message. +type RunResetHaltsResult struct { + Envelope + Previous int `json:"previous"` + PreviousUnreadable bool `json:"previous_unreadable,omitempty"` + Reason string `json:"reason,omitempty"` + Message string `json:"message,omitempty"` +} + +// HumanText renders the one-line outcome. +func (r RunResetHaltsResult) HumanText() string { + if r.Result == ResultApplied { + if r.PreviousUnreadable { + return "halt count reset to 0 (the previous count was unreadable)" + } + return fmt.Sprintf("halt count reset to 0 (was %d)", r.Previous) + } + return fmt.Sprintf("%s: %s (%s)", OperationRunResetHalts, r.Result, r.Reason) +} + +// RunResetHalts sets repoDir's halt count back to 0, the person's way to let a loop +// stopped at run.max_consecutive_halts carry on. A count that cannot be read is +// repaired by the same write. Markers stay, so a key already counted is never +// counted again. +func RunResetHalts(repoDir string) RunResetHaltsResult { + fail := func(result Result, reason string, err error) RunResetHaltsResult { + r := RunResetHaltsResult{Reason: reason, Message: err.Error()} + r.Envelope = NewEnvelope(OperationRunResetHalts, result) + return r + } + s, err := openHaltCountStore(repoDir) + if err != nil { + return fail(ResultInvalidState, "run-tracker-unavailable", err) + } + previous, unreadable, err := s.resetAll() + if errors.Is(err, errHaltCountBusy) { + return fail(ResultContended, "halt-count-busy", err) + } + if err != nil { + return fail(ResultInternalError, "halt-count-unwritable", err) + } + r := RunResetHaltsResult{Previous: previous, PreviousUnreadable: unreadable} + r.Envelope = NewEnvelope(OperationRunResetHalts, ResultApplied) + return r +} + +// haltCountStore is the halt-count folder of one repository. +type haltCountStore struct{ dir string } + +// haltCounted is the saved outcome of one key's halt. Decision is RunDecisionNext or +// RunDecisionStop for a loop-picked halt and empty when the run's mode is unknown; +// Noted marks a run-stop at the limit, which carries the reset note. +type haltCounted struct { + Schema int `json:"schema"` + Decision string `json:"decision,omitempty"` + HaltsInARow int `json:"halts_in_a_row"` + HaltLimit int `json:"halt_limit,omitempty"` + Noted bool `json:"noted,omitempty"` +} + +// haltCountFile is the on-disk shape of count.json. Pointer fields let readHaltCount +// tell a missing field from a zero one. +type haltCountFile struct { + Schema *int `json:"schema"` + HaltsInARow *int `json:"halts_in_a_row"` +} + +// haltResetMarker is the on-disk shape of a counted/.reset.json marker. +type haltResetMarker struct { + Schema int `json:"schema"` +} + +// haltCountStoreAt returns the halt-count store under stateDir, a per-repo state +// folder. It touches nothing on disk. +func haltCountStoreAt(stateDir string) haltCountStore { + return haltCountStore{dir: filepath.Join(stateDir, runTrackerHaltsDirName)} +} + +// openHaltCountStore resolves the halt-count store for repoDir through +// runTrackerStateDir. It resolves, never creates: nothing is written until a +// recording operation runs. +func openHaltCountStore(repoDir string) (haltCountStore, error) { + state, err := runTrackerStateDir(repoDir) + if err != nil { + return haltCountStore{}, err + } + return haltCountStoreAt(state), nil +} + +// recordHalt counts key's halt once and returns its outcome. For a loop-picked halt +// the outcome carries the decision against limit: run-next while the new count stays +// under limit, otherwise run-stop with Noted. An unknown-mode halt (loopPicked false) +// still counts, with no decision. A key already counted returns its saved outcome +// unchanged and writes nothing. +func (s haltCountStore) recordHalt(key string, loopPicked bool, limit int) (haltCounted, error) { + if err := validateRunKey(key); err != nil { + return haltCounted{}, err + } + if loopPicked && limit < 1 { + return haltCounted{}, fmt.Errorf("halt count: a loop-picked halt needs a limit of 1 or more, got %d", limit) + } + unlock, err := s.lock() + if err != nil { + return haltCounted{}, err + } + defer unlock() + + markerPath := s.markerPath(key, haltMarkerSuffix) + saved, found, err := readHaltMarker(markerPath) + if err != nil { + return haltCounted{}, err + } + if found { + return saved, nil + } + n, err := s.readCount() + if err != nil { + return haltCounted{}, err + } + n++ + out := haltCounted{Schema: haltStoreSchema, HaltsInARow: n} + if loopPicked { + out.HaltLimit = limit + if n < limit { + out.Decision = RunDecisionNext + } else { + out.Decision = RunDecisionStop + out.Noted = true + } + } + // Count first, then the marker: a crash between them over-counts on replay. + if err := s.writeCount(n); err != nil { + return haltCounted{}, err + } + if err := writeHaltJSONAtomic(markerPath, out); err != nil { + return haltCounted{}, err + } + return out, nil +} + +// recordReset zeroes the count once for key's run-complete. A key that already reset +// the count is a no-op, so an old run-complete replayed never re-zeroes a count that +// has grown since. +func (s haltCountStore) recordReset(key string) error { + if err := validateRunKey(key); err != nil { + return err + } + unlock, err := s.lock() + if err != nil { + return err + } + defer unlock() + + markerPath := s.markerPath(key, resetMarkerSuffix) + found, err := readResetMarker(markerPath) + if err != nil { + return err + } + if found { + return nil + } + // Marker first, then the zero count: a crash between them leaves the count high. + if err := writeHaltJSONAtomic(markerPath, haltResetMarker{Schema: haltStoreSchema}); err != nil { + return err + } + return s.writeCount(0) +} + +// resetAll sets the count to 0 and reports what it was. A count that cannot be read +// reports unreadable (previous 0) and is repaired by the same write. Markers stay, so +// keys already counted stay counted. +func (s haltCountStore) resetAll() (previous int, unreadable bool, err error) { + unlock, err := s.lock() + if err != nil { + return 0, false, err + } + defer unlock() + + previous, rerr := s.readCount() + if rerr != nil { + previous, unreadable = 0, true + } + if err := s.writeCount(0); err != nil { + return 0, unreadable, err + } + return previous, unreadable, nil +} + +// count reads the current count without taking the lock (tests and diagnostics). A +// missing count is 0; an unreadable one is an error. +func (s haltCountStore) count() (int, error) { + return s.readCount() +} + +// lock takes the exclusive halt-count lock, polling a non-blocking flock until +// haltLockWait elapses. The returned func releases it. +func (s haltCountStore) lock() (func(), error) { + if err := os.MkdirAll(filepath.Join(s.dir, haltCountedDirName), 0o700); err != nil { + return nil, fmt.Errorf("halt count: create folder: %w", err) + } + f, err := os.OpenFile(filepath.Join(s.dir, haltLockFileName), os.O_CREATE|os.O_RDWR, 0o600) + if err != nil { + return nil, fmt.Errorf("halt count: open lock: %w", err) + } + deadline := time.Now().Add(haltLockWait) + for { + err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB) + if err == nil { + break + } + if !errors.Is(err, syscall.EWOULDBLOCK) && !errors.Is(err, syscall.EINTR) { + f.Close() + return nil, fmt.Errorf("halt count: lock: %w", err) + } + if !time.Now().Before(deadline) { + f.Close() + return nil, errHaltCountBusy + } + time.Sleep(haltLockPoll) + } + return func() { + _ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN) + f.Close() + }, nil +} + +func (s haltCountStore) markerPath(key, suffix string) string { + return filepath.Join(s.dir, haltCountedDirName, key+suffix) +} + +// readCount reads count.json: missing is 0; unparseable, a wrong or missing schema, +// or a missing or negative count is an error, never 0. +func (s haltCountStore) readCount() (int, error) { + buf, err := os.ReadFile(filepath.Join(s.dir, haltCountFileName)) + if errors.Is(err, fs.ErrNotExist) { + return 0, nil + } + if err != nil { + return 0, fmt.Errorf("halt count: read: %w", err) + } + var c haltCountFile + if err := decodeHaltJSON(buf, &c); err != nil { + return 0, fmt.Errorf("halt count: unreadable %s: %w", haltCountFileName, err) + } + if c.Schema == nil || *c.Schema != haltStoreSchema { + return 0, fmt.Errorf("halt count: %s has an unknown schema", haltCountFileName) + } + if c.HaltsInARow == nil || *c.HaltsInARow < 0 { + return 0, fmt.Errorf("halt count: %s has no valid count", haltCountFileName) + } + return *c.HaltsInARow, nil +} + +func (s haltCountStore) writeCount(n int) error { + schema := haltStoreSchema + return writeHaltJSONAtomic(filepath.Join(s.dir, haltCountFileName), haltCountFile{Schema: &schema, HaltsInARow: &n}) +} + +// readHaltMarker reads a saved halt outcome. A missing marker is (zero, false, nil); +// an unreadable one is an error, never treated as absent. +func readHaltMarker(path string) (haltCounted, bool, error) { + buf, err := os.ReadFile(path) + if errors.Is(err, fs.ErrNotExist) { + return haltCounted{}, false, nil + } + if err != nil { + return haltCounted{}, false, fmt.Errorf("halt count: read marker: %w", err) + } + var out haltCounted + if err := decodeHaltJSON(buf, &out); err != nil { + return haltCounted{}, false, fmt.Errorf("halt count: unreadable marker %s: %w", filepath.Base(path), err) + } + if out.Schema != haltStoreSchema { + return haltCounted{}, false, fmt.Errorf("halt count: marker %s has an unknown schema", filepath.Base(path)) + } + return out, true, nil +} + +// readResetMarker reports whether a reset marker exists. An unreadable one is an +// error, never treated as absent. +func readResetMarker(path string) (bool, error) { + buf, err := os.ReadFile(path) + if errors.Is(err, fs.ErrNotExist) { + return false, nil + } + if err != nil { + return false, fmt.Errorf("halt count: read marker: %w", err) + } + var m haltResetMarker + if err := decodeHaltJSON(buf, &m); err != nil { + return false, fmt.Errorf("halt count: unreadable marker %s: %w", filepath.Base(path), err) + } + if m.Schema != haltStoreSchema { + return false, fmt.Errorf("halt count: marker %s has an unknown schema", filepath.Base(path)) + } + return true, nil +} + +// decodeHaltJSON decodes exactly one JSON document into v, refusing trailing data. +func decodeHaltJSON(buf []byte, v any) error { + dec := json.NewDecoder(bytes.NewReader(buf)) + if err := dec.Decode(v); err != nil { + return err + } + if dec.More() { + return errors.New("trailing data") + } + return nil +} + +// writeHaltJSONAtomic replaces path with v's JSON through a same-directory temp file +// and a rename, so a reader sees a whole old or new document. +func writeHaltJSONAtomic(path string, v any) error { + buf, err := json.Marshal(v) + if err != nil { + return fmt.Errorf("halt count: encode: %w", err) + } + tmp, err := os.CreateTemp(filepath.Dir(path), "."+filepath.Base(path)+".tmp-*") + if err != nil { + return fmt.Errorf("halt count: write: %w", err) + } + tmpName := tmp.Name() + defer os.Remove(tmpName) // no-op after a successful rename + if _, err := tmp.Write(buf); err != nil { + tmp.Close() + return fmt.Errorf("halt count: write: %w", err) + } + if err := tmp.Close(); err != nil { + return fmt.Errorf("halt count: write: %w", err) + } + if err := os.Rename(tmpName, path); err != nil { + return fmt.Errorf("halt count: write: %w", err) + } + return nil +} diff --git a/internal/app/runtracker_halts_integration_test.go b/internal/app/runtracker_halts_integration_test.go new file mode 100644 index 000000000..82b034d21 --- /dev/null +++ b/internal/app/runtracker_halts_integration_test.go @@ -0,0 +1,499 @@ +//go:build integration + +package app + +import ( + "context" + "errors" + "io/fs" + "os" + "path/filepath" + "strconv" + "strings" + "sync/atomic" + "syscall" + "testing" + "time" +) + +// These are the keyed run.verdict tests for the halt count: a halt on a change a +// loop picked from the queue prints run-next while the count of halts in a row +// stays under run.max_consecutive_halts, and run-stop plus a reset note at it. +// Every other path — a named run, a resume, an unknown-mode claim, a count fault, +// observe mode — prints exactly today's line, and only a clean build resets the +// count. The halts are reader-only RunVerify short-circuits over a "## Run halted" +// in-progress blob (runTrackerHaltedInProgressBlob). + +var haltLoopRunSeq atomic.Int64 + +// haltLoopRun mints a fresh started run for change id whose confirmed binding carries +// selection, and returns its key plus a WorkspaceDeps whose proof scanner names that +// claim. An empty selection reserves through the legacy ReserveRunTrackerClaim, the +// shape every binding written before the selection field had. +func haltLoopRun(t *testing.T, repo string, id int, selection string) (string, WorkspaceDeps) { + t.Helper() + hash := "halt-hash-" + strconv.FormatInt(haltLoopRunSeq.Add(1), 10) + key := runTrackerMintStarted(t, repo, nil, 1, hash) + requestID := "claim-" + strconv.Itoa(id) + "-" + key + if selection == "" { + must(t, ReserveRunTrackerClaim(repo, key, id, requestID)) + } else { + must(t, ReserveRunTrackerClaimSelection(repo, key, id, requestID, selection)) + } + revision := "r" + strconv.Itoa(id) + must(t, ConfirmRunTrackerClaim(repo, key, id, requestID, revision, "")) + wdeps := WorkspaceDeps{ClaimProofs: &fakeProofScanner{proofs: []ClaimProof{ + {RequestID: requestID, ChangeID: id, RunContextHash: hash, Revision: revision}, + }}} + return key, wdeps +} + +// haltVerdictDeps is the reader-only deps over halted changes 3 and 4, with the +// built-in run.max_consecutive_halts (2). +func haltVerdictDeps(t *testing.T) PlanningDeps { + t.Helper() + return runTrackerLightDeps(t, []StatusBlob{runTrackerHaltedInProgressBlob(3, rvSlug), runTrackerHaltedInProgressBlob(4, "other-change")}) +} + +// haltVerdictDepsLimit is haltVerdictDeps with run.max_consecutive_halts pinned to limit. +func haltVerdictDepsLimit(t *testing.T, limit int) PlanningDeps { + t.Helper() + pin := mainPin(t) + pin.Config.Effective.Run.MaxConsecutiveHalts.Value = limit + return PlanningDeps{Reader: &fakeReader{pin: pin, corpus: []StatusBlob{ + runTrackerHaltedInProgressBlob(3, rvSlug), runTrackerHaltedInProgressBlob(4, "other-change"), + }}, Clock: testClock()} +} + +func haltStoreOf(t *testing.T, repo string) haltCountStore { + t.Helper() + s, err := openHaltCountStore(repo) + if err != nil { + t.Fatalf("openHaltCountStore: %v", err) + } + return s +} + +func haltCountOf(t *testing.T, repo string) int { + t.Helper() + n, err := haltStoreOf(t, repo).count() + if err != nil { + t.Fatalf("count(): %v", err) + } + return n +} + +// seedHaltCount counts n unknown-mode halts under keys s0..s. +func seedHaltCount(t *testing.T, repo string, n int) { + t.Helper() + s := haltStoreOf(t, repo) + for i := 0; i < n; i++ { + if _, err := s.recordHalt("s"+strconv.Itoa(i), false, 0); err != nil { + t.Fatalf("seed recordHalt: %v", err) + } + } + if got := haltCountOf(t, repo); got != n { + t.Fatalf("seeded count = %d, want %d", got, n) + } +} + +// haltsDirAbsent asserts that nothing ever created the repository's halt-count folder. +func haltsDirAbsent(t *testing.T, repo string) { + t.Helper() + s := haltStoreOf(t, repo) + if _, err := os.Stat(s.dir); !errors.Is(err, fs.ErrNotExist) { + t.Fatalf("halt-count folder %s exists (stat err %v): the count was opened", s.dir, err) + } +} + +func persistedDisposition(t *testing.T, repo, key string) string { + t.Helper() + rec, err := LoadRunTrackerRecord(repo, key) + if err != nil { + t.Fatalf("LoadRunTrackerRecord: %v", err) + } + return rec.Disposition +} + +func TestIntegrationRunVerdictHaltLoopPickedUnderLimitPrintsRunNext(t *testing.T) { + repo := newRunTrackerRepo(t) + key, wdeps := haltLoopRun(t, repo, 3, ClaimSelectionQueue) + if _, err := MintRunRecord(repo, key, "3"); err != nil { + t.Fatalf("MintRunRecord: %v", err) + } + + res := RunVerdict(context.Background(), haltVerdictDeps(t), wdeps, GitHubDeps{}, repo, key) + want := "run-next " + key + " run-halted 3" + if got := res.HumanText(); got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if !res.Terminal || res.HaltsInARow != 1 || res.HaltLimit != 2 || res.Note != "" { + t.Fatalf("terminal/halts/limit/note = %v/%d/%d/%q, want true/1/2/empty", res.Terminal, res.HaltsInARow, res.HaltLimit, res.Note) + } + if got := persistedDisposition(t, repo, key); got != want { + t.Fatalf("persisted Disposition = %q, want %q", got, want) + } + used, err := RunTrackerRetryUsage(repo, key) + if err != nil || used != 0 { + t.Fatalf("RunTrackerRetryUsage = %d, %v; a halt must never spend a retry", used, err) + } + if st := loadRunState(t, repo, key); st != RunActive { + t.Fatalf("run state = %q, want active (a halted run waits for a person)", st) + } + if got := haltCountOf(t, repo); got != 1 { + t.Fatalf("count = %d, want 1", got) + } +} + +func TestIntegrationRunVerdictHaltLoopPickedAtLimitStopsWithNote(t *testing.T) { + repo := newRunTrackerRepo(t) + deps := haltVerdictDeps(t) + k1, w1 := haltLoopRun(t, repo, 3, ClaimSelectionQueue) + if got := RunVerdict(context.Background(), deps, w1, GitHubDeps{}, repo, k1).HumanText(); got != "run-next "+k1+" run-halted 3" { + t.Fatalf("first halt = %q, want run-next", got) + } + k2, w2 := haltLoopRun(t, repo, 4, ClaimSelectionQueue) + res := RunVerdict(context.Background(), deps, w2, GitHubDeps{}, repo, k2) + line := "run-stop " + k2 + " run-halted 4" + if got := res.reportLine(); got != line { + t.Fatalf("reportLine = %q, want %q", got, line) + } + if !strings.Contains(res.Note, "run.reset-halts") || !strings.Contains(res.Note, "Never") { + t.Fatalf("Note = %q, want it to name run.reset-halts and forbid a reset without a yes", res.Note) + } + if got := res.HumanText(); got != line+"\n"+res.Note { + t.Fatalf("HumanText = %q, want the line then the note", got) + } + if res.HaltsInARow != 2 || res.HaltLimit != 2 { + t.Fatalf("halts/limit = %d/%d, want 2/2", res.HaltsInARow, res.HaltLimit) + } + if got := persistedDisposition(t, repo, k2); got != line { + t.Fatalf("persisted Disposition = %q, want the report line only %q", got, line) + } +} + +func TestIntegrationRunVerdictHaltReplayNeverFlips(t *testing.T) { + repo := newRunTrackerRepo(t) + deps := haltVerdictDeps(t) + k1, w1 := haltLoopRun(t, repo, 3, ClaimSelectionQueue) + first := RunVerdict(context.Background(), deps, w1, GitHubDeps{}, repo, k1) + if first.Decision != RunDecisionNext { + t.Fatalf("first k1 decision = %q, want run-next", first.Decision) + } + k2, w2 := haltLoopRun(t, repo, 4, ClaimSelectionQueue) + atLimit := RunVerdict(context.Background(), deps, w2, GitHubDeps{}, repo, k2) + if atLimit.Decision != RunDecisionStop || atLimit.Note == "" { + t.Fatalf("first k2 = %q/%q, want run-stop with a note", atLimit.Decision, atLimit.Note) + } + + if _, _, err := haltStoreOf(t, repo).resetAll(); err != nil { + t.Fatalf("resetAll: %v", err) + } + // Replays after the count moved — and under a different limit — keep the saved line. + for _, d := range []PlanningDeps{deps, haltVerdictDepsLimit(t, 1), haltVerdictDepsLimit(t, 9)} { + if got := RunVerdict(context.Background(), d, w1, GitHubDeps{}, repo, k1); got.HumanText() != first.HumanText() || got.HaltsInARow != 1 { + t.Fatalf("k1 replay = %q (halts %d), want %q (halts 1)", got.HumanText(), got.HaltsInARow, first.HumanText()) + } + if got := RunVerdict(context.Background(), d, w2, GitHubDeps{}, repo, k2); got.HumanText() != atLimit.HumanText() || got.HaltsInARow != 2 { + t.Fatalf("k2 replay = %q (halts %d), want %q (halts 2)", got.HumanText(), got.HaltsInARow, atLimit.HumanText()) + } + } + if got := haltCountOf(t, repo); got != 0 { + t.Fatalf("count after replays = %d, want 0 (a replay never re-counts)", got) + } +} + +func TestIntegrationRunVerdictHaltNamedNeverTouchesCount(t *testing.T) { + t.Run("high count", func(t *testing.T) { + repo := newRunTrackerRepo(t) + seedHaltCount(t, repo, 5) + key, wdeps := haltLoopRun(t, repo, 3, ClaimSelectionNamed) + res := RunVerdict(context.Background(), haltVerdictDeps(t), wdeps, GitHubDeps{}, repo, key) + if got, want := res.HumanText(), "run-stop "+key+" run-halted 3"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if res.HaltsInARow != 0 || res.HaltLimit != 0 || res.Note != "" { + t.Fatalf("named halt carried count fields: %d/%d/%q", res.HaltsInARow, res.HaltLimit, res.Note) + } + if got := haltCountOf(t, repo); got != 5 { + t.Fatalf("count = %d, want 5 (a named halt never touches it)", got) + } + }) + t.Run("never opens the count", func(t *testing.T) { + repo := newRunTrackerRepo(t) + key, wdeps := haltLoopRun(t, repo, 3, ClaimSelectionNamed) + res := RunVerdict(context.Background(), haltVerdictDeps(t), wdeps, GitHubDeps{}, repo, key) + if got, want := res.HumanText(), "run-stop "+key+" run-halted 3"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + haltsDirAbsent(t, repo) + }) + t.Run("resume-shaped record", func(t *testing.T) { + repo := newRunTrackerRepo(t) + key := runTrackerMintAttributedLimit(t, repo, 3, 2) + res := RunVerdict(context.Background(), haltVerdictDeps(t), WorkspaceDeps{}, GitHubDeps{}, repo, key) + if got, want := res.HumanText(), "run-stop "+key+" run-halted 3"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + haltsDirAbsent(t, repo) + }) +} + +func TestIntegrationRunVerdictHaltUnknownCountsButPrintsTodaysLine(t *testing.T) { + repo := newRunTrackerRepo(t) + deps := haltVerdictDeps(t) + for i, sel := range []string{"", "loop"} { + key, wdeps := haltLoopRun(t, repo, 3, sel) + res := RunVerdict(context.Background(), deps, wdeps, GitHubDeps{}, repo, key) + if got, want := res.HumanText(), "run-stop "+key+" run-halted 3"; got != want { + t.Fatalf("selection %q: HumanText = %q, want %q", sel, got, want) + } + if res.HaltsInARow != 0 || res.HaltLimit != 0 || res.Note != "" { + t.Fatalf("selection %q: unknown halt carried count fields: %d/%d/%q", sel, res.HaltsInARow, res.HaltLimit, res.Note) + } + if got := haltCountOf(t, repo); got != i+1 { + t.Fatalf("selection %q: count = %d, want %d (an unknown halt still counts)", sel, got, i+1) + } + } +} + +func TestIntegrationRunVerdictHaltCountFaultKeepsTodaysLine(t *testing.T) { + repo := newRunTrackerRepo(t) + s := haltStoreOf(t, repo) + must(t, os.MkdirAll(s.dir, 0o700)) + countPath := filepath.Join(s.dir, haltCountFileName) + must(t, os.WriteFile(countPath, []byte("{"), 0o600)) + deps := haltVerdictDeps(t) + + loopKey, loopW := haltLoopRun(t, repo, 3, ClaimSelectionQueue) + loop := RunVerdict(context.Background(), deps, loopW, GitHubDeps{}, repo, loopKey) + if loop.Decision != RunDecisionStop || loop.Outcome != VerdictRunHalted { + t.Fatalf("decision/outcome = %q/%q, want run-stop/run-halted", loop.Decision, loop.Outcome) + } + if got, want := loop.HumanText(), "run-stop "+loopKey+" run-halted 3"; got != want { + t.Fatalf("loop-picked HumanText = %q, want %q", got, want) + } + if loop.HaltsInARow != 0 || loop.Note != "" { + t.Fatalf("a count fault carried count fields: %d/%q", loop.HaltsInARow, loop.Note) + } + + namedKey, namedW := haltLoopRun(t, repo, 3, ClaimSelectionNamed) + named := RunVerdict(context.Background(), deps, namedW, GitHubDeps{}, repo, namedKey) + if got, want := named.HumanText(), "run-stop "+namedKey+" run-halted 3"; got != want { + t.Fatalf("named HumanText = %q, want %q", got, want) + } + if strings.Replace(loop.HumanText(), loopKey, "K", 1) != strings.Replace(named.HumanText(), namedKey, "K", 1) { + t.Fatalf("loop-picked and named lines differ under a fault: %q vs %q", loop.HumanText(), named.HumanText()) + } + buf, err := os.ReadFile(countPath) + if err != nil || string(buf) != "{" { + t.Fatalf("count.json = %q, %v; a fault must leave it as it was", buf, err) + } +} + +func TestIntegrationRunVerdictHaltLockBusyKeepsTodaysLine(t *testing.T) { + old := haltLockWait + haltLockWait = 100 * time.Millisecond + t.Cleanup(func() { haltLockWait = old }) + + repo := newRunTrackerRepo(t) + s := haltStoreOf(t, repo) + must(t, os.MkdirAll(s.dir, 0o700)) + f, err := os.OpenFile(filepath.Join(s.dir, haltLockFileName), os.O_CREATE|os.O_RDWR, 0o600) + if err != nil { + t.Fatalf("open lock: %v", err) + } + t.Cleanup(func() { f.Close() }) + if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX); err != nil { + t.Fatalf("flock: %v", err) + } + + key, wdeps := haltLoopRun(t, repo, 3, ClaimSelectionQueue) + start := time.Now() + res := RunVerdict(context.Background(), haltVerdictDeps(t), wdeps, GitHubDeps{}, repo, key) + if elapsed := time.Since(start); elapsed > 2*time.Second { + t.Fatalf("verdict took %v under a held lock, want the bounded wait", elapsed) + } + if got, want := res.HumanText(), "run-stop "+key+" run-halted 3"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if got := haltCountOf(t, repo); got != 0 { + t.Fatalf("count = %d, want 0 (nothing counted without the lock)", got) + } +} + +func TestIntegrationRunVerdictHaltLimitOneStopsAtFirstHalt(t *testing.T) { + repo := newRunTrackerRepo(t) + key, wdeps := haltLoopRun(t, repo, 3, ClaimSelectionQueue) + res := RunVerdict(context.Background(), haltVerdictDepsLimit(t, 1), wdeps, GitHubDeps{}, repo, key) + if got, want := res.reportLine(), "run-stop "+key+" run-halted 3"; got != want { + t.Fatalf("reportLine = %q, want %q", got, want) + } + if res.Note == "" || res.HaltsInARow != 1 || res.HaltLimit != 1 { + t.Fatalf("note/halts/limit = %q/%d/%d, want a note and 1/1", res.Note, res.HaltsInARow, res.HaltLimit) + } +} + +func TestIntegrationRunVerdictHaltCountAboveLoweredLimitStops(t *testing.T) { + repo := newRunTrackerRepo(t) + seedHaltCount(t, repo, 3) + key, wdeps := haltLoopRun(t, repo, 3, ClaimSelectionQueue) + res := RunVerdict(context.Background(), haltVerdictDeps(t), wdeps, GitHubDeps{}, repo, key) + if got, want := res.reportLine(), "run-stop "+key+" run-halted 3"; got != want { + t.Fatalf("reportLine = %q, want %q", got, want) + } + if res.Note == "" || res.HaltsInARow != 4 || res.HaltLimit != 2 { + t.Fatalf("note/halts/limit = %q/%d/%d, want a note and 4/2", res.Note, res.HaltsInARow, res.HaltLimit) + } +} + +func TestIntegrationRunVerdictHaltUnreadableLimitCountsAsUnknown(t *testing.T) { + repo := newRunTrackerRepo(t) + key, wdeps := haltLoopRun(t, repo, 3, ClaimSelectionQueue) + res := RunVerdict(context.Background(), haltVerdictDepsLimit(t, 0), wdeps, GitHubDeps{}, repo, key) + if got, want := res.HumanText(), "run-stop "+key+" run-halted 3"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if res.Note != "" || res.HaltsInARow != 0 { + t.Fatalf("note/halts = %q/%d, want none", res.Note, res.HaltsInARow) + } + if got := haltCountOf(t, repo); got != 1 { + t.Fatalf("count = %d, want 1 (counted as unknown)", got) + } +} + +func TestIntegrationRunVerdictRunCompleteResetsHaltCount(t *testing.T) { + fx := newVerdictCompletionFixture(t) + seedHaltCount(t, fx.repo, 2) + res := RunVerdict(context.Background(), fx.deps, fx.wdeps, fx.gdeps, fx.repo, fx.key) + if got, want := res.HumanText(), "run-done "+fx.key+" run-complete 3"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if got := haltCountOf(t, fx.repo); got != 0 { + t.Fatalf("count after run-complete = %d, want 0", got) + } + if _, err := haltStoreOf(t, fx.repo).recordHalt("later", false, 0); err != nil { + t.Fatalf("recordHalt: %v", err) + } + replay := RunVerdict(context.Background(), fx.deps, fx.wdeps, fx.gdeps, fx.repo, fx.key) + if got, want := replay.HumanText(), "run-done "+fx.key+" run-complete 3"; got != want { + t.Fatalf("replay HumanText = %q, want %q", got, want) + } + if got := haltCountOf(t, fx.repo); got != 1 { + t.Fatalf("count after replay = %d, want 1 (an old run-complete never re-zeroes)", got) + } +} + +func TestIntegrationRunVerdictBlockedCloseoutKeepsHaltCount(t *testing.T) { + fx := newVerdictCompletionFixture(t) + seedHaltCount(t, fx.repo, 2) + must(t, RegisterRunParticipant(fx.repo, fx.key, RunParticipant{Kind: "raw-run", NativeHandle: "exec-live"})) + fx.observer.defaultProven = false + res := RunVerdict(context.Background(), fx.deps, fx.wdeps, fx.gdeps, fx.repo, fx.key) + if res.Decision != RunDecisionStop || res.Reason != ReasonRunCompletionUnaccounted { + t.Fatalf("decision/reason = %q/%q, want run-stop/completion-unaccounted", res.Decision, res.Reason) + } + if got := haltCountOf(t, fx.repo); got != 2 { + t.Fatalf("count = %d, want 2 (a blocked closeout resets nothing)", got) + } +} + +func TestIntegrationRunVerdictUnclaimedAndNoClaimKeepHaltCount(t *testing.T) { + t.Run("run-unclaimed", func(t *testing.T) { + repo := newRunTrackerRepo(t) + seedHaltCount(t, repo, 2) + key := runTrackerMintAttributedLimit(t, repo, 3, 2) + deps := runTrackerLightDeps(t, []StatusBlob{runTrackerProposedBlob(3, rvSlug)}) + res := RunVerdict(context.Background(), deps, WorkspaceDeps{}, GitHubDeps{}, repo, key) + if got, want := res.HumanText(), "run-done "+key+" run-unclaimed 3"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if got := haltCountOf(t, repo); got != 2 { + t.Fatalf("count = %d, want 2", got) + } + }) + t.Run("no-attributable-claim", func(t *testing.T) { + fx := newNoClaimRunFixture(t) + seedHaltCount(t, fx.repo, 2) + res := RunVerdict(context.Background(), PlanningDeps{}, fx.wdeps, GitHubDeps{}, fx.repo, fx.key) + if got, want := res.HumanText(), "run-done "+fx.key+" no-attributable-claim"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if got := haltCountOf(t, fx.repo); got != 2 { + t.Fatalf("count = %d, want 2", got) + } + }) +} + +func TestIntegrationRunVerdictObserveNeverTouchesHaltCount(t *testing.T) { + repo := newRunTrackerRepo(t) + deps := runTrackerLightDeps(t, []StatusBlob{runTrackerHaltedInProgressBlob(3, rvSlug)}) + res := RunVerdictObserve(context.Background(), deps, WorkspaceDeps{}, GitHubDeps{}, repo, nil) + if got, want := res.HumanText(), "run-observe run-halted 3"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + haltsDirAbsent(t, repo) +} + +func TestIntegrationRunVerdictResetHaltsZeroesCount(t *testing.T) { + repo := newRunTrackerRepo(t) + seedHaltCount(t, repo, 2) + res := RunResetHalts(repo) + if res.Result != ResultApplied || res.Operation != OperationRunResetHalts { + t.Fatalf("result/operation = %q/%q, want applied/%s (reason %q, message %q)", res.Result, res.Operation, OperationRunResetHalts, res.Reason, res.Message) + } + if res.Previous != 2 || res.PreviousUnreadable { + t.Fatalf("previous/unreadable = %d/%v, want 2/false", res.Previous, res.PreviousUnreadable) + } + if got, want := res.HumanText(), "halt count reset to 0 (was 2)"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if got := haltCountOf(t, repo); got != 0 { + t.Fatalf("count = %d, want 0", got) + } +} + +func TestIntegrationRunVerdictResetHaltsRepairsCorruptCount(t *testing.T) { + repo := newRunTrackerRepo(t) + s := haltStoreOf(t, repo) + must(t, os.MkdirAll(s.dir, 0o700)) + must(t, os.WriteFile(filepath.Join(s.dir, haltCountFileName), []byte("{"), 0o600)) + res := RunResetHalts(repo) + if res.Result != ResultApplied || !res.PreviousUnreadable || res.Previous != 0 { + t.Fatalf("result/unreadable/previous = %q/%v/%d, want applied/true/0", res.Result, res.PreviousUnreadable, res.Previous) + } + if got, want := res.HumanText(), "halt count reset to 0 (the previous count was unreadable)"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if got := haltCountOf(t, repo); got != 0 { + t.Fatalf("count = %d, want 0", got) + } +} + +func TestIntegrationRunVerdictResetHaltsLockBusy(t *testing.T) { + old := haltLockWait + haltLockWait = 100 * time.Millisecond + t.Cleanup(func() { haltLockWait = old }) + + repo := newRunTrackerRepo(t) + seedHaltCount(t, repo, 2) + s := haltStoreOf(t, repo) + f, err := os.OpenFile(filepath.Join(s.dir, haltLockFileName), os.O_CREATE|os.O_RDWR, 0o600) + if err != nil { + t.Fatalf("open lock: %v", err) + } + t.Cleanup(func() { f.Close() }) + if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX); err != nil { + t.Fatalf("flock: %v", err) + } + res := RunResetHalts(repo) + if res.Result != ResultContended || res.Reason != "halt-count-busy" { + t.Fatalf("result/reason = %q/%q, want contended/halt-count-busy", res.Result, res.Reason) + } + if got, want := res.HumanText(), "run.reset-halts: contended (halt-count-busy)"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if got := haltCountOf(t, repo); got != 2 { + t.Fatalf("count = %d, want 2 (nothing reset without the lock)", got) + } +} diff --git a/internal/app/runtracker_halts_test.go b/internal/app/runtracker_halts_test.go new file mode 100644 index 000000000..87822eef9 --- /dev/null +++ b/internal/app/runtracker_halts_test.go @@ -0,0 +1,288 @@ +package app + +import ( + "errors" + "fmt" + "os" + "path/filepath" + "reflect" + "strings" + "sync" + "syscall" + "testing" + "time" + + "github.com/danielhanold/docket/internal/testsupport" +) + +// haltStoreFixture returns a halt-count store rooted in a fresh temp state folder. +// It is pure filesystem: nothing here starts git. +func haltStoreFixture(t *testing.T) haltCountStore { + t.Helper() + s := haltCountStoreAt(testsupport.TempDir(t)) + if filepath.Base(s.dir) != runTrackerHaltsDirName { + t.Fatalf("store dir = %q, want it to end in %q", s.dir, runTrackerHaltsDirName) + } + return s +} + +func mustRecordHalt(t *testing.T, s haltCountStore, key string, loopPicked bool, limit int) haltCounted { + t.Helper() + out, err := s.recordHalt(key, loopPicked, limit) + if err != nil { + t.Fatalf("recordHalt(%q, %v, %d): %v", key, loopPicked, limit, err) + } + return out +} + +func mustHaltCount(t *testing.T, s haltCountStore, want int) { + t.Helper() + got, err := s.count() + if err != nil { + t.Fatalf("count(): %v", err) + } + if got != want { + t.Fatalf("count() = %d, want %d", got, want) + } +} + +func TestHaltCountRecordHaltUnderLimitIsRunNext(t *testing.T) { + s := haltStoreFixture(t) + out := mustRecordHalt(t, s, "k1", true, 2) + if out.Decision != RunDecisionNext || out.HaltsInARow != 1 || out.HaltLimit != 2 || out.Noted { + t.Fatalf("recordHalt = %+v, want run-next at 1 of 2, not noted", out) + } + mustHaltCount(t, s, 1) +} + +func TestHaltCountRecordHaltAtLimitIsRunStopNoted(t *testing.T) { + s := haltStoreFixture(t) + mustRecordHalt(t, s, "k1", true, 2) + out := mustRecordHalt(t, s, "k2", true, 2) + if out.Decision != RunDecisionStop || !out.Noted || out.HaltsInARow != 2 || out.HaltLimit != 2 { + t.Fatalf("recordHalt at limit = %+v, want run-stop noted at 2 of 2", out) + } + mustHaltCount(t, s, 2) +} + +func TestHaltCountRecordHaltOncePerKey(t *testing.T) { + s := haltStoreFixture(t) + first := mustRecordHalt(t, s, "k1", true, 2) + second := mustRecordHalt(t, s, "k1", true, 2) + if !reflect.DeepEqual(first, second) { + t.Fatalf("replay = %+v, want the saved %+v", second, first) + } + mustHaltCount(t, s, 1) + + if _, _, err := s.resetAll(); err != nil { + t.Fatalf("resetAll: %v", err) + } + // A replay after the count moved returns the SAVED decision, never a fresh one, + // and never counts the key a second time. + replay := mustRecordHalt(t, s, "k1", true, 2) + if replay.Decision != RunDecisionNext || replay.HaltsInARow != 1 || !reflect.DeepEqual(replay, first) { + t.Fatalf("replay after reset = %+v, want the saved %+v", replay, first) + } + mustHaltCount(t, s, 0) +} + +func TestHaltCountUnknownModeCountsWithoutDecision(t *testing.T) { + s := haltStoreFixture(t) + out := mustRecordHalt(t, s, "k1", false, 0) + if out.Decision != "" || out.HaltsInARow != 1 || out.HaltLimit != 0 || out.Noted { + t.Fatalf("unknown recordHalt = %+v, want no decision at 1", out) + } + mustHaltCount(t, s, 1) +} + +func TestHaltCountLimitBelowCountStops(t *testing.T) { + s := haltStoreFixture(t) + for _, k := range []string{"k1", "k2", "k3"} { + mustRecordHalt(t, s, k, false, 0) + } + out := mustRecordHalt(t, s, "k4", true, 2) + if out.Decision != RunDecisionStop || !out.Noted || out.HaltsInARow != 4 { + t.Fatalf("recordHalt above a lowered limit = %+v, want run-stop noted at 4", out) + } +} + +func TestHaltCountRecordResetOncePerKey(t *testing.T) { + s := haltStoreFixture(t) + mustRecordHalt(t, s, "k1", true, 5) + mustRecordHalt(t, s, "k2", true, 5) + mustHaltCount(t, s, 2) + if err := s.recordReset("c1"); err != nil { + t.Fatalf("recordReset: %v", err) + } + mustHaltCount(t, s, 0) + mustRecordHalt(t, s, "k3", true, 5) + mustHaltCount(t, s, 1) + // An old run-complete replayed never re-zeroes the count. + if err := s.recordReset("c1"); err != nil { + t.Fatalf("replayed recordReset: %v", err) + } + mustHaltCount(t, s, 1) +} + +func TestHaltCountCorruptCountIsAFault(t *testing.T) { + s := haltStoreFixture(t) + if err := os.MkdirAll(s.dir, 0o700); err != nil { + t.Fatal(err) + } + countPath := filepath.Join(s.dir, haltCountFileName) + if err := os.WriteFile(countPath, []byte("{"), 0o600); err != nil { + t.Fatal(err) + } + if _, err := s.recordHalt("k1", true, 2); err == nil { + t.Fatal("recordHalt over a corrupt count succeeded, want a fault (never read as 0)") + } + if got, _ := os.ReadFile(countPath); string(got) != "{" { + t.Fatalf("count.json = %q after a faulted recordHalt, want it untouched", got) + } + if _, err := os.Stat(filepath.Join(s.dir, haltCountedDirName, "k1"+haltMarkerSuffix)); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("a faulted recordHalt left a marker (stat err %v)", err) + } + if _, err := s.count(); err == nil { + t.Fatal("count() over a corrupt count succeeded, want an error") + } + + previous, unreadable, err := s.resetAll() + if err != nil || !unreadable || previous != 0 { + t.Fatalf("resetAll = (%d, %v, %v), want (0, true, nil)", previous, unreadable, err) + } + mustHaltCount(t, s, 0) +} + +func TestHaltCountRejectsOutOfShapeCounts(t *testing.T) { + for name, body := range map[string]string{ + "wrong schema": `{"schema":2,"halts_in_a_row":1}`, + "negative": `{"schema":1,"halts_in_a_row":-1}`, + "missing count": `{"schema":1}`, + "missing schema": `{"halts_in_a_row":1}`, + "trailing data": `{"schema":1,"halts_in_a_row":1} {}`, + } { + t.Run(name, func(t *testing.T) { + s := haltStoreFixture(t) + if err := os.MkdirAll(s.dir, 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(s.dir, haltCountFileName), []byte(body), 0o600); err != nil { + t.Fatal(err) + } + if _, err := s.count(); err == nil { + t.Fatalf("count() over %s succeeded, want an error", body) + } + if _, err := s.recordHalt("k1", true, 2); err == nil { + t.Fatalf("recordHalt over %s succeeded, want a fault", body) + } + }) + } +} + +func TestHaltCountLockIsBounded(t *testing.T) { + saved := haltLockWait + haltLockWait = 100 * time.Millisecond + t.Cleanup(func() { haltLockWait = saved }) + + s := haltStoreFixture(t) + if err := os.MkdirAll(s.dir, 0o700); err != nil { + t.Fatal(err) + } + f, err := os.OpenFile(filepath.Join(s.dir, haltLockFileName), os.O_CREATE|os.O_RDWR, 0o600) + if err != nil { + t.Fatal(err) + } + defer f.Close() + if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX); err != nil { + t.Fatal(err) + } + + start := time.Now() + _, err = s.recordHalt("k1", true, 2) + if !errors.Is(err, errHaltCountBusy) { + t.Fatalf("recordHalt under a held lock = %v, want errHaltCountBusy", err) + } + if elapsed := time.Since(start); elapsed > time.Second { + t.Fatalf("recordHalt waited %v under a held lock, want it bounded near %v", elapsed, haltLockWait) + } + if err := s.recordReset("c1"); !errors.Is(err, errHaltCountBusy) { + t.Fatalf("recordReset under a held lock = %v, want errHaltCountBusy", err) + } + if _, _, err := s.resetAll(); !errors.Is(err, errHaltCountBusy) { + t.Fatalf("resetAll under a held lock = %v, want errHaltCountBusy", err) + } + mustHaltCount(t, s, 0) +} + +func TestHaltCountConcurrentDistinctKeysAllCount(t *testing.T) { + s := haltStoreFixture(t) + const n = 16 + var wg sync.WaitGroup + errs := make(chan error, n) + for i := 0; i < n; i++ { + wg.Add(1) + go func(i int) { + defer wg.Done() + if _, err := s.recordHalt(fmt.Sprintf("k%d", i), true, 100); err != nil { + errs <- err + } + }(i) + } + wg.Wait() + close(errs) + for err := range errs { + t.Fatalf("concurrent recordHalt: %v", err) + } + mustHaltCount(t, s, n) +} + +func TestHaltCountRejectsMalformedKey(t *testing.T) { + s := haltStoreFixture(t) + if _, err := s.recordHalt("../x", true, 2); err == nil { + t.Fatal("recordHalt accepted a malformed key") + } + if err := s.recordReset("../x"); err == nil { + t.Fatal("recordReset accepted a malformed key") + } + if _, err := os.Stat(filepath.Join(s.dir, haltCountFileName)); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("a malformed key wrote a count (stat err %v)", err) + } +} + +// TestRunVerdictHumanTextAppendsNote pins the report rendering: the note rides on a +// second line of HumanText, while reportLine — what the record persists — stays the +// one report line. +func TestRunVerdictHumanTextAppendsNote(t *testing.T) { + r := RunVerdictResult{Decision: RunDecisionNext, Key: "k", Outcome: VerdictRunHalted, AttributedID: 3} + if got, want := r.HumanText(), "run-next k run-halted 3"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if r.reportLine() != r.HumanText() { + t.Fatalf("without a note reportLine %q != HumanText %q", r.reportLine(), r.HumanText()) + } + r.Decision, r.Note = RunDecisionStop, "note: x" + if got, want := r.HumanText(), "run-stop k run-halted 3\nnote: x"; got != want { + t.Fatalf("HumanText = %q, want %q", got, want) + } + if got, want := r.reportLine(), "run-stop k run-halted 3"; got != want { + t.Fatalf("reportLine = %q, want %q", got, want) + } +} + +// TestHaltLimitNoteNamesTheResetAndForbidsDoingItAlone pins the at-limit note: one +// line naming the count, the limit, the setting and the reset operation, and +// forbidding a reset without the person's yes. +func TestHaltLimitNoteNamesTheResetAndForbidsDoingItAlone(t *testing.T) { + n := haltLimitNote(2, 2) + for _, want := range []string{"note: ", "2 changes picked from the queue", "limit of 2", "run.max_consecutive_halts", "run.reset-halts", "Never reset it on your own"} { + if !strings.Contains(n, want) { + t.Errorf("note %q lacks %q", n, want) + } + } + if strings.Contains(n, "\n") { + t.Errorf("note %q spans more than one line", n) + } + if one := haltLimitNote(1, 1); !strings.Contains(one, "1 change picked from the queue has halted") || !strings.Contains(one, "limit of 1") { + t.Errorf("note at limit 1 = %q, want the singular wording", one) + } +} diff --git a/internal/app/runtracker_store.go b/internal/app/runtracker_store.go index 699723eb1..53db02ac2 100644 --- a/internal/app/runtracker_store.go +++ b/internal/app/runtracker_store.go @@ -232,6 +232,12 @@ type RunTrackerClaimBinding struct { RequestID string `json:"request_id"` Confirmed bool `json:"confirmed"` Revision string `json:"revision,omitempty"` + // Selection is how the claim's run chose the change (ClaimSelectionQueue or + // ClaimSelectionNamed; "" = unknown). Additive and optional: a binding written + // before the field existed reads as unknown, and the schema stays + // bindingSchemaVersion. It is set once at reservation and carried through + // ConfirmRunTrackerClaim's rewrite. + Selection string `json:"selection,omitempty"` } // runTrackerContinuationTripleOK reports whether rec's continuation triple is well @@ -713,6 +719,15 @@ func readRunTrackerClaimBinding(dir, op string) (RunTrackerClaimBinding, bool, e // replay (nil); an existing binding for a different claim is ErrRunTrackerBindingConflict // — bind-once, a later attempt can never overwrite the first. func ReserveRunTrackerClaim(repoDir, key string, changeID int, requestID string) error { + return ReserveRunTrackerClaimSelection(repoDir, key, changeID, requestID, "") +} + +// ReserveRunTrackerClaimSelection is ReserveRunTrackerClaim recording how the run +// chose the change (see RunTrackerClaimBinding.Selection). The selection is not +// part of the bind-once identity: reserveMatchOrConflict still compares only +// (changeID, requestID), so a replay naming another selection is an idempotent +// no-op that keeps the first one. +func ReserveRunTrackerClaimSelection(repoDir, key string, changeID int, requestID, selection string) error { dir, err := runKeyDir(repoDir, key, "reserve") if err != nil { return err @@ -723,7 +738,7 @@ func ReserveRunTrackerClaim(repoDir, key string, changeID int, requestID string) // pre-read that answered match-or-conflict on its own would make the CAS // untestable and would race a concurrent writer): the conflict-checked write is // authority. - buf, err := json.Marshal(RunTrackerClaimBinding{Schema: bindingSchemaVersion, ChangeID: changeID, RequestID: requestID, Confirmed: false}) + buf, err := json.Marshal(RunTrackerClaimBinding{Schema: bindingSchemaVersion, ChangeID: changeID, RequestID: requestID, Confirmed: false, Selection: selection}) if err != nil { return runTrackerErr(ErrRunTrackerIO, "reserve", err) } @@ -810,7 +825,9 @@ func ConfirmRunTrackerClaim(repoDir, key string, changeID int, requestID, revisi return runTrackerErr(ErrRunTrackerBindingConflict, "confirm", nil) } - confirmed := RunTrackerClaimBinding{Schema: bindingSchemaVersion, ChangeID: changeID, RequestID: requestID, Confirmed: true, Revision: revision} + // The confirmed binding is rebuilt from scratch, so it must carry the reserved + // selection forward: dropping it would read every claim as unknown. + confirmed := RunTrackerClaimBinding{Schema: bindingSchemaVersion, ChangeID: changeID, RequestID: requestID, Confirmed: true, Revision: revision, Selection: b.Selection} if err := writeRunTrackerClaimBindingAtomic(dir, confirmed); err != nil { return err } diff --git a/internal/app/runtracker_store_integration_test.go b/internal/app/runtracker_store_integration_test.go index 7b4c1710c..1bdf7b7c8 100644 --- a/internal/app/runtracker_store_integration_test.go +++ b/internal/app/runtracker_store_integration_test.go @@ -116,6 +116,33 @@ func TestIntegrationRunRecordConfirmRunTrackerClaimMirrorsRecord(t *testing.T) { } } +// TestIntegrationRunRecordConfirmKeepsSelection: confirm rewrites the binding +// from scratch, so it must carry the reserved selection forward — dropping it +// would read every loop-picked claim as unknown. A replayed reservation naming a +// different selection is the same (change, request) and leaves the first one in +// place (bind-once). +func TestIntegrationRunRecordConfirmKeepsSelection(t *testing.T) { + repo := newRunTrackerRepo(t) + key := mintPlainRunTracker(t, repo) + if err := ReserveRunTrackerClaimSelection(repo, key, 3, "claim-3-v", ClaimSelectionQueue); err != nil { + t.Fatalf("reserve: %v", err) + } + if err := ConfirmRunTrackerClaim(repo, key, 3, "claim-3-v", "r1", ""); err != nil { + t.Fatalf("confirm: %v", err) + } + b, ok, err := LoadRunTrackerClaimBinding(repo, key) + if err != nil || !ok || !b.Confirmed || b.Selection != ClaimSelectionQueue { + t.Fatalf("binding after confirm = %+v ok=%v err=%v; want confirmed with selection queue", b, ok, err) + } + if err := ReserveRunTrackerClaimSelection(repo, key, 3, "claim-3-v", ClaimSelectionNamed); err != nil { + t.Fatalf("replayed reserve: %v", err) + } + b, _, _ = LoadRunTrackerClaimBinding(repo, key) + if b.Selection != ClaimSelectionQueue { + t.Fatalf("binding selection after replay = %q, want queue (bind-once)", b.Selection) + } +} + // TestIntegrationRunRecordConfirmWithoutReservationFails: a failed or absent reservation can never // become a confirmed binding (spec: "Failed claims never become confirmed // bindings"). diff --git a/internal/app/runtracker_verdict.go b/internal/app/runtracker_verdict.go index 67ae10d31..ccaac7f36 100644 --- a/internal/app/runtracker_verdict.go +++ b/internal/app/runtracker_verdict.go @@ -81,6 +81,16 @@ import ( // single-use continuation triple, and reports `run-continue run-waiting // ` with Terminal false. Unsafe ownership // (ambiguous or halted takeover) earns neither retry nor continuation. +// +// HALT COUNT (runtracker_halts.go). A run-halted verdict consults the per-repository +// count of halts in a row by how the run chose its change (runTrackerHaltMode): a +// named run or a resume never opens the count and prints today's run-stop line; an +// unknown-mode claim counts but prints today's line; a change picked from the queue +// counts and prints `run-next run-halted ` while the count stays under +// run.max_consecutive_halts, else today's run-stop plus a reset note. Any count +// fault prints today's line, and a key's halt counts once — a re-run verdict +// replays the saved line. Only a final run-done run-complete resets the count, once +// per key. run-next keeps Terminal true, spends no retry, and leaves the run active. // OperationRunVerdict is the operation key `run verdict` records in its // envelope. @@ -91,6 +101,10 @@ const ( RunDecisionDone = "run-done" RunDecisionRetryOnce = "run-retry-once" RunDecisionStop = "run-stop" + // RunDecisionNext reports a halt on a change a loop picked from the queue while the + // halt count stays under run.max_consecutive_halts: the halted change is never + // re-dispatched, but a loop driver may start its next run with a fresh run.start. + RunDecisionNext = "run-next" ) // The run-tracker outcome tokens that are not themselves RunVerify verdicts. The run-* @@ -173,7 +187,7 @@ const ( type RunVerdictResult struct { Envelope Key string `json:"key,omitempty"` - Decision string `json:"decision,omitempty"` // run-done | run-retry-once | run-stop | run-continue + Decision string `json:"decision,omitempty"` // run-done | run-retry-once | run-stop | run-continue | run-next Outcome string `json:"outcome,omitempty"` // run-* | no-attributable-claim | ambiguous-claims | run-tracker-unavailable AttributedID int `json:"attributed_id,omitempty"` Unmet []string `json:"unmet,omitempty"` @@ -202,11 +216,29 @@ type RunVerdictResult struct { // It is ADDITIVE and diagnostic — omitempty keeps it off every other path — and // never changes the report-line TOKENS, so existing report parsing is untouched. CompletionFindings []string `json:"completion_findings,omitempty"` + // HaltsInARow and HaltLimit surface the halt count on a halt of a change a loop + // picked from the queue: the count of halts in a row this halt brought it to and + // the run.max_consecutive_halts it was weighed against. Note is the at-limit + // reset note, rendered on a second line after the report line. All three stay + // empty on every other verdict (omitempty keeps them off the JSON). + HaltsInARow int `json:"halts_in_a_row,omitempty"` + HaltLimit int `json:"halt_limit,omitempty"` + Note string `json:"note,omitempty"` } -// HumanText renders the single attributed report line. The field layout after -// ` ` is chosen by the outcome token. +// HumanText renders the attributed report line, followed by the Note on a second +// line when one is set (only a halt that reached the halt limit carries one). func (r RunVerdictResult) HumanText() string { + if r.Note != "" { + return r.reportLine() + "\n" + r.Note + } + return r.reportLine() +} + +// reportLine renders the single attributed report line — the one line the record +// persists as its Disposition. The field layout after ` ` +// is chosen by the outcome token. +func (r RunVerdictResult) reportLine() string { fields := []string{r.Decision, r.Key, r.Outcome} // A run-continue reuses the run-waiting outcome word but a DISTINCT field // layout — [id, continuation-id, phase] — so it is keyed on the DECISION, not @@ -253,7 +285,7 @@ func runVerdictLine(key, decision, outcome string, id int, terminal bool, set fu // the report line is the contract, and the retry permit's durability rests on the // O_EXCL marker (authority), not on this mirror save. func persistRunVerdict(repoDir, key string, rec RunTrackerRecord, res RunVerdictResult) RunVerdictResult { - rec.Disposition = res.HumanText() + rec.Disposition = res.reportLine() rec.Terminal = res.Terminal _ = SaveRunTrackerRecord(repoDir, key, rec) return res @@ -313,10 +345,19 @@ func RunVerdict(ctx context.Context, deps PlanningDeps, wdeps WorkspaceDeps, gde // (unit tests fake the observers); production composes // productionCancelSeams(repoDir). RunVerify's verdict is reported as fact — // runTrackerCompleteRun never re-derives it. - return runTrackerCompleteRun(repoDir, key, rec, v.Verdict, id, verdictSeams(repoDir, wdeps)) + res := runTrackerCompleteRun(repoDir, key, rec, v.Verdict, id, verdictSeams(repoDir, wdeps)) + if v.Verdict == VerdictRunComplete && res.Decision == RunDecisionDone { + // A clean build zeroes the halt count — only once the run-done line is + // final (after the closeout and its checked save), and best-effort. + runTrackerResetHaltCount(repoDir, key) + } + return res case VerdictRunHalted: - return persistRunVerdict(repoDir, key, rec, - runVerdictLine(key, RunDecisionStop, VerdictRunHalted, id, true, nil)) + // A halt never spends a retry and leaves the run active. The halt count may + // turn today's run-stop into run-next (a loop-picked halt under the limit) or + // add the at-limit note; see runTrackerApplyHaltCount. + res := runVerdictLine(key, RunDecisionStop, VerdictRunHalted, id, true, nil) + return persistRunVerdict(repoDir, key, rec, runTrackerApplyHaltCount(ctx, deps, repoDir, key, rec, res)) case VerdictRunWaiting: // A cooperatively handed-off drive is a live continuation, not a stop: emit // a NONTERMINAL run-continue that keeps the key and spends no retry (change @@ -456,7 +497,7 @@ func runTrackerCompleteRun(repoDir, key string, rec RunTrackerRecord, outcome st res := runVerdictLine(key, RunDecisionDone, outcome, id, true, func(r *RunVerdictResult) { r.CompletionFindings = findings }) - rec.Disposition = res.HumanText() + rec.Disposition = res.reportLine() rec.Terminal = res.Terminal if serr := SaveRunTrackerRecord(repoDir, key, rec); serr != nil { return persistRunVerdict(repoDir, key, rec, @@ -468,6 +509,131 @@ func runTrackerCompleteRun(repoDir, key string, rec RunTrackerRecord, outcome st return res } +// haltMode is how a halted run chose its change, as the halt count sees it. +type haltMode int + +const ( + // haltModeUnknown: no positive evidence either way (no binding, an unreadable + // one, or a claim made without a recognized selection). The halt counts, but the + // verdict prints today's line. + haltModeUnknown haltMode = iota + // haltModeLoopPicked: the claim recorded ClaimSelectionQueue. The halt counts and + // may print run-next. + haltModeLoopPicked + // haltModeNamed: the run named its change (ClaimSelectionNamed, or a + // `run start --resume` record). The count is never opened. + haltModeNamed +) + +// runTrackerHaltMode reads how the run behind key chose its change. A resume-shaped +// record is named by construction (it never claimed); otherwise the claim binding's +// Selection decides, and any binding fault or absence is unknown — never named, +// never loop-picked. +func runTrackerHaltMode(repoDir, key string, rec RunTrackerRecord) haltMode { + if rec.resumeAttributed() { + return haltModeNamed + } + b, ok, err := LoadRunTrackerClaimBinding(repoDir, key) + if err != nil || !ok { + return haltModeUnknown + } + switch b.Selection { + case ClaimSelectionQueue: + return haltModeLoopPicked + case ClaimSelectionNamed: + return haltModeNamed + default: + return haltModeUnknown + } +} + +// runTrackerHaltLimit reads run.max_consecutive_halts from the resolved config at +// verdict time. A missing reader, a pin fault, or a value under 1 reports ok=false, +// which demotes a loop-picked halt to unknown (counted, today's line). +func runTrackerHaltLimit(ctx context.Context, deps PlanningDeps, repoDir string) (int, bool) { + if deps.Reader == nil { + return 0, false + } + pin, err := deps.Reader.PinContext(ctx, repoDir) + if err != nil { + return 0, false + } + limit := pin.Config.Effective.Run.MaxConsecutiveHalts.Value + if limit < 1 { + return 0, false + } + return limit, true +} + +// runTrackerApplyHaltCount weighs a keyed run-halted verdict (res, today's +// `run-stop run-halted `) against the halt count and returns the line to +// report. A named halt returns res before the count is ever opened. Every fault — +// the store, the lock, an unreadable count or marker — returns res unchanged, so a +// count fault never changes a report line. The outcome comes from the key's SAVED +// marker, never re-derived from the current mode, count or limit, so re-running the +// verdict for an old key replays its first line. +func runTrackerApplyHaltCount(ctx context.Context, deps PlanningDeps, repoDir, key string, rec RunTrackerRecord, res RunVerdictResult) RunVerdictResult { + mode := runTrackerHaltMode(repoDir, key, rec) + if mode == haltModeNamed { + return res + } + limit := 0 + if mode == haltModeLoopPicked { + l, ok := runTrackerHaltLimit(ctx, deps, repoDir) + if !ok { + mode = haltModeUnknown + } else { + limit = l + } + } + store, err := openHaltCountStore(repoDir) + if err != nil { + return res + } + out, err := store.recordHalt(key, mode == haltModeLoopPicked, limit) + if err != nil { + return res + } + switch out.Decision { + case RunDecisionNext: + res.Decision = RunDecisionNext + case RunDecisionStop: + if out.Noted { + res.Note = haltLimitNote(out.HaltsInARow, out.HaltLimit) + } + default: + // Unknown mode, now or when the key was first counted: today's line. + return res + } + res.HaltsInARow = out.HaltsInARow + res.HaltLimit = out.HaltLimit + return res +} + +// runTrackerResetHaltCount zeroes the halt count for key's clean build, once per key. +// It is best-effort: the caller runs it only after the run-done line is final, and a +// fault leaves the count as it was without touching the report. +func runTrackerResetHaltCount(repoDir, key string) { + store, err := openHaltCountStore(repoDir) + if err != nil { + return + } + _ = store.recordReset(key) +} + +// haltLimitNote is the one-line note under a run-stop that reached the halt limit. +// It asks the coordinating session to put the reset to the person, and is worded +// without assuming a loop is running. +func haltLimitNote(n, limit int) string { + halted := fmt.Sprintf("%d changes picked from the queue have halted in a row", n) + if n == 1 { + halted = "1 change picked from the queue has halted" + } + return fmt.Sprintf("note: %s, reaching the limit of %d "+ + "(run.max_consecutive_halts). Ask the person whether to reset the halt count to 0; only on their "+ + "yes, run the run.reset-halts operation (docket run reset-halts). Never reset it on your own.", halted, limit) +} + // verdictSeams composes the census seam bundle the keyed run.verdict uses on both // of its paths (change 0491): the injected bundle when a caller wires one, else // the production bundle over repoDir. @@ -704,7 +870,7 @@ func resolveRunTrackerOwnership(ctx context.Context, deps PlanningDeps, wdeps Wo if !ok { return runTrackerOwnershipStop(repoDir, key, *rec, ReasonRunProofUnavailable) } - _ = ReserveRunTrackerClaim(repoDir, key, p.ChangeID, p.RequestID) + _ = ReserveRunTrackerClaimSelection(repoDir, key, p.ChangeID, p.RequestID, p.Selection) _ = ConfirmRunTrackerClaim(repoDir, key, p.ChangeID, p.RequestID, p.Revision, wt) runTrackerAdoptOwnership(wdeps, repoDir, key, rec, p.ChangeID, p.RequestID, p.Revision) return nil diff --git a/internal/app/runtracker_verdict_integration_test.go b/internal/app/runtracker_verdict_integration_test.go index 2a88ce58a..78c449f41 100644 --- a/internal/app/runtracker_verdict_integration_test.go +++ b/internal/app/runtracker_verdict_integration_test.go @@ -872,7 +872,7 @@ func TestIntegrationRunVerdictVerdictAbsentBindingAdoptsSoleProof(t *testing.T) ) key := runTrackerMintStarted(t, f.repo.invocation, nil, 1, "ha") wdeps.ClaimProofs = &fakeProofScanner{proofs: []ClaimProof{ - {RequestID: "claim-3-v", ChangeID: 3, RunContextHash: "ha", Revision: "r1"}, + {RequestID: "claim-3-v", ChangeID: 3, RunContextHash: "ha", Revision: "r1", Selection: ClaimSelectionQueue}, }} res := RunVerdict(context.Background(), deps, wdeps, gdeps, f.repo.invocation, key) @@ -883,6 +883,10 @@ func TestIntegrationRunVerdictVerdictAbsentBindingAdoptsSoleProof(t *testing.T) if err != nil || !ok || !b.Confirmed || b.ChangeID != 3 { t.Fatalf("binding = %+v ok=%v err=%v, want confirmed change 3 after adoption", b, ok, err) } + // The adopted binding keeps the selection the committed receipt recorded. + if b.Selection != ClaimSelectionQueue { + t.Fatalf("adopted binding selection = %q, want queue (carried from the proof)", b.Selection) + } }) t.Run("two proofs is binding-conflict", func(t *testing.T) { diff --git a/internal/app/schema_registry.go b/internal/app/schema_registry.go index 8db61f913..48e6c6bfb 100644 --- a/internal/app/schema_registry.go +++ b/internal/app/schema_registry.go @@ -115,6 +115,7 @@ var operationBindings = []OperationBinding{ {ID: "repository.sync-integration", Request: nil, Result: RepositorySyncResult{}}, // RunRepositorySyncIntegration {ID: "run.cancel", Request: nil, Result: RunCancelResult{}}, // RunCancel {ID: "run.continue", Request: nil, Result: RunContinueResult{}}, // RunContinue + {ID: "run.reset-halts", Request: nil, Result: RunResetHaltsResult{}}, // RunResetHalts {ID: "run.start", Request: nil, Result: RunStartResult{}}, // RunStart {ID: "run.verdict", Request: nil, Result: RunVerdictResult{}}, // RunVerdict (observe mode returns RunVerdictObserveResult) {ID: "run.verify", Request: nil, Result: RunVerifyResult{}}, // RunVerify diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 99fea5a70..09aa3e9a1 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,14 +1,14 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:fa6e5df41b394961fade11d17cad0451e4449ef2cc12af98625cdd812f5c7192", + "asset_set_id": "sha256:a387c735fef0b4929c67ec26af4ab7fe77364cf46cbdbcd02a16f2c08a184f32", "entries": [ { "path": ".docket.example.yml", "role": "config-schema", "mode": 420, - "size": 21708, - "sha256": "3147cee773ed79a4f995bfd1c3438f563a95908e0a68d4774749c14e06742808" + "size": 22191, + "sha256": "3ebda2ca57f6d67d526e8b5086f2370b9c61a3267ee2e1ac7e8fff8ccfa6355f" }, { "path": "agents/docket-adr.md", @@ -266,8 +266,8 @@ "path": "cursor-rules/run-tracker.md", "role": "dispatch", "mode": 420, - "size": 5135, - "sha256": "c68e82dbfc3e1429f31df6aa7c90d1210ffd8a9bcce32713fadf8f9c5562c5cb" + "size": 5343, + "sha256": "2324d22c947fe65622314b3c01755dd6e8f4eadc3da18aee53cbb6031c09a75a" }, { "path": "skills/docket-adr/SKILL.md", @@ -378,8 +378,8 @@ "path": "skills/docket-implement-next/SKILL.md", "role": "skill", "mode": 420, - "size": 58972, - "sha256": "a320347018fbf89758d72a880ce0f9cebcd35ed47b27ebd1afd7fb41b742916c" + "size": 59470, + "sha256": "4fa089cb4628311bad6750288b0cae3a84b6ba63911992c08979c9df08e389aa" }, { "path": "skills/docket-implement-next/references/edge-paths.md", diff --git a/internal/assets/embedded/tree/.docket.example.yml b/internal/assets/embedded/tree/.docket.example.yml index e39340fbf..7030f29a4 100644 --- a/internal/assets/embedded/tree/.docket.example.yml +++ b/internal/assets/embedded/tree/.docket.example.yml @@ -130,6 +130,14 @@ run: # scope: any layer max_attempts: 2 + # max_consecutive_halts — how many changes picked from the queue may halt in a row before a + # tracked implement-next loop stops. A halted change always waits for a person; under this limit + # the loop moves on to the next build-ready change instead of ending the drain. 2 by default; + # 1 stops the loop at the first halt. A clean build resets the count, and so does + # `docket run reset-halts`. A whole number of 1 or more. + # scope: any layer + max_consecutive_halts: 2 + # ═══ review — what implement-next fixes after review ══════════════════════════════════════ diff --git a/internal/assets/embedded/tree/cursor-rules/run-tracker.md b/internal/assets/embedded/tree/cursor-rules/run-tracker.md index 1cb7da5c3..d52d59dfe 100644 --- a/internal/assets/embedded/tree/cursor-rules/run-tracker.md +++ b/internal/assets/embedded/tree/cursor-rules/run-tracker.md @@ -24,6 +24,9 @@ broken: surface it, never rebuild the run tracker by hand. or dispatch `docket-implement-next` again with the explicit change id, the continuation id, and the same key, and run `run.verdict` with `` again. Every `run-stop` and every `run-observe` forbids re-dispatch; `run-halted` means a human is needed. + `run-next run-halted ` also forbids re-dispatching that change; only a loop driver + (`/loop`) may go on to its next run, with a fresh `run.start`; a single dispatch stops, as on + `run-stop`. ## Stopping a dispatched run — there is no automatic Stop button diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md index 94e17a919..e8fef5d33 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md @@ -46,7 +46,7 @@ The digest is an **accelerator, not the sole channel**: the authoritative read i ### Step 2 — Claim (conflict-checked write) -Claim by transaction: the `change.claim` operation with `--id --revision ` (the exact revision from the step-1 bundle). When the dispatch prompt carried a **run context** token, pass it to the claim as --run-context : the claim validates it against the started run, records durable proof binding this dispatch to its successful claim, and the parent's keyed verdict resolves ownership from that proof; an invalid or conflicting run context is a typed refusal that writes nothing — never retried as an ungated claim. A claim without the token stays supported for ungated invocations. In the **metadata working tree** the operation reloads fresh origin, re-proves the change is still `proposed`, uniquely identified, build-ready, and has a resolved effective base, then applies the landed claim (`status: in-progress` + `branch: /` + `updated:` + `claimed_at:` — the lease the `change.reclaim` operation and the maintenance sweep's reclaim key on) and updates the change record, `## Artifacts` block, and inline board **together in one metadata commit** on the metadata branch, pushed to the metadata remote. It returns the new record revision, feature branch, lease classification, and a closed disposition; a wrong revision or a not-`proposed`/not-build-ready/duplicate/unresolved-base change returns `contended`/a typed refusal that **writes nothing and creates no workspace**. A lost-response retry converges by re-reading authority — an already-held matching claim returns the applied receipt or a typed `already-claimed`, a foreign claim returns `contended`; never adopt a branch or workspace as proof the claim landed. A `contended` result is the **`contended`** disposition (see *Terminal disposition*): a lost conflict-checked claim race is a normal, continue-able outcome a driver re-selects past, **never `halted`** — re-sync (re-run the `repository.prepare` operation) and re-select. No worktree yet. +Claim by transaction: the `change.claim` operation with `--id --revision ` (the exact revision from the step-1 bundle). When the dispatch prompt carried a **run context** token, pass it to the claim as --run-context : the claim validates it against the started run, records durable proof binding this dispatch to its successful claim, and the parent's keyed verdict resolves ownership from that proof; an invalid or conflicting run context is a typed refusal that writes nothing — never retried as an ungated claim. A claim without the token stays supported for ungated invocations. Also pass `--selection queue` on the selection path and `--selection named` on the named path: the run tracker counts a halt toward a loop's halt limit only for a change picked from the queue. In the **metadata working tree** the operation reloads fresh origin, re-proves the change is still `proposed`, uniquely identified, build-ready, and has a resolved effective base, then applies the landed claim (`status: in-progress` + `branch: /` + `updated:` + `claimed_at:` — the lease the `change.reclaim` operation and the maintenance sweep's reclaim key on) and updates the change record, `## Artifacts` block, and inline board **together in one metadata commit** on the metadata branch, pushed to the metadata remote. It returns the new record revision, feature branch, lease classification, and a closed disposition; a wrong revision or a not-`proposed`/not-build-ready/duplicate/unresolved-base change returns `contended`/a typed refusal that **writes nothing and creates no workspace**. A lost-response retry converges by re-reading authority — an already-held matching claim returns the applied receipt or a typed `already-claimed`, a foreign claim returns `contended`; never adopt a branch or workspace as proof the claim landed. A `contended` result is the **`contended`** disposition (see *Terminal disposition*): a lost conflict-checked claim race is a normal, continue-able outcome a driver re-selects past, **never `halted`** — re-sync (re-run the `repository.prepare` operation) and re-select. No worktree yet. A claim of a `proposed` record that still carries a `## Run halted` section removes that section in the same transaction. **Resuming a halted in-progress change** — one the caller re-dispatches by id after a `run.verify` verdict of **`run-halted`** — goes through the `change.resume-halted` operation with `--id --revision --acknowledge-quiescent`, never a fresh claim: it requires the exact marked record and the explicit `--acknowledge-quiescent` acknowledgement that the prior worker is quiescent, reprobes the branch/workspace/live gate, refreshes the claim, and removes exactly the `## Run halted` marker section while preserving every other byte and checkpoint — it never resets or adopts a workspace whose writer may be live. It refuses (writing nothing) without the acknowledgement, on revision drift (`contended`), or on a live gate lock. A change that instead reached `proposed` through the `change.reclaim` operation carries no live claim, so it re-enters through the ordinary claim above. The claim and resume both render the inline board in their own transaction, so no separate Board pass runs here. Starting the resume also passes through the run tracker, which refuses a second run over one that has not verifiably stopped — **read `references/edge-paths.md` now (blocking)** for those run-tracker resume refusals and their remedies. @@ -179,9 +179,9 @@ Every run ends by declaring exactly **one** of four dispositions, so any driver | `advanced` | Built a change → PR opened (Step 7 reached), or completed a results-artifact change (done and archived, with a valid results artifact attached). | continue | | `contended` | Selected a change but lost the conflict-checked claim (Step 2); **nothing built**. | continue — re-select next | | `drained` | No build-ready+claimable change in scope (Step 1's empty queue). | **stop** | -| `halted` | Stopped needing a human — fundamentally-invalidated design (Step 3) or a hard error. Recorded on the metadata branch as a `## Run halted` section through the `change.halt` operation — see Step 3 for the write; the `run.verify` operation reads it back as the `run-halted` verdict. | **stop + surface** | +| `halted` | Stopped needing a human — fundamentally-invalidated design (Step 3) or a hard error. Recorded on the metadata branch as a `## Run halted` section through the `change.halt` operation — see Step 3 for the write; the `run.verify` operation reads it back as the `run-halted` verdict. | **stop + surface** — except a tracked loop whose verdict is `run-next`, which continues | -The driver's decision is binary: **continue on `advanced`/`contended`, stop on `drained`/`halted`.** The contract is **driver-agnostic** — it names run outcomes, not any one driver's mechanics; `/loop` is *recommended*, not required (see the README drain-pattern doc). +The driver's rule: **continue on `advanced`/`contended`, stop on `drained`/`halted`** — except that a tracked loop continues past `halted` when the run tracker's verdict is `run-next` (a halt on a change picked from the queue, still under `run.max_consecutive_halts`); an untracked driver has no verdict and stops on every `halted`. The contract is **driver-agnostic** — it names run outcomes, not any one driver's mechanics; `/loop` is *recommended*, not required (see the README drain-pattern doc). **The obligation is on the agent, not only the driver** — the run does not end until exactly one of the four is declared. A final report that declares a step-scoped or invented disposition — a build diff --git a/internal/cli/capability_production_test.go b/internal/cli/capability_production_test.go index a977acc01..9573fbc48 100644 --- a/internal/cli/capability_production_test.go +++ b/internal/cli/capability_production_test.go @@ -334,13 +334,15 @@ func TestRepresentativeSignatures(t *testing.T) { // change 0491: human Stop keyed by the run key alone — the two required // flags sorted, then the optional repo dir; no positional tail. "run.cancel": "--key --reason [--repo-dir ]", + // run.reset-halts sets the per-repository halt count back to 0: optional repo dir only. + "run.reset-halts": "[--repo-dir ]", // change 0489: the task owner and the scope/receipt flags are gone; every // owner runs its resolved suite command, so there is no `--` argv tail. // change 0493: --idempotent-suite-gate is gone (no drive relaunches). "gate.drive.start": "--owner --run-root [--branch ] [--change-id ] [--cwd ] [--env-hash ] [--phase ] [--ref ] [--repo-dir ] [--run-context ] [--task-id ]", // change 0472 (ADR-0129 rows 40, 40a): the record revision rides on // --revision, and relink's pin on --expect-revision. - "change.claim": "--id --revision [--repo-dir ] [--run-context ]", + "change.claim": "--id --revision [--repo-dir ] [--run-context ] [--selection ]", "change.relink": "--expect-revision --id [--adopt-pr ] [--adopt-pr-head] [--expect-branch ] [--expect-head ] [--expect-pr ] [--repo-dir ]", "finalize.block": "--attempt --head --id --input --pr-number --reason --revision [--repo-dir ]", "finalize.merge": "--head --id --revision [--admin] [--repo-dir ]", @@ -364,6 +366,10 @@ func TestRepresentativeSignatures(t *testing.T) { if e, ok := entryByID(entries, "run.start"); !ok || strings.Join(e.Effects, " ") != "local-write process-control" { t.Errorf("run.start effects = %v, want [local-write process-control]", e.Effects) } + // run.reset-halts only rewrites the local halt-count file. + if e, ok := entryByID(entries, "run.reset-halts"); !ok || strings.Join(e.Effects, " ") != "local-write" { + t.Errorf("run.reset-halts effects = %v, want [local-write]", e.Effects) + } // open reads the corpus, prepares the metadata checkout, and launches the // system opener. if e, ok := entryByID(entries, "open"); !ok || strings.Join(e.Effects, " ") != "local-write process-control read" { diff --git a/internal/cli/change.go b/internal/cli/change.go index 398df0913..6e14e0ca5 100644 --- a/internal/cli/change.go +++ b/internal/cli/change.go @@ -100,9 +100,11 @@ func newChangeCommand(setResult func(app.OperationResult)) *cobra.Command { "Claim a build-ready change at an exact revision, moving it to in-progress", func(c *cobra.Command, deps app.PlanningDeps, repoDir string, req app.ChangeClaimRequest) { req.RunContext, _ = c.Flags().GetString("run-context") - setResult(app.ChangeClaim(c.Context(), deps, repoDir, req)) + req.Selection, _ = c.Flags().GetString("selection") + setResult(changeClaimRunner(c.Context(), deps, repoDir, req)) }, EffectMetadataWrite) claim.Flags().String("run-context", "", "run-context `token` from run start, binding this claim to its started run (optional; omitted for an untracked claim)") + claim.Flags().String("selection", "", "how this change was chosen: `mode` queue (picked from the build-ready queue) or named (the run named it); any other value is recorded as unknown") refreshClaim := changeIDRevisionSubcommand("refresh-claim", "Re-stamp an in-progress change's claim lease at an exact revision", @@ -437,6 +439,11 @@ func changeInputSubcommand[T any](verb, short string, run func(c *cobra.Command, // carry no authored Markdown, so they take scalar flags (Global Constraints: // request files are for authored Markdown, never these). run receives the // resolved dependencies, repo directory, and decoded request. +// changeClaimRunner is the app entry point `change claim` dispatches to. It is a +// package variable so a test can capture the request the command built from its +// flags without a real repository. +var changeClaimRunner = app.ChangeClaim + func changeIDRevisionSubcommand(verb, short string, run func(c *cobra.Command, deps app.PlanningDeps, repoDir string, req app.ChangeClaimRequest), effects ...Effect) *cobra.Command { cmd := &cobra.Command{ Use: verb, diff --git a/internal/cli/change_test.go b/internal/cli/change_test.go index d1494ae45..bfc8ea72f 100644 --- a/internal/cli/change_test.go +++ b/internal/cli/change_test.go @@ -2,11 +2,13 @@ package cli import ( "bytes" + "context" "os" "path/filepath" "strings" "testing" + "github.com/danielhanold/docket/internal/app" "github.com/danielhanold/docket/internal/testsupport" ) @@ -687,3 +689,34 @@ func TestChangeRelinkReachesOperation(t *testing.T) { t.Fatalf("must be exactly one newline-terminated document, got %q", out) } } + +// TestChangeClaimSelectionFlagReachesRequest proves `change claim --selection` +// is copied into the request handed to the claim operation. Without it every +// claim records an unknown selection and every loop halt reads as unknown. +func TestChangeClaimSelectionFlagReachesRequest(t *testing.T) { + old := changeClaimRunner + t.Cleanup(func() { changeClaimRunner = old }) + var got app.ChangeClaimRequest + called := false + changeClaimRunner = func(ctx context.Context, deps app.PlanningDeps, repoDir string, req app.ChangeClaimRequest) app.ChangeClaimResult { + called = true + got = req + return old(ctx, deps, repoDir, app.ChangeClaimRequest{}) + } + _, errS, _ := runCLI(t, "change", "claim", + "--id", "7", "--revision", "1234123412341234123412341234123412341234", + "--selection", "queue", + "--repo-dir", testsupport.TempDir(t), "--json") + if errS != "" { + t.Fatalf("unexpected stderr %q", errS) + } + if !called { + t.Fatalf("change claim never reached the claim operation") + } + if got.Selection != app.ClaimSelectionQueue { + t.Fatalf("request Selection = %q, want %q", got.Selection, app.ClaimSelectionQueue) + } + if got.ID != 7 { + t.Fatalf("request ID = %d, want 7", got.ID) + } +} diff --git a/internal/cli/install.go b/internal/cli/install.go index 5dab9d1e2..6e849f84e 100644 --- a/internal/cli/install.go +++ b/internal/cli/install.go @@ -77,6 +77,7 @@ var assetIndependent = map[string]bool{ "run verdict": true, "run continue": true, "run cancel": true, + "run reset-halts": true, "learning": true, // the group itself; it reports a missing command "learning record": true, "learning update": true, diff --git a/internal/cli/run.go b/internal/cli/run.go index 2e763c828..c04942f1a 100644 --- a/internal/cli/run.go +++ b/internal/cli/run.go @@ -234,7 +234,27 @@ func newRunCommand(setResult func(app.OperationResult)) *cobra.Command { _ = cancel.MarkFlagRequired("key") _ = cancel.MarkFlagRequired("reason") - runCmd.AddCommand(verify, runStart, runVerdict, gateClaim, cancel) + // reset-halts sets the per-repository halt count back to 0, so a loop stopped at + // run.max_consecutive_halts can carry on. Only a person runs it; an agent never + // resets the count on its own. + resetHalts := &cobra.Command{ + Use: "reset-halts", + Short: "Set the count of implement-next halts in a row back to 0", + Args: cobra.NoArgs, + // local-write: rewrites the halt-count file under the per-repo state folder. + Annotations: capability("run.reset-halts", EffectLocalWrite), + RunE: func(c *cobra.Command, _ []string) error { + repoDir, err := resolveRepoDir(c) + if err != nil { + return err + } + setResult(app.RunResetHalts(repoDir)) + return nil + }, + } + resetHalts.Flags().String("repo-dir", "", "repository `dir` to operate on (default: current directory)") + + runCmd.AddCommand(verify, runStart, runVerdict, gateClaim, cancel, resetHalts) return runCmd } diff --git a/internal/config/config.go b/internal/config/config.go index 36fd2fcad..0af3f74a2 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -178,6 +178,10 @@ type Run struct { // start, counting the original dispatch. Positive; snapshotted into the // RunTrackerRecord at mint. MaxAttempts Value[int] `json:"max_attempts"` + // MaxConsecutiveHalts caps how many changes picked from the queue may + // halt in a row before a tracked implement-next loop stops. Positive; read + // at verdict time, never snapshotted. + MaxConsecutiveHalts Value[int] `json:"max_consecutive_halts"` } type Learnings struct { diff --git a/internal/config/decode_test.go b/internal/config/decode_test.go index 93e1c9ad4..f6c92135c 100644 --- a/internal/config/decode_test.go +++ b/internal/config/decode_test.go @@ -108,6 +108,9 @@ func decodeAcceptanceCases() []decodeCase { {row: "run.max_attempts", path: "run.max_attempts", block: "run:\n max_attempts: 3\n", flow: "run: {max_attempts: 3}\n", value: 3}, + {row: "run.max_consecutive_halts", path: "run.max_consecutive_halts", + block: "run:\n max_consecutive_halts: 3\n", + flow: "run: {max_consecutive_halts: 3}\n", value: 3}, {row: "review.min_fix_severity", path: "review.min_fix_severity", block: "review:\n min_fix_severity: blocker\n", diff --git a/internal/config/defaults.go b/internal/config/defaults.go index f7d9b9e82..c1301e6f6 100644 --- a/internal/config/defaults.go +++ b/internal/config/defaults.go @@ -42,7 +42,7 @@ func builtinEffective() Effective { TestCommand: builtinValue(""), MaxAttempts: builtinValue(4), }, - Run: Run{MaxAttempts: builtinValue(2)}, + Run: Run{MaxAttempts: builtinValue(2), MaxConsecutiveHalts: builtinValue(2)}, Learnings: Learnings{Enabled: builtinValue(true)}, Reclaim: Reclaim{ LeaseTTL: builtinValue(72), diff --git a/internal/config/defaults_test.go b/internal/config/defaults_test.go index 51b8022c0..b0a643905 100644 --- a/internal/config/defaults_test.go +++ b/internal/config/defaults_test.go @@ -167,6 +167,7 @@ func TestBuiltinEffectiveMatchesRegistryDefaults(t *testing.T) { "build.test_command": eff.Build.TestCommand.Value, "build.max_attempts": eff.Build.MaxAttempts.Value, "run.max_attempts": eff.Run.MaxAttempts.Value, + "run.max_consecutive_halts": eff.Run.MaxConsecutiveHalts.Value, "learnings.enabled": eff.Learnings.Enabled.Value, "reclaim.lease_ttl": eff.Reclaim.LeaseTTL.Value, "reclaim.auto": eff.Reclaim.Auto.Value, diff --git a/internal/config/resolve.go b/internal/config/resolve.go index c609d12c6..d08769cc3 100644 --- a/internal/config/resolve.go +++ b/internal/config/resolve.go @@ -314,6 +314,7 @@ func (r *resolution) assemble(byLayer map[LayerKind]map[string]leafDecl) (Effect set(assign(&eff.Build.TestCommand, r.declared, "build.test_command")) set(assign(&eff.Build.MaxAttempts, r.declared, "build.max_attempts")) set(assign(&eff.Run.MaxAttempts, r.declared, "run.max_attempts")) + set(assign(&eff.Run.MaxConsecutiveHalts, r.declared, "run.max_consecutive_halts")) set(assign(&eff.Learnings.Enabled, r.declared, "learnings.enabled")) set(assign(&eff.Reclaim.LeaseTTL, r.declared, "reclaim.lease_ttl")) set(assign(&eff.Reclaim.Auto, r.declared, "reclaim.auto")) diff --git a/internal/config/resolve_test.go b/internal/config/resolve_test.go index 450c5f85e..d62e556f6 100644 --- a/internal/config/resolve_test.go +++ b/internal/config/resolve_test.go @@ -84,6 +84,8 @@ func effectiveLeaf(t *testing.T, eff Effective, path string) (any, Provenance, b return eff.Build.MaxAttempts.Value, eff.Build.MaxAttempts.Provenance, eff.Build.MaxAttempts.Explicit case "run.max_attempts": return eff.Run.MaxAttempts.Value, eff.Run.MaxAttempts.Provenance, eff.Run.MaxAttempts.Explicit + case "run.max_consecutive_halts": + return eff.Run.MaxConsecutiveHalts.Value, eff.Run.MaxConsecutiveHalts.Provenance, eff.Run.MaxConsecutiveHalts.Explicit case "learnings.enabled": return eff.Learnings.Enabled.Value, eff.Learnings.Enabled.Provenance, eff.Learnings.Enabled.Explicit case "reclaim.lease_ttl": @@ -127,6 +129,10 @@ func runMax(n int) string { return fmt.Sprintf("run:\n max_attempts: %d\n", n) } +func runHalts(n int) string { + return fmt.Sprintf("run:\n max_consecutive_halts: %d\n", n) +} + // TestResolveBoardDefaults pins the built-in board presentation: the canonical // six-token permutation, and one updated/desc sort per section, all // non-explicit built-in. @@ -508,6 +514,39 @@ func TestPrecedenceRunMaxAttempts(t *testing.T) { } } +// TestPrecedenceRunMaxConsecutiveHalts pins run.max_consecutive_halts through the full four-layer +// precedence — the built-in default is 2. +func TestPrecedenceRunMaxConsecutiveHalts(t *testing.T) { + cases := []struct { + name string + sources []Source + want int + layer LayerKind + explicit bool + }{ + {"nothing declared wins the built-in default", nil, 2, LayerBuiltIn, false}, + {"global alone", []Source{srcG(runHalts(3))}, 3, LayerGlobal, true}, + {"repository beats global", []Source{srcG(runHalts(3)), srcR(runHalts(4))}, 4, LayerRepository, true}, + {"repository-local beats everything", []Source{srcG(runHalts(3)), srcR(runHalts(4)), srcL(runHalts(5))}, 5, LayerRepositoryLocal, true}, + {"repository-local beats global with no repository layer", []Source{srcG(runHalts(3)), srcL(runHalts(5))}, 5, LayerRepositoryLocal, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + res := mustResolve(t, tc.sources, mainCtx) + got := res.effective.Run.MaxConsecutiveHalts + if got.Value != tc.want { + t.Errorf("run.max_consecutive_halts = %d, want %d", got.Value, tc.want) + } + if got.Provenance.Layer != tc.layer { + t.Errorf("run.max_consecutive_halts provenance layer = %q, want %q", got.Provenance.Layer, tc.layer) + } + if got.Explicit != tc.explicit { + t.Errorf("run.max_consecutive_halts explicit = %v, want %v", got.Explicit, tc.explicit) + } + }) + } +} + // A leaf outside Effective (learnings.cap is inert) still resolves through the // same precedence, because the classifier reads `declared`, not Effective. func TestPrecedenceForNonEffectiveLeaf(t *testing.T) { diff --git a/internal/config/schema.go b/internal/config/schema.go index e41b8d49e..654116e20 100644 --- a/internal/config/schema.go +++ b/internal/config/schema.go @@ -329,6 +329,8 @@ func buildRegistry() []pathSpec { // run. The outer implement-next run tracker's own attempt policy (change 0421). {path: "run.max_attempts", kind: kindInt, def: 2, merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: intLeaf(1)}, + {path: "run.max_consecutive_halts", kind: kindInt, def: 2, + merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: intLeaf(1)}, // 16-17: review. {path: "review.min_fix_severity", kind: kindString, diff --git a/internal/config/schema_test.go b/internal/config/schema_test.go index 39d75d3e7..03e9e8b06 100644 --- a/internal/config/schema_test.go +++ b/internal/config/schema_test.go @@ -25,7 +25,7 @@ func TestRegistryPathSetMatchesV092(t *testing.T) { "leak_check.match_word", "open.artifacts", "build.checkpoint", "build.gate", "build.test_command", "build.max_attempts", - "run.max_attempts", + "run.max_attempts", "run.max_consecutive_halts", "review.min_fix_severity", "review.max_fix_tasks", "gate_observation_budget", "delegation_observation_budget", "board_surfaces", @@ -131,6 +131,7 @@ func TestRegistryDefaults(t *testing.T) { "build.test_command": "", "build.max_attempts": 4, "run.max_attempts": 2, + "run.max_consecutive_halts": 2, "review.min_fix_severity": "minor", "review.max_fix_tasks": 10, "gate_observation_budget": 30, @@ -328,6 +329,11 @@ func TestLeafValidators(t *testing.T) { {"run max attempts zero", "run.max_attempts", "0", nil, CodeInvalidValue}, {"run max attempts negative", "run.max_attempts", "-2", nil, CodeInvalidValue}, {"run max attempts string", "run.max_attempts", `"two"`, nil, CodeInvalidType}, + {"run halts explicit", "run.max_consecutive_halts", "5", 5, ""}, + {"run halts one", "run.max_consecutive_halts", "1", 1, ""}, + {"run halts zero", "run.max_consecutive_halts", "0", nil, CodeInvalidValue}, + {"run halts negative", "run.max_consecutive_halts", "-1", nil, CodeInvalidValue}, + {"run halts string", "run.max_consecutive_halts", `"two"`, nil, CodeInvalidType}, // enum membership. {"enum ok", "finalize.gate", "local", "local", ""}, diff --git a/internal/config/setting_paths_test.go b/internal/config/setting_paths_test.go index 023de4d26..ec09f2181 100644 --- a/internal/config/setting_paths_test.go +++ b/internal/config/setting_paths_test.go @@ -44,7 +44,7 @@ func TestSettingPathsSupportSplit(t *testing.T) { "finalize.gate", "finalize.test_command", "finalize.require_pr_approval", "finalize.resolver_max_attempts", "finalize.repair_max_attempts", "build.gate", "build.test_command", "build.max_attempts", - "run.max_attempts", + "run.max_attempts", "run.max_consecutive_halts", "review.min_fix_severity", "review.max_fix_tasks", "reclaim.lease_ttl", "reclaim.auto", "leak_check.match_word", diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index fa87438e2..060acf46d 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -206,7 +206,7 @@ var skillBudgets = []skillBudget{ {"docket-finalize-change/SKILL.md", 243, 6254}, // 0567: step 10 cleans each carried_ids child after the root (243/6191 -> 243/6254); 0551: step 1 checks the change out into its own workspace first (241/6033 -> 243/6191); 0532 review: both finalize gate dispatches carry the Visibility payload line (239/6020 -> 241/6033); 0532: the private-repository writing rule and visibility hand-off (239/6000 -> 239/6020); 0529 review: the PR-backlink repoint is a best-effort follow-up after the archive push, for root-archived descendants too (239/5984 -> 239/6000); 0529: close-out repoints the merged PR description's backlink; pr-backlink-pending is a retryable warning (239/5936 -> 239/5984); 0525 review: workspace-remnant rides any finished-workspace disposition and is named in the final report; branch-rules-unavailable comes only from the probing run (239/5910 -> 239/5936); 0525: plan-gated merges carry branch-rules-unavailable into closeout notes; cleanup reports workspace-remnant and names what blocked a workspace (239/5820 -> 239/5910); 0515 review: the refused-notes fallback names every dropped note in the final report (238/5809 -> 239/5820); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (238/5708 -> 238/5809); 0515: the repair sign-off is retired; a green repair merges (238/5808 -> 238/5708); 0517: the repaired-head evidence.record carries --owner finalize and records finalize.test_command (238/5790 -> 238/5808); 0502 review: clear-block re-reads the revision after the block lands (238/5771 -> 238/5790); 0502: repair sign-off records finalize.block before publishing the repaired head (238/5733 -> 238/5771); 0502: "loop" means /loop only (238/5729 -> 238/5733); 0502: repair sign-off is the human running finalize.clear-block (238/5666 -> 238/5729); 0502: the repaired head is re-gated through the gate driver (236/5568 -> 238/5666); 0502: the dummy-mode paragraph is deleted (238/5641 -> 236/5568); 0455: +record-invalid refusal (structural scope, findings remedy, merged-outside-docket precedence) in step 8 (word ceiling 5520 -> 5647); 0442: +post-publication base-advance guidance (word ceiling 5421 -> 5520); de-duplicated the shared forward-rebase mechanic against the 0438 unpublished-case paragraph (reclaimed 57 words), but the distinct published-refresh facts plus the retained 0438 guidance cannot fit the old ceiling without deleting required guidance; 0411: +reconciliation-write recovery exception paragraph in the resolver loop (ceilings 238/5232 -> 239/5421); 0413: +generated-bundle mixed-conflict handoff sentence in the resolver-loop block (word ceiling 5200 -> 5232); 0419: +repair-attempt budget payload line and rewired repair contract (line ceiling 236 -> 238); 0393: +exact payload, marker, and direct-dispatch lines atop 0349/0410 (see note above) {"docket-finalize-change/references/gate-failure.md", 162, 2111}, // 0532 review: the gate-agent payload names Visibility (161/2109 -> 162/2111); 0515 review: the refused-notes fallback names every dropped note in the final report (160/2098 -> 161/2109); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (153/2005 -> 160/2098); 0515: the repair sign-off is retired; a green repair merges (160/2086 -> 153/2005); 0517: the repaired-head evidence.record carries --owner finalize (159/2081 -> 160/2086); 0502 review: clear-block re-reads the revision after the block lands (157/2062 -> 159/2081); 0502: repair sign-off records finalize.block before publishing the repaired head (155/2028 -> 157/2062); 0502: the embedded-bundle rule is conditioned on docket's own repository (155/2024 -> 155/2028); 0502: "loop" means /loop only (155/2027 -> 155/2024); 0502: repair sign-off is the human running finalize.clear-block; the marker lifecycle names what removes it (154/2013 -> 155/2027); 0502: the repaired head is re-gated through the gate driver (148/1937 -> 154/2013); 0497: +wait-for-the-leftover-group sentence (146/1901 -> 148/1937); 0493: the gate relaunch is retired (145/1892 -> 146/1901); 0491: the run id is retired (145/1894 -> 145/1892); 0490: the shared-slot note became the shared worktree-lock note (147/1901 -> 145/1894); 0411: +reconciliation-write exception section and abort-set carve-out (ceilings 135/1472 -> 147/1901); 0413: +conflicted_paths-lists-authored-only rule in the resolver-report section (line ceiling 133 -> 135, word ceiling 1465 -> 1472); 0419: +repair-attempt budget payload and rewired repair contract prose (word ceiling 1450 -> 1465); 0349: +reserve-before-dispatch resolver protocol prose; 0375: +worktree-slot note for the scopeless finalize gate (120/1300 -> 133/1450) {"docket-groom-next/SKILL.md", 78, 2377}, // 0560 review: a revise that sets or lifts a hold changes the row's readiness (78/2370 -> 78/2377); 0560: the Step-4 hold paragraph (76/2282 -> 78/2370); 0559: the Step-4 deliverable, type, and branch_prefix paragraph (78/2215 -> 76/2282); 0550: the Step-4 reprioritize paragraph and the stub-edit priority route (76/2141 -> 78/2215); 0532: the private-repository writing rule and visibility hand-off (76/2109 -> 76/2141); 0531: the metadata worktree and remote come from the repository.prepare context (76/2102 -> 76/2109); 0502 rebase onto 0509: carried the edit-a-stub revise route and groom-exit-scoped STOPs (76/2012 -> 76/2102); 0502: "loop" means /loop only (76/2011 -> 76/2012); 0502: one metadata layout — the docket branch and the .docket/ worktree (76/2010 -> 76/2011); 0502: selection bands key on auto_groomable itself (76/2009 -> 76/2010); 0502: invoke superpowers:brainstorming by name (76/2037 -> 76/2009); 0502: the dummy-mode pointer is deleted (78/2080 -> 76/2037); 0461: +Step-4 retitle paragraph (title on change.groom; lines 77 -> 78, words 1996 -> 2081); +not-retitleable refusal code (2081 -> 2082); 0382: +typed rearm exit (word ceiling 1889 -> 1996); 0445: +revise route for already-groomed explicit ids (Step 1) and the fifth Step-4 exit (word ceiling 1650 -> 1813); +spec_version pin for a spec-body revise (1813 -> 1849); +revise spec_markdown excludes the backlink block (1849 -> 1850); +revise in the description and the revise contended/board clauses (1850 -> 1889) - {"docket-implement-next/SKILL.md", 218, 8555}, // 0560 review: on the named path on-hold also qualifies at the Step-1 confirm (218/8548 -> 218/8555); 0560: on-hold joins the readiness vocabulary and skip reasons; a held change is built when named (218/8518 -> 218/8548); 0559: the results-artifact ending pointer, postcondition row, and advanced meaning (215/8411 -> 218/8518); 0532: the private-repository writing rule and visibility hand-off (212/8282 -> 215/8411); 0531: the metadata worktree and remote come from the repository.prepare context (216/8443 -> 212/8282); 0517: evidence.record reads the gate command from build configuration (216/8438 -> 216/8443); 0502 rebase onto 0510: carried the Step 6.5 Backlog match paragraph and verdict pointers (214/8039 -> 216/8438); 0502 review: the controller dispatches the review tier wrapper; the skill dispatches nothing (214/8023 -> 214/8039); 0502: "loop" means /loop only (214/8058 -> 214/8057); 0502: one metadata layout — the docket branch and the .docket/ worktree (214/8042 -> 214/8058); 0502: the review payload names the resolved build.gate value; build_gate spellings become build.gate (214/8020 -> 214/8042); 0502: change.reclaim replaces reclaim-claims; the claim removes a leftover ## Run halted (214/8009 -> 214/8020); 0502: terminal-publication narration is deleted (214/8037 -> 214/8009); 0502: the severity floor is read as review.min_fix_severity through diagnostic.config (214/8034 -> 214/8037); 0502: the fixed role skills replace the $SKILL_* sites (214/8257 -> 214/8034); 0502: the dummy-mode paragraph and PR-body clause are deleted (216/8356 -> 214/8257); 0497: +Step 5 halted-build evidence kept verbatim in ## Run halted (216/8325 -> 216/8356); 0498 review: checkpoint (ii) persist wording (8320 -> 8325); 0498: +Step 6.5 review-findings homes, condensation exception, Human-actions class rule (214/8161 -> 216/8320); 0491: the run id is retired (214/8183 -> 214/8161); 0488 review: build-owned starts carry --change-id/--run-context (word ceiling 8162 -> 8183); 0488: run context and run id name only build-owned starts (word ceiling 8175 -> 8162); 0467 review fix: +the repair worker's post-fix re-run is a build-owned start (word ceiling 8165 -> 8175); 0467: +run id threaded to prepare-scope and build-owned starts (word ceiling 8080 -> 8165); 0455: +pr.publish record-invalid refusal clause (word ceiling 8025 -> 8080); 0448: +named-invocation branch; bounded own-dependency closeout moved to edge-paths.md (ceilings 210/7716 -> 214/8270 -> 214/8025); 0393: +exact payload, marker, and direct-dispatch lines atop 0410/0354/0376; 0375: +run-tracker resume pointer (word ceiling 7530 -> 7547); 0440: reader-first results prose; 0502: drop change citations and Go v1 narration (214/8057 -> 214/8023) + {"docket-implement-next/SKILL.md", 218, 8637}, // 0570: the --selection claim sentence and the run-next driver rule (218/8555 -> 218/8637); 0560 review: on the named path on-hold also qualifies at the Step-1 confirm (218/8548 -> 218/8555); 0560: on-hold joins the readiness vocabulary and skip reasons; a held change is built when named (218/8518 -> 218/8548); 0559: the results-artifact ending pointer, postcondition row, and advanced meaning (215/8411 -> 218/8518); 0532: the private-repository writing rule and visibility hand-off (212/8282 -> 215/8411); 0531: the metadata worktree and remote come from the repository.prepare context (216/8443 -> 212/8282); 0517: evidence.record reads the gate command from build configuration (216/8438 -> 216/8443); 0502 rebase onto 0510: carried the Step 6.5 Backlog match paragraph and verdict pointers (214/8039 -> 216/8438); 0502 review: the controller dispatches the review tier wrapper; the skill dispatches nothing (214/8023 -> 214/8039); 0502: "loop" means /loop only (214/8058 -> 214/8057); 0502: one metadata layout — the docket branch and the .docket/ worktree (214/8042 -> 214/8058); 0502: the review payload names the resolved build.gate value; build_gate spellings become build.gate (214/8020 -> 214/8042); 0502: change.reclaim replaces reclaim-claims; the claim removes a leftover ## Run halted (214/8009 -> 214/8020); 0502: terminal-publication narration is deleted (214/8037 -> 214/8009); 0502: the severity floor is read as review.min_fix_severity through diagnostic.config (214/8034 -> 214/8037); 0502: the fixed role skills replace the $SKILL_* sites (214/8257 -> 214/8034); 0502: the dummy-mode paragraph and PR-body clause are deleted (216/8356 -> 214/8257); 0497: +Step 5 halted-build evidence kept verbatim in ## Run halted (216/8325 -> 216/8356); 0498 review: checkpoint (ii) persist wording (8320 -> 8325); 0498: +Step 6.5 review-findings homes, condensation exception, Human-actions class rule (214/8161 -> 216/8320); 0491: the run id is retired (214/8183 -> 214/8161); 0488 review: build-owned starts carry --change-id/--run-context (word ceiling 8162 -> 8183); 0488: run context and run id name only build-owned starts (word ceiling 8175 -> 8162); 0467 review fix: +the repair worker's post-fix re-run is a build-owned start (word ceiling 8165 -> 8175); 0467: +run id threaded to prepare-scope and build-owned starts (word ceiling 8080 -> 8165); 0455: +pr.publish record-invalid refusal clause (word ceiling 8025 -> 8080); 0448: +named-invocation branch; bounded own-dependency closeout moved to edge-paths.md (ceilings 210/7716 -> 214/8270 -> 214/8025); 0393: +exact payload, marker, and direct-dispatch lines atop 0410/0354/0376; 0375: +run-tracker resume pointer (word ceiling 7530 -> 7547); 0440: reader-first results prose; 0502: drop change citations and Go v1 narration (214/8057 -> 214/8023) {"docket-implement-next/references/edge-paths.md", 109, 1265}, // 0532: the private-repository writing rule and visibility hand-off (109/1226 -> 109/1265); 0531: the metadata worktree and remote come from the repository.prepare context (118/1499 -> 109/1226); 0502: one metadata layout — the docket branch and the .docket/ worktree (118/1507 -> 118/1509); 0502: run.verify replaces verify-run (118/1505 -> 118/1507); 0502: terminal-publication narration is deleted (118/1513 -> 118/1505); 0502: the deferred results-only permit clause is deleted (118/1546 -> 118/1513); 0502: no custom plan location (118/1547 -> 118/1546); 0491: the run id is retired (118/1554 -> 118/1547); 0410: +resume/recovery + required-results reconciliation; 0375: +run-tracker resume refusals (78/1091 -> 93/1261); 0448: +named own-dependency closeout moved from SKILL.md (93/1261 -> 118/1554); 0502: drop change citations and Go v1 narration (118/1509 -> 118/1499) {"docket-implement-next/references/fix-pass.md", 189, 1963}, // 0532: the private-repository writing rule and visibility hand-off (187/1943 -> 189/1963); 0502 rebase onto 0510: carried the backlog-verdict pointer for reported findings (186/1929 -> 187/1943); 0502: "loop" means /loop only (190/1962 -> 190/1967); 0502: undispatchable fix worker halts (192/1991 -> 190/1962); 0502: renamed from fix-loop.md; 0498 review: results-file antecedent (1989 -> 1991); 0498: +review-findings condensation at final consolidation (190/1958 -> 192/1989); 0410: +findings-to-results checkpoint linkage (see note above); 0502: drop change citations and Go v1 narration (190/1967 -> 186/1929) {"docket-implement-next/references/results-artifact.md", 79, 775}, // 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) @@ -287,7 +287,7 @@ func TestSkillSizeBudgets(t *testing.T) { const ( dispatchStart = "docket:dispatch:start" dispatchEnd = "docket:dispatch:end" - dispatchBudget = 932 // 0501: run.start's stop note replaces the "honest owner-lifecycle caveat" wording, and coordinators are told not to relay it (was 897); 0491: the run id is retired from the run-tracker block; the 0443 operation-id wording is added (was 1154); 0477: the Codex request-file sentence labels the run context for `--run-context` on change.claim and the gate drive, since the gate drive now takes the same flag (was 1153); 0467 review fix-3: the Codex agent.enter request file also carries the unchanged run id for --run-id (was 1140); 0467: step 1 copies the into the dispatch prompt alongside the run context (was 1137); 0375: step 1 now states the arm prints the run id and where it threads (run.cancel --run-id and every --run-id dispatch flag), so the documented human Stop path is followable; this rides atop the earlier 0375 Stop/cancel + resume-after-stop contract (was 1110). Re-baselined at the exact new count; still strictly below the retired roster (the anti-regrowth invariant below). + dispatchBudget = 964 // 0570: the run-next sentence (was 932); 0501: run.start's stop note replaces the "honest owner-lifecycle caveat" wording, and coordinators are told not to relay it (was 897); 0491: the run id is retired from the run-tracker block; the 0443 operation-id wording is added (was 1154); 0477: the Codex request-file sentence labels the run context for `--run-context` on change.claim and the gate drive, since the gate drive now takes the same flag (was 1153); 0467 review fix-3: the Codex agent.enter request file also carries the unchanged run id for --run-id (was 1140); 0467: step 1 copies the into the dispatch prompt alongside the run context (was 1137); 0375: step 1 now states the arm prints the run id and where it threads (run.cancel --run-id and every --run-id dispatch flag), so the documented human Stop path is followable; this rides atop the earlier 0375 Stop/cancel + resume-after-stop contract (was 1110). Re-baselined at the exact new count; still strictly below the retired roster (the anti-regrowth invariant below). dispatchOld = 1156 // pre-0334 roster block; the ceiling must stay strictly below it. ) diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index b7286adc6..9efc3fa33 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1317,6 +1317,27 @@ var alignmentContracts = []proseContract{ "stack parent #A killed — re-parent, un-stack, or kill", "Kill refuses while the change has built stacked descendants", }}, + // change 0570 — a tracked loop carries on past a halt on a change it picked + // from the queue (verdict run-next); the claim names how the change was + // chosen; an untracked driver still stops on every halted. The dispatch + // block's run-next sentence must stay in both of its copies. + {sentinel: "change_0570_run_next_dispatch", file: "cursor-rules/run-tracker.md", + present: []string{ + "`run-next run-halted ` also forbids re-dispatching that change", + "only a loop driver (`/loop`) may go on to its next run, with a fresh `run.start`", + }}, + {sentinel: "change_0570_run_next_dispatch", file: "AGENTS.md", + present: []string{ + "`run-next run-halted ` also forbids re-dispatching that change", + "only a loop driver (`/loop`) may go on to its next run, with a fresh `run.start`", + }}, + {sentinel: "change_0570_driver_contract", file: "skills/docket-implement-next/SKILL.md", + present: []string{ + "pass `--selection queue` on the selection path and `--selection named` on the named path", + "a tracked loop whose verdict is `run-next`, which continues", + "an untracked driver has no verdict and stops on every `halted`", + }, + absent: []string{"The driver's decision is binary"}}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/skills/docket-implement-next/SKILL.md b/skills/docket-implement-next/SKILL.md index 94e17a919..e8fef5d33 100644 --- a/skills/docket-implement-next/SKILL.md +++ b/skills/docket-implement-next/SKILL.md @@ -46,7 +46,7 @@ The digest is an **accelerator, not the sole channel**: the authoritative read i ### Step 2 — Claim (conflict-checked write) -Claim by transaction: the `change.claim` operation with `--id --revision ` (the exact revision from the step-1 bundle). When the dispatch prompt carried a **run context** token, pass it to the claim as --run-context : the claim validates it against the started run, records durable proof binding this dispatch to its successful claim, and the parent's keyed verdict resolves ownership from that proof; an invalid or conflicting run context is a typed refusal that writes nothing — never retried as an ungated claim. A claim without the token stays supported for ungated invocations. In the **metadata working tree** the operation reloads fresh origin, re-proves the change is still `proposed`, uniquely identified, build-ready, and has a resolved effective base, then applies the landed claim (`status: in-progress` + `branch: /` + `updated:` + `claimed_at:` — the lease the `change.reclaim` operation and the maintenance sweep's reclaim key on) and updates the change record, `## Artifacts` block, and inline board **together in one metadata commit** on the metadata branch, pushed to the metadata remote. It returns the new record revision, feature branch, lease classification, and a closed disposition; a wrong revision or a not-`proposed`/not-build-ready/duplicate/unresolved-base change returns `contended`/a typed refusal that **writes nothing and creates no workspace**. A lost-response retry converges by re-reading authority — an already-held matching claim returns the applied receipt or a typed `already-claimed`, a foreign claim returns `contended`; never adopt a branch or workspace as proof the claim landed. A `contended` result is the **`contended`** disposition (see *Terminal disposition*): a lost conflict-checked claim race is a normal, continue-able outcome a driver re-selects past, **never `halted`** — re-sync (re-run the `repository.prepare` operation) and re-select. No worktree yet. +Claim by transaction: the `change.claim` operation with `--id --revision ` (the exact revision from the step-1 bundle). When the dispatch prompt carried a **run context** token, pass it to the claim as --run-context : the claim validates it against the started run, records durable proof binding this dispatch to its successful claim, and the parent's keyed verdict resolves ownership from that proof; an invalid or conflicting run context is a typed refusal that writes nothing — never retried as an ungated claim. A claim without the token stays supported for ungated invocations. Also pass `--selection queue` on the selection path and `--selection named` on the named path: the run tracker counts a halt toward a loop's halt limit only for a change picked from the queue. In the **metadata working tree** the operation reloads fresh origin, re-proves the change is still `proposed`, uniquely identified, build-ready, and has a resolved effective base, then applies the landed claim (`status: in-progress` + `branch: /` + `updated:` + `claimed_at:` — the lease the `change.reclaim` operation and the maintenance sweep's reclaim key on) and updates the change record, `## Artifacts` block, and inline board **together in one metadata commit** on the metadata branch, pushed to the metadata remote. It returns the new record revision, feature branch, lease classification, and a closed disposition; a wrong revision or a not-`proposed`/not-build-ready/duplicate/unresolved-base change returns `contended`/a typed refusal that **writes nothing and creates no workspace**. A lost-response retry converges by re-reading authority — an already-held matching claim returns the applied receipt or a typed `already-claimed`, a foreign claim returns `contended`; never adopt a branch or workspace as proof the claim landed. A `contended` result is the **`contended`** disposition (see *Terminal disposition*): a lost conflict-checked claim race is a normal, continue-able outcome a driver re-selects past, **never `halted`** — re-sync (re-run the `repository.prepare` operation) and re-select. No worktree yet. A claim of a `proposed` record that still carries a `## Run halted` section removes that section in the same transaction. **Resuming a halted in-progress change** — one the caller re-dispatches by id after a `run.verify` verdict of **`run-halted`** — goes through the `change.resume-halted` operation with `--id --revision --acknowledge-quiescent`, never a fresh claim: it requires the exact marked record and the explicit `--acknowledge-quiescent` acknowledgement that the prior worker is quiescent, reprobes the branch/workspace/live gate, refreshes the claim, and removes exactly the `## Run halted` marker section while preserving every other byte and checkpoint — it never resets or adopts a workspace whose writer may be live. It refuses (writing nothing) without the acknowledgement, on revision drift (`contended`), or on a live gate lock. A change that instead reached `proposed` through the `change.reclaim` operation carries no live claim, so it re-enters through the ordinary claim above. The claim and resume both render the inline board in their own transaction, so no separate Board pass runs here. Starting the resume also passes through the run tracker, which refuses a second run over one that has not verifiably stopped — **read `references/edge-paths.md` now (blocking)** for those run-tracker resume refusals and their remedies. @@ -179,9 +179,9 @@ Every run ends by declaring exactly **one** of four dispositions, so any driver | `advanced` | Built a change → PR opened (Step 7 reached), or completed a results-artifact change (done and archived, with a valid results artifact attached). | continue | | `contended` | Selected a change but lost the conflict-checked claim (Step 2); **nothing built**. | continue — re-select next | | `drained` | No build-ready+claimable change in scope (Step 1's empty queue). | **stop** | -| `halted` | Stopped needing a human — fundamentally-invalidated design (Step 3) or a hard error. Recorded on the metadata branch as a `## Run halted` section through the `change.halt` operation — see Step 3 for the write; the `run.verify` operation reads it back as the `run-halted` verdict. | **stop + surface** | +| `halted` | Stopped needing a human — fundamentally-invalidated design (Step 3) or a hard error. Recorded on the metadata branch as a `## Run halted` section through the `change.halt` operation — see Step 3 for the write; the `run.verify` operation reads it back as the `run-halted` verdict. | **stop + surface** — except a tracked loop whose verdict is `run-next`, which continues | -The driver's decision is binary: **continue on `advanced`/`contended`, stop on `drained`/`halted`.** The contract is **driver-agnostic** — it names run outcomes, not any one driver's mechanics; `/loop` is *recommended*, not required (see the README drain-pattern doc). +The driver's rule: **continue on `advanced`/`contended`, stop on `drained`/`halted`** — except that a tracked loop continues past `halted` when the run tracker's verdict is `run-next` (a halt on a change picked from the queue, still under `run.max_consecutive_halts`); an untracked driver has no verdict and stops on every `halted`. The contract is **driver-agnostic** — it names run outcomes, not any one driver's mechanics; `/loop` is *recommended*, not required (see the README drain-pattern doc). **The obligation is on the agent, not only the driver** — the run does not end until exactly one of the four is declared. A final report that declares a step-scoped or invented disposition — a build