@mjasnikovs/pi-task 0.38.10 → 0.38.12

package/dist/task/orchestrator.js

@@ -25,11 +25,10 @@ import { readTextFile } from '../shared/fs-text.js';
 import { allocateTaskId, ensureTasksDir, readSection, readTaskFile, setTaskSection, taskFilePath, tasksDir, updateTaskFrontMatter, writeTaskFile } from './task-io.js';
 import { startWidget } from './widget.js';
 import { armImplWidget, disarmImplWidget, setupImplWidget } from './impl-widget.js';
-import { publishViewer, publishNotify, publishLifecycleNotice, registerBridgeCommand, getBridge, SessionUI } from '../remote/bridge.js';
+import { publishViewer, publishNotify, registerBridgeCommand, getBridge } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { getConfig } from '../config/config.js';
 import { gateDebugWriter } from './debug-log.js';
-import { consumeWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js';
 import { buildGateDeps } from './gate-deps.js';
 import { runGatesForTask } from './task-gates.js';
 import { parseVerifyBlock } from './spec-validation.js';
@@ -37,11 +36,12 @@ import { findDeliveryPhantoms, formatApiOverrideBanner } from '../workers/phanto
 import { titleForDisplay } from './parsers.js';
 import { USER_CANCELLED } from './child-runner.js';
 import { cancelCheckpoint } from './cancel-points.js';
-import { armCancelListener, disarmCancelListener, rearmCancelListener } from './cancel-input.js';
-import { beginRun, endRun, takeHeldInput } from './mid-run-input.js';
-import { reportDroppedInput } from './dropped-input.js';
+import { rearmCancelListener } from './cancel-input.js';
+import { takeHeldInput } from './mid-run-input.js';
+import { withRun, announceTerminal } from './run-bracket.js';
 import { formatTimings } from './timings.js';
 import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
+import { superviseImplementation } from './implementation-turn.js';
 import { TERMINAL_OUTCOMES, formatAt, formatWhy } from './terminal-outcome.js';
 // ─── Module-level state ──────────────────────────────────────────────────────
 let activeTask = null;
@@ -67,10 +67,7 @@ export class TaskRunner {
     _onStart;
     _planContext;
     _fixInstruction;
-    /** True when the caller awaits the implementation turn (waitForImplementation):
-     *  the impl widget stays armed across the whole impl phase (incl. compaction /
-     *  steer turns) and is disarmed here. False for fire-and-forget /task, where the
-     *  widget is armed one-shot and its own agent_end disarms it. */
+    /** See {@link TaskRunnerOptions.implAwaited}. */
     _implAwaited;
     _abort = new AbortController();
     _startedAt;
@@ -87,16 +84,17 @@ export class TaskRunner {
      */
     _timings = [];
     _currentPhaseChildren = null;
-    constructor(ctx, cwd, rawPrompt, resumeId, sendSpec, spawnFn, onStart, planContext, fixInstruction, implAwaited) {
+    constructor(opts) {
+        const { ctx, cwd, rawPrompt } = opts;
         this._ctx = ctx;
         this._cwd = cwd;
         this._rawPrompt = rawPrompt;
-        this._resumeId = resumeId;
-        this._sendSpec = sendSpec;
-        this._onStart = onStart;
-        this._planContext = planContext;
-        this._fixInstruction = fixInstruction;
-        this._implAwaited = implAwaited ?? false;
+        this._resumeId = opts.resumeId;
+        this._sendSpec = opts.sendSpec;
+        this._onStart = opts.onStart;
+        this._planContext = opts.planContext;
+        this._fixInstruction = opts.fixInstruction;
+        this._implAwaited = opts.implAwaited ?? false;
         this._startedAt = Date.now();
         // We'll populate id/title/phase lazily in run().
         // Placeholder — real values set in run().
@@ -111,7 +109,13 @@ export class TaskRunner {
             cwd,
             taskId: '',
             signal: this._abort.signal,
-            spawn: spawnFn,
+            spawn: opts.spawnFn,
+            runChild: opts.runChild,
+            // Deliberately NOT a ChildStatus (child-status.ts): the phase widget's
+            // state is the whole-run WidgetState — task id, phase, label — shared by
+            // reference with PhaseContext and written by the phases themselves
+            // (grill sets `lastLine`, compose sets the title). Only these two
+            // callbacks overlap, and they call the same resolveContextUsage.
             onChildOutput: (line) => {
                 this._widgetState.lastLine = line;
             },
@@ -151,14 +155,17 @@ export class TaskRunner {
     cancel() {
         this._abort.abort();
     }
-    /** Execute the full task lifecycle. */
+    /** Execute the full task lifecycle. Mid-run input holds instead of starting
+     *  a competing turn for the whole of it, and the terminal interception is
+     *  armed for the same window (`withRun`); nested inside `runGatedTask` or
+     *  the `/task-auto` loop the bracket refcounts, so this changes nothing there
+     *  and covers the fire-and-forget `runSingleTask` path on its own. */
     async run() {
+        return withRun(this._ctx, {}, () => this._run());
+    }
+    async _run() {
         const cwd = this._cwd;
         const ctx = this._ctx;
-        // Mid-run input holds instead of starting a competing turn from here on,
-        // and the terminal interception is armed for the same window.
-        beginRun();
-        armCancelListener(ctx);
         // Initialise or resume the TASK file.
         let id;
         let title;
@@ -290,8 +297,6 @@ export class TaskRunner {
         finally {
             this._disposeWidget();
             clearActiveTask(this);
-            disarmCancelListener();
-            reportDroppedInput(endRun(), ctx);
         }
     }
     /** Stop the phase widget — clearing both the terminal and remote surfaces —
@@ -303,7 +308,7 @@ export class TaskRunner {
         this._stopWidget = null;
     }
     async _deliverSpec(_ctx) {
-        const spec = this._specForDelivery();
+        const spec = await this._specForDelivery();
         // Keep the rich status block alive across the implementation turn (the phase
         // widget was disposed at handoff). Awaited (/task-auto) stays armed across all
         // sub-turns and is disarmed here; fire-and-forget (/task) arms one-shot and its
@@ -343,8 +348,8 @@ export class TaskRunner {
      * deterministic check proves does not exist. No-op (returns the spec unchanged) when
      * nothing is flagged or the runtime's types aren't installed.
      */
-    _specForDelivery() {
-        const phantoms = findDeliveryPhantoms(this._pc.spec, this._cwd);
+    async _specForDelivery() {
+        const phantoms = await findDeliveryPhantoms(this._pc.spec, this._cwd);
         const apiBanner = formatApiOverrideBanner(phantoms);
         if (apiBanner) {
             this._deps.logDebug?.(`impl-handoff API override banner prepended for: ${phantoms.map(p => p.spec).join(', ')}`);
@@ -366,238 +371,6 @@ export class TaskRunner {
         return banners ? `${banners}\n\n${this._pc.spec}` : this._pc.spec;
     }
 }
-/** Dialog copy for the post-interrupt steering prompt. */
-const STEER_TITLE = 'Paused — steer the model';
-const STEER_PLACEHOLDER = 'Type guidance to continue this task, or leave empty to pause';
-/** Remote-card copy for the same prompt. The browser has no placeholder ghost
- *  text, so the pause affordance must be spelled out in the question itself
- *  (Skip = empty answer = pause, same as an empty local submit). */
-const STEER_QUESTION = 'Paused — the implementation was interrupted.\n'
-    + 'Type guidance to continue this task, or Skip to pause the run.';
-/**
- * True when the most recent assistant turn ended because the user interrupted it
- * (pressed ESC). pi records a user abort as stopReason "aborted" on the assistant
- * message, distinct from a natural "stop". Read after the implementation wait so
- * the /task-auto loop can tell "user wants to steer" apart from "task finished".
- */
-function wasInterrupted(ctx) {
-    const entries = ctx.sessionManager.getEntries();
-    for (let i = entries.length - 1; i >= 0; i--) {
-        const e = entries[i];
-        if ('message' in e && 'role' in e.message && e.message.role === 'assistant') {
-            return e.message.stopReason === 'aborted';
-        }
-    }
-    return false;
-}
-/**
- * The error cause when the most recent assistant turn ended with stopReason
- * "error" — the model/provider failed mid-implementation (context overflow,
- * disconnect, provider 5xx) after pi exhausted its own retries. Returns the
- * provider's errorMessage, or undefined if the turn ended cleanly ("stop") or
- * was user-aborted ("aborted", handled by wasInterrupted).
- *
- * The /task-auto loop reads this AFTER the implementation wait: a task's file is
- * marked `completed` at spec-handoff (before implementation), so without this
- * check an implementation turn that died — e.g. "400 ... exceeds the available
- * context size" — would still read as ok and get checked off and committed.
- */
-function implementationError(ctx) {
-    const entries = ctx.sessionManager.getEntries();
-    for (let i = entries.length - 1; i >= 0; i--) {
-        const e = entries[i];
-        if ('message' in e && 'role' in e.message && e.message.role === 'assistant') {
-            const m = e.message;
-            return m.stopReason === 'error' ? (m.errorMessage ?? 'model error') : undefined;
-        }
-    }
-    return undefined;
-}
-/**
- * True when the implementation turn went idle right after a context compaction —
- * the most recent entry in the branch is a `compaction` boundary sitting after the
- * last assistant message.
- *
- * A *threshold* auto-compaction (the runtime's "context is getting large" path)
- * compacts and then deliberately does NOT auto-continue: it returns to idle and
- * expects a manual continue (`_runAutoCompaction("threshold", false)` →
- * `hasQueuedMessages()` is false → the agent loop stops). Our implementation wait
- * resolves at exactly that idle. Without this check it reads as "the model
- * finished" (the last assistant message is a normal `stop`, not `aborted`/`error`),
- * so the run jumps straight to the verify gate and abandons a half-done task at the
- * compaction boundary — the failure this detector closes.
- *
- * Position-based, not timestamp-based: the runtime APPENDS the compaction entry to
- * the tail of the branch after the assistant message that triggered it
- * (`appendCompaction` → `_appendEntry` push), so a `compaction` after the last
- * assistant message means we are parked on a compaction with no continuation. A
- * genuinely finished turn ends on an assistant message with no trailing compaction;
- * an *overflow* compaction self-retries, so it never leaves us idle here.
- */
-export function endedAtCompactionBoundary(ctx) {
-    const entries = ctx.sessionManager.getEntries();
-    let lastAssistant = -1;
-    let lastCompaction = -1;
-    for (let i = 0; i < entries.length; i++) {
-        const e = entries[i];
-        if ('message' in e && 'role' in e.message && e.message.role === 'assistant') {
-            lastAssistant = i;
-        }
-        else if (e.type === 'compaction') {
-            lastCompaction = i;
-        }
-    }
-    return lastCompaction > lastAssistant;
-}
-/**
- * Nudge that resumes an implementation turn the runtime parked at a compaction
- * boundary. It must let a turn that was genuinely finished (then tipped over the
- * threshold by its own final message) confirm completion without inventing busywork
- * — we cannot tell "paused mid-task by compaction" from "finished, then compacted"
- * from the boundary alone, so the wording lets a done turn end in one line.
- */
-export const CONTINUE_AFTER_COMPACTION = 'Your context was automatically compacted. Continue implementing this task from '
-    + 'exactly where you left off, and keep going until it is fully done. If the '
-    + 'implementation is already complete, say so in one line and stop — do not invent '
-    + 'extra work or restart the task.';
-/**
- * Safety cap on compaction-driven resumes for a single implementation turn. Each
- * resume follows a real compaction (which only fires after the model produced a
- * turn large enough to cross the threshold), so a legitimately large task may
- * resume a handful of times; the cap exists only to stop a pathological loop from
- * auto-sending forever with no user in the loop. Hitting it stops resuming and lets
- * the verify gate / `/task-auto-resume` catch any leftover incompleteness.
- */
-export const MAX_COMPACTION_RESUMES = 20;
-/**
- * Resume an implementation turn that went idle at a threshold-compaction boundary.
- * The runtime compacts and parks at idle without auto-continuing; we send a
- * continue and wait again, repeating across successive compactions until the turn
- * ends on a real assistant message (genuine completion). A user ESC takes priority
- * (it is not a compaction boundary, and `wasInterrupted` guards the loop so the
- * steer loop handles it), and the safety cap bounds a runaway. Returns the number
- * of resumes performed (0 when the turn did not end on a compaction).
- */
-export async function resumeAcrossCompactions(ctx) {
-    let resumes = 0;
-    while (resumes < MAX_COMPACTION_RESUMES
-        && !wasInterrupted(ctx)
-        && endedAtCompactionBoundary(ctx)) {
-        await ctx.sendUserMessage(CONTINUE_AFTER_COMPACTION, { deliverAs: 'followUp' });
-        await ctx.waitForIdle();
-        resumes++;
-    }
-    return resumes;
-}
-/**
- * True when the watchdog's reminder follow-up has been DELIVERED into the session
- * after the aborted assistant turn but its own turn has not finished yet — the
- * artifact that confirms a pending watchdog recovery. Scoped after the LAST
- * assistant entry so an earlier fire's reminder (already answered by its own
- * turn) never matches.
- */
-function watchdogReminderDelivered(ctx) {
-    const entries = ctx.sessionManager.getEntries();
-    let lastAssistant = -1;
-    for (let i = 0; i < entries.length; i++) {
-        const e = entries[i];
-        if ('message' in e && 'role' in e.message && e.message.role === 'assistant') {
-            lastAssistant = i;
-        }
-    }
-    for (let i = lastAssistant + 1; i < entries.length; i++) {
-        const e = entries[i];
-        if (!('message' in e) || !('role' in e.message) || e.message.role !== 'user')
-            continue;
-        const content = e.message.content;
-        const text = typeof content === 'string' ? content
-            : Array.isArray(content) ?
-                content
-                    .map(b => b !== null && typeof b === 'object' && 'text' in b ?
-                    String(b.text)
-                    : '')
-                    .join(' ')
-                : '';
-        if (text.includes(WATCHDOG_CANCEL_MARKER))
-            return true;
-    }
-    return false;
-}
-const STEER_WATCHDOG_DEFAULTS = {
-    consume: consumeWatchdogAbort,
-    graceMs: 10_000,
-    pollMs: 100
-};
-/**
- * Wait for a watchdog abort's queued follow-up turn instead of prompting. The
- * abort and the reminder follow-up are two separate steps in the watchdog's
- * onFire, so the steer loop can observe the aborted turn before the reminder is
- * delivered — poll (bounded) until it lands or the follow-up turn has already
- * completed. True = recovery observed, re-check the loop; false = grace expired
- * with no reminder (stale flag) — fall back to the human prompt.
- */
-async function awaitWatchdogFollowUp(ctx, wd) {
-    const deadline = Date.now() + wd.graceMs;
-    for (;;) {
-        if (!wasInterrupted(ctx))
-            return true; // follow-up turn already completed
-        if (watchdogReminderDelivered(ctx)) {
-            await ctx.waitForIdle(); // let the follow-up turn run to completion
-            return true;
-        }
-        if (Date.now() >= deadline)
-            return false;
-        await new Promise(r => setTimeout(r, wd.pollMs));
-    }
-}
-/**
- * After the implementation turn settles, honour a user ESC by letting them steer.
- *
- * `waitForIdle` resolves both on natural completion AND on an ESC (which aborts
- * the turn → idle). When the last turn was aborted, the host's main input loop is
- * blocked inside our command handler, so a message typed in the editor would only
- * queue, never run (interactive-mode routes idle input through onInputCallback,
- * which is unset while we hold the loop). We therefore solicit the steering text
- * ourselves and feed it back as another turn via sendUserMessage — which runs to
- * completion when the session is idle. Repeat until a turn finishes uninterrupted.
- *
- * A WATCHDOG abort also ends the turn with stopReason 'aborted' — indistinguishable
- * from a human ESC by the session entries alone at that instant. The watchdog
- * queues its own recovery follow-up, so prompting there would show a steering
- * dialog to an empty room and wedge an unattended run on the race. The one-shot
- * flag (set synchronously before the abort) routes that case to
- * {@link awaitWatchdogFollowUp} instead; a stale flag degrades to a bounded wait
- * followed by the ordinary prompt, never to a suppressed one.
- *
- * Returns true when the user declined to steer (empty/cancelled) and the run
- * should pause; false when the implementation completed (steered or not).
- */
-export async function steerUntilDone(ctx, promptSteer, watchdog) {
-    const wd = { ...STEER_WATCHDOG_DEFAULTS, ...watchdog };
-    // Fan the prompt out through the bridge (local TUI input + remote browser
-    // card, first answer wins) instead of a raw ctx.ui.input: an interrupt can
-    // come from the remote Stop button just as well as a terminal ESC, and a
-    // terminal-only dialog leaves the remote viewer staring at a silently
-    // paused run. Remote Skip returns '' → same pause path as an empty local
-    // submit.
-    const ask = promptSteer
-        ?? (c => new SessionUI(c).ask({
-            localTitle: STEER_TITLE,
-            localPlaceholder: STEER_PLACEHOLDER,
-            question: STEER_QUESTION,
-            allowSkip: true
-        }));
-    while (wasInterrupted(ctx)) {
-        if (wd.consume() && (await awaitWatchdogFollowUp(ctx, wd)))
-            continue;
-        const steer = await ask(ctx);
-        if (steer === undefined || steer.trim().length === 0)
-            return true; // pause
-        await ctx.sendUserMessage(steer, { deliverAs: 'followUp' });
-        await ctx.waitForIdle();
-    }
-    return false;
-}
 /**
  * Run one prompt through the full single-task pipeline in a fresh session and
  * deliver its spec. With waitForImplementation, block until the agent finishes
@@ -625,26 +398,35 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
             // happens at the START of each task — precisely the window a typed
             // /task-auto-cancel has to survive. No-op unless a run armed one.
             rearmCancelListener(newCtx);
-            const runner = new TaskRunner(newCtx, cwd, rawPrompt, opts.resumeId, async (spec) => {
-                // Queue-or-run: never throws, whatever else is on the session (issue #8).
-                await newCtx.sendUserMessage(spec, { deliverAs: 'followUp' });
-                if (opts.waitForImplementation) {
-                    await newCtx.waitForIdle();
-                    // A threshold auto-compaction parks the turn at idle WITHOUT
-                    // auto-continuing (the runtime expects a manual continue). Our
-                    // single waitForIdle resolves there, so without this the run
-                    // would treat a compaction mid-task as completion and jump
-                    // straight to the verify gate. Resume across any compaction
-                    // boundaries first, so steering/error inspection below see the
-                    // turn's REAL end, not a compaction pause.
-                    await resumeAcrossCompactions(newCtx);
-                    interrupted = await steerUntilDone(newCtx, opts.promptSteer);
-                    // A user-declined steer (interrupted) is its own paused
-                    // path; otherwise inspect how the turn actually ended.
-                    if (!interrupted)
-                        implError = implementationError(newCtx);
-                }
-            }, opts.spawnFn, opts.onStart, opts.planContext, opts.fixInstruction, opts.waitForImplementation);
+            const runner = new TaskRunner({
+                ctx: newCtx,
+                cwd,
+                rawPrompt,
+                resumeId: opts.resumeId,
+                sendSpec: async (spec) => {
+                    // Queue-or-run: never throws, whatever else is on the session (issue #8).
+                    await newCtx.sendUserMessage(spec, { deliverAs: 'followUp' });
+                    if (opts.waitForImplementation) {
+                        await newCtx.waitForIdle();
+                        // A threshold auto-compaction parks the turn at idle WITHOUT
+                        // auto-continuing, and a user ESC ends it "aborted": the
+                        // first idle is not the turn's real end. superviseImplementation
+                        // resumes across compactions, steers across interrupts, and
+                        // reads how the turn ACTUALLY ended.
+                        const outcome = await superviseImplementation(newCtx, {
+                            promptSteer: opts.promptSteer
+                        });
+                        interrupted = outcome.interrupted;
+                        implError = outcome.error;
+                    }
+                },
+                spawnFn: opts.spawnFn,
+                runChild: opts.runChild,
+                onStart: opts.onStart,
+                planContext: opts.planContext,
+                fixInstruction: opts.fixInstruction,
+                implAwaited: opts.waitForImplementation
+            });
             await runner.run();
             taskId = runner.taskId;
         }
@@ -726,19 +508,13 @@ export async function runGatedTask(ctx, cwd, raw, opts = {}) {
     // TaskRunner would leave verify/enforce looking like "no run", which a live
     // run on pi 0.82.1 showed as runActive=false while the widget still read
     // "verifying work" (issue #8). The body has many early returns, so the
-    // bracket lives in this wrapper rather than in a dozen places.
-    beginRun();
-    // Arm the raw-stdin interception for the WHOLE run. Without this a plain
-    // /task had no terminal path at all — only /task-auto armed one — so a line
-    // typed during it went into pi's queue and fired after the run (seen live).
-    armCancelListener(ctx);
-    try {
-        await runGatedTaskInner(ctx, cwd, raw, opts);
-    }
-    finally {
-        disarmCancelListener();
-        reportDroppedInput(endRun(), ctx);
-    }
+    // bracket lives in this wrapper rather than in a dozen places. The same
+    // bracket arms the raw-stdin interception for the WHOLE run: without it a
+    // plain /task had no terminal path at all — only /task-auto armed one — so a
+    // line typed during it went into pi's queue and fired after the run (seen
+    // live). No onCancel: a typed /task-auto-cancel goes through the generic
+    // bridge dispatch here.
+    await withRun(ctx, {}, () => runGatedTaskInner(ctx, cwd, raw, opts));
 }
 async function runGatedTaskInner(ctx, cwd, raw, opts = {}) {
     const abort = new AbortController();
@@ -751,11 +527,8 @@ async function runGatedTaskInner(ctx, cwd, raw, opts = {}) {
     let active = ctx;
     // One push + remote bubble on the terminal outcome (parity with the
     // notifyFinish push the fire-and-forget path emits via runSingleTask).
-    const announce = (msg, level) => {
-        active.ui.notify(msg, level);
-        publishLifecycleNotice(msg, level);
-        void pushNotify('Task finished', msg, 'pi-end').catch(() => { });
-    };
+    // Bound late to `active`: a gate autofix can replace the live session.
+    const announce = (msg, level) => announceTerminal(active, msg, level);
     // First implementation run (blocking).
     const res = await deps.runTask(active, cwd, raw, { resumeId: opts.resumeId });
     active = res.ctx ?? active;

package/dist/task/phases.d.ts

@@ -5,6 +5,7 @@
 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';
@@ -102,6 +103,23 @@ export declare const phaseRefine: (deps: PhaseDeps, raw: string, planContext?: s
 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,

package/dist/task/phases.js

@@ -606,6 +606,7 @@ const CONTEXT_SILENT_RETRY_PREAMBLE = 'STOP. Your previous attempt at this task
     + '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);
     // 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
@@ -859,7 +860,7 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         }
         deps.logDebug?.(`${spec.label}: start`);
         const basePrompt = typeof spec.prompt === 'function' ? spec.prompt(prior) : spec.prompt;
-        const runOnce = (extraPreamble) => recordWorker(spec.label, runWorker({
+        const runOnce = (extraPreamble) => recordWorker(spec.label, runWorkerFn(spec.label, {
             prompt: extraPreamble ? `${extraPreamble}\n\n${basePrompt}` : basePrompt,
             cwd: deps.cwd,
             signal: deps.signal,
@@ -1510,7 +1511,7 @@ export const PHASES = [
             // (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 = findPhantomImports(refined, d.cwd);
+            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(', ')}`);
@@ -1534,7 +1535,7 @@ export const PHASES = [
             // 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(findPhantomImports(p.refined, d.cwd));
+            const corrections = formatApiCorrections(await findPhantomImports(p.refined, d.cwd));
             if (corrections) {
                 d.logDebug?.(`phantom imports flagged:\n${corrections}`);
                 return `${out}\n\n${corrections}`;