@mjasnikovs/pi-task 0.38.9 → 0.38.11

package/dist/task/launch-manifest.d.ts

@@ -35,3 +35,8 @@ export declare function readLaunchManifest(cwd: string): LaunchManifest;
  * silently did nothing must not read later as a check that passed.
  */
 export declare function inertLaunchContractNote(declared: string[], manifest: LaunchManifest): string;
+/** The `scripts` map of this tree's package.json, or `{}` when there isn't one.
+ *  Shared by the gate and the boot probe — both ask the same manifest question. */
+export declare function packageScripts(cwd: string): Record<string, string>;
+/** Does this tree's Makefile declare `target`? */
+export declare function makeHasTarget(cwd: string, target: string): boolean;

package/dist/task/launch-manifest.js

@@ -149,3 +149,24 @@ export function inertLaunchContractNote(declared, manifest) {
         + `but this project could not be diffed against a manifest — ${manifest.why ?? 'no manifest'}. `
         + 'The contract was NOT checked here.');
 }
+/** The `scripts` map of this tree's package.json, or `{}` when there isn't one.
+ *  Shared by the gate and the boot probe — both ask the same manifest question. */
+export function packageScripts(cwd) {
+    try {
+        const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+        return j.scripts ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Does this tree's Makefile declare `target`? */
+export function makeHasTarget(cwd, target) {
+    try {
+        const mk = readFileSync(path.join(cwd, 'Makefile'), 'utf8');
+        return new RegExp(`^${target}:`, 'm').test(mk);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/task/orchestrator.js

@@ -303,7 +303,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 +343,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(', ')}`);

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}`;

package/dist/task/task-gates.d.ts

@@ -63,6 +63,18 @@ export interface GateDeps {
      * tests or when `verify work` is off → the sequence treats it as a pass.
      */
     verify?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, taskId: string) => Promise<VerifyOutcome>;
+    /**
+     * The DIFFERENTIAL re-verify the enforce pass runs against the enforced tree,
+     * to decide whether its own commit survives. Absent → `verify`, which is what
+     * it has always been, so production wiring is untouched.
+     *
+     * Its own field because it answers a different question from the gate above.
+     * While the two shared one field the only way to answer them differently was to
+     * count invocations — a `verifyCalls` state machine whose FIRST return existed
+     * solely to unlock `mode === 'edit'`, re-invented in the suite and again in
+     * scripts/enforce-revert-attribution-replay-ab.ts.
+     */
+    reVerify?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, taskId: string) => Promise<VerifyOutcome>;
     /**
      * Hold the committed work to AGENTS.md / CLAUDE.md. `edit` (fix in place) only
      * with a clean verify signal to guard against; otherwise `flag` (report only).
@@ -293,4 +305,61 @@ export declare function askVerifyResolution(ctx: ExtensionCommandContext, title:
  * only a user cancel inside a gate child propagates (handled by the caller's
  * USER_CANCELLED path).
  */
+/** The durable per-task gate trail: every outcome is appended to the task file so
+ *  the sequence is auditable from artifacts alone. Best-effort — recording must
+ *  never break the gate sequence. */
+type Recorder = (line: string) => Promise<void>;
+/**
+ * The root-cause channel: was this FAIL caused by a pre-existing defect in a file
+ * some OTHER task created and this task never touched?
+ */
+type RootCauseRouter = (failReason: string, rationale: string, scope: 'worktree' | 'committed' | 'enforce-commit') => Promise<RepairCandidate | null>;
+/**
+ * What the VERIFY half settled. Either the sequence is over (`stop` carries the
+ * terminal GateResult — dismissed picker, cancelled session, interrupted or failed
+ * autofix) or the task proceeds to commit + enforce.
+ *
+ * `cleanPass` is the ONE fact that crosses to the enforce half: a GENUINE clean
+ * pass (a real signal ran and the work met it) is the only thing that gives
+ * enforce a signal to revert against, so only then may it edit in place. A no-op
+ * pass, a disabled gate or an accept-override leaves it false → flag-only.
+ */
+type VerifyGateStep = {
+    stop: GateResult;
+} | {
+    proceed: {
+        ctx: ExtensionCommandContext;
+        cleanPass: boolean;
+    };
+};
+/**
+ * The VERIFY resolution loop: run the task's verification against the finished
+ * work, and negotiate a FAIL through the graduated ladder (bounded lint fix →
+ * recommendation → unattended autofix → picker) until it verifies, is accepted,
+ * or terminates.
+ *
+ * Split out of `runGatesForTask` at the single boolean that crosses to the
+ * ENFORCE half. It carries 8 mutable locals over ~290 lines and has four terminal
+ * exits; enforce carries one local and always falls through. Joining them meant a
+ * test of the enforce differential had to traverse this whole loop first, which is
+ * why `deps.verify` was driven by an invocation counter whose first return existed
+ * only to unlock `mode === 'edit'`.
+ */
+export declare function resolveVerifyGate(ctxIn: ExtensionCommandContext, deps: GateDeps, p: GateParams, rec: Recorder, routeRootCause: RootCauseRouter): Promise<VerifyGateStep>;
+/**
+ * The ENFORCE differential: hold the committed work to AGENTS.md / CLAUDE.md,
+ * then decide whether the pass\'s own commit survives.
+ *
+ * `reVerify` is deliberately NOT `deps.verify`. They answer two different
+ * questions — the gate above, and this differential — and while they shared one
+ * field the only way to answer them differently was to count invocations.
+ *
+ * Reads `active` and never reassigns it: nothing here can replace the live
+ * session, unlike the autofix in the verify half.
+ */
+export declare function runEnforcePass(active: ExtensionCommandContext, deps: GateDeps, p: GateParams, rec: Recorder, routeRootCause: RootCauseRouter, args: {
+    cleanPass: boolean;
+    commit: CommitResult;
+}): Promise<void>;
 export declare function runGatesForTask(ctxIn: ExtensionCommandContext, deps: GateDeps, p: GateParams): Promise<GateResult>;
+export {};

package/dist/task/task-gates.js

@@ -67,60 +67,20 @@ export async function askVerifyResolution(ctx, title, failReason, rec) {
     return classifyResolutionAnswer(answer);
 }
 /**
- * Run the verify + enforce gates against a task's just-finished implementation.
+ * The VERIFY resolution loop: run the task's verification against the finished
+ * work, and negotiate a FAIL through the graduated ladder (bounded lint fix →
+ * recommendation → unattended autofix → picker) until it verifies, is accepted,
+ * or terminates.
  *
- * Lifted verbatim from /task-auto's per-task loop so the two commands gate
- * identically. Returns a GateResult; `done` means the caller should proceed (the
- * work is verified-or-accepted, checked off, committed, and enforced), every other
- * kind is a terminal stop the caller announces. Never throws for a gate outcome —
- * only a user cancel inside a gate child propagates (handled by the caller's
- * USER_CANCELLED path).
+ * Split out of `runGatesForTask` at the single boolean that crosses to the
+ * ENFORCE half. It carries 8 mutable locals over ~290 lines and has four terminal
+ * exits; enforce carries one local and always falls through. Joining them meant a
+ * test of the enforce differential had to traverse this whole loop first, which is
+ * why `deps.verify` was driven by an invocation counter whose first return existed
+ * only to unlock `mode === 'edit'`.
  */
-export async function runGatesForTask(ctxIn, deps, p) {
+export async function resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause) {
     let active = ctxIn;
-    // Durable per-task gate trail — every outcome below is also appended to the
-    // task file so the sequence is auditable from artifacts alone. Best-effort.
-    const rec = async (line) => {
-        try {
-            await deps.record?.(p.cwd, p.taskId, line);
-        }
-        catch {
-            // recording must never break the gate sequence
-        }
-    };
-    /**
-     * ROOT-CAUSE CHANNEL (mx5 run 14 item 5). Ask whether a FAIL was caused by a
-     * pre-existing defect in a file some OTHER task created and this task never
-     * touched. On a hit: record the durable debt (so the final gate surfaces it)
-     * and queue a scoped repair task (so something finally FIXES it — run 14
-     * recorded the same `test/teardown.ts` cause twice and scheduled nothing, and
-     * the bug survived ~24h). Returns the candidate so the caller can also decide
-     * NOT to punish the current task for it. Never throws: any fault degrades to
-     * null, i.e. exactly the pre-existing behavior.
-     */
-    const routeRootCause = async (failReason, rationale, scope) => {
-        if (!deps.touchedFiles || !deps.introducedBy)
-            return null;
-        try {
-            const candidate = await findRepairCandidate({
-                failReason,
-                rationale,
-                currentTaskId: p.taskId,
-                touched: await deps.touchedFiles(p.cwd, scope),
-                introducedBy: rel => deps.introducedBy(p.cwd, rel)
-            });
-            if (!candidate)
-                return null;
-            await deps.recordDebt?.(p.cwd, p.taskId, `${failReason} — ROOT CAUSE: \`${candidate.file}\` (introduced by ${candidate.owner}, not touched by this task)`, 'root-cause');
-            await deps.recordRepairCandidate?.(p.cwd, candidate);
-            await rec(`root-cause: FAIL attributed to \`${candidate.file}\` — a pre-existing defect in ${candidate.owner}'s file that this task never touched; `
-                + 'recorded as durable debt and a scoped repair task queued');
-            return candidate;
-        }
-        catch {
-            return null;
-        }
-    };
     const verdictLine = (v) => v.ok ?
         v.reason ?
             `verify: PASS (${v.reason})`
@@ -289,7 +249,7 @@ export async function runGatesForTask(ctxIn, deps, p) {
             }
             if (choice.action === 'cancel') {
                 await rec('resolution: user dismissed the verify-FAIL picker — paused');
-                return { kind: 'paused', ctx: active, reason: failReason };
+                return { stop: { kind: 'paused', ctx: active, reason: failReason } };
             }
             if (choice.action === 'accept') {
                 const byYolo = yoloChoice !== null;
@@ -360,11 +320,11 @@ export async function runGatesForTask(ctxIn, deps, p) {
             });
             active = fixRes.ctx ?? active;
             if (fixRes.sessionCancelled)
-                return { kind: 'session-cancelled', ctx: active };
+                return { stop: { kind: 'session-cancelled', ctx: active } };
             if (fixRes.interrupted)
-                return { kind: 'interrupted', ctx: active };
+                return { stop: { kind: 'interrupted', ctx: active } };
             if (!fixRes.ok)
-                return { kind: 'failed', ctx: active, reason: fixRes.reason };
+                return { stop: { kind: 'failed', ctx: active, reason: fixRes.reason } };
             // Resume reuses the same inner task id, so p.taskId is stable.
             verified = await deps.verify(active, p.cwd, p.title, p.taskId);
             await rec(verdictLine(verified));
@@ -374,39 +334,21 @@ export async function runGatesForTask(ctxIn, deps, p) {
         // accept-override (verified.ok still false at break) is NOT a guardable signal.
         verifyCleanPass = verified.ok && !verified.reason;
     }
-    // Mark the work verified (parent task-list check-off for /task-auto; no-op for
-    // /task) BEFORE committing, so the commit captures the check-off too.
-    await p.onVerified?.();
-    // Commit the task's work as one snapshot FIRST — before guideline enforcement —
-    // so a passing task is durably recorded no matter what enforcement later finds.
-    const commit = await deps.commit(p.cwd, `task: ${p.title} (${p.taskId})`);
-    if (commit.committed) {
-        await rec(`commit: task snapshot committed${commit.note ? ` (${commit.note})` : ''}`);
-        // SAY WHAT WAS LEFT OUT. The stage skips untracked regenerable test-runner
-        // output (mx5 run 20: TASK_0027's `git add -A` swept in three Playwright
-        // failure screenshots and two later fix attempts were rejected for deleting
-        // them). A SILENT exclusion is the same failure class as the silent
-        // ignored-path write nexttask 4 closed, so it gets its own trail line.
-        if (commit.excluded && commit.excluded.length > 0) {
-            await rec(`commit: left ${commit.excluded.length} untracked test-runner artifact(s) out of the `
-                + `snapshot — regenerable output, not deliverables: `
-                + `${commit.excluded.slice(0, 8).join(', ')}`
-                + `${commit.excluded.length > 8 ? `, +${commit.excluded.length - 8} more` : ''}`);
-        }
-        active.ui.notify(`${p.tag}: committed "${p.title}".`, 'info');
-    }
-    else {
-        await rec(`commit: skipped (${commit.reason ?? 'unknown'})`);
-        // A benign skip ("nothing to commit", auto-commit off) is a warning. A real
-        // git failure is louder: it silently disables enforce AND every commit-based
-        // guard — mx5 run 4 lost all 10 commits (no container git identity) with only
-        // per-task warnings to show for it. "blocked" is the unmerged-index refusal
-        // (gitCommitAll) — the same severity: nothing can commit until it's resolved.
-        const gitFailure = /^git (commit|add) (failed|blocked)/.test(commit.reason ?? '');
-        active.ui.notify(gitFailure ?
-            `${p.tag}: COMMIT FAILED (${commit.reason}) — enforce and revert guards are disabled for this task.`
-            : `${p.tag}: not committed (${commit.reason ?? 'unknown'}) — continuing.`, gitFailure ? 'error' : 'warning');
-    }
+    return { proceed: { ctx: active, cleanPass: verifyCleanPass } };
+}
+/**
+ * The ENFORCE differential: hold the committed work to AGENTS.md / CLAUDE.md,
+ * then decide whether the pass\'s own commit survives.
+ *
+ * `reVerify` is deliberately NOT `deps.verify`. They answer two different
+ * questions — the gate above, and this differential — and while they shared one
+ * field the only way to answer them differently was to count invocations.
+ *
+ * Reads `active` and never reassigns it: nothing here can replace the live
+ * session, unlike the autofix in the verify half.
+ */
+export async function runEnforcePass(active, deps, p, rec, routeRootCause, args) {
+    const { cleanPass: verifyCleanPass, commit } = args;
     // With the task committed, hold its work to AGENTS.md / CLAUDE.md — but as a step
     // INSIDE the validation gate, gated by the verify signal (see GateDeps.enforce).
     // Skipped when nothing was committed this round, when enforce is off, or in tests
@@ -516,8 +458,9 @@ export async function runGatesForTask(ctxIn, deps, p) {
             if (enforceCommit.committed) {
                 // Differential guard: re-run the verify signal against the enforced
                 // tree. A regression ⇒ drop the enforce commit, keep the verified work.
-                const after = deps.verify ?
-                    await deps.verify(active, p.cwd, p.title, p.taskId)
+                const differential = deps.reVerify ?? deps.verify;
+                const after = differential ?
+                    await differential(active, p.cwd, p.title, p.taskId)
                     : { ok: true };
                 const afterReason = after.reason ?? 'enforce re-verify failed';
                 // PRE-EXISTING-CAUSE KEEP PATH (mx5 run 14 item 5b). Both of run
@@ -632,5 +575,86 @@ export async function runGatesForTask(ctxIn, deps, p) {
         // so a missing enforce run is explainable from the trail (mx5 audit gap).
         await rec('enforce: skipped (nothing committed this round)');
     }
+}
+export async function runGatesForTask(ctxIn, deps, p) {
+    const rec = async (line) => {
+        try {
+            await deps.record?.(p.cwd, p.taskId, line);
+        }
+        catch {
+            // recording must never break the gate sequence
+        }
+    };
+    /**
+     * ROOT-CAUSE CHANNEL (mx5 run 14 item 5). Ask whether a FAIL was caused by a
+     * pre-existing defect in a file some OTHER task created and this task never
+     * touched. On a hit: record the durable debt (so the final gate surfaces it)
+     * and queue a scoped repair task (so something finally FIXES it — run 14
+     * recorded the same `test/teardown.ts` cause twice and scheduled nothing, and
+     * the bug survived ~24h). Returns the candidate so the caller can also decide
+     * NOT to punish the current task for it. Never throws: any fault degrades to
+     * null, i.e. exactly the pre-existing behavior.
+     */
+    const routeRootCause = async (failReason, rationale, scope) => {
+        if (!deps.touchedFiles || !deps.introducedBy)
+            return null;
+        try {
+            const candidate = await findRepairCandidate({
+                failReason,
+                rationale,
+                currentTaskId: p.taskId,
+                touched: await deps.touchedFiles(p.cwd, scope),
+                introducedBy: rel => deps.introducedBy(p.cwd, rel)
+            });
+            if (!candidate)
+                return null;
+            await deps.recordDebt?.(p.cwd, p.taskId, `${failReason} — ROOT CAUSE: \`${candidate.file}\` (introduced by ${candidate.owner}, not touched by this task)`, 'root-cause');
+            await deps.recordRepairCandidate?.(p.cwd, candidate);
+            await rec(`root-cause: FAIL attributed to \`${candidate.file}\` — a pre-existing defect in ${candidate.owner}'s file that this task never touched; `
+                + 'recorded as durable debt and a scoped repair task queued');
+            return candidate;
+        }
+        catch {
+            return null;
+        }
+    };
+    const step = await resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause);
+    if ('stop' in step)
+        return step.stop;
+    const { ctx: active, cleanPass } = step.proceed;
+    // Mark the work verified (parent task-list check-off for /task-auto; no-op for
+    // /task) BEFORE committing, so the commit captures the check-off too.
+    await p.onVerified?.();
+    // Commit the task's work as one snapshot FIRST — before guideline enforcement —
+    // so a passing task is durably recorded no matter what enforcement later finds.
+    const commit = await deps.commit(p.cwd, `task: ${p.title} (${p.taskId})`);
+    if (commit.committed) {
+        await rec(`commit: task snapshot committed${commit.note ? ` (${commit.note})` : ''}`);
+        // SAY WHAT WAS LEFT OUT. The stage skips untracked regenerable test-runner
+        // output (mx5 run 20: TASK_0027's `git add -A` swept in three Playwright
+        // failure screenshots and two later fix attempts were rejected for deleting
+        // them). A SILENT exclusion is the same failure class as the silent
+        // ignored-path write nexttask 4 closed, so it gets its own trail line.
+        if (commit.excluded && commit.excluded.length > 0) {
+            await rec(`commit: left ${commit.excluded.length} untracked test-runner artifact(s) out of the `
+                + `snapshot — regenerable output, not deliverables: `
+                + `${commit.excluded.slice(0, 8).join(', ')}`
+                + `${commit.excluded.length > 8 ? `, +${commit.excluded.length - 8} more` : ''}`);
+        }
+        active.ui.notify(`${p.tag}: committed "${p.title}".`, 'info');
+    }
+    else {
+        await rec(`commit: skipped (${commit.reason ?? 'unknown'})`);
+        // A benign skip ("nothing to commit", auto-commit off) is a warning. A real
+        // git failure is louder: it silently disables enforce AND every commit-based
+        // guard — mx5 run 4 lost all 10 commits (no container git identity) with only
+        // per-task warnings to show for it. "blocked" is the unmerged-index refusal
+        // (gitCommitAll) — the same severity: nothing can commit until it's resolved.
+        const gitFailure = /^git (commit|add) (failed|blocked)/.test(commit.reason ?? '');
+        active.ui.notify(gitFailure ?
+            `${p.tag}: COMMIT FAILED (${commit.reason}) — enforce and revert guards are disabled for this task.`
+            : `${p.tag}: not committed (${commit.reason ?? 'unknown'}) — continuing.`, gitFailure ? 'error' : 'warning');
+    }
+    await runEnforcePass(active, deps, p, rec, routeRootCause, { cleanPass, commit });
     return { kind: 'done', ctx: active };
 }

package/dist/workers/docs-core.d.ts

@@ -183,9 +183,5 @@ export declare function buildPrompt(pkg: ResolvedPackage, query: string, content
  * (`{name, version: 'local', root, entryDts: null, readme: null}`) purely to make
  * this call compile, with three of the five fields existing only for that.
  */
-export declare function formatResultText(header: string, parsed: {
-    answer: string;
-    excerpt?: string;
-}, verified: boolean | undefined): string;
 /** The header for an npm package answer. */
 export declare function packageHeader(pkg: ResolvedPackage): string;

package/dist/workers/docs-core.js

@@ -4,15 +4,14 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
-import { resolvePackage as defaultResolvePackage, ResolveError, detectTypesRedirect, typesPackageName, hasTypeFiles, isDtsFile, splitRuntimeNamespace } from './docs-resolve.js';
-import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
+import { resolvePackage as defaultResolvePackage, ResolveError, isDtsFile, resolveTypeSource, typesPackageName, splitRuntimeNamespace } from './docs-resolve.js';
+import { retrieveChunks as defaultRetrieveChunks, PACKAGE_RETRIEVE_LIMIT, RETRIEVE_CONTENT_BUDGET } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import { runChild } from '../shared/child-process.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { buildExtractionPrompt } from './abstention.js';
-import { formatResultText as formatResultTextShared } from '../shared/child-output.js';
-const DEFAULT_LIMIT = 8;
-const DEFAULT_BUDGET = 24_000;
+const DEFAULT_LIMIT = PACKAGE_RETRIEVE_LIMIT;
+const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
 const NO_CACHE_HEAD = 25_000;
 const NO_CACHE_TAIL = 5_000;
 const NO_CACHE_TOTAL = NO_CACHE_HEAD + NO_CACHE_TAIL;
@@ -224,31 +223,11 @@ async function tryResolveOrInstall(name, cwd, spawn, resolvePackage, signal) {
         }
     }
 }
-/** Follow the @types/<name> + triple-slash `<reference types>` redirect chain
- *  from a package that ships no usable types of its own to the one that actually
- *  holds the declarations (e.g. bun -> @types/bun -> bun-types). Bounded to a few
- *  hops; returns the original package if no better source is found. */
-async function resolveTypeSource(pkg, requested, cwd, spawn, resolvePackage, signal) {
-    const visited = new Set([pkg.name, extractParentPackage(requested)]);
-    let cur = pkg;
-    for (let depth = 0; depth < 3; depth++) {
-        let next = detectTypesRedirect(cur);
-        if (next && visited.has(next))
-            next = null;
-        if (!next && !hasTypeFiles(cur.root)) {
-            const types = typesPackageName(cur.name);
-            if (types && !visited.has(types))
-                next = types;
-        }
-        if (!next)
-            break;
-        visited.add(next);
-        const resolved = await tryResolveOrInstall(next, cwd, spawn, resolvePackage, signal);
-        if (!resolved)
-            break;
-        cur = resolved;
-    }
-    return cur;
+/** The docs pipeline's adapter over the shared redirect walk (docs-resolve.ts):
+ *  hops resolve through the auto-installing lookup, so a declaration package that is
+ *  declared but not yet on disk is fetched rather than abandoned. */
+function resolveTypeSourceForDocs(pkg, requested, cwd, spawn, resolvePackage, signal) {
+    return resolveTypeSource(pkg, extractParentPackage(requested), next => tryResolveOrInstall(next, cwd, spawn, resolvePackage, signal));
 }
 export async function docsRaw(input) {
     const resolvePackage = input.resolvePackage ?? defaultResolvePackage;
@@ -344,7 +323,7 @@ export async function docsRaw(input) {
     // @types/<name> + triple-slash `<reference types>` chain to the package that
     // actually holds the declarations (e.g. bun -> @types/bun -> bun-types).
     // Best-effort: any failure leaves the original resolution untouched.
-    pkg = await resolveTypeSource(pkg, requested, input.cwd, spawn, resolvePackage, input.signal);
+    pkg = await resolveTypeSourceForDocs(pkg, requested, input.cwd, spawn, resolvePackage, input.signal);
     // Step 2: open cache
     let cache = null;
     let cacheError;
@@ -569,9 +548,6 @@ export function buildPrompt(pkg, query, content) {
  * (`{name, version: 'local', root, entryDts: null, readme: null}`) purely to make
  * this call compile, with three of the five fields existing only for that.
  */
-export function formatResultText(header, parsed, verified) {
-    return formatResultTextShared(header, parsed, verified);
-}
 /** The header for an npm package answer. */
 export function packageHeader(pkg) {
     return `Per ${pkg.name}@${pkg.version}:`;

package/dist/workers/docs-project.js

@@ -2,11 +2,11 @@ import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
+import { retrieveChunks as defaultRetrieveChunks, PROJECT_RETRIEVE_LIMIT, RETRIEVE_CONTENT_BUDGET } from './docs-retrieve.js';
 import { buildExtractionPrompt } from './abstention.js';
 import { chunkDeclarations } from './docs-chunk.js';
-const DEFAULT_LIMIT = 50;
-const DEFAULT_BUDGET = 24_000;
+const DEFAULT_LIMIT = PROJECT_RETRIEVE_LIMIT;
+const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
 export function getProjectName(cwd) {
     try {
         const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));

package/dist/workers/docs-resolve.d.ts

@@ -54,3 +54,21 @@ export declare function countEntryDeclarations(content: string): number;
  *  local `/// <reference path=... />` aggregator entry, or an entry file that
  *  declares anything of its own). */
 export declare function detectTypesRedirect(pkg: ResolvedPackage): string | null;
+/**
+ * Follow the `@types/<name>` + triple-slash `<reference types>` redirect chain from
+ * a package that ships no usable types of its own to the one that actually holds
+ * the declarations — `bun` → `@types/bun` → `bun-types`. Bounded to three hops;
+ * returns the package it started from when no better source is found.
+ *
+ * This is what the four predicates above EXIST for. They were exported and heavily
+ * tested (35 references between them) while the loop that calls them lived in two
+ * byte-identical copies — `docs-core.ts` and `phantom-imports.ts` — and NEITHER was
+ * covered: both of their tests pin only the zero-hop case, so the multi-hop
+ * behaviour cited by name in five doc comments was asserted nowhere.
+ *
+ * `resolveHop` is the one thing the two call sites genuinely disagree about: the
+ * docs pipeline resolves the next hop through an auto-installing async lookup, the
+ * phantom-import checker through a bare sync resolve that must never install. It
+ * returns null to stop the walk.
+ */
+export declare function resolveTypeSource(start: ResolvedPackage, seed: string, resolveHop: (name: string) => Promise<ResolvedPackage | null>): Promise<ResolvedPackage>;

package/dist/workers/docs-resolve.js

@@ -304,3 +304,42 @@ export function detectTypesRedirect(pkg) {
         return null;
     return target;
 }
+/**
+ * Follow the `@types/<name>` + triple-slash `<reference types>` redirect chain from
+ * a package that ships no usable types of its own to the one that actually holds
+ * the declarations — `bun` → `@types/bun` → `bun-types`. Bounded to three hops;
+ * returns the package it started from when no better source is found.
+ *
+ * This is what the four predicates above EXIST for. They were exported and heavily
+ * tested (35 references between them) while the loop that calls them lived in two
+ * byte-identical copies — `docs-core.ts` and `phantom-imports.ts` — and NEITHER was
+ * covered: both of their tests pin only the zero-hop case, so the multi-hop
+ * behaviour cited by name in five doc comments was asserted nowhere.
+ *
+ * `resolveHop` is the one thing the two call sites genuinely disagree about: the
+ * docs pipeline resolves the next hop through an auto-installing async lookup, the
+ * phantom-import checker through a bare sync resolve that must never install. It
+ * returns null to stop the walk.
+ */
+export async function resolveTypeSource(start, seed, resolveHop) {
+    const visited = new Set([start.name, seed]);
+    let cur = start;
+    for (let hop = 0; hop < 3; hop++) {
+        let next = detectTypesRedirect(cur);
+        if (next && visited.has(next))
+            next = null;
+        if (!next && !hasTypeFiles(cur.root)) {
+            const types = typesPackageName(cur.name);
+            if (types && !visited.has(types))
+                next = types;
+        }
+        if (!next)
+            break;
+        visited.add(next);
+        const resolved = await resolveHop(next);
+        if (!resolved)
+            break;
+        cur = resolved;
+    }
+    return cur;
+}