tldr-experts 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,6 +1,86 @@
 # Changelog
 
 
+## 0.11.1 — 2026-09-08
+
+### Changed
+
+- **The mandate now tells the driver what to READ, because the host's own context was the
+  bill.** Measured over one week of host sessions on three real workspaces: ~$8.5k at list,
+  68 % of it Opus — and the work was not what cost it. Per-story time was a 0.6-1.35 h
+  median; the spend was 600-800-turn host sessions re-reading their whole context every
+  turn, one workspace alone at 2.5B cache-read tokens. `--tldr` already trims what the host
+  WRITES and what a sub-agent DELIVERS, and nothing anywhere told the host what to read
+  back. One bullet in the evidence discipline now does, in all four modes: a sub-agent's
+  outcome comes from its `result.json` and the ledger, never its transcript; each is briefed
+  to report its TURN in ten lines (a handoff is not a turn report — that one is a gate input
+  with its own contract, and trimming it costs the gate); and a cited file is re-opened to
+  VERIFY it at a gate, never re-read for a claim already made. It is paid for rather than
+  appended — the line budgets did not move (`MANDATE_MAX_LINES` 140, `MANDATE_TLDR_MAX_LINES`
+  165, unattended still exactly at both) because the negative-case and contradiction bullets
+  each lost a line of wrapping to the same meaning and the unattended gate's interrupt
+  paragraph lost the clause that restated "## Do not stop".
+
+### Added
+
+- **A run can now tell a person it needs them, without the framework naming a chat tool.**
+  `tldrx run auto` announced an open question or a gate by exiting `4` and printing a
+  decision card to stdout, and stdout is in a terminal nobody is watching — which is why
+  every run in the week of 2026-09-07 was driven in host mode instead, trading a metered
+  budget, an enforced model and parallel stories for a notification. `.tldrx/workspace.yml`
+  now takes one optional `notify:` block — a `command`, an optional `events:` list, an
+  optional `timeout_s` — and the loop hands that command one `version: 1` JSON object on
+  **stdin** at each moment a person is needed: the open question with its options, its
+  recommendation and the literal `tldrx answer <Qid> "…" --run <id>` line; a gate with the
+  literal approve line; a finished or failed run with its exit code and what that code's
+  family means; a budget warning with both numbers. The command is held to §2.1's rule
+  exactly — split to argv and run directly, never through a shell, a bare metacharacter
+  refused rather than shelled — and the payload never touches the command line, so a
+  question's own title cannot become shell syntax. Which service reaches the owner stays the
+  owner's decision: a built-in integration would be this framework deciding whose product it
+  depends on, which is the same reasoning the drive mandate has always given. `tldrx init`
+  writes the block commented out with a line saying what it is for, the way `test_fast` is
+  written — who gets woken up is not a thing to detect. Schema and payload: spec §2.18.
+  (#180)
+- **A failing notifier is written down, never a refusal.** A command that will not split, a
+  binary that is not there, a non-zero exit, a hang — each becomes a `notify.failed` event
+  carrying the reason, and the run keeps the exit code it already had; a delivered one is
+  `notify.sent` with the kind, the exit code and the duration. Both are `cost_usd: 0` and
+  both join the closed `EVENT_TYPES` enum. "The owner was not told, and here is why" is a
+  fact about the run; "the chat tool was down, so the run failed" would make a side channel
+  load-bearing. (#180)
+- **`tldrx run auto --notify-every <duration>`** sends the declared hook a periodic `status`
+  payload carrying what `tldrx run status` prints. It fires from a timer rather than between
+  iterations on purpose: the period when somebody most wants to know a run is alive is the
+  twenty minutes it is inside one stage. Off by default. Over a run that is PARKED it
+  reminds rather than reassures — the summary names the open questions, `command` is the
+  literal `tldrx answer` line and `detail.waiting_on` carries the ids. A heartbeat that went
+  on saying "nothing is waiting on you" while the run sat on somebody's answer was
+  reproduced in review with both flags on, and it is worse than silence, because a heartbeat
+  is believed. Parked-ness comes from the same predicate `--wait-answers` polls and `next`
+  parks on, never a second opinion. (#180)
+- **`tldrx run auto --wait-answers <duration>`** polls the run's question files instead of
+  exiting `4` the moment a stage parks, and resumes if the question is answered — by a
+  person, or by whatever the notify hook reached — then exits `4` with the same lines it
+  always did, after one `question.timeout` notification, when the wait lapses. Nothing is
+  spent while it polls, and the loop never answers its own question: the answer is an
+  ordinary `tldrx answer`. Both flags take `30s`, `10m`, `2h` or a bare number of seconds
+  through one parser, and refuse anything else by name at exit `1`. Without either flag,
+  behaviour is unchanged for every existing user — a question or a gate still exits `4`, the
+  hook has simply already fired with the answer command in it. (#180)
+- **The docs site now explains how to OPERATE a run unattended, not just what the flags
+  are.** The notify hook shipped with its schema in the spec and a paragraph in the driving
+  guide, and neither answers the question somebody actually has at 11pm: what do I write, and
+  what do I check when nothing arrives. A new guide page (EN + ES, in both sidebars) walks the
+  whole loop — host mode versus the engine with the honest trade-off, the `notify:` block and
+  its argv rule, the nine top-level payload keys with `question.raised` and `status` shown in
+  full and a per-kind table of the other six, a dependency-free ~30-line Node adapter you can
+  paste, `--notify-every` / `--wait-answers` with what exit `4` means when a wait lapses, a
+  first-run checklist that dry-runs the adapter on a hand-made payload before any run depends
+  on it, and troubleshooting for the four ways it silently does nothing. It names no
+  messaging service and it is not going to: the adapter is the reader's, and the page says
+  why in the same words the drive mandate does. (#180)
+
 ## 0.11.0 — 2026-09-08
 
 ### Fixed

package/README.md

@@ -316,6 +316,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 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 |
 | 0.9.2 | 2026-09-07 | `beta` | the Build executor decomposed: 4,351 lines became an orchestrator plus eight modules under src/core/build/ (review ledger and phase cost, money caps, the DoD runner with its preflight cache, worktrees and epic-branch claims, the reviewer bundle and review round) — a pure refactor proven byte-for-byte by a golden guard over prompts, ordered events, run.yml rows and exit codes across three scenarios; no behaviour changed, every remaining hardening fix now lands in a file a reviewer can hold |

package/dist/hooks/answer-capture.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-bk7rkdzw.js";
+} from "./chunk-qn8qnrgw.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-kqvbzyc0.js";
+} from "./chunk-gj1ckg0c.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-6c84kjd7.js";
+} from "./chunk-8d0t69pk.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-9v45j71e.js";
-import"./chunk-tg7ppsxr.js";
+} from "./chunk-rw3n3z6t.js";
+import"./chunk-b26rvgjd.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -24,7 +24,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-wzzywf6c.js";
+} from "./chunk-h23db062.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -32,7 +32,7 @@ import {
   commandProbeIssues,
   factsPath,
   parseYaml
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.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-stw0dxna.js";
+} from "./chunk-zs84arc1.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-6ws778wq.js";
-import"./chunk-6c84kjd7.js";
+} from "./chunk-hx0jgrmh.js";
+import"./chunk-8d0t69pk.js";
 import {
   asRunBudget,
   currentActor,
@@ -29,20 +29,20 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-1c43349s.js";
+} from "./chunk-jmypgf6s.js";
 import {
   EventLog
-} from "./chunk-9v45j71e.js";
+} from "./chunk-rw3n3z6t.js";
 import {
   noteDeprecations
-} from "./chunk-wzzywf6c.js";
+} from "./chunk-h23db062.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

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

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

package/dist/hooks/{chunk-tg7ppsxr.js → chunk-b26rvgjd.js}

@@ -1,7 +1,7 @@
 import {
   PROJECT_FRAMEWORK_DIR,
   PROJECT_WORK_DIR
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/core/lock/workspaceLock.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, rmSync as rmSync2, writeSync, closeSync } from "node:fs";

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

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

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

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

package/dist/hooks/{chunk-6ws778wq.js → chunk-hx0jgrmh.js}

@@ -1,7 +1,7 @@
 import {
   parseHookInput,
   readStdin
-} from "./chunk-6c84kjd7.js";
+} from "./chunk-8d0t69pk.js";
 
 // src/hooks/lib/decide.ts
 function deny(reason) {

package/dist/hooks/{chunk-1c43349s.js → chunk-jmypgf6s.js}

@@ -23,7 +23,7 @@ import {
   requireVersion,
   requireVersion1,
   result
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/hooks/lib/runFile.ts
 import { existsSync, readFileSync } from "node:fs";

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

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

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

@@ -10,7 +10,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/core/events/EventLog.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -58,6 +58,8 @@ var EVENT_TYPES = [
   "fact.superseded",
   "fact.conflict_raised",
   "doc.superseded",
+  "notify.sent",
+  "notify.failed",
   "map.refreshed",
   "ticket.synced",
   "error"

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

@@ -8,7 +8,7 @@ import {
   nowRfc3339,
   openRunViews,
   validateRunBudget
-} from "./chunk-1c43349s.js";
+} from "./chunk-jmypgf6s.js";
 import {
   EventLog,
   asRunFile,
@@ -20,7 +20,7 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-9v45j71e.js";
+} from "./chunk-rw3n3z6t.js";
 import {
   backupPathFor,
   isAlive,
@@ -29,18 +29,18 @@ import {
   workspaceRootOfRunDir,
   writeAtomic,
   yamlScalar
-} from "./chunk-tg7ppsxr.js";
+} from "./chunk-b26rvgjd.js";
 import {
   isAdvisory,
   noteDeprecations,
   openBlocks,
   parseQuestions
-} from "./chunk-wzzywf6c.js";
+} from "./chunk-h23db062.js";
 import {
   listRunDirs,
   parseYaml,
   parseYamlRepairing
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/core/statusline/runSnapshot.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";

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

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

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

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

package/dist/hooks/claim-sources.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   wouldBeContent
-} from "./chunk-ecwes7kd.js";
+} from "./chunk-z6n9551r.js";
 import {
   claimSourcesDeny,
   claimSourcesEmptySectionDeny,
   claimSourcesMalformedDeny,
   claimSourcesUnresolvedDeny
-} from "./chunk-stw0dxna.js";
+} from "./chunk-zs84arc1.js";
 import {
   allow,
   deny,
@@ -16,8 +16,8 @@ import {
   postContext,
   readPayload,
   runHook
-} from "./chunk-6ws778wq.js";
-import"./chunk-6c84kjd7.js";
+} from "./chunk-hx0jgrmh.js";
+import"./chunk-8d0t69pk.js";
 import {
   isHandoff,
   loadWorkspace,
@@ -25,7 +25,7 @@ import {
   toSrcContext,
   validateCitations,
   validateHandoff
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/hooks/claim-sources.ts
 await runHook("claim-sources", async () => {

package/dist/hooks/dod-gate.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   wouldBeContent
-} from "./chunk-ecwes7kd.js";
+} from "./chunk-z6n9551r.js";
 import {
   dodGateDeny,
   dodGateInternalErrorDeny,
   dodGateMissingBlockDeny,
   dodGateRefusedCommandDeny
-} from "./chunk-stw0dxna.js";
+} from "./chunk-zs84arc1.js";
 import {
   allow,
   deny,
@@ -15,8 +15,8 @@ import {
   filePathOf,
   isWriteOrEdit,
   readPayload
-} from "./chunk-6ws778wq.js";
-import"./chunk-6c84kjd7.js";
+} from "./chunk-hx0jgrmh.js";
+import"./chunk-8d0t69pk.js";
 import {
   DodCommandRefused,
   loadWorkspace,
@@ -24,7 +24,7 @@ import {
   readStory,
   repoPath,
   runDodCommand
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/hooks/dod-gate.ts
 import { basename, join } from "node:path";

package/dist/hooks/no-reask.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   wouldBeContent
-} from "./chunk-ecwes7kd.js";
+} from "./chunk-z6n9551r.js";
 import {
   noReAskDeny
-} from "./chunk-stw0dxna.js";
+} from "./chunk-zs84arc1.js";
 import {
   FactsStore
-} from "./chunk-kqvbzyc0.js";
+} from "./chunk-gj1ckg0c.js";
 import {
   allow,
   deny,
@@ -15,17 +15,17 @@ import {
   isWriteOrEdit,
   readPayload,
   runHook
-} from "./chunk-6ws778wq.js";
-import"./chunk-6c84kjd7.js";
-import"./chunk-tg7ppsxr.js";
+} from "./chunk-hx0jgrmh.js";
+import"./chunk-8d0t69pk.js";
+import"./chunk-b26rvgjd.js";
 import {
   openBlocks,
   parseQuestions
-} from "./chunk-wzzywf6c.js";
+} from "./chunk-h23db062.js";
 import {
   factsPath,
   locateWork
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/hooks/no-reask.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/session-start.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   questionsCard
-} from "./chunk-bk7rkdzw.js";
-import"./chunk-kqvbzyc0.js";
+} from "./chunk-qn8qnrgw.js";
+import"./chunk-gj1ckg0c.js";
 import {
   allow,
   readPayload,
   runHook,
   sessionContext
-} from "./chunk-6ws778wq.js";
-import"./chunk-6c84kjd7.js";
+} from "./chunk-hx0jgrmh.js";
+import"./chunk-8d0t69pk.js";
 import {
   RunStore,
   closedByMachine,
@@ -18,7 +18,7 @@ import {
   openQuestions,
   runSnapshot,
   whatIsWaiting
-} from "./chunk-d20x2aew.js";
+} from "./chunk-wbkwjpq2.js";
 import {
   expertsDir,
   loadExperts,
@@ -26,13 +26,13 @@ import {
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-1c43349s.js";
-import"./chunk-9v45j71e.js";
-import"./chunk-tg7ppsxr.js";
+} from "./chunk-jmypgf6s.js";
+import"./chunk-rw3n3z6t.js";
+import"./chunk-b26rvgjd.js";
 import {
   openBlocks,
   parseQuestions
-} from "./chunk-wzzywf6c.js";
+} from "./chunk-h23db062.js";
 import {
   PROJECT_FRAMEWORK_DIR,
   PROJECT_WORK_DIR,
@@ -42,7 +42,7 @@ import {
   isRecord,
   listRunDirs,
   parseYaml
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/core/status/PendingItem.ts
 function isPending(item) {

package/dist/hooks/statusline.js

@@ -2,15 +2,15 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-d20x2aew.js";
-import"./chunk-1c43349s.js";
-import"./chunk-9v45j71e.js";
-import"./chunk-tg7ppsxr.js";
-import"./chunk-wzzywf6c.js";
+} from "./chunk-wbkwjpq2.js";
+import"./chunk-jmypgf6s.js";
+import"./chunk-rw3n3z6t.js";
+import"./chunk-b26rvgjd.js";
+import"./chunk-h23db062.js";
 import {
   findWorkspaceRoot,
   runtime
-} from "./chunk-r1efatxk.js";
+} from "./chunk-5hyd1rk1.js";
 
 // src/core/statusline/renderStatusLine.ts
 var NO_SESSION_DATA = "[tldrx] no session data";