@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/research-fanout-budget.js

@@ -1,74 +1,48 @@
 /**
- * nexttask 5B — the two candidate bounds on worker:apis's project-source fan-out.
- *
- * ⚠ ONE of the levers in this file is wired: the RESCUE progress deadline
- * (`workerProgressCeilingMs`) SHIPPED ON in nexttask 9, on a PASS measured over 42
- * trials per arm against an instrument whose own false-break rate is on record at
- * 1.5%. CAP, SCALE and RESCUE-CARRY remain OFF unless their env var is set — CAP
- * and SCALE were rejected on argument (see below), carry-forward was measured
- * HARMFUL on its own.
- *
- * The OFF levers exist so `scripts/live-research-fanout-budget-ab.ts` can run them
- * against the shipped baseline in the SAME build — the alternative (dist surgery)
- * measures a patched copy of the code and not the code. Nothing may read them
- * outside that harness until it reports PASS; a lever wired on argument rather
- * than measurement is the failure mode nexttasks exists to prevent.
- *
- * THE FAULT THEY TARGET (mx5 run 18, measured — scripts/research-restart-baserate.ts):
- * `worker:apis` fans out `pi-worker-docs(module: ".")` project-source lookups, each
- * of which spawns its own summarising child, and the per-worker wall-clock cap is
- * 240s. Pearson r(project lookups, worker wall clock) = 0.909 over 24 tasks. 0-4
- * lookups never timed out; every worker at >=46 lookups burned the FULL restart
- * budget — 3 attempts, 720s, two of them discarded whole. The 240s ceiling and a
- * 46-call fan-out are jointly unsatisfiable, so the timeout is not a backstop
- * there, it is the guaranteed outcome.
- *
- * TWO WAYS TO MAKE THEM SATISFIABLE, and the A/B — not this comment — decides:
+ * research-fanout-budget — the levers bounding worker:apis's project-source
+ * fan-out, and which of them is on.
+ *
+ * `workerProgressCeilingMs` is ON by default; its env var is the OFF switch. CAP
+ * (`projectDocsBudget`), SCALE (`fanoutTimeoutPolicy`) and RESCUE-CARRY
+ * (`workerCarryForward`) are OFF unless their env var is set. They stay in the
+ * shipped build so a harness can run them against the shipped baseline in the SAME
+ * build — patching a copy of the code measures the copy, not the code. Nothing may
+ * read them outside such a harness.
+ *
+ * THE FAULT THEY TARGET. `worker:apis` fans out `pi-worker-docs(module: ".")`
+ * project-source lookups, and each one spawns its own summarising child. Under a
+ * fixed wall-clock cap, a large enough fan-out cannot finish inside it — so the
+ * timeout is not a backstop there, it is the guaranteed outcome.
  *
  *   CAP     bound the fan-out to fit the ceiling. Told to the worker upfront
  *           (projectDocsBudgetNotice) and enforced in the tool
- *           (projectDocsBudgetExhausted), because run 18 shows the prompt alone
- *           does not bind: the same worker is ALREADY told "be decisive" by
- *           WORKER_TIMEOUT_HINT on every restart.
- *   SCALE   bound the ceiling to fit the fan-out: each project-source lookup
- *           pushes the deadline out, up to a hard ceiling, so a worker that is
- *           making progress is not killed for making progress.
- *
- * The risk each carries, and why the A/B's quality invariant is load-bearing: CAP
- * can produce a faster worker that ships a THINNER APIS section, which is a
- * regression wearing a win's clothes (memory/apis-contract-stage2-failed.md: a
- * lever moved behaviour 20/20 while fabricating 15% of it). SCALE can simply
- * spend the extra time and still time out, buying nothing.
- *
- * ─────────────────────────────────────────────────────────────────────────────
- * BOTH OF THE ABOVE ANSWER THE WRONG QUESTION. Kept for the record and for the
- * A/B's other arms, but they are not the fix.
- *
- * They argue about how long a worker may run. The actual defect is what happens
- * when it runs out: the attempt is killed and everything it produced is THROWN
- * AWAY, and the re-spawn is given a hint but no findings — so it re-reads the
- * same files against the same clock and dies in the same place. That is why
- * every worker at >=46 lookups burned the FULL budget rather than converging.
- * The r=0.909 correlation measures the amnesia, not an over-long task.
+ *           (projectDocsBudgetExhausted). The prompt alone does not bind: the same
+ *           worker is ALREADY told "be decisive" by WORKER_TIMEOUT_HINT
+ *           (pi-worker-core.ts) on every restart.
+ *   SCALE   bound the ceiling to fit the fan-out: each project-source lookup pushes
+ *           the deadline out, up to a hard ceiling, so a worker that is making
+ *           progress is not killed for making progress.
+ *
+ * BOTH ANSWER THE WRONG QUESTION. They argue about how long a worker may run. The
+ * defect is what happens when it runs out: the attempt is killed, everything it
+ * produced is THROWN AWAY, and the re-spawn gets a hint but no findings — so it
+ * re-reads the same files against the same clock and dies in the same place.
  *
  * Judged against "the worker must return its work", CAP makes the worker read
- * LESS — lowering the requirement so the metric goes green — and SCALE is a
- * per-file constant that dies on one big file, and, being wall-clock, makes
- * answer quality a function of the user's hardware: the same task on a slower
- * local model loses its work and degrades. No constant fixes that.
- *
- *   RESCUE  (pi-worker-core.ts) carry the killed attempt's findings into the
- *           next one and never return less than the best attempt produced, so a
- *           restart CONVERGES instead of repeating; and deadline on lack of
- *           PROGRESS rather than elapsed time, so "slow" and "stuck" stop being
- *           the same verdict. Being stuck is already detected separately and
- *           correctly by the output-stall probe (STALL_AFTER_MS), which resets
- *           on progress and only kills when the model endpoint is unreachable.
- *
- * Its risk is its own, and the same quality invariant catches it: a half-written
- * entry replayed under "work already done" is exactly how a fabrication gets
- * laundered into a final answer. Hence the carry is framed as unverified, and
- * ungrounded-symbol and anti-synthesis counts gate the arm.
+ * LESS, lowering the requirement so the metric goes green; and SCALE is a per-file
+ * constant that dies on one big file and, being wall-clock, makes answer quality a
+ * function of the user's hardware — the same task on a slower model loses its work.
+ *
+ *   RESCUE  (pi-worker-core.ts) carry the killed attempt's findings into the next
+ *           one and never return less than the best attempt produced, so a restart
+ *           CONVERGES instead of repeating; and deadline on lack of PROGRESS rather
+ *           than elapsed time, so "slow" and "stuck" stop being the same verdict.
+ *           Being stuck is already detected separately by the output-stall probe
+ *           (STALL_AFTER_MS, worker-profiles.ts), which resets on progress.
+ *
+ * The carry has a risk of its own: a half-written entry replayed under "work
+ * already done" is how a fabrication gets laundered into a final answer. That is
+ * why the carry is framed to the worker as unverified.
  */
 /** Max project-source (`module: "."`) docs lookups per worker ATTEMPT. Unset = no cap. */
 export const PROJECT_DOCS_BUDGET_ENV = 'PI_TASK_PROJECT_DOCS_BUDGET';
@@ -99,12 +73,10 @@ export const RESEARCH_LEVER_ENVS = [
  * The levers, read ONCE, as a reader the profile table can be handed.
  *
  * WHY A SNAPSHOT AND NOT `process.env`. Every worker in one research phase must
- * see the same arm. The three lever values used to be resolved once in
- * `phases.ts` and threaded down as three separate `ResearchWorkerRun` fields for
- * exactly that reason; moving the resolution into the `research` profile would
- * have moved the READ down to each worker with it, and a harness that flips a
- * var mid-phase would then half-apply its own arm. Freezing the reader keeps the
- * read-once property while letting the profile own what the values MEAN.
+ * see the same lever values. A profile that read `process.env` itself would move
+ * the read down to each worker, and a var flipped mid-phase would then apply to
+ * some workers and not others. Freezing the reader keeps the read-once property
+ * while letting the profile own what the values MEAN.
  */
 export function snapshotLeverEnv(env = defaultEnv) {
     const snap = new Map(RESEARCH_LEVER_ENVS.map(k => [k, env(k)]));
@@ -149,14 +121,10 @@ export function workerCarryForward(env = defaultEnv) {
 /**
  * The absolute backstop for the progress-based deadline.
  *
- * WHY THIS NUMBER. It is not a budget and it does not decide how long a worker
- * may take — the no-progress deadline does that, and it resets on every tool call.
- * This is the last-resort bound on a worker that never stops moving (an infinite
- * tool-call loop the loop detector somehow misses), so its only requirement is to
- * sit clear of the real workload. Measured on 42 progress-arm trials
- * (`~/tmp/research-fanout-ab-v3`): median 275s, p90 523s, **max 730s**. 20 minutes
- * is 1.6x the observed worst case, and 1.7x the 720s the SHIPPED path already
- * spends on a worker that burns all three attempts and returns nothing.
+ * It is not a budget and it does not decide how long a worker may take — the
+ * no-progress deadline does that, and it resets on every tool call. This is the
+ * last-resort bound on a worker that never stops moving (a tool-call loop the loop
+ * detector misses), so its only requirement is to sit clear of the real workload.
  *
  * A ceiling that never fires in production is the correct behaviour for a
  * backstop, not evidence it is untested: it fires under test
@@ -168,12 +136,7 @@ export const DEFAULT_WORKER_PROGRESS_CEILING_MS = 1_200_000;
 /**
  * The progress-based deadline's ceiling, or null when the lever is OFF.
  *
- * SHIPPED ON as of nexttask 9 — the env var is now the OFF switch, not the on
- * switch. Measured baseline vs progress over 42 trials/arm on a calibrated
- * instrument (A/A false-break 1.5%): worker-timeout restarts 22/24 → 0/24,
- * degrades 8/24 → 0/24, entries up on all four high-fan-out fixtures (TASK_0021
- * 11.0 → 25.5), quality invariants HOLD, every treatment-arm ungrounded flag
- * hand-verified as an instrument artifact rather than a fabrication.
+ * ON by default, so the env var is the OFF switch, not the on switch:
  *
  *     unset            ON at DEFAULT_WORKER_PROGRESS_CEILING_MS
  *     "0" | "off"      OFF — the fixed elapsed-time cap, exactly as before
@@ -194,9 +157,9 @@ export function workerProgressCeilingMs(env = defaultEnv) {
  * The upfront half of the CAP arm, appended to the APIS worker's prompt.
  *
  * Upfront and NUMERIC on purpose. The worker cannot ration a budget it learns
- * about only when it is spent, and "be decisive" — which it already receives on
- * every timeout restart — is exactly the unquantified version that run 18 shows
- * it ignoring until the third attempt.
+ * about only when it is spent, and "be decisive" — WORKER_TIMEOUT_HINT, which it
+ * already receives on every timeout restart — is the unquantified version of the
+ * same ask.
  */
 export function projectDocsBudgetNotice(budget) {
     return (`\n\nLOOKUP BUDGET: you may make at most ${budget} project-source `

package/dist/task/research-worker.d.ts

@@ -1,21 +1,17 @@
 /**
  * ONE research worker, cache-skip to persist.
  *
- * WHY IT IS A MODULE. This was a 228-line closure inside `phaseResearch` over
- * eleven locals, and inside it live the three RETRY GATES and their precedence:
- * the EMPTY-SECTION gate (the only one that can fail the phase), the
- * ZERO-RETRIEVAL gate and the SILENT gate (both of which discard a failed retry
- * and ship the original). Getting that order wrong is how a run either dies on a
- * legitimately empty section or ships one written from memory.
+ * WHY IT IS A MODULE. It holds the three RETRY GATES and their precedence: the
+ * EMPTY-SECTION gate (the only one that can fail the phase), the ZERO-RETRIEVAL
+ * gate and the SILENT gate (both of which discard a failed retry and ship the
+ * original). Getting that order wrong is how a run either dies on a legitimately
+ * empty section or ships one written from memory.
  *
- * The cost was in the TESTS. Reaching the gates meant a temp dir, a real task
- * file, and a fake spawn routed on prose lifted out of `prompts.ts` — plus, for
- * attempt-1-vs-attempt-2, a second sentence lifted out of a module-private
- * preamble constant. In a codebase whose whole workflow is re-wording prompts and
- * measuring what changed, that means a reworded preamble silently stops the gate
- * tests from testing the gate. Behind this interface a test scripts
- * `runWorker(label, attempt)` and states the `RunWorkerResult` fields a gate
- * reads.
+ * Behind `ResearchWorkerRun` a test scripts `runWorker(label, attempt)` and states
+ * the `RunWorkerResult` fields a gate reads. Reaching a gate through the phase
+ * instead would mean a temp dir, a real task file, and a fake spawn routed on
+ * prose lifted out of `prompts.ts` — so re-wording a prompt would silently stop
+ * the gate tests from testing the gate.
  *
  * THE INVARIANT, stated once: the empty gate runs FIRST and is the only one that
  * can throw; the other two keep the original when their retry does not improve a
@@ -27,8 +23,8 @@ import type { SpawnFn } from '../shared/child-process.js';
 import type { DebugLine } from './debug-log.js';
 /**
  * One research worker's row. `section` is the heading its output is assembled
- * and cached under; `label` is its child NAME — what the loader, the debug trail
- * and the A/B ledgers print, and the key into `REASONING_GROUP_BY_CHILD`.
+ * and cached under; `label` is its child NAME — what the loader and the debug
+ * trail print, and the key into `REASONING_GROUP_BY_CHILD` (config/reasoning.ts).
  */
 export interface ResearchWorkerSpec {
     section: string;
@@ -52,7 +48,7 @@ export interface ResearchWorkerSpec {
      *  loop-degrade banner or a hallucinated non-bullet fragment — is re-run ONCE
      *  with this preamble. A legitimately-empty section is NOT retried. */
     retryIfSilent?: string;
-    /** This worker can issue project-source docs lookups, so the 5B fan-out bounds
+    /** This worker can issue project-source docs lookups, so the fan-out bounds
      *  apply to it (see task/research-fanout-budget.ts). */
     fanoutBounded?: true;
 }
@@ -67,9 +63,8 @@ export interface ResearchWorkerRun {
     runWorker: (label: string, input: RunWorkerInput) => Promise<RunWorkerResult>;
     /**
      * The parent session's context window, forwarded to every worker child.
-     * `PhaseDeps.contextWindow` already carried it and this driver dropped it, so
-     * the churn rule was dead for all four workers — see
-     * `RunWorkerInput.contextWindow`.
+     * Nothing in pi's stream reports one, so a child that is not TOLD sits at 0 and
+     * the churn rule cannot fire — see `RunWorkerInput.contextWindow`.
      */
     contextWindow: number | 'unknown';
     cwd: string;
@@ -87,22 +82,20 @@ export interface ResearchWorkerRun {
     /**
      * Read one worker's cached output back, or '' when there is none.
      *
-     * A SEAM, and the symmetric half of `persistSection`. The cache skip is one
-     * of the four outcomes this driver has, and reaching it used to require a
-     * real task file on disk — which is most of why the gate tests needed a temp
-     * dir at all.
+     * A SEAM, and the symmetric half of `persistSection`. The cache skip is one of
+     * the four outcomes this driver has, and reaching it any other way would need a
+     * real task file on disk.
      */
     readCached: (heading: string) => Promise<string>;
     /** Write one validated section to the task file. Serialised by the caller. */
     persistSection: (heading: string, text: string) => Promise<void>;
     /**
-     * The 5B lever env vars, READ ONCE for the whole phase.
+     * The fan-out lever env vars, READ ONCE for the whole phase.
      *
-     * Was three resolved values (`carryForward`, `fanoutTimeout`,
-     * `progressCeilingMs`). It is one frozen reader now because the `research`
-     * profile owns what those values mean; what this layer still owns is that
-     * every worker in a run sees the SAME arm, which a live `process.env` read
-     * per worker would lose. See `snapshotLeverEnv`.
+     * A frozen reader rather than resolved values, because the `research` profile
+     * (workers/worker-profiles.ts) owns what those values MEAN. What this layer
+     * owns is that every worker in one run sees the same values, which a live
+     * `process.env` read per worker would lose. See `snapshotLeverEnv`.
      */
     leverEnv: (key: string) => string | undefined;
 }
@@ -137,15 +130,12 @@ export declare function researchWorkerCacheHeading(section: string): string;
  *     wrote nothing): NOT a failure. On an extremely simple task ("create a folder
  *     with an index.html in it") three of the four workers have genuinely nothing
  *     to report, and each worker prompt tells the model to emit ONLY what this task
- *     touches and to drop everything else — so silence is the CORRECT answer and
- *     was killing the whole task at research (issue #10). Measured live on the
- *     issue's own prompt (30 reps/worker, local Qwen3.6-27B): every APIS answer was
- *     semantically "there is nothing here", and 2/30 were literally zero bytes on a
- *     clean exit — the other 28 survived only because the model happened to wrap the
- *     same non-answer in a parenthetical, which is model style, not signal. The
- *     caller retries once and then accepts an explicit empty section; what stays
- *     fatal is silence WITH a reported cause, which is the masked-disconnect case
- *     this branch was written for and which `modelError` now names outright.
+ *     touches and to drop everything else — so silence is the CORRECT answer, and
+ *     treating it as a failure kills the whole task at research. "Nothing here"
+ *     and zero bytes are the same answer; which one a model writes is style, not
+ *     signal. The caller retries once and then accepts an explicit empty section.
+ *     What stays fatal is silence WITH a reported cause, the masked-disconnect
+ *     case `modelError` names outright.
  *
  * Returns null when the result is trustworthy.
  */

package/dist/task/research-worker.js

@@ -1,21 +1,17 @@
 /**
  * ONE research worker, cache-skip to persist.
  *
- * WHY IT IS A MODULE. This was a 228-line closure inside `phaseResearch` over
- * eleven locals, and inside it live the three RETRY GATES and their precedence:
- * the EMPTY-SECTION gate (the only one that can fail the phase), the
- * ZERO-RETRIEVAL gate and the SILENT gate (both of which discard a failed retry
- * and ship the original). Getting that order wrong is how a run either dies on a
- * legitimately empty section or ships one written from memory.
+ * WHY IT IS A MODULE. It holds the three RETRY GATES and their precedence: the
+ * EMPTY-SECTION gate (the only one that can fail the phase), the ZERO-RETRIEVAL
+ * gate and the SILENT gate (both of which discard a failed retry and ship the
+ * original). Getting that order wrong is how a run either dies on a legitimately
+ * empty section or ships one written from memory.
  *
- * The cost was in the TESTS. Reaching the gates meant a temp dir, a real task
- * file, and a fake spawn routed on prose lifted out of `prompts.ts` — plus, for
- * attempt-1-vs-attempt-2, a second sentence lifted out of a module-private
- * preamble constant. In a codebase whose whole workflow is re-wording prompts and
- * measuring what changed, that means a reworded preamble silently stops the gate
- * tests from testing the gate. Behind this interface a test scripts
- * `runWorker(label, attempt)` and states the `RunWorkerResult` fields a gate
- * reads.
+ * Behind `ResearchWorkerRun` a test scripts `runWorker(label, attempt)` and states
+ * the `RunWorkerResult` fields a gate reads. Reaching a gate through the phase
+ * instead would mean a temp dir, a real task file, and a fake spawn routed on
+ * prose lifted out of `prompts.ts` — so re-wording a prompt would silently stop
+ * the gate tests from testing the gate.
  *
  * THE INVARIANT, stated once: the empty gate runs FIRST and is the only one that
  * can throw; the other two keep the original when their retry does not improve a
@@ -57,15 +53,12 @@ export function researchWorkerCacheHeading(section) {
  *     wrote nothing): NOT a failure. On an extremely simple task ("create a folder
  *     with an index.html in it") three of the four workers have genuinely nothing
  *     to report, and each worker prompt tells the model to emit ONLY what this task
- *     touches and to drop everything else — so silence is the CORRECT answer and
- *     was killing the whole task at research (issue #10). Measured live on the
- *     issue's own prompt (30 reps/worker, local Qwen3.6-27B): every APIS answer was
- *     semantically "there is nothing here", and 2/30 were literally zero bytes on a
- *     clean exit — the other 28 survived only because the model happened to wrap the
- *     same non-answer in a parenthetical, which is model style, not signal. The
- *     caller retries once and then accepts an explicit empty section; what stays
- *     fatal is silence WITH a reported cause, which is the masked-disconnect case
- *     this branch was written for and which `modelError` now names outright.
+ *     touches and to drop everything else — so silence is the CORRECT answer, and
+ *     treating it as a failure kills the whole task at research. "Nothing here"
+ *     and zero bytes are the same answer; which one a model writes is style, not
+ *     signal. The caller retries once and then accepts an explicit empty section.
+ *     What stays fatal is silence WITH a reported cause, the masked-disconnect
+ *     case `modelError` names outright.
  *
  * Returns null when the result is trustworthy.
  */
@@ -125,7 +118,7 @@ export function classifyResearchWorker(name, result) {
         // point of this branch is to tell them apart:
         //
         //   FAILED, cause reported: pi delivers a failed turn as an empty assistant
-        //     message with stopReason "error" and exit 0, so the real cause used to be
+        //     message with stopReason "error" and exit 0, so the real cause would be
         //     discarded and reported as the useless "produced no output". Name it.
         //   FAILED, child never spoke: no stdout at all means the child died before it
         //     could run (unresolvable provider, missing key, bad argv) — it never
@@ -181,10 +174,9 @@ export function emptySectionBody(name) {
 }
 /**
  * A worker answer that IS the word "nothing" and carries no other content:
- * `(none)`, `N/A`, `- none`, `(no content)`, `(no entries)`. Live workers write
- * these often on a task that touches nothing (measured on the issue's prompt:
- * `(no content)`, `(no response)`, a bare `(none)` from the gate's own retry),
- * and each one means exactly what an empty answer means — so they are recorded
+ * `(none)`, `N/A`, `- none`, `(no content)`, `(no entries)`. A worker writes one of
+ * these on a task that touches nothing, and each means exactly what an empty
+ * answer means — so they are recorded
  * with the same marker rather than passed through in whatever shape the model
  * happened to pick. Deliberately NARROW: it matches only a lone token, never
  * prose like "(no APIs to list — this task creates a plain HTML file …)", which
@@ -205,16 +197,9 @@ export function isBareNoneAnswer(text) {
  * fires on a normal project where the first attempt died for an unrelated reason,
  * and an easy opt-out there would silence real research.
  *
- * MEASUREMENT OPEN. The recovery path's QUALITY on a real repo is being measured
- * (scripts live under /home/edgars/tmp/issue10: first FILES answer faulted to
- * empty, every other child live, against an uninterrupted control). First rep on
- * an earlier wording did NOT take the `(none)` exit but drifted into writing code
- * instead of listing paths — the deliverable-not-inputs failure the base prompt
- * already forbids below this preamble. Blast radius is bounded: the gate fires
- * only on a run that would otherwise have FAILED outright, so a mediocre recovered
- * section is strictly better than the dead task it replaces — but if the drift
- * reproduces, this preamble must restate the section's output contract, not just
- * demand an answer.
+ * The blast radius is bounded: this gate fires only on a run that would otherwise
+ * have FAILED outright, so even a mediocre recovered section beats the dead task
+ * it replaces.
  */
 const EMPTY_SECTION_PREAMBLE = 'STOP. Your previous attempt returned an EMPTY answer — zero characters. An empty '
     + 'response cannot be accepted, because it is indistinguishable from a worker that '
@@ -250,21 +235,16 @@ export async function runResearchWorker(spec, run, prior = []) {
         contextWindow: run.contextWindow,
         signal: run.signal,
         spawn: run.spawn,
-        // ONE CELL PER WORKER since 2026-08-28. They used to share
-        // the `research` cell on the grounds that they are the same
-        // job over four questions; the run logs disagree. All 40.7
-        // wasted research minutes in mx5-n were restarts in
-        // `tooling` and `context`, and `files`/`apis` never
-        // restarted — so the level that pays for one pair is being
-        // paid for the other. THE FOUR CELLS DO NOT SHIP IDENTICAL:
-        // `research:files` is `off` on a measured tie while the
-        // other three are `medium`, so this line changes what the
-        // FILES worker runs at for every default-mode user. The
-        // evidence is on each cell in reasoning.ts.
+        // ONE REASONING CELL PER WORKER, keyed on the spec's LABEL —
+        // the four workers ask four different questions and the four
+        // cells do not ship identical. `REASONING_DEFAULTS` in
+        // config/reasoning.ts is where each one's level lives, so this
+        // line decides what THIS worker runs at for a default-mode
+        // user.
         thinking: run.thinkingFor(spec.label),
         ...(spec.tools ? { tools: spec.tools } : {}),
         ...(spec.extensions ? { extensions: spec.extensions } : {}),
-        // The three 5B lever spreads that used to sit here are the
+        // The three lever spreads that would otherwise sit here are the
         // `research` row of WORKER_PROFILES (workers/worker-profiles.ts).
         // Two facts still come from here, and only these two: which of
         // the four workers is docs-capable (only it can be scaled), and
@@ -276,10 +256,8 @@ export async function runResearchWorker(spec, run, prior = []) {
             env: run.leverEnv
         },
         // One line per DISCARDED attempt. The `done` line below reports
-        // the final attempt only, so a worker that timed out twice at
-        // 240s and then answered used to log exactly like a clean one —
-        // 8 minutes of burned compute recoverable only by subtracting
-        // its own wait+work from the start/done timestamps.
+        // the FINAL attempt only, so without these a worker that timed
+        // out twice and then answered logs exactly like a clean one.
         onCarryForward: ci => {
             run.logDebug?.(`${spec.label}: CARRY-FORWARD injected into attempt ${ci.attempt}`
                 + ` (${ci.chars} chars onto a ${ci.promptCharsBefore}-char prompt)`);
@@ -301,8 +279,8 @@ export async function runResearchWorker(spec, run, prior = []) {
         }
     }));
     let r = await runOnce();
-    // EMPTY-SECTION GATE (issue #10). A worker that returns zero bytes on a clean run
-    // used to fail the whole task ("Research APIS worker produced no output"), which is
+    // EMPTY-SECTION GATE. A worker that returns zero bytes on a clean run
+    // would fail the whole task ("Research APIS worker produced no output"), which is
     // exactly what an extremely simple task provokes: with nothing on disk to survey and
     // no external symbol in play, silence is the correct answer and the run died on it.
     // Retry ONCE — silence is genuinely ambiguous, and a worker that crashed before
@@ -396,11 +374,9 @@ export async function runResearchWorker(spec, run, prior = []) {
         + (r.restarts.length > 0 ?
             ` restarts=[${r.restarts.map(x => x.reason).join(',')}]`
             : '')
-        // Attribution for the RESCUE arm: a run with zero restarts was
-        // never killed (the progress deadline did it), while a run that
-        // restarted and salvaged was killed but kept its work. Without
-        // this the two are indistinguishable in the logs, and "0
-        // timeouts" cannot be traced to the half that earned it.
+        // A run with zero restarts was never killed; a run that restarted
+        // and salvaged WAS killed but kept its work. Without this flag the
+        // two are indistinguishable in the log.
         + (r.salvagedFromDiscardedAttempt ? ' salvaged=1' : '')
         + (r.stderr ? ` stderr=${r.stderr.slice(0, 300)}` : '')
         + (r.leakedToolCall ? ` leaked=${r.leakedToolCall.trim().slice(0, 80)}` : ''));

package/dist/task/resume-gap.d.ts

@@ -1,25 +1,24 @@
 /**
  * Resume gating & the honest resume banner.
  *
- * mx5 run 14 lost ~10 hours to dead air that looked like a stall: the host was
- * powered off overnight, both containers stopped at 20:00Z, and the run picked
- * up cleanly the moment they were restarted at 06:01Z. Nothing was wrong with
- * the run — the only defect was that nobody could tell. Two things follow.
+ * A host that is powered off mid-run produces dead air that looks exactly like a
+ * stall. Nothing is wrong with the run; the defect is that nobody can tell. Two
+ * things follow.
  *
- * (1) A restart-time resume can be automated (`restart: unless-stopped` on the
- * containers plus a boot hook that runs `/task-auto-resume --unattended`), which
- * turns that 10h of nothing into minutes.
+ * (1) A restart-time resume can be automated — a boot hook that runs
+ * `/task-auto-resume --unattended` (the flag auto-orchestrator.ts parses).
  *
  * (2) An automated resume must not resume everything. `RESUMABLE_STATES`
- * deliberately includes `failed` and `cancelled` because a HUMAN typing
- * /task-auto-resume has decided to continue; a boot hook has decided nothing. A
- * failed run stopped for a reason a power cycle does not clear, and re-entering
- * it unattended burns the whole loop against the same wall. Unattended resume
- * therefore covers in-flight states only (see UNATTENDED_STATES), and refuses
- * the rest by name rather than silently doing nothing.
+ * (task-types.ts) deliberately includes `failed` and `cancelled`, because a HUMAN
+ * typing /task-auto-resume has decided to continue; a boot hook has decided
+ * nothing. A failed run stopped for a reason a power cycle does not clear, and
+ * re-entering it unattended burns the whole loop against the same wall.
+ * Unattended resume therefore covers in-flight states only (see
+ * UNATTENDED_STATES), and refuses the rest BY NAME rather than silently doing
+ * nothing.
  *
- * The banner follows the honest-restart-hint rule (70a8497): say exactly what
- * was observed and exactly what it does not tell you. All this process knows is
+ * The banner says exactly what was observed and exactly what it does not tell
+ * you. All this process knows is
  * when the AUTO file was last written — it cannot distinguish a stopped host
  * from a hung child from a slow task, so it reports the gap and attributes no
  * cause. It is equally careful about the tree: nothing is rolled back between

package/dist/task/root-cause-repair.d.ts

@@ -87,10 +87,11 @@ export interface MergedRepair {
     verifyCommand?: string;
 }
 /**
- * Collapse candidates by file — MANDATORY dedup: run 14's two teardown.ts debts
- * (TASK_0013, TASK_0019) must yield exactly ONE repair task naming both. First
- * record wins for defect/command (they describe the same fault); blamed tasks
- * accumulate in first-seen order.
+ * Collapse candidates by file — MANDATORY dedup: two debts naming the same file
+ * must yield exactly ONE repair task naming both blamed tasks. Keyed on the
+ * NORMALISED path, so `./x.ts` and `x.ts` are one entry. First record wins for
+ * defect and command (they describe the same fault); blamed tasks accumulate in
+ * first-seen order.
  */
 export declare function mergeRepairCandidates(candidates: RepairCandidate[]): MergedRepair[];
 /** Machine-recognisable prefix, so a repair entry can be found in a plan again. */
@@ -112,11 +113,10 @@ export declare function parseRepairTitleFile(title: string): string | null;
  */
 export declare function planHasRepairFor(titles: string[], file: string): boolean;
 /**
- * The extra scope fence a repair entry carries into refine. Without it, refine
- * re-expands "repair test/teardown.ts: parameterized table names in TRUNCATE"
- * into "overhaul the test infrastructure" — the /task-auto drift lesson. The
- * fence pins the single editable file and pins the VERIFY to the exact command
- * the debt failed on.
+ * The extra scope fence a repair entry carries into refine. A repair title names
+ * one file and one narrow defect, which refine will otherwise re-expand into
+ * "overhaul the test infrastructure". The fence pins the single editable file and
+ * pins the VERIFY to the exact command the debt failed on.
  */
 export declare function buildRepairScopeFence(file: string, verifyCommand?: string): string;
 export {};