@mjasnikovs/pi-task 0.38.15 → 0.38.16

package/dist/task/phases.d.ts

@@ -3,12 +3,7 @@
  * critique) plus the config table that drives the orchestrator loop.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
-import { docsFocused } from '../workers/docs-core.js';
-import { fetchFocused } from '../workers/fetch-core.js';
-import { type RunWorkerInput, type RunWorkerResult } from '../workers/pi-worker-core.js';
-import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
-import type { SearchProvider } from '../workers/search-types.js';
-import { type ExternalContextDeps } from './external-context.js';
+import { type SearchProvider } from '../workers/search-types.js';
 import { MAX_GRILL_QUESTIONS } from './prompts.js';
 import { type PhaseName } from './task-types.js';
 import { type WidgetState } from './widget.js';
@@ -101,29 +96,9 @@ export declare function resolveOwnedFreezeForThisTask(deps: PhaseDeps, spec: str
 export declare function claimOwnedFreezeForThisTask(deps: PhaseDeps, refined: string): Promise<void>;
 export declare const phaseRefine: (deps: PhaseDeps, raw: string, planContext?: string) => Promise<string>;
 export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): Promise<string>;
-export interface PhaseResearchDeps extends ExternalContextDeps {
-    getFileInventory?: (cwd: string, signal?: AbortSignal) => Promise<string>;
-    /**
-     * Run ONE research worker. Absent (production) → the real `runWorker`.
-     *
-     * The seam exists for the same reason `getFileInventory` does: every decision
-     * `runSpec` makes — the three Research retry gates, the fatal/runaway/empty
-     * classification, the marker choice, `postProcess` — is a pure function of the
-     * returned `RunWorkerResult`, but reaching any of them used to require driving
-     * a fake process that emits JSON events. Substituting the result lets a gate be
-     * tested by the fields it actually reads.
-     *
-     * `label` is the worker's name — the same one `recordWorker` trails. It is
-     * passed because a substitute must answer differently per worker, and the only
-     * alternative is matching a marker sentence inside the prompt, which makes
-     * prompt copy load-bearing test infrastructure. Same reason
-     * `PhaseDeps.runChild` takes a name.
-     */
-    runWorker?: (label: string, input: RunWorkerInput) => Promise<RunWorkerResult>;
-}
 /**
  * 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 declare function searchConfigured(getEnv?: (k: string) => string | undefined, provider?: SearchProvider): boolean;
 /** Extra prompt block for the APIS worker when search is available — trigger-framed
@@ -177,13 +152,8 @@ export declare function degradedSectionBody(name: string, reason: string, partia
  */
 export declare function emptySectionBody(name: string): string;
 export declare function isBareNoneAnswer(text: string): boolean;
-export declare function phaseResearch(deps: PhaseDeps, refined: string, researchDeps?: PhaseResearchDeps): Promise<string>;
-export interface PhaseAutoAnswerDeps {
-    docsFocused?: typeof docsFocused;
-    fetchFocused?: typeof fetchFocused;
-    searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
-}
-export declare function phaseAutoAnswer(deps: PhaseDeps, refined: string, research: string, question: string, autoDeps?: PhaseAutoAnswerDeps): Promise<AutoAnswer>;
+export declare function phaseResearch(deps: PhaseDeps, refined: string): Promise<string>;
+export declare function phaseAutoAnswer(deps: PhaseDeps, refined: string, research: string, question: string): Promise<AutoAnswer>;
 export declare function phaseGrill(deps: PhaseDeps, ctx: ExtensionCommandContext, widgetState: WidgetState, refined: string, research: string): Promise<string>;
 /**
  * A refutation is a DELETION. Where the run's own research explicitly says a
@@ -220,5 +190,59 @@ export declare function phaseCritique(deps: PhaseDeps, spec: string, refined: st
  */
 extraDefects?: string | null): Promise<string>;
 export declare function critiqueWithFallback(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * 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 declare function refinePhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * 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 declare function researchPhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/** GRILL — the adaptive question loop, and the only phase that talks to the user. */
+export declare function grillPhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * COMPOSE — drop constraints research REFUTED before composing, then compose.
+ *
+ * The drop mutates `p.refined` in place on purpose: the refuted constraint must be
+ * gone from every later reader of the refined spec, not just from this call's
+ * argument. Critique re-reads it.
+ */
+export declare function composePhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * 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 declare function critiquePhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * 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 declare const PHASES: PhaseConfig[];
 export declare function postCommitPhase(phase: PhaseConfig, deps: PhaseDeps, pc: PhaseContext, out: string): Promise<void>;

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,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 { 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';
 // ─── Re-export constants from their home modules ────────────────────────────
@@ -262,7 +264,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 +272,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 +302,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 +619,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 +736,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 +764,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 +1086,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 +1126,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);
@@ -1209,7 +1226,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, qa.join('\n'))), { verb: 'restart' });
         deps.recordSubStep?.('gen', Date.now() - tGenStart);
         const questions = parseGrillQuestions(raw);
         if (questions.length === 0)
@@ -1497,91 +1514,101 @@ export async function critiqueWithFallback(d, p) {
     }
 }
 // ─── Phase config table ──────────────────────────────────────────────────────
-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);
-        }
-    },
-    {
-        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);
-        }
+/**
+ * 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 — drop constraints research REFUTED before composing, then compose.
+ *
+ * The drop mutates `p.refined` in place on purpose: the refuted constraint must be
+ * gone from every later reader of the refined spec, not just from this call's
+ * argument. Critique re-reads it.
+ */
+export async function composePhase(d, p) {
+    p.refined = await dropRefutedConstraints(d, p.refined, p.research);
+    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: refinePhase },
+    { name: 'research', section: 'research', field: 'research', run: researchPhase },
+    { name: 'grill', section: 'grill Q&A', field: 'qa', run: grillPhase },
+    { name: 'compose', section: 'spec', field: 'spec', run: composePhase },
+    { name: 'critique', section: 'spec', field: 'spec', run: critiquePhase }
 ];
 // INTEGRATION-DEPTH APPEND (2026-07-27): the lever proposed for this exact site —
 // deterministically append a known-runnable integration command to the VERIFY block

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/repo-health-check.d.ts

@@ -1,3 +1,4 @@
+import { type CommandRunner } from './command-run.js';
 export interface HealthOutcome {
     /** true → every discovered static check passed, or there was nothing to run.
      *  false → a discovered command actually ran and exited non-zero. */
@@ -29,38 +30,37 @@ export declare function discoverHealthCommands(cwd: string): {
     ecosystem: string | null;
     cmds: HealthCommand[];
 };
+/** Progress hook: called with each command's label as it STARTS, so a caller can
+ *  keep a live status line naming what is currently running. */
+export type HealthProgress = (command: string) => void;
 /**
  * Run the discovered static checks whole-repo and let the real exit codes decide.
- * Deterministic and synchronous under the hood (a wrapper keeps the caller async).
  *
  *  - No manifest / no static command  → ok (nothing can regress).
- *  - A command that CANNOT run (ENOENT / null exit — tool not installed) → skipped,
+ *  - A command that CANNOT run (ENOENT / null exit / 127 inside the chain) → skipped,
  *    treated as an environment gap, not a fault.
  *  - A command that ran and exited non-zero → the first such failure is returned.
  *
- * A generous per-command timeout guards against a wedged tool; a timeout is treated
- * as an inconclusive skip, not a fault (it is an environment problem, not the code's).
+ * This module owns DISCOVERY and its own output policy; running a command and
+ * deciding what its ending MEANS is `command-run.ts`'s. It used to own those too —
+ * `HealthRun`, `classifyHealthRun` and `spawnHealthCommand` were a second statement
+ * of the gap ladder, with no injectable runner, so every classification case in the
+ * suite spawned a real shell. `command-run.ts`'s own header notes that this module
+ * "had solved exactly this shape years earlier" and the gate never adopted it; this
+ * is the adoption, in the other direction.
  *
- * SYNCHRONOUS — it blocks the event loop for as long as the project's own lint takes
- * (MEASURED: 15s on mx5, 69s on aiz-client), so nothing can render or animate while
- * it runs. Gate callers must use {@link runRepoHealthCheckAsync} instead; this stays
- * for callers that genuinely have no async seam.
- */
-export declare function runRepoHealthCheck(cwd: string, timeoutMs?: number): HealthOutcome;
-/** Progress hook: called with each command's label as it STARTS, so a caller can
- *  keep a live status line naming what is currently running. */
-export type HealthProgress = (command: string) => void;
-/**
- * Same check, same verdicts, without blocking the event loop.
+ * `captureHealthOutput` stays this module's own: 40 lines of a linter's report is a
+ * real difference from `outputTail`'s 400 characters, and that is a parameter, not a
+ * thing to unify.
  *
- * The gate runs this immediately after the implementation turn ends, when the impl
- * widget has just been cleared — the sync version froze the whole TUI there for the
- * duration of the project's lint (MEASURED: 0 of 686 expected 100ms timer ticks
- * fired during a 69s aiz-client run), so no spinner, clock or queued notify could
- * paint. `onCommand` lets the caller name the running command in a live status line.
+ * `onCommand` lets the caller name the running command in a live status line — the
+ * gate runs this immediately after the implementation turn ends, when the impl
+ * widget has just been cleared.
  */
-export declare function runRepoHealthCheckAsync(cwd: string, opts?: {
+export declare function runRepoHealthCheck(cwd: string, opts?: {
     timeoutMs?: number;
     signal?: AbortSignal;
     onCommand?: HealthProgress;
+    /** The spawner. Injected so a verdict is testable without a real shell. */
+    run?: CommandRunner;
 }): Promise<HealthOutcome>;