tldr-experts 0.3.1 → 0.5.0

package/README.md

@@ -1,8 +1,8 @@
 # tldr-experts
 
-[![npm](https://img.shields.io/npm/v/tldr-experts?label=npm%20tldr-experts)](https://www.npmjs.com/package/tldr-experts) [![ci](https://github.com/ederwii/tldr-experts/actions/workflows/ci.yml/badge.svg)](https://github.com/ederwii/tldr-experts/actions/workflows/ci.yml) ![status](https://img.shields.io/badge/status-alpha-orange)
+[![npm](https://img.shields.io/npm/v/tldr-experts?label=npm%20tldr-experts)](https://www.npmjs.com/package/tldr-experts) [![ci](https://github.com/ederwii/tldr-experts/actions/workflows/ci.yml/badge.svg)](https://github.com/ederwii/tldr-experts/actions/workflows/ci.yml) ![status](https://img.shields.io/badge/status-beta-blue)
 
-**A lightweight, file-based AI development workflow.** Open source, tool-agnostic in design, piloted on Claude Code. **Alpha:** every command is implemented and verified by running it; interfaces may change without notice, and `tldrx --help` is the authoritative surface.
+**An evidence-first, file-based AI development framework: five stages, a gate on every one, and every claim cited or refused.** Open source, tool-agnostic in design, piloted on Claude Code. **Beta:** every command is implemented and verified by running it, the `version: 1` file formats only grow from here, and `tldrx --help` is the authoritative command surface.
 
 One loop — *Investigate → Handoff → Interview → Gate* — five phases, **what · how · plan · build ·
 watch**, one stage per command, each stopping at a gate you own; the files ARE the state, the
@@ -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,16 @@ tldrx init                # detect repos, map the code, write .tldrx/, ask only
 tldrx install --claude    # write the skill, hooks and status line into ./.claude/
 ```
 
+Later: **`tldrx update`** pulls the newest published version and prints the CHANGELOG between the
+one you had and the one you now have. Any command will tell you, in one line, when there is a newer
+one — off the hot path, cached for a day, silent when it cannot reach the registry, and never in
+`--json` output or during a hook. Turn it off with `TLDRX_UPDATE_CHECK=off`.
+
+**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 +45,79 @@ 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 — and the prompt now ships with the package:
+
+```bash
+tldrx drive --unattended        # print the mandate; paste it into the session that drives the run
+tldrx drive --attended          # the same disciplines, but every gate stays yours to sign
+```
+
+`tldrx drive` needs no workspace, opens no run and writes nothing: it prints the discipline the
+first real runs were driven by — the three-role protocol (developer → a **fresh** adversarial
+reviewer, never the author → the host verifying both in the code, not in their reports), evidence
+labelled `measured` / `inferred` / `assumed`, product questions parked rather than decided, the
+reviewer calibrated to the story's stakes, and the cost declared once. The two modes differ in
+exactly two places: who drives the turns, and who may close a gate.
+
+The rest of this section is what that mandate says, in the shape you would type it by hand.
+
+```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`.
@@ -78,7 +157,14 @@ Those are the shipped defaults, and every scope keeps at least one human gate. O
 signs something it should not have, `tldrx reject --stage <phase>/<stage> --note "…"` revokes it, moves
 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.
+`tldrx story reopen <id> --note "…"` gives that one story another run of attempts and nothing else;
+for one named defect in a story already `done`, `--for-fix` opens a fix round instead — no attempt
+consumed, the same DoD and the same reviewer, one open round at a time.
+To move who may close a gate after `run new` froze it, `tldrx run gates set <stage>:<policy> --note "…"`
+is the only sanctioned way, and it records the old→new value with your reason.
+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
@@ -127,7 +213,7 @@ context 83.7 KB of 160.0 KB (~23.8k tok, 12% of sonnet's ~200.0k window)
 ```
 
 Over `prompt_max_bytes` the stage is **refused** (exit 2) before anything spawns; `max_reads` stops
-the sub-agent at a read ceiling; `--effort` changes what a turn costs. What `--max-budget-usd` does is
+the sub-agent at a read ceiling; `--effort` changes what a turn costs. What `--max-usd` does is
 end a run *after* the turn it is already in — measured, one turn spent **$5.15** against a **$1.50**
 ceiling — so size the prompt for the money you are willing to lose. Afterwards `tldrx cost [--all]` adds up what was actually charged, per attempt, per stage, per
 run, read off `agent.result` events and nothing else. Retries are never merged — a retry is
@@ -137,22 +223,40 @@ Details: [`docs/guide/06-budgets-and-cost.md`](docs/guide/06-budgets-and-cost.md
 
 ## Several runs
 
-With several runs open and no id, every run-targeting command **refuses rather than guessing**,
-exits `2`, and lists them — `tldrx next: 3 runs are open — pass one:`. That means "you left off
-the id", not "it broke". Pass a positional `<run>` on `next`, `run status`, `cost`, `replay` and
-`retro`; `--run <id>` on the rest. `tldrx run status` with several open lists them all, exit `0`.
+With several runs open and no id, a run-targeting command **refuses rather than guessing** and
+lists them — `tldrx next: 3 runs are open — pass one:`. That means "you left off the id", not "it
+broke". Two of them refuse differently and it is worth knowing which: `tldrx run status` is not a
+refusal at all — it lists every open run and exits `0`, and it is the screen you read to find the
+id the others want — and `tldrx cost` refuses at exit `1`, not `2`.
+
+Most run-targeting commands take the id either way, a positional `<run>` or `--run <id>`: `next`,
+`cost`, `note`, `gate template`, `questions`, `budget show`, `ship`, `tickets`, and `run attend` ·
+`status` · `estimate` · `auto` · `unlock` · `cancel`. `replay` and `retro` take the positional only
+— `--run` there is an unknown flag. `approve`, `reject`, `answer`, `interview`, `plan`,
+`story reopen`, `watch` and `run gates set` take `--run <id>` only.
+
+`tldrx retro --all` goes the other way: it reads **every** run in the workspace and prints one
+table of what keeps catching you — finding class × count × how many runs × one example with its
+citation — mined from the review logs, the fix lists, `retro.md` and the `story.reopened` reasons.
+Strictly read-only: it writes nothing, anywhere.
 
 ## What to commit
 
 **Both `.tldrx/` and `tldrx-work/`.** The files are the state — the map, the facts, the questions and
 their answers, `run.yml`, `budget.yml`, `events.jsonl`, the handoffs, the plan — so a teammate who clones
-the repo gets the run. The block `tldrx init` appends to `.gitignore` excludes five paths and nothing
-else, because those five are machine-local or regenerated: `.tldrx/graphify-out/`, `.tldrx/cache/`,
-`.tldrx/worktrees/`, `tldrx-work/*/.lock`, `tldrx-work/*/.agent/`.
+the repo gets the run. The block `tldrx init` appends to `.gitignore` excludes eight paths and nothing
+else, because those eight are machine-local, regenerated, or a backup git already holds the history
+of: `.tldrx/graphify-out/`, `.tldrx/cache/`, `.tldrx/worktrees/`, `tldrx-work/*/.lock`,
+`tldrx-work/*/.agent/`, `tldrx-work/*/*.bak`, `.tldrx/memory/*.bak` and
+`.claude/settings.json.bak-tldrx-*`.
 
 ## 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) ·
@@ -166,6 +270,12 @@ Design docs: [`docs/concept.md`](docs/concept.md) (why) · [`docs/spec.md`](docs
 open decisions) · [`docs/ROADMAP.md`](docs/ROADMAP.md) (next) · [`CHANGELOG.md`](CHANGELOG.md) (shipped) ·
 [`docs/dashboard-model.md`](docs/dashboard-model.md).
 
+Contributing: **[`CONTRIBUTING.md`](CONTRIBUTING.md)** — the loop a change goes through, the four gates
+and what CI actually runs, the red-first test rules, and
+[how to contribute a model-provider config](CONTRIBUTING.md#contributing-a-model-provider-config)
+(the `TLDRX_CLAUDE_BIN` seam, the `stream-json` transcript contract, and what a generic provider
+would have to supply).
+
 ## Releases and status tags
 
 Install name is **`tldr-experts`**; it installs two commands, **`tldrx`** (short) and `tldr-experts` (same binary).
@@ -175,6 +285,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.5.0 | 2026-09-02 | `beta` | `tldrx drive` and its own preflight, `watch check` / `watch arm`, `questions cards`, `plan schema`, `retro --all` (with its findings fed back into every reviewer prompt) and `story reopen --for-fix`; `tldrx update` plus a cached newer-version notice; the dashboard reads `budget.yml` and `events.jsonl` — operator notes, reopens and retries, the per-phase budget panel, and a host-attended run metered in tokens against `ceiling_host_tokens`; a rejected review envelope no longer burns a story attempt; `ship` opens one PR per repo; merge-wave lock + ref guard; five golden-transcript evals, one per stage; `CONTRIBUTING.md` and a model-provider contract |
+| 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 |
@@ -188,6 +300,10 @@ path documented; `stable` = 1.0, semver from here on. The badge above shows the
 
 ## Releasing
 
-**One command: `scripts/release.sh X.Y.Z --tag alpha`.** It is the only sanctioned path — a Claude Code hook denies hand-made `git tag` / `npm publish`, and `publish.yml` re-runs the same checks. Checklist and judgement calls: `docs/RELEASING.md`.
+**One command: `scripts/release.sh X.Y.Z --tag beta`.** The tag is not optional in practice: omit
+`--tag` and the script writes `alpha`, which is no longer this project's status. It is the only
+sanctioned path — a Claude Code hook denies hand-made `git tag` / `npm publish`, and `publish.yml`
+runs `release-check.sh --ci` (the file checks only) plus its own typecheck, tests and build.
+Checklist and judgement calls: `docs/RELEASING.md`.
 
 MIT, © 2026 Alan Martinez — a placeholder made while scaffolding; change it freely before anything ships.

package/dist/hooks/answer-capture.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   FactsStore
-} from "./chunk-ytvmc5ns.js";
+} from "./chunk-889tybxc.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-s5qsb4k6.js";
+} from "./chunk-v1c1hpb8.js";
 import {
   EventLog
-} from "./chunk-ybacnpxd.js";
-import"./chunk-9kkm6q0t.js";
+} from "./chunk-sae7sqty.js";
+import"./chunk-qw73rdbr.js";
 import {
   MAX_FACT_CHARS,
   detectAnswered,
@@ -17,13 +17,12 @@ import {
   recordAnswer,
   replaceBlock,
   serializeQuestions
-} from "./chunk-3t91gvpp.js";
-import"./chunk-sznsenee.js";
+} from "./chunk-nadqsr3w.js";
 import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
   factsPath
-} from "./chunk-ztczwtj0.js";
+} from "./chunk-a6rpj2cp.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync2 } from "fs";
@@ -68,7 +67,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

@@ -1,47 +1,51 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-9gb21660.js";
+} from "./chunk-a5dq2dcp.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-3g61yg59.js";
-import"./chunk-s5qsb4k6.js";
+} from "./chunk-bvm6vjrt.js";
+import"./chunk-v1c1hpb8.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-14zn51kh.js";
 import {
   EventLog
-} from "./chunk-ybacnpxd.js";
-import"./chunk-458wgg9j.js";
-import"./chunk-0z27twdk.js";
+} from "./chunk-sae7sqty.js";
+import"./chunk-hcrbr430.js";
 import {
   noteDeprecations
-} from "./chunk-3t91gvpp.js";
-import"./chunk-sznsenee.js";
+} from "./chunk-nadqsr3w.js";
 import"./chunk-39zh2e44.js";
+import"./chunk-q8d3sff9.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-ztczwtj0.js";
+} from "./chunk-a6rpj2cp.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";
@@ -69,7 +73,9 @@ function loadRunBudget(runDir) {
 var SPAWN_RE = /^(claude -p|tldrx next|tldrx run auto|tldrx expert train|tldrx seed triage)\b/;
 var RUN_ARG_RE = /--run[= ]([\w.-]+)/;
 var DEFAULT_TRAIN_USD = 2;
+var DEFAULT_FULL_TRAIN_USD = 3;
 var DEFAULT_TRIAGE_USD = 1;
+var FULL_MODE_RE = /--mode[= ]full\b/;
 var MAX_USD_RE = /--max-usd[= ]([0-9]+(?:\.[0-9]+)?)/;
 var MAX_BUDGET_RE = /--max-budget-usd[= ]([0-9]+(?:\.[0-9]+)?)/;
 await runHook("budget-gate", async () => {
@@ -107,6 +113,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 +123,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,18 +189,37 @@ 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)) {
     return Number.isFinite(flagged) ? flagged : stageBudget ?? 0;
   }
   if (/^tldrx expert train\b/.test(command)) {
-    return Number.isFinite(flagged) ? flagged : DEFAULT_TRAIN_USD;
+    if (Number.isFinite(flagged))
+      return flagged;
+    return FULL_MODE_RE.test(command) ? DEFAULT_FULL_TRAIN_USD : DEFAULT_TRAIN_USD;
   }
   if (/^tldrx seed triage\b/.test(command)) {
     return Number.isFinite(flagged) ? flagged : DEFAULT_TRIAGE_USD;