tldr-experts 0.3.1 → 0.4.0

package/README.md

@@ -13,10 +13,6 @@ do: a command that cannot do the thing exits non-zero and says which thing.
 
 ## Quick start
 
-> **Not on npm yet.** Every published version was unpublished on 2026-08-29 (`npm view tldr-experts
-> version` → `E404 Unpublished`) and there is no `v0.3.0` tag, so the `npm i -g` line 404s until
-> `scripts/release.sh 0.3.0` is run. Until then: clone and `bun link`, or `bun <repo>/bin/tldrx.ts <cmd>`.
-
 ```bash
 npm i -g tldr-experts     # installs `tldrx` (short) and `tldr-experts` (same binary)
 cd your-project
@@ -25,6 +21,11 @@ tldrx init                # detect repos, map the code, write .tldrx/, ask only
 tldrx install --claude    # write the skill, hooks and status line into ./.claude/
 ```
 
+**Never used it before?** `tldrx learn` teaches the loop by running it: eight chapters, ~15 minutes,
+in a throwaway sandbox with a toy repo and a stand-in agent. Every command in it is the real one —
+`init`, `run new`, `next`, `approve`, a Build that cuts a branch and runs a real DoD — so nothing it
+shows you can drift from what the binary does, and it costs $0.00 and touches nothing you own.
+
 Then open Claude Code there and type **`/tldrx`**. It runs `tldrx status`, finds what is already
 waiting on you — unanswered setup questions, a proposed split nobody decided, a run waiting on a gate,
 an expert no stage can lean on yet — and walks you through it one item at a time, asking every decision
@@ -39,6 +40,65 @@ tldrx run auto            # `next`, over and over, until something actually need
 dependencies, so an installed `tldrx` needs only Node; Bun builds it. Full walkthrough:
 [`docs/guide/01-quick-start.md`](docs/guide/01-quick-start.md).
 
+## Trying it: three ways to run
+
+`tldrx run auto` and `tldrx run attend host` read like two speeds of the same thing. They are
+opposites and they do not compose. **`auto` is an engine, not a lock**: a headless loop in which
+the *framework* spawns a metered sub-agent, stage after stage. **`attend host` is a lock, not an
+engine**: it sets one field, spends nothing and runs no stage, and from then on the framework never
+spawns on that run — every turn is a `--prepare` / `--commit` handshake with a session you drive.
+`run auto` on an attended run is refused outright (exit `1`); a bare `tldrx next` there exits `4`
+and names the `--prepare` command instead.
+
+| | who executes each turn | what a turn costs | where it stops |
+|---|---|---|---|
+| `tldrx run auto` | the framework — `claude -p`, spawned stage after stage | metered per spawn, rolled up by `tldrx cost` | the first human gate or open question (`4`), stage failure (`5`), ceiling (`2`) |
+| `tldrx run attend host`, driven from a session | your session's own sub-agents | host-billed; the framework records `cost_usd: null, metered: false` | every turn — `--prepare` writes the bundle, `--commit` settles it |
+| the same, under a **mandate** | your session's own sub-agents | host-billed | a new product decision, a ceiling raise, a boundary exit — nothing else |
+
+- **A small run you were going to watch anyway** → `run auto`. One command, and it stops the moment it needs you.
+- **A Claude Code session already open, and you care about cost or quality** → `run attend host`, driven from it: the context is warm, the turns are host-billed, and the framework writes the Build reviewer's bundle rather than spawning a second reader beside one you are already paying for.
+- **Overnight, hands off, and you still want the adversarial check** → `run attend host` plus a mandate, below.
+- **CI or cron** → `run auto`. It is the only one of the three with no session behind it.
+
+### Overnight, with the checking kept
+
+Two commands and a prompt. There is no keyword for this: the mandate is prose you write.
+
+```bash
+tldrx run new payments --scope feature --budget 25 \
+  --attended-by host --gates what:agent,plan:agent,build:agent,watch:agent
+tldrx run attend host 260101-payments      # or flip a run that is already open
+```
+
+`--gates` **replaces the workflow's gates wholesale**, and a stage you leave out of the list becomes
+`auto` — so name every gate you want signed. Then, in the session, the mandate:
+
+> Act as my unattended verification gate on run `260101-payments`, until it reaches its last gate.
+>
+> Drive every stage yourself — `tldrx next --prepare 260101-payments`, then
+> `tldrx next --commit 260101-payments` — dispatching your own sub-agents for the turns. The
+> framework must never spawn.
+>
+> For every build story, run an INDEPENDENT adversarial review through the `--review` handshake:
+> `tldrx next --prepare --review`, one read-only sub-agent over the diff, then
+> `tldrx next --commit --review`. Its job is to find what the developer got wrong, not to agree
+> with it.
+>
+> Approve a gate only after you have checked it yourself — that the citations resolve, that every
+> touched path is one this run declared, and that the diff matches the stories it claims to
+> implement — and write that check down as evidence: `tldrx gate template`, fill it in, then
+> `tldrx approve --as-agent`.
+>
+> Interrupt me ONLY for a new product decision, a budget-ceiling raise, or work that has to go
+> outside the declared boundary. Everything else you decide, and log.
+>
+> Never push. The final merge is mine.
+
+The whole chapter — the three switches, what "never spawns" is enforced by, the review handshake,
+the fix list, the evidence note and the four fallthroughs:
+[10 Unattended mode](docs/guide/10-unattended-mode.md).
+
 ## How much human is in the loop
 
 Every stage ends at a gate; what you choose is **who closes it**. `human` waits for `tldrx approve`.
@@ -79,6 +139,9 @@ signs something it should not have, `tldrx reject --stage <phase>/<stage> --note
 the cursor back and marks the later stages `stale`. When it is one BUILD STORY you disagree with — a
 story two reviewers refused, which is terminal for the rest of the run —
 `tldrx story reopen <id> --note "…"` gives that one story another run of attempts and nothing else.
+When you fix `.tldrx/workspace.yml` mid-run and the approved stories still cite the old command strings,
+`tldrx plan sync-dod` rewrites just their dod lines — renames followed, removed commands dropped, and
+anything with no ancestor in the file's history flagged rather than guessed at.
 What an auto gate cannot do: [`docs/guide/03-runs-and-gates.md`](docs/guide/03-runs-and-gates.md).
 
 ## What you see while it runs
@@ -152,7 +215,11 @@ else, because those five are machine-local or regenerated: `.tldrx/graphify-out/
 
 ## Documentation
 
-The guide, in `docs/guide/`: [1 Quick start](docs/guide/01-quick-start.md) ·
+**[The documentation site](https://ederwii.github.io/tldr-experts/)** is the place to start if you have
+never used this: a landing page, a Quickstart and one short page per concept, written for a reader
+rather than for an agent. Source in [`docs-site/`](docs-site/).
+
+The reference guide, in `docs/guide/`: [1 Quick start](docs/guide/01-quick-start.md) ·
 [2 The loop](docs/guide/02-the-loop.md) (the four steps, what a stage file controls, the two execution modes) ·
 [3 Runs and gates](docs/guide/03-runs-and-gates.md) (`run new`→`retro`, gate policy, `run auto`, unlock/cancel, dashboard, tickets) ·
 [4 Experts](docs/guide/04-experts.md) (loading rules, role experts, training, levels) ·
@@ -175,6 +242,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.4.0 | 2026-09-01 | `beta` | FIRST BETA — 40-issue hardening burn (DoD pre-flight + `plan sync-dod`, merge-wave lock + gated-HEAD, load-aware tests, claim-sources across all outputs), `tldrx learn` 8-chapter sandbox tutorial (cold-player QA), `tldrx ship` / `tldrx note` / `run gates set`, budget policies + dual-economy wiring, single integration branch for chained epics, epic worktrees live to run close, bilingual docs site |
 | 0.3.1 | 2026-08-31 | `alpha` | Unattended mode (gates_policy agent, review handshake, fixlist, decision cards, dual economy), 6 contact fixes from the first feature-scope runs, colored init, training repair round |
 | 0.3.0 | 2026-08-30 | `alpha` | expert training with provenance, auto gates with an undo, `tldrx status`, seed triage, the token economy (context ledger, `max_reads`, `cost`, `estimate`), `install --claude`, `interview`, the ticket mirror, `--help` with flags and exit codes |
 | 0.2.0 | 2026-08-29 | `alpha` | Build executor (worktree + branch per story, epic branches, DoD gate, reviewer), Watch cards, live dashboard |

package/dist/hooks/answer-capture.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   FactsStore
-} from "./chunk-ytvmc5ns.js";
+} from "./chunk-t1ywrfr4.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-s5qsb4k6.js";
+} from "./chunk-b8kxzna2.js";
 import {
   EventLog
-} from "./chunk-ybacnpxd.js";
-import"./chunk-9kkm6q0t.js";
+} from "./chunk-rz541e2b.js";
+import"./chunk-c6t5nx0r.js";
 import {
   MAX_FACT_CHARS,
   detectAnswered,
@@ -17,13 +17,13 @@ import {
   recordAnswer,
   replaceBlock,
   serializeQuestions
-} from "./chunk-3t91gvpp.js";
-import"./chunk-sznsenee.js";
+} from "./chunk-rpcxsqh3.js";
+import"./chunk-m3mewgnw.js";
 import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
   factsPath
-} from "./chunk-ztczwtj0.js";
+} from "./chunk-sq44k6g2.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync2 } from "fs";
@@ -68,7 +68,7 @@ function filePathOf(payload) {
 }
 
 // src/hooks/lib/workspace.ts
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 function locateWork(filePath) {
   if (filePath === "")
     return null;

package/dist/hooks/budget-gate.js

@@ -8,32 +8,37 @@ import {
   readPayload,
   runHook,
   toolInput
-} from "./chunk-3g61yg59.js";
-import"./chunk-s5qsb4k6.js";
+} from "./chunk-tzzwddct.js";
+import"./chunk-b8kxzna2.js";
 import {
   asRunBudget,
   currentActor,
   cursorStage,
   economyFor,
+  hostTokensIn,
+  isAttendedByHostView,
   isHostTokens,
   loadRunView,
   newestActiveRun,
   nowRfc3339,
   raiseCommand,
   remainingWork,
+  renderRunEconomies,
+  runSpend,
   shortBy,
   validateRunBudget,
-  wouldExceed
-} from "./chunk-zdxgragg.js";
+  wouldExceed,
+  wouldExceedHostTokens
+} from "./chunk-4cp363kv.js";
 import {
   EventLog
-} from "./chunk-ybacnpxd.js";
-import"./chunk-458wgg9j.js";
-import"./chunk-0z27twdk.js";
+} from "./chunk-rz541e2b.js";
+import"./chunk-9zsqxr6y.js";
+import"./chunk-phmdk72a.js";
 import {
   noteDeprecations
-} from "./chunk-3t91gvpp.js";
-import"./chunk-sznsenee.js";
+} from "./chunk-rpcxsqh3.js";
+import"./chunk-m3mewgnw.js";
 import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
@@ -41,7 +46,7 @@ import {
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-ztczwtj0.js";
+} from "./chunk-sq44k6g2.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";
@@ -107,6 +112,7 @@ await runHook("budget-gate", async () => {
   }
   if (budget === null)
     failClosed(command, `${view.dir}/budget.yml is missing or unreadable`);
+  const attended = isAttendedByHostView(view);
   const stage = cursorStage(view);
   const declared = stage?.budget_usd ?? stageBudgetFromLibrary(root, view.cursor.stage);
   const work = declared === null ? null : remainingWork({
@@ -116,18 +122,59 @@ await runHook("budget-gate", async () => {
     stageSpentUsd: stage?.cost_usd ?? 0,
     perAgentMaxUsd: budget.per_agent_max_usd,
     maxUsd: null,
-    economy: economyFor(budget, view.cursor.phase)
+    economy: economyFor(budget, view.cursor.phase),
+    attended
   });
   const estimate = estimateFor(command, work === null ? null : work.usd);
   if (estimate <= 0)
     return;
+  const economies = renderRunEconomies(view);
+  const spend = runSpend(view);
   if (isHostTokens(budget, view.cursor.phase)) {
-    process.stderr.write(`tldrx hook budget-gate: ${view.cursor.phase} is priced in \`host-tokens\` — ` + "no dollar ceiling to enforce here; `tldrx next` refuses a headless spawn on it.\n");
+    const tokens = wouldExceedHostTokens(budget, view.cursor.phase, hostTokensIn(view, view.cursor.phase));
+    const over = tokens !== null && tokens.over ? ` ${view.cursor.phase} is OVER its host-token ceiling: ` + `${String(tokens.spent)} declared of ${String(tokens.ceiling)} allowed.` : "";
+    const stops = tokens !== null && tokens.blocked && !attended;
+    if (over !== "") {
+      recordBudgetEvent(view, view.cursor.stage, stops ? "budget.blocked" : "budget.warned", {
+        phase: view.cursor.phase,
+        scope: tokens?.scope ?? "phase",
+        economy: "host-tokens",
+        attended_by: view.attended_by,
+        host_tokens: tokens?.spent ?? 0,
+        ceiling_tokens: tokens?.ceiling ?? 0,
+        estimate_usd: estimate,
+        metered_usd: spend.meteredUsd,
+        unmetered_tasks: spend.unmeteredTasks
+      });
+    }
+    if (stops && tokens !== null) {
+      deny(`[tldrx] budget-gate: refusing to start stage "${view.cursor.stage}" — phase ${view.cursor.phase} is ` + `priced in \`host-tokens\` and has declared ${String(tokens.spent)} of ${String(tokens.ceiling)} ` + "allowed. Raise that phase's ceiling in budget.yml (under this economy the number is a TOKEN " + "allowance), or set `on_host_tokens_exceed: warn` to go back to a note." + `${economies === null ? "" : `
+${economies}`}`);
+    }
+    process.stderr.write(`tldrx hook budget-gate: ${view.cursor.phase} is priced in \`host-tokens\` — ` + "no dollar ceiling to enforce here; `tldrx next` refuses a headless spawn on it." + over + `${economies === null ? "" : ` ${economies}`}
+`);
     return;
   }
   const decision = wouldExceed(budget, view.cursor.phase, estimate);
   if (!decision.blocked)
     return;
+  if (attended) {
+    recordBudgetEvent(view, view.cursor.stage, "budget.warned", {
+      phase: view.cursor.phase,
+      scope: decision.scope,
+      remaining_usd: decision.remaining,
+      ceiling_usd: decision.ceiling,
+      estimate_usd: decision.estimate,
+      economy: economyFor(budget, view.cursor.phase),
+      attended_by: view.attended_by,
+      metered_usd: spend.meteredUsd,
+      host_tokens: spend.hostTokens,
+      unmetered_tasks: spend.unmeteredTasks
+    });
+    process.stderr.write(`tldrx hook budget-gate: ${view.cursor.phase} has $${decision.remaining.toFixed(2)} left of ` + `$${decision.ceiling.toFixed(2)} and the stage estimate is $${estimate.toFixed(2)} — NOT refusing, ` + "because this run is attended_by: host and the framework spawns nothing on it." + `${economies === null ? "" : ` ${economies}`}
+`);
+    return;
+  }
   new EventLog(join2(view.dir, "events.jsonl")).tryAppend({
     ts: nowRfc3339(),
     run: view.run,
@@ -141,11 +188,28 @@ await runHook("budget-gate", async () => {
       remaining_usd: decision.remaining,
       ceiling_usd: decision.ceiling,
       estimate_usd: decision.estimate,
-      blocked_by: currentActor()
+      blocked_by: currentActor(),
+      economy: economyFor(budget, view.cursor.phase),
+      attended_by: view.attended_by,
+      metered_usd: spend.meteredUsd,
+      host_tokens: spend.hostTokens,
+      unmetered_tasks: spend.unmeteredTasks
     }
   });
-  deny(budgetGateDeny(view.cursor.stage, view.cursor.phase, decision.remaining, decision.ceiling, estimate, raiseCommand(view.run, view.cursor.phase, shortBy(estimate, decision.remaining))));
+  deny(budgetGateDeny(view.cursor.stage, view.cursor.phase, decision.remaining, decision.ceiling, estimate, raiseCommand(view.run, view.cursor.phase, shortBy(estimate, decision.remaining))) + (economies === null ? "" : `
+${economies}`));
 });
+function recordBudgetEvent(view, stage, type, payload) {
+  new EventLog(join2(view.dir, "events.jsonl")).tryAppend({
+    ts: nowRfc3339(),
+    run: view.run,
+    stage,
+    type,
+    actor: "hook:budget-gate",
+    cost_usd: 0,
+    payload
+  });
+}
 function estimateFor(command, stageBudget) {
   const flagged = Number(MAX_USD_RE.exec(command)?.[1] ?? MAX_BUDGET_RE.exec(command)?.[1] ?? NaN);
   if (/^tldrx run auto\b/.test(command)) {

package/dist/hooks/{chunk-zdxgragg.js → chunk-4cp363kv.js}

@@ -1,6 +1,6 @@
 import {
   parseHandoff
-} from "./chunk-458wgg9j.js";
+} from "./chunk-9zsqxr6y.js";
 import {
   MAX_PLAN_STORIES,
   MAX_STORIES_PER_WAVE,
@@ -11,10 +11,10 @@ import {
   requirePattern,
   requireStringList,
   requireVersion1
-} from "./chunk-0z27twdk.js";
+} from "./chunk-phmdk72a.js";
 import {
   classifySrc
-} from "./chunk-sznsenee.js";
+} from "./chunk-m3mewgnw.js";
 import {
   asDocument,
   isRecord,
@@ -31,7 +31,7 @@ import {
   PROJECT_FRAMEWORK_DIR,
   listRunDirs,
   parseYaml
-} from "./chunk-ztczwtj0.js";
+} from "./chunk-sq44k6g2.js";
 
 // src/hooks/lib/runFile.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -67,7 +67,8 @@ function loadRunView(runDir) {
             status: str(s?.status),
             expert: typeof s?.expert === "string" ? s.expert : null,
             budget_usd: typeof s?.budget_usd === "number" ? s.budget_usd : null,
-            cost_usd: typeof s?.cost_usd === "number" ? s.cost_usd : null
+            cost_usd: typeof s?.cost_usd === "number" ? s.cost_usd : null,
+            tasks: tasksOf(s?.tasks)
           });
         }
       }
@@ -81,10 +82,69 @@ function loadRunView(runDir) {
     scope: str(doc.scope),
     status: str(doc.status),
     updated_at: str(doc.updated_at),
+    attended_by: typeof doc.attended_by === "string" && doc.attended_by !== "" ? doc.attended_by : null,
     cursor,
     phases
   };
 }
+function tasksOf(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.map((task) => ({
+    cost_usd: typeof task?.cost_usd === "number" ? task.cost_usd : null,
+    metered: task?.metered !== false,
+    tokens: typeof task?.tokens === "number" ? task.tokens : null
+  }));
+}
+function isAttendedByHostView(view) {
+  return view.attended_by === "host";
+}
+function runSpend(view) {
+  let meteredUsd = 0;
+  let hostTokens = 0;
+  let unmeteredTasks = 0;
+  for (const phase of view.phases) {
+    for (const stage of phase.stages) {
+      for (const task of stage.tasks) {
+        if (task.cost_usd !== null)
+          meteredUsd += task.cost_usd;
+        if (!task.metered || task.cost_usd === null)
+          unmeteredTasks += 1;
+        if (task.tokens !== null)
+          hostTokens += task.tokens;
+      }
+    }
+  }
+  return { meteredUsd: Math.round(meteredUsd * 100) / 100, hostTokens, unmeteredTasks };
+}
+function hostTokensIn(view, phaseId) {
+  let tokens = 0;
+  for (const phase of view.phases) {
+    if (phaseId !== null && phase.id !== phaseId)
+      continue;
+    for (const stage of phase.stages) {
+      for (const task of stage.tasks) {
+        if (task.tokens !== null)
+          tokens += task.tokens;
+      }
+    }
+  }
+  return tokens;
+}
+function renderRunEconomies(view) {
+  const spend = runSpend(view);
+  const attended = isAttendedByHostView(view);
+  if (spend.hostTokens === 0 && spend.unmeteredTasks === 0 && !attended)
+    return null;
+  const parts = [`$${spend.meteredUsd.toFixed(2)} metered`];
+  if (spend.hostTokens > 0)
+    parts.push(`${String(spend.hostTokens)} host tokens`);
+  if (spend.unmeteredTasks > 0) {
+    parts.push(`${String(spend.unmeteredTasks)} unmetered turn${spend.unmeteredTasks === 1 ? "" : "s"}`);
+  }
+  const who = attended ? " (attended_by: host — the framework does not spawn on this run)" : "";
+  return `spend so far: ${parts.join(" + ")}${who}. ` + "The dollar figure is METERED spend only; host tokens are a different currency and are never converted.";
+}
 function isTerminal(status) {
   return TERMINAL_STATUSES.includes(status);
 }
@@ -126,6 +186,8 @@ function nowRfc3339() {
 
 // src/core/budget/RunBudget.ts
 var ON_EXCEED = ["block", "warn"];
+var ON_HOST_TOKENS_EXCEED = ["warn", "block"];
+var DEFAULT_ON_HOST_TOKENS_EXCEED = "warn";
 var ECONOMIES = ["metered-usd", "host-tokens"];
 var DEFAULT_ECONOMY = "metered-usd";
 var DEFAULT_WARN_AT_PCT = 80;
@@ -158,6 +220,9 @@ function validateRunBudget(input) {
   if (doc.economy !== undefined && doc.economy !== null) {
     requireEnum(doc.economy, ECONOMIES, "economy", issues);
   }
+  if (doc.on_host_tokens_exceed !== undefined && doc.on_host_tokens_exceed !== null) {
+    requireEnum(doc.on_host_tokens_exceed, ON_HOST_TOKENS_EXCEED, "on_host_tokens_exceed", issues);
+  }
   if (doc.warn_at_pct !== undefined) {
     requireNumber(doc.warn_at_pct, "warn_at_pct", issues);
     const pct = doc.warn_at_pct;
@@ -203,6 +268,7 @@ function asRunBudget(input) {
     warn_at_pct: doc.warn_at_pct ?? DEFAULT_WARN_AT_PCT,
     on_exceed: doc.on_exceed ?? "block",
     economy: doc.economy ?? DEFAULT_ECONOMY,
+    on_host_tokens_exceed: doc.on_host_tokens_exceed ?? DEFAULT_ON_HOST_TOKENS_EXCEED,
     phases: (doc.phases ?? []).map((phase) => ({
       id: phase.id,
       ceiling_usd: phase.ceiling_usd,
@@ -211,6 +277,16 @@ function asRunBudget(input) {
     }))
   };
 }
+function hostTokenCeiling(budget, phaseId) {
+  if (budget === null || !isHostTokens(budget, phaseId))
+    return null;
+  if (phaseId !== undefined && phaseId !== null) {
+    const phase = budget.phases.find((entry) => entry.id === phaseId);
+    if (phase !== undefined)
+      return phase.ceiling_usd;
+  }
+  return budget.ceiling_usd;
+}
 
 // src/core/budget/remainingWork.ts
 import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
@@ -326,6 +402,12 @@ var SKIPPED_DIRS = new Set([
   "test-results"
 ]);
 
+// src/core/plan/branchModel.ts
+var BRANCH_MODELS = ["per-epic", "integration"];
+function isBranchModelKind(value) {
+  return typeof value === "string" && BRANCH_MODELS.includes(value);
+}
+
 // src/core/experts/expertDocument.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
 import { join as join3 } from "node:path";
@@ -1082,6 +1164,8 @@ function round(n) {
 }
 
 // src/core/build/review.ts
+var VERDICT_WORDS = ["approve", "fixlist", "changes"];
+var VERDICT_ENUM = VERDICT_WORDS.join("|");
 var REVIEWER_FAILED = "the reviewer sub-agent failed";
 function looksLikeReviewerError(detail) {
   const text = detail.trim();
@@ -1111,6 +1195,7 @@ function staticOnly(input) {
     staticUsd: input.stageBudgetUsd,
     clamped: false,
     economy: input.economy ?? DEFAULT_ECONOMY,
+    attended: input.attended === true,
     stories: [],
     done: 0,
     total: 0,
@@ -1119,6 +1204,7 @@ function staticOnly(input) {
 }
 function measure(input) {
   const economy = input.economy ?? DEFAULT_ECONOMY;
+  const hostPaysDeveloper = economy === "host-tokens" || input.attended === true;
   const fallback = {
     basis: "static",
     usd: input.stageBudgetUsd,
@@ -1126,6 +1212,7 @@ function measure(input) {
     staticUsd: input.stageBudgetUsd,
     clamped: false,
     economy,
+    attended: input.attended === true,
     stories: [],
     done: 0,
     total: 0,
@@ -1157,7 +1244,7 @@ function measure(input) {
     if (attemptsLeft === 0)
       continue;
     const developerTurns = Math.max(attemptsLeft - (story.status === "review" ? 1 : 0), 0);
-    const developerCapUsd = economy === "host-tokens" ? 0 : caps.developer(story.id);
+    const developerCapUsd = hostPaysDeveloper ? 0 : caps.developer(story.id);
     const reviewerCapUsd = caps.reviewer(story.id);
     const usd = round2(developerCapUsd * developerTurns + reviewerCapUsd * attemptsLeft);
     if (usd <= 0 && developerTurns === 0 && attemptsLeft === 0)
@@ -1182,6 +1269,7 @@ function measure(input) {
     staticUsd: input.stageBudgetUsd,
     clamped,
     economy,
+    attended: input.attended === true,
     stories,
     done: progress.done,
     total: progress.total,
@@ -1314,6 +1402,20 @@ function wouldExceed(budget, phaseId, estimate) {
 function round3(n) {
   return Math.round(n * 1e6) / 1e6;
 }
+function wouldExceedHostTokens(budget, phaseId, spentTokens) {
+  const ceiling = hostTokenCeiling(budget, phaseId);
+  if (ceiling === null)
+    return null;
+  const phase = phaseId === null ? undefined : budget.phases.find((p) => p.id === phaseId);
+  const over = ceiling > 0 && spentTokens > ceiling;
+  return {
+    over,
+    blocked: over && budget.on_host_tokens_exceed === "block",
+    scope: phase === undefined ? "run" : "phase",
+    spent: spentTokens,
+    ceiling
+  };
+}
 
 // src/core/run/gatePolicy.ts
 var GATE_POLICIES = ["human", "auto", "agent"];
@@ -1450,6 +1552,12 @@ function validateRunFile(input) {
           requireString(branch, `build.epic_branch[${i}]`, issues);
         });
       }
+      if (doc.build.branch_model !== undefined && !isBranchModelKind(doc.build.branch_model)) {
+        issues.push({
+          path: "build.branch_model",
+          message: `expected one of ${BRANCH_MODELS.join(" | ")}`
+        });
+      }
     } else {
       issues.push({ path: "build", message: "expected a mapping" });
     }
@@ -1479,6 +1587,9 @@ function validateRunFile(input) {
   }
   if (doc.attended_by !== undefined)
     requireEnum(doc.attended_by, ATTENDED_BY, "attended_by", 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}` });
+  }
   if (!requireArray(doc.phases, "phases", issues))
     return result(issues, deprecations);
   const phases = doc.phases;
@@ -1652,4 +1763,4 @@ function shortBy(estimate, remaining) {
   return Math.max(0.01, Math.ceil((estimate - remaining) * 100) / 100);
 }
 
-export { loadRunView, cursorStage, openRunViews, newestActiveRun, currentActor, nowRfc3339, DEFAULT_ECONOMY, economyFor, isHostTokens, validateRunBudget, asRunBudget, expertsDir, loadExperts, readExpertDomain, pathsIntersect, parseEvidence, evidencePath, gateEvidencePath, stackExpertNames, remainingWork, wouldExceed, isTerminal2 as isTerminal, isFinished, isAttendedByHost, flatten, stageAt, deriveRunStatus, derivePhaseStatus, validateRunFile, asRunFile, raiseCommand, shortBy };
+export { loadRunView, isAttendedByHostView, runSpend, hostTokensIn, renderRunEconomies, cursorStage, openRunViews, newestActiveRun, currentActor, nowRfc3339, DEFAULT_ON_HOST_TOKENS_EXCEED, DEFAULT_ECONOMY, economyFor, isHostTokens, validateRunBudget, asRunBudget, expertsDir, loadExperts, readExpertDomain, pathsIntersect, parseEvidence, evidencePath, gateEvidencePath, stackExpertNames, remainingWork, wouldExceed, wouldExceedHostTokens, isTerminal2 as isTerminal, isFinished, isAttendedByHost, flatten, stageAt, deriveRunStatus, derivePhaseStatus, validateRunFile, asRunFile, raiseCommand, shortBy };

package/dist/hooks/{chunk-afamdvyn.js → chunk-7y2dq0pj.js}

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

package/dist/hooks/{chunk-458wgg9j.js → chunk-9zsqxr6y.js}

@@ -2,7 +2,7 @@ import {
   hasSrcMarker,
   parseSrcToken,
   resolveSrc
-} from "./chunk-sznsenee.js";
+} from "./chunk-m3mewgnw.js";
 
 // src/core/text/handoff.ts
 var HANDOFF_SECTIONS = ["Findings", "Decisions", "Unknowns", "Evidence ledger"];
@@ -61,6 +61,42 @@ function parseHandoff(text) {
   flush();
   return { sections, headings };
 }
+function parseItems(text) {
+  const items = [];
+  let section = "";
+  let pending = null;
+  const flush = () => {
+    if (pending === null)
+      return;
+    const joined = pending.parts.join(" ");
+    items.push({ line: pending.line, text: joined, section: pending.section, token: parseSrcToken(joined) });
+    pending = null;
+  };
+  const lines = text.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const heading = H2_RE.exec(line);
+    if (heading !== null && heading[1] !== undefined) {
+      flush();
+      section = heading[1];
+      continue;
+    }
+    const bullet = BULLET_RE.exec(line);
+    if (bullet !== null && bullet[1] !== undefined) {
+      flush();
+      pending = { line: i + 1, parts: [bullet[1]], section };
+      continue;
+    }
+    if (pending !== null && CONTINUATION_RE.test(line)) {
+      pending.parts.push(line.trim());
+      continue;
+    }
+    flush();
+  }
+  flush();
+  return items;
+}
 function isHandoff(text) {
   return missingSections(parseHandoff(text)).length === 0;
 }
@@ -141,5 +177,37 @@ function validateHandoff(text, ctx) {
     bulletCount: report.bulletCount
   };
 }
+function validateCitations(text, ctx) {
+  const malformed = [];
+  const unresolved = [];
+  const unverified = [];
+  let cited = 0;
+  for (const item of parseItems(text)) {
+    if (item.token === null) {
+      if (!hasSrcMarker(item.text))
+        continue;
+      cited++;
+      malformed.push({
+        line: item.line,
+        message: "malformed citation — the `[src: …]` token must be the last thing on the line " + "(closing quotes, brackets and a final `.` are allowed after it, words are not)"
+      });
+      continue;
+    }
+    cited++;
+    for (const error of item.token.errors) {
+      unresolved.push({ line: item.line, message: `[src: ${error.raw}] — ${error.message}` });
+    }
+    const claim = item.text.replace(item.token.raw, " ").trim();
+    for (const ref of item.token.refs) {
+      const resolution = resolveSrc(ref, ctx, item.section, claim);
+      const issue = { line: item.line, message: `[src: ${ref.raw}] — ${resolution.message ?? "unresolvable"}` };
+      if (resolution.outcome === "refused")
+        unresolved.push(issue);
+      else if (resolution.outcome === "unverified")
+        unverified.push(issue);
+    }
+  }
+  return { malformed, unresolved, unverified, cited };
+}
 
-export { parseHandoff, isHandoff, validateHandoff };
+export { parseHandoff, isHandoff, validateHandoff, validateCitations };