tldr-experts 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## 0.26.0 — 2026-09-14
+
+### Fixed
+
+- **`tldrx replay` says what a failed stage died of, instead of `FAILED: no reason recorded` for
+  every one (#309).** MEASURED by inspection at `03d53e8`: the ONLY writer of `stage.failed` in the
+  tree — and, per `git log -S`, in its whole history — carries the failure as `payload.reason`
+  (`runNext.ts`, the fail path; the same field `stage.skipped` uses, and the same field `run auto`'s
+  own summary reads). The narrative renderer read `payload.error`, a field nothing ever set, so
+  `text()` was always empty and the fallback always fired — a stakeholder reading a replay saw
+  that a stage failed and never why, while the reason sat one field over in the same line of
+  `events.jsonl`. Same class as the `message`/`detail` drift #249's round-1 review found:
+  payloads are untyped and nothing checks a reader's field name against its writer's. The
+  renderer now reads `reason`, like its sibling one line down; the `FAILED: ` marker and the
+  fallback sentence are exported constants, and `test/replay.test.ts` feeds a hand-built
+  `stage.failed` event and pins the rendered line to the reason it carried (RED on the old read:
+  the line was never found; the fallback case is a guard). No record changes shape — nothing
+  wrote `error`, so there is no old record to tolerate.
+
+- **A wide story's measured widening no longer kills the invocation that earned it, and an executor that
+  throws after paid turns leaves their rows and their money in `run.yml` (#249).** MEASURED on a live 0.24.0
+  field run: a story with 16 declared touches changed 32 files, and the `story.touches_widened` the framework
+  measures at settle carried `paths`, `before` and `after` — three unbounded path lists, 5556 bytes against
+  the 4096-byte cap. `capPayload` knew `detail` and `outputs` by name and nothing else, so `EventLog.append`
+  threw; `measureSurface`'s "advisory, never throws" contract guarded the git read and not the emit, so the
+  throw went out through `settle` — after the story's `done` was on disk and before its `task.done` was in
+  the ledger — into `runNext`'s catch, which failed the stage with `tasks_recorded: false`: the developer's
+  and the reviewer's paid turns never reached `run.yml`, and every ceiling that derives from recorded spend
+  was short by exactly that, so the next economy refusal that should have fired would not have. Three fixes,
+  one per seam. The cap seam knows the three lists BY NAME in one declared table (`DROPPABLE_LISTS`):
+  `after` first (the largest, and derivable from the other two), then `before`, then `paths` last — each
+  dropped WHOLE and only while the payload is still over, each replaced by `<field>_omitted: N` and the same
+  reason-and-pointer sentence `outputs_omitted` carries, never a shortened list, which would read downstream
+  as the whole one; a `paths_omitted` a writer already put there (`worktree.foreign_work_aside`) is added
+  to, not overwritten. Every reader — `wideningRows`, the Build handoff, `tldrx replay` — renders
+  `(16 → 29 path(s))` from ONE derivation, `listCount`, so a row the cap could not carry reads the same
+  everywhere. `measureSurface` never throws: a refused emit records a bounded absence on the same event (the
+  counts, and a `note` naming the failure), and a log that refuses even that says so on stderr while the
+  story still settles. And the structural half, the expensive one: the Build executor carries the rows it
+  had already earned ON the error it throws (`withPartialTasks` — data on the same object, never a wrapper,
+  so what threw is still what the caller sees), and `runNext`'s catch records them through the same
+  `recordExecutorTasks` the return path uses BEFORE it fails the stage: the `error` event says
+  `tasks_recorded: true` with `rows_written`/`rows_expected` measured off the store after the write, the
+  rows keep their own `done` rather than being repainted with a throw they did not produce, and
+  `budget.spent_usd` is what was paid. Pinned by a real fake-agent build whose settle throws after both turns:
+  MEASURED on that case, the ledger before the fix recorded 0 rows / $0.00 for two paid turns, and after it
+  records 2 rows / $0.50. Which is the sentence an operator needs after this release: the cost half does not
+  just stop losing money, it stops LYING in favour of spend. With paid turns now recorded, ceilings bite
+  earlier — a run that used to reach the end because the ledger counted short may now be refused mid-way,
+  correctly but differently, so a new economy refusal after upgrading is this change working, not a
+  regression to hunt elsewhere. Pre-merge review found the double fault behind that: when recording the
+  carried rows itself threw (an `agent.result` the cap cannot rescue), rows and events were interleaved, so
+  a throw at event k stranded rows k+1… in memory and nothing the spend surfaces read said so — a plausible
+  short total, worse than a loud zero — and the `error` event was emitted BEFORE the save with a free-text
+  `recording_error` the cap did not trim, so a long one could throw the seam and lose the rows with no
+  trace. Now every row goes into the store before any event is appended (the in-memory row write cannot
+  throw; the append is the only line that can), the store is saved before the `error` event is emitted and
+  that emit is wrapped, `recording_error` sits in the cap's prose table beside `detail`, and no new
+  vocabulary reaches `budget show`, the dashboard or status: `run.yml` is whole, so they read a
+  measurement. Pre-merge review round 2 found the events side was NOT labelled — `tldrx cost --stories`
+  reads only `agent.result` events, so a story the fault left un-evented came back with no measured cost
+  and zero unmetered turns, a silent null at odds with the `budget.spent_usd` run.yml records. Now the
+  story ledger walks the log in order: a spawn opens a slot for its story, a result closes one (or, arriving
+  late from an orphaned agent after its slot was already counted lost, retires that lost slot — a result is
+  proof the turn was metered whenever it lands, never both the dollars and a lost turn), and an
+  invocation-terminal event on that stage (`stage.done`/`failed`/`skipped`, the executor or record-tasks
+  `error`, or a later `stage.started` that superseded it) turns every slot still open into a LOST turn,
+  which enters the SAME unmetered/lower-bound door: the story reads as a LOWER BOUND with the turn count,
+  not a confident zero (the dollars are in run.yml; a task row carries no story key, so they are named
+  absent per story, never invented). A spawn with nothing terminal after it is a turn IN FLIGHT — every
+  healthy mid-run read of `tldrx cost` and of the handoff — and is counted as nothing, review round 3's
+  finding: `spawned − accounted` alone had flagged every live build as a lower bound. Events carry no
+  attempt id, so the log's own order is the attempt scope. `tldrx replay`
+  renders the error line from `detail` (it read `message`, a field the event never carried) and reports
+  `rows_written` of `rows_expected` — reports, never sums.
+
 ## 0.25.0 — 2026-09-14
 
 ### Fixed

package/README.md

@@ -335,6 +335,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.26.0 | 2026-09-14 | `beta` | Two field defects from the same class — a reader of an event payload trusting a field its writer never set — plus the ceiling that killed the turn that earned it. A wide story's measured `touches_widened` no longer throws after the turn has settled: the cap knows the three lists by name and drops them whole by count, every reader derives before/after through one function, and an executor that throws after paid turns leaves their rows and money in `run.yml` and saves before it emits. The cost surfaces then agree with each other: a turn whose result was lost to that fault reads as UNMETERED, LOWER BOUND on `tldrx cost` and in the Build handoff through the door other unmeasured turns already use, a turn still in flight reads as nothing, and a late result retires the lost mark instead of counting twice. Replay reads the reason a failed stage recorded instead of printing "no reason recorded" for every one. |
 | 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. |

package/dist/hooks/answer-capture.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-tjx8g39f.js";
+} from "./chunk-d0jhr5wh.js";
 import {
   FactsStore,
   formatJaccard
@@ -13,7 +13,7 @@ import {
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-6z5rmj0b.js";
+} from "./chunk-41k19q8t.js";
 import {
   PHASE_IDS
 } from "./chunk-m1s8a6s0.js";

package/dist/hooks/budget-gate.js

@@ -25,7 +25,7 @@ import {
 } from "./chunk-bbrhs055.js";
 import {
   EventLog
-} from "./chunk-6z5rmj0b.js";
+} from "./chunk-41k19q8t.js";
 import {
   cursorStage,
   hostTokensIn,

package/dist/hooks/{chunk-tjx8g39f.js → chunk-d0jhr5wh.js}

@@ -5,7 +5,7 @@ import {
   evidencePath,
   gateEvidencePath,
   parseEvidence
-} from "./chunk-6z5rmj0b.js";
+} from "./chunk-41k19q8t.js";
 import {
   openBlocks,
   parseQuestions

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

@@ -21,7 +21,7 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-6z5rmj0b.js";
+} from "./chunk-41k19q8t.js";
 import {
   cursorStage,
   isAttendedByHostView,

package/dist/hooks/session-start.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   questionsCard
-} from "./chunk-tjx8g39f.js";
+} from "./chunk-d0jhr5wh.js";
 import"./chunk-jpp137mb.js";
 import {
   allow,
@@ -20,7 +20,7 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-rgn23z77.js";
+} from "./chunk-pwzy19er.js";
 import {
   expertsDir,
   loadExperts,
@@ -30,7 +30,7 @@ import {
 } from "./chunk-bbrhs055.js";
 import {
   isFinished
-} from "./chunk-6z5rmj0b.js";
+} from "./chunk-41k19q8t.js";
 import"./chunk-m1s8a6s0.js";
 import {
   openRunViews

package/dist/hooks/statusline.js

@@ -2,9 +2,9 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-rgn23z77.js";
+} from "./chunk-pwzy19er.js";
 import"./chunk-bbrhs055.js";
-import"./chunk-6z5rmj0b.js";
+import"./chunk-41k19q8t.js";
 import"./chunk-m1s8a6s0.js";
 import"./chunk-yre2scxn.js";
 import"./chunk-bznt6jb2.js";

package/dist/tldrx.js

@@ -7362,24 +7362,34 @@ function capPayload(payload, save) {
   const where = (text, field) => save === undefined ? "the full text was not preserved and is not recoverable from this event" : save(text, field);
   const named = (size, text, field) => `${String(size)} bytes exceeds the ${String(MAX_PAYLOAD_BYTES)}-byte cap — ${where(text, field)}`;
   let current = payload;
-  if (typeof current.detail === "string") {
-    const { detail: dropped, ...rest } = current;
-    current = { ...rest, detail_omitted: named(byteSize(current), dropped, "detail") };
+  for (const field of DROPPABLE_PROSE) {
+    const dropped = current[field];
+    if (typeof dropped !== "string")
+      continue;
+    const { [field]: _gone, ...rest } = current;
+    current = { ...rest, [`${field}_omitted`]: named(byteSize(current), dropped, field) };
     if (byteSize(current) <= MAX_PAYLOAD_BYTES)
       return current;
   }
-  if (Array.isArray(current.outputs) && current.outputs.length > 0) {
-    const { outputs: dropped, ...rest } = current;
-    const list = dropped;
+  for (const field of DROPPABLE_LISTS) {
+    if (byteSize(current) <= MAX_PAYLOAD_BYTES)
+      return current;
+    const list = current[field];
+    if (!Array.isArray(list) || list.length === 0)
+      continue;
+    const { [field]: dropped, ...rest } = current;
+    const already = current[`${field}_omitted`];
     current = {
       ...rest,
-      outputs_omitted: list.length,
-      outputs_omitted_reason: named(byteSize(current), list.map((p) => String(p)).join(`
-`), "outputs")
+      [`${field}_omitted`]: list.length + (typeof already === "number" ? already : 0),
+      [`${field}_omitted_reason`]: named(byteSize(current), dropped.map((p) => String(p)).join(`
+`), field)
     };
   }
   return current;
 }
+var DROPPABLE_LISTS = ["outputs", "after", "before", "paths"];
+var DROPPABLE_PROSE = ["recording_error", "detail"];
 function byteSize(payload) {
   return Buffer.byteLength(JSON.stringify(payload), "utf8");
 }
@@ -30038,8 +30048,9 @@ function wideningBullets(rows) {
   for (const row2 of rows.slice(0, MAX_WIDENING_BULLETS)) {
     const named = row2.paths.slice(0, NAMED_WIDENED_PATHS).map((path) => `\`${path}\``).join(", ");
     const more = row2.paths.length > NAMED_WIDENED_PATHS ? `, +${String(row2.paths.length - NAMED_WIDENED_PATHS)} more` : "";
+    const unlisted = (row2.pathsOmitted ?? 0) > 0 ? `${row2.paths.length === 0 ? "" : ", "}${String(row2.pathsOmitted)} path(s) not listed on the event` : "";
     const opening = row2.basis === "measured" ? `${row2.story}'s declared surface was under the work it did (measured)` : `${row2.story}'s surface was widened by a person (declared)`;
-    out.push(`- ${opening}: +${named}${more} ` + `(${String(row2.before)} → ${String(row2.after)} path(s))` + `${row2.note === "" ? "" : ` — ${row2.note}`} [src: events.jsonl:${String(row2.line)}]`);
+    out.push(`- ${opening}: +${named}${more}${unlisted} ` + `(${String(row2.before)} → ${String(row2.after)} path(s))` + `${row2.note === "" ? "" : ` — ${row2.note}`} [src: events.jsonl:${String(row2.line)}]`);
   }
   if (rows.length > MAX_WIDENING_BULLETS) {
     const next = rows[MAX_WIDENING_BULLETS]?.line ?? 1;
@@ -35798,6 +35809,11 @@ var MEASURED_NOTE_TAIL = " — measured off the story's own diff, the range the
 function basisOf(payload) {
   return payload.basis === "measured" ? "measured" : "declared";
 }
+function listCount(payload, field) {
+  const list = payload[field];
+  const omitted = payload[`${field}_omitted`];
+  return (Array.isArray(list) ? list.length : 0) + (typeof omitted === "number" ? omitted : 0);
+}
 function stringList3(value) {
   return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
@@ -35822,8 +35838,9 @@ function wideningRows(eventsText) {
       story: typeof payload.story === "string" ? payload.story : "?",
       basis: basisOf(payload),
       paths: stringList3(payload.paths),
-      before: stringList3(payload.before).length,
-      after: stringList3(payload.after).length,
+      ...typeof payload.paths_omitted === "number" && payload.paths_omitted > 0 ? { pathsOmitted: payload.paths_omitted } : {},
+      before: listCount(payload, "before"),
+      after: listCount(payload, "after"),
       note: typeof payload.note === "string" ? payload.note : "",
       line: i + 1
     });
@@ -38830,6 +38847,9 @@ function storyLedger(runDir2, scope = null, extraTurns = []) {
   const ceilings = new Map;
   const measured = new Map;
   const unmetered = new Map;
+  const open = new Map;
+  const openStage = new Map;
+  const lost = new Map;
   const storyKeys = new Set;
   const storyPhases = new Set;
   let excluded = 0;
@@ -38878,6 +38898,39 @@ function storyLedger(runDir2, scope = null, extraTurns = []) {
     else
       measured.set(turn.key, round9((measured.get(turn.key) ?? 0) + turn.costUsd));
   }
+  for (const event4 of events) {
+    if (event4.type === "agent.spawned" && inScope(event4)) {
+      const story = str10(event4.payload.story);
+      if (story === null)
+        continue;
+      open.set(story, (open.get(story) ?? 0) + 1);
+      openStage.set(story, event4.stage);
+      continue;
+    }
+    if (event4.type === "agent.result" && inScope(event4)) {
+      const key = str10(event4.payload.key);
+      if (key === null || !isStory(key, str10(event4.payload.phase)))
+        continue;
+      const opened = open.get(key) ?? 0;
+      if (opened > 0)
+        open.set(key, opened - 1);
+      else if ((lost.get(key) ?? 0) > 0)
+        lost.set(key, (lost.get(key) ?? 0) - 1);
+      continue;
+    }
+    if (!closesAttempt(event4))
+      continue;
+    for (const [story, count] of open) {
+      if (count === 0 || openStage.get(story) !== event4.stage)
+        continue;
+      lost.set(story, (lost.get(story) ?? 0) + count);
+      open.set(story, 0);
+    }
+  }
+  for (const [story, count] of lost) {
+    if (count > 0)
+      unmetered.set(story, (unmetered.get(story) ?? 0) + count);
+  }
   return {
     rows: order.map((story) => ({
       story,
@@ -38889,6 +38942,14 @@ function storyLedger(runDir2, scope = null, extraTurns = []) {
     events: events.length
   };
 }
+function closesAttempt(event4) {
+  if (event4.type === "stage.started" || event4.type === "stage.done" || event4.type === "stage.failed" || event4.type === "stage.skipped")
+    return true;
+  if (event4.type !== "error")
+    return false;
+  const where = str10(event4.payload.where);
+  return where === "executor" || where === "record-tasks";
+}
 function buildStoryCost(runDir2) {
   let title = "";
   let runId = basename13(runDir2);
@@ -39006,7 +39067,7 @@ function storyVerdict(cost) {
     return "no total: a story above is missing one side, and an absent figure is not summed as zero.";
   }
   if (floor) {
-    return `no verdict: ${turns} unmetered, so at least one story's measurement is a LOWER BOUND ` + "— an unmetered turn could put it over a spawn ceiling this cannot see.";
+    return `no verdict: ${turns} unmetered, so at least one story's measurement is a ${LOWER_BOUND_MARK} ` + "— an unmetered turn could put it over a spawn ceiling this cannot see.";
   }
   return "every story measured inside the spawn ceilings it was given.";
 }
@@ -39035,7 +39096,7 @@ function renderStoryCost(cost) {
     lines.push("  measured not recorded — no metered `agent.result` carried a cost for that story. " + "A turn this process never metered is a cost it did not see, never a free one.");
   }
   if (cost.unmeteredStories.length > 0) {
-    lines.push(`  ${cost.unmeteredStories.join(", ")}: ${plural3(cost.unmeteredTurns, "turn")} UNMETERED, so ` + "that measurement is a LOWER BOUND, not a total.");
+    lines.push(`  ${cost.unmeteredStories.join(", ")}: ${plural3(cost.unmeteredTurns, "turn")} UNMETERED, so ` + `that measurement is a ${LOWER_BOUND_MARK}, not a total.`);
   }
   if (cost.excludedKeyedResults > 0)
     lines.push(`  ${excludedLine(cost)}`);
@@ -39104,6 +39165,7 @@ function readBudget(runDir2) {
 var ECONOMY_WIDTH = 12;
 var DASH = "—";
 var NOT_RECORDED = "not recorded";
+var LOWER_BOUND_MARK = "LOWER BOUND";
 function tokenColumns(t, declared2 = 0) {
   const measured = `${bigTokens(t.input)} in · ${bigTokens(t.output)} out · ` + `${bigTokens(t.cacheCreation)} cache write · ${bigTokens(t.cacheRead)} cache read`;
   if (declared2 <= 0)
@@ -39287,7 +39349,7 @@ async function buildExecutor(ctx) {
     try {
       await session.restoreForeignWorkAside();
     } catch {}
-    throw error;
+    throw withPartialTasks(error, session.tasks);
   }
 }
 function refusedOnBase(session, error) {
@@ -41173,14 +41235,33 @@ class BuildSession {
     const measured = measuredWidening(changed, declared2);
     if (measured === null)
       return;
-    this.ctx.emit("story.touches_widened", {
-      story: story.planned.story.id,
-      paths: [...measured.paths],
-      note: measured.note,
-      before: [...measured.before],
-      after: [...measured.after],
-      basis: "measured"
-    }, 0, "framework");
+    const id = story.planned.story.id;
+    const actor = "framework";
+    try {
+      this.ctx.emit("story.touches_widened", {
+        story: id,
+        paths: [...measured.paths],
+        note: measured.note,
+        before: [...measured.before],
+        after: [...measured.after],
+        basis: "measured"
+      }, 0, actor);
+      return;
+    } catch (error) {
+      const why = firstLine7(error instanceof Error ? error.message : String(error));
+      try {
+        this.ctx.emit("story.touches_widened", {
+          story: id,
+          paths_omitted: measured.paths.length,
+          before_omitted: measured.before.length,
+          after_omitted: measured.after.length,
+          note: `${measured.note} — the lists could not be recorded on this event: ${why}`,
+          basis: "measured"
+        }, 0, actor);
+      } catch (again) {
+        this.advisories.push(`${id}: the measured widening of its surface (${String(measured.paths.length)} path(s) outside ` + `\`touches:\`) could not be recorded in events.jsonl — ` + firstLine7(again instanceof Error ? again.message : String(again)));
+      }
+    }
   }
   orderedOutcomes() {
     const rows = [];
@@ -41791,6 +41872,20 @@ function failed3(ctx, error, tasks) {
 }
 
 // src/core/facilitator/executors/index.ts
+var PARTIAL_TASKS = Symbol.for("tldrx.partialTasks");
+function withPartialTasks(error, tasks) {
+  if (tasks.length === 0)
+    return error;
+  const carrier = typeof error === "object" && error !== null ? error : new Error(String(error));
+  Object.defineProperty(carrier, PARTIAL_TASKS, { value: [...tasks], enumerable: false, configurable: true });
+  return carrier;
+}
+function partialTasksOf(error) {
+  if (typeof error !== "object" || error === null)
+    return [];
+  const tasks = error[PARTIAL_TASKS];
+  return Array.isArray(tasks) ? tasks : [];
+}
 var EXECUTORS = new Map([
   [BUILD_PHASE, buildExecutor],
   [WATCH_PHASE, watchExecutor]
@@ -42535,14 +42630,33 @@ async function runExecutor(store, options, phaseId, stageId, spec, notes, execut
     outcome = await executor(executorCtx);
   } catch (error) {
     const why = error instanceof Error ? error.message : String(error);
-    appendCapped("error", {
+    const partial = partialTasksOf(error);
+    const progress2 = { rows: 0, events: 0 };
+    let recordingFailed = null;
+    if (partial.length > 0) {
+      try {
+        recordExecutorTasks(store, options, phaseId, stageId, spec, partial, progress2);
+      } catch (again) {
+        recordingFailed = again instanceof Error ? again.message : String(again);
+      }
+    }
+    const written = requireStage(store, phaseId, stageId).tasks.length - tasksBefore;
+    const whole = partial.length > 0 && written === partial.length;
+    store.save();
+    const extra = appendOrSay(() => appendCapped("error", {
       phase: phaseId,
       where: "executor",
       detail: why,
-      tasks_recorded: false
-    }, 0);
-    store.save();
-    return failStage(store, options, phaseId, stageId, `the executor threw before returning its task rows — this invocation's turn costs are not in run.yml: ${why}`, notes, tasksBefore);
+      tasks_recorded: whole,
+      rows_written: written,
+      rows_expected: partial.length,
+      events_written: progress2.events,
+      ...recordingFailed === null ? {} : { recording_error: recordingFailed }
+    }, 0));
+    const n = String(partial.length);
+    const eventsShort = recordingFailed === null ? "" : `; ${String(progress2.events)} of ${n} agent.result events could not be appended: ${recordingFailed}`;
+    const reason = partial.length === 0 ? `the executor threw before returning its task rows — this invocation's turn costs are not in run.yml: ${why}` : whole ? `the executor threw after ${n} turn(s) — their rows and costs are in run.yml${eventsShort}: ${why}` : `the executor threw after ${n} turn(s) and recording their rows threw too — ` + `${String(written)} of ${n} rows are in run.yml and the rest are not: ${why}; recording: ${recordingFailed ?? "unknown"}`;
+    return failStage(store, options, phaseId, stageId, reason, [...notes, ...extra], tasksBefore + written);
   }
   if (isSequencingRefusal(outcome)) {
     if (!started) {
@@ -42552,20 +42666,25 @@ async function runExecutor(store, options, phaseId, stageId, spec, notes, execut
     return out(EXIT_USAGE3, [...notes, ...outcome.lines], [], executorSignature(outcome));
   }
   claimEpicBranches(store, outcome.epicBranches, outcome.branchModel);
+  const progress = { rows: 0, events: 0 };
   try {
-    recordExecutorTasks(store, options, phaseId, stageId, spec, outcome);
+    recordExecutorTasks(store, options, phaseId, stageId, spec, outcome.tasks, progress);
   } catch (error) {
     const why = error instanceof Error ? error.message : String(error);
     const recorded = requireStage(store, phaseId, stageId).tasks.length;
-    appendCappedEvent(store, options, phaseId, stageId, "error", {
+    const written = recorded - tasksBefore;
+    const expected = outcome.tasks.length;
+    store.save();
+    const extra = appendOrSay(() => appendCappedEvent(store, options, phaseId, stageId, "error", {
       phase: phaseId,
       where: "record-tasks",
       detail: why,
-      rows_written: recorded - tasksBefore,
-      rows_expected: outcome.tasks.length
-    }, 0);
-    store.save();
-    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);
+      rows_written: written,
+      rows_expected: expected,
+      events_written: progress.events
+    }, 0));
+    const rows = written === expected ? `all ${String(expected)} rows are in run.yml and ${String(progress.events)} of ${String(expected)} ` + "agent.result events were appended" : `${String(written)} of ${String(expected)} rows are in run.yml and the rest are not`;
+    return failStage(store, options, phaseId, stageId, `recording this invocation's task rows threw — ${rows}: ${why}`, [...notes, ...extra], recorded);
   }
   store.save();
   if (store.cancelledUnder) {
@@ -42595,11 +42714,22 @@ async function runExecutor(store, options, phaseId, stageId, spec, notes, execut
 function isSequencingRefusal(outcome) {
   return outcome.sequencing === true && outcome.refused === true && outcome.tasks.length === 0 && outcome.costUsd === 0 && (outcome.epicBranches?.length ?? 0) === 0;
 }
-function recordExecutorTasks(store, options, phaseId, stageId, spec, outcome) {
+function appendOrSay(append) {
+  try {
+    append();
+    return [];
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    return [`the error event for this failure could not be appended to events.jsonl — ${why}; run.yml is saved regardless`];
+  }
+}
+function recordExecutorTasks(store, options, phaseId, stageId, spec, tasks, progress = { rows: 0, events: 0 }) {
   const version = frameworkVersionSync();
-  for (const task2 of outcome.tasks) {
+  const rows = [];
+  for (const task2 of tasks) {
     const id = nextTaskId(store, phaseId, stageId);
     const metered = task2.metered !== false;
+    rows.push({ id, task: task2, metered });
     recordTask(store, phaseId, stageId, {
       id,
       status: task2.error === null ? "done" : "failed",
@@ -42618,6 +42748,9 @@ function recordExecutorTasks(store, options, phaseId, stageId, spec, outcome) {
       ...cacheSplit(task2.usage?.cache_creation_input_tokens, task2.usage?.cache_read_input_tokens),
       ...task2.durationMs === undefined ? {} : { duration_ms: task2.durationMs, duration_basis: "spawned" }
     });
+    progress.rows += 1;
+  }
+  for (const { id, task: task2, metered } of rows) {
     appendCappedEvent(store, options, phaseId, stageId, "agent.result", {
       phase: phaseId,
       task: id,
@@ -42632,6 +42765,7 @@ function recordExecutorTasks(store, options, phaseId, stageId, spec, outcome) {
       ...task2.tokens === undefined ? {} : { tokens: task2.tokens },
       ...task2.usage === undefined ? {} : { usage: usagePayload(task2.usage) }
     }, metered ? round26(task2.costUsd) : 0);
+    progress.events += 1;
   }
 }
 async function commitStage(store, options, phaseId, stageId, spec, notes) {
@@ -53512,6 +53646,8 @@ import { isAbsolute as isAbsolute13, join as join135 } from "node:path";
 import { existsSync as existsSync111, readFileSync as readFileSync98, readdirSync as readdirSync34 } from "node:fs";
 import { basename as basename17, join as join131 } from "node:path";
 // src/core/replay/renderReplay.ts
+var STAGE_FAILED_MARKER = "FAILED: ";
+var NO_REASON_RECORDED = "no reason recorded";
 function renderReplay(loaded) {
   const run2 = loaded.run;
   const out2 = [
@@ -53639,9 +53775,9 @@ function bullet2(item, trail) {
     case "stage.done":
       return `${prefix5}ended`;
     case "stage.failed":
-      return `${prefix5}FAILED: ${text3(payload2.error) || "no reason recorded"}`;
+      return `${prefix5}${STAGE_FAILED_MARKER}${text3(payload2.reason) || NO_REASON_RECORDED}`;
     case "stage.skipped":
-      return `${prefix5}skipped: ${text3(payload2.reason) || "no reason recorded"}`;
+      return `${prefix5}skipped: ${text3(payload2.reason) || NO_REASON_RECORDED}`;
     case "question.asked":
       return `${prefix5}${q || "a question"} asked by ${actor}: ${text3(payload2.question)}`.trimEnd();
     case "question.answered":
@@ -53657,7 +53793,7 @@ function bullet2(item, trail) {
     case "story.reopened":
       return `${prefix5}story ${text3(payload2.story) || "?"} REOPENED by ${actor}` + ` — back to \`${text3(payload2.to_status) || "todo"}\` from \`${text3(payload2.from_status) || "?"}\`` + `${note(payload2.note)}`;
     case "story.touches_widened":
-      return `${prefix5}story ${text3(payload2.story) || "?"}'s \`touches:\` WIDENED by ${actor}` + ` (${basisOf(payload2)})` + ` — +${pathList(payload2.paths)}` + ` (${String(lengthOf(payload2.before))} → ${String(lengthOf(payload2.after))} path(s))` + `${note(payload2.note)}`;
+      return `${prefix5}story ${text3(payload2.story) || "?"}'s \`touches:\` WIDENED by ${actor}` + ` (${basisOf(payload2)})` + ` — +${widenedPaths(payload2)}` + ` (${String(listCount(payload2, "before"))} → ${String(listCount(payload2, "after"))} path(s))` + `${note(payload2.note)}`;
     case "story.base_fastforwarded":
       return `${prefix5}story ${text3(payload2.story) || "?"}'s base fast-forwarded to` + ` \`${text3(payload2.base) || "?"}\` — ${text3(payload2.from) || "?"} → ${text3(payload2.to) || "?"}` + ` (${String(payload2.commits ?? "?")} commit(s))`;
     case "story.base_updated":
@@ -53694,8 +53830,11 @@ function bullet2(item, trail) {
       return `${prefix5}map refreshed`;
     case "result.unreadable":
       return `${prefix5}UNREADABLE ${text3(payload2.path) || "result.json"}` + ` — ${text3(payload2.error) || "no parse error recorded"}` + " (nothing failed; rewrite it and run the same command again)";
-    case "error":
-      return `${prefix5}error: ${text3(payload2.message) || "no message recorded"}`;
+    case "error": {
+      const what = text3(payload2.detail) || text3(payload2.detail_omitted) || text3(payload2.message) || "no message recorded";
+      const rows = typeof payload2.rows_expected === "number" ? ` (${String(payload2.rows_written ?? "?")} of ${String(payload2.rows_expected)} task rows recorded)` : "";
+      return `${prefix5}error: ${what}${rows}`;
+    }
     default:
       return null;
   }
@@ -53753,8 +53892,12 @@ function pathList(value) {
   const items = value.filter((item) => typeof item === "string");
   return items.length === 0 ? "?" : items.join(", ");
 }
-function lengthOf(value) {
-  return Array.isArray(value) ? value.length : 0;
+function widenedPaths(payload2) {
+  const listed = pathList(payload2.paths);
+  const omitted = typeof payload2.paths_omitted === "number" && payload2.paths_omitted > 0 ? `${String(payload2.paths_omitted)} path(s) not listed on the event` : "";
+  if (omitted === "")
+    return listed;
+  return listed === "?" ? omitted : `${listed}, ${omitted}`;
 }
 function signature(actor, payload2) {
   const executed = payload2.executed_by;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tldr-experts",
-  "version": "0.25.0",
+  "version": "0.26.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.25.0",
+  "version": "0.26.0",
   "author": {
     "name": "Alan Martinez"
   }