tldr-experts 0.28.1 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,236 @@
 # Changelog
 
+## 0.29.0 — 2026-09-15
+
+### Changed
+
+- **A reviewer's `changes` verdict must cite its evidence, or it is refused as a malformed
+  envelope (closes #326).** MEASURED on a field run: a reviewer returned `changes` with summary
+  "test" and findings `["a","b"]`, and the framework recorded it as a real review — it spent the
+  story's attempt, blocked `done`, and would have quoted "test" to the next developer as why the
+  story is not done. Nothing checked a `changes` verdict's content; only a `refuted` fix-list
+  finding had to carry a citation. Owner decision (2026-09-14): a `changes` now pays the same
+  price — its `summary`, or one line of a finding, must END with an `[src: …]` token the §2.8
+  parser reads (the diff line that is wrong, the unmet acceptance criterion as
+  `03-plan/stories/<id>.md:<line>`, or `absent:<path>` for missing work). One that cites nothing
+  is a fault in the REPORT, so it takes the existing bounded format retry — re-prompted with the
+  refusal, no attempt spent, two corrections — and the third is recorded as `changes` exactly as
+  before. This deliberately reverses the part of #79's pin that called a citation-less `changes` a
+  judgement about the work; a `changes` that DOES cite still costs the attempt. The reviewer prompt
+  now states the rule under `changes` and carries the `[src: …]` grammar on every review, not only
+  when `fixlist` is on the table. The citation is read, not resolved: a token that parses but
+  points at nothing still passes, so this refuses the hollow envelope, not a wrong one.
+- **`tldrx run auto` now moves a blocked phase's shortfall out of finished phases by default
+  (closes #330).** The rebalance shipped opt-in in #314 because a phase ceiling is a person's
+  decision about money. An audit of `run auto`'s intervention episodes across two client
+  workspaces ranked stage/phase sizing as the #2 cause of a human stepping in: 22 episodes, 27
+  `budget.raised`, 7 `budget.blocked` (counts the audit measured, cited from #330), and not one raise note changed the work
+  (the audit's inferred reading of those notes). In a validation run the flag moved money twice
+  with nobody present. So a person was signing a move the framework could already prove safe.
+  Now a bare `run auto` makes it, and `--no-rebalance-finished` turns it off for a launch whose
+  phase ceilings must mean exactly what they say. `--rebalance-finished` is still accepted, and
+  passing both flags is exit 1, by name. The rules are unchanged: the run ceiling never grows, no
+  move passes a recorded grant, donors must be finished and metered with no unmetered turn, the
+  move is the exact shortfall or nothing, and each move is one `budget.raised` with the same
+  `source: run auto --rebalance-finished`. `tldrx next` on its own still never rebalances. The
+  `tldrx drive` mandate is unchanged on purpose: its unattended mode is refused `run auto`
+  outright (`attended_by: host`), and its attended mode drives `tldrx next`. No mandate-driven
+  turn ever reaches the move, so a sentence about it would teach something the driver cannot do.
+- **A headless fix list now buys its fix round in the same run, and the approving reviewer's
+  signature closes what it was shown (#327, owner decision "A: ronda + auto-cierre").** A reviewer
+  that signed with a `fix-now` finding used to park the story at `review`, on the grounds that
+  routing a fix list needed a host — measured live, that park stranded the story and the two
+  stories of the next wave behind it until a person intervened. Now the story is requeued without
+  spending an attempt, the developer is handed the open findings, and the next reviewer is shown
+  each one verbatim with the rule "approve only if every one is fixed". Its `approve` rewrites each
+  finding it was shown as `Resolved: yes <commit> — auto-closed: …` naming the reviewer session,
+  attempt and run — the existing line grammar, so every reader parses it unchanged, and checked
+  against git before the story may settle, so a sha that is not on the story branch reopens it. A
+  finding that reached the file after the prompt was rendered stays open and still blocks. The
+  test that pinned the park ("a headless run … parks the story") is inverted, citing the decision.
+  A host review is shown the same findings and closes nothing. No new event, `run.yml` field or
+  CLI verb.
+- **An `auto` Build gate no longer stops on paths outside the declared surface — it signs, and
+  carries them into the PR (closes #331).** A hold-surface audit of two client workspaces measured
+  `boundary` in 48 of 78 Build `held_by` values, the only reason on 6, and 7 intervention episodes
+  on it; every one ended in an approval or a `story widen` (the "no real catch" reading is inferred
+  from their notes). A condition that stops an unattended run and is always waved through is a
+  cost, not a check — but dropping it would lose the one question a reviewer asks first. So the
+  fact moves from the gate to the review: the auto note renders the boundary with "does not hold an
+  auto gate — it is carried into the PR body for review" and ends in `· warned by: boundary`;
+  `gate.requested` gains an additive `warned_by` beside `held_by` (present only when non-empty);
+  `tldrx next` prints a `warning: boundary — …` line; `tldrx run status` marks the gate row
+  `— warning: boundary`; and `tldrx ship` renders `## Outside declared scope — review these`,
+  every outside path, grouped under the story whose own measured `story.touches_widened` row names
+  it, the rest under `no story's measured diff names these`. One derivation: the gate and the PR
+  body both call `evaluateBoundary`, which now returns the uncapped list beside its detail. An
+  `agent` gate still falls to a person on a boundary, and a `human` gate is unchanged. **One
+  carve-out keeps the hold where the blast radius is not product code:** an outside path in
+  `SENSITIVE_PATH_CLASSES` (one exported constant beside `evaluateBoundary` — `ci`, `secrets`,
+  `infra`, `dependencies`) still holds an auto gate, named with its class
+  (`app:.github/workflows/deploy.yml [ci]`); declaring it in a story's `touches:` clears it. The
+  per-story grouping needs nobody to widen: the executor writes its own measured
+  `story.touches_widened` row for each story as it settles, and a real unattended Build then
+  `ship` puts the path under the story that wrote it. No exit
+  code changed; a check-only refusal with a boundary warning beside it is now eligible for
+  `run auto`'s bounded re-run, since the boundary no longer holds it.
+
+### Fixed
+
+- **A Build gate now names the story a dependent WAITS on, not only the stories that are
+  `blocked` (closes #303).** #280 correctly left a dependent of a `review`/`in_progress` story at
+  `todo` instead of recording a terminal `blocked` — but the gate only ever named literal
+  `blocked` stories (`storiesView`'s `firstBlocked`), so the sentence saying what S2 waits on
+  reached `04-build/handoff.md`'s `## Unknowns` and nowhere an operator watches: `gate.requested`,
+  its notification and the terminal `stories:` line said `S2 not started` and named no
+  dependency. That is the one thing to act on — `story reopen` refuses a story already `todo`,
+  and `run auto --until-done` does not relaunch an awaiting-human exit. MEASURED on the #280
+  fixture (S1 parked at `review` by a dying reviewer): the payload carried no key for S2 at all.
+  Now `gate.requested` and its notification carry three ADDITIVE keys, `waiting_story`,
+  `waiting_on` and `waiting_reason` — absent, never null, when nothing waits — and the summary
+  and terminal line say S2 waits on S1 (`review`). The wait is derived with the Build loop's own
+  `decidingHold`/`dependencyIsPending`, so a story that will BLOCK on a terminal dependency is
+  never reported as merely waiting, and `waiting_reason` is `dependencyWaitReason` — the
+  `## Unknowns` sentence, byte for byte. `story reopen`'s `depends_on` reader moved to
+  `buildProgress.ts` so both ask one reader. No event version or dashboard model bump.
+- **`run auto --until-done` stops a `host-tokens` refusal in tokens, not in dollar words it
+  never measured (closes #270).** Every `budget.blocked` went through one dollar-shaped
+  sentence, reading `remaining_usd` / `estimate_usd` through a helper that defaults a missing
+  field to `0`. The two `host-tokens` writers carry neither field, so a token refusal stopped
+  the supervisor with `remaining_usd $0.00 < estimate_usd $0.00` — a confident figure nothing
+  measured — and sent the operator to `tldrx budget raise`, a dollar command for a ceiling that
+  is a token allowance (and for the headless refusal, a raise that changes nothing: the way out
+  is `--prepare` or re-pricing to `metered-usd`, as the row's own reason already says). The stop
+  line now switches on `economy`, as the dashboard model already did: a `host-tokens` row names
+  the `host_tokens` / `ceiling_tokens` it carries and quotes its `reason`, and a dollar row
+  missing its figures says they are not recorded rather than printing `$0.00`. The verdict is
+  unchanged — a `budget.blocked` was never relaunched and still is not.
+- **`budget show`, `run estimate` and the `budget-gate` hook price the remaining work with the
+  stage's own `attempts:` (closes #214).** `tldrx next`'s brake has resolved the stage's
+  `attempts:` since the key existed; these three readers asked `remainingWork` with the shipped
+  2. On an `attempts: 1` stage that reserved a second developer turn and a second reviewer the
+  executor never dispatches, so the page said BLOCKED and the hook DENIED a `tldrx next` the
+  brake itself allowed. Reproduced before the fix on the Build fixture with `attempts: 1`, two
+  of three stories done and $5.00 left: the brake allowed ($4.40 of work), while `budget show`
+  and `run estimate` quoted $6.40 and the hook denied `tldrx next` on "the stage estimate is
+  $6.40". The hook and `budget show` now resolve the cursor stage through the same tolerant
+  `buildStageDefaults` the `dod-gate` hook already calls on its PreToolUse path (it now takes
+  the stage id; an unreadable preset still gives the shipped 2), and `run estimate` passes the
+  stage spec it already loads. `reviewer_share`, `story_cap_multiplier` and
+  `story_cap_floor_usd` are still asked with their defaults by these three readers — the same
+  disagreement on three more knobs, measured and filed as #333; this change moves `attempts` only.
+- **An in-session Watch turn is recorded as UNMETERED, not as a measured `$0.00` (closes #224).**
+  The `--commit` path read the result envelope's own `cost_usd` and defaulted it to `0` — and a
+  host session has no reason to fill that field in — while `--cost-usd`, the flag the host
+  declares what its sub-agent cost with, was never read anywhere in the Watch executor. Measured
+  on disk across two live workspaces: 56 watch task rows at `cost_usd: 0.0` with no `metered` key,
+  one of them written by a current release, so every zero was counted by `budget.spent_usd` as a
+  real measurement and the lower-bound labelling that keys off `metered: false` could not fire for
+  the whole of 05-watch. Watch now uses the same three-value contract Build and the single-agent
+  stages already use: `--cost-usd` first, then the envelope's figure, and with NEITHER
+  `cost_usd: null` + `metered: false` — a named absence instead of a confident zero. A declared
+  `--tokens` rides along on the row the same way. A headless watch turn, which this process really
+  does meter, is untouched.
+- **A Watch spawn now records the ceiling it was given (closes #190).** The executor computed a
+  per-feature ceiling, handed it to the sub-agent and emitted no `agent.spawned` at all, so a
+  watcher feature was the one turn in the framework whose measured cost could not be read against
+  what it was allowed to cost — every other stage reconciles `agent.spawned.max_budget_usd`
+  against the `agent.result` it paired with. Watch now emits one `agent.spawned` per feature
+  before the spawn (a turn that dies is still a turn the ceiling was committed to), carrying
+  `phase`, `role: developer`, `model`, `effort`, `max_budget_usd` and `key` — the same `key` the
+  `agent.result` for that row already carries, which is what joins the two ends of one turn.
+  Deliberately not `story:`: that is the field `tldrx cost --stories` counts a row as a Build
+  story by, and a Watch feature id is not a story, so that report is unchanged and whether it
+  grows a Watch axis stays a separate decision.
+- **The conflict-turn marker guard no longer counts an unreadable path as a clean one, bounds its
+  scan, and reads modified files too (closes #324).** #286's guard caught every read failure and
+  returned "holds nothing": a guard failing OPEN, and silently, which is the one direction an audit
+  record may never fail in. A path that could not be read is now NAMED with its reason — the errno,
+  or the cap that skipped it — and only `ENOENT` stays silent, because a file that is gone cannot
+  carry a marker into a commit. The scan is bounded for the first time: 2,000 paths and 4 MiB per
+  file, neither of which can bite a normal worktree (this whole repo is 1,037 tracked files and its
+  largest is a 766 KB `CHANGELOG.md`, measured on 5256fab), and a path past either cap surfaces the
+  same way an unreadable one does rather than passing as clean — an un-ignored generated tree used
+  to make the guard as slow and as hungry as that tree was big, with nothing afterwards to say it
+  had been. The scope now also includes files MODIFIED since the handed sha, closing the hole where
+  a developer pastes a conflicted hunk, markers and all, into an already-tracked file; that
+  widening was measured before it was made, not assumed — every `M` row of 1,060 commits of this
+  repo's history, 8,366 rows, each row's content against the marker regex, 0 false positives (one
+  repo is not every repo). What to DO about an unchecked path is one decision at one call site
+  (`UNCHECKED_PATH_POLICY` in `src/core/build/git.ts`): it refuses the attempt with the paths
+  named, and a `warn` policy that lets the story walk on with them named on the Build lines is
+  implemented beside it.
+- **A developer's `notes` written as an ARRAY of strings is now joined with newlines instead of
+  read as `""` by both readers (closes #217).** Measured on a 0.14.3 security-patch run: the
+  in-session developer wrote one note per array element, and the two readers' `typeof … ===
+  "string"` ternaries — `toEnvelope` on the spawned path, `readResult` on the `--commit` path —
+  each threw the whole field away. `notes` is the envelope's one free-text channel, so a turn's
+  stated caveats (on that run, what a security patch could NOT verify) vanished from `run.yml`,
+  the story log and the handoff with nothing on the `--commit` line saying so — a record wrong in
+  the dangerous direction. The elements ARE the notes, so they are joined rather than refused:
+  refusing would spend the turn again over a file whose content is not in doubt, on the reader
+  that is tolerant by design. Silence was the actual defect, so `tldrx next --commit --check` now
+  says which of the three readings a file gets — joined (with the count), dropped by index for a
+  non-string element the way `outputs[i]` already is, or still `""` for a `notes` that is neither
+  a string nor an array. All three paths, the check included, go through ONE function
+  (`readNotes`, `envelope.ts`), so the rehearsal cannot disagree with the commit.
+- **The `budget-gate` hook no longer refuses the `run auto` launch that would fix the shortfall
+  (closes #321).** It priced a `tldrx run auto` spawn against the cursor phase's own ceiling
+  alone. On a phase already short, it denied the launch and wrote `budget.blocked` before the
+  loop could run its in-process rebalance, even when finished phases held the money. With the
+  rebalance on by default, that turned into the common case. Reproduced on the hook fixture
+  before the fix: 02-how was $2.39 short, finished 01-what held $2.86 unspent, and
+  `tldrx run auto` was denied. Now, when finished phases cover the WHOLE shortfall under the
+  loop's own rules, the gate allows and says why on stderr, writing no event. It checks that
+  with the same `planRebalance`, `--take-from` validation and grant verdict the loop uses, read
+  against the full `run.yml` so a stale donor still counts as unfinished. The gate itself moves
+  nothing; the move and its `budget.raised` are the loop's. Denied exactly as before:
+  `tldrx next`, a launch with `--no-rebalance-finished`, a run-ceiling shortfall, a shortfall
+  the finished phases cover only in part, a stale donor, and a move past a recorded grant.
+- **A re-reviewed story's `changes` is consumed instead of parking the story (closes #327).** A
+  story whose earlier reviewer died or was unfunded is re-reviewed alone, and that path returned
+  right after the verdict — so a `changes` with attempts left parked at `review` and its
+  dependents never started, on the serial path and in a wave alike. It now enters the attempt loop
+  (or the wave's next round) under the same ledger bound every other requeue uses.
+- **A story `blocked` on an approving review whose fix list was closed later now settles `done`
+  (closes #329).** Measured live: a fix landed, the reviewer approved, the story blocked on a
+  `Resolved: no` nobody had rewritten — and after a person rewrote it, `story reopen` dispatched a
+  developer with nothing to change and `--as-is` refused a branch already on its epic. Before the
+  frontier walk, `tldrx next` and `--prepare` now settle such a story `done` with no agent spawned,
+  after holding every `Resolved: yes` to git, and say why in one line. The refusal that blocks a
+  story on its fix list names that remedy instead of `tldrx story reopen`.
+- **A parallel Build wave no longer hands two developers the same unspent money (closes #325).**
+  Every per-story cap reads the stage's METERED remainder, which is only right when stories run
+  one at a time. Measured live: a $21.60 stage spawned S1 under $21.00 and S2 under $16.50 in one
+  wave before either had metered a cent, spend landed at $33.07, and S2's reviewer was refused on
+  "$0.00 left" — the build ended 0 of 4. Reproduced on the fake agent before the fix: two lanes on
+  a $20 stage were spawned at $9.00 each, $22 claimed with their review floors. Now each lane is
+  capped at the stage's remainder less the caps of the lanes still running and a $2.00 reviewer
+  floor for every story whose review is still ahead, its own included. A lane that bound would
+  put under the least its developer is already allowed (`story_cap_floor_usd` for a priced story,
+  its uniform share otherwise) waits for a lane to finish, and the run prints `S2: not dispatched
+  beside S1 yet —` with the remainder, the reservation, the floors and the bound; with nothing in
+  flight nothing can be freed by waiting, so it runs at that floor instead of stalling. The
+  consequence to know: a small stage can now serialise a wide wave — measured, the third of three
+  unpriced stories on an $8 stage waits for the other two to meter. `--parallel 1` is
+  byte-identical (golden unchanged). No new config key, event or field. Not in this
+  change: sizing the stage from the plan once it exists, and `budget show`
+  naming what its estimate excludes — both named on #325.
+- **The Plan prompt states the per-item character cap where each capped field is described, and
+  an over-cap finding now survives into the retry (closes #328).** Two plan stages failed on the
+  same cap in one day: a 683-character `test_plan` item, and a `wave_cap_reason` — held to the
+  same cap at the gate, and stated nowhere the Plan agent reads before writing it. The
+  `acceptance` and `test_plan` rows now say "one sentence each; split a long … into several
+  items", and the Plan-shape wave-cap rule and the Caps list name `wave_cap_reason`'s cap — all
+  rendered from `MAX_ITEM_CHARS`, never a typed number. The retry half was measured, not assumed:
+  a failed check's reason reaches the next `## Previous attempt` squeezed to one line with its
+  middle elided, and on a one-defect plan the old message lost "split it into several items" to
+  that ellipsis. The finding is now `<n> characters (cap <cap>) — split it into several items`,
+  short enough that the field, the length, the cap and the instruction reach the retry; an
+  over-cap `wave_cap_reason` is told its length and the cap too. A prompt byte change by
+  design; no Build golden moves. Not in this change: the facilitator's one-line squeeze itself,
+  which still elides whatever a longer multi-finding reason puts in the middle.
+
 ## 0.28.1 — 2026-09-15
 
 ### Fixed

package/README.md

@@ -335,6 +335,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 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). |
 | 0.27.0 | 2026-09-14 | `beta` | Five changes for unattended runs, from a planning audit and live field measurement. The `plan` check now refuses a plan with more waves than the framework carries per run (unless `waves.yml` names a `wave_cap_reason`), refuses a story scheduled before its `depends_on` allows, and flags a dod command siblings carry that one story doesn't (#316–#319). `tldrx run auto --rebalance-finished` moves a blocked phase's exact shortfall out of a finished phase's unspent ceiling before refusing, through `budget raise --take-from` itself, so the run ceiling never grows and no grant is ever assumed; every money refusal now names the unspent total and the exact command to fix it (#314). `tldrx ship` fetches and merges the base into the epic and re-runs the `done` stories' DoD before opening a PR, so a stale or red epic refuses instead of shipping a PR that comes back red (#315). A reviewer's budget floor rises from $1.00 to $2.00, matching what completed reviews actually cost, so a review no longer dies mid-diff on a floor that was never measured (#307). And a developer whose DoD goes red gets the story's next attempt instead of blocking on the first miss, with the kept output handed to the next attempt and the bound counted from `events.jsonl` so it holds across process restarts; a refused developer, a cap death, or a broken dod command still blocks immediately (#313). |

package/dist/hooks/answer-capture.js

@@ -1,24 +1,23 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-c62y35wh.js";
+} from "./chunk-erasdab5.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-48ctk154.js";
+} from "./chunk-gr83pq7x.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-khjm356r.js";
+} from "./chunk-z9hv47ps.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-abswp1vt.js";
+} from "./chunk-t6gbx3jg.js";
 import {
   PHASE_IDS
-} from "./chunk-veffvzw5.js";
-import"./chunk-g7wz339n.js";
-import"./chunk-zvxgdssb.js";
+} from "./chunk-g4d2v4jc.js";
+import"./chunk-857jhjmb.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -28,7 +27,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-khy21x6e.js";
+} from "./chunk-yanmz0vz.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -38,7 +37,7 @@ import {
   isScopedTemplate,
   parseYaml,
   scopedSlotOf
-} from "./chunk-f6t1xc3f.js";
+} from "./chunk-qmp5p77c.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync5 } from "fs";

package/dist/hooks/budget-gate.js

@@ -1,31 +1,36 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-q3d4xdhb.js";
+} from "./chunk-mg3aj0sa.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-tna1bz8r.js";
-import"./chunk-khjm356r.js";
+} from "./chunk-pne7afnf.js";
+import"./chunk-z9hv47ps.js";
 import {
+  REBALANCE_SOURCE,
+  applyRebalance,
   asRunBudget,
   currentActor,
+  describeRebalance,
   economyFor,
   isHostTokens,
   nowRfc3339,
+  planRebalance,
   raiseCommand,
+  raiseGrantVerdict,
   remainingWork,
   shortBy,
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-e618k6te.js";
+} from "./chunk-w3d9kxcp.js";
 import {
   EventLog
-} from "./chunk-abswp1vt.js";
+} from "./chunk-t6gbx3jg.js";
 import {
   cursorStage,
   hostTokensIn,
@@ -34,18 +39,20 @@ import {
   newestActiveRun,
   renderRunEconomies,
   runSpend
-} from "./chunk-hws2gnxj.js";
-import"./chunk-g7wz339n.js";
+} from "./chunk-0d4csx4s.js";
+import {
+  buildStageDefaults
+} from "./chunk-g4d2v4jc.js";
 import {
   noteDeprecations
-} from "./chunk-khy21x6e.js";
+} from "./chunk-yanmz0vz.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-f6t1xc3f.js";
+} from "./chunk-qmp5p77c.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";
@@ -72,6 +79,8 @@ function loadRunBudget(runDir) {
 // src/hooks/budget-gate.ts
 var SPAWN_RE = /^(claude -p|tldrx next|tldrx run auto|tldrx expert train|tldrx seed triage)\b/;
 var RUN_ARG_RE = /--run[= ]([\w.-]+)/;
+var RUN_AUTO_RE = /^tldrx run auto\b/;
+var NO_REBALANCE_RE = /(?:^|\s)--no-rebalance-finished(?:[\s=]|$)/;
 var DEFAULT_TRAIN_USD = 2;
 var DEFAULT_FULL_TRAIN_USD = 3;
 var DEFAULT_TRIAGE_USD = 1;
@@ -116,6 +125,7 @@ await runHook("budget-gate", async () => {
   const attended = isAttendedByHostView(view);
   const stage = cursorStage(view);
   const declared = stage?.budget_usd ?? stageBudgetFromLibrary(root, view.cursor.stage);
+  const attempts = buildStageDefaults(root, view.scope, view.cursor.stage).attempts;
   const work = declared === null ? null : remainingWork({
     runDir: view.dir,
     phaseId: view.cursor.phase,
@@ -124,7 +134,8 @@ await runHook("budget-gate", async () => {
     perAgentMaxUsd: budget.per_agent_max_usd,
     maxUsd: null,
     economy: economyFor(budget, view.cursor.phase),
-    attended
+    attended,
+    attempts
   });
   const estimate = estimateFor(command, work === null ? null : work.usd);
   if (estimate <= 0)
@@ -156,7 +167,7 @@ ${economies}`}`);
 `);
     return;
   }
-  const decision = wouldExceed(budget, view.cursor.phase, estimate);
+  const decision = wouldExceed(budget, view.cursor.phase, estimate, attempts);
   if (!decision.blocked)
     return;
   if (attended) {
@@ -176,6 +187,15 @@ ${economies}`}`);
 `);
     return;
   }
+  if (decision.scope === "phase" && RUN_AUTO_RE.test(command) && !NO_REBALANCE_RE.test(command)) {
+    const short = shortBy(estimate, decision.remaining);
+    const covered = finishedPhasesCover(view.dir, budget, view.cursor.phase, short);
+    if (covered !== null) {
+      process.stderr.write(`tldrx hook budget-gate: ${view.cursor.phase} has $${decision.remaining.toFixed(2)} left of ` + `$${decision.ceiling.toFixed(2)} and the stage estimate is $${estimate.toFixed(2)} — NOT refusing: ` + `\`run auto\` rebalances finished phases before it refuses, and ${covered}, which covers the ` + `$${short.toFixed(2)} shortfall. The loop makes that move on its own record (\`budget.raised\`, ` + `source: ${REBALANCE_SOURCE}); launch with --no-rebalance-finished to be refused here instead.` + `${economies === null ? "" : ` ${economies}`}
+`);
+      return;
+    }
+  }
   new EventLog(join2(view.dir, "events.jsonl")).tryAppend({
     ts: nowRfc3339(),
     run: view.run,
@@ -226,6 +246,22 @@ function estimateFor(command, stageBudget) {
   }
   return stageBudget ?? 0;
 }
+function finishedPhasesCover(runDir, budget, phaseId, shortUsd) {
+  try {
+    const doc = parseYaml(readFileSync2(join2(runDir, "run.yml"), "utf8"));
+    if (doc === null || !Array.isArray(doc.phases))
+      return null;
+    const plan = planRebalance(budget, doc, phaseId, shortUsd);
+    if (plan.moves.length === 0)
+      return null;
+    const applied = applyRebalance(budget, plan);
+    if (applied.outcomes.some((outcome) => raiseGrantVerdict(budget, outcome).exceeds))
+      return null;
+    return describeRebalance(plan);
+  } catch {
+    return null;
+  }
+}
 function failClosed(command, why) {
   deny(`[tldrx] budget-gate: refusing \`${command.slice(0, 80)}\` — this gate could not read the budget ` + `it is supposed to enforce (${why}).
 ` + "It fails CLOSED: a spend nothing can check is exactly the one that must not start. Fix the run's " + "budget.yml, or pass `--run <id>` so the gate knows which run to charge.");

package/dist/hooks/{chunk-hws2gnxj.js → chunk-0d4csx4s.js}

@@ -1,7 +1,7 @@
 import {
   listRunDirs,
   parseYaml
-} from "./chunk-f6t1xc3f.js";
+} from "./chunk-qmp5p77c.js";
 
 // src/hooks/lib/runFile.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-zrwq6r7k.js → chunk-7xascvee.js}

@@ -1,6 +1,6 @@
 import {
   toolInput
-} from "./chunk-tna1bz8r.js";
+} from "./chunk-pne7afnf.js";
 
 // src/hooks/lib/wouldBe.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-zvxgdssb.js → chunk-857jhjmb.js}

@@ -1,7 +1,7 @@
 import {
   PROJECT_FRAMEWORK_DIR,
   PROJECT_WORK_DIR
-} from "./chunk-f6t1xc3f.js";
+} from "./chunk-qmp5p77c.js";
 
 // src/core/lock/workspaceLock.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, rmSync as rmSync2, writeSync, closeSync } from "node:fs";

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

@@ -1,15 +1,15 @@
 import {
   findDuplicate
-} from "./chunk-48ctk154.js";
+} from "./chunk-gr83pq7x.js";
 import {
   evidencePath,
   gateEvidencePath,
   parseEvidence
-} from "./chunk-abswp1vt.js";
+} from "./chunk-t6gbx3jg.js";
 import {
   openBlocks,
   parseQuestions
-} from "./chunk-khy21x6e.js";
+} from "./chunk-yanmz0vz.js";
 
 // src/core/distill/distill.ts
 var CONFLICT_THRESHOLD = 0.6;

package/dist/hooks/{chunk-veffvzw5.js → chunk-g4d2v4jc.js}

@@ -1,9 +1,3 @@
-import {
-  GatePolicyError,
-  STAGE_TUNING_DEFAULTS,
-  parseWorkflowGates,
-  readStageTuning
-} from "./chunk-g7wz339n.js";
 import {
   PROJECT_FRAMEWORK_DIR,
   STAGES_DIR,
@@ -12,12 +6,109 @@ import {
   isRecord,
   loadWorkspace,
   parseYaml
-} from "./chunk-f6t1xc3f.js";
+} from "./chunk-qmp5p77c.js";
 
 // src/core/run/workflowPreset.ts
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
+// src/core/run/stagePolicy.ts
+function validateStagePolicy(value, stageIds, issues, spec) {
+  if (value === undefined || value === null)
+    return;
+  if (!isRecord(value)) {
+    issues.push({
+      path: spec.field,
+      message: `expected a mapping of stage id -> ${spec.policies.join(" | ")}`
+    });
+    return;
+  }
+  const known = new Set(stageIds);
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw !== "string" || !spec.policies.includes(raw)) {
+      issues.push({
+        path: `${spec.field}.${key}`,
+        message: `expected one of ${spec.policies.join(" | ")}, got ${JSON.stringify(raw)}`
+      });
+    }
+    if (known.size > 0 && !known.has(key)) {
+      issues.push({ path: `${spec.field}.${key}`, message: `names no stage in this run` });
+    }
+  }
+}
+
+// src/core/run/gatePolicy.ts
+var GATE_POLICIES = ["human", "auto", "agent"];
+var RESERVED_GATE_KEYS = ["collapse"];
+
+class GatePolicyError extends Error {
+}
+function isGatePolicy(value) {
+  return typeof value === "string" && GATE_POLICIES.includes(value);
+}
+function parseWorkflowGates(value, stageIds, source) {
+  if (value === undefined || value === null)
+    return {};
+  if (!isRecord(value)) {
+    throw new GatePolicyError(`${source}: gates must be a mapping of stage id -> ${GATE_POLICIES.join(" | ")}`);
+  }
+  const known = new Set(stageIds);
+  const out = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (RESERVED_GATE_KEYS.includes(key))
+      continue;
+    if (!known.has(key)) {
+      throw new GatePolicyError(`${source}: gates names '${key}', which is not one of this workflow's stages (${stageIds.join(", ")})`);
+    }
+    if (!isGatePolicy(raw)) {
+      throw new GatePolicyError(`${source}: gates.${key} must be ${GATE_POLICIES.join(" | ")}, got ${JSON.stringify(raw)}`);
+    }
+    out[key] = raw;
+  }
+  return out;
+}
+function validateGatesPolicy(value, stageIds, issues) {
+  validateStagePolicy(value, stageIds, issues, { field: "gates_policy", policies: GATE_POLICIES });
+}
+
+// src/core/schemas/stageTuning.ts
+var STAGE_TUNING_DEFAULTS = {
+  attempts: 2,
+  fixlistRounds: 1,
+  reviewerShare: 0.25,
+  gateSignerShare: 0.25,
+  storyCapMultiplier: 3,
+  storyCapFloorUsd: 4
+};
+var STAGE_TUNING_RANGES = {
+  attempts: { key: "attempts", min: 1, max: 5, integer: true },
+  fixlistRounds: { key: "fixlist_rounds", min: 0, max: 3, integer: true },
+  reviewerShare: { key: "reviewer_share", min: 0, max: 1, integer: false },
+  gateSignerShare: { key: "gate_signer_share", min: 0, max: 1, integer: false },
+  storyCapMultiplier: { key: "story_cap_multiplier", min: 1, max: 20, integer: false },
+  storyCapFloorUsd: { key: "story_cap_floor_usd", min: 0, max: 200, integer: false }
+};
+var FIELDS = Object.keys(STAGE_TUNING_RANGES);
+function inTuningRange(range, value) {
+  if (!Number.isFinite(value))
+    return false;
+  if (range.integer && !Number.isInteger(value))
+    return false;
+  return value >= range.min && value <= range.max;
+}
+function readStageTuning(doc) {
+  if (!isRecord(doc))
+    return STAGE_TUNING_DEFAULTS;
+  const out = { ...STAGE_TUNING_DEFAULTS };
+  for (const field of FIELDS) {
+    const range = STAGE_TUNING_RANGES[field];
+    const value = doc[range.key];
+    if (typeof value === "number" && inTuningRange(range, value))
+      out[field] = value;
+  }
+  return out;
+}
+
 // src/core/schemas/stage.ts
 var EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 function isEffortLevel(value) {
@@ -30,11 +121,11 @@ var PRECONDITION_TIMEOUT_S = 60;
 var PHASE_IDS = ["01-what", "02-how", "03-plan", "04-build", "05-watch"];
 var PHASE_SEGMENT_RE = /^0[1-5]-[a-z]+$/;
 var DEFAULT_TIMEOUT_S = 7200;
-function buildStageDefaults(root, scope) {
+function buildStageDefaults(root, scope, stageId) {
   const fallback = { attempts: STAGE_TUNING_DEFAULTS.attempts, timeoutS: DEFAULT_TIMEOUT_S };
   try {
     const preset = loadWorkflowPreset(root, scope);
-    const stage = preset.stages.find((s) => s.phase === PHASE_IDS[3]);
+    const stage = (stageId === undefined ? undefined : preset.stages.find((s) => s.id === stageId)) ?? preset.stages.find((s) => s.phase === PHASE_IDS[3]);
     if (stage === undefined)
       return fallback;
     return { attempts: stage.attempts, timeoutS: stage.timeout_s };
@@ -275,4 +366,4 @@ function isString(value) {
   return typeof value === "string";
 }
 
-export { PHASE_IDS, DEFAULT_TIMEOUT_S, buildStageDefaults };
+export { validateStagePolicy, GATE_POLICIES, validateGatesPolicy, STAGE_TUNING_DEFAULTS, PHASE_IDS, DEFAULT_TIMEOUT_S, buildStageDefaults };