tldr-experts 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,151 @@
 # 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

package/README.md

@@ -335,6 +335,7 @@ 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. |

package/dist/hooks/budget-gate.js

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

package/dist/hooks/{chunk-2jb272zj.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" },

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

@@ -8,7 +8,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-2jb272zj.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) => ({

package/dist/hooks/session-start.js

@@ -20,14 +20,14 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-4frmcwp3.js";
+} from "./chunk-rgn23z77.js";
 import {
   expertsDir,
   loadExperts,
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-2jb272zj.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-4frmcwp3.js";
-import"./chunk-2jb272zj.js";
+} from "./chunk-rgn23z77.js";
+import"./chunk-bbrhs055.js";
 import"./chunk-6z5rmj0b.js";
 import"./chunk-m1s8a6s0.js";
 import"./chunk-yre2scxn.js";

package/dist/tldrx.js

@@ -17140,6 +17140,7 @@ import { basename as basename4 } from "node:path";
 
 // src/core/run/RunStore.ts
 import { existsSync as existsSync12, readFileSync as readFileSync12 } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
 import { basename as basename3, join as join14 } from "node:path";
 
 // src/hooks/lib/actor.ts
@@ -17160,11 +17161,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) {
@@ -17249,6 +17253,20 @@ class RunStore {
   get runId() {
     return this.current.run;
   }
+  get cancelledUnder() {
+    return this.cancelledUnderFlag;
+  }
+  static cancelledOnDisk(runDir) {
+    const path = join14(runDir, "run.yml");
+    if (!existsSync12(path))
+      return false;
+    try {
+      const doc = parseYaml(readFileSync12(path, "utf8"));
+      return validateRunFile(doc).ok && asRunFile(doc).cancelled !== undefined;
+    } catch {
+      return false;
+    }
+  }
   cursorEntry() {
     return stageAt(this.current, this.current.cursor);
   }
@@ -17270,13 +17288,14 @@ class RunStore {
     this.events.append(event2);
   }
   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) {
@@ -17284,12 +17303,56 @@ class RunStore {
         throw new RunStoreError(`refusing to write an invalid budget.yml: ${first?.path ?? ""} ${first?.message ?? ""}`);
       }
       writeAtomic(join14(this.runDir, "budget.yml"), emitBudgetYaml(budget));
-      writeAtomic(join14(this.runDir, "run.yml"), emitRunYaml(rolled));
+      const runPath = join14(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 = join14(this.runDir, "run.yml");
+    if (!existsSync12(path))
+      return { run: this.current, fallback: null, cancelledUnder: false };
+    let doc;
+    try {
+      doc = parseYaml(readFileSync12(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;
@@ -17337,6 +17400,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) => ({
@@ -25206,6 +25304,8 @@ function renderStagePreamble(preamble) {
 var QUESTIONS_FILE2 = "questions.md";
 var INPUTS_HEADING = "Inputs";
 var PREVIOUS_ATTEMPT_HEADING = "Previous attempt";
+var PREVIOUS_ATTEMPT_EDIT_HEADING = "Previous attempt — edit, do not restart";
+var MAX_PREVIOUS_ATTEMPT_BYTES = 32 * 1024;
 function buildPrompt(parts) {
   return renderParts(parts).map((part) => part.text).join("");
 }
@@ -34508,94 +34608,6 @@ function quoted(values) {
 // src/core/watch/watchPrompt.ts
 import { existsSync as existsSync66, readFileSync as readFileSync60 } from "node:fs";
 import { join as join80 } from "node:path";
-var WATCH_FACT_AREAS = ["observability", "deploy", "ownership"];
-function featureInputs(options) {
-  const inputs = [];
-  for (const story of options.feature.stories) {
-    inputs.push({ path: story.path, content: story.text });
-  }
-  const epicPath = `${PLAN_PHASE2}/${EPICS_DIR}/${options.feature.epicId}.md`;
-  const epicAbs = join80(options.runDir, epicPath);
-  if (existsSync66(epicAbs))
-    inputs.push({ path: epicPath, content: readFileSync60(epicAbs, "utf8") });
-  inputs.push({ path: `(git) ${options.feature.epicId} branch vs default branch`, content: renderDiffs(options.diffs) });
-  inputs.push({ path: `(facts) area: ${WATCH_FACT_AREAS.join(", ")}`, content: renderWatchFacts(options.facts, options.feature.repos) });
-  for (const repo of options.feature.repos) {
-    const rel = `${PROJECT_FRAMEWORK_DIR}/map/${repo}/gotchas.md`;
-    const abs = join80(options.root, rel);
-    if (existsSync66(abs))
-      inputs.push({ path: rel, content: readFileSync60(abs, "utf8") });
-  }
-  return inputs.slice(0, MAX_STAGE_INPUTS);
-}
-function renderWatchFacts(facts, repos) {
-  const areas = new Set(WATCH_FACT_AREAS);
-  const relevant = facts.filter((fact) => isLive(fact) && areas.has(fact.area) && (fact.repos.length === 0 || fact.repos.some((r) => repos.includes(r))));
-  if (relevant.length === 0) {
-    return `_No live fact is tagged ${WATCH_FACT_AREAS.join(" or ")} for these repos. ` + "Cite `absent:.tldrx/memory/facts.yml` rather than inventing where a signal is read._";
-  }
-  return relevant.map((fact) => `- [${fact.id}] ${fact.fact} (${fact.area} · ${fact.confidence})`).join(`
-`);
-}
-function watcherRelPath(featureId2) {
-  return `${WATCH_PHASE}/${WATCHERS_DIR}/${featureId2}.md`;
-}
-function featureBrief(feature) {
-  const path = watcherRelPath(feature.id);
-  const stories = feature.stories.map((s) => s.story.id);
-  return [
-    `Write exactly ONE file: \`${path}\`. Do not write, edit or delete anything else.`,
-    "",
-    "Its YAML front matter is fixed — copy it verbatim:",
-    "",
-    "```yaml",
-    "---",
-    "version: 1",
-    `id: ${feature.id}`,
-    `epic: ${feature.epicId}`,
-    `title: ${JSON.stringify(feature.title)}`,
-    `stories: [${stories.join(", ")}]`,
-    `repos: [${feature.repos.join(", ")}]`,
-    "status: draft",
-    "---",
-    "```",
-    "",
-    `Then these H2 sections, in this order: ${WATCHER_SECTIONS.map((s) => `\`## ${s}\``).join(" · ")}.`,
-    "",
-    "- Every list item under **Signal**, **Where**, **Healthy baseline** and **Looks broken when**",
-    "  ends with a `[src: …]` token: `<repo>:<path>:<line>` for a line in the built code, `F<n>` for",
-    "  a recorded fact, or `absent:<what you looked at>` when the code emits nothing.",
-    "- **Signal** names the log line, metric or event that is IN the diff above, at the line it is on.",
-    "  If nothing is emitted, say so with an `absent:` source and say what to instrument. Do not",
-    "  describe a signal that would be nice to have as though it exists.",
-    "- **Query** is one fenced block, copy-pasteable in whatever place **Where** names.",
-    "  If — and ONLY if — the code emits nothing at all, so there is no place to paste a query into,",
-    "  write ONE line instead of the block, sourced like every other claim on the card:",
-    "",
-    "      Query: none — <why nothing is queryable> [src: absent:<what you looked at>]",
-    "",
-    "  This is CHECKED, not trusted: it is refused unless **Signal** above cites `absent:` and the",
-    "  reason's own source is `absent:` too. A card that names a real signal has somewhere to point a",
-    "  query at, so `none` on one is a shortcut and will fail the stage. An unsourced `none` is refused",
-    "  exactly like an unsourced bullet, and describing a query in prose is still refused either way.",
-    "- **Sources** is prose: each citation above, once, with what it establishes.",
-    "",
-    "Owner (optional, gh #70). A Signal item may name WHO to ask about it, as `(owner: <name>)`",
-    "placed BEFORE its `[src: …]` token — the token is still the last thing on the line:",
-    "",
-    "    - `checkout.completed` is written on every order (owner: alice) [src: api:src/Checkout.cs:88]",
-    "",
-    "Write it ONLY from an `ownership` fact inlined above, and write the SAME name that fact uses.",
-    "Put it in the front matter as `owner: <name>` when one name covers every item on the card, or on",
-    "the individual items when they differ. Do not invent a name, do not put a repo name there (the",
-    "framework already derives that from your citation), and leave it off entirely when no fact says.",
-    "An `(owner: )` with nothing in it is refused — it loses the name it was trying to write.",
-    "",
-    "Leave `status: draft`. The framework sets it: a card is stamped `verified` only when nothing",
-    "under **Signal** cites `absent:`. Writing `verified` yourself changes nothing and will be overwritten."
-  ].join(`
-`);
-}
 
 // src/core/watch/itemOwner.ts
 var MAX_OWNER_CHARS = 64;
@@ -34632,7 +34644,8 @@ function itemOwner(text3) {
 }
 
 // src/core/watch/watcherFile.ts
-var NO_SRC_TOKEN_ISSUE = "no `[src: …]` token — every item on a card is sourced";
+var NON_FILE_SOURCE_CURE = "a table, queue, dashboard or console is not a line of code, so cite the file that defines it " + "(the migration, model or config, as `<repo>:<path>:<line>`) or the `F<n>` fact that names it";
+var NO_SRC_TOKEN_ISSUE = `no \`[src: …]\` token — every item on a card is sourced; ${NON_FILE_SOURCE_CURE}`;
 var QUERY_NONE_NOT_EARNED_ISSUE = "`Query: none` is only for a card whose `## Signal` is itself `absent:` — this one names a real signal";
 var QUERY_NOT_PASTEABLE_ISSUE = "`## Query` holds no fenced block — the query has to be copy-pasteable, not described";
 var SRC_SECTION2 = "Evidence ledger";
@@ -34820,12 +34833,147 @@ function setWatcherStatus(text3, status) {
   }
   return text3;
 }
+function describeWatcherIssue(issue) {
+  return `L${String(issue.line)}${issue.path === "" ? "" : ` ${issue.path}`}: ${issue.message}`;
+}
 function describeWatcherIssues(issues, max = 5) {
-  const shown = issues.slice(0, max).map((issue) => `  L${String(issue.line)}${issue.path === "" ? "" : ` ${issue.path}`}: ${issue.message}`);
+  const shown = issues.slice(0, max).map((issue) => `  ${describeWatcherIssue(issue)}`);
   const rest = issues.length - shown.length;
   return rest > 0 ? [...shown, `  (+${String(rest)} more)`] : shown;
 }
 
+// src/core/watch/watchPrompt.ts
+var WATCH_FACT_AREAS = ["observability", "deploy", "ownership"];
+function featureInputs(options) {
+  const inputs = [];
+  for (const story of options.feature.stories) {
+    inputs.push({ path: story.path, content: story.text });
+  }
+  const epicPath = `${PLAN_PHASE2}/${EPICS_DIR}/${options.feature.epicId}.md`;
+  const epicAbs = join80(options.runDir, epicPath);
+  if (existsSync66(epicAbs))
+    inputs.push({ path: epicPath, content: readFileSync60(epicAbs, "utf8") });
+  inputs.push({ path: `(git) ${options.feature.epicId} branch vs default branch`, content: renderDiffs(options.diffs) });
+  inputs.push({ path: `(facts) area: ${WATCH_FACT_AREAS.join(", ")}`, content: renderWatchFacts(options.facts, options.feature.repos) });
+  for (const repo of options.feature.repos) {
+    const rel = `${PROJECT_FRAMEWORK_DIR}/map/${repo}/gotchas.md`;
+    const abs = join80(options.root, rel);
+    if (existsSync66(abs))
+      inputs.push({ path: rel, content: readFileSync60(abs, "utf8") });
+  }
+  return inputs.slice(0, MAX_STAGE_INPUTS);
+}
+function renderWatchFacts(facts, repos) {
+  const areas = new Set(WATCH_FACT_AREAS);
+  const relevant = facts.filter((fact) => isLive(fact) && areas.has(fact.area) && (fact.repos.length === 0 || fact.repos.some((r) => repos.includes(r))));
+  if (relevant.length === 0) {
+    return `_No live fact is tagged ${WATCH_FACT_AREAS.join(" or ")} for these repos. ` + "Cite `absent:.tldrx/memory/facts.yml` rather than inventing where a signal is read._";
+  }
+  return relevant.map((fact) => `- [${fact.id}] ${fact.fact} (${fact.area} · ${fact.confidence})`).join(`
+`);
+}
+function watcherRelPath(featureId2) {
+  return `${WATCH_PHASE}/${WATCHERS_DIR}/${featureId2}.md`;
+}
+function featureBrief(feature) {
+  const path = watcherRelPath(feature.id);
+  const stories = feature.stories.map((s) => s.story.id);
+  return [
+    `Write exactly ONE file: \`${path}\`. Do not write, edit or delete anything else.`,
+    "",
+    "Its YAML front matter is fixed — copy it verbatim:",
+    "",
+    "```yaml",
+    "---",
+    "version: 1",
+    `id: ${feature.id}`,
+    `epic: ${feature.epicId}`,
+    `title: ${JSON.stringify(feature.title)}`,
+    `stories: [${stories.join(", ")}]`,
+    `repos: [${feature.repos.join(", ")}]`,
+    "status: draft",
+    "---",
+    "```",
+    "",
+    `Then these H2 sections, in this order: ${WATCHER_SECTIONS.map((s) => `\`## ${s}\``).join(" · ")}.`,
+    "",
+    "- Every list item under **Signal**, **Where**, **Healthy baseline** and **Looks broken when**",
+    "  ends with a `[src: …]` token: `<repo>:<path>:<line>` for a line in the built code, `F<n>` for",
+    "  a recorded fact, or `absent:<what you looked at>` when the code emits nothing.",
+    `- **Where** names a PLACE, and a place is cited like a line: ${NON_FILE_SOURCE_CURE}.`,
+    "  An item with no token at all is refused, however obvious the place. One example, for a table",
+    "  that no fact and no dashboard names yet:",
+    "",
+    "      - PostgreSQL `leaderboard_refreshes` table, read with `psql` [src: api:db/migrations/0007_leaderboard_refreshes.sql:1]",
+    "",
+    "- **Signal** names the log line, metric or event that is IN the diff above, at the line it is on.",
+    "  If nothing is emitted, say so with an `absent:` source and say what to instrument. Do not",
+    "  describe a signal that would be nice to have as though it exists.",
+    "- **Query** is one fenced block, copy-pasteable in whatever place **Where** names.",
+    "  If — and ONLY if — the code emits nothing at all, so there is no place to paste a query into,",
+    "  write ONE line instead of the block, sourced like every other claim on the card:",
+    "",
+    "      Query: none — <why nothing is queryable> [src: absent:<what you looked at>]",
+    "",
+    "  This is CHECKED, not trusted: it is refused unless **Signal** above cites `absent:` and the",
+    "  reason's own source is `absent:` too. A card that names a real signal has somewhere to point a",
+    "  query at, so `none` on one is a shortcut and will fail the stage. An unsourced `none` is refused",
+    "  exactly like an unsourced bullet, and describing a query in prose is still refused either way.",
+    "- **Sources** is prose: each citation above, once, with what it establishes.",
+    "",
+    "Owner (optional, gh #70). A Signal item may name WHO to ask about it, as `(owner: <name>)`",
+    "placed BEFORE its `[src: …]` token — the token is still the last thing on the line:",
+    "",
+    "    - `checkout.completed` is written on every order (owner: alice) [src: api:src/Checkout.cs:88]",
+    "",
+    "Write it ONLY from an `ownership` fact inlined above, and write the SAME name that fact uses.",
+    "Put it in the front matter as `owner: <name>` when one name covers every item on the card, or on",
+    "the individual items when they differ. Do not invent a name, do not put a repo name there (the",
+    "framework already derives that from your citation), and leave it off entirely when no fact says.",
+    "An `(owner: )` with nothing in it is refused — it loses the name it was trying to write.",
+    "",
+    "Leave `status: draft`. The framework sets it: a card is stamped `verified` only when nothing",
+    "under **Signal** cites `absent:`. Writing `verified` yourself changes nothing and will be overwritten."
+  ].join(`
+`);
+}
+function previousCard(options) {
+  const rel = watcherRelPath(options.feature.id);
+  const abs = join80(options.runDir, rel);
+  if (!existsSync66(abs))
+    return "";
+  const text3 = readFileSync60(abs, "utf8");
+  if (text3.trim() === "")
+    return "";
+  const card = parseWatcherCard(text3, options.ctx, options.feature.id);
+  const lines = text3.split(`
+`);
+  const out = [];
+  if (card.ok) {
+    out.push(`The previous attempt at this stage wrote \`${rel}\` and it validates. The stage is being run`, "again for another reason; keep this card as it is unless the evidence above contradicts it.");
+  } else {
+    out.push(`The previous attempt at this stage wrote \`${rel}\` and it was REFUSED — ` + `${String(card.issues.length)} line(s) do not validate. Each one, with the line as written:`, "");
+    for (const issue of card.issues) {
+      out.push(`- ${describeWatcherIssue(issue)}`);
+      const quoted2 = issue.line > 0 ? lines[issue.line - 1] : undefined;
+      if (quoted2 !== undefined && quoted2.trim() !== "")
+        out.push(`  > ${quoted2}`);
+    }
+    out.push("", "Fix what is described above. Everything else in this prompt still applies.");
+  }
+  out.push("", `### ${PREVIOUS_ATTEMPT_EDIT_HEADING}`, "", "This card is on disk RIGHT NOW, exactly as the last attempt left it. It is the draft you are", "being paid to fix, not history: keep every item that already carries a `[src: …]` token, cure", "the lines marked above, and write the file back at the same path. Starting from a blank page", "throws away paid-for work — and, measured, moves a refusal to a different line instead of", "curing it.", "");
+  const budget = options.maxBytes ?? MAX_PREVIOUS_ATTEMPT_BYTES;
+  const size = Buffer.byteLength(text3, "utf8");
+  if (size > budget) {
+    out.push(`_Not inlined (past the ${budget.toLocaleString("en-US")}-byte previous-attempt budget): ` + `${rel} (${size.toLocaleString("en-US")} B). It is on disk; read it before you rewrite it._`);
+  } else {
+    const fence = fenceFor(text3);
+    out.push(`#### \`${rel}\``, "", fence, text3.replace(/\n$/, ""), fence);
+  }
+  return out.join(`
+`);
+}
+
 // src/core/watch/renderWatchHandoff.ts
 var NO_STORIES_SRC = `absent:${PLAN_PHASE2}/stories`;
 function renderWatchHandoff(cards, ctx) {
@@ -35050,6 +35198,7 @@ async function watchExecutor(ctx) {
       refused: true
     };
   }
+  const srcCtx = toSrcContext(loadWorkspace(ctx.root), ctx.runDir, { epicRefs: true });
   let prompts = [];
   if (ctx.mode !== "commit") {
     const build = recordedBuild(ctx.runDir);
@@ -35068,7 +35217,7 @@ async function watchExecutor(ctx) {
         signature: incoherent.signature
       };
     }
-    prompts = features.map((feature, i) => featurePrompt(ctx, feature, diffs[i] ?? []));
+    prompts = features.map((feature, i) => featurePrompt(ctx, feature, diffs[i] ?? [], srcCtx));
   }
   if (ctx.mode === "prepare")
     return prepare2(ctx, features, prompts);
@@ -35109,7 +35258,6 @@ async function watchExecutor(ctx) {
       }
     }
   }
-  const srcCtx = toSrcContext(loadWorkspace(ctx.root), ctx.runDir, { epicRefs: true });
   const written = [];
   for (const feature of features) {
     const rel = watcherRelPath(feature.id);
@@ -35196,7 +35344,7 @@ function collectResults(ctx, features) {
   }
   return { tasks, error: null };
 }
-function featurePrompt(ctx, feature, diffs) {
+function featurePrompt(ctx, feature, diffs, srcCtx) {
   const facts = FactsStore.loadOrEmpty(factsPath(ctx.root)).facts;
   const stageMd = applyCheckContracts(readFileSync62(stageMdPath(ctx.spec.planned.id, ctx.spec.planned.source), "utf8"), {
     checks: ctx.spec.planned.checks.map((check) => check.id),
@@ -35227,7 +35375,8 @@ function featurePrompt(ctx, feature, diffs) {
       budget_usd: agentShare(ctx, 1).toFixed(2)
     },
     experts: bundles.experts,
-    inputs: featureInputs({ root: ctx.root, runDir: ctx.runDir, feature, diffs, facts })
+    inputs: featureInputs({ root: ctx.root, runDir: ctx.runDir, feature, diffs, facts }),
+    previousAttempt: previousCard({ runDir: ctx.runDir, feature, ctx: srcCtx })
   });
   return replaceSection(body, "Feature", featureBrief(feature));
 }
@@ -38436,6 +38585,27 @@ function dependencyHoldOfLog(log) {
   const body = (end === -1 ? rest : rest.slice(0, end)).map((line) => line.trim()).filter((line) => line !== "");
   return body.length === 1 && body[0] !== undefined ? dependencyNamedByHold(body[0]) : null;
 }
+function dependencyHoldCure(held2) {
+  if (dependencyIsPending(held2.status)) {
+    return `${held2.id} \`done\` is what releases it — it is offered again by the next \`tldrx next --prepare\``;
+  }
+  return held2.status === "blocked" ? `${held2.id} will not land in this run as it stands — \`tldrx story reopen ${held2.id} --note "…"\` gives it its turn` : `${held2.id} is \`todo\` after its wave ran, so its developer never delivered — \`tldrx next --prepare\` offers ${held2.id} first`;
+}
+function dependencyPrepareRefusal(storyId, held2) {
+  if (dependencyIsPending(held2.status)) {
+    return `nothing to prepare yet: ${storyId} waits on dependency ${held2.id}, which is \`${held2.status}\`, ` + `not \`done\` — ${storyId} is left \`todo\`, not \`blocked\`; ${dependencyHoldCure(held2)}`;
+  }
+  return `nothing to review: ${dependencyHoldReason(held2)}, so ${storyId} has no developer turn to review and ` + `none is owed — \`tldrx next --prepare\` records ${storyId} \`blocked\` with that reason; ${dependencyHoldCure(held2)}`;
+}
+function dependencyCommitRefusal(storyId, held2, work) {
+  return `${storyId} is not settled: ${dependencyHoldReason(held2)}, and a story does not land over a dependency ` + `that has not. Nothing is lost — the bundle stays at ${work.bundleDir}, the work stays on \`${work.branch}\` ` + `in ${work.worktree}, and ${storyId} stays \`in_progress\`; ${dependencyHoldCure(held2)}, ` + `then \`tldrx next --commit\` settles ${storyId}`;
+}
+function dependencyNextLine(storyId, held2) {
+  if (dependencyIsPending(held2.status)) {
+    return `nothing is next yet — ${storyId} waits on dependency ${held2.id}, which is \`${held2.status}\`, ` + `not \`done\`; ${dependencyHoldCure(held2)}`;
+  }
+  return `nothing is next — ${dependencyHoldReason(held2)}, so \`tldrx next --prepare\` records ${storyId} ` + `\`blocked\` with that reason and closes the stage at its gate; ${dependencyHoldCure(held2)}`;
+}
 
 // src/core/facilitator/reviewerModel.ts
 function resolveReviewer(layers) {
@@ -39302,12 +39472,18 @@ class BuildSession {
     return await this.finish();
   }
   async prepare() {
-    const planned = this.nextPending();
+    let planned = this.nextPending();
     if (planned === null)
       return await this.finish();
     const refusal = await this.refuseOnDirtyRepos() ?? await this.refuseOnForeignEpic() ?? await this.setAsideForeign() ?? await this.refuseOnRedBase() ?? await this.refuseOnUnrunnableWorktree();
     if (refusal !== null)
       return refusal;
+    const offered = this.offerAtFrontier();
+    if (offered.kind === "wait")
+      return refusedOnSequence(this.ctx, dependencyPrepareRefusal(offered.story, offered.held));
+    if (offered.kind === "none")
+      return await this.finish();
+    planned = offered.planned;
     const review = this.reviewWorkFor(planned);
     if (review !== null)
       return await this.prepareReview(planned, review);
@@ -39399,6 +39575,9 @@ class BuildSession {
     const refusal = await this.refuseOnDirtyRepos() ?? await this.refuseOnForeignEpic() ?? await this.setAsideForeign();
     if (refusal !== null)
       return refusal;
+    const held2 = this.blockingDependency(planned);
+    if (held2 !== null)
+      return refusedOnSequence(this.ctx, dependencyPrepareRefusal(planned.story.id, held2));
     const work = this.reviewWorkFor(planned) ?? this.reviewWorkFromLedger(planned);
     if (work === null) {
       return refusedOnSequence(this.ctx, `${planned.story.id} has no merged commit to review — a story is reviewed after its developer turn, ` + "not instead of one. Run `tldrx next --prepare` for the developer half first.");
@@ -39493,7 +39672,7 @@ class BuildSession {
       lines: [
         ...this.lines,
         `${planned.story.id} → \`${outcome?.status ?? "?"}\` (host review, unmetered)`,
-        `${this.nextPending()?.story.id ?? "?"} is next — run \`tldrx next --prepare\``
+        this.nextAtFrontier()
       ],
       stderr: [...this.advisories],
       error: null
@@ -39505,6 +39684,14 @@ class BuildSession {
     if (planned === null) {
       return refusedOnSequence(this.ctx, "no story is `in_progress` — run `tldrx next --prepare` first");
     }
+    const held2 = this.blockingDependency(planned);
+    if (held2 !== null) {
+      return refusedOnSequence(this.ctx, dependencyCommitRefusal(planned.story.id, held2, {
+        bundleDir: relative16(this.ctx.root, agentDir(this.ctx.runDir, this.bundleKey(planned.story.id))),
+        branch: storyBranchOf(this.ctx.runId, planned.story.id),
+        worktree: relative16(this.ctx.root, this.storyWorktree(planned))
+      }));
+    }
     const key = this.bundleKey(planned.story.id);
     let result2;
     try {
@@ -39553,11 +39740,14 @@ class BuildSession {
       lines: [
         ...this.lines,
         `${planned.story.id} → \`${outcome?.status ?? "?"}\``,
-        `${this.nextPending()?.story.id ?? "?"} is next — run \`tldrx next --prepare\``
+        this.nextAtFrontier()
       ],
       error: null
     };
   }
+  cancelledUnder() {
+    return RunStore.cancelledOnDisk(this.ctx.runDir);
+  }
   async driveStory(planned) {
     const resume = this.resumableReview(planned);
     if (resume !== null) {
@@ -39565,6 +39755,10 @@ class BuildSession {
       return;
     }
     for (let i = 0;i < this.attempts; i++) {
+      if (this.cancelledUnder()) {
+        this.lines.push(`  · ${planned.story.id}: ${i === 0 ? "not started" : "not requeued"} — the run was cancelled ` + "(tldrx run cancel) while this stage held it");
+        return;
+      }
       await this.settleHalf(await this.buildHalf(planned));
       const outcome = this.outcomes.get(planned.story.id);
       if (outcome !== undefined && outcome.developerError !== null)
@@ -39614,6 +39808,10 @@ class BuildSession {
         const planned = queue[cursor++];
         if (planned === undefined)
           return;
+        if (this.cancelledUnder()) {
+          this.lines.push(`  · ${planned.story.id}: not started — the run was cancelled (tldrx run cancel) while this stage held it`);
+          return;
+        }
         halves.set(planned.story.id, await this.buildHalf(planned));
       }
     };
@@ -39940,6 +40138,29 @@ class BuildSession {
       });
       return "settled";
     }
+    if (supplied === undefined && this.cancelledUnder()) {
+      const review2 = reviewerUnfunded("the run was cancelled (tldrx run cancel) before the review — the diff is merged on the epic " + "branch and nobody has judged it");
+      this.ctx.emit("check.failed", {
+        phase: this.ctx.phaseId,
+        check: "review",
+        story: story.planned.story.id,
+        verdict: review2.verdict,
+        attempt: story.attempt,
+        detail: review2.summary
+      });
+      await this.settle(story, "review", {
+        dod,
+        commit: commit2,
+        merged: true,
+        carried,
+        epicBase,
+        verdict: "n-a",
+        review: review2,
+        cost: round23(priorCost),
+        reason: review2.summary
+      });
+      return "settled";
+    }
     const outcome = supplied === undefined ? await this.spawnReviewer(story, dod, epicBase) : { review: supplied, cost: 0 };
     const review = outcome.review;
     const cost = round23(priorCost + outcome.cost);
@@ -40187,6 +40408,41 @@ class BuildSession {
     }
     return decidingHold(holds);
   }
+  offerAtFrontier() {
+    const walked = this.walkFrontier(true);
+    if (walked.kind === "held" && !walked.recorded)
+      return { kind: "wait", story: walked.story, held: walked.held };
+    if (walked.kind === "held")
+      return { kind: "none" };
+    return walked;
+  }
+  nextAtFrontier() {
+    const walked = this.walkFrontier(false);
+    if (walked.kind === "offer")
+      return `${walked.planned.story.id} is next — run \`tldrx next --prepare\``;
+    if (walked.kind === "held")
+      return dependencyNextLine(walked.story, walked.held);
+    return "nothing is next — run `tldrx next --prepare` to close the stage at its gate";
+  }
+  walkFrontier(record3) {
+    let recorded = false;
+    let first2 = null;
+    for (const planned of this.pendingStories()) {
+      const held2 = this.blockingDependency(planned);
+      if (held2 === null)
+        return { kind: "offer", planned };
+      first2 ??= { story: planned.story.id, held: held2 };
+      if (dependencyIsPending(held2.status)) {
+        if (record3)
+          this.waitOnDependency(planned, held2);
+        continue;
+      }
+      if (record3)
+        this.blockOnDependency(planned, held2);
+      recorded = true;
+    }
+    return first2 === null ? { kind: "none" } : { kind: "held", ...first2, recorded };
+  }
   waitOnDependency(planned, held2) {
     this.waits.set(planned.story.id, held2);
     this.lines.push(dependencyWaitLine(planned.story.id, held2));
@@ -42312,6 +42568,13 @@ async function runExecutor(store, options, phaseId, stageId, spec, notes, execut
     return failStage(store, options, phaseId, stageId, `recording this invocation's task rows threw — ${String(recorded - tasksBefore)} of ` + `${String(outcome.tasks.length)} rows are in run.yml and the rest are not: ${why}`, notes, recorded);
   }
   store.save();
+  if (store.cancelledUnder) {
+    return out(EXIT_OK4, [
+      ...notes,
+      ...outcome.lines,
+      `run ${store.runId} was cancelled while ${phaseId}/${stageId} ran — stopped here: ` + `${String(outcome.tasks.length)} task row(s) from this invocation are recorded, and nothing more is spawned`
+    ], outcome.stderr ?? []);
+  }
   if (outcome.refused === true) {
     setStatus(store, phaseId, stageId, "ready");
     store.save();
@@ -42790,7 +43053,6 @@ function assemblePrompt(store, options, spec, stage2, inputs, ctx, seed) {
     dispatchNotes
   };
 }
-var MAX_PREVIOUS_ATTEMPT_BYTES = 32 * 1024;
 function describePreviousAttempt(stage2, options) {
   const lines = [];
   const failure = [...stage2.tasks].reverse().find((task2) => task2.error !== null)?.error ?? null;
@@ -42833,7 +43095,7 @@ function priorOutputs(options) {
     return [];
   const out = [
     "",
-    "### Previous attempt — edit, do not restart",
+    `### ${PREVIOUS_ATTEMPT_EDIT_HEADING}`,
     "",
     "These files are on disk RIGHT NOW, exactly as the last attempt left them. They are",
     "not a suggestion and they are not history: they are the draft you are being paid to",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tldr-experts",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "tldr-experts: an evidence-first, file-based AI development framework - five stages, a gate on every one, and every claim cited or refused. Installs the `tldrx` (and `tldr-experts`) command. Beta.",
   "license": "MIT",
   "author": "Alan Martinez",

package/plugin/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$doc": "Shape verified from https://code.claude.com/docs/en/plugins.md (Quickstart > Create the plugin manifest). Fields used here: name, description, version, author.name. Only plugin.json goes inside .claude-plugin/; skills/, agents/ and hooks/ live at the plugin root.",
   "name": "tldrx",
   "description": "tldr-experts: an evidence-first, file-based AI development framework. Five stages, a gate on every one, every claim cited or refused. Beta.",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "author": {
     "name": "Alan Martinez"
   }

package/stages/watch/stage.md

@@ -56,7 +56,8 @@ these H2 sections, in order:
 ## Rules
 
 - Every list item under Signal / Where / Healthy baseline / Looks broken when is ONE
-  line and ENDS with a `[src: …]` token. An item without one is refused.
+  line and ENDS with a `[src: …]` token. An item without one is refused — a table, queue,
+  dashboard or console included: cite the file that defines it (**Feature** above shows one).
 - Source grammar (exact): `[src: <one or more sources separated by "; ">]`, a source being
   `<repo>:<path>:<line>` (or `:<start>-<end>`) · `F<n>` · `https://…` ·
   `$ <command> → exit <n>` · `absent:<path>`. Never a whole file, never a comma list.

package/templates/watcher.md

@@ -38,9 +38,14 @@ status: draft                # draft | verified — verified only when Signal ha
 
 ## Where
 
-> The dashboard, log stream, table or query console this is read in.
+> The dashboard, log stream, table or query console this is read in. A place is
+> cited like a line: a table, queue, dashboard or console is not a line of code,
+> so cite the file that DEFINES it — the migration, model or config — or the
+> `F<n>` fact that names it. An item with no token is refused, however obvious
+> the place.
 
 - Application Insights → `traces`, filtered to the message above [src: F014]
+- PostgreSQL `leaderboard_refreshes` table, read with `psql` — no dashboard reads it yet [src: api:db/migrations/0007_leaderboard_refreshes.sql:1]
 
 ## Healthy baseline