tldr-experts 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.16.0 — 2026-09-11
+
+### Added
+
+- **`tldrx run auto --retry-failed <n>` — a bounded retry on a failed stage (#233).** Measured
+  on a real unattended run at 0.15.0: the loop drove itself through what → how → plan and
+  signed all three `auto` gates by itself, and still needed a person four times. Three of the
+  four were content decisions or money, which a loop must not make. The fourth was a plan that
+  failed its `plan` check by five characters over a cap — a person relaunched `run auto`, the
+  next attempt fixed the two files and passed, and nothing else happened. So the loop stopped
+  on the one failure it could have cleared, and it stopped because `run auto` returned on every
+  non-zero exit except `4`. Now `--retry-failed <n>` lets it run that stage again, at most `n`
+  times in a row. It bounds exit `5` and nothing else: a usage error (`1`), a money refusal
+  (`2`) and an awaiting-human park (`4`) are each attempted ONCE however large `n` is, because
+  a phase ceiling means *a human decides about money* and a retry would turn that sentence into
+  a delay. Only CONSECUTIVE failures count — any other outcome puts the count back to zero,
+  since what is bounded is "this run is stuck", not "this run has ever failed". A retry SPENDS:
+  it is a fresh metered stage under the same phase ceiling and the same `--max-usd`, which is
+  what stops it running up a bill. `0` is the default and a default invocation's lines are
+  byte-identical to what they were; anything outside `0..3` is refused by name with exit `1`,
+  from the one constant the loop and the flag parser share. When the bound is spent the loop
+  stops on the failure's own exit `5` and SAYS the count last — `3 consecutive stage failures
+  at 03-plan/plan …` — so the sentence that reaches a phone is what the loop tried, not a bare
+  `5`.
+
+### Fixed
+
+- **An `auto` gate that REFUSES now writes the verdict down, so `run status` says which of the
+  seven conditions is holding it (#230).** The note has always been the designed answer to
+  "which of the seven stopped it" — and it was written only by a gate that CLOSED, so the one
+  record built for that question was `note: ""` in exactly the case it exists for. Measured
+  2026-09-10 on an unattended `run auto`: a gate sat pending ~40 minutes, `run status` and
+  `run status --verbose` named no condition, and the reason (`claim-sources`, one unresolvable
+  source) surfaced only when a person guessed at the `tldrx approve` the status line suggested
+  — the one route nobody unattended is going to take. Each re-measure that refuses now records
+  `auto-gate refused — held by: <ids> · <all seven with their values>` on the gate that is
+  still `pending`, and `run status` names the ids on the gate row and on the `waiting` line
+  (`--verbose` still quotes the whole note). All seven values, not just the failures: a note
+  that dropped `budget=$0.30 of $6.00` would answer "was it the money" with the same silence.
+  It writes only a `pending` gate — a gate a person has since signed keeps THEIR words — and
+  only when the note would change, so a four-hour `--wait-gates` poll writes `run.yml` once per
+  distinct verdict rather than thousands of times. That `pending` test and the write are a
+  **compare-and-set under the workspace lock**, over a `run.yml` read inside it: a check-then-act
+  over a snapshot taken a moment earlier erased a concurrent `approve` outright — `save()` writes
+  the whole snapshot and re-reads only `budget.yml`'s ceilings, so the gate fell back to
+  `pending`, `by`/`at` to null and the person's words were gone. Caught in pre-merge review and
+  reproduced with two real processes, which is now the test: the poll runs every two seconds
+  precisely while a person is deciding, so an audit record that destroys the evidence of a human
+  decision is not a theoretical interleaving. A gate carrying a refusal note is no longer
+  counted among the "signed gates carry a note" rows, because nobody closed it.
+
 ## 0.15.0 — 2026-09-10
 
 ### Added

package/README.md

@@ -316,6 +316,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.16.0 | 2026-09-11 | `beta` | an unattended run can now clear the one kind of failure it was stopping on, and a gate that refuses says why it refused: measured 2026-09-10 on a real unattended `run auto`, the loop drove itself through what → how → plan and signed all three `auto` gates by itself, and still needed a person four times — three of those were content or money decisions a loop must not make, and the fourth was a plan that failed its own check by five characters over a cap, where a person relaunched the same command and the next attempt fixed the two files and passed, so the loop stopped on the one failure it could have cleared; `tldrx run auto --retry-failed <n>` now runs a failed stage again at most `n` times in a row, bounding exit `5` and nothing else — a usage error (`1`), a money refusal (`2`) and an awaiting-human park (`4`) are each attempted ONCE however large `n` is, because a phase ceiling means a human decides about money and a retry would turn that sentence into a delay — only CONSECUTIVE failures count since what is bounded is "this run is stuck" and not "this run has ever failed", a retry SPENDS as a fresh metered stage under the same phase ceiling and the same `--max-usd`, `0` is the default and a default invocation's lines are byte-identical to what they were, and when the bound is spent the loop stops on the failure's own exit `5` and says the count LAST, so the sentence that reaches a phone is what the loop tried and not a bare number; and an `auto` gate that REFUSES now writes down the verdict its note was always designed to carry — a gate sat pending ~40 minutes while `run status` and `--verbose` named no condition at all, and the reason surfaced only when a person guessed at the `tldrx approve` the status line suggested, which is the one route nobody unattended is going to take — recording all seven conditions WITH THEIR VALUES on the still-`pending` gate, since a note that dropped the passing ones would answer "was it the money" with the same silence, and naming the holding ids on the gate row and on the `waiting` line; it writes only over a `pending` gate, so a gate a person has since signed keeps THEIR words, and only when the verdict would change, so a four-hour `--wait-gates` poll writes once per distinct verdict rather than thousands of times — and that test and that write are a compare-and-set under the workspace lock, because pre-merge review reproduced, with two real processes, a check-then-act over an earlier snapshot erasing a concurrent `approve` outright, and the poll runs every two seconds precisely while a person is deciding |
 | 0.15.0 | 2026-09-10 | `beta` | defaults for the models actually running today, and records that name what happened: measured 2026-09-07/09 across three real workspaces, the first engine-driven run of each was ended by a calibration rather than by the work — a `how` turn and two Build developer turns killed at a 900 s per-turn clock while Opus turns on real repositories run 15-50 minutes, a 202 KB prompt refused by a ceiling whose own message called it "29% of a 200k window", and a 169 KB `facts.yml` sliced to 96 KB on its way into a design turn that then died. So a turn gets two hours (`timeout_s` 900 → 7200), a prompt 400 KB and inputs 256 KB, a phase ceiling holds every attempt its stages may take so the first retry of a stage that spent anything is no longer refused by arithmetic — `warn_at_pct` still measured against one attempt's share, so the warning still arrives before the money — and the four numbers that were calibrations rather than invariants (`attempts`, `fixlist_rounds`, `reviewer_share`, `gate_signer_share`) became optional `stage.yml` keys, refused by name out of range instead of clamped, absent meaning today's constant byte for byte, with `tldrx run auto --prompt-max-bytes` and `--max-reads` for the unattended run that would otherwise need a file edit to get past one refusal; a story's Definition of Done now runs with its dependencies installed — the `install:` slot has sat unread in `templates/workspace.yml` since the beginning and now runs in every fresh story worktree through the same allowlist-and-argv runner, recorded with its own exit code and duration, blocking the story rather than paying a turn to discover it — an exit 127 is reported as a named absent binary and not as a red test, a declared command may be run WITH ARGUMENTS (the exact `Bash(npm run test)` grant matched nothing the developer actually typed, so its own 127 was first seen by the gate, after the turn was paid for), and every DoD check says which tree it ran in; the Build gate now names story outcomes on every policy and not only `auto` — two runs approved from a phone printed `run is done` over zero stories delivered — `run.yml` records an additive `outcome:` written once by all three commands that close a run and rendered by six surfaces, and `tldrx ship` refuses with exit 1 instead of opening a PR over nothing; a red DoD keeps its real failure — the last 200 lines on disk (gitignored, since a tail can carry a secret), up to five failure-looking lines as the detail rather than the last `DeprecationWarning` on stderr, the failing line cited at the line it starts on, and the next attempt told it was the check and not a reviewer; a watcher card may honestly say `Query: none — <reason> [src: …]`, earned only over a card whose own `## Signal` cites `absent:` and refused like any unsourced item otherwise, after a stage spent real money writing the honest answer and was refused for it; a truncated input is told to the OWNER at spawn and not only to the sub-agent, a turn killed on timeout keeps the usage it had already streamed and never a price; and the maintain skill says which sha a review record must cite — the code head — a rule that cost a wave and was written down nowhere an agent reads |
 | 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 |

package/dist/hooks/{chunk-zccma7kt.js → chunk-vvr4rk82.js}

@@ -507,6 +507,16 @@ function statusWithOutcome(status, outcome) {
 
 // src/core/run/autoGate.ts
 var AUTO_GATE_ACTOR = "auto";
+var AUTO_GATE_REFUSED_PREFIX = "auto-gate refused — held by: ";
+var HELD_SEPARATOR = " · ";
+function heldByNote(note) {
+  if (!note.startsWith(AUTO_GATE_REFUSED_PREFIX))
+    return [];
+  const rest = note.slice(AUTO_GATE_REFUSED_PREFIX.length);
+  const end = rest.indexOf(HELD_SEPARATOR);
+  const ids = (end === -1 ? rest : rest.slice(0, end)).split(", ").map((id) => id.trim());
+  return ids.filter((id) => id !== "");
+}
 
 // src/core/run/gateAuthority.ts
 var UNRECORDED_AUTHORIZER = "unrecorded";
@@ -729,12 +739,14 @@ function waitingFor(run, runDir) {
   }
   const open = blockingQuestionIds(join6(runDir, cursor.phase, "questions.md"));
   switch (entry.stage.status) {
-    case "awaiting_gate":
+    case "awaiting_gate": {
+      const held = heldByNote(entry.stage.gate?.note ?? "");
       return {
         kind: "gate",
-        message: `gate on ${entry.phase.id}/${entry.stage.id} — \`tldrx approve\` or \`tldrx reject --note "…"\``,
+        message: `gate on ${entry.phase.id}/${entry.stage.id}` + (held.length === 0 ? "" : ` — held by ${held.join(", ")}`) + ` — \`tldrx approve\` or \`tldrx reject --note "…"\``,
         questions: open
       };
+    }
     case "awaiting_answer":
       return {
         kind: "answer",

package/dist/hooks/session-start.js

@@ -20,7 +20,7 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-zccma7kt.js";
+} from "./chunk-vvr4rk82.js";
 import {
   expertsDir,
   loadExperts,

package/dist/hooks/statusline.js

@@ -2,7 +2,7 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-zccma7kt.js";
+} from "./chunk-vvr4rk82.js";
 import"./chunk-3kmx3dmz.js";
 import"./chunk-rz0qr006.js";
 import"./chunk-d0rp8c68.js";

package/dist/tldrx.js

@@ -15643,6 +15643,12 @@ var ENTRIES = [
         meaning: "Send the workspace's declared notify hook a `status` payload this often while the loop runs — `30s`, `10m`, `2h`, or a bare number of seconds. Off by default, and it does nothing at all unless `.tldrx/workspace.yml` declares a `notify:` command (§2.18). A `status` payload carries what `tldrx run status` prints. It asks for nothing while the run is moving — and when the run is PARKED on an open question it says so and repeats the literal answer command, because a heartbeat that keeps saying nothing is waiting on you while a run waits on you is worse than silence.",
         sub: "auto"
       },
+      {
+        name: "retry-failed",
+        arg: "<n>",
+        meaning: 'How many times in a row the loop may run a FAILED stage again before it stops. 0 — the default, and what every invocation before this got — means one attempt and then exit 5. A retry is the same `tldrx next` a person would have typed: the stage is on disk as `failed` with its reason recorded, and the next attempt is told what the last one did. It bounds EXIT 5 AND NOTHING ELSE — a usage error (1), a money refusal (2) and an awaiting-human park (4) are attempted once however large the bound, because each is a decision a person owns; a phase ceiling especially, which means "a human decides about money" and would otherwise become a delay. Only CONSECUTIVE failures count: a stage that succeeds puts the count back to zero. A retry SPENDS — it is a fresh metered stage under the same phase ceiling and the same --max-usd — and when the bound is spent the loop stops on the failure\'s own exit 5, with the count in the last line.',
+        sub: "auto"
+      },
       {
         name: "wait-gates",
         arg: "<duration>",
@@ -15695,6 +15701,7 @@ var ENTRIES = [
       "tldrx run auto --parallel 3",
       "tldrx run auto --prompt-max-bytes 500000 --max-reads 300",
       "tldrx run auto --notify-every 10m",
+      "tldrx run auto --retry-failed 2",
       "tldrx run auto --wait-answers 30m",
       "tldrx run auto --wait-answers 4h --wait-gates 4h",
       "tldrx run unlock 260101-checkout --force",
@@ -15703,7 +15710,7 @@ var ENTRIES = [
     exits: [EXIT_OK, EXIT_USAGE, EXIT_GATE_REFUSED, EXIT_NOT_FOUND, EXIT_AWAITING_HUMAN, EXIT_AGENT_FAILED],
     notes: [
       "`run attend host` is a LOCK, not an engine. It sets one field, spends nothing, runs no stage and touches no branch — and from then on THE FRAMEWORK WILL NOT SPAWN on that run: every turn is a `tldrx next --prepare` / `tldrx next --commit` handshake with the session driving it, the Build reviewer included. `run attend --none` hands it back.",
-      "`run auto` is an ENGINE, not a lock. It calls `next` HEADLESS over and over, so THE FRAMEWORK spawns a metered sub-agent stage after stage, and it stops at the first thing it may not decide: a human gate or an open question (4), a stage failure (5), a phase ceiling or this loop's own --max-usd (2). It is REFUSED ON AN ATTENDED RUN (exit 1, before the event log is opened) — a lock and an engine are alternatives, never layers.",
+      "`run auto` is an ENGINE, not a lock. It calls `next` HEADLESS over and over, so THE FRAMEWORK spawns a metered sub-agent stage after stage, and it stops at the first thing it may not decide: a human gate or an open question (4), a stage failure (5) — unless `--retry-failed <n>` lets it run that stage again, bounded, up to n times in a row — a phase ceiling or this loop's own --max-usd (2). It is REFUSED ON AN ATTENDED RUN (exit 1, before the event log is opened) — a lock and an engine are alternatives, never layers.",
       "`run auto` can also TELL SOMEBODY. When `.tldrx/workspace.yml` declares a `notify:` command (§2.18), the loop hands that command one `version: 1` JSON object on stdin at every moment a person is needed — an open question with its options and the literal `tldrx answer` line, a gate with the literal approve line, a finished or failed run with its exit code and family — plus a periodic `status` under `--notify-every`. The framework names no chat tool: the command is the owner's own, run as argv with no shell, and its exit code is recorded as `notify.sent` / `notify.failed` and NEVER changes the run's outcome.",
       "Under `run auto`, a stage whose `gates_policy` is `agent` gets one bounded GATE-SIGNER turn of its own. When the stage's checks have passed, the engine spawns a single sub-agent at the stage's model and effort, on a quarter of the stage's per-agent ceiling, allowed to read and to write exactly one file: `.agent/<stage>/evidence.md`. The note then goes through the UNCHANGED `approve --as-agent` path — the same validator a person's note goes through — so `verdict: sign` plus every condition holding closes the gate under the note's own `by:`, and anything else leaves it pending for a person with the reasons named. The turn is recorded like any other (`agent.spawned` / `agent.result`, `role: gate-signer`) and shows up in `tldrx cost`. There is no flag for it: `gates_policy: agent` is already the owner's recorded decision that an agent may close this gate, and `human` gates are never touched.",
       "`run status` with several runs open LISTS them and exits 0 — it is the screen you read to find the id every other command wants.",
@@ -29357,6 +29364,22 @@ async function evaluateAutoGate(input) {
 function heldBy(verdict) {
   return verdict.conditions.filter((condition) => !condition.ok).map((condition) => condition.id);
 }
+var AUTO_GATE_REFUSED_PREFIX = "auto-gate refused — held by: ";
+var HELD_SEPARATOR = " · ";
+function refusalNote(verdict) {
+  const held2 = heldBy(verdict);
+  if (held2.length === 0)
+    return "";
+  return `${AUTO_GATE_REFUSED_PREFIX}${held2.join(", ")}${HELD_SEPARATOR}` + verdict.conditions.map(render2).join("; ");
+}
+function heldByNote(note) {
+  if (!note.startsWith(AUTO_GATE_REFUSED_PREFIX))
+    return [];
+  const rest = note.slice(AUTO_GATE_REFUSED_PREFIX.length);
+  const end = rest.indexOf(HELD_SEPARATOR);
+  const ids = (end === -1 ? rest : rest.slice(0, end)).split(", ").map((id) => id.trim());
+  return ids.filter((id) => id !== "");
+}
 async function reevaluateAutoGate(input) {
   const phase = input.run.phases.find((entry) => entry.stages.some((stage3) => stage3.id === input.stageId));
   const stage2 = phase?.stages.find((entry) => entry.id === input.stageId);
@@ -29377,7 +29400,7 @@ async function reevaluateAutoGate(input) {
     runDir: input.runDir,
     stage: planned
   });
-  return await evaluateAutoGate({
+  const verdict = await evaluateAutoGate({
     root: input.root,
     runDir: input.runDir,
     phaseId: phase.id,
@@ -29386,6 +29409,30 @@ async function reevaluateAutoGate(input) {
     budget: input.budget,
     checks
   });
+  if (!verdict.ok)
+    recordRefusal(input.runDir, input.stageId, verdict);
+  return verdict;
+}
+function recordRefusal(runDir, stageId, verdict) {
+  const note = refusalNote(verdict);
+  if (note === "")
+    return;
+  try {
+    withWorkspaceLock(workspaceRootOfRunDir(runDir), () => {
+      const store = RunStore.open(runDir);
+      const current = store.run.phases.flatMap((phase) => phase.stages).find((stage2) => stage2.id === stageId);
+      if (current === undefined || current.gate.status !== "pending" || current.gate.note === note)
+        return;
+      store.mutate((run) => ({
+        ...run,
+        phases: run.phases.map((phase) => ({
+          ...phase,
+          stages: phase.stages.map((stage2) => stage2.id === stageId && stage2.gate.status === "pending" ? { ...stage2, gate: { ...stage2.gate, note } } : stage2)
+        }))
+      }));
+      store.save();
+    });
+  } catch {}
 }
 function render2(condition) {
   return `${condition.id}=${condition.detail}`;
@@ -29708,12 +29755,14 @@ function waitingFor(run, runDir) {
   }
   const open = blockingQuestionIds(join66(runDir, cursor.phase, "questions.md"));
   switch (entry.stage.status) {
-    case "awaiting_gate":
+    case "awaiting_gate": {
+      const held2 = heldByNote(entry.stage.gate?.note ?? "");
       return {
         kind: "gate",
-        message: `gate on ${entry.phase.id}/${entry.stage.id} — \`tldrx approve\` or \`tldrx reject --note "…"\``,
+        message: `gate on ${entry.phase.id}/${entry.stage.id}` + (held2.length === 0 ? "" : ` — held by ${held2.join(", ")}`) + ` — \`tldrx approve\` or \`tldrx reject --note "…"\``,
         questions: open
       };
+    }
     case "awaiting_answer":
       return {
         kind: "answer",
@@ -30020,7 +30069,7 @@ function renderGates(rows, verbose = false) {
   const auto = rows.filter((row2) => row2.policy === "auto").length;
   const agent = rows.filter((row2) => row2.policy === "agent").length;
   const human = rows.length - auto - agent;
-  const noted2 = rows.filter((row2) => row2.note !== null).length;
+  const noted2 = rows.filter((row2) => isSigned(row2) && row2.note !== null).length;
   const lines = [
     `gates   ${String(human)} human, ${String(auto)} auto` + (agent === 0 ? "" : `, ${String(agent)} agent`)
   ];
@@ -30043,10 +30092,13 @@ function renderGates(rows, verbose = false) {
 var NOTE_MARK = "✎";
 function gateTail(row2) {
   const parts = [briefDuration(row2.started_at, row2.ended_at)];
-  if (row2.note !== null)
+  if (isSigned(row2) && row2.note !== null)
     parts.push(NOTE_MARK);
   return parts.filter((part) => part !== "").join("  ");
 }
+function isSigned(row2) {
+  return row2.status === "approved" || row2.status === "rejected";
+}
 function briefDuration(startedAt, endedAt) {
   const measured = dashDuration(startedAt, endedAt);
   if (measured !== "")
@@ -30076,7 +30128,8 @@ function describeGate(row2) {
     return `rejected by ${describeGateSignature(row2)}`;
   if (row2.status === "n-a")
     return `${row2.type}: n-a`;
-  return `${row2.type}: ${row2.status}`;
+  const held2 = heldByNote(row2.note ?? "");
+  return `${row2.type}: ${row2.status}` + (held2.length === 0 ? "" : ` — held by ${held2.join(", ")}`);
 }
 var NOTES_SHOWN = 3;
 function renderOperatorNotes(notes) {
@@ -40210,6 +40263,8 @@ var EXIT_USAGE4 = 1;
 var EXIT_REFUSED3 = 2;
 var EXIT_NOT_FOUND4 = 3;
 var EXIT_AWAITING_HUMAN3 = 4;
+var EXIT_AGENT_FAILED3 = 5;
+var MAX_RETRY_FAILED = 3;
 var MAX_ITERATIONS = 96;
 async function runAuto(options) {
   const lines = [];
@@ -40349,6 +40404,7 @@ async function runAuto(options) {
     }
     return { costUsd: null, deferredGate: null };
   };
+  let consecutiveFailures = 0;
   try {
     for (let iteration = 0;iteration < MAX_ITERATIONS; iteration++) {
       const store = RunStore.open(runDir2);
@@ -40400,7 +40456,19 @@ async function runAuto(options) {
         if (send !== null)
           await send();
       };
+      if (outcome.code !== EXIT_AGENT_FAILED3)
+        consecutiveFailures = 0;
       if (outcome.code !== EXIT_OK5) {
+        const retryBound = options.retryFailedStages ?? 0;
+        if (outcome.code === EXIT_AGENT_FAILED3) {
+          consecutiveFailures += 1;
+          if (consecutiveFailures <= retryBound) {
+            for (const line of outcome.lines)
+              say(`  ${line}`);
+            say(`retrying ${cursorBefore} — failure ${String(consecutiveFailures)} of ` + `${String(retryBound)} retries allowed (--retry-failed ${String(retryBound)})`);
+            continue;
+          }
+        }
         let rejection = null;
         if (outcome.code === EXIT_AWAITING_HUMAN3) {
           const card = openQuestions2();
@@ -40447,6 +40515,9 @@ async function runAuto(options) {
           say(line);
         if (rejection !== null)
           say(rejection);
+        if (outcome.code === EXIT_AGENT_FAILED3 && retryBound > 0) {
+          say(`stopped: ${String(consecutiveFailures)} consecutive stage failures at ${cursorBefore} ` + `— the --retry-failed ${String(retryBound)} bound is spent, and the exit code is still ` + "5, the failure's own");
+        }
         return await finish(outcome.code, spentByLoop);
       }
       const after = RunStore.open(runDir2);
@@ -42691,7 +42762,8 @@ var VALUE_FLAGS = [
   "wait-answers",
   "wait-gates",
   "prompt-max-bytes",
-  "max-reads"
+  "max-reads",
+  "retry-failed"
 ];
 function durationFlag(args, name) {
   const raw = stringFlag(args, name);
@@ -42703,6 +42775,15 @@ function durationFlag(args, name) {
   }
   return ms;
 }
+function retryFailedFlag(args) {
+  const value = numberFlag(args, "retry-failed");
+  if (value === undefined)
+    return;
+  if (!Number.isInteger(value) || value < 0 || value > MAX_RETRY_FAILED) {
+    throw new UsageError(`--retry-failed must be a whole number between 0 and ${String(MAX_RETRY_FAILED)} ` + "(0 is the default: a failed stage stops the loop). A stage that has failed that many " + "times in a row is failing for a reason another spawn will not discover, and every " + "attempt is real money.");
+  }
+  return value;
+}
 var runCommand = {
   name: "run",
   summary: "Create, inspect or auto-run a piece of work",
@@ -42715,6 +42796,7 @@ var runCommand = {
 ` + `       tldrx run auto [<run>] [--max-usd <n>] [--until <stage>] [--model <m>] [--effort <level>]
 ` + `                      [--notify-every <duration>] [--wait-answers <duration>]
 ` + `                      [--wait-gates <duration>] [--prompt-max-bytes <n>] [--max-reads <n>]
+` + `                      [--retry-failed <n>]
 ` + `                  [--yolo] [--parallel <n>] [--gate-agent] [--ui scene|compact|plain|off]
 ` + `                  [--run <id>] [--root <path>]
 ` + `       tldrx run gates set <stage>:<human|auto|agent> --note <text> [--run <id>] [--root <path>]
@@ -42877,6 +42959,7 @@ async function runAutoLoop(argv) {
         notifyEveryMs: durationFlag(args, "notify-every"),
         waitAnswersMs: durationFlag(args, "wait-answers"),
         waitGatesMs: durationFlag(args, "wait-gates"),
+        retryFailedStages: retryFailedFlag(args),
         actor: currentActor(),
         at: nowRfc3339(),
         onLine: (line) => ui2.log(() => process.stdout.write(`${line}
@@ -43294,7 +43377,7 @@ var PROPOSE_STAGE = "propose";
 var EXIT_OK9 = 0;
 var EXIT_USAGE6 = 1;
 var EXIT_REFUSED7 = 2;
-var EXIT_AGENT_FAILED3 = 5;
+var EXIT_AGENT_FAILED4 = 5;
 var DEFAULT_TRIAGE_EFFORT = "low";
 var DEFAULT_TRIAGE_USD = 1;
 var MIN_TRIAGE_USD = 0.25;
@@ -43428,7 +43511,7 @@ async function propose(options, workspaceCommands, inventory, seed, outDir) {
     metered = outcome.metered;
     if (!outcome.ok) {
       return {
-        code: EXIT_AGENT_FAILED3,
+        code: EXIT_AGENT_FAILED4,
         costUsd,
         outDir,
         inventory,
@@ -43449,7 +43532,7 @@ async function propose(options, workspaceCommands, inventory, seed, outDir) {
     if (mode === "commit")
       writeRaw(outDir, PROPOSE_STAGE, JSON.stringify(raw ?? null, null, 2));
     return {
-      code: EXIT_AGENT_FAILED3,
+      code: EXIT_AGENT_FAILED4,
       costUsd,
       outDir,
       inventory,
@@ -48535,7 +48618,7 @@ var EXIT_OK14 = 0;
 var EXIT_USAGE9 = 1;
 var EXIT_GATE_REFUSED2 = 2;
 var EXIT_NOT_FOUND12 = 3;
-var EXIT_AGENT_FAILED4 = 5;
+var EXIT_AGENT_FAILED5 = 5;
 var TRAIN_TIMEOUT_MS = 30 * 60 * 1000;
 async function runTraining(options) {
   const said2 = [];
@@ -48775,7 +48858,7 @@ async function trainWithPreflight(options, said2) {
     }));
     if (!outcome.ok) {
       rollback(previous);
-      return fail3(EXIT_AGENT_FAILED4, [
+      return fail3(EXIT_AGENT_FAILED5, [
         `${options.expert}/${area.id}: the ${task2.key} sub-agent failed — ${outcome.error ?? "no result"}`,
         outcome.metered ? `  $${round29(outcome.costUsd).toFixed(2)} spent and recorded; nothing was written to competencies.yml` : `  ${providerWarning ?? "the provider turn was unmetered in dollars"}; nothing was written to competencies.yml`
       ], sum(tasks));
@@ -49114,7 +49197,7 @@ function reject2(log, options, area, costUsd, lines, detail) {
       ...fitProblems(detail.problems)
     }
   }));
-  return { code: EXIT_AGENT_FAILED4, lines, costUsd };
+  return { code: EXIT_AGENT_FAILED5, lines, costUsd };
 }
 function fitProblems(problems) {
   const budget = MAX_PAYLOAD_BYTES2 - 1024;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tldr-experts",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "tldr-experts: an evidence-first, file-based AI development framework - five stages, a gate on every one, and every claim cited or refused. Installs the `tldrx` (and `tldr-experts`) command. Beta.",
   "license": "MIT",
   "author": "Alan Martinez",

package/plugin/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$doc": "Shape verified from https://code.claude.com/docs/en/plugins.md (Quickstart > Create the plugin manifest). Fields used here: name, description, version, author.name. Only plugin.json goes inside .claude-plugin/; skills/, agents/ and hooks/ live at the plugin root.",
   "name": "tldrx",
   "description": "tldr-experts: an evidence-first, file-based AI development framework. Five stages, a gate on every one, every claim cited or refused. Beta.",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "author": {
     "name": "Alan Martinez"
   }