@mjasnikovs/pi-task 0.37.7 → 0.38.0

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

@@ -4,6 +4,7 @@ import { resolvePackage as defaultResolvePackage, type ResolvedPackage } from '.
 import { retrieveChunks as defaultRetrieveChunks, type RetrievedChunk } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup, type NpmVersionInfo } from './npm-version.js';
 import { type SpawnFn } from '../shared/child-process.js';
+import { type ExcerptVerification } from '../shared/child-output.js';
 /**
  * Provenance of an auto-installed package's version, so the answer can state
  * what the version is grounded in instead of leaving it buried in tool details.
@@ -74,9 +75,22 @@ export interface DocsRawInput {
     signal?: AbortSignal;
 }
 export interface DocsFocusedResult {
+    /**
+     * The child's answer — EMPTY when `failure` is set. A failed child's stdout is never
+     * parsed as an answer (it used to be: `parseChildOutput` returns the whole trimmed
+     * stdout when there is no `<answer>` tag, so a crashed child's error dump was handed
+     * to phaseAutoAnswer as if it were package documentation).
+     */
     answer: string;
     excerpt?: string;
     excerptVerified?: boolean;
+    /** Retained evidence for a false `excerptVerified`, diagnosable without re-running. */
+    excerptCheck?: ExcerptVerification;
+    /**
+     * Set exactly when the child failed (aborted, or non-zero exit): the standard
+     * child-failure message. Callers must treat `answer` as absent when this is present.
+     */
+    failure?: string;
     pkg: ResolvedPackage;
     version: string;
     exitCode: number;

package/dist/workers/docs-core.js

@@ -7,17 +7,15 @@ 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 { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
-import { getPiInvocation } from '../shared/pi-invocation.js';
 import { runChild } from '../shared/child-process.js';
-import { childBaseArgs } from '../shared/child-extensions.js';
-import { parseChildOutput, isExcerptInContent, formatResultText as formatResultTextShared } from '../shared/child-output.js';
+import { runFocusedExtraction } from './focused-extractor.js';
+import { formatResultText as formatResultTextShared } from '../shared/child-output.js';
 const DEFAULT_LIMIT = 8;
 const DEFAULT_BUDGET = 24_000;
 const NO_CACHE_HEAD = 25_000;
 const NO_CACHE_TAIL = 5_000;
 const NO_CACHE_TOTAL = NO_CACHE_HEAD + NO_CACHE_TAIL;
 const NO_CACHE_MARKER = '\n\n[...content continues, truncated...]\n\n';
-const childArgs = () => [...childBaseArgs(), '--no-tools'];
 export function extractParentPackage(moduleName) {
     if (moduleName.startsWith('@')) {
         const parts = moduleName.split('/');
@@ -516,26 +514,40 @@ export async function docsFocused(input) {
     }
     const { pkg, chunks, hitCache, indexingMs } = rawResult;
     const concatenated = chunks.map(c => c.content).join('\n\n');
-    const prompt = buildPrompt(pkg, input.query, concatenated);
-    const invocation = getPiInvocation(childArgs(), prompt);
-    const child = await runChild(spawn, invocation, input.cwd, input.signal);
-    const parsed = parseChildOutput(child.stdout);
-    const excerptVerified = parsed.excerpt ? isExcerptInContent(parsed.excerpt, concatenated) : undefined;
-    return {
-        answer: parsed.answer,
-        excerpt: parsed.excerpt,
-        excerptVerified,
+    const extraction = await runFocusedExtraction({
+        prompt: buildPrompt(pkg, input.query, concatenated),
+        // Exactly what went into the prompt — this path prompts with the whole concatenation,
+        // so the verify target and the prompt content are the same text.
+        verifyAgainst: concatenated,
+        cwd: input.cwd,
+        signal: input.signal,
+        spawn,
+        abortedMessage: 'Docs lookup aborted.'
+    });
+    const base = {
         pkg,
         version: pkg.version,
-        exitCode: child.exitCode,
-        aborted: child.aborted,
-        stderr: child.stderr,
+        exitCode: extraction.exitCode,
+        aborted: extraction.aborted,
+        stderr: extraction.stderr,
         hitCache,
         indexingMs,
         chunksRetrieved: chunks.length,
         autoInstalled: rawResult.autoInstalled,
         npmVersion: rawResult.npmVersion
     };
+    // A failed child yields NO answer. The caller (phaseAutoAnswer) gates on `answer` being
+    // non-empty, so an empty one keeps a dead child's output out of the spec entirely;
+    // `failure` carries the reason for anyone who wants to report it.
+    if (!extraction.ok)
+        return { answer: '', failure: extraction.failure, ...base };
+    return {
+        answer: extraction.answer,
+        excerpt: extraction.excerpt,
+        excerptVerified: extraction.excerptVerified,
+        excerptCheck: extraction.excerptCheck,
+        ...base
+    };
 }
 export function buildPrompt(pkg, query, content) {
     return (`You answer one question about an npm package, using only the provided content.\n`

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

@@ -1,5 +1,5 @@
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
-import { type SpawnFn } from '../shared/child-process.js';
+import type { SpawnFn } from '../shared/child-process.js';
 import { type ExcerptVerification } from '../shared/child-output.js';
 /** The exact non-answers the child is instructed to emit, matched at the tool layer. */
 export declare const UNCLEAR_ANSWER = "unclear from this page";
@@ -67,6 +67,11 @@ export interface FetchFocusedResult {
     excerptCheck?: ExcerptVerification;
     /** The prompt actually handed to the child — the A/B asserts surgery against this per rep. */
     assembledPrompt: string;
+    /**
+     * Set exactly when the child failed (aborted, or non-zero exit): the standard
+     * child-failure message, already formatted. Present ⇒ `answer` is empty and means nothing.
+     */
+    failure?: string;
     childExitCode: number;
     aborted: boolean;
     stderr: string;

package/dist/workers/fetch-core.js

@@ -1,9 +1,6 @@
-import { spawn as defaultSpawn } from 'node:child_process';
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
-import { getPiInvocation } from '../shared/pi-invocation.js';
-import { runChild } from '../shared/child-process.js';
-import { childBaseArgs } from '../shared/child-extensions.js';
-import { parseChildOutput, verifyExcerpt, formatResultText as formatResultTextShared } from '../shared/child-output.js';
+import { runFocusedExtraction } from './focused-extractor.js';
+import { formatResultText as formatResultTextShared } from '../shared/child-output.js';
 const CONTENT_BUDGET = 30_000;
 const HEAD_CHARS = 25_000;
 const TAIL_CHARS = 5_000;
@@ -23,7 +20,6 @@ export const NOT_COVERED_ANSWER = 'not covered by this page';
  * no recorded verdict.
  */
 const NOT_COVERED_RE = /^not covered by this page[.\s]*$/i;
-const childArgs = () => [...childBaseArgs(), '--no-tools'];
 /**
  * `github.com/{owner}/{repo}/blob/{ref}/{path}` renders the file through a client-side
  * viewer, so the HTML we clean carries GitHub chrome ("Sign in", "Appearance settings")
@@ -59,7 +55,6 @@ export async function fetchRaw(input) {
 }
 export async function fetchFocused(input) {
     const fetchAndCleanFn = input.fetchAndClean ?? defaultFetchAndClean;
-    const spawnFn = input.spawn ?? defaultSpawn;
     const strategy = input.strategy ?? shippedStrategy;
     const fetchedUrl = normaliseSourceUrl(input.url);
     const cleaned = await fetchAndCleanFn(fetchedUrl, { signal: input.signal });
@@ -73,43 +68,41 @@ export async function fetchFocused(input) {
         content: selected.content,
         section: selected.section
     });
-    const invocation = getPiInvocation(childArgs(), prompt);
-    const childResult = await runChild(spawnFn, invocation, input.cwd, input.signal);
+    const extraction = await runFocusedExtraction({
+        prompt,
+        // Verify against the FULL page, not the anchored slice we prompted with: the slice is
+        // a substring of it, so a genuine excerpt still verifies, and an excerpt the child
+        // pulled from memory still fails — the detector's discrimination is unchanged by
+        // fragment anchoring. This is the one call site that verifies against a SUPERSET of
+        // the prompt content, which is why the extractor takes the target by name.
+        verifyAgainst: cleaned.markdown,
+        cwd: input.cwd,
+        signal: input.signal,
+        spawn: input.spawn,
+        abortedMessage: 'Fetch aborted.'
+    });
     const base = {
         anchoredSection: selected.section,
         assembledPrompt: prompt,
-        stderr: childResult.stderr,
-        stdout: childResult.stdout
+        stderr: extraction.stderr,
+        stdout: extraction.stdout
     };
-    if (childResult.aborted) {
-        return {
-            answer: '',
-            coverageMiss: false,
-            childExitCode: childResult.exitCode,
-            aborted: true,
-            ...base
-        };
-    }
-    if (childResult.exitCode !== 0) {
+    if (!extraction.ok) {
         return {
             answer: '',
             coverageMiss: false,
-            childExitCode: childResult.exitCode,
-            aborted: false,
+            failure: extraction.failure,
+            childExitCode: extraction.exitCode,
+            aborted: extraction.aborted,
             ...base
         };
     }
-    const parsed = parseChildOutput(childResult.stdout);
-    const coverageMiss = NOT_COVERED_RE.test(parsed.answer.trim());
-    // Verify against the FULL page, not the anchored slice: the slice is a substring of it,
-    // so a genuine excerpt still verifies, and an excerpt the child pulled from memory still
-    // fails — the detector's discrimination is unchanged by fragment anchoring.
-    const check = parsed.excerpt ? verifyExcerpt(parsed.excerpt, cleaned.markdown) : undefined;
+    const coverageMiss = NOT_COVERED_RE.test(extraction.answer.trim());
     return {
-        answer: parsed.answer,
-        excerpt: parsed.excerpt,
-        excerptVerified: check?.verified,
-        excerptCheck: check,
+        answer: extraction.answer,
+        excerpt: extraction.excerpt,
+        excerptVerified: extraction.excerptVerified,
+        excerptCheck: extraction.excerptCheck,
         coverageMiss,
         nextStep: coverageMiss ? coverageMissNextStep(input.url, fetchedUrl) : undefined,
         childExitCode: 0,

package/dist/workers/focused-extractor.d.ts

@@ -0,0 +1,73 @@
+import { type SpawnFn } from '../shared/child-process.js';
+import { type ExcerptVerification } from '../shared/child-output.js';
+/**
+ * The argv every focused extraction child runs with: the shared child base (whitelisted
+ * extensions + `--print --no-session …`) plus `--no-tools`. This was three byte-identical
+ * one-liners in fetch-core, docs-core and pi-worker-docs.
+ *
+ * `--no-tools` is the contract, not a default: the child is given all the content it may use
+ * inside its prompt, so a tool call could only reach for something unsourced.
+ */
+export declare const focusedChildArgs: () => string[];
+export interface FocusedRequest {
+    /** The fully assembled prompt, including the content block. Delivered on stdin. */
+    prompt: string;
+    /**
+     * The text the cited excerpt is checked against — a NAMED knob, because the four call
+     * sites deliberately disagree and the disagreement used to be invisible.
+     *
+     * `pi-worker-docs` and `docsFocused` pass exactly the concatenated chunks that went into
+     * the prompt. `fetchFocused` passes the FULL cleaned page while prompting with only the
+     * anchored `#fragment` section: the slice is a substring of the page, so a genuine excerpt
+     * still verifies, and an excerpt pulled from the model's memory still fails — fragment
+     * anchoring therefore cannot change the hallucination detector's discrimination.
+     *
+     * Passing the prompt's own content is the safe default; passing a SUPERSET (as fetch does)
+     * loosens the check deliberately. Passing anything narrower would manufacture false
+     * fabrication verdicts.
+     */
+    verifyAgainst: string;
+    cwd: string;
+    signal?: AbortSignal;
+    /** Defaults to node's spawn; injected by tests and by the worker `internals` hooks. */
+    spawn?: SpawnFn;
+    /** The message reported when the child was aborted, e.g. `'Docs lookup aborted.'`. */
+    abortedMessage: string;
+}
+/** What every outcome carries, success or failure — the raw child evidence. */
+interface FocusedChildEvidence {
+    exitCode: number;
+    aborted: boolean;
+    stderr: string;
+    /** The child's raw stdout, retained for A/B harnesses and failure diagnosis. */
+    stdout: string;
+}
+/** The child aborted or exited non-zero. There is deliberately no `answer` here. */
+export interface FocusedFailure extends FocusedChildEvidence {
+    ok: false;
+    /** `formatChildFailure`'s message — the abort message, or `Worker exited N` + stderr tail. */
+    failure: string;
+}
+/** The child exited 0; its output has been parsed and its citation checked. */
+export interface FocusedAnswer extends FocusedChildEvidence {
+    ok: true;
+    aborted: false;
+    /** The `<answer>` body, or the whole trimmed stdout when the child emitted no tags. */
+    answer: string;
+    /** The `<excerpt>` body; absent when the child cited nothing (or cited only whitespace). */
+    excerpt?: string;
+    /** The full verification record — absent exactly when `excerpt` is. */
+    excerptCheck?: ExcerptVerification;
+    /** `excerptCheck?.verified`, for the many callers that only report the verdict. */
+    excerptVerified?: boolean;
+}
+export type FocusedResult = FocusedFailure | FocusedAnswer;
+/**
+ * Run one focused extraction: spawn the no-tools child on `prompt`, and on success parse its
+ * `<answer>`/`<excerpt>` and verify the excerpt against `verifyAgainst`.
+ *
+ * Never retries — a re-ask of a deterministic extraction over unchanged content is a second
+ * bill for the same answer, and all four call sites already had it that way.
+ */
+export declare function runFocusedExtraction(req: FocusedRequest): Promise<FocusedResult>;
+export {};

package/dist/workers/focused-extractor.js

@@ -0,0 +1,72 @@
+/**
+ * The **Focused extractor** — the one place a no-tools child pi is run to answer ONE question
+ * over content already in hand, cite a verbatim `<excerpt>`, and have that citation checked.
+ *
+ * It had four copies: `fetchFocused` (fetch-core), `docsFocused` (docs-core), and both paths
+ * of `pi-worker-docs` (project source, npm package) — the last two 17-of-20 lines identical
+ * and 150 lines apart inside one function. Everything the four did around the child was
+ * byte-identical: the `--no-tools` argv, `getPiInvocation`, `runChild`, `parseChildOutput`,
+ * and no retry. What genuinely differed was DATA, and the copies hid it:
+ *
+ *   1. the prompt body — so {@link FocusedRequest.prompt} is a string the caller assembles;
+ *   2. WHAT the excerpt is verified against — see {@link FocusedRequest.verifyAgainst};
+ *   3. what the answer MEANS (fetch's coverage-miss sentinel) — left to the caller, because
+ *      classifying an answer is the caller's domain, not the child runner's.
+ *
+ * Two things the copies got wrong, fixed here once:
+ *   - **Failure.** `docsFocused` never called `formatChildFailure`, so a child that exited
+ *     non-zero had its raw stdout parsed as if it were an answer (`parseChildOutput` returns
+ *     the whole trimmed stdout when there is no `<answer>` tag) and handed to the caller.
+ *     The result type below makes that unrepresentable: there is no `answer` on a failure.
+ *   - **Evidence.** Only fetch kept the rich {@link ExcerptVerification}; the other three
+ *     reduced it to a bare boolean, which is exactly the diagnostic gap typeonly-log.ts
+ *     names — an `excerptVerified === false` that cannot afterwards be attributed to
+ *     fabrication vs a normaliser gap. Every caller now gets the struct.
+ */
+import { spawn as defaultSpawn } from 'node:child_process';
+import { getPiInvocation } from '../shared/pi-invocation.js';
+import { runChild } from '../shared/child-process.js';
+import { childBaseArgs } from '../shared/child-extensions.js';
+import { parseChildOutput, verifyExcerpt } from '../shared/child-output.js';
+import { formatChildFailure } from './shared.js';
+/**
+ * The argv every focused extraction child runs with: the shared child base (whitelisted
+ * extensions + `--print --no-session …`) plus `--no-tools`. This was three byte-identical
+ * one-liners in fetch-core, docs-core and pi-worker-docs.
+ *
+ * `--no-tools` is the contract, not a default: the child is given all the content it may use
+ * inside its prompt, so a tool call could only reach for something unsourced.
+ */
+export const focusedChildArgs = () => [...childBaseArgs(), '--no-tools'];
+/**
+ * Run one focused extraction: spawn the no-tools child on `prompt`, and on success parse its
+ * `<answer>`/`<excerpt>` and verify the excerpt against `verifyAgainst`.
+ *
+ * Never retries — a re-ask of a deterministic extraction over unchanged content is a second
+ * bill for the same answer, and all four call sites already had it that way.
+ */
+export async function runFocusedExtraction(req) {
+    const spawn = req.spawn ?? defaultSpawn;
+    const invocation = getPiInvocation(focusedChildArgs(), req.prompt);
+    const child = await runChild(spawn, invocation, req.cwd, req.signal);
+    const evidence = {
+        exitCode: child.exitCode,
+        aborted: child.aborted,
+        stderr: child.stderr,
+        stdout: child.stdout
+    };
+    const failure = formatChildFailure(child, req.abortedMessage);
+    if (failure !== null)
+        return { ok: false, failure, ...evidence };
+    const parsed = parseChildOutput(child.stdout);
+    const excerptCheck = parsed.excerpt ? verifyExcerpt(parsed.excerpt, req.verifyAgainst) : undefined;
+    return {
+        ok: true,
+        ...evidence,
+        aborted: false,
+        answer: parsed.answer,
+        excerpt: parsed.excerpt,
+        excerptCheck,
+        excerptVerified: excerptCheck?.verified
+    };
+}

package/dist/workers/pi-worker-docs.d.ts

@@ -4,7 +4,7 @@ import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
 import { resolvePackage as defaultResolvePackage } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
-import { type SpawnFn } from '../shared/child-process.js';
+import type { SpawnFn } from '../shared/child-process.js';
 /**
  * Pull `@see {@link https://…}` pointers out of retrieved .d.ts/README text.
  *

package/dist/workers/pi-worker-docs.js

@@ -5,17 +5,13 @@ import { openCache as defaultOpenCache } from './docs-cache.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { docsRaw, formatResultText, buildPrompt, buildVersionBanner } from './docs-core.js';
 import { formatNpmVersionSection } from './npm-version.js';
-import { runChild } from '../shared/child-process.js';
-import { childBaseArgs } from '../shared/child-extensions.js';
-import { parseChildOutput, isExcerptInContent } from '../shared/child-output.js';
-import { getPiInvocation } from '../shared/pi-invocation.js';
-import { formatChildFailure, makeWorkerTool } from './shared.js';
+import { runFocusedExtraction } from './focused-extractor.js';
+import { makeWorkerTool } from './shared.js';
 import { isTypeOnlyAnswer } from '../task/type-only-answer.js';
 import { logDocsAnswer } from './typeonly-log.js';
 import { normalizeQuery } from './research-cache.js';
 import { projectDocsRaw, buildProjectPrompt } from './docs-project.js';
 import { projectDocsBudget, projectDocsBudgetExhausted } from '../task/research-fanout-budget.js';
-const childArgs = () => [...childBaseArgs(), '--no-tools'];
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
     module: Type.String({
@@ -57,6 +53,25 @@ export function packageRootOf(module) {
 function pinDetails(pin) {
     return pin ? { versionSource: pin.source, declaredRange: pin.range } : {};
 }
+/**
+ * The tool result for a focused-extraction child that failed, shared by both docs paths —
+ * the last chunk they still held in common after the extractor seam took the child running.
+ * The paths differ only in `prefix`: the npm path leads every result, failures included, with
+ * its version banner and npm-version header; the project path has neither.
+ *
+ * `childExitCode` is recorded but NOT as 0, which is what keeps a failure out of the research
+ * cache (see `cacheable` below).
+ */
+function docsFailureResult(extraction, baseDetails, prefix) {
+    return {
+        text: prefix + extraction.failure,
+        details: {
+            ...baseDetails,
+            ...(extraction.aborted ? { aborted: true } : {}),
+            childExitCode: extraction.exitCode
+        }
+    };
+}
 export function registerPiWorkerDocs(pi, internals = {}) {
     // CAP arm of nexttask 5B — OFF unless PI_TASK_PROJECT_DOCS_BUDGET is set, and
     // then per-ATTEMPT by construction: the extension is loaded into a fresh pi
@@ -110,6 +125,18 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             // It was DEAD in production (pi runs under node) and BYPASSED under bun test
             // (internals.spawn is always injected), i.e. untested, unreachable, and wrong.
             const spawn = internals.spawn ?? defaultSpawn;
+            // Both paths below run the SAME extraction against this call's cwd/signal/spawn
+            // and verify the citation against exactly the content they prompted with; only
+            // the prompt body and the abort wording differ. (fetch is the site that verifies
+            // against a superset — see FocusedRequest.verifyAgainst.)
+            const extract = (prompt, content, abortedMessage) => runFocusedExtraction({
+                prompt,
+                verifyAgainst: content,
+                cwd: ctx.cwd,
+                signal,
+                spawn,
+                abortedMessage
+            });
             // ── Project source lookup ───────────────────────────────────────
             if (params.module === '.') {
                 const budget = projectDocsBudget();
@@ -158,29 +185,17 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                     indexingMs
                 };
                 const concatenated = chunks.map(c => c.content).join('\n\n');
-                const prompt = buildProjectPrompt(projectName, params.query, concatenated);
-                const invocation = getPiInvocation(childArgs(), prompt);
-                const child = await runChild(spawn, invocation, ctx.cwd, signal);
-                const failure = formatChildFailure(child, 'Project docs lookup aborted.');
-                if (failure !== null) {
-                    return {
-                        text: failure,
-                        details: {
-                            ...baseDetails,
-                            ...(child.aborted ? { aborted: true } : {}),
-                            childExitCode: child.exitCode
-                        }
-                    };
-                }
-                const parsed = parseChildOutput(child.stdout);
-                const verified = parsed.excerpt ? isExcerptInContent(parsed.excerpt, concatenated) : undefined;
+                const extraction = await extract(buildProjectPrompt(projectName, params.query, concatenated), concatenated, 'Project docs lookup aborted.');
+                if (!extraction.ok)
+                    return docsFailureResult(extraction, baseDetails, '');
+                const verified = extraction.excerptVerified;
                 const text = formatResultText({
                     name: projectName,
                     version: 'local',
                     root: ctx.cwd,
                     entryDts: null,
                     readme: null
-                }, parsed, verified);
+                }, extraction, verified);
                 // SAME instrumentation channel as the package path below, extended to the
                 // project-source branch because that branch is the MAJORITY of what
                 // worker:apis asks — 13 of 17 docs calls in run 15's fatal task, 7 of 12 in
@@ -196,10 +211,11 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 logDocsAnswer({
                     module: params.module,
                     query: params.query,
-                    answer: parsed.answer,
+                    answer: extraction.answer,
                     typeOnly: false,
                     reason: 'project-source lookup — the type-only detector is not applied here',
                     excerptVerified: verified,
+                    excerptCheck: extraction.excerptCheck,
                     toolText: text
                 });
                 return {
@@ -281,23 +297,12 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 ...npmDetails
             };
             const concatenated = chunks.map(c => c.content).join('\n\n');
-            const prompt = buildPrompt(pkg, params.query, concatenated);
-            const invocation = getPiInvocation(childArgs(), prompt);
-            const child = await runChild(spawn, invocation, ctx.cwd, signal);
-            const failure = formatChildFailure(child, 'Docs lookup aborted.');
-            if (failure !== null) {
-                return {
-                    text: versionBanner + npmHeader + failure,
-                    details: {
-                        ...baseDetails,
-                        ...(child.aborted ? { aborted: true } : {}),
-                        childExitCode: child.exitCode
-                    }
-                };
+            const extraction = await extract(buildPrompt(pkg, params.query, concatenated), concatenated, 'Docs lookup aborted.');
+            if (!extraction.ok) {
+                return docsFailureResult(extraction, baseDetails, versionBanner + npmHeader);
             }
-            const parsed = parseChildOutput(child.stdout);
-            const verified = parsed.excerpt ? isExcerptInContent(parsed.excerpt, concatenated) : undefined;
-            const body = formatResultText(pkg, parsed, verified);
+            const verified = extraction.excerptVerified;
+            const body = formatResultText(pkg, extraction, verified);
             // F-2: a TYPE-ONLY answer is the dangerous failure. "unclear from this package"
             // is honest and already escalates; a signature is a well-formed, confident,
             // on-topic answer that names the very parameter asked about, so the worker
@@ -310,7 +315,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             // hono.dev present in run-15 cache values ONLY inside these JSDoc links, never
             // fetched. Prompting the escalation beats performing it here: this tool runs in
             // parallel execution mode and cannot cleanly spawn a fetch of its own.
-            const typeOnly = isTypeOnlyAnswer(parsed.answer, params.query);
+            const typeOnly = isTypeOnlyAnswer(extraction.answer, params.query);
             let text = versionBanner + npmHeader + body;
             if (typeOnly.typeOnly) {
                 const seeUrls = extractSeeUrls(concatenated);
@@ -344,10 +349,11 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             logDocsAnswer({
                 module: params.module,
                 query: params.query,
-                answer: parsed.answer,
+                answer: extraction.answer,
                 typeOnly: typeOnly.typeOnly,
                 reason: typeOnly.reason,
                 excerptVerified: verified,
+                excerptCheck: extraction.excerptCheck,
                 toolText: text
             });
             return {

package/dist/workers/pi-worker-fetch.js

@@ -2,7 +2,7 @@ import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
 import { FetchAndCleanError } from './html-clean.js';
 import { fetchFocused, formatResultText } from './fetch-core.js';
-import { formatChildFailure, makeWorkerTool } from './shared.js';
+import { makeWorkerTool } from './shared.js';
 import { normalizeQuery } from './research-cache.js';
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
@@ -44,13 +44,11 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                     fetchAndClean: internals.fetchAndClean,
                     spawn: internals.spawn
                 });
-                const failure = formatChildFailure({
-                    aborted: result.aborted,
-                    exitCode: result.childExitCode,
-                    stderr: result.stderr
-                }, 'Fetch aborted.');
-                if (failure !== null) {
-                    return { text: failure, details: { childExitCode: result.childExitCode } };
+                // Child failure is decided and formatted once, inside the focused extractor
+                // (workers/focused-extractor.ts) — this used to re-map the result back into a
+                // ChildOutcome just to ask formatChildFailure the same question.
+                if (result.failure !== undefined) {
+                    return { text: result.failure, details: { childExitCode: result.childExitCode } };
                 }
                 const body = formatResultText({ answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
                 // The coverage miss is the one outcome that carries an instruction. It goes

package/dist/workers/typeonly-log.d.ts

@@ -1,3 +1,4 @@
+import type { ExcerptVerification } from '../shared/child-output.js';
 /** Env var naming the JSONL sink. Unset (or empty) ⇒ instrumentation is entirely off. */
 export declare const TYPEONLY_LOG_ENV = "PI_TASK_TYPEONLY_LOG";
 /** One pi-worker-docs answer, as observed at the tool layer. */
@@ -18,6 +19,18 @@ export interface TypeOnlyLogRecord {
     unclear: boolean;
     /** child-output's excerpt check; undefined when the child cited no excerpt. */
     excerptVerified?: boolean;
+    /**
+     * The FULL verification record behind `excerptVerified` — the normalised excerpt that was
+     * searched for, plus a sha256 + length of the normalised content it was searched in.
+     *
+     * This is the other half of the F-3(f) hole described above: retaining the answer text
+     * says WHAT was claimed, and this says what it was checked against, so a false verdict can
+     * be attributed to fabrication (the excerpt is nowhere near the content) rather than a
+     * normaliser gap (a markdown-escape variant of text that IS present) without re-running
+     * the lookup. Only fetch's extractor used to keep it; all four focused-extractor call
+     * sites now can (workers/focused-extractor.ts). Optional — records predating it parse.
+     */
+    excerptCheck?: ExcerptVerification;
     /**
      * The tool's ENTIRE return text — version banner, npm header, the answer prose, the cited
      * excerpt, and (when it fires) the type-only banner. Optional so logs written before this

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.37.7",
+    "version": "0.38.0",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",