@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/phases.js

@@ -23,8 +23,10 @@ import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CO
 import { appendGateRecord, readSection, removeTaskSection, setTaskSection, updateTaskFrontMatter } from './task-io.js';
 import { applyRefutations } from './refuted-constraint.js';
 import { spawnSync } from 'node:child_process';
+import {} from './task-types.js';
 import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
 import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './question-dedup.js';
+import {} from './widget.js';
 import { parseGrillQuestions, parseAutoAnswer, autoAnswerHasTag, parseVerifyToolingOutput, deriveTitle } from './parsers.js';
 import { compressTitle } from './title-label.js';
 import { parseVerifyBlock, validateSpecShape, validateRefineShape, stripSpecPreamble, isCritiqueClean } from './spec-validation.js';
@@ -36,7 +38,7 @@ import { readContracts, buildContractsBlock, buildContractsVerifyBlock } from '.
 import { readRequirements, buildRequirementsBlock, buildOwnedRequirementsBlock, readOwnedRequirements, writeOwnedRequirements, ownedForTitle, appendOwnedConstraints } from './requirements.js';
 import { detachUnsatisfiableRequirements, claimPendingRequirements, unclaimedPendingRequirements, formatReassignActions } from './owned-freeze-reassign.js';
 import { trackedSourceOracle } from './owned-freeze-conflict.js';
-import { thinkingForChild, runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED } from './child-runner.js';
+import { thinkingForChild, runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED, CommandTimeoutError, isFatalChildCause } from './child-runner.js';
 import { runResearchWorker, researchWorkerCacheHeading } from './research-worker.js';
 import { SessionUI } from '../remote/bridge.js';
 import { isYoloMode, yoloPickAutoAnswer } from './yolo.js';
@@ -85,14 +87,12 @@ export function replaceToolingWithVerified(research, verifiedCommands) {
 }
 // ─── Phase functions ─────────────────────────────────────────────────────────
 // Authoritative directive that travels with the refine orientation block. Refine
-// runs BEFORE research, so on a "Scaffold project with package.json…" title it has
-// no signal the file already exists and authors greenfield strip-constraints
-// ("bun-plugin-tailwind the only dependency", "exactly N scripts") that compose
-// then obeys over the research facts — the implementer executes a wholesale
-// rewrite that drops every existing dependency and script (mx5 TASK_0001 emptied
-// package.json; the REAL pipeline reproduced it 3/3 even with research surfacing
-// the deps). Handing refine the manifest/config CONTENT up front, with this
-// reframe, fixes it at the origin (A/B: 1/5 → 5/5 preserve, 5/5 end-to-end).
+// is PHASE_ORDER[0] and research is [1], so on a "scaffold the project" title
+// refine has no signal that the manifest already exists. It can then author
+// greenfield strip-constraints ("X is the only dependency", "exactly N scripts")
+// which compose obeys — and the implementer rewrites the manifest from scratch,
+// dropping every dependency and script already in it. Handing refine the
+// manifest/config CONTENT up front, with this reframe, fixes it at the origin.
 const REFINE_PRESERVE_DIRECTIVE = 'EXISTING FILES ON DISK — AUTHORITATIVE (overrides any "scaffold / create / set '
     + 'up / initialize / from scratch / only / exactly / minimal" wording in the task '
     + 'below): the files shown in the PROJECT ORIENTATION block ALREADY EXIST. When '
@@ -146,14 +146,13 @@ export async function phaseContractsBlock(deps) {
 }
 /**
  * The carried-context blocks a GENERATIVE phase (refine, compose) receives: the
- * cross-slice contracts plus the carried cross-cutting requirements (mx5 run 11,
- * goals A/C — `.pi-tasks/requirements.md`, written at plan time). The verbatim
- * requirement quotes travel INTO every task's spec generation, so a mandated
- * methodology ("a test lands in the same change as each new route") reaches the
- * task's GOAL/CONSTRAINTS and its VERIFY — a pointer back to the spec doc
- * recovered the dropped §10 in only 1 of ~6 applicable run-11 tasks; content
- * travels, pointers don't. Both blocks are '' outside their runs, so a bare
- * /task is byte-identical to before.
+ * cross-slice contracts plus the carried cross-cutting requirements
+ * (`.pi-tasks/requirements.md`, written at plan time). The verbatim requirement
+ * quotes travel INTO every task's spec generation, so a mandated methodology
+ * ("a test lands in the same change as each new route") reaches the task's
+ * GOAL/CONSTRAINTS and its VERIFY. Content travels; a pointer back to the spec
+ * doc does not. Both blocks are '' outside a /task-auto run, so a bare /task
+ * sees no change.
  */
 export async function phaseCarriedBlocks(deps) {
     const contracts = await phaseContractsBlock(deps);
@@ -162,13 +161,13 @@ export async function phaseCarriedBlocks(deps) {
     return [contracts, requirements, owned].filter(b => b.length > 0).join('\n');
 }
 /**
- * The owned (task-mapped) requirements for THIS task (mx5 run 16): matched by
+ * The owned (task-mapped) requirements for THIS task: matched by
  * the plan title the coverage map keyed them to, which is the task's stored
  * `raw prompt` section verbatim. Empty outside /task-auto runs, for spliced
- * repair tasks, and when the plan recorded no mapping — all of which degrade to
- * the pre-run-16 behavior. This is the BELT (prompt block, into refine +
- * compose); appendOwnedConstraints on the final spec is the BRACES — the belt
- * alone folded the clause in only 2/8 live reps per fixture.
+ * repair tasks, and when the plan recorded no mapping — all of which make this a
+ * no-op. This is the BELT (a prompt block, into refine and compose);
+ * `appendOwnedConstraints` on the final spec is the BRACES. The belt is a request
+ * to the model and can be ignored; the braces are a host-side append and cannot.
  */
 async function ownedForThisTask(deps) {
     try {
@@ -196,17 +195,18 @@ function repoSourceOracle(cwd) {
     });
 }
 /**
- * DETACH (nexttask 2) — an owned requirement this task cannot satisfy, because a
+ * DETACH — an owned requirement this task cannot satisfy, because a
  * category freeze in the very spec that carries it covers the only file that
  * could, stops being this task's obligation and is released to whichever later
  * task writes that file.
  *
  * Runs at the LAST spec-producing step, where the pair first exists: the stamped
  * bullet is written one statement earlier by `appendOwnedConstraints`, and a
- * critique-time probe measured 0/40 because the stamp did not exist yet. It
- * never edits prose and never asks a model — the run-18 rewrite lever resolved
- * 11 of 20 pairs by DELETING the authoritative clause. The quote stays in the
- * ledger throughout; only its owner changes.
+ * critique-time probe would find nothing because the stamp does not exist yet.
+ * It never edits prose and never asks a model — a model asked to remove a
+ * contradiction can satisfy the request by DELETING the authoritative clause,
+ * which is not satisfaction of the requirement. The quote stays in the ledger
+ * throughout; only its owner changes.
  */
 export async function resolveOwnedFreezeForThisTask(deps, spec) {
     const ledger = await readOwnedRequirements(deps.cwd).catch(() => []);
@@ -230,16 +230,16 @@ export async function resolveOwnedFreezeForThisTask(deps, spec) {
     return res.spec;
 }
 /**
- * CLAIM (nexttask 2) — the other half. A requirement detached by an earlier task
+ * CLAIM — the other half. A requirement detached by an earlier task
  * becomes THIS task's own when its refined prompt says it writes the frozen
  * file. Run before compose builds its carried blocks, so the claimed obligation
  * rides the same belt every owned requirement does and the braces stamp it onto
  * this spec.
  *
- * The claimant is the only party that knows: at detach time the later tasks are
- * bare plan titles, and none of mx5 run 19's 26 titles contains the path. Over
- * the same run's 26 REFINED prompts, `writeIntent` picks out exactly the two
- * tasks that write the server file.
+ * The claimant is the only party that knows. At detach time the later tasks are
+ * bare plan titles, and a plan title names a slice of behaviour rather than a
+ * file. By its own compose a task has a REFINED prompt, which does say which
+ * files it will write — and that is what `writeIntent` reads.
  */
 export async function claimOwnedFreezeForThisTask(deps, refined) {
     const ledger = await readOwnedRequirements(deps.cwd).catch(() => []);
@@ -259,24 +259,23 @@ export const phaseRefine = async (deps, raw, planContext) => {
     const contracts = await phaseCarriedBlocks(deps);
     // Imperative tool directives the user wrote into the RAW prompt ("via web
     // search", "fetch <url>"). Refine paraphrases the task and a weak model drops
-    // these some of the time (mx5 run 9: "via web search" vanished, the whole run
-    // made 0 search calls). Hand them to refine as a MUST-PRESERVE block (belt) and
+    // these some of the time, and a directive that vanishes at refine is gone from
+    // every later phase. Hand them to refine as a MUST-PRESERVE block (belt) and
     // re-check the output below (lever). Empty on an ordinary prompt → refine unchanged.
     const directives = extractUserDirectives(raw);
     const directivesBlock = preserveDirectivesBlock(directives);
     const refined = await runPhaseChild(deps, 'refine', 'read', REFINE_PROMPT(raw, planContext, existingFiles, contracts, directivesBlock), 
     // refine's deliverable is a 4-section text rewrite that never strictly
-    // needs a successful read — on a test-writing task against a large
-    // existing codebase the model over-explores (re-reads source hunting for
-    // the impl) and burns the loop budget. Degrade to a no-tools final
-    // attempt instead of hard-failing the whole run. See TASK_0016 (mx5):
-    // refine looped 3×/resume forever; the deliverable was always producible
-    // from the title + design doc alone.
+    // needs a successful read: it is producible from the title and the design
+    // doc alone. Against a large existing codebase the model can over-explore
+    // instead — re-reading source hunting for the implementation — and burn the
+    // loop budget. Degrade to a no-tools final attempt rather than hard-failing
+    // the whole run.
     { degradeOnExhaustion: true, verb: 'restart' });
     // Shape check, REPORTED not enforced. Refine's four sections are what
     // extractCapsSection, scopedToolingGoal, deriveTitle and extractEnrichTargets
-    // each look for, and all four fail SILENTLY when one is missing — so the loss
-    // was previously invisible. Deliberately not a retry or a throw: refine's
+    // each look for, and all four fail SILENTLY when one is missing, so without
+    // this line the loss leaves no trace. Deliberately not a retry or a throw: refine's
     // output is usable prose even when a heading is gone (the four consumers
     // degrade, they do not break), and a run must not die over a heading. This
     // puts the miss in the debug log where an audit can find it.
@@ -302,7 +301,16 @@ export async function phaseVerifyTooling(deps, research) {
     try {
         verifyOutput = await runPhaseChild(deps, 'verify-tooling', 'read,bash', VERIFY_TOOLING_PROMPT(toolingList));
     }
-    catch {
+    catch (e) {
+        if (isFatalChildCause(e))
+            throw e;
+        // The fallback ships the tooling list UNVERIFIED, which is the right
+        // degrade for a child that merely failed. A hung command is different: it
+        // cost the ceiling on every strike and says the SPEC named something
+        // unbounded, so it is the one cause worth a trail line rather than silence.
+        if (e instanceof CommandTimeoutError) {
+            deps.logDebug?.(`verify-tooling: ${e.message} — shipping the list unverified`);
+        }
         return replaceToolingWithVerified(research, commands);
     }
     const parsed = parseVerifyToolingOutput(verifyOutput);
@@ -316,10 +324,10 @@ export async function phaseVerifyTooling(deps, research) {
  * The worker channels the APIS research worker is given.
  *
  * `pi-worker-search` + `pi-worker-fetch` ride along only when the configured
- * engine is usable (a keyless engine always is; brave needs its key). A tool
- * without a key just errors, and a weak model burns calls on it — while search
- * being ABSENT was structural in the other direction: three consecutive audited
- * runs made 0 search calls because the child literally did not have the tool.
+ * engine is usable. `searchConfigured` decides: exa and ddg are keyless and
+ * always usable, brave is usable only with its key. A keyless tool that errors
+ * on every call is something a weak model burns calls on; a tool the child was
+ * never handed is a channel it cannot use at all, however the prompt is worded.
  *
  * Both halves of "given a channel" — the tools string and the `-e` path — come
  * from the same rows, so they cannot disagree.
@@ -335,10 +343,10 @@ export function apisWorkerChannels() {
  * ddg) always are; only brave needs its API key.
  */
 export function searchConfigured(getEnv = k => process.env[k], provider = getConfig().searchProvider) {
-    // Asks the SAME row `search()` asks. This used to re-state brave's env pair
-    // under a comment saying it "mirrors search-core's lookup" — two statements of
-    // one fact, and the one that decides whether the APIS worker is even handed the
-    // search tool.
+    // Goes through `searchProviderKey`, the same lookup `search()` itself uses.
+    // Re-stating brave's env pair here would make two statements of one fact, and
+    // this is the one that decides whether the APIS worker is handed the search
+    // tool at all.
     return searchProviderKey(provider, getEnv) !== null;
 }
 /** Extra prompt block for the APIS worker when search is available — trigger-framed
@@ -353,9 +361,9 @@ export const RESEARCH_SEARCH_HINT = '\n\nLIVE WEB — use pi-worker-search for e
  * In-process guards loaded into the TOOLING worker only: block a re-read of any
  * file already read, and block any byte-identical grep/find/ls repeat, feeding
  * the model "you already have this, answer now" instead of letting it re-run.
- * TOOLING reads each file once and never needs an identical search twice in any
- * healthy recorded run, so neither rule has a legitimate false positive here.
- * See single-read-guard.ts.
+ * TOOLING's job is to name verification commands, so it has no reason to read a
+ * file twice or repeat a search byte for byte — which is what makes both rules
+ * safe to arm HERE and nowhere else. See single-read-guard.ts.
  */
 export const SINGLE_READ_EXTENSION_PATH = fileURLToPath(new URL('../workers/single-read-extension.js', import.meta.url));
 /**
@@ -363,15 +371,13 @@ export const SINGLE_READ_EXTENSION_PATH = fileURLToPath(new URL('../workers/sing
  * cares about — never the per-file edit list. Big refined prompts embed a long
  * bulleted "fix these files" checklist *inside* the GOAL block; handing that to
  * a weak local model drags it into reading/grepping source it doesn't need and
- * it loops (TASK_0017: read(sql-adapter.ts) ×5 → loop-kill → fails the phase).
+ * it loops.
  * So scope TOOLING's view to the GOAL prose, truncated at the first bullet.
  *
  * Fallbacks, in order: no bare `GOAL` header (free-form refined) → the whole
  * refined unchanged; a GOAL block with no bullets → the full GOAL block. The
  * GOAL boundary is the next bare ALL-CAPS header (CONSTRAINTS, KNOWN-UNKNOWNS,
- * …) or end of text. Verified against every recorded refined prompt: the
- * bullet-heavy failure case drops 3319→329 chars with zero source-file
- * mentions; the rest are unchanged or only lightly trimmed.
+ * …) or end of text.
  */
 export function scopedToolingGoal(refined) {
     const m = /^GOAL[ \t]*\n([\s\S]*?)(?=\n[A-Z][A-Z][A-Z -]*[ \t]*\n|$(?![\s\S]))/m.exec(refined);
@@ -400,8 +406,8 @@ async function manifestDependencyNames(cwd) {
 /**
  * Prepended to worker:apis's prompt on the ONE retry the zero-retrieval gate triggers. It
  * names the exact failure (a section written with no retrieval) so the correction is concrete,
- * and bounds the retrieval to the symbols about to be listed — a broad "read everything" here
- * would trade the memory-written section for the 37-read near-runaway at phases.ts's read tail.
+ * and bounds the retrieval to the symbols about to be listed — a broad "read everything"
+ * here would trade a memory-written section for a read runaway.
  */
 const APIS_ZERO_RETRIEVAL_PREAMBLE = 'STOP. Your previous attempt at this task wrote a complete APIS section without calling a '
     + 'single retrieval tool — so every signature, type, and command in it was recalled from '
@@ -412,12 +418,11 @@ const APIS_ZERO_RETRIEVAL_PREAMBLE = 'STOP. Your previous attempt at this task w
     + 'list — no more, no less; do not read the whole tree.';
 /**
  * Prepended to worker:context's prompt on the ONE retry the silent-retry gate triggers. The
- * previous attempt produced ZERO bullets — STEP 0 (context-silence.ts) showed every such rep
- * across 48 live reps was a genuine loss (a loop-degrade or a hallucinated non-bullet
- * fragment), never a legitimate empty answer, because the same tree reliably yields 11–21
- * bullets. So this names that failure and steers away from the two shapes that caused it:
- * the repeated-grep thrash that trips the loop-killer, and emitting anything that is not a
- * bullet. It does NOT loosen the sourced-bullet invariant — it explicitly repeats that
+ * previous attempt produced ZERO bullets, which `classifyContextSilence`
+ * (context-silence.ts) has already judged a genuine loss rather than an honest empty
+ * answer. So this names that failure and steers away from the two shapes that cause it:
+ * the repeated-grep thrash that trips the loop-killer, and emitting anything that is not
+ * a bullet. It does NOT loosen the sourced-bullet invariant — it explicitly repeats that
  * external-API semantics stay open questions unless quoted.
  */
 const CONTEXT_SILENT_RETRY_PREAMBLE = 'STOP. Your previous attempt at this task produced ZERO usable bullets — either it thrashed '
@@ -448,15 +453,12 @@ export async function phaseResearch(deps, refined) {
     // repo; purely additive (nothing is blocked) so it can only remove a
     // redundant read, never hide a file.
     //
-    // Applied to FILES and APIS only — NOT CONTEXT/TOOLING. Verified with a live
-    // A/B on the local model (real pi, real repo): FILES and APIS are bimodal —
-    // they sometimes answer from the inventory but sometimes spiral into heavy
-    // reads (APIS hit 37 reads / 221s, a near-runaway), and pre-supplying the core
-    // collapses that to 0 reads / ~3.5s with the model honoring "do not re-read"
-    // (0 core re-reads in every ON run). CONTEXT works from inventory+grep and
-    // reads ~0 files regardless, so the block was pure prefill and made it slower
-    // in 5/5 reps; TOOLING is already scoped + single-read-guarded and saw no
-    // benefit. So orientation only goes where reads actually happen.
+    // Applied to FILES and APIS only — NOT CONTEXT/TOOLING, and the split is by
+    // whether the worker reads at all. FILES and APIS explore by reading, so
+    // pre-supplying the core replaces reads they would otherwise make. CONTEXT
+    // works from the inventory and grep, and TOOLING is scoped to the GOAL prose
+    // and single-read-guarded, so for those two the block is pure prefill with no
+    // read to displace. Orientation only goes where reads actually happen.
     const orientationPaths = getConfig().orientation && inventoryRaw.length > 0 ?
         inventoryRaw.split('\n').filter(l => l.trim().length > 0)
         : [];
@@ -476,25 +478,20 @@ export async function phaseResearch(deps, refined) {
     // Judged against the EXTERNAL CONTEXT this run actually gathered — the same string
     // the worker is handed below — and the manifest's dependency names.
     const manifestPackages = await manifestDependencyNames(deps.cwd);
-    // PROMPT 4's spec-cited-URL lever is NOT WIRED HERE. It is built and unit-tested in
-    // ./spec-urls.ts and its live A/B FAILED: baseline 2/20 vs treatment 3/20, Fisher
-    // one-tailed p = 0.50, over two fixtures, with delivery into this very prompt proven
-    // separately (scripts/spec-url-prompt-delivery-check.ts). Shipping it anyway would put
-    // ~1000 characters of prefill into every APIS prompt for no measured benefit, which is
-    // the pattern nexxtasks exists to prevent. To re-run the experiment, restore the block
-    // this comment replaces — see the git history of this file and the PROMPT 4 entry in
-    // nexxtasks.txt RESULTS.
-    // nexttask 5B fan-out bounds. All four read their env ONCE per research
-    // phase, so every worker in a run sees the same policy and a harness cannot
-    // half-apply an arm. CAP, SCALE and carry-forward are null/false in the
-    // shipped configuration; the progress deadline shipped ON (nexttask 9).
+    // The spec-cited-URL lever from ./spec-urls.ts is built and unit-tested but is
+    // NOT WIRED HERE: pointing the worker at a page it should have read did not
+    // change what it produced, so the block would be prefill on every APIS prompt
+    // for nothing.
+    // Research fan-out bounds, read from the environment ONCE per research phase,
+    // so every worker in a run sees the same policy and a harness cannot half-apply
+    // one. In the shipped configuration the budget knobs are unset and the progress
+    // deadline is on.
     const leverEnv = snapshotLeverEnv();
     const fanoutBudget = projectDocsBudget(leverEnv);
     const progressCeilingMs = workerProgressCeilingMs(leverEnv);
-    // Which deadline policy was in force is a fact about how every number below
-    // was produced. Run 18's 120 discarded minutes were only recoverable because
-    // 5A started writing down what the workers actually did; a run whose logs do
-    // not say which policy it ran under cannot be compared with one that does.
+    // Which deadline policy was in force decides what every worker timing below
+    // means, and the two policies are not comparable. Logging it is what makes a
+    // trail readable after the fact.
     deps.logDebug?.(progressCeilingMs === null ?
         'phase:research: worker deadline = fixed elapsed cap (progress deadline DISABLED)'
         : `phase:research: worker deadline = no-progress, ceiling ${progressCeilingMs}ms`);
@@ -512,10 +509,9 @@ export async function phaseResearch(deps, refined) {
     // wall-clock-relative (queueing shows up in waitMs).
     //
     // Restarted attempts get their OWN row. Without one the widget contradicts
-    // itself: mx5 run 18 printed `workers 722.2s` over a longest member reading
-    // `worker:apis work 239.3s`, because wait/work describe the final attempt
-    // while the phase clock counts all three. The discarded time is the whole
-    // gap, so naming it is what closes the widget.
+    // itself: waitMs and workMs describe only the FINAL attempt while the phase
+    // clock counts every attempt, so the phase total exceeds its longest member by
+    // the time the discarded attempts took. Naming that gap is what reconciles them.
     const recordWorker = (label, p) => p.then(r => {
         deps.recordSubStep?.(`${label} wait`, r.waitMs);
         deps.recordSubStep?.(`${label} work`, r.workMs);
@@ -524,33 +520,15 @@ export async function phaseResearch(deps, refined) {
         }
         return r;
     });
-    // Run the four workers ONE AT A TIME. Settled by an A/B on the local
-    // llama.cpp backend (single GPU, same task/model) — and the answer FLIPS
-    // with thinking:
-    //   - thinking ON  → parallel wins: long decodes batch well, 4 concurrent
-    //     finish in ~max(worker), not the sum.
-    //   - thinking OFF → sequential wins: with short decodes the batching upside
-    //     is gone, but 4 concurrent streams still split the one GPU and slow
-    //     each other ~4x (context worker measured 27s solo vs 128s under load),
-    //     so summed-but-fast (~100s) beats max-of-slowed (~130s).
-    //
-    // KNOWN-OPEN, AND THIS IS THE HONEST STATE OF IT. That A/B was run when
-    // every worker carried Qwen3's `/no_think` prompt suffix, so "thinking OFF"
-    // was assumed and sequential followed. The suffix has since been measured
-    // INERT — with server thinking on and `/no_think` still in the prompt,
-    // Qwen3.8 emitted a median 17k-char trace anyway (n=25) — and it has been
-    // removed in favour of the `research` reasoning group (config/reasoning.ts).
-    // So the arm this default was chosen under may never have been the arm that
-    // ran, and the group's level is now a user-visible setting rather than a
+    // Run the four workers ONE AT A TIME by default. Which order wins depends on
+    // the backend: concurrent streams share one local GPU and slow each other
+    // down, so the sum of four fast workers can beat the max of four slowed ones,
+    // while a backend that genuinely serves parallel streams has no such tradeoff.
+    // `parallelResearchWorkers` is the opt-in for those backends. The worker's
+    // reasoning level (config/reasoning.ts `research` group) changes decode length
+    // and so changes the answer too, which is why this is a config knob and not a
     // constant.
     //
-    // The default stays SEQUENTIAL because that is the measured-safe arm on a
-    // single-GPU box and because flipping a shipped default on an invalidated
-    // premise would be replacing one unmeasured claim with another. The
-    // parallel x reasoning-level interaction is unmeasured; re-run the A/B
-    // before changing this, and treat `parallelResearchWorkers` as the opt-in
-    // for backends that genuinely serve parallel streams.
-    //
     // Result order (files, apis, context, tooling) is preserved for assembly.
     // Resolved once: `searchConfigured()` reads the environment, and the tools
     // string and the `-e` paths must be derived from the SAME answer.
@@ -568,46 +546,38 @@ export async function phaseResearch(deps, refined) {
             // Read-heavy: gets the orientation core (see note above). Search/fetch
             // ride along only when a Brave key exists — see SEARCH_EXTENSION_PATH.
             // FILES' finished map rides along when available (serial default), so
-            // the worker doesn't re-derive where-things-live via docs-"."
-            // queries the FILES worker just answered (run-7 F7: up to 10
-            // duplicate `.`-decodes per task through the serial bottleneck).
+            // the worker doesn't re-derive where-things-live through project-docs
+            // queries the FILES worker just answered.
             prompt: prior => orientation.block
                 + promptHeader
                 + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined)
                 + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')
-                // 5B CAP arm — empty unless PI_TASK_PROJECT_DOCS_BUDGET is
-                // set. The tool-side half lives in pi-worker-docs.ts; a
-                // budget enforced without being announced would just read
-                // to the worker as a broken tool.
+                // Empty unless PI_TASK_PROJECT_DOCS_BUDGET is set. The tool-side
+                // half lives in pi-worker-docs.ts; a budget enforced without being
+                // announced would just read to the worker as a broken tool.
                 + (fanoutBudget === null ? '' : projectDocsBudgetNotice(fanoutBudget)),
             // The tools string and the `-e` paths are ONE fact — which worker
-            // channels this research worker is given — and used to be two literals
+            // channels this research worker is given — and would otherwise be two literals
             // kept in step by eye. `channelSet` derives both from the same rows.
             tools: `read,grep,find,ls,${apisChannels.tools}`,
             fanoutBounded: true,
             extensions: apisChannels.extensions,
-            // ZERO-RETRIEVAL GATE (mx5 run-15 F-1, distinct from the STAGE 1-3 stopping-point
-            // thread). In a MINORITY of reps worker:apis emits a complete, plausible APIS section
-            // having made ZERO retrieval tool calls — the whole thing recalled from memory.
-            // The output contract at RESEARCH_APIS_PROMPT already INSTRUCTS tool use and the
-            // worker skips it anyway (STAGE 2 proved a prompt line does not move grounding), so
-            // this is a deterministic gate, not another instruction: groundingRetrievalCount === 0
-            // on a non-empty section is ungrounded BY CONSTRUCTION — no semantic judgement, the
-            // exact checkable handle STAGE 3's prose-clause gate lacked. The forced-retrieval
-            // retry recovers a grounded section rather than silencing the worker (entry count
-            // preserved). It bounds itself ("look up the symbols you will list — no more") away
-            // from the near-runaway 37-read tail.
+            // ZERO-RETRIEVAL GATE. worker:apis can emit a complete, plausible APIS
+            // section having made ZERO retrieval tool calls — the whole thing recalled
+            // from memory. RESEARCH_APIS_PROMPT already instructs tool use, so another
+            // instruction is not the answer; this is a deterministic gate instead.
+            // `groundingRetrievalCount === 0` on a NON-EMPTY section is ungrounded by
+            // construction, with no semantic judgement needed. The forced-retrieval
+            // retry recovers a grounded section rather than silencing the worker (the
+            // original is kept if the retry still retrieves nothing, so the entry count
+            // cannot collapse), and it bounds itself — "look up the symbols you will
+            // list — no more" — away from a read runaway.
             //
-            // EFFICACY NOT DEMONSTRATED — read before trusting this to matter. The live A/B
-            // (scripts/live-apis-zero-retrieval-ab.ts) ABSTAINED, underpowered: the failure is
-            // RARE and intermittent (base rate 0/40 one session, pooled ~5%), so the primary
-            // reduction (baseline 1/40 zero-retrieval ships -> treatment 0/40) did NOT reach
-            // significance (Fisher p = 0.50 — needs ~5 baseline ships, ~85 reps at ~6%). What IS
-            // established: the gate is correct BY CONSTRUCTION; on the 3 firings observed it
-            // recovered a grounded section every time; and it did NO harm (ungrounded-symbol rate
-            // went DOWN not up, no entry collapse, no runaway, cost +4-6%). It is wired as a
-            // harmless safety net, NOT a proven-effective lever — do not cite it as a measured win
-            // (nexxtasks.txt "ZERO-RETRIEVAL GATE ... ABSTAIN"). A powered A/B is STILL OPEN.
+            // A SAFETY NET, NOT A DEMONSTRATED WIN. The failure it catches is
+            // intermittent, and nothing here establishes how often it fires or what it
+            // is worth. What the code does establish is that it cannot make things
+            // worse: it only ever replaces a zero-retrieval section with a retrieving
+            // one.
             zeroRetrievalRetry: APIS_ZERO_RETRIEVAL_PREAMBLE
         },
         {
@@ -619,30 +589,26 @@ export async function phaseResearch(deps, refined) {
             // spawning long enumeration loops whose output then inflates
             // prefill on every subsequent round.
             //
-            // RECORDED DECISION (mx5 run-15 F-1, PROMPT 1 item 4): this worker stays
-            // ISOLATED — it is NOT given the APIS worker's output. It keeps `read,grep`
-            // and is forbidden, by prompt and by the post-check below, from asserting
-            // external-API behaviour it cannot see. Handing it the APIS section would
-            // widen what it may assert without making any of it checkable here, and
-            // APIS' own answers are the ones F-2 shows are type-only and unverified.
+            // ISOLATED on purpose: this worker is NOT given the APIS worker's output.
+            // It keeps `read,grep` and is forbidden — by prompt and by the post-check
+            // below — from asserting external-API behaviour it cannot see. Handing it
+            // the APIS section would widen what it may assert without making any of it
+            // checkable here.
             tools: 'read,grep',
-            // SILENT-RETRY GATE. STEP 0 measured this worker silent (zero bullets) in ~10%
-            // of live reps (5/48, Wilson95 [4.5%, 22.2%]) and classified EVERY silent rep as
-            // a genuine loss — a loop-degrade banner (60%) or a hallucinated non-bullet
-            // fragment (40%) — never a legitimate empty answer, because the identical fixture
-            // reliably yields 11–21 bullets. A silent section is therefore a dropped section;
-            // retry once, keep the retry only if it emits bullets. See context-silence.ts.
+            // SILENT-RETRY GATE. This worker can come back with zero bullets. The two
+            // causes `classifyContextSilence` recognises — a loop-degrade banner, and a
+            // hallucinated non-bullet fragment — are both dropped sections, not honest
+            // empty answers, so retry once and keep the retry only if it emits bullets.
+            // See context-silence.ts.
             retryIfSilent: CONTEXT_SILENT_RETRY_PREAMBLE,
-            // BRACES for the LIVE-DATA RULE. In run 15 this worker wrote, verbatim, "The
-            // `hono` dependency is pinned at `^4.12.31` in package.json, and the external
-            // context confirms `hc<AppType>` pattern with base URL `/api` ... works
-            // correctly (per Hono RPC docs LIVE data)". It has read+grep only, so the
-            // base-URL half came from memory; fused with the true version half under one
-            // attribution it read as sourced, became a hard requirement in TASK_0027's
-            // CONSTRAINTS and ACCEPTANCE, and every request went to /api/api/... ⇒ 404.
-            // A flagged bullet is demoted to an OPEN QUESTION here — before the section is
-            // persisted — so it cannot reach compose as fact. Demotion, not deletion: the
-            // bullet count is preserved, because a silenced worker is a different
+            // BRACES for the LIVE-DATA RULE (the belt is the prompt). This worker has
+            // `read,grep` only, so it cannot have read a doc — yet it can write one
+            // bullet that fuses a fact it DID read from the manifest with an external-API
+            // claim it did not, under a single "per the docs" attribution. Fused that
+            // way the whole bullet reads as sourced and can become a hard CONSTRAINT.
+            // A flagged bullet is demoted to an OPEN QUESTION here — before the section
+            // is persisted — so it cannot reach compose as fact. Demotion, not deletion:
+            // the bullet count is preserved, because a silenced worker is a different
             // regression.
             postProcess: text => {
                 const r = demoteUnsourcedAttributions(text, externalContext, manifestPackages);
@@ -684,10 +650,10 @@ export async function phaseResearch(deps, refined) {
         taskId: deps.taskId,
         signal: deps.signal,
         spawn: deps.spawn,
-        // ONE CELL PER WORKER since 2026-08-28. The four workers used to
-        // share the `research` cell on the grounds that they are the same
-        // job over four questions; the run logs disagree. The cells DO NOT
-        // ship identical — the evidence is on each of them in reasoning.ts.
+        // ONE CELL PER WORKER. The four are the same job over four
+        // questions, so one shared `research` cell is the tempting shape —
+        // but the four cells do not ship identical, so sharing one would
+        // silently change three of them. See config/reasoning.ts.
         thinkingFor: thinkingForChild,
         logDebug: deps.logDebug,
         onChildOutput: deps.onChildOutput,
@@ -699,7 +665,7 @@ export async function phaseResearch(deps, refined) {
     }, prior);
     const sections = [];
     if (!getConfig().parallelResearchWorkers) {
-        // Default: ONE AT A TIME (see the A/B note above the specs) — a fatal
+        // Default: ONE AT A TIME (see the note above the worker specs) — a fatal
         // failure throws before later workers run, and each worker can see the
         // finished sections before it (APIS builds on the FILES map).
         for (const spec of workerSpecs) {
@@ -711,8 +677,8 @@ export async function phaseResearch(deps, refined) {
         // worker runs to its own outcome first, so one fatal failure cannot
         // orphan the others' output — their sections persist for the resume
         // before the failure is thrown. Assembly order stays the spec order
-        // regardless of completion order. No prior sections exist here, so
-        // prompt builders get none (APIS runs map-less, as before this option).
+        // regardless of completion order. No prior sections exist here, so prompt
+        // builders get none — APIS runs without the FILES map it gets when serial.
         const settled = await Promise.allSettled(workerSpecs.map(spec => drive(spec, [])));
         for (const s of settled) {
             if (s.status === 'rejected')
@@ -784,7 +750,7 @@ export async function phaseAutoAnswer(deps, refined, research, question) {
             text = await runPhaseChild(deps, 'grill-auto', 'read', prependHint(GRILL_AUTO_FORMAT_HINT, basePrompt));
         }
         let parsed = parseAutoAnswer(text);
-        // Anti-synthesis guard (mx5 run 13, Bug A): the auto-answer invented
+        // Anti-synthesis guard: the auto-answer invented
         // `Bun.mkdirSync` while research's APIS section carried the correct list,
         // and the invention was promoted into requirements + VERIFY. Deterministic
         // verbatim-substring check: an API-shaped identifier in the answer that is
@@ -804,7 +770,9 @@ export async function phaseAutoAnswer(deps, refined, research, question) {
                     if (autoAnswerHasTag(text2))
                         reasked = parseAutoAnswer(text2);
                 }
-                catch {
+                catch (e) {
+                    if (isFatalChildCause(e))
+                        throw e;
                     reasked = null;
                 }
                 if (reasked === null
@@ -859,8 +827,8 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
     const ui = new SessionUI(ctx);
     // ONE record, two renderings (task/qa-transcript.ts): `forRecord()` is what
     // compose and critique are handed, `forGenerator()` is what the next grill-gen
-    // call sees. The provenance rule below used to be a comment 12 lines under a
-    // push that broke it.
+    // call sees. The two differ only in provenance suffixes, which is why they can
+    // drift apart unnoticed.
     const transcript = new QaTranscript(GRILL_QA_POLICY);
     const askedQuestions = []; // plain text of each question, for the dup backstop
     // Deterministic backstop against a model that ignores "never re-ask": a
@@ -953,8 +921,6 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
  * the same place. The task file's `## refined prompt` is deliberately left as
  * refine wrote it; the drop is recorded on the `## gates` trail with both source
  * lines quoted, so the decision stays auditable after the fact.
- *
- * STEP 0 `scripts/refuted-constraint-baserate.ts`; A/B-1 `…-ab.ts` (PASS).
  */
 export async function dropRefutedConstraints(deps, refined, research) {
     const refuted = applyRefutations(refined, research);
@@ -1019,17 +985,15 @@ export async function phaseCritique(deps, spec, refined, qa, planContext, resear
  * An additional deterministic defect block, forced into the rewrite exactly
  * like the probes below and overriding a CLEAN triage the same way.
  *
- * This is the A/B seam for a probe that is not wired yet: the discipline
- * here is "wire only on PASS" (memory/prompt4-spec-urls-failed.md), so a
- * candidate probe has to be measurable through the SHIPPED critique path
- * rather than through a hand-copied replica of it, or the two arms differ by
- * more than the probe. Undefined in production.
+ * The seam exists so a candidate probe can be exercised through the SHIPPED
+ * critique path rather than through a hand-copied replica of it — otherwise a
+ * comparison differs by more than the probe. Undefined in production.
  */
 extraDefects) {
     // Fast triage before the expensive full rewrite. The rewrite regenerates
-    // the entire spec from scratch and is the costliest tail of the pipeline
-    // (observed up to ~240s). Most compose drafts are already good, so we first
-    // ask a cheap, short-output triage pass whether a rewrite is even needed.
+    // the entire spec from scratch, which makes it the most expensive step in the
+    // pipeline. Most compose drafts are already good, so we first ask a cheap,
+    // short-output triage pass whether a rewrite is even needed.
     //
     // We only short-circuit when the draft already has a runnable VERIFY block
     // (parseVerifyBlock !== null): the final handoff gate rejects specs without
@@ -1041,12 +1005,12 @@ extraDefects) {
     // model does not self-discover reliably, each forced into the rewrite and each
     // overriding a CLEAN triage. They live as rows in CRITIQUE_PROBES
     // (critique-probes.ts) so the override and the merge below are DERIVED from
-    // the table rather than retyped — a probe used to be listed by hand in three
+    // the table rather than retyped — a probe would otherwise be listed by hand in three
     // places, and forgetting the override term shipped the very defect it was
     // added to catch.
     //
     // The contract registry is read here rather than inside the table because the
-    // critique PROMPT needs it too (run-8 F3): threading the design's pinned
+    // critique PROMPT needs it too: threading the design's pinned
     // interface facts into the rewrite lets it RECONCILE a synthesized wiring
     // specific against the facts it must reproduce — the generation-side
     // complement of the verify-side boundary check.
@@ -1066,12 +1030,14 @@ extraDefects) {
         let verdict;
         try {
             // No tools: triage judges only the spec/refined/qa text it is given.
-            // Granting `read` here let it wander the repo to "verify" findings,
-            // which made the supposedly-cheap pass cost as much as a rewrite
-            // (observed ~133s). The judgement needs no file access.
+            // Granting `read` lets it wander the repo to "verify" findings, which
+            // costs as much as the rewrite this pass exists to avoid. The judgement
+            // needs no file access.
             verdict = await runPhaseChild(deps, 'critique-triage', '', CRITIQUE_TRIAGE_PROMPT(spec, refined, qa, contractsBlock));
         }
-        catch {
+        catch (e) {
+            if (isFatalChildCause(e))
+                throw e;
             verdict = null;
         }
         deps.recordSubStep?.('triage', Date.now() - tTriage);
@@ -1142,10 +1108,9 @@ export async function critiqueWithFallback(d, p) {
         // so returning that same draft would persist a VERIFY-less spec the
         // handoff gate rejects and resume can't heal. Compose now enforces a
         // parseable VERIFY, so this should hold; keep the guard so a regression
-        // fails the run cleanly instead of shipping a broken spec.
-        // (verify_grep_theater: both rewrite attempts kept a grep-only VERIFY;
-        // the draft carries the same defect but is the validated-shape fallback
-        // — deliver it rather than fail the run. The guard costs time, never work.)
+        // fails the run cleanly instead of shipping a broken spec. A draft that
+        // carries the SAME defect the rewrite failed to fix is still delivered —
+        // it is the validated-shape fallback, and failing the run costs more.
         if (parseVerifyBlock(p.spec) === null)
             throw err;
         p.ctx.ui.notify(msg === 'verify_grep_theater' ?
@@ -1159,8 +1124,8 @@ export async function critiqueWithFallback(d, p) {
  * REFINE — restate the raw prompt as a bounded 4-section spec, then subtractively
  * strike any phantom runtime specifier (`bun:sql`) it carried up verbatim from the
  * spec doc, BEFORE it flows to research/grill/compose. An appended correction alone
- * loses: the affirmative survives into the composed GOAL and on to the implementer
- * (proven: compose re-leaks it 4/4). Rewriting the source so compose has nothing to
+ * loses: the affirmative survives into the composed GOAL and on to the
+ * implementer, because compose re-leaks it. Rewriting the source so compose has nothing to
  * contradict is the fix. Silent + no-op when nothing is wrong or the runtime's types
  * aren't installed.
  */
@@ -1213,16 +1178,16 @@ export async function composePhase(d, p) {
  * CRITIQUE — the last spec-producing step, and the two host-side corrections that
  * must run after it in THIS ORDER.
  *
- * BRACES (mx5 run 16): append any owned design obligation the spec still omits as a
- * CONSTRAINTS bullet. The belt block upstream is obeyed ~25% (measured); a host-side
+ * BRACES: append any owned design obligation the spec still omits as a
+ * CONSTRAINTS bullet. The belt block upstream is obeyed only sometimes; a host-side
  * append is obeyed by construction. Idempotent — quotes the spec already carries
  * (belt-obeying reps) are skipped.
  *
  * Then DETACH: an owned obligation whose only file this spec also FREEZES is
  * unsatisfiable here, so it moves to the pending task that writes that file rather
  * than shipping a requirement no one can meet. It MUST run after the append, because
- * the append is what writes the stamp the detach reads — a critique-time probe
- * measured 0/40 because the stamp did not exist yet.
+ * the append is what writes the stamp the detach reads, so a critique-time probe
+ * would find nothing.
  */
 export async function critiquePhase(d, p) {
     const spec = await critiqueWithFallback(d, p);
@@ -1239,10 +1204,9 @@ export async function critiquePhase(d, p) {
  * The pipeline, as a table with no bodies.
  *
  * Every row's `run` is a named exported function, so the COMPOSITION inside a
- * step — which is where this codebase's recorded phase defects have lived, not in
- * the parts — is drivable directly instead of only through a whole TaskRunner run.
- * The parts stay exported and separately covered; what changed is that the ORDER
- * they run in is now asserted by driving the row rather than retyped in a test.
+ * step is drivable directly instead of only through a whole TaskRunner run. That
+ * matters because a step's parts can each be correct while the order they run in
+ * is wrong — see `runPhaseRow`, which is the surface that pins the order.
  */
 export const PHASES = [
     {
@@ -1279,50 +1243,30 @@ export async function runPhaseRow(row, deps, pc) {
 export async function replayPhaseCarry(row, deps, pc) {
     await row.carry?.(deps, pc);
 }
-// INTEGRATION-DEPTH APPEND (2026-07-27): the lever proposed for this exact site —
-// deterministically append a known-runnable integration command to the VERIFY block
-// whenever a task's ACCEPTANCE claims runtime behaviour — is REFUTED at STEP 0 and was
-// NOT built. Nothing below is wired; this is the record.
+// INTEGRATION-DEPTH APPEND — considered for this site, NOT built.
 //
-// The defect is real and reproduces on four unrelated stacks. Measured with
-// scripts/verify-integration-depth-step0.ts (published metric regex in that file;
-// re-runnable, no model time): VERIFY blocks that boot or hit the real integrated
-// product — mx5 7/41, IAR1 3/10, godot-engine 2/20, runner 0/2, total 12/73 (16.4%).
-// That total OVERSTATES the truth: godot's two hits only match because the block greps
-// a URL out of CLAUDE.md, and IAR1's TASK_0006 curls a GitHub tarball to check a hash,
-// so genuine product integration is ~9/73 (~12%). The addressable class — runtime claim
-// in ACCEPTANCE, a boot command available with provenance, static-only VERIFY anyway —
-// is 29/73 (39.7%), clearing the task's 25% kill condition, but 27 of those 29 are mx5.
+// The idea: whenever a task's ACCEPTANCE claims runtime behaviour, deterministically
+// append a known-runnable integration command to its VERIFY block. Most VERIFY blocks
+// never boot or touch the integrated product, so the gap is real.
 //
-// What kills the lever is its input, not its premise. It needs a command that is
-// (1) provenance-bearing, (2) proven runnable, (3) terminating, and (4) integration-
-// shaped. Measured on scratch clones with scripts/integration-command-provenance.ts,
-// that intersection is EMPTY on every stack available here:
-//   mx5    `bun run dev` is the only command matching the metric and it does not
-//          terminate (probe killed it at 60s) — appending it hangs the verify child
-//          until the 15-minute command watchdog and then FAILs. Every command that DOES
-//          terminate (`bun run build` exit 0) fails the metric.
-//   godot  `godot --headless --quit` (0.8s, exit 0) and the real GUT runner (1.7s,
-//          exit 0) are both appendable — and neither matches the metric, which is
-//          web-shaped (curl/localhost/PORT=/run dev/http://). Nothing appendable can
-//          move the registered metric on a non-web stack, so the two-stack A/B the
-//          task requires is unsatisfiable by construction, not by sample size.
-//   IAR1   no candidate at all: cmake is absent from this box (the N5 finding).
-// R4 forbids swapping the metric after seeing results, so a broadened "boots the real
-// product" metric is a separate pre-registered experiment, not a rescue of this one.
+// What kills it is the input, not the premise. The append needs a command that is all
+// four of: provenance-bearing, proven runnable, TERMINATING, and integration-shaped.
+// That intersection tends to be empty. A dev server matches the shape and never
+// terminates — appending it hangs the verify child until the command watchdog and then
+// FAILs. Everything that does terminate (a build, a headless one-shot) is not
+// integration-shaped. And on a non-web stack nothing appendable is web-shaped at all.
 //
-// The deeper finding: on the stack holding 93% of the addressable mass, integration is
-// not a COMMAND. mx5's 7 integrated blocks are whole task-specific procedures — pick a
-// free port (3911/41234/42421/3001), export DATABASE_URL, boot, seed, log in, assert N
-// endpoints, tear down. A host-side append cannot synthesize that from provenance
-// (launch-contract.md records script NAMES only — no port, no health URL), and
-// synthesizing it from the task's own `## verified tooling` is the N5 fabrication road.
-// That machinery already exists in ONE place that owns ports, seeding and teardown: the
-// final gate's render check. The mx5-class defect belongs there (nexttask TASK 6), not
-// in per-task VERIFY blocks.
+// The deeper point: on a web stack, integration is not a COMMAND. An integrated VERIFY
+// block is a whole task-specific procedure — pick a free port, export the database URL,
+// boot, seed, log in, assert some endpoints, tear down. A host-side append cannot
+// synthesize that from provenance, because a launch contract records script NAMES and
+// nothing else: no port, no health URL. Synthesizing it from the task's own
+// `## verified tooling` section is fabrication.
 //
-// Durable assets kept: both rigs above and their unit tests. Do NOT wire an append here
-// without a command source that satisfies all four properties at once.
+// That machinery already exists in ONE place that owns ports, seeding and teardown: the
+// final gate's render check. This class of defect belongs there, not in per-task VERIFY
+// blocks. Do NOT wire an append here without a command source that satisfies all four
+// properties at once.
 /** Dispatch a row's declared post-commit effect. Rows with none do nothing. */
 export async function postCommitPhase(phase, deps, pc, out) {
     await phase.postCommit?.(deps, pc, out);