tldr-experts 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,278 @@
 # Changelog
 
+## 0.25.0 — 2026-09-14
+
+### Fixed
+
+- **A Watch card refused for an unsourced `## Where` item comes back to its writer, marked, instead
+  of being rewritten blind (#301).** MEASURED on two unattended field runs the same night: the
+  `05-watch` writer named a PostgreSQL table under `## Where` with no `[src: …]` at all — twice per
+  run, on both workspaces, once on two cards in one run — while the migration defining that table
+  was cited two lines above under `## Signal`. Three things let it through. The rule said "every
+  item is sourced" and listed five source kinds, and nowhere said which kind a table, queue or
+  dashboard takes (`stage.md`, the feature brief and the template each showed a file or a fact,
+  never a place). The refusal, `no [src: …] token — every item on a card is sourced`, restated the
+  rule and named no cure. And the retry re-ran `tldrx next` from scratch: `featurePrompt` took no
+  previous-card parameter, the refusal was written to the operator's terminal and never into the
+  next prompt, and attempt 2 on run A moved the failure from L21+L22 to L19 — an independent
+  re-generation, not a repair. A person hand-edited the card and recorded the stage twice. Now:
+  ONE sentence, `NON_FILE_SOURCE_CURE`, says what a place cites (the migration, model or config
+  that defines it, or the fact that names it), and the writer's brief teaches it with one worked
+  example while the validator's refusal repeats it verbatim — one derivation, so a retry armed with
+  the refusal is armed with the cure. And the retry's prompt carries `## Previous attempt` (the
+  same heading, H3 and 32 KB cap as the one-agent path, now constants in `prompt.ts`): the card on
+  disk re-read by the parser that refused it, each refused line as `L<n> <section>: <message>`
+  with the line quoted as written, and the card inlined under "edit, do not restart". Re-validated
+  at prompt time rather than replayed from `run.yml`, so a card a person has since fixed shows no
+  stale marks; a first attempt has no card and no section, so its prompt is unchanged. The model
+  pin stays `haiku`: nothing measured says the model cannot follow the rule — it was never told
+  the rule for this case, and the retry was never shown its own card. Pinned by the fake-agent
+  harness: the first attempt's refusal names line, rule and cure; the headless retry's and the
+  `--prepare` bundle's prompts carry the marked card; a first attempt carries no section.
+
+- **The freeze between a release and a merge wave runs both ways now (#304).** #299 made one
+  direction mechanical — the wave waits on `.RELEASE-IN-PROGRESS` — and left the other as prose:
+  MEASURED by reading `scripts/release.sh` at `a341b4f`, it sourced `merge-lock.sh` only to name
+  its own marker, and nothing between its first line and `git commit` read `merge-wave.lock`. A
+  release started mid-wave edited CHANGELOG, README and package.json in a tree another process
+  was gating, and the only thing that stopped the commit was the ref hook — which aborts the
+  COMMIT and leaves the three edits dirty in the shared checkout, with nothing to roll them back.
+  `release.sh` now WAITS on a running wave's lock before it writes its marker and before its
+  first edit — same `MW_LOCK_*` knobs, same dead-owner rule (a dead wave's lock is broken open
+  and said so on stderr) — and gives up with **exit 14**, having edited nothing. The precedence
+  is fixed rather than symmetric (peer review of this change): a wave holding the lock finishes,
+  never preempted; once the marker is up the release is ahead, a wave that took the lock in the
+  gap hands it back as it already did, and the release waits for the lock to clear WITHOUT
+  handing back its marker — two sides yielding on the same poll cadence would ping-pong for the
+  whole budget and end in 13 and 14; pinned with the gap interleaving built deterministically (a
+  stand-in `mv` plants the lock the instant the marker lands). Which makes the wave's dead-owner
+  check the only thing that ever clears a marker a SIGKILL or a cut session orphaned (the traps
+  cover INT/TERM), so it now says so on stderr, naming the marker and the pid, and that sentence
+  is pinned. And a kept marker means two things — queued and untouched, or editing and tagging —
+  so it carries `phase: waiting|releasing` (rewritten atomically), which `--status` and the wave's
+  refusal print — and while a wave holds the lock, `--status` names the queued release on a
+  second line rather than answering "a wave, nothing else": a record never says more than the
+  truth (§7). The code: 14 rather than 1 because there is nothing to undo, and
+  not the wave's own 6 because the two scripts' codes are read in the same logs, so the next
+  number after the wave's 13 keeps a bare "exit 14" unambiguous. Pinned in both directions with
+  the real scripts: a real wave against a real running release exits 13, a real release against a
+  live wave lock exits 14 with the tree untouched, and a queued release edits nothing until the
+  lock is gone. The wave's exit-12 heading gate now also requires the unreleased version to be
+  above `package.json`'s — the CHANGELOG used to be checked only against its own top dated
+  heading, so a dated section never written, or a heading edited by hand, passed on two lies from
+  one file; `package.json` is what shipped (§9's drift guard already pins README's top row to it).
+  Same exit 12: one condition, measured twice, and the refusal names both figures. Two Minors the
+  #299 review named are pinned rather than fixed, because reading was right: `--status` on an
+  old-format lock (owner and token only) with a live pid prints `?` for what it never recorded,
+  and `ver_gt` orders `1.0.0 > 0.99.0` and `0.10.0 > 0.9.0` numerically — the function is
+  lifted from the script's own text for the test, so the pin is on the real implementation.
+
+- **`tldrx next --prepare` and `--commit` ask the same dependency frontier the headless loop asks (#300).**
+  MEASURED at `31ed3d7` on the mixed shape #280 opened: a headless pass met S2 behind S1 at `review` and
+  — correctly — left S2 `todo`; the host's `--commit --review` blocked S1; the next `--prepare` said
+  `prepared S2 · … ($3.20 ceiling, attempt 1 of 1)` and `--commit` then merged S2 into an epic branch
+  S1 had put nothing on. `runAll` has asked `blockingDependency` per story since #260/#263, but the
+  three in-session doors took `nextPending()` / `inProgress()` as offered, and `pendingStories` skips
+  only `done` and a terminal `blocked` — so the `blocked` row #280 stopped writing was, incidentally,
+  the only thing keeping `--prepare` off that dependent. A pure in-session run had the hole all along
+  (S1 blocked by a verdict, S2 `todo`); the mixed run is what made it fire without a person's hand.
+  Now `--prepare` walks the pending stories through the ONE frontier and does per story what the loop
+  does — a terminal hold records the dependent `blocked` with the recorded sentence, so the reason
+  reaches the gate and `staleDependencyHold` releases it when the dependency lands; a pending hold
+  leaves the row `todo` (never `blocked`, which would re-create #280 on the other door) and, with
+  nothing else to offer, refuses with exit 1 saying there is nothing to prepare YET and what releases
+  it. `--prepare --review` refuses over a hold and records nothing. `--commit` on a story whose
+  dependency is no longer `done` refuses with exit 1 in both cases and writes nothing — the bundle,
+  the branch and the worktree stay, the story stays `in_progress`, and the sentence names all three
+  — because that story has a developer's attempt on its branch and the loop's row would say it had
+  none. Exit 1 is the sequencing family (`refusedOnSequence`): the cycle is fine and the fix is the
+  other command; a `2` would send the stage back to `ready` and throw away the bundle a held
+  `--commit` is sitting on. And the closing hint of a `--commit` with more to do asks the same frontier,
+  recording nothing: it used to read raw `nextPending()` and say `S2 is next — run tldrx next --prepare`
+  the instant S1 was blocked, naming the one bundle the next `--prepare` refuses to write; it now names
+  what `--prepare` would actually offer, or says nothing is next and why. One correction to the issue's
+  proposed sequence, measured: S1 at `review`
+  followed by `--prepare` does NOT hand S2 out — S1 is pending too and earlier in wave order, so that
+  `--prepare` offers S1's review; the dependent is offered the moment S1 leaves `review` for a status
+  `pendingStories` skips. Minor by behaviour: a `--prepare` and a `--commit` that used to hand out and
+  settle now record `blocked` or refuse.
+- **A `budget raise --stage` typed during a live `run auto` loop no longer evaporates on the loop's
+  next save (#305).** MEASURED in the field on 0.21.0: the command printed `04-build/build budget_usd
+  $12.60 → $62.60`, exited 0, and two hours later `run.yml` read `budget_usd: 12.60` again with the
+  gate note holding the stage on `budget=$35.78 of $12.60` — the developers had been capped on the
+  figure the operator had raised. Not a `budget` bug: a LOST UPDATE on `run.yml`. `RunStore.save()`
+  re-read `budget.yml`'s ceilings from disk before writing (the 2026-08-29 fix) and wrote `run.yml`
+  WHOLE from the copy the store loaded — and `run auto` holds one store for the whole of a stage, the
+  Build fan-out included. Pinned RED through the real writers on today's `main`: the raise reverted
+  (`Expected: 54 / Received: 4`), a `reject --and-continue` beside a held store reverted (`rejected` →
+  `pending`), a `run cancel` beside one lost its `cancelled:` block. `save()` now re-reads `run.yml`
+  under the workspace lock and carries over it ONLY the fields this store changed since it last read
+  or wrote the file; every derived figure is rolled up from the merged document. That is ownership by
+  change, not the blind reload-and-merge the issue warned against: every value on disk was written by
+  the store that changed it, and a store never writes back a value it merely loaded — so the loop,
+  which never touches a stage's `budget_usd`, cannot revert a raise, and the raise, which never touches
+  task rows, cannot revert the ledger. Who changes what is now written down in spec §2.2 — the loop
+  owns the execution record, a person's commands own `budget_usd`, `cancelled`, gate decisions and the
+  policies — and the one field two writers can both change, a stage's `status` under `run cancel
+  --force` while a loop still runs it, has a DECLARED winner (peer review): `cancelled` is terminal
+  and wins. A cancel that landed under a held store keeps its statuses and the cursor on the file —
+  the held store's task rows still land, those turns happened and cost money — the save answers
+  `cancelledUnder: true` and says so on stderr, and the PROCESS obeys the file, not only the file:
+  the Build executor asks `RunStore.cancelledOnDisk` before every spawn (each story attempt, each
+  parallel lane, the reviewer) and `tldrx next` stops after the save that merged the cancel, with
+  the same exit 0 its "is cancelled — nothing to advance" path uses, rather than parking a
+  cancelled stage on a gate. Pinned through the real dispatch with the fake agent: a forced cancel
+  fired from S1's own DoD command leaves exactly one `agent.spawned` on the log — S1's developer —
+  S1 parked at `review` with an `n-a` verdict naming the cancel, S2 never started, `run.yml`
+  `cancelled` with the stage `cancelled`. MEASURED before the rule: the same collision spawned five
+  times over an already-cancelled run (S1's reviewer, S2's developer and reviewer, S1's developer
+  again), and the file ended `cancelled` with the stage `awaiting_gate` — #305's shape one level
+  down. A verdict read across two owners (the loop's spend against an
+  operator's ceiling) already records the figures it read beside itself — `budget.blocked` carries
+  `remaining_usd` and `ceiling_usd`, the auto-gate note carries `budget=$x of $y` — and that is now
+  the stated rule, because the file can legitimately hold a pair no single writer saw together. For
+  the record: `reject` had no live exposure by construction (it refuses anything but
+  `awaiting_gate`/`failed`, by which point the loop's store for that stage is gone) and `run cancel`
+  already refused under a live `.lock` unless forced; both are pinned at store level anyway, because
+  the next writer will not be one of these three.
+  Two edges from the pre-merge review, because a fallback that guesses silently is the same lie in a
+  smaller font: a `run.yml` on disk that exists but cannot be merged with (does not parse, does not
+  validate) has the in-memory copy written whole — the only honest move — but that is exactly the
+  case an external write may just have been destroyed, so `save()` says so on stderr, naming the
+  reason and the `.bak` beside the file where the replaced version is (the convention the repair path
+  already uses; no new event kind, none exists for repairs and §7 does not invent one); an absent file
+  is merged with nothing and stays silent, there was nothing to lose. And a `run.yml` that records
+  ANOTHER run is not damage but a violated premise: the save REFUSES, naming both ids and the path,
+  and writes nothing — unreachable by path construction today, pinned so it stays unreachable by
+  accident.
+
+## 0.24.0 — 2026-09-14
+
+### Added
+
+- **The two-session protocol is mechanical where it was chat (#299).** MEASURED over one
+  unattended day (2026-09-13/14, two sessions, ~16 issues): two branches each staged ONE
+  unreleased CHANGELOG heading — `0.22.1` and `0.23.0` — for the same next version, and every
+  per-branch check passed both because the defect only exists on the merged tree; "is a release
+  in flight?" was asked by message four times because `scripts/release.sh` wrote nothing anyone
+  could wait on; and a wave's liveness was read off `ps` and a marker's mtime, once wrongly.
+  Three things change, none of them in `src/`. `scripts/merge-wave.sh` now refuses a MERGED tree
+  carrying more than one `## <v> — unreleased` heading, or one whose version is not above the
+  top dated heading, with **exit 12** — the merge commit is rewound, nothing is pushed, both
+  headings are named; zero unreleased headings (the state right after a release) still merges.
+  `scripts/release.sh` writes `.RELEASE-IN-PROGRESS` at the repo root (pid, host, version,
+  started) for its whole span and removes it on every exit path including a red gate and a
+  signal; the wave WAITS on that marker exactly as it waits on its own lock — same poll, same
+  stale-by-dead-pid rule, same `MW_LOCK_*` budget — and gives up with **exit 13**. And
+  `scripts/merge-wave.sh --status` prints one line, exit 0 either way: the live wave's holder,
+  branch, phase (`merge|gates|push`, now recorded in the lock) and start time, a live release's
+  holder and version, or `idle`. The `maintain` skill gains a §9 for a session that is not the
+  driver — announce the file set first (naming the `build.ts` rule), agree the one unreleased
+  heading before writing it, announce lock/sha/OK line, re-review after a rebase — citing
+  `AGENTS.md` by section; `test/maintain-skill.test.ts` pins the section and its citations.
+  Minor by behaviour: a wave that used to pass now refuses.
+
+### Fixed
+
+- **A per-story cap now says what it was derived from, and names a lever that moves it (#281).**
+  MEASURED on a live unattended run (0.18.2, eight stories): a developer died twice on a **$5.97**
+  cap while `03-plan/budget.yml` priced its story at **$14.00** and the 0.18.2 entry below promised
+  `max(price × 3, $4.00)` = $42. The `blocked_reason` told the operator to raise the plan price; the
+  operator raised every price ×4 and the cap did not move by a cent. The arithmetic is not the
+  defect: `priceScale` fits the plan's SUM into the stage's `budget_usd` — $16.20 over a $114.00 plan
+  is a scale of 0.1421 — and a uniform raise keeps the ratio and the sum, so the scale absorbs it
+  exactly. What the framework SAID was: two comment copies in `caps.ts` and the 0.18.2 bullet wrote
+  `price` where the code reads `price × scale`, and that section is dated and immutable, so this
+  bullet corrects #277's wording — the ceiling is `max(price × scale × story_cap_multiplier,
+  story_cap_floor_usd)`, scale being 1 only while the prices sum inside the stage. Three things
+  change, none of them a number. The cap death reason now shows the FORMULA with its inputs, not
+  the conclusion — `cap $5.97 = plan price $14.00 × stage scale 0.1421 (stage budget_usd $16.20 over
+  $114.00 of plan prices) × story_cap_multiplier 3 = $5.97, above the floor $4.00` — and on a scaled
+  plan it says the price cannot move the cap and names the stage's own `budget_usd` with the
+  `tldrx budget raise … --stage` command (#244) that lifts the scale to 1; an unscaled plan keeps
+  the price as a lever (the old sentence was right exactly there), and an unpriced story names its
+  uniform share instead of a plan price it never had. A plan priced past its Build stage still
+  passes the `plan` gate — the scale is a deliberate tolerance — but the gate's detail now carries
+  the factor (`7.0× what the stage holds`), the scale, the largest story as a worked example and the
+  same command; the Build executor prints the same advisory on stderr at entry, before any spawn,
+  so a run already in flight is told too. `shortBy` moved from `budget/budgetView.ts` to
+  `build/caps.ts` (re-exported where it was): the plan-price shortfall needs the same round-up, and a
+  second copy of a rounding rule is what §7 forbids.
+- **A story whose dependency is at `review` now WAITS instead of being written `blocked`, and a
+  `blocked` row whose reason names a dependency that has since turned `done` is offered again
+  (#280).** Measured on a live unattended run (0.18.2, four stories in four waves, S3 and S4
+  `depends_on: [S2]`): S2 came out of its fix round at `review` — verdict recorded, branch merged
+  into the epic — and the loop parked both dependents `blocked` with `dependency S2 is \`review\`,
+  not \`done\``. Two polls later S2 was `done`; the dependents were still `blocked`, because
+  `blocked` is a terminal row the loop never revisits, and a person had to `story reopen` both.
+  #260's frontier drew one line — `done` runs, anything else blocks — which is right for a
+  dependency that will not land in this loop (`blocked`, or `todo` after its developer died, #263)
+  and wrong for `review`/`in_progress`: that is a story mid-pipeline, re-offered by the very next
+  invocation, and a terminal row over it confused "not yet" with "never". Now such a dependency is
+  a wait — the dependent's row is left untouched at `todo`, no log and no outcome row are written,
+  `## Unknowns` names the wait with the story it waits on, and the next invocation asks again. And
+  the shape every earlier run left on disk is released the same way a dead developer's block is:
+  a `blocked` row whose `## Why it is not done` is a dependency hold, over dependencies that are
+  all `done` now, is offered again — nothing attempted it, so nothing about it was judged; a row a
+  reviewer blocked keeps its verdict. One leaf, `build/dependencyHold.ts`, writes the sentence and
+  reads it back. #263's own pin — a dependency parked `todo` still blocks — is untouched. Visible
+  in-session too: after a story settles, a dependent that used to sit `blocked` is now the next
+  `--prepare`, so the stage stays `running` and names it instead of reaching the gate.
+- **`--until-done` compares the REFUSAL across attempts, not the last line printed (#297).** The
+  guard exists so a loop does not spend its whole relaunch budget hammering a wall, and for whole
+  exit families it could not see a wall at all: every stage death ends with the same literal advice
+  — `cost is recorded, not refunded — retry with …` — and so did every context refusal, every
+  budget refusal, every host-tokens refusal, each of them a string with nothing interpolated in it.
+  Reading `lines[lines.length - 1]` there compared a constant to itself, so the SECOND stage death
+  of any run was declared a verbatim repeat whether the two deaths were the same refusal, different
+  refusals, or measurable progress — and every remaining relaunch was thrown away. Both halves of
+  the guard were wrong at once: it spent nothing on the stuck case it was built for, and spent the
+  budget on the case that was moving. The fix is not a better index — an index is right only for
+  the report shapes that exist the day it is written, and breaks the moment a caller appends
+  another note. A report now NAMES its own refusal (`NextOutcome.signature`), the loop compares
+  that, and it falls back to the last line only where nothing named one (a throw's message, a
+  missing input — reports whose last line already IS their reason; a repeat there is still real
+  evidence, and the bound is a backstop that costs money, not a reading). `run.relaunched` carries
+  the comparand it will compare against next, and its `reason` — the sentence the stop line and the
+  ledger both quote — now names the refusal rather than the advice under it. Executor refusals
+  (`refused: true`) are covered at their ONE pass-through rather than producer by producer: eight
+  producers across the Build and Watch executors leave through a single `out()` call, which now
+  passes the executor's own signature, falling back to `ExecutorOutcome.error` — and four of those
+  sentences had to be corrected before the fallback was worth anything. The question is not what a
+  sentence interpolates but whether it DISTINGUISHES the states a relaunch can move between, and a
+  run comes back to the same repo: naming the repo alone made two different dirty trees one
+  refusal, two different stash failures one refusal, and four structurally different foreign-epic
+  faults one refusal. So the dirty-tree refusal now names the overlapping paths and why each is
+  claimed; the foreign-epic refusal carries one sentence per fault (unreadable claims, an open
+  claimant, nobody's leftover, a leftover that could not be moved) instead of one per branch; the
+  could-not-be-set-aside refusal carries git's own reason, which its printed lines already had; and
+  the red-base refusal names EVERY red command rather than the first in iteration order — measured
+  on two base trees that differ only in their second command, where the printed refusal changed and
+  the comparand did not move a byte. Watch's branch-incoherence refusal, whose `error` is null and
+  whose last line is a literal about `tldrx doctor`, names its faults itself. A ninth producer
+  added tomorrow inherits the door instead of being born blind.
+
+- **The Build handoff no longer fails its own `claim-sources` check over a command that spans
+  lines (#283).** MEASURED twice in one hour on a live unattended run (0.18.2 → 0.18.3): the
+  executor wrote `04-build/handoff.md` itself and then refused it — `trailing-position` on a
+  blocked story's Findings and Unknowns bullets, then `unsourced` on a `<id>'s developer had …
+  refused` bullet — stage exit 5, a `--until-done` relaunch burned each time. The issue's own
+  reading, the DoD citation joined mid-line by `; and `, was probed on the same base and passes:
+  the reader takes the LAST `[src: …]` on a line. What fails is a NEWLINE. The refused command
+  reaches the renderer as the developer typed it (`agentEvents.ts` `toolTarget` returns the Bash
+  `command` input verbatim — a wrapped `mv a \` + `b`, a heredoc), `renderBuildHandoff` quoted it
+  inside one bullet, and `parseHandoff` ends a bullet at the first column-0 line, so the first
+  physical line carried its citation mid-sentence or none at all and the rest was prose nothing
+  read. Every element of the document is now made ONE line at the join — the break shown as ` ⏎ `
+  rather than erased, so `mv a \ ⏎ b` still says the line was wrapped and nothing is dropped —
+  which holds for every field the renderer embeds, not only the two the run hit; the review log
+  keeps the command verbatim — and a document that had to draw the mark says so once, under its
+  header, where the developer that copies the line reads it. Text the framework composes has to
+  satisfy the grammar the framework checks; the rule is one function, `asOneLine`, and the file's
+  other writer (`epicRelease.ts`, the `## Epic branch released` section carrying a `run cancel
+  --note` verbatim) goes through it too. A document with no newline in any quoted text is
+  byte-identical, so the build golden is unchanged.
+
 ## 0.23.0 — 2026-09-14
 
 ### Fixed

package/README.md

@@ -335,6 +335,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.25.0 | 2026-09-14 | `beta` | The other half of the two-session protocol and four holes measured on live runs. `scripts/release.sh` now waits on a running wave's lock before touching the tree and never hands back the marker it wrote — release has precedence, the wave yields, exit 14 when it gives up; the heading gate also refuses an unreleased version at or below `package.json`; the marker carries its phase and `--status` reports a release queued behind a wave (#304). In-session `tldrx next --prepare` and `--commit` ask the same dependency frontier the headless loop asks: a terminal hold records the dependent `blocked`, a pending hold refuses without writing, a held `--commit` keeps the work it sits on and says where it is (#300). A Watch card refused for an unsourced `## Where` item comes back to its writer marked, the refusal names the cure, and the brief shows one non-file example, so a retry edits the card instead of regenerating it blind (#301). And `run.yml` no longer loses an external write to a live loop: a save carries only the fields the store changed over a fresh read, ownership is declared, `cancelled` is terminal and wins in the file and in the process, a file that cannot be merged is kept beside as `.bak` and said so, and a file recording another run is refused (#305). Minor release: a new exit code on a public script, a stricter merge gate, and `--prepare`/`--commit` refuse where they used to proceed. |
+| 0.24.0 | 2026-09-14 | `beta` | Five fixes from one unattended night, all measured on live runs. The two-session protocol is mechanical where it was chat: the merge wave refuses a merged tree with two unreleased CHANGELOG headings or one at or below the last release (exit 12), `release.sh` holds a `.RELEASE-IN-PROGRESS` marker the wave waits on (exit 13 when it gives up), `merge-wave.sh --status` reads holder, branch and phase in one line, and the `maintain` skill gains a worker-mode section (#299). A per-story cap says what it was derived from — plan price × stage scale — and names the lever that moves it, and a plan whose prices exceed the stage budget is told so instead of being scaled in silence (#281). A story whose dependency is still at `review` waits in `todo` instead of being written `blocked`, and a dependency block left by an earlier version is released once the dependency is `done` (#280). `--until-done` compares the refusal across attempts, not the advice line printed under it, so a failure that made progress keeps its relaunches (#297). And the Build handoff no longer fails its own `claim-sources` check over a refused command that spans lines: one physical line per element, the break shown as `⏎` and explained once in the document (#283). Minor release: the wave and `--until-done` behave differently in situations that exist today. |
 | 0.23.0 | 2026-09-14 | `beta` | `tldrx story reopen --as-is` now settles a story whose work is already merged into the epic but whose review never completed (`n-a` or `error` on its last recorded merge): a new, named review-only case that merges nothing and only routes the story to its reviewer, read from an additive ledger field; the existing refusal ("no commit the epic has not got") is untouched and now names the standing verdict when one exists (`changes`, `approve`, `fixlist` still refuse). A fix list whose findings are all deferred settles the story `done` instead of spawning a developer with nothing to fix, measured on a live run that paid for four such developers (#295). And a turn that died on a provider limit no longer records `success` borrowed from the provider's own subtype: the failure record says what the host saw (#296, first half — DETECTING the provider limit as its own non-execution kind is #298 and is NOT in this release). Minor release: `story reopen --as-is` behaves differently in a situation that exists today. |
 | 0.22.0 | 2026-09-14 | `beta` | A developer may now READ its own tree — `git status`, `log`, `diff` and `show` join the one constant the grant, the developer prompt and the refusal classifier all read; measured on a live unattended run where a developer was refused `git -C <worktree> log` twice and the story died, ~$5 for a command that changes nothing. `-C <path>` (and `--git-dir`, `--work-tree`) stays ungranted as a decision with its own refusal kind, `elsewhere`, because it points git at trees the story does not own. And every refusal cure now says WHY it is a cure: three consecutive developers on one story re-appended `; echo "EXIT:$?"` to a DoD command because the cure said what to drop and never that the facilitator re-runs the Definition of Done itself and records each exit code (#287, #294). Minor release: the developer's git allowance grew and a new refusal kind was added. |
 | 0.21.0 | 2026-09-13 | `beta` | `tldrx budget raise <phase> <usd> --stage <id>` now moves the stage's own `budget_usd` — the figure that actually sets a developer's and a reviewer's spawn ceiling — instead of the phase figure, which caps no spawn at all: measured on a live unattended run where raising the plan's per-story price and the phase ceiling moved a developer's cap by nothing, and only raising the stage figure moved it; a raise naming no `--stage` now says outright that it moved no spawn ceiling. And a reviewer a nearly-exhausted stage cannot fund is refused before it is spawned — the run that surfaced this handed a reviewer **$0.43**, which died before reading a line of diff and recorded `verdict: error`, parking the story with its dependents blocked; the refusal now costs $0 and records `verdict: n-a`, not an error the reviewer never formed (#244, #289). Minor release: a new flag, `--stage`, on `budget raise`. |

package/dist/hooks/budget-gate.js

@@ -22,7 +22,7 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-1p5027fn.js";
+} from "./chunk-bbrhs055.js";
 import {
   EventLog
 } from "./chunk-6z5rmj0b.js";

package/dist/hooks/{chunk-1p5027fn.js → chunk-bbrhs055.js}

@@ -706,6 +706,9 @@ function stackExpertNames(root, repos) {
   return names;
 }
 
+// src/core/facilitator/prompt.ts
+var MAX_PREVIOUS_ATTEMPT_BYTES = 32 * 1024;
+
 // src/core/text/srcGrammarContract.ts
 var KINDS = {
   file: { shape: "`[repo:]path:line[-line]`", example: "api:src/Selector.ts:241" },
@@ -1232,12 +1235,18 @@ function wouldExceedHostTokens(budget, phaseId, spentTokens) {
   };
 }
 
+// src/core/build/caps.ts
+var MAX_ATTEMPTS2 = STAGE_TUNING_DEFAULTS.attempts;
+var REVIEWER_SHARE2 = STAGE_TUNING_DEFAULTS.reviewerShare;
+var STORY_CAP_MULTIPLIER2 = STAGE_TUNING_DEFAULTS.storyCapMultiplier;
+var STORY_CAP_FLOOR_USD2 = STAGE_TUNING_DEFAULTS.storyCapFloorUsd;
+function shortBy(estimate, remaining) {
+  return Math.max(0.01, Math.ceil((estimate - remaining) * 100) / 100);
+}
+
 // src/core/budget/budgetView.ts
 function raiseCommand(runId, phaseId, amountUsd) {
   return `tldrx budget raise ${phaseId} ${amountUsd.toFixed(2)} --run ${runId}`;
 }
-function shortBy(estimate, remaining) {
-  return Math.max(0.01, Math.ceil((estimate - remaining) * 100) / 100);
-}
 
-export { currentActor, nowRfc3339, spentBasis, tallyOf, DEFAULT_ON_HOST_TOKENS_EXCEED, DEFAULT_ON_GRANT_EXCEED, DEFAULT_ECONOMY, economyFor, isHostTokens, validateRunBudget, asRunBudget, expertsDir, loadExperts, readExpertDomain, pathsIntersect, stackExpertNames, BUILD_PHASE2 as BUILD_PHASE, remainingWork, wouldExceed, wouldExceedHostTokens, raiseCommand, shortBy };
+export { currentActor, nowRfc3339, spentBasis, tallyOf, DEFAULT_ON_HOST_TOKENS_EXCEED, DEFAULT_ON_GRANT_EXCEED, DEFAULT_ECONOMY, economyFor, isHostTokens, validateRunBudget, asRunBudget, expertsDir, loadExperts, readExpertDomain, pathsIntersect, stackExpertNames, BUILD_PHASE2 as BUILD_PHASE, remainingWork, wouldExceed, wouldExceedHostTokens, shortBy, raiseCommand };

package/dist/hooks/{chunk-ah1pdax3.js → chunk-rgn23z77.js}

@@ -8,7 +8,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-1p5027fn.js";
+} from "./chunk-bbrhs055.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,
@@ -56,6 +56,7 @@ import { join as join4 } from "node:path";
 
 // src/core/run/RunStore.ts
 import { existsSync, readFileSync as readFileSync2 } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
 import { basename, join as join2 } from "node:path";
 
 // src/core/frameworkVersion.ts
@@ -297,11 +298,14 @@ class RunStore {
   events;
   current;
   currentBudget;
+  loaded;
+  cancelledUnderFlag = false;
   budgetMutated = false;
   constructor(runDir, run, budget, events) {
     this.runDir = runDir;
     this.events = events;
     this.current = run;
+    this.loaded = run;
     this.currentBudget = budget;
   }
   static open(runDir) {
@@ -386,6 +390,20 @@ class RunStore {
   get runId() {
     return this.current.run;
   }
+  get cancelledUnder() {
+    return this.cancelledUnderFlag;
+  }
+  static cancelledOnDisk(runDir) {
+    const path = join2(runDir, "run.yml");
+    if (!existsSync(path))
+      return false;
+    try {
+      const doc = parseYaml(readFileSync2(path, "utf8"));
+      return validateRunFile(doc).ok && asRunFile(doc).cancelled !== undefined;
+    } catch {
+      return false;
+    }
+  }
   cursorEntry() {
     return stageAt(this.current, this.current.cursor);
   }
@@ -407,13 +425,14 @@ class RunStore {
     this.events.append(event);
   }
   save() {
-    const rolled = rollUp(this.current);
-    const runValidation = validateRunFile(rolled);
-    if (!runValidation.ok) {
-      const first = runValidation.issues[0];
-      throw new RunStoreError(`refusing to write an invalid run.yml: ${first?.path ?? ""} ${first?.message ?? ""}`);
-    }
-    withWorkspaceLock(workspaceRootOfRunDir(this.runDir), () => {
+    return withWorkspaceLock(workspaceRootOfRunDir(this.runDir), () => {
+      const base = this.runToWrite();
+      const rolled = rollUp(base.run);
+      const runValidation = validateRunFile(rolled);
+      if (!runValidation.ok) {
+        const first = runValidation.issues[0];
+        throw new RunStoreError(`refusing to write an invalid run.yml: ${first?.path ?? ""} ${first?.message ?? ""}`);
+      }
       const budget = rollUpBudget(this.ceilingsToWrite(), rolled);
       const budgetValidation = validateRunBudget(budget);
       if (!budgetValidation.ok) {
@@ -421,12 +440,56 @@ class RunStore {
         throw new RunStoreError(`refusing to write an invalid budget.yml: ${first?.path ?? ""} ${first?.message ?? ""}`);
       }
       writeAtomic(join2(this.runDir, "budget.yml"), emitBudgetYaml(budget));
-      writeAtomic(join2(this.runDir, "run.yml"), emitRunYaml(rolled));
+      const runPath = join2(this.runDir, "run.yml");
+      writeAtomic(runPath, emitRunYaml(rolled));
       this.current = rolled;
+      this.loaded = rolled;
       this.currentBudget = budget;
       this.budgetMutated = false;
+      if (base.fallback !== null) {
+        process.stderr.write(`tldrx: ${runPath} ${base.fallback}, so it could not be merged with: this process's copy of ` + `the run was written whole, and the version that was on disk is beside it as ${backupPathFor(runPath)}. ` + "A change another command wrote there since this process read the run (a budget raise, a " + `cancel, a rejection) may be in that backup and not in run.yml.
+`);
+      }
+      if (base.cancelledUnder) {
+        this.cancelledUnderFlag = true;
+        const who = rolled.cancelled;
+        process.stderr.write(`tldrx: run ${rolled.run} was cancelled` + (who === undefined ? "" : ` by ${who.by} at ${who.at} (${who.note})`) + " while this process held it: the cancel's statuses were kept, this process's task rows were " + `recorded beside them, and nothing more may be spawned for it.
+`);
+      }
+      return { cancelledUnder: base.cancelledUnder };
     });
   }
+  runToWrite() {
+    const path = join2(this.runDir, "run.yml");
+    if (!existsSync(path))
+      return { run: this.current, fallback: null, cancelledUnder: false };
+    let doc;
+    try {
+      doc = parseYaml(readFileSync2(path, "utf8"));
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      return { run: this.current, fallback: `could not be read or parsed (${detail})`, cancelledUnder: false };
+    }
+    const validation = validateRunFile(doc);
+    if (!validation.ok) {
+      const first = validation.issues[0];
+      return {
+        run: this.current,
+        fallback: `does not validate (${first?.path ?? ""} ${first?.message ?? "schema error"})`,
+        cancelledUnder: false
+      };
+    }
+    const onDisk = asRunFile(doc);
+    if (onDisk.run !== this.current.run) {
+      throw new RunStoreError(`refusing to write ${path}: it records run ${onDisk.run}, and this store holds run ` + `${this.current.run} — a save never overwrites another run's record`);
+    }
+    const cancelledUnder = onDisk.cancelled !== undefined && this.loaded.cancelled === undefined && this.current.cancelled === undefined;
+    return {
+      run: carryChanges(onDisk, this.current, this.loaded, { cancelledWins: this.cancelledUnderFlag || cancelledUnder }),
+      fallback: null,
+      cancelledUnder
+    };
+  }
   ceilingsToWrite() {
     if (this.budgetMutated)
       return this.currentBudget;
@@ -474,6 +537,41 @@ function parseStateFile(path) {
 `));
   }
 }
+function carryChanges(onDisk, mine, loaded, rules = { cancelledWins: false }) {
+  const top = carryLevel(onDisk, mine, loaded, rules.cancelledWins ? ["phases", "cursor"] : ["phases"]);
+  const phases = mine.phases.map((phase) => {
+    const theirs = onDisk.phases.find((p) => p.id === phase.id);
+    const was = loaded.phases.find((p) => p.id === phase.id);
+    if (theirs === undefined || was === undefined)
+      return phase;
+    const stages = phase.stages.map((stage2) => {
+      const theirStage = theirs.stages.find((s) => s.id === stage2.id);
+      const wasStage = was.stages.find((s) => s.id === stage2.id);
+      if (theirStage === undefined || wasStage === undefined)
+        return stage2;
+      const kept = rules.cancelledWins && theirStage.status === "cancelled" ? ["status", "started_at", "ended_at"] : [];
+      return carryLevel(theirStage, stage2, wasStage, kept);
+    });
+    return { ...carryLevel(theirs, phase, was, ["stages"]), stages };
+  });
+  return { ...top, phases };
+}
+function carryLevel(onDisk, mine, loaded, skip) {
+  const out = { ...onDisk };
+  const theirs = mine;
+  const was = loaded;
+  for (const key of new Set([...Object.keys(theirs), ...Object.keys(was)])) {
+    if (skip.includes(key))
+      continue;
+    if (isDeepStrictEqual(theirs[key], was[key]))
+      continue;
+    if (theirs[key] === undefined)
+      delete out[key];
+    else
+      out[key] = theirs[key];
+  }
+  return out;
+}
 function rollUp(run) {
   const phases = run.phases.map((phase) => {
     const stages = phase.stages.map((stage2) => ({
@@ -515,10 +613,20 @@ function round(n) {
   return Math.round(n * 100) / 100;
 }
 
+// src/core/facilitator/seedInputs.ts
+var DEFAULT_INPUTS_MAX_BYTES = 256 * 1024;
+var MAX_SEED_INLINE_BYTES = 64 * 1024;
+var MIN_SLICE_BYTES = 2 * 1024;
+
+// src/core/facilitator/contextLedger.ts
+var DEFAULT_PROMPT_MAX_BYTES = 400 * 1024;
+
 // src/core/run/runOutcome.ts
 import { join as join3 } from "node:path";
 
 // src/core/build/handoff.ts
+var LINE_BREAK_MARK = "⏎";
+var LINE_BREAK_NOTE = `\`${LINE_BREAK_MARK}\` marks a line break inside a quoted command; the review log beside this file ` + "keeps the command verbatim.";
 var FINDING_STATUS_RE = new RegExp(`—\\s+(${PLAN_STATUSES.join("|")})\\s+—`);
 var FINDING_REASON_RE = new RegExp(`—\\s+(?:${PLAN_STATUSES.join("|")})\\s+—\\s+[^:]*:\\s*(\\S.*)$`);
 

package/dist/hooks/session-start.js

@@ -20,14 +20,14 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-ah1pdax3.js";
+} from "./chunk-rgn23z77.js";
 import {
   expertsDir,
   loadExperts,
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-1p5027fn.js";
+} from "./chunk-bbrhs055.js";
 import {
   isFinished
 } from "./chunk-6z5rmj0b.js";

package/dist/hooks/statusline.js

@@ -2,8 +2,8 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-ah1pdax3.js";
-import"./chunk-1p5027fn.js";
+} from "./chunk-rgn23z77.js";
+import"./chunk-bbrhs055.js";
 import"./chunk-6z5rmj0b.js";
 import"./chunk-m1s8a6s0.js";
 import"./chunk-yre2scxn.js";