@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/workers/single-read-guard.d.ts

@@ -1,34 +1,30 @@
 /**
- * In-process thrash guards for the TOOLING research worker.
+ * In-process thrash guards, armed by single-read-extension.ts in the TOOLING
+ * research worker and the planning children.
  *
- * Two guards, one mechanism — deny a wasteful repeat *inside the run* (the
+ * Two guards, one mechanism — deny a wasteful repeat *inside the run*. The
  * extension returns the block from a `tool_call` handler, pi feeds `reason` back
- * as an error tool result, the worker continues). No kill, no restart: detect-
- * and-kill only re-spawns a model that deterministically re-thrashes.
+ * as an error tool result, and the child continues. No kill, no restart:
+ * detect-and-kill only re-spawns a model that deterministically re-thrashes.
  *
- *   - SingleReadGuard: "read each LINE of a file once". Validated against every
- *     recorded mx5 run — a healthy TOOLING worker reads each file exactly once
- *     (max same-file reads = 1 across 7 tasks). TASK_0017 re-read one file 50×.
+ *   - SingleReadGuard: "read each LINE of a file once".
  *
- *     It used to key on the resolved path alone, blocking any second read
- *     "regardless of offset". That made a file bigger than one read into a trap.
- *     Measured 2026-08-17 on a captured auto-decompose request: the planner asked
- *     for `DESIGN/marketplace.html` with `limit: 80` — the first 80 lines of 743,
- *     deliberately paging — and its request for offset 80 was refused. It never
- *     reached the end of the file, and spent the rest of the run asking for the
- *     remainder: 197 of 200 tool calls were this guard's own refusal. The guard
- *     did not stop a thrash, it CAUSED one.
+ *     Keying on the resolved path alone — blocking any second read regardless of
+ *     offset — turns a file bigger than one read into a TRAP. A child paging
+ *     deliberately, first 80 lines then the next 80, has its second request
+ *     refused; it never reaches the end of the file and spends the rest of the run
+ *     asking for the remainder. That guard does not stop a thrash, it causes one.
  *
- *     So the unit is the line range, not the file. A request that extends past
- *     the furthest line already delivered is forward paging and passes; one that
- *     lies entirely within ground already delivered is a re-read and is blocked.
+ *     So the unit is the line range, not the file. A request that extends past the
+ *     furthest line already delivered is forward paging and passes; one that lies
+ *     entirely within ground already delivered is a re-read and is blocked.
  *
- *   - RepeatedCallGuard: "no identical search twice", for grep/find/ls. TASK_0017
- *     also looped on grep({pattern:"^\\s*}",path:".../index.ts"}) ×5 — a path the
- *     read guard never covered, so the call fell back to the ineffective detect→
- *     restart path. Keyed on (toolName, stableStringify(args)) — the *same* key
- *     the LoopDetector uses — so only byte-identical repeats trip; a legitimately
- *     different grep pattern on the same file still passes.
+ *   - RepeatedCallGuard: "no identical search twice", for grep/find/ls — the
+ *     shapes the read guard cannot see, such as the same grep pattern re-run
+ *     against the same path. Keyed on `${toolName}\0${stableStringify(args)}`,
+ *     byte-identical to the key `LoopDetector.record` builds, so argument key
+ *     order never causes a miss and only an identical repeat trips. A different
+ *     pattern on the same file still passes.
  *
  * Pure logic, no I/O — the extension does path resolution and tool routing.
  */
@@ -40,10 +36,11 @@ export interface ReadBlock {
  * The error text the model receives in place of the re-read's contents.
  *
  * It must say what to do NEXT, and the honest next move depends on whether there
- * is any of the file left: with `covered` lines already delivered, asking for
- * line `covered + 1` is always allowed, so the message says so. The old wording
- * ("Do not read it again") was a dead end for a model that was mid-way through a
- * file — it had nowhere legal to go and kept asking anyway.
+ * is any of the file left: with `covered` lines already delivered, asking for line
+ * `covered + 1` is always allowed, so the message says so. A bare "do not read it
+ * again" is a dead end for a model mid-way through a file — it has nowhere legal
+ * to go and keeps asking anyway. A read that reached EOF has `covered` set to
+ * Infinity and gets the other wording, with no line to resume from.
  */
 export declare function singleReadReason(path: string, covered: number): string;
 export declare class SingleReadGuard {

package/dist/workers/single-read-guard.js

@@ -1,34 +1,30 @@
 /**
- * In-process thrash guards for the TOOLING research worker.
+ * In-process thrash guards, armed by single-read-extension.ts in the TOOLING
+ * research worker and the planning children.
  *
- * Two guards, one mechanism — deny a wasteful repeat *inside the run* (the
+ * Two guards, one mechanism — deny a wasteful repeat *inside the run*. The
  * extension returns the block from a `tool_call` handler, pi feeds `reason` back
- * as an error tool result, the worker continues). No kill, no restart: detect-
- * and-kill only re-spawns a model that deterministically re-thrashes.
+ * as an error tool result, and the child continues. No kill, no restart:
+ * detect-and-kill only re-spawns a model that deterministically re-thrashes.
  *
- *   - SingleReadGuard: "read each LINE of a file once". Validated against every
- *     recorded mx5 run — a healthy TOOLING worker reads each file exactly once
- *     (max same-file reads = 1 across 7 tasks). TASK_0017 re-read one file 50×.
+ *   - SingleReadGuard: "read each LINE of a file once".
  *
- *     It used to key on the resolved path alone, blocking any second read
- *     "regardless of offset". That made a file bigger than one read into a trap.
- *     Measured 2026-08-17 on a captured auto-decompose request: the planner asked
- *     for `DESIGN/marketplace.html` with `limit: 80` — the first 80 lines of 743,
- *     deliberately paging — and its request for offset 80 was refused. It never
- *     reached the end of the file, and spent the rest of the run asking for the
- *     remainder: 197 of 200 tool calls were this guard's own refusal. The guard
- *     did not stop a thrash, it CAUSED one.
+ *     Keying on the resolved path alone — blocking any second read regardless of
+ *     offset — turns a file bigger than one read into a TRAP. A child paging
+ *     deliberately, first 80 lines then the next 80, has its second request
+ *     refused; it never reaches the end of the file and spends the rest of the run
+ *     asking for the remainder. That guard does not stop a thrash, it causes one.
  *
- *     So the unit is the line range, not the file. A request that extends past
- *     the furthest line already delivered is forward paging and passes; one that
- *     lies entirely within ground already delivered is a re-read and is blocked.
+ *     So the unit is the line range, not the file. A request that extends past the
+ *     furthest line already delivered is forward paging and passes; one that lies
+ *     entirely within ground already delivered is a re-read and is blocked.
  *
- *   - RepeatedCallGuard: "no identical search twice", for grep/find/ls. TASK_0017
- *     also looped on grep({pattern:"^\\s*}",path:".../index.ts"}) ×5 — a path the
- *     read guard never covered, so the call fell back to the ineffective detect→
- *     restart path. Keyed on (toolName, stableStringify(args)) — the *same* key
- *     the LoopDetector uses — so only byte-identical repeats trip; a legitimately
- *     different grep pattern on the same file still passes.
+ *   - RepeatedCallGuard: "no identical search twice", for grep/find/ls — the
+ *     shapes the read guard cannot see, such as the same grep pattern re-run
+ *     against the same path. Keyed on `${toolName}\0${stableStringify(args)}`,
+ *     byte-identical to the key `LoopDetector.record` builds, so argument key
+ *     order never causes a miss and only an identical repeat trips. A different
+ *     pattern on the same file still passes.
  *
  * Pure logic, no I/O — the extension does path resolution and tool routing.
  */
@@ -37,10 +33,11 @@ import { stableStringify } from '../task/loop-detector.js';
  * The error text the model receives in place of the re-read's contents.
  *
  * It must say what to do NEXT, and the honest next move depends on whether there
- * is any of the file left: with `covered` lines already delivered, asking for
- * line `covered + 1` is always allowed, so the message says so. The old wording
- * ("Do not read it again") was a dead end for a model that was mid-way through a
- * file — it had nowhere legal to go and kept asking anyway.
+ * is any of the file left: with `covered` lines already delivered, asking for line
+ * `covered + 1` is always allowed, so the message says so. A bare "do not read it
+ * again" is a dead end for a model mid-way through a file — it has nowhere legal
+ * to go and keeps asking anyway. A read that reached EOF has `covered` set to
+ * Infinity and gets the other wording, with no line to resume from.
  */
 export function singleReadReason(path, covered) {
     if (!Number.isFinite(covered)) {
@@ -53,7 +50,8 @@ export function singleReadReason(path, covered) {
         + `starting at line ${covered + 1}; otherwise use what you have already gathered and `
         + `write your final answer now.`);
 }
-/** Default `limit` pi's read tool applies when the call names none. */
+/** pi's own read truncation ceiling (`DEFAULT_MAX_LINES` in its truncate.js): a
+ *  read that names no `limit` returns at most this many lines. */
 const DEFAULT_READ_LIMIT = 2000;
 /** The 1-based line a read starts at (`offset` absent or junk means line 1). */
 function startLine(offset) {
@@ -62,9 +60,11 @@ function startLine(offset) {
         : 1;
 }
 /**
- * The last line a read reaches. A `limit` of exactly the tool default is treated
- * as "no limit given" — indistinguishable at this layer, and the safe reading is
- * the generous one, since blocking honest paging is the failure this guard had.
+ * The last line a read reaches, or Infinity when the read is unbounded. A `limit`
+ * at or above pi's own ceiling is treated as "no limit given" — indistinguishable
+ * at this layer — and so is a `limit` that is absent, zero, negative or not a
+ * number. The generous reading is the safe one, since blocking honest paging is
+ * the failure mode this guard has.
  */
 function endLine(start, limit) {
     if (typeof limit !== 'number' || !Number.isFinite(limit) || limit <= 0)

package/dist/workers/typeonly-log.d.ts

@@ -23,12 +23,12 @@ export interface TypeOnlyLogRecord {
      * The FULL verification record behind `excerptVerified` — the normalised excerpt that was
      * searched for, plus a sha256 + length of the normalised content it was searched in.
      *
-     * This is the other half of the F-3(f) hole described above: retaining the answer text
-     * says WHAT was claimed, and this says what it was checked against, so a false verdict can
-     * be attributed to fabrication (the excerpt is nowhere near the content) rather than a
-     * normaliser gap (a markdown-escape variant of text that IS present) without re-running
-     * the lookup. Only fetch's extractor used to keep it; all four focused-extractor call
-     * sites now can (workers/focused-extractor.ts). Optional — records predating it parse.
+     * The other half of the retention above: the answer text says WHAT was claimed, and
+     * this says what it was checked against — so a false verdict can be attributed to
+     * fabrication (the excerpt is nowhere near the content) rather than to a normaliser
+     * gap (a markdown-escape variant of text that IS present) without re-running the
+     * lookup. focused-extractor.ts hands the struct to both of its call sites.
+     * Optional — older records still parse.
      */
     excerptCheck?: ExcerptVerification;
     /**
@@ -50,9 +50,12 @@ export interface TypeOnlyLogRecord {
 /**
  * Append one record to the JSONL sink named by `PI_TASK_TYPEONLY_LOG`, if set.
  *
- * @param rec everything but `at` and `unclear`, which are derived here so every call site
- *            stamps them identically.
+ * @param rec everything but `at` (an ISO timestamp) and `unclear` (the abstention
+ *            predicate over `answer`), which are derived here so both call sites in
+ *            pi-worker-docs stamp them identically.
  */
 export declare function logDocsAnswer(rec: Omit<TypeOnlyLogRecord, 'at' | 'unclear'>, getEnv?: (k: string) => string | undefined): void;
-/** Parse a sink written by {@link logDocsAnswer}; malformed lines are skipped, not thrown. */
+/** Parse a sink written by {@link logDocsAnswer}. Blank lines are skipped and a
+ *  malformed one — including the truncated tail a killed process leaves — is dropped
+ *  rather than thrown. */
 export declare function readTypeOnlyLog(text: string): TypeOnlyLogRecord[];

package/dist/workers/typeonly-log.js

@@ -1,40 +1,33 @@
 /**
- * STAGE 1 INSTRUMENTATION for F-2 / PROMPT 2 — firing-rate observability, no behaviour.
+ * Firing-rate instrumentation for the TYPE-ONLY detector. Observability only; it
+ * changes no behaviour.
  *
- * WHY THIS EXISTS. PROMPT 2's live A/B measured 82% baseline vs 91% treatment, p = 0.88,
- * and was written off as "the lever does not work". It was a broken EXPERIMENT, and it was
- * broken for a reason this module fixes: the metric counted ALL research terminations while
- * the lever touches only TYPE-ONLY answers, and nothing anywhere recorded how often a
- * type-only answer actually occurs. The causal claim "workers stop BECAUSE of type-only
- * answers" was asserted from one static corpus (1 flag in 150 recorded answers, 0.7%) and
- * never measured live. You cannot size an arm, pick a metric, or decide whether the lever is
- * a population fix or a single-case guard without that firing rate.
+ * WHY THIS EXISTS. "How often does a type-only answer occur" cannot be answered by
+ * counting the times the detector FIRED — a log of firings has no denominator. So
+ * every pi-worker-docs answer is recorded, flagged or not, and the rate is
+ * computable rather than inferable.
  *
- * WHAT IT DOES. When `PI_TASK_TYPEONLY_LOG` names a file, every pi-worker-docs answer — not
- * only the flagged ones — appends one JSON line there. Denominator and numerator both, from
- * the same channel, so a rate is computable rather than inferable. With the variable unset
- * this is a no-op and nothing is written.
+ * WHAT IT DOES. When `PI_TASK_TYPEONLY_LOG` names a file, each answer appends one
+ * JSON line there. Unset or blank and this is a no-op that writes nothing.
  *
- * MECHANICAL, NOT SELF-REPORT. The record is written at the TOOL layer from the verdict the
- * shipped detector just returned, next to the same `details` the caller receives. No model is
- * asked whether it thought the answer was a type signature.
+ * MECHANICAL, NOT SELF-REPORT. The record is written at the TOOL layer from the
+ * verdict the shipped detector just returned, next to the same `details` the caller
+ * receives. No model is asked whether it thought the answer was a type signature.
  *
- * BEHAVIOUR-NEUTRALITY IS THE WHOLE POINT — this lands in a stage that forbids src/ behaviour
- * change, so:
+ * BEHAVIOUR-NEUTRAL BY CONSTRUCTION:
  *   - it is called for its side effect only; nothing reads its return value;
- *   - every failure is swallowed (a full disk or an unwritable path must not turn a working
- *     docs lookup into an error — instrumentation that can break the thing it measures is
- *     worse than no instrumentation);
- *   - it appends synchronously, because the process that writes it (a pi child running the
- *     docs extension) can exit immediately after the tool returns and a queued async write
- *     would be lost.
+ *   - every failure is swallowed. A full disk or an unwritable path must not turn a
+ *     working docs lookup into an error — instrumentation that can break the thing
+ *     it measures is worse than none;
+ *   - it appends SYNCHRONOUSLY, because the process that writes it is a pi child
+ *     that can exit the moment the tool returns, and a queued async write would be
+ *     lost.
  *
- * THE FULL ANSWER TEXT IS RETAINED, deliberately. Run 15's audit could not decide F-3(f) —
- * whether an `excerptVerified === false` was fabrication or a normaliser gap — because the
- * text it judged was kept nowhere. The same hole would make every stability question here
- * unanswerable: whether a question is type-only in EVERY rep or churns between identical
- * reps can only be settled by re-scoring the recorded answers. Cheap to keep, impossible to
- * reconstruct later.
+ * THE FULL ANSWER TEXT IS RETAINED, deliberately. Without it, an
+ * `excerptVerified === false` cannot afterwards be attributed to fabrication rather
+ * than to a normaliser gap, and "is this question type-only every time or does it
+ * churn between identical runs" cannot be settled at all — both need the recorded
+ * answers re-scored. Cheap to keep, impossible to reconstruct later.
  */
 import * as fs from 'node:fs';
 import { isAbstention } from './abstention.js';
@@ -43,8 +36,9 @@ export const TYPEONLY_LOG_ENV = 'PI_TASK_TYPEONLY_LOG';
 /**
  * Append one record to the JSONL sink named by `PI_TASK_TYPEONLY_LOG`, if set.
  *
- * @param rec everything but `at` and `unclear`, which are derived here so every call site
- *            stamps them identically.
+ * @param rec everything but `at` (an ISO timestamp) and `unclear` (the abstention
+ *            predicate over `answer`), which are derived here so both call sites in
+ *            pi-worker-docs stamp them identically.
  */
 export function logDocsAnswer(rec, getEnv = k => process.env[k]) {
     const sink = getEnv(TYPEONLY_LOG_ENV);
@@ -63,7 +57,9 @@ export function logDocsAnswer(rec, getEnv = k => process.env[k]) {
         // succeeded must not be reported as failed because the sink was unwritable.
     }
 }
-/** Parse a sink written by {@link logDocsAnswer}; malformed lines are skipped, not thrown. */
+/** Parse a sink written by {@link logDocsAnswer}. Blank lines are skipped and a
+ *  malformed one — including the truncated tail a killed process leaves — is dropped
+ *  rather than thrown. */
 export function readTypeOnlyLog(text) {
     const out = [];
     for (const line of text.split('\n')) {

package/dist/workers/worker-channels.d.ts

@@ -1,28 +1,19 @@
 /**
  * worker-channels — what a worker TOOL is, as data.
  *
- * `makeWorkerTool` already gives every worker tool one registration adapter, but
- * `spec.name` never left the registration closure. So the same four name strings
- * were re-typed as literals in three directories and had to agree by hand:
+ * `makeWorkerTool` gives every worker tool one registration adapter, but
+ * `spec.name` never leaves that closure. Without this table the three tool names
+ * are re-typed as literals wherever anything else needs them: the tools string
+ * and its matching `-e` path list, the grounding set, the debug-log summary and
+ * its per-tool parameter shape, and — worst for locality — the GENERIC child
+ * runner, which would have to name one tool AND one of its parameters to decide a
+ * fan-out deadline extension. Nothing links those edits at compile time. Here
+ * each tool is one row.
  *
- *   • `phases.ts` paired `'…,pi-worker-docs'` with `DOCS_EXTENSION_PATH`, and
- *     `',pi-worker-search,pi-worker-fetch'` with `SEARCH_EXTENSION_PATH` — a tools
- *     string and an `-e` path list that mean the same thing, written twice and
- *     kept in step by eye.
- *   • `GROUNDING_RETRIEVAL_TOOLS` was a second copy of the names.
- *   • `summarizeToolArgs` was a third, and also re-stated each tool's parameter
- *     shape (`module`/`query`, `query`, `url`).
- *   • Worst for locality: `runWorker` — the GENERIC child runner — hardcoded one
- *     tool's identity AND its parameter, `call.name === 'pi-worker-docs' &&
- *     args.module === '.'`, to decide a fan-out deadline extension.
- *
- * A rename or a new tool was five edits in three directories with no compile
- * error linking them. It is one row here now.
- *
- * What is NOT in a row: the tools string's non-worker members (`read`, `grep`,
- * `find`, `ls`) are pi's own built-ins, not channels — they appear in
- * {@link GROUNDING_RETRIEVAL_TOOLS} because grounding is about RETRIEVAL, not
- * about which extension supplies it.
+ * What is NOT a row: pi's own built-ins. `read` and `grep` are listed in
+ * {@link GROUNDING_RETRIEVAL_TOOLS} because grounding is about RETRIEVAL rather
+ * than about which extension supplies it, while `find` and `ls` return names only
+ * and are excluded from it.
  */
 /** One worker tool, and everything the rest of the codebase knows about it. */
 export interface WorkerChannel {
@@ -49,8 +40,9 @@ export declare const WORKER_CHANNELS: readonly WorkerChannel[];
 export declare function workerChannel(toolName: string): WorkerChannel | undefined;
 /**
  * The tools string and the `-e` paths for a set of channels, together — they are
- * one fact and used to be two literals. Entry paths are de-duplicated: search and
- * fetch ship in one extension file.
+ * one fact, and two literals would drift. The tools string preserves the order it
+ * was asked for; entry paths are de-duplicated, so asking for search AND fetch
+ * yields ONE path, since both ship in search-extension.js.
  */
 export declare function channelSet(names: readonly string[]): {
     tools: string;

package/dist/workers/worker-channels.js

@@ -1,28 +1,19 @@
 /**
  * worker-channels — what a worker TOOL is, as data.
  *
- * `makeWorkerTool` already gives every worker tool one registration adapter, but
- * `spec.name` never left the registration closure. So the same four name strings
- * were re-typed as literals in three directories and had to agree by hand:
+ * `makeWorkerTool` gives every worker tool one registration adapter, but
+ * `spec.name` never leaves that closure. Without this table the three tool names
+ * are re-typed as literals wherever anything else needs them: the tools string
+ * and its matching `-e` path list, the grounding set, the debug-log summary and
+ * its per-tool parameter shape, and — worst for locality — the GENERIC child
+ * runner, which would have to name one tool AND one of its parameters to decide a
+ * fan-out deadline extension. Nothing links those edits at compile time. Here
+ * each tool is one row.
  *
- *   • `phases.ts` paired `'…,pi-worker-docs'` with `DOCS_EXTENSION_PATH`, and
- *     `',pi-worker-search,pi-worker-fetch'` with `SEARCH_EXTENSION_PATH` — a tools
- *     string and an `-e` path list that mean the same thing, written twice and
- *     kept in step by eye.
- *   • `GROUNDING_RETRIEVAL_TOOLS` was a second copy of the names.
- *   • `summarizeToolArgs` was a third, and also re-stated each tool's parameter
- *     shape (`module`/`query`, `query`, `url`).
- *   • Worst for locality: `runWorker` — the GENERIC child runner — hardcoded one
- *     tool's identity AND its parameter, `call.name === 'pi-worker-docs' &&
- *     args.module === '.'`, to decide a fan-out deadline extension.
- *
- * A rename or a new tool was five edits in three directories with no compile
- * error linking them. It is one row here now.
- *
- * What is NOT in a row: the tools string's non-worker members (`read`, `grep`,
- * `find`, `ls`) are pi's own built-ins, not channels — they appear in
- * {@link GROUNDING_RETRIEVAL_TOOLS} because grounding is about RETRIEVAL, not
- * about which extension supplies it.
+ * What is NOT a row: pi's own built-ins. `read` and `grep` are listed in
+ * {@link GROUNDING_RETRIEVAL_TOOLS} because grounding is about RETRIEVAL rather
+ * than about which extension supplies it, while `find` and `ls` return names only
+ * and are excluded from it.
  */
 import { fileURLToPath } from 'node:url';
 const DOCS_ENTRY = fileURLToPath(new URL('./docs-extension.js', import.meta.url));
@@ -64,8 +55,9 @@ export function workerChannel(toolName) {
 }
 /**
  * The tools string and the `-e` paths for a set of channels, together — they are
- * one fact and used to be two literals. Entry paths are de-duplicated: search and
- * fetch ship in one extension file.
+ * one fact, and two literals would drift. The tools string preserves the order it
+ * was asked for; entry paths are de-duplicated, so asking for search AND fetch
+ * yields ONE path, since both ship in search-extension.js.
  */
 export function channelSet(names) {
     // REFUSED, not dropped. Silently skipping an unrecognised name is the exact

package/dist/workers/worker-failure.d.ts

@@ -5,35 +5,34 @@
  * Why this module exists. `RunWorkerResult` reports each kill cause as its own
  * optional field (`loopHit`, `timedOut`, `stalled`, `commandTimedOut`,
  * `streamStalled`, `leakedToolCall`, `aborted`, `exitCode`), and every kill path
- * ALSO sets `aborted` and a non-zero exit — killProc flips those on every route
- * out. So a consumer cannot read the fields in any order it likes: the specific
- * causes must be matched before the generic `aborted`/`exitCode` ones, or a dead
- * backend is reported to the user as "you cancelled".
+ * ALSO sets the two generic ones. `killProc` sets `aborted` on every route out,
+ * and pi's own print/json mode installs a SIGTERM handler that exits 143, so a
+ * terminated child carries a non-zero exit too. So a consumer cannot read the
+ * fields in any order it likes: the specific causes must be matched before the
+ * generic `aborted`/`exitCode` ones, or a dead backend is reported to the user as
+ * "you cancelled".
  *
- * That rule used to live as prose in three doc comments and as the source order
- * of three hand-written ladders (`classifyEnforceChildFailure`,
- * `classifyResearchWorker`, and the gate's own reading). Three copies of an
- * ordering is three chances to drift, and it had already drifted: `streamStalled`
- * was added to the result and to `finalAttemptFailed`, but the enforce ladder
- * never grew an arm for it, so an enforcement child killed for a hung model
- * stream fell all the way through to `if (aborted) return USER_CANCELLED` — the
- * exact mislabel the comment above that line warns against.
+ * Written as prose, or as the source order of each consumer's own hand-rolled
+ * ladder, that rule gets a fresh chance to drift per consumer — and the failure is
+ * silent: add a new kill cause to the result, forget one ladder's arm for it, and
+ * that consumer falls through to `if (aborted)` and reports a cancel.
  *
- * The fix is to make the order data. `FAILURE_RULES` is ordered, the first
- * matching row wins, and consumers `switch` on the resulting `kind` instead of
- * re-deriving the ladder. A new kill cause is one row here plus a compile error
- * in every consumer that has not handled it — which is what makes the drift that
- * caused the bug impossible rather than merely fixed.
+ * So the order is DATA. `FAILURE_RULES` is ordered, the first matching row wins,
+ * and consumers `switch` on the resulting `kind` — `classifyEnforceChildFailure`
+ * (enforce-guidelines.ts) and `classifyResearchWorker` (research-worker.ts) both
+ * call `classifyWorkerFailure` and say only what each cause means to THEM. A new
+ * kill cause is one row here plus a compile error in every consumer that has not
+ * handled it.
  */
 import type { LoopHit } from '../task/loop-detector.js';
 import type { WorkerKillId } from './worker-kill.js';
 /**
  * The subset of a finished child result this classification reads.
  *
- * Structural on purpose: `runWorker` returns a superset, and
- * `EnforceChildResult` is a hand-written narrowing of the same shape. Typing the
- * input as what is actually READ lets both pass without either importing the
- * other's interface.
+ * Structural on purpose: `runWorker` returns a superset, and `EnforceChildResult`
+ * extends this interface with the one field enforcement adds. Typing the input as
+ * what is actually READ lets both pass without either importing the other's
+ * interface.
  */
 export interface WorkerFailureInput {
     exitCode: number;
@@ -55,9 +54,9 @@ export interface WorkerFailureInput {
  *
  * Note what is NOT here: an empty answer, and a reported `modelError` on a run
  * that still produced text. Neither is a kill — whether they count as a failure
- * is the consumer's policy (research accepts a genuinely empty section; the gate
- * does not), so folding them in would move a decision out of the module that
- * owns it.
+ * is the consumer's policy — research-worker.ts, for one, accepts an explicit
+ * empty section after a retry — so folding them in would move a decision out of
+ * the module that owns it.
  */
 export type WorkerFailure = {
     kind: 'stalled';
@@ -102,9 +101,8 @@ export type WorkerFailureKind = WorkerFailure['kind'];
  *     class of event: a watchdog, not the model, ended the attempt.
  *  4. `worker-timeout` — the wall-clock backstop.
  *  5. `loop` — killed for repeating one tool call past threshold. After the
- *     timeouts, matching the enforce ladder this replaces; in practice the two
- *     cannot both fire, since a loop kill stops the attempt before its own timer
- *     can expire.
+ *     timeouts: a loop kill ends the attempt, so its own timer does not go on to
+ *     expire as well.
  *  6. `leaked-tool-call` — the model wrote a call as prose instead of invoking
  *     it. Only ever set on an otherwise clean run.
  *  7. `aborted` — no specific cause survived, so this really is a cancel.
@@ -117,35 +115,29 @@ export declare const FAILURE_RULES: ReadonlyArray<{
     id: WorkerKillId;
     match: (r: WorkerFailureInput) => WorkerFailure | null;
 }>;
-/**
- * Classify a finished child. Returns `undefined` when nothing killed it —
- * which is not the same as "it answered": the text may still be empty, and that
- * judgement belongs to the caller.
- */
 /**
  * What a worker failure SAYS to the caller that asked for the work.
  *
- * WHY IT EXISTS. The ladder above already names the cause exactly, with its
- * detail — which tool hung, how long the stream was idle, which exit code. None
- * of that reached a human. `formatChildFailure` was handed a `ChildOutcome`
- * (`{aborted, exitCode, stderr}`) and answered `if (aborted) return
- * abortedMessage`, so a 240s wall-clock kill, a hung `bash`, a dead model
- * backend, a loop kill and a user pressing ESC all printed the SAME four words.
- * The discriminating value was computed a line later by `childFailureReason` and
- * put in the debug trail, which a user reading a tool result never sees.
- *
- * That is not only unhelpful; it is why the `pi-worker` tool's 240s cap has no
- * base rate. 53 recorded invocations across eight repos carry 14 failures, and
- * NOTHING in the transcript says which of them ran out of time — the honest
- * bound recoverable from timestamps alone is "somewhere between 0 and 8".
+ * WHY IT EXISTS. The ladder above already names the cause exactly, with its detail
+ * — which tool hung, how long the stream was idle, which exit code. Answering
+ * `if (aborted) return abortedMessage` instead throws all of it away: a wall-clock
+ * kill, a hung `bash`, a dead model backend, a loop kill and a user pressing ESC
+ * then print the SAME words, and the discriminating value only reaches a debug
+ * trail a user reading a tool result never sees. Every arm below returns a
+ * different message, and only `aborted` returns the caller's own.
  *
  * A switch, not a table: `WorkerFailure` is a discriminated union carrying a
  * different payload per arm, so the exhaustiveness check is the compiler's and a
- * ninth arm cannot be added without a message.
+ * new arm cannot be added without a message.
  */
 export declare function describeWorkerFailure(f: WorkerFailure, 
 /** What a genuine user cancel says. The caller's wording — only this arm is theirs. */
 abortedMessage: string, 
 /** stderr for the `exit` arm; ignored by every other. */
 stderr?: string): string;
+/**
+ * Classify a finished child against the ladder. Returns `undefined` when nothing
+ * killed it — which is not the same as "it answered": the text may still be empty,
+ * and that judgement belongs to the caller.
+ */
 export declare function classifyWorkerFailure(r: WorkerFailureInput): WorkerFailure | undefined;