tldr-experts 0.14.2 → 0.14.3

package/CHANGELOG.md

@@ -1,6 +1,117 @@
 # Changelog
 
 
+## 0.14.3 — 2026-09-10
+
+### Changed
+
+- **A Build no longer stops because somebody else's work is uncommitted in the checkout
+  (#164).** The dirty-tree guard used to count every `git status --porcelain` entry and refuse,
+  and its only exits were "commit it" or "stash it" — neither of which an agent may take with
+  another person's files. Measured twice on two consecutive days on a Next.js workspace: 14
+  uncommitted paths, 13 untracked, none of them the run's, and nine stories waited three hours
+  for a human to grant one `git stash` at 4 a.m. Measured again across three real workspaces on
+  0.14.2: every first engine-driven run reaching Build stopped at `04-build`, over seed docs, a
+  data export and one untracked note. The dirt is now CLASSIFIED, and only one verdict still
+  refuses. `own` — anything under this workspace's own `tldrx-work/` or `.tldrx/` — is not dirt,
+  as before. `overlapping` — a dirty path inside a pending story's `touches:`, a submodule, or a
+  directory of the operator's that merely looks like tldrx state — refuses exactly as it did,
+  and names which path and why. Everything else is `foreign`: the engine sets it aside with a
+  pathspec-limited `git stash push` before it cuts the epic branch, records
+  `worktree.foreign_work_aside`, and pops it back when the stage ends, recording
+  `worktree.foreign_work_restored` — on every exit path, success or failure. A repo in the
+  middle of a merge, rebase, cherry-pick or bisect refuses outright and is never stashed into:
+  that state has no clean undo. Nothing is ever deleted and nothing is ever force-popped; a pop
+  git refuses is `restored: false` with the paths and the literal command, said as the stage's
+  LAST line, carried into the handoff's `## Unknowns` (and so into a PR body) and into the
+  `stage.done` / `run.finished` / `run.failed` notification's own summary — no new notify kind.
+  The run's exit code does not move for it, because that code answers for the run's work and not
+  for the operator's tree.
+
+  **The stash is the LAST step before anything is cut**, and every exit from the Build executor
+  — a refusal, a failure, a green stage — gives it back before it returns. An earlier draft took
+  the stash at the first door, so the foreign-epic refusal and the base pre-flight could both
+  refuse with the operator's files already moved, through a return path that neither restored
+  them nor said they had gone: reproduced in review as exit 2, a stash on the list, the file
+  missing, nothing printed, and a re-run that refused forever.
+- **The restore reinstates the INDEX, not just the files (#164).** `git stash pop --index`, so a
+  path staged at one version and modified further in the worktree comes back both staged and
+  modified — the shape one of the three measured workspaces actually had (a script and a
+  `package.json` line staged in a sub-repo). Measured: a plain pop left `git show :f.txt` reading
+  the commit instead of what was staged. When `--index` itself refuses, the fallback is a plain
+  pop and the record says so — `index_restored: false` on the event and a sentence saying those
+  paths are back unstaged. `--keep-index` is deliberately not used on the push side: measured, it
+  leaves the staged content in the working tree, which is the dirt this path exists to remove.
+
+### Fixed
+
+- **The dashboard's live tests wait on the machine's clock, not a literal — the flake that
+  blocked four merges in two days (#193).** `test/dashboard-live.test.ts` and
+  `test/dashboard-server.test.ts` both call `setDefaultTimeout(spawnTestTimeout())`, so the
+  per-test BUDGET already scaled with load; every deadline that actually decided a result was
+  a number typed inside the assertion (`sse.next("reload", 5_000)`, `Date.now() + 2_000`), and
+  the load factor could never reach it. Each of those waits is an `fs.watch` notification
+  racing a stopwatch, so on a busy box a different SSE test reddened every time — measured
+  2026-09-09 under `load averages: 65–107` on 14 cores, five consecutive runs of the two files
+  went red 3 times, at 5084.27 / 5108.01 / 5256.49 ms against the 5000 and 2002.30 / 2002.55 /
+  2005.47 ms against the 2000. Not one failed on CONTENT: they timed out. The deadlines now go
+  through one helper, `eventWaitMs()` in `test/fixtures/machineLoad.ts`, which is
+  `spawnTestTimeout` with a 15 s base rather than a second scaler — the same derivation, so a
+  box given twice the budget to start a process is given twice the patience for a notification
+  from it — and the per-test budgets scale with it. The assertions are otherwise unchanged: the
+  fix is the instrument, not the behaviour, and `test/machine-load.test.ts` now refuses a
+  hard-coded millisecond deadline in either file so it cannot come back at somebody's merge.
+  The server's own timings are not what the 5 s bound was papering over — `DEBOUNCE_MS` is 300
+  (20 in these tests) and the mtime fallback sweeps every 500 ms, both an order of magnitude
+  under it — but the measurement did surface a second, distinct cause, filed as #213: with the
+  deadlines scaled, the failures that remain are all directory create/remove events that never
+  arrive AT ALL (114 s, 82 s, no frame), tracking `fseventsd` at ~100% CPU rather than load
+  average, and `watchWorkspace` runs its fingerprint sweep only in poll mode, so a dropped
+  FSEvents notification leaves a live dashboard silently stale for the life of the process.
+  This entry fixes the instrument; the bullet below is the product half.
+
+- **A live dashboard can no longer go silently stale because the OS dropped a notification
+  (#213).** `fs.watch` is the fast path, never a guarantee — FSEvents drops and coalesces
+  under queue pressure — and `watchWorkspace` armed its mtime sweep only in `poll` mode, so
+  a dropped event meant nothing fired, nothing re-armed, and nothing ever swept: the page
+  stopped updating for the life of the process and said nothing about it. Measured on a
+  14-core macOS box with `fseventsd` at 98-115% CPU while `mdbulkimport` indexed: directory
+  create and remove events that never arrived at all — 82,556 ms and 113,942 ms with no
+  frame — while appends inside an already-watched directory kept arriving throughout. Load
+  average was not the predictor; fseventsd saturation was. The sweep now runs in BOTH modes:
+  it is the notifier in `poll` at 500 ms and a backstop in `watch` at `SWEEP_MS` (2 s,
+  overridable like `debounceMs`), so a dropped notification is bounded rather than fatal, and
+  the watcher is re-armed by the sweep's own `fire()`. Same `fingerprint`, one derivation, two
+  cadences. It is idempotent with the fast path — a change the watcher reported re-baselines
+  the sweep inside the same debounce, so one change is still one reload frame. RED first:
+  `test/dashboard-live.test.ts`'s new "a change the watcher missed still reaches the page, by
+  sweep" hangs a real change off a server whose `fs.watch` handles have been closed
+  (`simulateWatcherLoss()` — you cannot ask the OS to drop an event on demand) and went red
+  before this change with no frame at all.
+- **The refusal's printed remedy no longer makes the run disappear (#164).** It printed
+  `git stash push -u -m "tldrx <run> foreign work"` with no pathspec. Measured on 0.14.2: an
+  owner ran it exactly as printed and it swept the run's OWN untracked records under
+  `tldrx-work/<run>/` into the stash, after which `tldrx next` answered
+  `no run '<id>' in tldrx-work/` and `tldrx status` said `nothing pending`. Nothing was lost —
+  `git stash pop` brings it all back — but the framework's own advice had made its own run
+  vanish, and an owner who does not know git internals reads that as the work being gone. The
+  remedy is now limited to exactly the paths the refusal listed, each passed after a literal
+  `--`, and the relaunch verb is chosen by MODE: `tldrx run auto <run>` when the engine is
+  driving, `tldrx next` when a person is. The owner was in `run auto` and the message told him
+  to run `next`, which is the cursor verb. The printed line is also the SAME string the engine
+  runs, `:(literal)` pathspecs and all, shell-quoted so it survives being retyped: it used to
+  join the raw paths while the engine passed `:(literal)`, and the docstring claiming they were
+  one thing was simply false — measured, the printed line for a file called `[x].txt` moved the
+  neighbouring `x.txt`.
+- **A filename with a space, a leading dash or a bracket is the file that moves (#164).** Git
+  pathspecs are globs by default, so `git stash push -u -- 'a[b].txt'` takes the neighbouring
+  `ab.txt` with it — measured in a scratch repo, the tree came back empty where one file should
+  have remained dirty. Every path the framework hands to git for a write is now
+  `:(literal)<path>`, and `git status` is read with `-z` so the path is the bytes on disk rather
+  than git's quoted-and-escaped rendering of them. This is the first thing tldrx does that
+  WRITES to the operator's uncommitted work, and it is the one operation with no undo.
+
+
 ## 0.14.2 — 2026-09-09
 
 ### Fixed

package/README.md

@@ -316,6 +316,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.14.3 | 2026-09-10 | `beta` | foreign uncommitted work no longer stops a Build, and the dashboard flake that blocked four merges in two days has a root cause: the dirty-tree guard used to count every `git status --porcelain` entry and refuse, offering only "commit it" or "stash it" — neither of which an agent may take with another person's files — and measured across three real workspaces on 0.14.2, every first engine-driven run reaching Build stopped at `04-build`, over seed docs, a data export and one untracked note; the dirt is now classified, `own` and `overlapping` refusing or passing exactly as before while everything `foreign` is set aside with a pathspec-limited `git stash push` as the LAST step before the epic branch is cut, recorded as `worktree.foreign_work_aside` and given back with `--index` on every exit path, success or failure, nothing ever deleted and nothing force-popped, a repo mid-merge, rebase, cherry-pick or bisect refused outright because that state has no clean undo, and a pop git refuses said as the stage's last line and carried into the handoff and the notification; the refusal's printed remedy is now the SAME string the engine runs, limited to the paths it listed and relaunching by mode, after an owner ran the pathspec-less line exactly as printed and it swept the run's own records under `tldrx-work/<run>/` into the stash until `tldrx next` answered `no run`; every path handed to git for a write is `:(literal)` and `git status` is read with `-z`, since a glob pathspec moved the neighbouring `x.txt` for a file called `[x].txt`; and the dashboard's live tests stop racing a typed millisecond — five consecutive runs of the two files went red 3 times, at 5084.27 / 5108.01 / 5256.49 ms against a hard-coded 5000 under load averages 65–107 on 14 cores — every deadline now deriving from one `eventWaitMs()` helper that scales like every other budget, with `test/machine-load.test.ts` refusing a hard-coded deadline in either file so it cannot come back at somebody's merge, while that measurement surfaced the product half: `watchWorkspace` armed its mtime sweep only in `poll` mode, so a dropped FSEvents notification left a live dashboard silently stale for the life of the process — measured with `fseventsd` at 98–115% CPU, directory events that never arrived AT ALL at 82,556 ms and 113,942 ms — and the sweep now runs in watch mode too, at 2 s, so a dropped notification is bounded rather than fatal |
 | 0.14.2 | 2026-09-09 | `beta` | every citation check starts from a fresh view of `questions.md` and `facts.yml`: `srcToken.ts` memoised both indexes at module scope and nothing outside `test/` ever dropped them, so in `tldrx run auto` — one Node process for a whole run — the FIRST citation resolved anywhere froze the view every later stage was then judged against; measured on three real unattended workspaces at 0.14.1, a `how` stage refused with `no such question Q2 … declared: Q1` over questions it had itself written minutes earlier, and another refused over `145 live fact(s)` when `facts.yml` held 148, the three extra written by the owner's answers two seconds before the stage started — roughly $11 of paid turns thrown away for ids that were real the whole time; the indexes are now refreshed inside `toSrcContext`, the one place a citation context is built and a place every caller reaches exactly once per check, gate or hook, so a document's forty citations still read `facts.yml` once while nothing survives the check that read it |
 | 0.14.1 | 2026-09-09 | `beta` | an auto gate that says what holds it and closes itself, and three derivations cut to one: measured on a real workspace at 0.14.0, the first `run auto --wait-answers 4h --wait-gates 4h` with a notify hook finished its What stage for $1.98 with every declared check green and told the owner *"waiting at a auto gate that did not close by itself — a person signs it"* — no reason, because `evaluateAutoGate` had computed exactly that sentence into a stdout line nobody was watching while `gate.requested` was appended a hundred lines BEFORE the verdict existed; the verdict is now taken one statement earlier and `why`/`held_by` ride the event to the phone (present only for an `auto` policy, since `held_by: []` on a `human` gate would read as "checked, and nothing held it"), the questions that hold a gate are notified BEFORE the gate downstream of them so the owner stops being told to sign a thing before being told what it is, and an `auto` gate whose only blocker was an open question stops permanently degrading into a `human` one — each poll re-runs the seven conditions off disk and signs through the same `approve` door `next` uses, never for `human` and never for `agent`, a person's `approve` or `reject` still landing first; a question can carry its own `Recommended: <letter> — <why> [src: …]`, parsed tolerantly so an older note reads as not recorded rather than refusing; `tldrx facts add --repo <name>` is now checked against `workspace.yml` through the ONE leaf `answer --repo` already refused on, because the unvalidated flag wrote `repos: [ghost]` at exit 0 and every prompt or filter keyed on a real repo name was then silently blind to that fact; the five phase ids are written out in one file instead of three — `PHASE_IDS`, `QUESTION_PHASES`, and an inline literal walked by `questions lint` that `QUESTION_PHASES`' own doc comment claimed could not exist — pinned from both ends, because an identical second copy and a copy that has already drifted redden different guards and neither alone is enough; a training test stops running on bun's fixed 5000 ms after a spawn probe, validated first against a file the heuristic already claimed (87 spawns recorded, so the instrument can see the thing), found it spawning three real children unclaimed by any marker, with the 14 further unclaimed files filed rather than fixed; and `release-check.sh` refuses a rewritten released section — every dated heading whose tag is present must equal `git show vX.Y.Z:CHANGELOG.md` byte for byte, three sections having drifted with nothing checking, and an amendment recorded in `CHANGELOG.amendments` must still contain the tag's section as an ordered subsequence and may only add lines that exist verbatim in its source sha, after a reviewer proved the first version of that check happily passed an invented bullet |
 | 0.14.0 | 2026-09-09 | `beta` | an `agent` gate the engine can actually close, and three computations of the same answer cut to one: `gates_policy: agent` named who MAY sign a gate but nothing in the engine produced the evidence note it is signed over — measured on 0.13.1, an owner ran `tldrx run gates set what:agent`, was told "an agent may now close it", and the loop stopped at the next gate anyway with exit 4 — so `run auto` now spawns one bounded **gate signer** when a stage's checks pass under an `agent` policy: the stage's own model and effort, a quarter of its per-agent ceiling, a tool allowance that reads anything and writes exactly one file, and a prompt carrying the stage's declared outputs, the seven `auto` conditions as measured and the §2.8 skeleton `gate template` itself renders — the note going through the UNCHANGED `approve --as-agent` path, so a refusal, a note that does not validate, a signer that wrote nothing and a signer that died are one outcome, pending for a person with the reason named on stdout and now in the `gate.requested` summary, and there is no flag to turn it on because an `agent` policy is already the owner's recorded decision; the turn is recorded like any other (`role: gate-signer`, a `run.yml` task row, a row in `tldrx cost`) and taken BEFORE the stage moves to `awaiting_gate`, because the other order had a person sign the gate the engine was mid-signing, three runs out of three; and the suite stops being run three times per change — the pre-merge reviewer now runs only the test files that cover its diff plus `typecheck`, never the full `bun test`, since the wave re-runs every gate on the MERGED tree anyway, `publish.yml` refuses unless `ci` has a `success` run for the same sha instead of recomputing typecheck/tests/build (~87 min/week of runner time, with a `cancelled` ci run failing by name and the remedy), `ci` cancels a run a newer push has already superseded (25 of 122 push runs began under 10 minutes apart), the docs deploy finally fires on `src/cli/helpText.ts` so a help-registry change stops deploying nothing while the published CLI reference goes stale, and `AGENTS.md` §2 now says out loud that a slash in a branch name is a directory, which is what the review-record gate builds |

package/dist/hooks/answer-capture.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-w8qm1jbn.js";
+} from "./chunk-taj1vrbe.js";
 import {
   FactsStore,
   formatJaccard
@@ -16,7 +16,7 @@ import {
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-dnat9z30.js";
+} from "./chunk-mt8f2czb.js";
 import"./chunk-db7wf3hy.js";
 import {
   ADVISORY_KEY,

package/dist/hooks/budget-gate.js

@@ -32,7 +32,7 @@ import {
 } from "./chunk-fefnr71h.js";
 import {
   EventLog
-} from "./chunk-dnat9z30.js";
+} from "./chunk-mt8f2czb.js";
 import {
   noteDeprecations
 } from "./chunk-bqmstq21.js";

package/dist/hooks/{chunk-dnat9z30.js → chunk-mt8f2czb.js}

@@ -45,6 +45,8 @@ var EVENT_TYPES = [
   "story.review_retried",
   "story.work_rescued",
   "story.touches_widened",
+  "worktree.foreign_work_aside",
+  "worktree.foreign_work_restored",
   "result.unreadable",
   "operator_note",
   "check.passed",

package/dist/hooks/{chunk-97zs34wb.js → chunk-ppgbs5ag.js}

@@ -22,7 +22,7 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-dnat9z30.js";
+} from "./chunk-mt8f2czb.js";
 import {
   backupPathFor,
   isAlive,

package/dist/hooks/{chunk-w8qm1jbn.js → chunk-taj1vrbe.js}

@@ -5,7 +5,7 @@ import {
   evidencePath,
   gateEvidencePath,
   parseEvidence
-} from "./chunk-dnat9z30.js";
+} from "./chunk-mt8f2czb.js";
 import {
   openBlocks,
   parseQuestions

package/dist/hooks/session-start.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   questionsCard
-} from "./chunk-w8qm1jbn.js";
+} from "./chunk-taj1vrbe.js";
 import"./chunk-mzwqb08p.js";
 import {
   allow,
@@ -18,7 +18,7 @@ import {
   openQuestions,
   runSnapshot,
   whatIsWaiting
-} from "./chunk-97zs34wb.js";
+} from "./chunk-ppgbs5ag.js";
 import"./chunk-dzkg8c68.js";
 import {
   expertsDir,
@@ -28,7 +28,7 @@ import {
   readExpertDomain,
   stackExpertNames
 } from "./chunk-fefnr71h.js";
-import"./chunk-dnat9z30.js";
+import"./chunk-mt8f2czb.js";
 import"./chunk-db7wf3hy.js";
 import {
   openBlocks,

package/dist/hooks/statusline.js

@@ -2,10 +2,10 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-97zs34wb.js";
+} from "./chunk-ppgbs5ag.js";
 import"./chunk-dzkg8c68.js";
 import"./chunk-fefnr71h.js";
-import"./chunk-dnat9z30.js";
+import"./chunk-mt8f2czb.js";
 import"./chunk-db7wf3hy.js";
 import"./chunk-bqmstq21.js";
 import {