tldr-experts 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,6 +1,130 @@
 # Changelog
 
 
+## 0.12.0 — 2026-09-08
+
+### Added
+
+- **The reviewer can run on a different model than the developer, and every verdict now says
+  which model produced it.** Measured this week across three real workspaces and 168 Build
+  stories: `model:` and `effort:` in `stage.yml` are per STAGE, one accessor served both
+  spawns, and all 168 stories ran the same model at the same effort for the developer AND the
+  reviewer that judged its diff. Zero reviewers ran on anything stronger — so *does a stronger
+  reviewer find more* was not a question the data could answer, while hosts were already
+  answering it by hand, upgrading the reviewer on stories whose own text said they were
+  security-bearing. Three additive keys close that: `reviewer: {model?, effort?}` in
+  `stage.yml` is the reviewer role's own pin; `reviewer_by_stakes:` is the same thing keyed on
+  a story's new optional `stakes:` field (`security | money | data | correctness | routine`, a
+  closed enum the Plan agent emits and nothing infers from prose); and both resolve FIELD BY
+  FIELD under `--model`/`--effort`, which stay the operator's word. Absent everywhere ⇒ the
+  reviewer runs on the stage's own two lines, byte for byte. **No opus default ships**:
+  `stages/build/stage.yml` declares `reviewer_by_stakes: {}` and a commented example, because
+  there is no evidence yet that a stronger reviewer finds more and shipping the answer as a
+  default would spend money asserting the thing these keys exist to measure. What ships is the
+  record that makes the evidence accumulate — a spawned reviewer's arguments were always on
+  its `agent.spawned`, a host review's are now read off `--model`/`--effort` on `tldrx next
+  --commit --review` and written as `basis: host-declared`, `04-build/log/<story>.md` carries
+  a `- Reviewer:` line, and `tldrx replay` names the model on every review round. A host that
+  declared nothing reads `not recorded` rather than the bundle's suggested model: that
+  suggestion is one tldrx made, and quoting it back would be a record lying in the dangerous
+  direction. (#178)
+- **`touches` was declared and never measured, so the boundary audit was answering against a
+  forecast.** Measured on three real workspaces: one story changed 21 files and 18 of them fell
+  outside its declared `touches`, and the other two stories of the same run under-declared as
+  well — none of it a mistake anybody could point at, because the 18 were the Application-layer
+  files the work genuinely required and no compiler runs at Plan time to predict them. The
+  consequence is the part worth fixing: the check that exists to say "this epic changed something
+  no story claimed" was comparing a diff against a guess, which is the shape of check that gets
+  switched off. Build now takes the second reading, at the moment a story's work is final and the
+  answer is free: it diffs the story over exactly the range the reviewer was shown (the
+  `epic_base` recorded on `task.done` since 0.10.0 — one definition of "the story's diff", not a
+  second `git diff` derivation) and, when paths landed outside the declared list, appends ONE
+  `story.touches_widened` with `basis: "measured"` and `actor: framework`, naming the paths and
+  the count. It is the SAME event `tldrx story widen` writes, deliberately: "the surface grew" is
+  one fact, and a sibling type would make every reader ask two questions to learn it. `basis` is
+  additive and **absent means `declared`**, so every row written before it existed keeps its
+  meaning and reads unchanged. It is advisory and cannot refuse — nothing is written when the
+  work stayed inside the forecast, an unreadable diff is simply no measurement, and the story's
+  own `touches:` is never rewritten, because declaring is the operator's verb and a framework
+  that back-dated a declaration would make the plan claim it declared a path it did not. Both
+  bases render labelled in the Build handoff, in the `tldrx ship` PR body that embeds it, and in
+  `tldrx replay`, so the paths outside BOTH readings are the ones a human is pointed at.
+
+
+- **A run now records which tldrx wrote it (#183).** `run.yml`'s `version: 1` is the FILE
+  FORMAT's number; nothing anywhere carried the framework's, so across 23 unattended runs on
+  three real workspaces no record could be attributed to the release that produced it — in a
+  week that shipped ten of them and moved behaviour in three (the DoD refusal record grew
+  `status`, the reviewer's diff base moved, a mandate check was reworded). `run.yml` gains
+  two additive keys beside the format's: `created_with`, stamped once at `run new` and never
+  rewritten, and `last_written_by`, rewritten by every save — so a run that outlived an
+  upgrade carries both ends of the range that drove it. `agent.spawned` and `agent.result`
+  carry `tldrx_version` for the same reason at the turn level: a spawn that never produced a
+  result is still a turn a release is answerable for. All of it reads from the one source
+  `tldrx --version` reads, so a record and the CLI cannot disagree. `run status` prints both
+  stamps; a run.yml written before the keys reads `not recorded`, which is a different fact
+  from a guess at what happened to be installed that day.
+
+- **A task row now carries a duration it actually measured, and says which span it is
+  (#184).** `started_at` is the INVOCATION's clock and `ended_at` is the instant the row was
+  written, so every task of one parallel Build shares a start and subtracting the two yields
+  close to the whole invocation for each of them — three unattended runs measured 34.5 h,
+  43.2 h and 36.8 h of span that no record could attribute to a phase or a sub-agent. Those
+  two fields keep their meaning; `duration_ms` is the new one, and it never travels without
+  `duration_basis`. `spawned` is the wall clock around the sub-agent's own process, measured
+  in `spawnAgent.ts` and written on the task row and on `agent.result`. `prepare-to-commit`
+  is the gap between a `--prepare` bundle's `prepared_at` and the `--commit` that recorded
+  the turn: the only span the framework can see for an in-session turn, and one that INCLUDES
+  the host's own time — a ceiling on the sub-agent's span the way `spent_usd` is a floor on
+  the money, and the spec says so rather than letting the number be read as the sub-agent's.
+  `tldrx cost` gains a duration column per attempt and a per-stage sum that names a mixed
+  basis instead of adding two different quantities, and counts the attempts it could not
+  time. A row from before this reads `not recorded`, never `0s`: "it took no time" and
+  "nobody timed it" are different facts and only one is a measurement.
+
+- **A `maintain` skill turns a session into this repo's maintainer, and the circuit it encodes
+  is the one that was measured, not the one that sounds right.** Twelve maintenance waves ran
+  over two days by hand, and three of their lessons were costing time every cycle. First,
+  issues go stale in days: one asked for a fix to sequential Build execution while `--parallel`
+  had already shipped, so the skill reproduces an issue's measurement on current `origin/main`
+  BEFORE anything is touched, and a measured refutation closes it. Second, a fresh reviewer who
+  did not write the code found a real Important defect in four of those waves, each one
+  checkable from `git log`: `2a6413f` fixed a defect review found in `cbd5c4b`, and the fixes
+  that pre-merge review forced landed inside `28a987e` (the B0 mandate reword), `674049a` (the
+  heartbeat fix) and `103ff96` (the `runAuto` $0.00 fix). The one wave that reviewed AFTER
+  merging left its defect on `main` for two hours. So review is a mandatory step BEFORE
+  `scripts/merge-wave.sh`, run by a separate sub-agent on a mid-tier model, which is where the
+  defects were actually found. Third, concurrency: at most 3 issues a
+  cycle with non-overlapping file sets and at most 2 implementers at once, because the flaky
+  tests this repo already knows about redden under machine load and a red gate you caused
+  yourself costs a full re-run to disprove. The skill is a workflow and cites `AGENTS.md` and
+  `docs/RELEASING.md` by section rather than restating them; `test/maintain-skill.test.ts`
+  holds that premise mechanically — every `tldrx` command and `scripts/*.sh` it names must
+  exist in the real surface, every `§N` it cites must resolve to a real heading, and no private
+  workspace name or chat-product name may appear anywhere in the skill tree (#191). The review
+  step itself is still prose, which is the one thing the skill cannot fix about itself — #192
+  proposes making `scripts/merge-wave.sh` refuse a branch that carries no review record.
+
+### Fixed
+
+- **No surface prints a bare `$0.00` over work nobody metered.** Measured across 23 real runs:
+  45 % of 845 task rows are in-session turns recorded `cost_usd: null, metered: false`, which
+  every sum treats as contributing nothing — the only honest arithmetic there is. Two of those
+  runs then RENDERED `spent_usd: 0.00` against $3,000 and $200 ceilings after 30 and 9
+  stories. The counting and the caveat already existed (#103, #139); what did not was a rule
+  for the FIGURE, so each screen printed `$${n.toFixed(2)}` in its own words and three printed
+  it with no caveat at all. One implementation now writes it everywhere: `≥ $12.40 (7 tasks
+  unmetered)` when some of the work was metered, and `not measured: 9 in-session tasks, 0
+  metered` when none of it was and there is no floor worth printing. `run status`, `budget
+  show`, the dashboard's row and its hero, `replay`, `run auto`'s per-loop lines, the Build
+  handoff's `Cost:` header (and so the ship PR body, which embeds it), the `budget.warned`
+  note and every notification payload all read from it. `budget.yml` gains `unmetered_tasks`
+  and `spent_basis: lower-bound | complete` so an archived file alone still tells the truth —
+  emitted only when there IS something unmetered, so a fully metered run and every budget.yml
+  written before them stay byte-identical. `spent_usd` is unchanged and still what the ceiling
+  arithmetic enforces; a run that really did meter everything keeps its plain figure, because
+  a caveat on every screen is a caveat nobody reads.
+
 ## 0.11.1 — 2026-09-08
 
 ### Changed

package/README.md

@@ -316,6 +316,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.12.0 | 2026-09-08 | `beta` | records that can be attributed and spans that were actually measured: the reviewer can be pinned to its own model and effort per role (`reviewer:`) and per story stakes (`reviewer_by_stakes:`, keyed on a story's new optional `stakes:` enum), resolved field by field under `--model`/`--effort` and shipping NO opus default — because there is no evidence yet that a stronger reviewer finds more, only the record that lets the evidence accumulate: every verdict now names the model that produced it, a host review reading `basis: host-declared` off its own flags and a host that declared nothing reading `not recorded` rather than the bundle's suggestion; `run.yml` gains `created_with` and `last_written_by` beside the file format's own `version: 1`, and `agent.spawned`/`agent.result` carry `tldrx_version`, so a run that outlived an upgrade carries both ends of the range that drove it; a task row carries `duration_ms` that never travels without `duration_basis` — `spawned` is the wall clock around the sub-agent's process, `prepare-to-commit` is a ceiling that includes the host's own time — and `tldrx cost` shows a duration per attempt and a per-stage sum that names a mixed basis instead of adding two different quantities, with a pre-existing row reading `not recorded` and never `0s`; no surface prints a bare `$0.00` over work nobody metered — one implementation writes `≥ $12.40 (7 tasks unmetered)` or `not measured: 9 in-session tasks, 0 metered` across `run status`, `budget show`, the dashboard, `replay`, `run auto`, the Build handoff and every notification, and `budget.yml` gains `unmetered_tasks` and `spent_basis`; the surface a story actually changed is measured off its own diff over the range the reviewer was shown and appended as one `story.touches_widened` with `basis: "measured"` beside what was declared, advisory and never rewriting the operator's `touches:`; and a `maintain` skill encodes the maintenance circuit twelve hand-run waves actually measured — reproduce an issue on current `origin/main` before touching anything, a fresh reviewer before `merge-wave.sh` and not after, at most 3 issues and 2 implementers a cycle — pinned by a test that every command and `§N` it cites resolves |
 | 0.11.1 | 2026-09-08 | `beta` | operating a run when nobody is watching: the drive mandate now names the host's own context as the costliest instrument and tells the driver what to READ back — a sub-agent's outcome from its `result.json` and the ledger, never its transcript, each sub-agent briefed to report its turn in ten lines, and a cited file re-opened to VERIFY at a gate rather than re-read for a claim already made — paid for inside the unchanged line budgets rather than appended; `.tldrx/workspace.yml` takes one optional `notify:` block whose command is handed a `version: 1` JSON object on stdin at each moment a person is needed (an open question with its options, its recommendation and the literal `tldrx answer` line; a gate with its approve line; a finished or failed run with what its exit code's family means; a budget warning with both numbers), split to argv and never shelled, with a notifier that will not split, is not there, exits non-zero or hangs recorded as `notify.failed` instead of failing the run; `tldrx run auto --wait-answers <duration>` polls the question files and resumes when the answer lands instead of exiting 4 the moment a stage parks, and `--notify-every <duration>` sends a timer-driven heartbeat that reminds rather than reassures while a run is parked; and a new EN+ES guide page walks the whole unattended loop — host mode versus the engine, the payload keys, a dependency-free Node adapter, a first-run checklist and the four ways it silently does nothing — naming no messaging service, by the same reasoning the mandate has always given |
 | 0.11.0 | 2026-09-08 | `beta` | governance that leaves a record: every answer says who decided it and what repo it binds, an advisory contradiction check raises a question that never stops a run and states its own limit, the close and the Build handoff count decided vs not-stated; `tldrx story widen` is the sanctioned way to grow a story's surface (a done story needs `reopen --for-fix` first) and a defect no story owns is named in the handoff, the PR body and the boundary card instead of absorbed; a budget grant is a recorded number in `budget.yml` that survives every writer, `budget raise` warns or refuses against it, presets are labelled as the assumptions they are, `triage.budget_basis` says where a figure came from and `tldrx cost --stories` measures each story against the ceiling its spawn was given, honest about lower bounds |
 | 0.10.0 | 2026-09-07 | `beta` | the mechanical blockers measured in real runs, fixed: a refused DoD command is recorded as refused (never a fabricated exit 126) in the event, the handoff, the review and retro logs, and the readers that used to recover it as green; the dirty-tree refusal prints the exact stash and pop commands and its true reason; the reviewer diffs the epic as it was before the merge (`epic_base` recorded on the story and the bundle) instead of an empty range; `tldrx init` probes each declared command once and records `command_probes` beside a `commands:` allowlist it never guesses; `tldrx ship` opens a PR whose body describes the change and its known defects, with the handoff folded underneath, and a state refusal that honours settled stories' declared touches; reviewer turns carry their token split and the spend basis reads it, so a whole provider no longer reads as absent |

package/dist/hooks/answer-capture.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-qn8qnrgw.js";
+} from "./chunk-fyr7f9t6.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-gj1ckg0c.js";
+} from "./chunk-nwzevx0j.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-8d0t69pk.js";
+} from "./chunk-mvz7jwt8.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-rw3n3z6t.js";
-import"./chunk-b26rvgjd.js";
+} from "./chunk-f1w9sy07.js";
+import"./chunk-yvgkw0gm.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -24,7 +24,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-h23db062.js";
+} from "./chunk-1knfmj6j.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -32,7 +32,7 @@ import {
   commandProbeIssues,
   factsPath,
   parseYaml
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync5 } from "fs";

package/dist/hooks/budget-gate.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-zs84arc1.js";
+} from "./chunk-qefqmgjn.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-hx0jgrmh.js";
-import"./chunk-8d0t69pk.js";
+} from "./chunk-v2xzr4qd.js";
+import"./chunk-mvz7jwt8.js";
 import {
   asRunBudget,
   currentActor,
@@ -29,20 +29,20 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-jmypgf6s.js";
+} from "./chunk-zrjgpgwy.js";
 import {
   EventLog
-} from "./chunk-rw3n3z6t.js";
+} from "./chunk-f1w9sy07.js";
 import {
   noteDeprecations
-} from "./chunk-h23db062.js";
+} from "./chunk-1knfmj6j.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/hooks/{chunk-h23db062.js → chunk-1knfmj6j.js}

@@ -1,6 +1,6 @@
 import {
   parseSrcToken
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/core/text/questions.ts
 var REQUIRED_METADATA_KEYS = ["id", "status", "area", "asked_by", "asked_at"];

package/dist/hooks/{chunk-5hyd1rk1.js → chunk-6fywd8xd.js}

@@ -9122,4 +9122,4 @@ function noneBullet(lookedAt) {
   return `- none [src: absent:${lookedAt}]`;
 }
 
-export { runtime, parseYaml, parseYamlRepairing, STAGES_DIR, TEMPLATES_DIR, PROJECT_FRAMEWORK_DIR, PROJECT_WORK_DIR, result, requireVersion, isRecord, requireKeys, requireEnum, requireArray, requireNumber, requireString, requireRecord, asDocument, STORY_ID_RE, WAVE_ID_RE, MAX_WAVES, MAX_STORIES_PER_WAVE, MAX_PLAN_STORIES, requireStringList, requirePattern, requireVersion1, parseFrontMatter, ITERATION_ONLY_SLOT, readStory, DodCommandRefused, runDodCommand, commandProbeIssues, readableSource, SRC_PATTERNS, srcRule, parseSrcToken, classifySrc, locateWork, findWorkspaceRoot, loadWorkspace, toSrcContext, repoPath, factsPath, stageYamlPath, listRunDirs, parseHandoff, isHandoff, BULLET_RULE, EMPTY_SECTION_RULE, validateHandoff, validateCitations, noneBullet };
+export { runtime, parseYaml, parseYamlRepairing, FRAMEWORK_ROOT, STAGES_DIR, TEMPLATES_DIR, PROJECT_FRAMEWORK_DIR, PROJECT_WORK_DIR, result, requireVersion, isRecord, requireKeys, requireEnum, requireArray, requireNumber, requireString, requireRecord, asDocument, STORY_ID_RE, WAVE_ID_RE, MAX_WAVES, MAX_STORIES_PER_WAVE, MAX_PLAN_STORIES, requireStringList, requirePattern, requireVersion1, parseFrontMatter, ITERATION_ONLY_SLOT, readStory, DodCommandRefused, runDodCommand, commandProbeIssues, readableSource, SRC_PATTERNS, srcRule, parseSrcToken, classifySrc, locateWork, findWorkspaceRoot, loadWorkspace, toSrcContext, repoPath, factsPath, stageYamlPath, listRunDirs, parseHandoff, isHandoff, BULLET_RULE, EMPTY_SECTION_RULE, validateHandoff, validateCitations, noneBullet };

package/dist/hooks/{chunk-z6n9551r.js → chunk-cg8v4mz4.js}

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

package/dist/hooks/{chunk-rw3n3z6t.js → chunk-f1w9sy07.js}

@@ -10,7 +10,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/core/events/EventLog.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -448,6 +448,9 @@ function describe(value) {
   return typeof value === "string" ? `\`${value}\`` : String(value);
 }
 
+// src/core/run/duration.ts
+var DURATION_BASES = ["spawned", "prepare-to-commit"];
+
 // src/core/run/RunFile.ts
 var STAGE_STATUSES = [
   "pending",
@@ -596,6 +599,10 @@ function validateRunFile(input) {
   }
   if (doc.attended_by !== undefined)
     requireEnum(doc.attended_by, ATTENDED_BY, "attended_by", issues);
+  for (const key of ["created_with", "last_written_by"]) {
+    if (doc[key] !== undefined)
+      requireString(doc[key], key, issues);
+  }
   if (doc.keep_worktrees !== undefined && typeof doc.keep_worktrees !== "boolean") {
     issues.push({ path: "keep_worktrees", message: `expected a boolean, got ${typeof doc.keep_worktrees}` });
   }
@@ -717,6 +724,17 @@ function validateRunFile(input) {
               issues.push({ path: `${tp}.${key}`, message: "expected a number >= 0" });
             }
           }
+          if (task.duration_ms !== undefined) {
+            if (typeof task.duration_ms !== "number" || !Number.isFinite(task.duration_ms) || task.duration_ms < 0) {
+              issues.push({ path: `${tp}.duration_ms`, message: "expected a number >= 0" });
+            }
+            requireEnum(task.duration_basis, DURATION_BASES, `${tp}.duration_basis`, issues);
+          } else if (task.duration_basis !== undefined) {
+            issues.push({
+              path: `${tp}.duration_basis`,
+              message: "a duration_basis with no duration_ms names the basis of nothing"
+            });
+          }
           if (typeof task.cost_usd === "number")
             spentFromTasks += task.cost_usd;
           checkOrder(task.started_at, task.ended_at, tp, issues);

package/dist/hooks/{chunk-qn8qnrgw.js → chunk-fyr7f9t6.js}

@@ -1,15 +1,15 @@
 import {
   findDuplicate
-} from "./chunk-gj1ckg0c.js";
+} from "./chunk-nwzevx0j.js";
 import {
   evidencePath,
   gateEvidencePath,
   parseEvidence
-} from "./chunk-rw3n3z6t.js";
+} from "./chunk-f1w9sy07.js";
 import {
   openBlocks,
   parseQuestions
-} from "./chunk-h23db062.js";
+} from "./chunk-1knfmj6j.js";
 
 // src/core/distill/distill.ts
 var CONFLICT_THRESHOLD = 0.6;

package/dist/hooks/{chunk-wbkwjpq2.js → chunk-jd48713j.js}

@@ -7,8 +7,10 @@ import {
   isAttendedByHostView,
   nowRfc3339,
   openRunViews,
+  spentBasis,
+  tallyOf,
   validateRunBudget
-} from "./chunk-jmypgf6s.js";
+} from "./chunk-zrjgpgwy.js";
 import {
   EventLog,
   asRunFile,
@@ -20,7 +22,7 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-rw3n3z6t.js";
+} from "./chunk-f1w9sy07.js";
 import {
   backupPathFor,
   isAlive,
@@ -29,26 +31,43 @@ import {
   workspaceRootOfRunDir,
   writeAtomic,
   yamlScalar
-} from "./chunk-b26rvgjd.js";
+} from "./chunk-yvgkw0gm.js";
 import {
   isAdvisory,
   noteDeprecations,
   openBlocks,
   parseQuestions
-} from "./chunk-h23db062.js";
+} from "./chunk-1knfmj6j.js";
 import {
+  FRAMEWORK_ROOT,
   listRunDirs,
   parseYaml,
   parseYamlRepairing
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/core/statusline/runSnapshot.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
-import { join as join2 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
+import { join as join3 } from "node:path";
 
 // src/core/run/RunStore.ts
-import { existsSync, readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
+import { basename, join as join2 } from "node:path";
+
+// src/core/frameworkVersion.ts
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+var PACKAGE_JSON = join(FRAMEWORK_ROOT, "package.json");
+function versionOf(pkg) {
+  const version = pkg?.version;
+  return typeof version === "string" ? version : "0.0.0";
+}
+function frameworkVersionSync() {
+  try {
+    return versionOf(JSON.parse(readFileSync(PACKAGE_JSON, "utf8")));
+  } catch {
+    return "0.0.0";
+  }
+}
 
 // src/core/run/emitRunYaml.ts
 function inlineList(values) {
@@ -91,6 +110,7 @@ function task(t, indent) {
     ...t.stopped_by === undefined || t.stopped_by === null ? [] : [`${inner}stopped_by: ${yamlScalar(t.stopped_by)},`],
     ...t.banked_before_refusal === undefined ? [] : [`${inner}banked_before_refusal: true,`],
     ...t.dedupe === undefined ? [] : [`${inner}dedupe: ${yamlScalar(t.dedupe)},`],
+    ...t.duration_ms === undefined ? [] : [`${inner}duration_ms: ${String(Math.round(t.duration_ms))}, ` + `duration_basis: ${yamlScalar(t.duration_basis ?? null)},`],
     `${inner}outputs: ${inlineList(t.outputs)}}`
   ].join(`
 `);
@@ -126,6 +146,8 @@ function emitRunYaml(run) {
     "# tldrx-work/<run>/run.yml — the execution path and the only resume point (spec §2.2).",
     "# Written by the facilitator alone. Hand-edit at your own risk: every write revalidates.",
     `version: ${run.version}`,
+    ...run.created_with === undefined ? [] : [`created_with: ${yamlScalar(run.created_with)}`],
+    ...run.last_written_by === undefined ? [] : [`last_written_by: ${yamlScalar(run.last_written_by)}`],
     `run: ${yamlScalar(run.run)}`,
     `title: ${yamlScalar(run.title)}`,
     `scope: ${yamlScalar(run.scope)}`,
@@ -190,6 +212,10 @@ function emitBudgetYaml(budget) {
     ...budget.authorized_by === null ? [] : [`authorized_by: ${yamlScalar(budget.authorized_by)}`],
     ...budget.authorized_at === null ? [] : [`authorized_at: ${yamlScalar(budget.authorized_at)}`],
     ...budget.on_grant_exceed === DEFAULT_ON_GRANT_EXCEED ? [] : [`on_grant_exceed: ${yamlScalar(budget.on_grant_exceed)}`],
+    ...budget.unmetered_tasks > 0 ? [
+      `unmetered_tasks: ${String(budget.unmetered_tasks)}`,
+      `spent_basis: ${yamlScalar(budget.spent_basis)}`
+    ] : [],
     "phases:"
   ];
   for (const phase of budget.phases) {
@@ -223,7 +249,7 @@ class RunStore {
     this.currentBudget = budget;
   }
   static open(runDir) {
-    const runPath = join(runDir, "run.yml");
+    const runPath = join2(runDir, "run.yml");
     if (!existsSync(runPath))
       throw new RunStoreError(`no run.yml in ${runDir}`);
     const run = parseStateFile(runPath);
@@ -233,7 +259,7 @@ class RunStore {
       const first = validation.issues[0];
       throw new RunStoreError(`invalid run.yml (${runPath}): ${first?.path ?? ""} ${first?.message ?? "schema error"}`);
     }
-    const budgetPath = join(runDir, "budget.yml");
+    const budgetPath = join2(runDir, "budget.yml");
     if (!existsSync(budgetPath))
       throw new RunStoreError(`no budget.yml in ${runDir}`);
     const budget = parseStateFile(budgetPath);
@@ -252,9 +278,9 @@ class RunStore {
     try {
       withWorkspaceLock(workspaceRootOfRunDir(this.runDir), () => {
         if (runRepaired)
-          writeAtomic(join(this.runDir, "run.yml"), emitRunYaml(this.current));
+          writeAtomic(join2(this.runDir, "run.yml"), emitRunYaml(this.current));
         if (budgetRepaired)
-          writeAtomic(join(this.runDir, "budget.yml"), emitBudgetYaml(this.currentBudget));
+          writeAtomic(join2(this.runDir, "budget.yml"), emitBudgetYaml(this.currentBudget));
       });
       const which = [runRepaired ? "run.yml" : "", budgetRepaired ? "budget.yml" : ""].filter((name) => name !== "").join(" and ");
       process.stderr.write(`tldrx: ${this.runDir}: ${which} held text broken across lines by an emitter bug ` + "since fixed. It was repaired in memory and rewritten correctly; the version that was " + `on disk is beside it as .bak. Nothing else about the run was changed.
@@ -338,8 +364,8 @@ class RunStore {
         const first = budgetValidation.issues[0];
         throw new RunStoreError(`refusing to write an invalid budget.yml: ${first?.path ?? ""} ${first?.message ?? ""}`);
       }
-      writeAtomic(join(this.runDir, "budget.yml"), emitBudgetYaml(budget));
-      writeAtomic(join(this.runDir, "run.yml"), emitRunYaml(rolled));
+      writeAtomic(join2(this.runDir, "budget.yml"), emitBudgetYaml(budget));
+      writeAtomic(join2(this.runDir, "run.yml"), emitRunYaml(rolled));
       this.current = rolled;
       this.currentBudget = budget;
       this.budgetMutated = false;
@@ -348,11 +374,11 @@ class RunStore {
   ceilingsToWrite() {
     if (this.budgetMutated)
       return this.currentBudget;
-    const path = join(this.runDir, "budget.yml");
+    const path = join2(this.runDir, "budget.yml");
     if (!existsSync(path))
       return this.currentBudget;
     try {
-      const doc = parseYaml(readFileSync(path, "utf8"));
+      const doc = parseYaml(readFileSync2(path, "utf8"));
       const validation = validateRunBudget(doc);
       if (!validation.ok)
         return this.currentBudget;
@@ -376,7 +402,7 @@ class RunStore {
   }
 }
 function parseStateFile(path) {
-  const text = readFileSync(path, "utf8");
+  const text = readFileSync2(path, "utf8");
   try {
     return parseYamlRepairing(text);
   } catch (error) {
@@ -406,7 +432,8 @@ function rollUp(run) {
     ...run,
     phases,
     budget: { ...run.budget, spent_usd: spent },
-    updated_at: nowRfc3339()
+    updated_at: nowRfc3339(),
+    last_written_by: frameworkVersionSync()
   };
   return { ...next, status: deriveRunStatus(next) };
 }
@@ -415,8 +442,11 @@ function rollUpBudget(budget, run) {
   for (const phase of run.phases) {
     spentByPhase.set(phase.id, round(phase.stages.reduce((sum, s) => sum + s.cost_usd, 0)));
   }
+  const tally = tallyOf(run.phases.flatMap((p) => p.stages.flatMap((s) => s.tasks)));
   return {
     ...budget,
+    unmetered_tasks: tally.unmetered,
+    spent_basis: spentBasis(tally.unmetered),
     phases: budget.phases.map((p) => ({ ...p, spent_usd: spentByPhase.get(p.id) ?? p.spent_usd }))
   };
 }
@@ -456,7 +486,7 @@ function describeGateSignature(sig) {
 }
 
 // src/core/facilitator/skipIf.ts
-import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "node:fs";
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3 } from "node:fs";
 function phaseDirs(runDir) {
   try {
     return readdirSync(runDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && /^0[1-9]-/.test(entry.name)).map((entry) => entry.name).sort();
@@ -468,7 +498,7 @@ function openQuestionIds(path) {
   if (!existsSync2(path))
     return [];
   try {
-    return openBlocks(parseQuestions(readFileSync2(path, "utf8")).blocks).map((block) => block.id);
+    return openBlocks(parseQuestions(readFileSync3(path, "utf8")).blocks).map((block) => block.id);
   } catch {
     return [];
   }
@@ -477,7 +507,7 @@ function blockingQuestionIds(path) {
   if (!existsSync2(path))
     return [];
   try {
-    return openBlocks(parseQuestions(readFileSync2(path, "utf8")).blocks).filter((block) => !isAdvisory(block)).map((block) => block.id);
+    return openBlocks(parseQuestions(readFileSync3(path, "utf8")).blocks).filter((block) => !isAdvisory(block)).map((block) => block.id);
   } catch {
     return [];
   }
@@ -490,7 +520,7 @@ function runSnapshot(root) {
 function openQuestions(snapshot) {
   const ids = [];
   for (const phase of phaseDirs(snapshot.runDir)) {
-    ids.push(...openQuestionIds(join2(snapshot.runDir, phase, "questions.md")));
+    ids.push(...openQuestionIds(join3(snapshot.runDir, phase, "questions.md")));
   }
   return ids;
 }
@@ -558,11 +588,11 @@ function fromTolerantRead(root) {
   };
 }
 function readBudgetMirror(runDir) {
-  const path = join2(runDir, "run.yml");
+  const path = join3(runDir, "run.yml");
   if (!existsSync3(path))
     return { ceiling_usd: 0, spent_usd: 0 };
   try {
-    const text = readFileSync3(path, "utf8");
+    const text = readFileSync4(path, "utf8");
     return {
       ceiling_usd: numberAfter(text, "ceiling_usd"),
       spent_usd: numberAfter(text, "spent_usd")
@@ -577,18 +607,18 @@ function numberAfter(text, key) {
 }
 
 // src/core/run/waiting.ts
-import { basename as basename2, join as join4 } from "node:path";
+import { basename as basename2, join as join5 } from "node:path";
 
 // src/core/run/prepared.ts
 import { existsSync as existsSync4, readdirSync as readdirSync2, statSync } from "node:fs";
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 var PENDING_JSON = "pending.json";
 function preparedBundles(runDir, stageId) {
-  const dir = join3(runDir, ".agent", stageId);
+  const dir = join4(runDir, ".agent", stageId);
   if (!existsSync4(dir))
     return [];
   const found = [];
-  if (existsSync4(join3(dir, PENDING_JSON)))
+  if (existsSync4(join4(dir, PENDING_JSON)))
     found.push(dir);
   let entries;
   try {
@@ -597,14 +627,14 @@ function preparedBundles(runDir, stageId) {
     return found;
   }
   for (const entry of entries) {
-    const child = join3(dir, entry);
+    const child = join4(dir, entry);
     try {
       if (!statSync(child).isDirectory())
         continue;
     } catch {
       continue;
     }
-    if (existsSync4(join3(child, PENDING_JSON)))
+    if (existsSync4(join4(child, PENDING_JSON)))
       found.push(child);
   }
   return found;
@@ -651,7 +681,7 @@ function waitingFor(run, runDir) {
       questions: []
     };
   }
-  const open = blockingQuestionIds(join4(runDir, cursor.phase, "questions.md"));
+  const open = blockingQuestionIds(join5(runDir, cursor.phase, "questions.md"));
   switch (entry.stage.status) {
     case "awaiting_gate":
       return {

package/dist/hooks/{chunk-8d0t69pk.js → chunk-mvz7jwt8.js}

@@ -1,6 +1,6 @@
 import {
   runtime
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/core/hooks/passthrough.ts
 async function readStdin() {

package/dist/hooks/{chunk-gj1ckg0c.js → chunk-nwzevx0j.js}

@@ -3,7 +3,7 @@ import {
   withWorkspaceLock,
   workspaceRootOfFactsPath,
   writeAtomic
-} from "./chunk-b26rvgjd.js";
+} from "./chunk-yvgkw0gm.js";
 import {
   FACT_CONFIDENCES,
   FACT_KINDS,
@@ -14,7 +14,7 @@ import {
   isLive,
   isRetired,
   noteDeprecations
-} from "./chunk-h23db062.js";
+} from "./chunk-1knfmj6j.js";
 import {
   SRC_PATTERNS,
   asDocument,
@@ -27,7 +27,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/core/facts/FactsStore.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-zs84arc1.js → chunk-qefqmgjn.js}

@@ -3,7 +3,7 @@ import {
   EMPTY_SECTION_RULE,
   noneBullet,
   srcRule
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/hooks/lib/messages.ts
 var GRAMMAR = "[src: <repo:path:line> | https://… | Q<n> | F<n> | $ <cmd> → exit <n> | graph:<node> | absent:<path>]";