@mjasnikovs/pi-task 0.38.15 → 0.38.17

package/dist/task/phases.js

@@ -8,6 +8,8 @@ import { fetchFocused } from '../workers/fetch-core.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { classifyWorkerFailure } from '../workers/worker-failure.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
+import { searchProviderKey } from '../workers/search-types.js';
+import { channelSet } from '../workers/worker-channels.js';
 import { fanoutTimeoutPolicy, workerCarryForward, workerProgressCeilingMs, projectDocsBudget, projectDocsBudgetNotice } from './research-fanout-budget.js';
 import { isIntegrationUnknown } from './unknown-routing.js';
 import { extractUserDirectives, preserveDirectivesBlock, enforceDirectives } from './user-directives.js';
@@ -36,9 +38,10 @@ 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 { runPhaseChild, runPhaseWithLoopGuard, runWithEmphasisRetry, prependHint, USER_CANCELLED } from './child-runner.js';
+import { runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED } from './child-runner.js';
 import { SessionUI } from '../remote/bridge.js';
-import { isYoloMode, yoloPickAutoAnswer, YOLO_STAMP } from './yolo.js';
+import { isYoloMode, yoloPickAutoAnswer } from './yolo.js';
+import { QaTranscript, GRILL_QA_POLICY } from './qa-transcript.js';
 // ─── Re-export constants from their home modules ────────────────────────────
 export { MAX_GRILL_QUESTIONS };
 // ─── Tooling helpers ─────────────────────────────────────────────────────────
@@ -262,7 +265,7 @@ export const phaseRefine = async (deps, raw, planContext) => {
     // re-check the output below (lever). Empty on an ordinary prompt → refine unchanged.
     const directives = extractUserDirectives(raw);
     const directivesBlock = preserveDirectivesBlock(directives);
-    const refined = await runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext, existingFiles, contracts, directivesBlock))), 
+    const refined = await runPhaseChild(deps, 'refine', 'read', appendNoThink(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
@@ -270,7 +273,7 @@ export const phaseRefine = async (deps, raw, planContext) => {
     // 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.
-    { degradeOnExhaustion: true });
+    { degradeOnExhaustion: true, verb: 'restart' });
     // Deterministic backstop: if the refined spec still dropped a directive, append
     // it verbatim rather than trusting the paraphrase. No model in this path.
     const { text, appended } = enforceDirectives(refined, directives);
@@ -300,21 +303,34 @@ export async function phaseVerifyTooling(deps, research) {
     await setTaskSection(deps.cwd, deps.taskId, 'verified tooling', verifiedSection);
     return replaceToolingWithVerified(research, parsed.verified);
 }
-const DOCS_EXTENSION_PATH = fileURLToPath(new URL('../workers/docs-extension.js', import.meta.url));
-/** pi-worker-search + pi-worker-fetch, loaded into the APIS research worker only
- *  when a Brave key is configured (the tool without a key just errors, and a weak
- *  model burns calls on it). Search being absent from the research toolset was
- *  STRUCTURAL: three consecutive audited runs made 0 search calls because the
- *  child literally did not have the tool. */
-const SEARCH_EXTENSION_PATH = fileURLToPath(new URL('../workers/search-extension.js', import.meta.url));
+/**
+ * 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.
+ *
+ * Both halves of "given a channel" — the tools string and the `-e` path — come
+ * from the same rows, so they cannot disagree.
+ */
+function apisWorkerChannels() {
+    return channelSet([
+        'pi-worker-docs',
+        ...(searchConfigured() ? ['pi-worker-search', 'pi-worker-fetch'] : [])
+    ]);
+}
 /**
  * Is live web search configured for this process? The keyless providers (exa,
- * ddg) always are; only brave needs its API key — mirrors search-core's lookup.
+ * ddg) always are; only brave needs its API key.
  */
 export function searchConfigured(getEnv = k => process.env[k], provider = getConfig().searchProvider) {
-    if (provider !== 'brave')
-        return true;
-    return Boolean(getEnv('BRAVE_SEARCH_API_KEY') ?? getEnv('BRAVE_API_KEY'));
+    // 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.
+    return searchProviderKey(provider, getEnv) !== null;
 }
 /** Extra prompt block for the APIS worker when search is available — trigger-framed
  *  (the validated shape for getting a local model to actually reach for search). */
@@ -604,10 +620,10 @@ const CONTEXT_SILENT_RETRY_PREAMBLE = 'STOP. Your previous attempt at this task
     + 'nothing else. Keep the same rules as before: state an external library/API behaviour as fact '
     + 'ONLY when quoting an EXTERNAL CONTEXT block; otherwise write it as an "unverified:" open '
     + 'question. One claim per bullet. Better to emit three sharp sourced bullets than to say nothing.';
-export async function phaseResearch(deps, refined, researchDeps = {}) {
-    const fileInventoryFn = researchDeps.getFileInventory ?? getFileInventory;
-    const runWorkerFn = researchDeps.runWorker ?? ((_label, input) => runWorker(input));
-    const externalContext = await gatherExternalContext(refined, deps, researchDeps);
+export async function phaseResearch(deps, refined) {
+    const fileInventoryFn = deps.getFileInventory ?? getFileInventory;
+    const runWorkerFn = deps.runWorker ?? ((_label, input) => runWorker(input));
+    const externalContext = await gatherExternalContext(refined, deps);
     // Pre-compute the project file inventory once and hand it to every worker.
     // Workers can then jump straight to targeted read/grep on known paths
     // instead of each spawning its own discovery loop (find/ls). A '' result
@@ -721,6 +737,9 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     // The worker still calls as many tools as it wants; it just stops narrating
     // between them. See appendNoThink. 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.
+    const apisChannels = apisWorkerChannels();
     const workerSpecs = [
         {
             section: 'FILES',
@@ -746,13 +765,12 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
                 // budget enforced without being announced would just read
                 // to the worker as a broken tool.
                 + (fanoutBudget === null ? '' : projectDocsBudgetNotice(fanoutBudget))),
-            tools: 'read,grep,find,ls,pi-worker-docs'
-                + (searchConfigured() ? ',pi-worker-search,pi-worker-fetch' : ''),
+            // The tools string and the `-e` paths are ONE fact — which worker
+            // channels this research worker is given — and used to 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: [
-                DOCS_EXTENSION_PATH,
-                ...(searchConfigured() ? [SEARCH_EXTENSION_PATH] : [])
-            ],
+            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.
@@ -1069,9 +1087,9 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     }
     return sections.map(({ name, text }) => `${name}\n${text}`).join('\n\n');
 }
-export async function phaseAutoAnswer(deps, refined, research, question, autoDeps = {}) {
-    const docsFocusedFn = autoDeps.docsFocused ?? docsFocused;
-    const fetchFocusedFn = autoDeps.fetchFocused ?? fetchFocused;
+export async function phaseAutoAnswer(deps, refined, research, question) {
+    const docsFocusedFn = deps.docsFocused ?? docsFocused;
+    const fetchFocusedFn = deps.fetchFocused ?? fetchFocused;
     try {
         // Same assembly as the research phase (see external-context.ts); what
         // differs is POLICY and the worker variant, and both are arguments now.
@@ -1109,7 +1127,7 @@ export async function phaseAutoAnswer(deps, refined, research, question, autoDep
                 });
                 return { body: countBody(r.answer || undefined) };
             },
-            search: autoDeps.searchFn
+            search: deps.searchFn
         }, { targetCap: 2, serviceCap: 2 });
         const basePrompt = externalContext + GRILL_AUTO_ANSWER_PROMPT(refined, research, question);
         let text = await runPhaseChild(deps, 'grill-auto', 'read', basePrompt);
@@ -1194,8 +1212,11 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
     // nothing ambiguous remains. Kept in sync with /task-auto's clarify dialog.
     const theme = ctx.ui.theme;
     const ui = new SessionUI(ctx);
-    const out = []; // human-facing Q&A transcript (with auto-worker debug lines)
-    const qa = []; // compact Q&A fed back into the next question
+    // 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.
+    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
     // near-duplicate question is reprompted (not auto-answered or shown), and after
@@ -1209,7 +1230,7 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
     for (let n = 0; n < MAX_GRILL_QUESTIONS; n++) {
         const tGenStart = Date.now();
         const genHint = dupHint;
-        const raw = await runPhaseWithLoopGuard(deps, 'grill-gen', 'read', hint => prependHint(hint, prependHint(genHint, GRILL_GEN_PROMPT(refined, research, qa.join('\n')))));
+        const raw = await runPhaseChild(deps, 'grill-gen', 'read', prependHint(genHint, GRILL_GEN_PROMPT(refined, research, transcript.forGenerator())), { verb: 'restart' });
         deps.recordSubStep?.('gen', Date.now() - tGenStart);
         const questions = parseGrillQuestions(raw);
         if (questions.length === 0)
@@ -1235,11 +1256,8 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
         // for the editable default and the persisted file.
         const shownQ = renderInlineMarkdown(q, theme);
         const plainQ = stripInlineMarkdown(q);
-        out.push(`Q${n + 1}: ${plainQ}`);
-        let answer;
         if (auto.kind === 'answered') {
-            answer = stripInlineMarkdown(auto.text);
-            out.push(`A${n + 1}: ${answer} (auto)`);
+            transcript.add('auto', plainQ, stripInlineMarkdown(auto.text));
         }
         else {
             const plainSuggested = auto.suggested === undefined ? undefined : stripInlineMarkdown(auto.suggested);
@@ -1251,12 +1269,15 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
             // guard direction, promoting a hallucination is not.
             const yolo = yoloPickAutoAnswer(isYoloMode(), auto);
             if (yolo !== null) {
-                answer =
-                    yolo.kind === 'answer' ?
-                        stripInlineMarkdown(yolo.answer)
-                        : `(skipped — ${yolo.note})`;
-                out.push(`A${n + 1}: ${answer} ${YOLO_STAMP}`);
-                qa.push(`Q${n + 1}: ${plainQ}\nA${n + 1}: ${answer} ${YOLO_STAMP}`);
+                // The YOLO stamp is a RECORD fact. It used to be pushed into the
+                // generator feedback too, against the rule stated a dozen lines
+                // below — the policy now decides, so the two cannot disagree.
+                if (yolo.kind === 'answer') {
+                    transcript.add('yolo', plainQ, stripInlineMarkdown(yolo.answer));
+                }
+                else {
+                    transcript.add('yolo-skip', plainQ, `(skipped — ${yolo.note})`);
+                }
                 continue;
             }
             // The picker cards and the reply mapping are shared with /task-auto's
@@ -1287,17 +1308,17 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
             });
             if (a === undefined)
                 throw new Error(USER_CANCELLED);
-            // No provenance stamp here, unlike clarify's transcript: this string is
-            // fed back VERBATIM into the next grill-gen prompt, so a
-            // "(accepted recommendation)" suffix would become model input.
-            answer = resolveAnswer(pending, a).answer;
-            out.push(`A${n + 1}: ${answer}`);
+            // Grill's generator sees NO provenance — its feedback is fed verbatim
+            // into the next grill-gen prompt, where a suffix would describe how the
+            // answer was obtained rather than what it was. That is
+            // `GRILL_QA_POLICY.generatorSeesProvenance: false`, stated once.
+            const resolved = resolveAnswer(pending, a);
+            transcript.add(resolved.source === 'accepted' ? 'accepted' : 'typed', plainQ, resolved.answer);
         }
-        qa.push(`Q${n + 1}: ${plainQ}\nA${n + 1}: ${answer}`);
     }
-    if (out.length === 0)
+    if (transcript.length === 0)
         return '(no questions produced)';
-    return out.join('\n');
+    return transcript.forRecord();
 }
 /**
  * A refutation is a DELETION. Where the run's own research explicitly says a
@@ -1323,11 +1344,32 @@ export async function dropRefutedConstraints(deps, refined, research) {
     const refuted = applyRefutations(refined, research);
     if (refuted.trail.length === 0)
         return refined;
-    for (const line of refuted.trail) {
-        deps.logDebug?.(`compose: ${line}`);
+    await recordPhaseTrail(deps, 'compose', refuted.trail);
+    return refuted.refined;
+}
+/**
+ * COMPOSE's carry: the refutation drop, as a `PhaseConfig.carry`.
+ *
+ * Same transform as `dropRefutedConstraints` over the same pure core, minus the
+ * recording — the caller decides whether this application is the live one or a
+ * resume replay. `dropRefutedConstraints` stays exported and unchanged for the
+ * harnesses under `scripts/` that drive the drop directly.
+ */
+export function composeCarry(_deps, pc) {
+    // Not `async`, and that is the shape rather than an oversight: this carry
+    // performs no I/O at all, which is what lets the resume path replay it.
+    const refuted = applyRefutations(pc.refined, pc.research);
+    if (refuted.trail.length === 0)
+        return Promise.resolve([]);
+    pc.refined = refuted.refined;
+    return Promise.resolve(refuted.trail);
+}
+/** Write a carry's trail to the debug log and the task file's `## gates` section. */
+export async function recordPhaseTrail(deps, phaseName, trail) {
+    for (const line of trail) {
+        deps.logDebug?.(`${phaseName}: ${line}`);
         await appendGateRecord(deps.cwd, deps.taskId, line).catch(() => { });
     }
-    return refuted.refined;
 }
 export async function phaseCompose(deps, refined, research, qa) {
     // CLAIM before the belt is built: an obligation an earlier task had to
@@ -1497,92 +1539,130 @@ export async function critiqueWithFallback(d, p) {
     }
 }
 // ─── Phase config table ──────────────────────────────────────────────────────
+/**
+ * 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
+ * contradict is the fix. Silent + no-op when nothing is wrong or the runtime's types
+ * aren't installed.
+ */
+export async function refinePhase(d, p) {
+    const refined = await phaseRefine(d, p.rawPrompt, p.planContext);
+    const phantoms = await findPhantomImports(refined, d.cwd);
+    if (phantoms.length === 0)
+        return refined;
+    d.logDebug?.(`phantom specifiers rewritten in refined: ${phantoms.map(x => x.spec).join(', ')}`);
+    return rewritePhantomSpecifiers(refined, phantoms);
+}
+/**
+ * RESEARCH — the four workers, then the TOOLING verification pass, then a
+ * deterministic check of every runtime builtin specifier the refined task names
+ * (`bun:sql`, `node:…`) against the installed types. A doc can confidently name a
+ * module that does not exist; left unchecked it rides through every phase and the
+ * implementer fabricates a `declare module` shim to compile it. The corrections are
+ * APPENDED so compose folds them into CONSTRAINTS. No LLM cost, silent when clean.
+ */
+export async function researchPhase(d, p) {
+    const tResearch = Date.now();
+    const rawResearch = await phaseResearch(d, p.refined);
+    d.recordSubStep?.('workers', Date.now() - tResearch);
+    const tVerify = Date.now();
+    const out = await phaseVerifyTooling(d, rawResearch);
+    d.recordSubStep?.('verify-tooling', Date.now() - tVerify);
+    const corrections = formatApiCorrections(await findPhantomImports(p.refined, d.cwd));
+    if (corrections) {
+        d.logDebug?.(`phantom imports flagged:\n${corrections}`);
+        return `${out}\n\n${corrections}`;
+    }
+    return out;
+}
+/** GRILL — the adaptive question loop, and the only phase that talks to the user. */
+export function grillPhase(d, p) {
+    return phaseGrill(d, p.ctx, p.widgetState, p.refined, p.research);
+}
+/**
+ * COMPOSE — compose the spec from the refined task, the research and the Q&A.
+ *
+ * The refutation drop that must happen first is compose's declared `carry`
+ * (`composeCarry`), not a line at the top of this function. It settles `p.refined`,
+ * which is not compose's own `field`, so the orchestrator has to replay it on the
+ * resume path too — and a `run` body cannot be replayed.
+ */
+export async function composePhase(d, p) {
+    return await phaseCompose(d, p.refined, p.research, p.qa);
+}
+/**
+ * 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
+ * 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.
+ */
+export async function critiquePhase(d, p) {
+    const spec = await critiqueWithFallback(d, p);
+    const owned = await ownedForThisTask(d);
+    if (owned.length === 0)
+        return spec;
+    const out = appendOwnedConstraints(spec, owned);
+    if (out !== spec) {
+        d.logDebug?.('owned-requirements braces: appended omitted design obligation(s) to CONSTRAINTS');
+    }
+    return await resolveOwnedFreezeForThisTask(d, out);
+}
+/**
+ * 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.
+ */
 export const PHASES = [
     {
         name: 'refine',
         section: 'refined prompt',
         field: 'refined',
-        run: async (d, p) => {
-            const refined = await phaseRefine(d, p.rawPrompt, p.planContext);
-            // Subtractively strike any phantom runtime specifier (`bun:sql`) the
-            // refine 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 contradict is the fix. Silent + no-op when nothing is wrong
-            // or the runtime's types aren't installed.
-            const phantoms = await findPhantomImports(refined, d.cwd);
-            if (phantoms.length === 0)
-                return refined;
-            d.logDebug?.(`phantom specifiers rewritten in refined: ${phantoms.map(x => x.spec).join(', ')}`);
-            return rewritePhantomSpecifiers(refined, phantoms);
-        }
-    },
-    {
-        name: 'research',
-        section: 'research',
-        field: 'research',
-        run: async (d, p) => {
-            const tResearch = Date.now();
-            const rawResearch = await phaseResearch(d, p.refined);
-            d.recordSubStep?.('workers', Date.now() - tResearch);
-            const tVerify = Date.now();
-            const out = await phaseVerifyTooling(d, rawResearch);
-            d.recordSubStep?.('verify-tooling', Date.now() - tVerify);
-            // Deterministically verify every runtime builtin specifier the refined
-            // task names (`bun:sql`, `node:…`) against the installed types. A doc can
-            // confidently name a module that does not exist; left unchecked it rides
-            // through every phase and the implementer fabricates a `declare module`
-            // shim to compile it. Append the corrections so compose folds them into
-            // CONSTRAINTS. No LLM cost and silent when nothing is wrong.
-            const corrections = formatApiCorrections(await findPhantomImports(p.refined, d.cwd));
-            if (corrections) {
-                d.logDebug?.(`phantom imports flagged:\n${corrections}`);
-                return `${out}\n\n${corrections}`;
-            }
-            return out;
-        }
-    },
-    {
-        name: 'grill',
-        section: 'grill Q&A',
-        field: 'qa',
-        run: (d, p) => phaseGrill(d, p.ctx, p.widgetState, p.refined, p.research)
-    },
-    {
-        name: 'compose',
-        section: 'spec',
-        field: 'spec',
-        run: async (d, p) => {
-            p.refined = await dropRefutedConstraints(d, p.refined, p.research);
-            return await phaseCompose(d, p.refined, p.research, p.qa);
-        }
+        run: refinePhase,
+        postCommit: refinePostCommit
     },
-    {
-        name: 'critique',
-        section: 'spec',
-        field: 'spec',
-        run: async (d, p) => {
-            const spec = await critiqueWithFallback(d, p);
-            // BRACES (mx5 run 16): after the LAST spec-producing step, append any
-            // owned design obligation the spec still omits as a CONSTRAINTS
-            // bullet. The belt block upstream is obeyed ~25% (measured); a
-            // host-side append is obeyed by construction. Idempotent: quotes the
-            // spec already carries (belt-obeying reps) are skipped.
-            const owned = await ownedForThisTask(d);
-            if (owned.length === 0)
-                return spec;
-            const out = appendOwnedConstraints(spec, owned);
-            if (out !== spec) {
-                d.logDebug?.('owned-requirements braces: appended omitted design obligation(s) to CONSTRAINTS');
-            }
-            // An owned obligation whose only file this spec also FREEZES is
-            // unsatisfiable here; move it to the pending task that writes that
-            // file rather than shipping a requirement no one can meet.
-            return await resolveOwnedFreezeForThisTask(d, out);
-        }
-    }
+    { name: 'research', section: 'research', field: 'research', run: researchPhase },
+    { name: 'grill', section: 'grill Q&A', field: 'qa', run: grillPhase },
+    { name: 'compose', section: 'spec', field: 'spec', carry: composeCarry, run: composePhase },
+    { name: 'critique', section: 'spec', field: 'spec', run: critiquePhase }
 ];
+/**
+ * Run one phase row the way the orchestrator does: carry, then run.
+ *
+ * The row is the interface, so this is the surface a row-driving test crosses —
+ * calling `row.run` alone tests past it and would not have caught a carry that the
+ * resume path drops. The orchestrator adds only persistence, timings and the
+ * checkpoint around this.
+ */
+export async function runPhaseRow(row, deps, pc) {
+    if (row.carry)
+        await recordPhaseTrail(deps, row.name, await row.carry(deps, pc));
+    return await row.run(deps, pc);
+}
+/**
+ * Re-apply one phase row's carry on the RESUME path, where `run` is skipped.
+ *
+ * The trail is discarded: the live run that produced this phase's output already
+ * recorded it on `## gates`, and a replay must not append a second copy.
+ */
+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
@@ -1627,9 +1707,16 @@ export const PHASES = [
 //
 // 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.
+/** Dispatch a row's declared post-commit effect. Rows with none do nothing. */
 export async function postCommitPhase(phase, deps, pc, out) {
-    if (phase.name !== 'refine')
-        return;
+    await phase.postCommit?.(deps, pc, out);
+}
+/**
+ * REFINE's post-commit: derive the task title from the refined prompt, then a short
+ * display label. Runs after the section write, so a fault here cannot lose the
+ * output it reads.
+ */
+export async function refinePostCommit(deps, pc, out) {
     const title = deriveTitle(out);
     pc.widgetState.title = title;
     // Compress the (often paragraph-long) title into a short display label. This

package/dist/task/plan-orchestrator.js

@@ -187,8 +187,8 @@ async function defaultHandoff(ctx, cwd, prompt) {
         await runGatedTask(ctx, cwd, prompt);
         return undefined;
     }
-    const { taskId, sessionCancelled } = await runSingleTask(ctx, cwd, prompt, { notifyFinish: true });
-    if (sessionCancelled) {
+    const { taskId, end } = await runSingleTask(ctx, cwd, prompt, { notifyFinish: true });
+    if (end.kind === 'no-session') {
         ctx.ui.notify('Could not start a fresh session for /task-plan.', 'warning');
         return undefined;
     }

package/dist/task/plan-rounds.d.ts

@@ -0,0 +1,86 @@
+/**
+ * What the PLAN-SHAPING loops record, and the decisions that record makes.
+ *
+ * `GateTally`'s and `AutofixLedger`'s twin, one phase earlier. CONTEXT.md records
+ * that shape twice already: a long loop threading mutable locals by closure, with
+ * pure helpers extracted for testability while the ORDERING and CARRY-FORWARD
+ * decisions stayed in the caller. `coverPlan` was the third instance — five locals
+ * (`planTitles`, `best`, `round`, `roundCap`, `bonusRoundUsed`) plus a
+ * snapshot-before-overwrite pair (`priorCovered`, `priorMissing`) that existed
+ * ONLY because the bonus-round decision was made downstream from the evidence it
+ * needed, so the loop had to save a copy of `best` before replacing it.
+ *
+ * The last real bug here says the shape out loud, in the loop's own comment:
+ * *"This used to be two assignments, and the second one kept the OLD plan's
+ * accounting whenever the new plan's coverage-map child faulted
+ * (`cand.accounting ?? accounting`) — binding requirements to titles they were
+ * never mapped against."* `AutofixLedger`'s indictment, verbatim: the decision was
+ * made downstream from the evidence.
+ *
+ * `consider` closes it by construction rather than by comment. It compares, it
+ * replaces the plan WHOLE (titles and accounting together, because they are one
+ * value), and it grants the bonus round IN THE SAME CALL that adopts — the way
+ * `judge(outcome, edited)` enters the demoted signature in the call that demotes.
+ * There is no window in which the snapshot and the replacement can disagree.
+ *
+ * NO I/O. No `logPlanDebug`, no notify, no child — for the same reason `GateTally`
+ * performs none: a record that performs effects cannot be driven by a test that
+ * only wants the verdict. The caller trails what the returned decision says.
+ */
+import { type AdoptionDecision, type ScoredPlan } from './coverage-loop.js';
+/** What `consider` did with a candidate, and why. */
+export interface ConsiderOutcome {
+    adopted: boolean;
+    /** The adoption verdict's own reasoning, for the caller's trail. */
+    decision: AdoptionDecision;
+    /** True when this adoption is what bought the one bonus round. */
+    grantedBonusRound: boolean;
+}
+export interface CoverageLedgerOptions {
+    /** The round cap before any bonus. */
+    cap: number;
+    /**
+     * Are there grounded requirements to judge against?
+     *
+     * Without them `missing` is pure holistic-judge free text that can change every
+     * round, so there is no trustworthy "grew"/"new" signal — which is why the
+     * bonus round is requirements-path only.
+     */
+    hasRequirements: boolean;
+}
+/**
+ * The coverage loop's record: the best plan seen, the rounds spent, and the
+ * one-shot bonus round.
+ *
+ * Methods are named for what they MEAN, not for the field they touch.
+ */
+export declare class CoverageLedger {
+    private _best;
+    private readonly _opts;
+    private _round;
+    private _cap;
+    private _bonusUsed;
+    constructor(_best: ScoredPlan, _opts: CoverageLedgerOptions);
+    /** The best-covered plan seen so far — the one that reprompts, and the one that ships. */
+    best(): ScoredPlan;
+    /** Rounds spent so far. */
+    round(): number;
+    /** May another reprompt round run? */
+    mayRetry(): boolean;
+    /** Spend a round. Call once per reprompt, before the child runs. */
+    startRound(): number;
+    /** What is still uncovered in the shipping plan, or null when nothing is. */
+    unresolved(): string[] | null;
+    /**
+     * Judge one candidate against the best plan and, if it wins, adopt it.
+     *
+     * The bonus-round grant is decided HERE, against the pre-adoption plan this
+     * method still holds — not by a caller reading a snapshot it took beforehand.
+     * Two guards keep it off generic judge churn: the grounded covered-set must
+     * strictly GROW (a flaky judge relabelling the same-shaped plan's gap does not
+     * qualify), and the candidate must expose a NEW area (a gap already present is
+     * one we have reprompted against or will). Bounded to one, so a judge that
+     * flags forever still cannot loop the plan phase.
+     */
+    consider(cand: ScoredPlan): ConsiderOutcome;
+}