@mjasnikovs/pi-task 0.37.7 → 0.38.1

package/dist/task/child-runner.js

@@ -124,52 +124,80 @@ export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsag
         leakedToolCall: loopHit ? undefined : (detectLeakedToolCall(text) ?? undefined)
     };
 }
+/**
+ * The error-triage ladder both phase wrappers run over a finished child, in
+ * this fixed order: non-zero exit → model error → empty completion → leaked
+ * tool call. Callers own the loop, the prompt and the hint; this owns the
+ * verdict, so a fix to any rung lands in every caller at once.
+ *
+ * `attempt` is the caller's 0-based counter (its attempt/strike), `budget` the
+ * matching restart allowance (MAX_LEAK_RETRIES for runPhaseChild's leak budget,
+ * MAX_LOOP_RESTARTS for runPhaseWithLoopGuard's strike budget) — so both run
+ * `budget + 1` attempts in total before a rung gives up and throws.
+ *
+ * `verb` names the caller's restart in the debug log ("retry" for runPhaseChild,
+ * "restart" for runPhaseWithLoopGuard). It is the only externally visible thing
+ * that differs between the two, and the only way to tell from a debug log which
+ * wrapper produced a given line — so it is passed in rather than hardcoded.
+ *
+ * A loop kill (`r.loopHit`) is NOT handled here: only runPhaseWithLoopGuard
+ * detects loops, and it must consume the hit before calling this.
+ */
+async function triageChildResult(deps, name, r, attempt, budget, verb) {
+    if (r.exitCode !== 0) {
+        throw new Error(`${name} child failed: ${r.stderr || '(no stderr)'}`);
+    }
+    if (r.modelError) {
+        // The model/provider failed (pi exited 0 with a stopReason "error"
+        // turn). A connection-class cause is transient — re-spawn within the
+        // caller's budget after a backoff; anything else fails fast (pi already
+        // retried, and re-spawning won't fix a real fault).
+        if (isConnectionError(r.modelError) && attempt < budget) {
+            deps.logDebug?.(`${name}: connection error "${r.modelError}" — ${verb} `
+                + `${attempt + 1}/${budget}`);
+            await (deps.sleepFor ?? defaultSleep)(connectionRetryBackoffMs(attempt));
+            return { done: false };
+        }
+        throw new ModelError(name, r.modelError);
+    }
+    if (r.text.trim().length === 0) {
+        // An empty completion (exit 0, no assistant text, no stderr) is almost
+        // always transient — a model/API error swallowed inside --mode json,
+        // not a repeatable mistake — so re-spawn rather than fail the phase.
+        // There's nothing to correct, so we carry no hint (and leave any hint
+        // the caller already has alone). Shares the caller's budget: budget+1
+        // attempts, then surface the error.
+        if (attempt === budget) {
+            throw new Error(`${name} child produced no output${r.stderr ? ' — stderr: ' + r.stderr : ''}`);
+        }
+        return { done: false };
+    }
+    if (r.leakedToolCall) {
+        if (attempt === budget) {
+            throw new LeakedToolCallError(name, r.leakedToolCall);
+        }
+        return { done: false, hint: leakedToolCallHint(r.leakedToolCall) };
+    }
+    return { done: true, text: r.text };
+}
 /**
  * Run a child pi and return its assistant text. Throws if exit code != 0.
  *
  * If the child leaks a tool call as plain text (wrong dialect — never executed),
  * re-prompt with a correction hint up to MAX_LEAK_RETRIES times; if it keeps
  * leaking, throw LeakedToolCallError rather than returning the unexecuted call.
+ * Empty completions and connection-class model errors share that same budget —
+ * see triageChildResult, which decides every one of those cases.
  */
 export async function runPhaseChild(deps, name, tools, prompt) {
     let hint = null;
     for (let attempt = 0; attempt <= MAX_LEAK_RETRIES; attempt++) {
         const r = await runChild(deps.cwd, tools, prependHint(hint, prompt), deps.signal, deps.onChildOutput, deps.onContextUsage, undefined, deps.spawn);
-        if (r.exitCode !== 0) {
-            throw new Error(`${name} child failed: ${r.stderr || '(no stderr)'}`);
-        }
-        if (r.modelError) {
-            // The model/provider failed (pi exited 0 with a stopReason "error"
-            // turn). A connection-class cause is transient — retry within the
-            // leak budget after a backoff; anything else fails fast (pi already
-            // retried, and re-spawning won't fix a real fault).
-            if (isConnectionError(r.modelError) && attempt < MAX_LEAK_RETRIES) {
-                deps.logDebug?.(`${name}: connection error "${r.modelError}" — retry `
-                    + `${attempt + 1}/${MAX_LEAK_RETRIES}`);
-                await (deps.sleepFor ?? defaultSleep)(connectionRetryBackoffMs(attempt));
-                continue;
-            }
-            throw new ModelError(name, r.modelError);
-        }
-        if (r.text.trim().length === 0) {
-            // An empty completion (exit 0, no assistant text, no stderr) is almost
-            // always transient — a model/API error swallowed inside --mode json,
-            // not a repeatable mistake — so re-spawn rather than fail the phase.
-            // There's nothing to correct, so we carry no hint. Reuses the leak
-            // retry budget: MAX_LEAK_RETRIES+1 attempts, then surface the error.
-            if (attempt === MAX_LEAK_RETRIES) {
-                throw new Error(`${name} child produced no output${r.stderr ? ' — stderr: ' + r.stderr : ''}`);
-            }
-            continue;
-        }
-        if (r.leakedToolCall) {
-            if (attempt === MAX_LEAK_RETRIES) {
-                throw new LeakedToolCallError(name, r.leakedToolCall);
-            }
-            hint = leakedToolCallHint(r.leakedToolCall);
-            continue;
-        }
-        return r.text;
+        const step = await triageChildResult(deps, name, r, attempt, MAX_LEAK_RETRIES, 'retry');
+        if (step.done)
+            return step.text;
+        if (step.hint !== undefined)
+            hint = step.hint;
     }
     // Unreachable: the loop returns clean text or throws on the final leak.
     throw new LeakedToolCallError(name, '(unknown)');
@@ -235,41 +263,17 @@ export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt, opts
             nextHint = formatLoopHint(r.loopHit);
             continue;
         }
-        if (r.exitCode !== 0) {
-            throw new Error(`${name} child failed: ${r.stderr || '(no stderr)'}`);
-        }
-        if (r.modelError) {
-            // The model/provider failed (pi exited 0 with a stopReason "error"
-            // turn). A connection-class cause is transient — restart within the
-            // strike budget after a backoff; anything else fails fast (pi already
-            // retried, and re-spawning won't fix a real fault).
-            if (isConnectionError(r.modelError) && strike < MAX_LOOP_RESTARTS) {
-                deps.logDebug?.(`${name}: connection error "${r.modelError}" — restart `
-                    + `${strike + 1}/${MAX_LOOP_RESTARTS}`);
-                await (deps.sleepFor ?? defaultSleep)(connectionRetryBackoffMs(strike));
-                continue;
-            }
-            throw new ModelError(name, r.modelError);
-        }
-        if (r.text.trim().length === 0) {
-            // An empty completion (exit 0, no assistant text, no stderr) is almost
-            // always transient — a model/API error swallowed inside --mode json,
-            // not a repeatable mistake — so re-spawn rather than fail the phase.
-            // Nothing to correct, so leave nextHint as-is. Reuses the strike
-            // budget shared with loop/leak restarts: MAX_LOOP_RESTARTS+1 attempts.
-            if (strike === MAX_LOOP_RESTARTS) {
-                throw new Error(`${name} child produced no output${r.stderr ? ' — stderr: ' + r.stderr : ''}`);
-            }
-            continue;
-        }
-        if (r.leakedToolCall) {
-            if (strike === MAX_LOOP_RESTARTS) {
-                throw new LeakedToolCallError(name, r.leakedToolCall);
-            }
-            nextHint = leakedToolCallHint(r.leakedToolCall);
-            continue;
-        }
-        return r.text;
+        // Everything past the loop kill is the shared ladder: exit code, model
+        // error (connection-class restarts within the strike budget), empty
+        // completion, leaked tool call. The strike budget is shared with the
+        // loop restarts above — MAX_LOOP_RESTARTS+1 attempts across all causes.
+        const step = await triageChildResult(deps, name, r, strike, MAX_LOOP_RESTARTS, 'restart');
+        if (step.done)
+            return step.text;
+        // Only a leak produces a new correction hint; the other rungs have
+        // nothing to correct and leave any loop hint already in flight alone.
+        if (step.hint !== undefined)
+            nextHint = step.hint;
     }
     throw new LoopExhaustedError(name, loopHistory);
 }

package/dist/task/enforce-guidelines.d.ts

@@ -1,4 +1,4 @@
-import { type SpawnFn } from '../shared/child-process.js';
+import type { SpawnFn } from '../shared/child-process.js';
 /** Filenames discovered in the working directory (cwd only — no tree walk). */
 export declare const GUIDELINE_FILENAMES: readonly ["AGENTS.md", "CLAUDE.md"];
 /**

package/dist/task/enforce-guidelines.js

@@ -23,7 +23,7 @@
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
-import { runChildDefault } from '../shared/child-process.js';
+import { makeGit } from '../shared/git-runner.js';
 import { USER_CANCELLED } from './child-runner.js';
 import { TASKS_DIR_NAME } from './task-types.js';
 import { findProbeGamingInDiff } from './probe-gaming.js';
@@ -279,7 +279,7 @@ export async function captureCommitDiff(cwd, signal, spawnFn) {
     // `:(exclude)<dir>` is a git pathspec that drops everything under the tasks
     // directory from the result, leaving only real source changes to verify.
     const excludeTasks = `:(exclude)${TASKS_DIR_NAME}`;
-    const run = (args) => runChildDefault({ command: 'git', args }, cwd, signal, { mode: 'text' }, spawnFn);
+    const run = makeGit(cwd, signal, spawnFn);
     // Diff the last commit against its parent. On a root commit there is no
     // HEAD~1 (rev-parse exits non-zero), so fall back to the empty tree.
     const parent = await run(['rev-parse', '--verify', '--quiet', 'HEAD~1']);

package/dist/task/external-context.d.ts

@@ -1,18 +1,94 @@
 /**
- * External-context enrichment — extract packages / URLs / services from the
- * refined spec, fan out to docs / fetch / search workers, and assemble the
- * `EXTERNAL CONTEXT` block the research phase prepends to every worker prompt.
+ * External-context enrichment — extract packages / URLs / services from a piece
+ * of text, fan out to docs / fetch / search workers, and assemble the
+ * `EXTERNAL CONTEXT` block that gets prepended to a worker prompt.
  *
  * Split out of phases.ts so the research phase reads as "gather context → run
  * probes → assemble", and so this fan-out has its own test surface separate
  * from the four research workers. `enrichment.ts` stays a pure parser; the I/O
  * lives here.
+ *
+ * There were TWO copies of this assembly: {@link gatherExternalContext} (the
+ * research phase, raw workers) and an 87-line inline block in `phaseAutoAnswer`
+ * (the grill auto-answer, focused workers). They agreed on everything that
+ * shows up in the output — the 8-step shape, the "npm blocks lead" ordering,
+ * the `### docs:` / `### url:` headings, the service loop's `no_key` / `error`
+ * handling, the block terminator — and disagreed only on POLICY. So the shape
+ * is {@link buildExternalContext} once, the disagreements are
+ * {@link ExternalContextPolicy}, and the worker variant is
+ * {@link ExternalContextLookups} — an adapter, expressible only since the
+ * focused-extractor seam landed.
  */
 import { docsRaw } from '../workers/docs-core.js';
 import { fetchRaw } from '../workers/fetch-core.js';
-import { npmVersionLookup } from '../workers/npm-version.js';
+import { npmVersionLookup, type NpmVersionInfo } from '../workers/npm-version.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
 import type { PhaseDeps } from './child-runner.js';
+type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep'>;
+/** What a target lookup contributes to the block. */
+export interface ExternalTargetResult {
+    /** Emitted as an `### npm:` block ahead of every body. Absent for url targets. */
+    npmVersion?: NpmVersionInfo | null;
+    /**
+     * The `### docs:`/`### url:` body. `undefined` means "this target contributes no
+     * body block" — and the two call paths draw that line differently ON PURPOSE:
+     * the raw lookups emit a (possibly empty) body whenever the docs call returned
+     * chunks, the focused ones emit one only when the child produced a non-empty
+     * answer. Both keep any `npmVersion` regardless.
+     */
+    body?: string;
+}
+/**
+ * The worker variant. This is the adapter the focused-extractor seam made
+ * expressible: `gatherExternalContext` binds the RAW workers (whole doc chunks /
+ * whole page markdown, truncated), `phaseAutoAnswer` binds the FOCUSED ones (a
+ * child's one-question answer). Everything else about the block is identical.
+ *
+ * A rejected lookup is caught by the builder and yields no blocks for that
+ * target, so adapters may throw freely.
+ */
+export interface ExternalContextLookups {
+    docs(pkg: string): Promise<ExternalTargetResult | null>;
+    url(url: string): Promise<ExternalTargetResult | null>;
+    /** Defaults to the real search worker. */
+    search?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
+}
+/**
+ * The six places the two call paths genuinely disagreed. Each is a knob rather
+ * than a default, because every one of them is a deliberate, measured choice on
+ * at least one path — the auto-answer block is capped and records nothing
+ * because it runs per grill question, in front of a waiting user.
+ */
+export interface ExternalContextPolicy {
+    /**
+     * Max combined docs+url targets fanned out, packages first. Omit for uncapped
+     * (research); the auto-answer path caps at 2.
+     */
+    targetCap?: number;
+    /** Max services fanned out. Omit for uncapped; the auto-answer path caps at 2. */
+    serviceCap?: number;
+    /**
+     * A cheap live version lookup for every named dep that did NOT get a docs
+     * target, so a version block exists for ALL of them. Omit to disable, as the
+     * auto-answer path does. Without this on the research path, deps past the
+     * docs cap had no live version and a "which version?" question fell back to
+     * the model's stale training data — how tailwindcss got pinned to an old major.
+     */
+    versionLookup?: (pkg: string) => Promise<NpmVersionInfo | null>;
+    /** Sub-step label recorded via `deps.recordSubStep`. Omit to record nothing. */
+    subStepLabel?: string;
+    /**
+     * Return `''` before any fan-out when there is nothing to look up. Only the
+     * research path does this today; on the auto-answer path the empty fan-out is
+     * a no-op that produces the same `''`.
+     */
+    earlyReturnOnNoTargets?: boolean;
+}
+/**
+ * Assemble the `EXTERNAL CONTEXT\n…\n\n` block for `source`, or `''` when there
+ * is nothing to enrich (no targets, or every lookup failed).
+ */
+export declare function buildExternalContext(source: string, deps: GatherDeps, lookups: ExternalContextLookups, policy?: ExternalContextPolicy): Promise<string>;
 /** Injectable workers so enrichment is testable without spawning real lookups. */
 export interface ExternalContextDeps {
     docsRaw?: typeof docsRaw;
@@ -20,10 +96,12 @@ export interface ExternalContextDeps {
     searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
     npmVersionLookup?: typeof npmVersionLookup;
 }
-type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep'>;
 /**
- * Returns the `EXTERNAL CONTEXT\n…\n\n` block for the refined spec, or `''` when
- * there is nothing to enrich (no targets, or every lookup failed).
+ * The RESEARCH-phase binding: raw workers, no caps, live versions for every
+ * named dep, truncated bodies, timed, and short-circuited when there is nothing
+ * to look up.
+ *
+ * Returns the `EXTERNAL CONTEXT\n…\n\n` block for the refined spec, or `''`.
  */
 export declare function gatherExternalContext(refined: string, deps: GatherDeps, researchDeps?: ExternalContextDeps): Promise<string>;
 export {};

package/dist/task/external-context.js

@@ -1,12 +1,23 @@
 /**
- * External-context enrichment — extract packages / URLs / services from the
- * refined spec, fan out to docs / fetch / search workers, and assemble the
- * `EXTERNAL CONTEXT` block the research phase prepends to every worker prompt.
+ * External-context enrichment — extract packages / URLs / services from a piece
+ * of text, fan out to docs / fetch / search workers, and assemble the
+ * `EXTERNAL CONTEXT` block that gets prepended to a worker prompt.
  *
  * Split out of phases.ts so the research phase reads as "gather context → run
  * probes → assemble", and so this fan-out has its own test surface separate
  * from the four research workers. `enrichment.ts` stays a pure parser; the I/O
  * lives here.
+ *
+ * There were TWO copies of this assembly: {@link gatherExternalContext} (the
+ * research phase, raw workers) and an 87-line inline block in `phaseAutoAnswer`
+ * (the grill auto-answer, focused workers). They agreed on everything that
+ * shows up in the output — the 8-step shape, the "npm blocks lead" ordering,
+ * the `### docs:` / `### url:` headings, the service loop's `no_key` / `error`
+ * handling, the block terminator — and disagreed only on POLICY. So the shape
+ * is {@link buildExternalContext} once, the disagreements are
+ * {@link ExternalContextPolicy}, and the worker variant is
+ * {@link ExternalContextLookups} — an adapter, expressible only since the
+ * focused-extractor seam landed.
  */
 import { docsRaw } from '../workers/docs-core.js';
 import { fetchRaw } from '../workers/fetch-core.js';
@@ -14,77 +25,61 @@ import { formatNpmVersionSection, npmVersionLookup } from '../workers/npm-versio
 import { search as defaultSearch } from '../workers/search-core.js';
 import { extractEnrichTargets } from './enrichment.js';
 import { formatServiceBlock, formatFreshnessSkippedBlock } from './service-blocks.js';
+/** How much of a docs/url body survives into the block, for the raw-worker lookups. */
+const RAW_BODY_LIMIT = 4000;
 /**
- * Returns the `EXTERNAL CONTEXT\n…\n\n` block for the refined spec, or `''` when
- * there is nothing to enrich (no targets, or every lookup failed).
+ * Assemble the `EXTERNAL CONTEXT\n…\n\n` block for `source`, or `''` when there
+ * is nothing to enrich (no targets, or every lookup failed).
  */
-export async function gatherExternalContext(refined, deps, researchDeps = {}) {
-    const docsRawFn = researchDeps.docsRaw ?? docsRaw;
-    const fetchRawFn = researchDeps.fetchRaw ?? fetchRaw;
-    const searchFn = researchDeps.searchFn ?? defaultSearch;
-    const npmVersionFn = researchDeps.npmVersionLookup ?? npmVersionLookup;
-    const enrichTargets = extractEnrichTargets(refined);
-    // Every named dep past the heavy-docs cap still gets a cheap live version
-    // lookup, so a version block exists for ALL of them (the docs-fetched ones
-    // emit their version below from the bundled lookup). Without this, deps 4..N
-    // had no live version and a "which version?" question fell back to the model's
-    // stale training data — how tailwindcss got pinned to an old major.
-    const docsPkgs = new Set(enrichTargets.packages);
-    const extraVersionPkgs = enrichTargets.versionPackages.filter(p => !docsPkgs.has(p));
-    if (enrichTargets.packages.length === 0
-        && enrichTargets.urls.length === 0
-        && enrichTargets.services.length === 0) {
+export async function buildExternalContext(source, deps, lookups, policy = {}) {
+    const searchFn = lookups.search ?? defaultSearch;
+    const enrichTargets = extractEnrichTargets(source);
+    // Packages lead urls, then the combined cap applies — so a capped run spends
+    // its budget on named deps first. Uncapped, this is just "packages, then urls".
+    const targets = [
+        ...enrichTargets.packages.map(name => ({ kind: 'pkg', name })),
+        ...enrichTargets.urls.map(name => ({ kind: 'url', name }))
+    ].slice(0, policy.targetCap ?? Number.POSITIVE_INFINITY);
+    const services = enrichTargets.services.slice(0, policy.serviceCap ?? Number.POSITIVE_INFINITY);
+    const versionLookup = policy.versionLookup;
+    const docsTargets = new Set(targets.filter(t => t.kind === 'pkg').map(t => t.name));
+    const extraVersionPkgs = versionLookup ? enrichTargets.versionPackages.filter(p => !docsTargets.has(p)) : [];
+    if (policy.earlyReturnOnNoTargets && targets.length === 0 && services.length === 0)
         return '';
-    }
-    const enrichSections = [];
-    const tEnrichStart = Date.now();
-    const [docsResults, fetchResults, serviceResults, extraVersionResults] = await Promise.all([
-        Promise.all(enrichTargets.packages.map(pkg => docsRawFn({
-            pkg,
-            query: refined.split('\n').find(l => l.trim()) ?? refined,
-            cwd: deps.cwd,
-            signal: deps.signal
-        }).catch(() => null))),
-        Promise.all(enrichTargets.urls.map(url => fetchRawFn({ url, signal: deps.signal }).catch(() => null))),
-        Promise.all(enrichTargets.services.map(s => searchFn({
+    const startedAt = Date.now();
+    const [targetResults, serviceResults, extraVersionResults] = await Promise.all([
+        Promise.all(targets.map(t => (t.kind === 'pkg' ? lookups.docs(t.name) : lookups.url(t.name)).catch(() => null))),
+        Promise.all(services.map(s => searchFn({
             query: `${s.name} ${s.query}`,
             count: 3,
             signal: deps.signal
         }).catch(() => null))),
-        Promise.all(extraVersionPkgs.map(pkg => npmVersionFn(pkg, { signal: deps.signal }).catch(() => null)))
+        Promise.all(versionLookup ? extraVersionPkgs.map(pkg => versionLookup(pkg).catch(() => null)) : [])
     ]);
+    const sections = [];
     // npm version blocks lead the section so the model anchors on live version
     // data before reading any docs body. The docs-fetched packages carry their
-    // version in docsRaw's bundled lookup; the remaining named deps get theirs
-    // from the cheap standalone lookup above. Together they cover EVERY named dep.
-    for (let i = 0; i < enrichTargets.packages.length; i++) {
-        const v = docsResults[i]?.npmVersion;
-        if (v)
-            enrichSections.push(formatNpmVersionSection(v));
+    // version in the lookup's own bundled result; the remaining named deps get
+    // theirs from the cheap standalone lookup above. Together they cover EVERY
+    // named dep.
+    for (const r of targetResults) {
+        if (r?.npmVersion)
+            sections.push(formatNpmVersionSection(r.npmVersion));
     }
     for (const v of extraVersionResults) {
         if (v)
-            enrichSections.push(formatNpmVersionSection(v));
-    }
-    for (let i = 0; i < enrichTargets.packages.length; i++) {
-        const r = docsResults[i];
-        if (r?.kind === 'ok' && r.chunks.length > 0) {
-            const body = r.chunks
-                .map(c => c.content)
-                .join('\n\n')
-                .slice(0, 4000);
-            enrichSections.push(`### docs: ${enrichTargets.packages[i]}\n${body}`);
-        }
+            sections.push(formatNpmVersionSection(v));
     }
-    for (let i = 0; i < enrichTargets.urls.length; i++) {
-        const r = fetchResults[i];
-        if (r) {
-            enrichSections.push(`### url: ${enrichTargets.urls[i]}\n${r.markdown.slice(0, 4000)}`);
-        }
+    for (let i = 0; i < targets.length; i++) {
+        const body = targetResults[i]?.body;
+        if (body === undefined)
+            continue;
+        const heading = targets[i].kind === 'pkg' ? 'docs' : 'url';
+        sections.push(`### ${heading}: ${targets[i].name}\n${body}`);
     }
     const skipped = [];
-    for (let i = 0; i < enrichTargets.services.length; i++) {
-        const s = enrichTargets.services[i];
+    for (let i = 0; i < services.length; i++) {
+        const s = services[i];
         const r = serviceResults[i];
         if (r === null)
             continue;
@@ -95,13 +90,55 @@ export async function gatherExternalContext(refined, deps, researchDeps = {}) {
         if (r.kind === 'error')
             continue;
         // kind === 'ok'
-        enrichSections.push(formatServiceBlock(s.name, `${s.name} ${s.query}`, r.results));
+        sections.push(formatServiceBlock(s.name, `${s.name} ${s.query}`, r.results));
     }
     if (skipped.length > 0) {
-        enrichSections.push(formatFreshnessSkippedBlock(skipped));
+        sections.push(formatFreshnessSkippedBlock(skipped));
     }
-    deps.recordSubStep?.('enrichment', Date.now() - tEnrichStart);
-    if (enrichSections.length === 0)
+    if (policy.subStepLabel)
+        deps.recordSubStep?.(policy.subStepLabel, Date.now() - startedAt);
+    if (sections.length === 0)
         return '';
-    return `EXTERNAL CONTEXT\n${enrichSections.join('\n\n')}\n\n`;
+    return `EXTERNAL CONTEXT\n${sections.join('\n\n')}\n\n`;
+}
+/**
+ * The RESEARCH-phase binding: raw workers, no caps, live versions for every
+ * named dep, truncated bodies, timed, and short-circuited when there is nothing
+ * to look up.
+ *
+ * Returns the `EXTERNAL CONTEXT\n…\n\n` block for the refined spec, or `''`.
+ */
+export async function gatherExternalContext(refined, deps, researchDeps = {}) {
+    const docsRawFn = researchDeps.docsRaw ?? docsRaw;
+    const fetchRawFn = researchDeps.fetchRaw ?? fetchRaw;
+    const npmVersionFn = researchDeps.npmVersionLookup ?? npmVersionLookup;
+    const docsQuery = refined.split('\n').find(l => l.trim()) ?? refined;
+    return buildExternalContext(refined, deps, {
+        docs: async (pkg) => {
+            const r = await docsRawFn({
+                pkg,
+                query: docsQuery,
+                cwd: deps.cwd,
+                signal: deps.signal
+            });
+            return {
+                npmVersion: r.npmVersion,
+                body: r.kind === 'ok' && r.chunks.length > 0 ?
+                    r.chunks
+                        .map(c => c.content)
+                        .join('\n\n')
+                        .slice(0, RAW_BODY_LIMIT)
+                    : undefined
+            };
+        },
+        url: async (url) => {
+            const r = await fetchRawFn({ url, signal: deps.signal });
+            return { body: r.markdown.slice(0, RAW_BODY_LIMIT) };
+        },
+        search: researchDeps.searchFn
+    }, {
+        versionLookup: pkg => npmVersionFn(pkg, { signal: deps.signal }),
+        subStepLabel: 'enrichment',
+        earlyReturnOnNoTargets: true
+    });
 }

package/dist/task/file-inventory.js

@@ -4,7 +4,7 @@
  * read/grep on known paths. Returns '' on failure (non-git repo, git missing,
  * timeout) so callers can fall back to the pre-inventory behavior.
  */
-import { spawn } from 'node:child_process';
+import { makeGit } from '../shared/git-runner.js';
 import { TASKS_DIR_NAME } from './task-types.js';
 const DEFAULT_MAX_LINES = 2000;
 /**
@@ -23,46 +23,27 @@ export function stripTasksDir(raw) {
         .filter(l => !l.startsWith(prefix))
         .join('\n');
 }
-function runGitLsFiles(cwd, signal) {
-    return new Promise(resolve => {
-        let stdout = '';
-        let proc;
-        try {
-            proc = spawn('git', ['ls-files'], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
-        }
-        catch {
-            resolve('');
-            return;
-        }
-        proc.stdout?.on('data', (d) => {
-            stdout += d.toString();
-        });
-        // Same detach discipline as runChild (GitHub issue #9): `signal` is the
-        // run-long orchestrator signal, so a listener left behind by a normally
-        // finished `git ls-files` would retain that child for the whole run.
-        const onAbort = () => {
-            if (!proc.killed)
-                proc.kill('SIGTERM');
-        };
-        let settled = false;
-        const settle = (value) => {
-            signal?.removeEventListener('abort', onAbort);
-            if (settled)
-                return;
-            settled = true;
-            resolve(value);
-        };
-        proc.once('error', () => settle(''));
-        proc.once('close', code => settle(code === 0 ? stdout : ''));
-        if (signal) {
-            // An already-aborted signal never emits 'abort', so without this check
-            // a run cancelled before this point would let the child run to term.
-            if (signal.aborted)
-                onAbort();
-            else
-                signal.addEventListener('abort', onAbort, { once: true });
-        }
-    });
+/**
+ * `git ls-files`, or '' on ANY failure — non-git tree, missing git, cancelled run.
+ * The empty string is the caller's fall-back-to-pre-inventory signal, so every
+ * unhappy path has to collapse to it.
+ *
+ * Runs on the shared GitRunner (`shared/git-runner.ts`), which brings the abort
+ * discipline this used to hand-roll: the listener is detached when the child
+ * settles normally, so a run-long orchestrator signal does not accumulate one
+ * retained child per invocation (GitHub issue #9).
+ *
+ * The `signal.aborted` check is what preserves this function's OWN contract on
+ * cancellation. A killed child closes with a null exit code, which the runner
+ * reports as 0 — so without it a cancelled run would hand back a truncated
+ * inventory as if it were complete, where the hand-rolled version returned ''.
+ */
+async function runGitLsFiles(cwd, signal) {
+    const git = makeGit(cwd, signal);
+    const r = await git(['ls-files']);
+    if (r.exitCode !== 0 || signal?.aborted)
+        return '';
+    return r.stdout;
 }
 /** Cap output to maxLines real (non-blank) paths; tag truncation when cut. */
 export function capInventory(raw, maxLines = DEFAULT_MAX_LINES) {