tldr-experts 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,409 @@
 # Changelog
 
+## 0.30.0 — 2026-09-15
+
+### Fixed
+
+- **The plan-over-stage advisory speaks only when the plan asks for more than 2× what the stage
+  holds, instead of on every overage (#302).** #281 gave a scaled plan a voice before a spawn —
+  right, and the reason a $16.20 stage over a $114.00 plan no longer has to be learned from a dead
+  developer. Unconditioned, that voice was loud: MEASURED by the #281 pre-merge reviewer over 30
+  priced run dirs on one machine, 8 of them (27%; 54% in one of the two workspaces) had
+  `priceScale < 1`, at severities from 0.095 to 0.85 — and at the mild end the plan asks ~18% more
+  than the stage and usually finishes without one story reaching its scaled cap. A line on every
+  Build entry and every Plan gate for a case that harmless is the wallpaper that teaches an
+  operator to skip the channel before the run where it matters, the same shape #285/#290 already
+  cost once. So the PROACTIVE channel gets a bar — `PLAN_OVER_STAGE_ADVISORY_SCALE`, strictly below
+  0.5, in `caps.ts` beside the reasoning, one constant that both call sites inherit by calling the
+  same function — and the REACTIVE one keeps none: `capDeathReason` still names the formula, the
+  scale and the lever at every scale, because a story that actually died on its cap is never
+  wallpaper. The severe tail the channel exists for (0.095, >10× the stage) still speaks before the
+  spawn.
+
+- **The provider's rate-limit warning is read instead of dropped, and a Build parks at a story
+  boundary before the wall instead of spending developers into it (#298, warning half).** The signal
+  was never missing, and the repo did not have to leave its own tree to find that out: `claude
+  --output-format stream-json` emits `{"type":"rate_limit_event","rate_limit_info":{…}}` WHILE a turn
+  is still working, `agentEvents.ts`'s own header has documented one since the transcript was
+  recorded, and `test/fixtures/agent/stream-json.jsonl:9` carries it in full — while
+  `test/agent-stream.test.ts` pinned it as noise, in the same list as `"{broken"`. It fell through
+  the dispatch `switch`'s `default:` and vanished, so the only trace a quota wall left was a
+  developer dying mid-story with the provider's own `success` on the record. Measured on a live
+  field turn (#298's thread): `status: "allowed_warning"` at `utilization: 0.92`, then `0.94`,
+  arriving BEFORE the limit bit, on a turn that then finished normally and cost $2.00 — and
+  `resetsAt` is an epoch integer, so a reader has a real deadline and never parses "resets 6pm". The
+  frame is now a typed `rate-limit` event, `AgentOutcome` carries the last one a turn streamed, and
+  a Build stage that sees a status the provider itself does not call `allowed` starts NO further
+  story: the stories already running finish and settle, the next one is not started, and the run
+  says so with the provider's own words on stdout and an `agent.rate_limited` event carrying the
+  status, the window, the utilization and the reset instant — written once per stage whether or not
+  a story was left to withhold, because a one-story wave that warns is a warning the operator still
+  acts on, and carried as the REASON on every story the handoff lists as not started, where the
+  audit record would otherwise say this stage had no reason for it. The park test is the provider's WORD,
+  never a utilization threshold this repo picked — the CLI already owns the judgement of when a
+  window has surpassed its threshold, and a second opinion here would be a second implementation of
+  it. Nothing waits and nothing retries: waiting to a reset the provider stated, and classifying the
+  DEATH itself, need a terminal capture nobody has obtained (measured negative, twice) and are filed
+  as the other half. Absent stays absent — a frame that states no utilization records
+  `utilization_absent: "not recorded — …"` rather than a `0` that would read as an empty window, and
+  a Codex turn carries no frame at all rather than a fabricated `allowed`, because nothing here has
+  measured what `codex exec --json` says about a quota.
+
+- **`tldrx ship` refuses an epic carrying a merged diff NOBODY judged, instead of opening a PR over
+  it (#311).** #282 closed the case where a reviewer read a story's diff and said `changes` — a
+  rejection that stands, with the rejected code on the epic branch. It left the sibling open: three
+  settle paths park a story at `review` with `merged: true` beside a verdict that is not an opinion
+  about anything. The reviewer was refused for want of money and never spawned (#289) or the run was
+  cancelled before the review (#305), both recorded `n-a`; or the reviewer died mid-read, recorded
+  `error`. The run's own ledger already said what that class means — "`n-a` and `error` mean nothing
+  did [judge it]" — and `ship` asked it nothing: with one story `done` beside the parked one, #210's
+  refusal does not fire, #282's predicate does not match, and the PR opens with an unread diff in it
+  while the body lists that story under `## Not done` without one word that its code is in the diff.
+  Under `--ship merge` that body is read by nobody before auto-merge arms. It is now a refusal of its
+  own (exit 2, the family #282 uses: what is missing is a gate, and one of the three causes is
+  literally the money refusal), reading the SAME predicate the as-is path reads — `reviewNeverCompleted`,
+  not a second list of verdicts to fall out of step. It is a separate line rather than a widening of
+  #282's, because the REMEDY differs and a refusal that names the wrong verb sends the operator to the
+  wrong place: a rejection is a story to reopen and build again, while an unjudged merge is a review
+  still owed, and `tldrx next` settles a story parked at `review` by re-running the review with no
+  developer spawned. The line says which of the two non-verdicts it was, never just "unjudged": never
+  spawned and died mid-read are different problems with different next steps.
+
+- **`tldrx init` probes a repo's four commands at once, and says which one it is waiting on
+  (#180).** MEASURED on `6fd2af2` with four 500 ms probes: they started at 0, 501, 1003 and
+  1504 ms and `probeCommands` returned after 2006 ms — the SUM of the four deadlines, not the
+  longest. The same shape at the real `PROBE_TIMEOUT_MS` is 4 × 120 s = eight minutes for ONE
+  repo whose toolchain hangs, multiplied by the repo count, and for all of it detection had
+  nothing to say: `repoStart` fires once per repo and the next line is the repo's summary.
+  Nothing about a probe ever wanted the one before it — each has its own argv, races its OWN
+  deadline and writes its OWN key — so the four now run together, which puts the same fixture at
+  502 ms (4.0×) and bounds one repo at one deadline. Bounding the wait was only half of it: two
+  minutes of a live view with nothing on it still reads as hung, so a probe that starts a process
+  announces itself and its outcome, `init` names the repo and the slots still in flight, and the
+  plain-mode heartbeat — the CI-log line, where there is no spinner to prove anything is alive —
+  carries that detail instead of only a clock. The rows are still assembled in slot order, not in
+  the order the probes happened to finish: `workspace.yml` is a file people diff, and a key order
+  that depended on which build was slower today would be a diff that means nothing. A slot decided
+  without starting anything — `run`, a command needing a shell, an absent one, a `--no-probe` skip
+  — announces nothing, because it costs no wait to report.
+- **A Plan refused for a formatting slip gets ONE bounded repair turn instead of a full re-plan
+  (#288).** MEASURED on a live unattended run (0.18.3, `run auto --until-done`): the planner wrote
+  `acceptance: [ … ], test_plan: [ … ]` on one line — a flow-mapping comma inside a block mapping —
+  in three of three stories. The `plan` check refused it correctly, naming the file, the line and
+  the column; the stage then failed, because on a failed stage `tldrx next` IS a fresh stage. A
+  $2.19 Plan turn and one of the five `--until-done` relaunches were spent re-deriving a plan whose
+  only defect the checker had already localised, and the second planner passed only because it
+  happened to put one key per line. Build has always had the shape this needed — a verdict, then a
+  second turn on the same branch — and Plan had nothing between "refused" and "plan again". Now a
+  `plan` refusal whose every issue names a file that EXISTS re-spawns the planner ONCE over those
+  files, with the refusal VERBATIM and the same generated `## Output schemas` contract, and re-runs
+  the checks; a second refusal fails the stage exactly as before, in the same exit family, naming
+  both. Every bound is deliberate: the class is the CHECK's own answer computed from its issues and
+  not from the wording of its message (a refusal with nothing on disk to edit — "the Plan wrote no
+  stories" — earns no round, because a repair turn there is a re-plan wearing a fix round's
+  clothes); one round per planner turn, read off the `role: plan-fix` row rather than a counter
+  that could drift; headless only, since a `--prepare`/`--commit` cycle is a person for whom the
+  refusal is already the fix list, and it says so rather than doing nothing silently; and the money
+  goes through `wouldExceed`, the same predicate the budget gate decides on, at the same `agentCap`
+  the planner's own turn got — a phase that cannot fund the repair is told so and nothing is spent.
+  The turn is recorded like any other (a task row, an `agent.result`), with an additive
+  `plan.fix_round` event beside them saying why it happened and naming the row that holds the
+  dollars — one figure in one place. The Plan prompt also now states the rule the field run broke:
+  one key per line, never two joined by a comma.
+
+- **Five more stack-pack reviewer Checks asked the read-only reviewer to do something it holds no
+  tool for, and one of them had no answer waiting for it anywhere (#195, #182's sibling).** #182
+  moved the can-it-fail Check to the developer because the mutation it asked for needs a write and
+  a test run, and the reviewer's whole allowance is `Read`, `Grep`, `Glob`, `Bash(git diff *)` — but
+  four more Checks, one per language pack, carried the identical contradiction: "run the typecheck
+  and lint commands declared in `.tldrx/workspace.yml`" sits sixty-odd lines above the SAME rendered
+  prompt's "Do not re-run them. They passed; that is why you are being asked," which follows the
+  `## Definition of Done — already re-run by the facilitator` section that already hands the
+  reviewer every declared command's exit code. Unlike #182's mutation, this one is not a producer's
+  obligation moved to whoever can perform it — the answer was already ON THE PAGE, so the four
+  Checks now point the reviewer at the Definition of Done section instead of asking it to run
+  anything a second time. The `postgres-testcontainers` overlay's ordering Check ("run the new tests
+  alone, then again … and compare") is a different case: nothing re-runs it at the Definition of
+  Done, so owner decision (Slack) gives it #182's shape instead — the overlay's own Defaults section
+  now asks the developer to run each new database test alone and with its neighbours and record the
+  result beside the test, and the Check asks the reviewer only whether that record is there.
+
+- **A stage death no longer recommends the retry the budget is about to refuse (#232, remaining
+  half).** Every failed stage ended with the same literal — *"cost is recorded, not refunded —
+  retry with `tldrx next`"* — printed whether or not the phase could fund that retry. On a phase
+  sized to hold exactly one attempt of its stage (what `run new` wrote before #170, and what every
+  run created before 2026-09-09 keeps for life) `tldrx next` comes straight back as exit 2, so the
+  advice sent the operator to buy the refusal themselves: measured twice in one evening on the run
+  #232 was filed from, and once more on a second workspace where the starved phase was the last
+  one. The other half of #232 shipped in `efb4eee` — `budget show`'s `next` column says `NO-RETRY`
+  before a cent is spent — and this is the same fact said where the operator actually is when it
+  bites: the line now names the refusal, both figures, the shortfall and the `budget raise` that
+  clears it. It predicts the GATE and not the budget's health, using the gate's OWN inputs — what
+  the phase has left, the same remaining-work estimate the brake compares it against, the same
+  `planRebalance`, and this invocation's own `--rebalance-finished` state — deliberately: #232's
+  own comments measured how badly a derived estimate reads on a partly unmetered run, and a second
+  opinion computed here would disagree with the refusal the operator then hits. **That last term is
+  the one a first version of this fix got wrong, and a reviewer caught it before it merged**: the
+  rebalance is ON by default under `run auto` (#330), so a shortfall that finished phases can cover
+  is moved out of them before anything is refused, and the advice was telling the operator to raise
+  a ceiling on a run whose very next relaunch would have funded the retry by itself. `tldrx next`
+  alone never rebalances, so the same starved phase is refused through one door and funded through
+  the other; the advice now names which door it is standing in. Under a rebalancing launch whose
+  donors cover the shortfall it says the retry funds itself, names the donor phase and the move,
+  and says that a bare `tldrx next` is not that door — it stops short of a promise, because the
+  grant check on each move happens after this line is written. When no finished phase can cover it,
+  the refusal prediction stands through either door, with how short it still is *with all of it*.
+  Where this gate does not decide the retry at all — `on_exceed: warn` refuses nothing,
+  a `host-tokens` phase is a category error the dollar brake must never judge, an `attended_by:
+  host` run is allowed past it by policy — the plain line is printed unchanged: those are "not this
+  gate's call", which is not the same as "affordable", and claiming a refusal there would be the
+  invented value the house rules forbid. The failure's `signature` (#297) is untouched and is still
+  the failure's own sentence, never this line.
+
+- **A Build refusal built from a CACHED base reading says so, and a relaunch re-measures the red
+  instead of being served it (#339).** MEASURED on a live `run auto --until-done`, 2026-09-15: two
+  Definition-of-Done commands exited 127 on the untouched base tree, the framework refused, the
+  operator installed the two missing binaries and confirmed all four commands green by hand — and
+  the next attempt printed the SAME refusal, byte for byte, over a base tree that was by then
+  repaired. Then the supervisor stopped the loop on it: "a refusal that repeats verbatim is not one
+  a relaunch moves", with four relaunches unspent and the run ended early on a workspace where the
+  thing complained about was fixed. Two halves compose into that. A cached refusal reproduces
+  itself exactly — which is correct for a cache and is the one condition the repeat guard reads —
+  and nothing anywhere said the second reading had not been taken. So: a refusal whose evidence was
+  re-used now names it as re-used, says when it was measured, against which base sha, and when it
+  stops being trusted, and it adds the sentence the generic advice cannot carry — that an edit to
+  `.tldrx/workspace.yml` or a base that moves clears a cached reading, but a repair the cache
+  cannot see (a binary installed, a service started) is not re-measured until that expiry. The
+  supervisor's repeat guard now reads a FRESHNESS field the producer sets rather than diffing text:
+  a repeat whose evidence was measured stops the loop exactly as it did, a repeat that was re-used
+  is relaunched and says why. And the relaunch is no longer served the same cache — an attempt that
+  follows a refusal re-probes a RED base unconditionally, the way `--prepare` already did, because
+  the attempt before it asked for exactly this repair. Greens are still re-used, so the cost of
+  that is bounded by the commands that are actually broken. The 30-minute red TTL is untouched;
+  it was never what saved this run, and the reason it was not is filed separately (#340).
+
+- **A red Definition-of-Done command is measured TWICE before it pins a story `blocked`, and the
+  record carries both exit codes (#163, sub-fix 1).** MEASURED on a .NET workspace, 2026-09-05: a
+  story's DoD gate returned `dotnet test` → exit 2, so the story blocked; the operator then ran the
+  identical suite twice — in the story worktree and on the epic branch — and got exit 0 with 2860
+  tests and 0 failing. The red was contention over a container runtime, and it had consumed the
+  story's last attempt. `blocked` is terminal in-run, so a human had to reopen the story by hand.
+  The hole was not the terminality, which is a defensible rule: it was that a story's red was never
+  re-measured, so a flake and a defect were written down identically and nobody reading the block
+  could tell which one they had. The framework already did this one level up — the base-tree
+  pre-flight re-measures a command the cache cannot answer — and the story's own red had no
+  equivalent. It does now: when a command goes red on a story, the identical command runs once more
+  in the same tree, and the `check.failed` event, the story's `dod` row and the blocked reason all
+  carry what the second run said. **Nothing about terminality changes** — a red that reproduces
+  blocks exactly as before, and a red that does NOT reproduce also still blocks; it is now blocked
+  with a sentence that says the command passed the second time, which is the difference between
+  reopening the story and going looking for a bug that is not there. When no second run could be
+  taken the record says so with the reason and no number (§7): a command whose binary the tree
+  never had would only measure the same absence again, and a refused command never ran, so it has
+  no first reading to reproduce. **A red that TIMED OUT is re-run too, so a timing-out
+  Definition-of-Done command now costs up to two timeout periods instead of one.** That is stated
+  rather than buried: the owner approved one extra run of the suite, and doubling a timeout is a
+  fair reading of it but was not in the framing. Timeouts are deliberately not carved out — the
+  measured case was contention over a container runtime, and contention is exactly what makes a
+  suite hang rather than fail cleanly, so a carve-out would leave the likeliest flake the one thing
+  never measured. The blocked reason names both readings and marks either of them `(timed out)`,
+  so the record says which kind of red was paid for twice. Owner decision, answered on Slack:
+  re-run the red command once and record both exit codes. One reading per spawn, shared with the base-tree path, so the two cannot
+  disagree about what a timeout's exit code is or which line of a red suite is the summary.
+
+- **A fix-list sha that is too LONG is refused by name, instead of reading as no sha at all
+  (#163, sub-fix 3).** The abbreviation edge of `Resolved: yes <sha>` was closed in 0.10.0 — a
+  7-39 hex claim that verifies is rewritten to the 40 `rev-parse` returned — and the same
+  grammar, `\b([0-9a-f]{7,40})\b`, was failing silently at the other edge, which is the
+  dangerous direction §7 names. No position inside a 41-character hex run is a word boundary, so
+  an over-long token produced NO match: the line read as a bare `Resolved: yes` that named
+  nothing, and the shape fault was never stated. Measured while fixing it, and worse than the
+  issue reported: the scan did not stop there but carried on to the next hex word on the line, so
+  `Resolved: yes <41 hex> (see 9f2c1ab)` closed the finding over `9f2c1ab` — a DIFFERENT commit
+  from the one the line claims, which is an audit record inventing its own evidence. A token of
+  41+ hex characters is now refused by name and by count, through the `claimed-unverified`
+  sentence #130 already writes into the file, so the finding keeps holding the story and the
+  record says why; a refusal anywhere on the line refuses the whole read, so the answer cannot
+  depend on which side of the bad token a good one happens to sit. 7-39 is still accepted and
+  still canonicalised — nothing a person legitimately types is refused. The grammar now lives in
+  one leaf, `readResolvedSha`, read by both the parser and the rewriter, which is what makes the
+  token that gets verified and the token that gets replaced provably the same span. The refusal is
+  written once and read everywhere: `verifyResolutions` is the single site that withdraws a claim,
+  so the file, the story's blocked reason and the stdout report all carry the SAME sentence. They
+  did not before — the file would have named the 41-character token while the report a human reads
+  first said `named no commit to point at`, which is two records of one event disagreeing.
+
+- **`budget show` says a phase cannot afford its own retry BEFORE the money is spent, instead of
+  labelling it `ok` up to the refusal (closes #232).** A phase whose ceiling equals ONE attempt of
+  its stage refuses every retry after the first cent — by arithmetic, not by policy — and the
+  framework's own remedy for a failed stage ("cost is recorded, not refunded — retry with `tldrx
+  next`") is exactly what it then refuses. Measured twice in one run, and on a second workspace in
+  the LAST phase, where every dollar has already gone. `run new` has sized phases at `attempts ×`
+  their stage since #170 so it can no longer be created, and #330's rebalance reaches it only when
+  some FINISHED phase has slack to give — with none, the run stops at exit 2, the one exit nothing
+  unattended can leave. The `next` column now answers the SIZE question in its own word: `NO-RETRY`
+  with the exact raise, and `n/e` for a phase there is nothing to size in. The verdict reads the
+  stage's DECLARED `budget_usd` and its own `attempts:`, never the derived estimate beside it —
+  #232's own comments measured why: on a partly unmetered run the estimate is too small, so
+  `ceiling / est.` reports headroom that is not there, and the less a run is metered the safer that
+  ratio claims it is. A declaration does not move with metering. `attempts: 1` declares no retry, so
+  one attempt's worth is the right size for it and still reads `ok`. Nothing about the refusal moved:
+  `blocked`, `remaining` and `est.` are untouched and `tldrx next` still runs. One derivation
+  (`retrySizing`, `budget/wouldExceed.ts`), read back additively by `budget show --json`.
+
+- **A killed headless turn reads as `interrupted` and is handed a command the next line of code
+  accepts, instead of being called a `--prepare` bundle that never existed (closes #246, half
+  one).** MEASURED on a 0.16.1 field run: the `tldrx` process driving `run auto` died
+  SIGKILL-class (no handler ran), leaving the stage `running`, a dead pid in the `.lock`, and
+  `.agent/<stage>/pending.json` on disk. `run status` said "a `--prepare` bundle is waiting — run
+  the prompt and `tldrx next --commit <id>`"; that command was then REFUSED ("what is `ready`, not
+  `running`"), so the only advice the screen gave was a dead end, and nobody was going to run a
+  prompt by hand on an unattended run anyway. The mechanism is that the two states are
+  indistinguishable on disk: `runNext` writes the bundle BEFORE it branches on the mode, so every
+  headless spawn leaves exactly what a `--prepare` leaves, and `waiting.ts` derived `prepared`
+  from stage `running` + dead lock + a bundle without ever reading which mode opened the turn. The
+  ledger already knew — `stage.started` has carried `mode` since it was first written — so the
+  answer is now read off the newest `stage.started` for that stage
+  (`src/core/run/lastStart.ts`, one implementation, imported by both readers that had made this
+  identification independently). A tenth waiting kind, `interrupted`, says what happened and
+  prescribes `tldrx run auto <id>` — the command that actually resumes the run; `prepared` is
+  reserved for a bundle a `--prepare` really wrote. `Ctrl-C` shared the bug and is fixed with it:
+  `stopInFlightRun` preserved any `killed === 0` stage with a bundle as `running` forever, and now
+  preserves only one whose last start was a `prepare`. A ledger that does not say keeps the old
+  reading exactly — an absent record is not evidence of a spawn. The second half of #246, the
+  orphaned sub-agent's dollars being recorded nowhere while `spent_usd` reads a confident `0.00`,
+  is untouched and stays open.
+
+- **A Watch retry no longer re-buys a watcher card that already validated (closes #306).** The
+  Watch stage fails on the FIRST card that does not validate, and `tldrx next` / `run auto
+  --retry-failed` re-enter the executor from the top — so a run with N features where feature k
+  was refused spawned all N writers again, including the k-1 cards that had already validated and
+  been stamped. Each of those paid at least the `$0.25` cold-spawn floor for a card nothing had
+  refused, and on a two-feature field run (#301, run B) with a different card refused in each
+  attempt, every writer was bought at least twice. #301 made the second spend an edit rather than
+  a rewrite; this makes it zero. The headless path now takes one snapshot of disk as the stage is
+  entered, before anything spawns, and keeps a feature whose card passes the SAME
+  `parseWatcherCard` against the SAME source context the stage validates with — so the skip can
+  never hide a bad card, only decline to save money, and a card whose citations went stale in the
+  meantime is rewritten like any other. It is a snapshot rather than a per-feature read so that
+  one writer loose in the run directory can never decide whether the next feature is written at
+  all. A kept feature still gets its `tasks[]` row, with `cost_usd: 0.0`, `model: null` and
+  `session_id: null` — a measured zero, not the `metered: false` of a turn billed to a host
+  session — and the stage's report names every kept card, so a `$0.00` row is never read as a
+  writer that silently did nothing. `--prepare`/`--commit` is untouched.
+
+- **The epic branch Build cuts is claimed in `run.yml` at the cut, not when the stage returns
+  (closes #262).** Reported from a field workspace: a `run auto` loop was killed mid-Build,
+  relaunched, and was refused its OWN epic — "`epic/<slug>` already exists … refusing to stack
+  this run's commits onto someone else's epic" — with `tldrx next --reuse-epic` the only way back
+  in, a flag `run auto` cannot pass. Same sentence as #248, different mechanism, and #248's fix
+  cannot reach this one: #248 closed the THROW path, where a process is still alive to run its
+  catch. Here the process is GONE. `ExecutorOutcome.epicBranches` merges into `build.epic_branch`
+  only after the executor RETURNS, and a Build stage does not return for as long as a developer
+  turn takes — so a SIGKILL, an OOM kill or a cut session anywhere in that window left
+  `epic/<slug>` in the repo with nothing in the record claiming it. SIGINT and SIGTERM are hooked
+  (`src/cli/signals.ts`); SIGKILL cannot be hooked by any process, so no handler was ever going to
+  cover this. The cut now records the claim itself, through the `ctx.claimEpicBranch` seam, once
+  per branch rather than once per story. It does NOT ride the write serializer and is not claimed
+  to: of `openStory`'s eight call sites, four wrap it in `this.writes.run` and four
+  (`prepare`, `prepareReview`, `commitReview`, `commit`) call it bare. What makes it safe is that
+  there is no `await` between the branch being cut and the claim, and the claim is synchronous —
+  so on every one of those paths the cut and its record are one uninterrupted step. The guard is
+  NOT widened: a branch this run did not cut is refused exactly as
+  before — the claim stays a RECORD, and the fix is to write the record when it is earned rather
+  than to teach the guard to accept inferred evidence. A `run.yml` save that cannot take the
+  workspace lock is NOT swallowed: it fails the stage naming the branch, the repo, why the write
+  failed and both ways back in, because a claim that could not be written is this defect happening
+  again in silence. Honest about how far this goes: the save is atomic against a KILLED PROCESS
+  (temp file, then `rename`), and it is not `fsync`ed — a power cut can still lose a write the
+  kernel had not flushed. It is pinned by a real SIGKILL of a real `tldrx next`, never a simulated
+  throw, which would only have re-tested #248.
+
+- **A Codex Build review no longer dies before the reviewer runs, and the provider's own refusal
+  arrives on one line (#148).** MEASURED on a live Build smoke run, published 0.7.0 +
+  codex-cli 0.153.0: the developer stage finished and 4 tests passed, then the review failed at
+  the API with `invalid_json_schema: fixlist.items.required must include every property (missing
+  n)`. Codex's structured-output API requires every DECLARED property to be listed as required;
+  `REVIEW_SCHEMA` declares optional fields at two levels — `fixlist` itself, and `n`, `severity`,
+  `where`, `detail`, `do_not` inside each item — and the spawn wrote that object to Codex's
+  `--output-schema` file verbatim. Every Codex review was refused before it began, so the story
+  paid an attempt for a turn the provider never ran. The translation happens at the Codex spawn
+  boundary ALONE (`codexSchema`, one implementation, §7): an optional property becomes
+  `anyOf: [<its schema>, {"type": "null"}]` and joins `required`, recursively, and the review
+  parser already reads a `null` exactly as it read the absent field — so nothing about
+  fail-closed moves, and a `fixlist` verdict with nothing readable in it is still `changes`.
+  `REVIEW_SCHEMA` itself is untouched and Claude's `--json-schema` still carries it byte for
+  byte; the test asserts both directions, because a fix at a provider seam that quietly edits the
+  shared contract is the failure this one was supposed to avoid. Second half, same issue: Codex
+  names its refusal in a pretty-printed block, and that sentence is quoted into a handoff where
+  every line must carry its own `[src: …]` — a multi-line reason became uncited continuation
+  lines that failed the claim-sources check. The Codex reason is now collapsed onto one line
+  rather than cut at the first, because the first line of that block is `{` and the WHY is two
+  lines down. Claude's failure text is passed through unchanged. The acceptance is MEASURED,
+  not argued from the error message: the pre-merge reviewer ran one real
+  `codex exec -s read-only --output-schema <the translated schema>` in an isolated directory
+  against an authenticated codex-cli 0.153.0 — the issue's own version — and it exited 0 with
+  no `invalid_json_schema` and the structured output `{"verdict": "approve", "summary":
+  "Approved with no findings.", "findings": [], "fixlist": null}`. That `"fixlist": null` is
+  the translation's whole point arriving back off the wire: the field the API refused to leave
+  optional comes home as the null this parser already reads as absent. Two readings, taken by
+  different hands — the schema bytes the child was handed, asserted in the test on every run,
+  and that one live call, which is not re-run by any gate.
+
+- **A still-open fix-list finding is re-checked against the EPIC tip before the Build gate, so a
+  defect a LATER story closed says so with the closing sha instead of reading `Resolved: no`
+  (#163, sub-fix 2).** MEASURED on a Next.js workspace, 2026-09-05: at a Build gate all 6
+  `fix-now` findings carried a resolving sha and the 3 `defer-with-log` entries read
+  `Resolved: no` — "correct PER STORY", in the host agent's own words — but two of those three
+  defects had in fact been closed later in the same run by a DIFFERENT story, which the host
+  verified by reading the code. Exactly one finding had genuinely shipped unfixed, the record
+  could not tell those apart, and so a human narrated the difference by hand at the gate. The hole
+  was structural rather than careless: verification asks whether a claim's sha is reachable from
+  the STORY's own branch, and it asks at the moment that story settles — a fix that lands later,
+  on somebody else's branch, and reaches the epic through a merge did not exist when the question
+  was asked and is not on the branch it was asked about. There was no third answer for it, so it
+  was recorded as the second. There is one now. After the last story settles and before the
+  handoff is written, every finding not already closed with evidence is re-checked against its
+  epic tip, and a sha that is reachable from the epic and NOT from the story's own branch is
+  recorded as what it is. **The two kinds of close are spelled apart, never flattened**:
+  `Resolved: yes <sha>` stays the story's own close, and a close a later story landed is
+  `Resolved: yes-on-epic <sha>` — a different word because it is a different fact about who fixed
+  it and where the fix lives. `yes-on-epic` is not `yes`, so nothing the sweep writes changes what
+  any gate decides; the finding is exactly as open afterwards as it was before, and a finding that
+  genuinely shipped unfixed still reads unfixed. **Nothing is ever re-marked on inference.** A
+  reachable commit the record already names is the only thing that closes anything here — never a
+  changed file, never a heading that resembles another story's work — so the sweep cannot invent
+  the one direction §7 refuses to be wrong in. **And it does not go quiet when it finds nothing.**
+  Every finding it examined gets a `Swept:` line saying what was measured and against which tip,
+  because a `Resolved: no` that has been re-checked against the whole run and one that only ever
+  meant "correct per story" were indistinguishable, and that indistinguishability is the defect.
+  A sweep that could NOT be taken — no epic branch recorded, a tip git will not resolve, a file
+  that cannot be re-read — names its reason on every finding and in the handoff's `## Unknowns`,
+  rather than reporting a clean sweep over a measurement nobody took. **And it asks the weaker
+  question too, in words that say it is weaker.** The three entries that Next.js gate got wrong
+  named no commit at all — nobody had claimed one — so re-checking shas the record already names
+  has nothing to say about exactly the findings a human had to read the code for. For those, the
+  sweep asks what that human asked first: did a commit on the EPIC, and not on this story's own
+  branch, CHANGE the file this finding cites? Up to three such commits come back named, on the
+  `Swept:` line and as their own `## Unknowns` bullet — and they resolve NOTHING. A changed file
+  is not a closed defect, and writing `Resolved: yes` off one would be the same lie arrived at
+  from the other side; what this replaces is a person grepping the run's commits by hand at the
+  gate, never a person's judgement about them. **A probe git REFUSED says that, too.** An
+  unresolvable story ref and a file nobody changed both come back as no commits, and writing
+  "no later commit changed this" over the first would be a measurement nobody took wearing the
+  words of one that was — so the refusal carries git's own reason onto the `Swept:` line and
+  into `## Unknowns`, and is never counted as a clean probe. `Swept:` and the
+  `yes-on-epic` word are additive: a fix list written before this change reads exactly as it did.
+
+### Changed
+
+- **The zero-touch launch recipe (EN and ES) now pairs `run auto` with `--wait-gates` and
+  `--wait-answers` everywhere it shows opening a run with `--gates none`, and says why: `--gates
+  none` sets the policy, but only `--wait-gates` lets `run auto` re-sign a parked `auto` gate once
+  the question that held it is auto-answered — without it the loop exits `awaiting human` on the
+  first gate that parks on a question, even though every one of its conditions already holds (see
+  #342).**
+
 ## 0.29.0 — 2026-09-15
 
 ### Changed

package/README.md

@@ -335,6 +335,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.30.0 | 2026-09-15 | `beta` | Seventeen changes that keep an unattended run moving instead of stranding. A cached Build refusal says so and a relaunch re-measures it (#339); a rate-limit warning is read instead of dropped, so a Build parks before the wall (#298); the plan-over-stage advisory speaks only past 2× (#302); a stage death stops recommending a retry the budget refuses (#232); a DoD command is measured twice, a fix-list finding is checked against the epic tip, and an over-long sha is refused by name (#163); a formatting slip gets one bounded repair turn (#288); five Checks stop asking the reviewer for what it can't do (#195); a Codex review no longer dies before it runs (#148); `tldrx init` probes four commands at once (#180); `tldrx ship` refuses a merged diff nobody judged (#311). Docs: the zero-touch recipe pairs `run auto` with `--wait-gates`/`--wait-answers` (#342). |
 | 0.29.0 | 2026-09-15 | `beta` | Sixteen changes that make an unattended run trust its own gates and its own numbers. Verdict integrity: a reviewer's `changes` must cite evidence (#326), a re-reviewed story's `changes` is consumed instead of parking it (#327), and a story blocked on a stale fix list settles `done` once resolved (#329). Fix-list flow: a headless fix list now buys its own fix round, and an approving reviewer's signature closes what it was shown (#327). Money and phase sizing: `run auto` rebalances a blocked phase's shortfall out of finished phases by default (#330), the `budget-gate` hook stops denying the launch that would fix the shortfall (#321), a Build gate no longer stops on paths outside the declared surface but carries them into the PR instead (#331), a parallel wave no longer hands two developers the same unspent money (#325), `budget show`/`run estimate`/the budget-gate hook price remaining work off the stage's own `attempts:` (#214), `run auto --until-done` states a token refusal in tokens rather than invented dollar words (#270), a Watch turn is recorded as unmetered rather than a false `$0.00` (#224), and a Watch spawn now records the ceiling it was given (#190). Dependency and safety: a Build gate names the story a dependent waits on (#303), the conflict-turn marker guard names unreadable paths, bounds its scan, and covers modified files too (#324), a developer's array-valued `notes` is joined instead of silently dropped (#217), and the Plan prompt states its per-item character cap where each field is described so an over-cap finding survives into the retry (#328). |
 | 0.28.1 | 2026-09-15 | `beta` | Two fixes so a reopened story's reason reaches the agents that need it. The developer and reviewer prompts now carry `## Why this story was reopened` — who signed it, whether it's a fix round, the note verbatim — off the same ledger value #308 reads, instead of the note reaching only a report line and #308's check (closes #322). `tldrx note --help` now says an operator note reaches no agent and names `dispatch-notes.md` as the channel that does (closes #151). |
 | 0.28.0 | 2026-09-15 | `beta` | Four changes that keep an unattended run moving instead of stranding on a person. A story whose merge-up to its epic conflicts in at most three of its own touched files gets one automated conflict turn instead of a person, guarded against committing conflict markers (#286). `story reopen` on a blocked story now releases every dependent it alone was holding, in the same command (#312). Seed's `Recommended:` line and the loop's question parser now share one grammar, so a citation-only recommendation no longer parks a run that `seed check` had already passed (#323). And an `absent:` needle over `facts.yml` no longer trips on a fact's own recording metadata, while an `auto` gate refused only by failed checks gets one automatic re-run before waiting for a person (#231). |

package/dist/hooks/answer-capture.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-erasdab5.js";
+} from "./chunk-fbmj1bk6.js";
 import {
   FactsStore,
   formatJaccard
@@ -13,7 +13,7 @@ import {
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-t6gbx3jg.js";
+} from "./chunk-77x6v0gg.js";
 import {
   PHASE_IDS
 } from "./chunk-g4d2v4jc.js";

package/dist/hooks/budget-gate.js

@@ -27,10 +27,10 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-w3d9kxcp.js";
+} from "./chunk-zpch8e2j.js";
 import {
   EventLog
-} from "./chunk-t6gbx3jg.js";
+} from "./chunk-77x6v0gg.js";
 import {
   cursorStage,
   hostTokensIn,

package/dist/hooks/{chunk-t6gbx3jg.js → chunk-77x6v0gg.js}

@@ -39,6 +39,7 @@ var EVENT_TYPES = [
   "task.done",
   "agent.spawned",
   "agent.result",
+  "agent.rate_limited",
   "question.asked",
   "question.answered",
   "gate.requested",
@@ -54,6 +55,7 @@ var EVENT_TYPES = [
   "story.review_retried",
   "story.work_rescued",
   "story.touches_widened",
+  "plan.fix_round",
   "epic.released",
   "worktree.foreign_work_aside",
   "worktree.foreign_work_restored",

package/dist/hooks/{chunk-erasdab5.js → chunk-fbmj1bk6.js}

@@ -5,7 +5,7 @@ import {
   evidencePath,
   gateEvidencePath,
   parseEvidence
-} from "./chunk-t6gbx3jg.js";
+} from "./chunk-77x6v0gg.js";
 import {
   openBlocks,
   parseQuestions

package/dist/hooks/{chunk-ggjxes7m.js → chunk-przta0a0.js}

@@ -9,7 +9,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-w3d9kxcp.js";
+} from "./chunk-zpch8e2j.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,
@@ -22,7 +22,7 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-t6gbx3jg.js";
+} from "./chunk-77x6v0gg.js";
 import {
   cursorStage,
   isAttendedByHostView,
@@ -881,8 +881,33 @@ function hasPreparedBundle(runDir, stageId) {
   return preparedBundles(runDir, stageId).length > 0;
 }
 
+// src/core/run/lastStart.ts
+function lastStageStartMode(runDir, stageId) {
+  const events = EventLog.forRun(runDir).readAll().events;
+  for (let index = events.length - 1;index >= 0; index -= 1) {
+    const event = events[index];
+    if (event === undefined)
+      continue;
+    if (event.type !== "stage.started" || event.stage !== stageId)
+      continue;
+    const mode = event.payload.mode;
+    return typeof mode === "string" && mode !== "" ? mode : null;
+  }
+  return null;
+}
+function startedHeadless(runDir, stageId) {
+  return lastStageStartMode(runDir, stageId) === "headless";
+}
+
 // src/core/run/waiting.ts
-var MOVABLE_KINDS = ["gate", "answer", "ready", "failed", "prepared"];
+var MOVABLE_KINDS = [
+  "gate",
+  "answer",
+  "ready",
+  "failed",
+  "prepared",
+  "interrupted"
+];
 function isMovable(kind) {
   return MOVABLE_KINDS.includes(kind);
 }
@@ -952,6 +977,13 @@ function waitingFor(run, runDir) {
           questions: open
         };
       }
+      if (startedHeadless(runDir, entry.stage.id)) {
+        return {
+          kind: "interrupted",
+          message: `${entry.phase.id}/${entry.stage.id} was interrupted — its headless turn's process is gone — ` + `\`tldrx run auto ${basename2(runDir)}\``,
+          questions: open
+        };
+      }
       if (hasPreparedBundle(runDir, entry.stage.id)) {
         return {
           kind: "prepared",

package/dist/hooks/{chunk-w3d9kxcp.js → chunk-zpch8e2j.js}

@@ -743,6 +743,9 @@ var MARKER_SCAN_MAX_BYTES = 4 * 1024 * 1024;
 // src/core/build/fixlist.ts
 var MAX_FIXLIST_ROUNDS = STAGE_TUNING_DEFAULTS.fixlistRounds;
 var FINDING_KINDS = ["correctness", "security", "docs", "style"];
+var CLAIMED_UNVERIFIED = "claimed-unverified";
+var CLOSED_ON_EPIC = "yes-on-epic";
+var CLAIMING_VERDICTS = new Set(["yes", CLAIMED_UNVERIFIED, CLOSED_ON_EPIC]);
 
 // src/core/build/refusalKind.ts
 var OUTCOME_ALREADY_REPORTED = "the facilitator re-runs the Definition of Done after you and records each command's exit " + "code, so the number the `echo` would print is measured and written down whether you " + "capture it or not";

package/dist/hooks/session-start.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   questionsCard
-} from "./chunk-erasdab5.js";
+} from "./chunk-fbmj1bk6.js";
 import"./chunk-gr83pq7x.js";
 import {
   allow,
@@ -20,17 +20,17 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-ggjxes7m.js";
+} from "./chunk-przta0a0.js";
 import {
   expertsDir,
   loadExperts,
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-w3d9kxcp.js";
+} from "./chunk-zpch8e2j.js";
 import {
   isFinished
-} from "./chunk-t6gbx3jg.js";
+} from "./chunk-77x6v0gg.js";
 import {
   openRunViews
 } from "./chunk-0d4csx4s.js";
@@ -628,6 +628,8 @@ function summaryOf(run, waiting, blocked) {
       return `run ${what} was closed by hand — ${waiting.message}`;
     case "prepared":
       return `run ${what} has a --prepare bundle waiting for the host session to run it`;
+    case "interrupted":
+      return `run ${what} was interrupted at ${run.cursor.phase}/${run.cursor.stage} and is waiting to be relaunched`;
     case "running":
       return `run ${what} is running ${run.cursor.phase}/${run.cursor.stage} right now`;
     default:
@@ -643,6 +645,8 @@ function commandFor(run, waiting) {
     case "ready":
     case "failed":
       return `tldrx next ${run.run}`;
+    case "interrupted":
+      return `tldrx run auto ${run.run}`;
     default:
       return "";
   }

package/dist/hooks/statusline.js

@@ -2,9 +2,9 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-ggjxes7m.js";
-import"./chunk-w3d9kxcp.js";
-import"./chunk-t6gbx3jg.js";
+} from "./chunk-przta0a0.js";
+import"./chunk-zpch8e2j.js";
+import"./chunk-77x6v0gg.js";
 import"./chunk-0d4csx4s.js";
 import"./chunk-g4d2v4jc.js";
 import"./chunk-857jhjmb.js";