@mjasnikovs/pi-task 0.18.48 → 0.18.50

package/dist/task/type-only-answer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Deterministic detector for the F-2 shape: a pi-worker-docs answer that RESTATES a type
+ * signature or declaration for a USAGE question, without ever saying what the API DOES.
+ *
+ * THE FATAL CASE, from mx5 run 15 (research-cache.json, verbatim):
+ *
+ *   query : "hc factory function signature base url parameter types exported from hono/client"
+ *   answer: "The `hc` factory function exported from `hono/client` accepts a generic type
+ *            `T` extending `Hono`, an optional string prefix type `Prefix` (defaulting to
+ *            `string`), and takes two parameters: `baseUrl` of type `Prefix` and an optional
+ *            `options` of type `ClientRequestOptions`. It returns a
+ *            `UnionToIntersection<Client<T, Prefix>>`."
+ *
+ * Every clause is type-level. "`baseUrl` of type `Prefix`" names the parameter's TYPE — and
+ * `Prefix` is itself an opaque type variable — while saying nothing about what `baseUrl`
+ * MEANS (is it an origin, or a mount prefix?). Escalation to search/fetch never fired
+ * because the answer looked complete: it named the very parameter asked about. worker:context
+ * then filled the semantic gap from memory and shipped `hc<AppType>('/api')`, so every request
+ * went to `/api/api/...` ⇒ 404 ⇒ the product's entire API surface was dead (F-2 → F-1).
+ *
+ * The lever (PROMPT 2 DO item 1): when a docs answer for a usage question is ONLY a
+ * signature/declaration restatement with no behavioural statement, treat it as UNANSWERED so
+ * the caller escalates (follow the `@see` pointer / fetch the spec-cited URL) instead of
+ * accepting a type as the answer.
+ *
+ * ── PRECISION/RECALL TRADEOFF (chosen deliberately; documented per the task) ────────────────
+ * A FALSE POSITIVE here (flagging a real answer as type-only) forces a needless escalation:
+ * wall-clock cost against PROMPT 2 invariant 1, which caps added child spawns. A false
+ * NEGATIVE (missing a type-only answer) merely leaves the pre-existing bug unfixed for that
+ * one borderline case. So this detector is tuned for HIGH PRECISION on real answers, accepting
+ * low recall — "better to miss a borderline type-only answer than to flag a real one." Three
+ * independent gates must ALL hold before an answer is called type-only; any one failing clears
+ * it. Calibrated against the run-15 corpus: of the 149 valid (non-"unclear") pi-worker-docs
+ * answers, this rule flags EXACTLY ONE — the recorded `hc` case — and clears the other 148,
+ * including every legitimate signature answer to an explicit "give me the type/signature"
+ * question (bun.password.hash, toBuffer, BuildOutput, …). See type-only-answer.test.ts.
+ *
+ * THE THREE GATES (all required):
+ *   1. USAGE QUESTION. The question must seek usage/semantics — "how", "use", "work", "chain",
+ *      "example", "call", "rpc", "mean", or it names a usage concept whose meaning is being
+ *      sought ("base url"). A question that asks only for a TYPE / SIGNATURE / DEFINITION /
+ *      FIELDS is legitimately answered by a signature, so it is NOT gated in. (The recorded hc
+ *      query is signature-shaped but names "base url", the concept whose meaning was needed.)
+ *   2. NO BEHAVIOURAL CONTENT IN PROSE. The answer must contain no statement of what the API
+ *      DOES: no usage verb ("use/call/pass/import"), no runtime-effect verb ("executes/
+ *      prepends/enables/wraps"), no concrete usage example, no semantic meaning ("means/
+ *      represents/so pass"), no concrete default VALUE or value RANGE ("default of 80", "from
+ *      1 to 100"). Any one clears. This scan runs over `proseOf(answer)`, NOT the raw answer:
+ *      a verb that is really a method name inside a declaration ("methods route(url, handler)
+ *      and use(...handlers)") is an identifier, not behaviour, and must not clear the answer.
+ *   3. SIGNATURE RESTATEMENT. The answer must actually be a declaration/signature restatement —
+ *      "of type", "takes N parameters", "accepts", "returns a…", "extends", "interface",
+ *      "declare const/function". Without this it is not type-only, it is just terse prose.
+ *
+ * An explicit "unclear from this package/page" is NOT type-only — it is the HONEST non-answer,
+ * already handled by the escalation path (PROMPT 2 DO item 2 escalates BOTH). It is cleared
+ * here with a distinct reason so the caller can route it through the existing unclear channel.
+ *
+ * Pure and side-effect free; unit-tested in type-only-answer.test.ts against real run-15 text.
+ */
+/** The verdict, with a human-readable reason for logging and for the escalation channel. */
+export interface TypeOnlyVerdict {
+    /** True iff the answer restates a signature for a usage question with no behaviour. */
+    typeOnly: boolean;
+    /** Why — names the gate that decided it, quoting the matched marker where useful. */
+    reason: string;
+}
+/**
+ * Strip signature/declaration fragments so the behavioural scan sees only PROSE.
+ *
+ * A behavioural verb is a signal ONLY when it is a verb in prose ("the base URL is
+ * prepended", "you use X to Y"), NEVER when it is a method/identifier token inside a
+ * declaration. Without this, a bare type-only answer like
+ *   "It has methods route(url, handler) and use(...handlers)."
+ * is wrongly cleared, because `use(...handlers)` matches /\buse\b/ and `handler` matches
+ * /handle/ — the F-3(a) router-fixture shape. So before scanning for behaviour we remove:
+ *   - `name(args)` call fragments, whose args are identifiers, not prose (this is what
+ *     carries the method-name verbs);
+ *   - `declare const|function|module|class|namespace …` declaration lines.
+ * The SIGNATURE gate still runs against the ORIGINAL answer, so stripping never weakens
+ * gate 3 — it only prevents an identifier inside a signature from masquerading as prose.
+ * Deliberately conservative: it does NOT strip `: Type` annotations or backtick spans,
+ * because a colon or backtick often precedes real behavioural prose ("Usage: call …",
+ * "`sql` is prepended …"), and removing those would silently drop behaviour and MANUFACTURE
+ * false positives — worse than the recall gap this fixes.
+ */
+export declare function proseOf(answer: string): string;
+/**
+ * Decide whether a pi-worker-docs `answer` to `question` is type-only — a signature/declaration
+ * restatement with no behavioural statement, for a question that needed usage semantics.
+ *
+ * @param answer   the child's <answer> prose (NOT the version banner or the source excerpt).
+ * @param question the query the answer was produced for.
+ */
+export declare function isTypeOnlyAnswer(answer: string, question: string): TypeOnlyVerdict;

package/dist/task/type-only-answer.js

@@ -0,0 +1,249 @@
+/**
+ * Deterministic detector for the F-2 shape: a pi-worker-docs answer that RESTATES a type
+ * signature or declaration for a USAGE question, without ever saying what the API DOES.
+ *
+ * THE FATAL CASE, from mx5 run 15 (research-cache.json, verbatim):
+ *
+ *   query : "hc factory function signature base url parameter types exported from hono/client"
+ *   answer: "The `hc` factory function exported from `hono/client` accepts a generic type
+ *            `T` extending `Hono`, an optional string prefix type `Prefix` (defaulting to
+ *            `string`), and takes two parameters: `baseUrl` of type `Prefix` and an optional
+ *            `options` of type `ClientRequestOptions`. It returns a
+ *            `UnionToIntersection<Client<T, Prefix>>`."
+ *
+ * Every clause is type-level. "`baseUrl` of type `Prefix`" names the parameter's TYPE — and
+ * `Prefix` is itself an opaque type variable — while saying nothing about what `baseUrl`
+ * MEANS (is it an origin, or a mount prefix?). Escalation to search/fetch never fired
+ * because the answer looked complete: it named the very parameter asked about. worker:context
+ * then filled the semantic gap from memory and shipped `hc<AppType>('/api')`, so every request
+ * went to `/api/api/...` ⇒ 404 ⇒ the product's entire API surface was dead (F-2 → F-1).
+ *
+ * The lever (PROMPT 2 DO item 1): when a docs answer for a usage question is ONLY a
+ * signature/declaration restatement with no behavioural statement, treat it as UNANSWERED so
+ * the caller escalates (follow the `@see` pointer / fetch the spec-cited URL) instead of
+ * accepting a type as the answer.
+ *
+ * ── PRECISION/RECALL TRADEOFF (chosen deliberately; documented per the task) ────────────────
+ * A FALSE POSITIVE here (flagging a real answer as type-only) forces a needless escalation:
+ * wall-clock cost against PROMPT 2 invariant 1, which caps added child spawns. A false
+ * NEGATIVE (missing a type-only answer) merely leaves the pre-existing bug unfixed for that
+ * one borderline case. So this detector is tuned for HIGH PRECISION on real answers, accepting
+ * low recall — "better to miss a borderline type-only answer than to flag a real one." Three
+ * independent gates must ALL hold before an answer is called type-only; any one failing clears
+ * it. Calibrated against the run-15 corpus: of the 149 valid (non-"unclear") pi-worker-docs
+ * answers, this rule flags EXACTLY ONE — the recorded `hc` case — and clears the other 148,
+ * including every legitimate signature answer to an explicit "give me the type/signature"
+ * question (bun.password.hash, toBuffer, BuildOutput, …). See type-only-answer.test.ts.
+ *
+ * THE THREE GATES (all required):
+ *   1. USAGE QUESTION. The question must seek usage/semantics — "how", "use", "work", "chain",
+ *      "example", "call", "rpc", "mean", or it names a usage concept whose meaning is being
+ *      sought ("base url"). A question that asks only for a TYPE / SIGNATURE / DEFINITION /
+ *      FIELDS is legitimately answered by a signature, so it is NOT gated in. (The recorded hc
+ *      query is signature-shaped but names "base url", the concept whose meaning was needed.)
+ *   2. NO BEHAVIOURAL CONTENT IN PROSE. The answer must contain no statement of what the API
+ *      DOES: no usage verb ("use/call/pass/import"), no runtime-effect verb ("executes/
+ *      prepends/enables/wraps"), no concrete usage example, no semantic meaning ("means/
+ *      represents/so pass"), no concrete default VALUE or value RANGE ("default of 80", "from
+ *      1 to 100"). Any one clears. This scan runs over `proseOf(answer)`, NOT the raw answer:
+ *      a verb that is really a method name inside a declaration ("methods route(url, handler)
+ *      and use(...handlers)") is an identifier, not behaviour, and must not clear the answer.
+ *   3. SIGNATURE RESTATEMENT. The answer must actually be a declaration/signature restatement —
+ *      "of type", "takes N parameters", "accepts", "returns a…", "extends", "interface",
+ *      "declare const/function". Without this it is not type-only, it is just terse prose.
+ *
+ * An explicit "unclear from this package/page" is NOT type-only — it is the HONEST non-answer,
+ * already handled by the escalation path (PROMPT 2 DO item 2 escalates BOTH). It is cleared
+ * here with a distinct reason so the caller can route it through the existing unclear channel.
+ *
+ * Pure and side-effect free; unit-tested in type-only-answer.test.ts against real run-15 text.
+ */
+/**
+ * Question seeks usage/semantics rather than a bare type. A usage concept whose MEANING is
+ * being asked about ("base url") counts, because the F-2 defect is exactly a semantics need
+ * dressed in signature words. A question that asks only for the "type"/"signature"/"definition"
+ * is deliberately NOT here — a signature answer is responsive to it.
+ */
+const USAGE_INTENT = [
+    /\bhow\b/i,
+    /\buse\b/i,
+    /\busing\b/i,
+    /\busage\b/i,
+    /\bworks?\b/i,
+    /\bworking\b/i,
+    /\bchain/i,
+    /base\s?url/i,
+    /\bconnect/i,
+    /\brpc\b/i,
+    /\bexample/i,
+    /\bcall\b/i,
+    /\binvoke/i,
+    /\bmean/i,
+    /\bbehav/i,
+    /what\s+does/i,
+    /how\s+does/i
+];
+/**
+ * Markers that the answer says what the API DOES — a usage instruction, a runtime effect, a
+ * concrete example, a meaning, a concrete default value or range. Deliberately GENEROUS: every
+ * extra marker here can only SUPPRESS a flag, which is the safe direction for precision.
+ */
+const BEHAVIOURAL = [
+    /\buse\b/i,
+    /\busing\b/i,
+    /\bcall/i,
+    /\bpass(es|ed|ing)?\b/i,
+    /\bimport/i,
+    /\binstantiate/i,
+    /\bprovide[sd]?\b/i,
+    /\binvoke/i,
+    /\bread\b/i,
+    /\bwrite\b/i,
+    /\bexecut/i,
+    /\bsends?\b/i,
+    /\bprepend/i,
+    /\bappend/i,
+    /\bconnect/i,
+    /\bhandle/i,
+    /\bresolves?\s+to\b/i,
+    /\bstarts?\b/i,
+    /\bspread/i,
+    /\bautomatically\b/i,
+    /\breplac/i,
+    /\benabl/i,
+    /\bdisabl/i,
+    /\bwrap/i,
+    /\bperform/i,
+    /\bmanag/i,
+    /\bcontrol/i,
+    /\baccess/i,
+    /\bcreat/i,
+    /\ballow/i,
+    /\bcontain/i,
+    /\bregister/i,
+    /\bmount/i,
+    /\bnavigat/i,
+    /\btrigger/i,
+    /\bappl(y|ies)/i,
+    /\bmeans\b/i,
+    /\brepresents/i,
+    /so\s+pass/i,
+    /for\s+setup/i,
+    /used\s+to/i,
+    /used\s+for/i,
+    /in\s+order\s+to/i,
+    /for\s+\w+ing\b/i,
+    /e\.g\./i,
+    /for\s+example/i,
+    /default\s+of/i,
+    /defaults?\s+to/i,
+    /with\s+a\s+default/i,
+    /from\s+\d+\s+to\s+\d+/i,
+    /when\s+using/i,
+    /you\s+can/i,
+    /you\s+provide/i,
+    /you\s+get/i,
+    /gives?\s+access/i,
+    /to\s+(enable|perform|run|execute|create|manage|handle)\b/i,
+    /\bconfigur/i,
+    /\bschema/i,
+    /\bvalidat/i
+];
+/** Markers that the answer is a declaration/signature restatement. */
+const SIGNATURE = [
+    /\bof\s+type\b/i,
+    /\btakes?\s+(a|an|two|three|one|four)\b/i,
+    /\baccepts?\b/i,
+    /\breturns?\s+(a|an|`|the|void|Promise|<|\w+<)/i,
+    /\bsignature\s+(is|:)/i,
+    /\bextends\b/i,
+    /\binterface\b/i,
+    /\bgeneric\s+type\b/i,
+    /\boverload/i,
+    /\bparameters?:/i,
+    /\bconstructor\s+accepts/i,
+    /declare\s+(const|function)/i
+];
+/** Explicit non-answer the docs child emits when the package cannot answer. */
+const UNCLEAR = /\bunclear\s+from\s+this\s+(package|page)\b/i;
+function firstMatch(text, patterns) {
+    for (const p of patterns) {
+        const m = p.exec(text);
+        if (m)
+            return m[0];
+    }
+    return null;
+}
+/**
+ * Strip signature/declaration fragments so the behavioural scan sees only PROSE.
+ *
+ * A behavioural verb is a signal ONLY when it is a verb in prose ("the base URL is
+ * prepended", "you use X to Y"), NEVER when it is a method/identifier token inside a
+ * declaration. Without this, a bare type-only answer like
+ *   "It has methods route(url, handler) and use(...handlers)."
+ * is wrongly cleared, because `use(...handlers)` matches /\buse\b/ and `handler` matches
+ * /handle/ — the F-3(a) router-fixture shape. So before scanning for behaviour we remove:
+ *   - `name(args)` call fragments, whose args are identifiers, not prose (this is what
+ *     carries the method-name verbs);
+ *   - `declare const|function|module|class|namespace …` declaration lines.
+ * The SIGNATURE gate still runs against the ORIGINAL answer, so stripping never weakens
+ * gate 3 — it only prevents an identifier inside a signature from masquerading as prose.
+ * Deliberately conservative: it does NOT strip `: Type` annotations or backtick spans,
+ * because a colon or backtick often precedes real behavioural prose ("Usage: call …",
+ * "`sql` is prepended …"), and removing those would silently drop behaviour and MANUFACTURE
+ * false positives — worse than the recall gap this fixes.
+ */
+export function proseOf(answer) {
+    return answer
+        .replace(/[\w$][\w$.]*\s*\([^)]*\)/g, ' ')
+        .replace(/\bdeclare\s+(const|function|module|class|namespace)\b[^.\n]*/gi, ' ')
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+}
+/**
+ * Decide whether a pi-worker-docs `answer` to `question` is type-only — a signature/declaration
+ * restatement with no behavioural statement, for a question that needed usage semantics.
+ *
+ * @param answer   the child's <answer> prose (NOT the version banner or the source excerpt).
+ * @param question the query the answer was produced for.
+ */
+export function isTypeOnlyAnswer(answer, question) {
+    const a = answer.trim();
+    const q = question.trim();
+    if (a.length === 0) {
+        return { typeOnly: false, reason: 'empty answer' };
+    }
+    if (UNCLEAR.test(a)) {
+        return {
+            typeOnly: false,
+            reason: 'explicit "unclear" non-answer — routed through the existing unclear/escalation path, not type-only'
+        };
+    }
+    const usage = firstMatch(q, USAGE_INTENT);
+    if (usage === null) {
+        return {
+            typeOnly: false,
+            reason: 'question requests a type/signature/definition, not usage semantics — a signature answer is responsive'
+        };
+    }
+    // Scan for behavioural verbs over the PROSE only — a verb that is really a method name
+    // inside a signature (`use(...handlers)`) must not read as a statement of behaviour.
+    const behavioural = firstMatch(proseOf(a), BEHAVIOURAL);
+    if (behavioural !== null) {
+        return {
+            typeOnly: false,
+            reason: `answer states behaviour/usage (matched "${behavioural}") — not type-only`
+        };
+    }
+    const signature = firstMatch(a, SIGNATURE);
+    if (signature === null) {
+        return {
+            typeOnly: false,
+            reason: 'answer is not a signature/declaration restatement'
+        };
+    }
+    return {
+        typeOnly: true,
+        reason: `usage question answered only with a signature/declaration restatement (matched "${signature}") and no behavioural statement`
+    };
+}

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

@@ -1,5 +1,9 @@
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.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";
+export declare const NOT_COVERED_ANSWER = "not covered by this page";
 export interface FetchRawInput {
     url: string;
     signal?: AbortSignal;
@@ -11,6 +15,22 @@ export interface FetchRawResult {
     title: string;
 }
 export declare function fetchRaw(input: FetchRawInput): Promise<FetchRawResult>;
+/**
+ * How the page content is turned into the child's prompt. Injectable so an A/B harness can
+ * run the shipped strategy against a frozen legacy one in the SAME process, and assert per
+ * rep that the two arms differ by exactly the lever (see scripts/live-fetch-abstention-ab.ts).
+ * Production always uses {@link shippedStrategy}.
+ */
+export interface PromptStrategy {
+    selectContent(markdown: string, requestedUrl: string): SelectedContent;
+    buildPrompt(args: {
+        query: string;
+        url: string;
+        title: string;
+        content: string;
+        section?: string;
+    }): string;
+}
 export interface FetchFocusedInput {
     url: string;
     query: string;
@@ -18,17 +38,47 @@ export interface FetchFocusedInput {
     signal?: AbortSignal;
     fetchAndClean?: typeof defaultFetchAndClean;
     spawn?: SpawnFn;
+    /** Defaults to {@link shippedStrategy}; overridden only by the A/B harness. */
+    strategy?: PromptStrategy;
 }
 export interface FetchFocusedResult {
     answer: string;
     excerpt?: string;
     excerptVerified?: boolean;
+    /**
+     * The page did not cover the asked-about version/topic — a DISTINCT outcome from
+     * `unclear from this page`, so the caller can pick a different URL instead of treating
+     * "page has no answer" and "answer is ambiguous" as the same thing (PROMPT-3 item 3).
+     */
+    coverageMiss: boolean;
+    /** The #fragment slug that was anchored, when the URL carried one and it was located. */
+    anchoredSection?: string;
+    /** Retained evidence for a false `excerptVerified`, so it is diagnosable without re-fetch. */
+    excerptCheck?: ExcerptVerification;
+    /** The prompt actually handed to the child — the A/B asserts surgery against this per rep. */
+    assembledPrompt: string;
     childExitCode: number;
     aborted: boolean;
     stderr: string;
     stdout: string;
 }
 export declare function fetchFocused(input: FetchFocusedInput): Promise<FetchFocusedResult>;
+export interface SelectedContent {
+    content: string;
+    /** The #fragment slug that was anchored, if the URL carried one AND it was located. */
+    section?: string;
+}
+/**
+ * Slice a markdown page down to the section its heading-anchor #fragment names — the deep
+ * link the caller actually asked for — instead of head-truncating the whole page and losing
+ * a section that sits past the head window (PROMPT-3 item 2). Falls back to {@link truncate}
+ * when the URL has no fragment, or the fragment names no heading in THIS content (e.g. the
+ * page changed since the link was captured), so a fragment we cannot honour never degrades a
+ * page we could otherwise read.
+ */
+export declare function selectContent(markdown: string, requestedUrl: string): SelectedContent;
+/** The shipped strategy: fragment-aware selection + the recalibrated prompt. */
+export declare const shippedStrategy: PromptStrategy;
 export declare function formatResultText(parsed: {
     answer: string;
     excerpt?: string;

package/dist/workers/fetch-core.js

@@ -3,11 +3,15 @@ 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, isExcerptInContent, formatResultText as formatResultTextShared } from '../shared/child-output.js';
+import { parseChildOutput, verifyExcerpt, formatResultText as formatResultTextShared } from '../shared/child-output.js';
 const CONTENT_BUDGET = 30_000;
 const HEAD_CHARS = 25_000;
 const TAIL_CHARS = 5_000;
 const TRUNCATION_MARKER = '\n\n[...page continues, truncated...]\n\n';
+/** The exact non-answers the child is instructed to emit, matched at the tool layer. */
+export const UNCLEAR_ANSWER = 'unclear from this page';
+export const NOT_COVERED_ANSWER = 'not covered by this page';
+const NOT_COVERED_RE = /not covered by this page/i;
 const childArgs = () => [...childBaseArgs(), '--no-tools'];
 export async function fetchRaw(input) {
     const fetchAndCleanFn = input.fetchAndClean ?? defaultFetchAndClean;
@@ -17,52 +21,135 @@ 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 cleaned = await fetchAndCleanFn(input.url, { signal: input.signal });
-    const truncated = truncate(cleaned.markdown);
-    const prompt = buildPrompt({
+    // The #fragment is a client-side concern the server never sees, so anchor from the
+    // ORIGINALLY REQUESTED url, not the post-redirect finalUrl (which will have dropped it).
+    const selected = strategy.selectContent(cleaned.markdown, input.url);
+    const prompt = strategy.buildPrompt({
         query: input.query,
         url: cleaned.finalUrl,
         title: cleaned.title,
-        content: truncated
+        content: selected.content,
+        section: selected.section
     });
     const invocation = getPiInvocation(childArgs(), prompt);
     const childResult = await runChild(spawnFn, invocation, input.cwd, input.signal);
+    const base = {
+        anchoredSection: selected.section,
+        assembledPrompt: prompt,
+        stderr: childResult.stderr,
+        stdout: childResult.stdout
+    };
     if (childResult.aborted) {
         return {
             answer: '',
+            coverageMiss: false,
             childExitCode: childResult.exitCode,
             aborted: true,
-            stderr: childResult.stderr,
-            stdout: childResult.stdout
+            ...base
         };
     }
     if (childResult.exitCode !== 0) {
         return {
             answer: '',
+            coverageMiss: false,
             childExitCode: childResult.exitCode,
             aborted: false,
-            stderr: childResult.stderr,
-            stdout: childResult.stdout
+            ...base
         };
     }
     const parsed = parseChildOutput(childResult.stdout);
-    const excerptVerified = parsed.excerpt ? isExcerptInContent(parsed.excerpt, cleaned.markdown) : undefined;
+    // 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;
     return {
         answer: parsed.answer,
         excerpt: parsed.excerpt,
-        excerptVerified,
+        excerptVerified: check?.verified,
+        excerptCheck: check,
+        coverageMiss: NOT_COVERED_RE.test(parsed.answer),
         childExitCode: 0,
         aborted: false,
-        stderr: childResult.stderr,
-        stdout: childResult.stdout
+        ...base
     };
 }
+/** Read the #fragment from a URL. Empty string when there is none. */
+function fragmentOf(url) {
+    const h = url.indexOf('#');
+    return h === -1 ? '' : url.slice(h + 1).trim();
+}
+/**
+ * Slice a markdown page down to the section its heading-anchor #fragment names — the deep
+ * link the caller actually asked for — instead of head-truncating the whole page and losing
+ * a section that sits past the head window (PROMPT-3 item 2). Falls back to {@link truncate}
+ * when the URL has no fragment, or the fragment names no heading in THIS content (e.g. the
+ * page changed since the link was captured), so a fragment we cannot honour never degrades a
+ * page we could otherwise read.
+ */
+export function selectContent(markdown, requestedUrl) {
+    const frag = fragmentOf(requestedUrl);
+    if (frag) {
+        const section = sliceSection(markdown, frag);
+        if (section)
+            return { content: truncate(section), section: frag };
+    }
+    return { content: truncate(markdown) };
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Find the heading whose anchor is `#<frag>` and return that heading's section: from the
+ *  heading line up to the next heading of the same or higher level. Anchors are matched on
+ *  the heading line in both the Docusaurus (`### Title[](#slug "…")`) and GitHub
+ *  (`## [Title](#slug)`) shapes; `#foo` must not match `#foobar`. */
+function sliceSection(markdown, frag) {
+    const lines = markdown.split('\n');
+    const anchor = new RegExp('#' + escapeRegExp(frag) + '(?![a-z0-9-])', 'i');
+    let start = -1;
+    let level = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const h = /^(#{1,6})\s/.exec(lines[i]);
+        if (h && anchor.test(lines[i])) {
+            start = i;
+            level = h[1].length;
+            break;
+        }
+    }
+    if (start === -1)
+        return undefined;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        const h = /^(#{1,6})\s/.exec(lines[i]);
+        if (h && h[1].length <= level) {
+            end = i;
+            break;
+        }
+    }
+    const section = lines.slice(start, end).join('\n').trim();
+    return section.length > 0 ? section : undefined;
+}
 function truncate(md) {
     if (md.length <= CONTENT_BUDGET)
         return md;
     return md.slice(0, HEAD_CHARS) + TRUNCATION_MARKER + md.slice(md.length - TAIL_CHARS);
 }
+/**
+ * The shipped extraction prompt. Rule 5 was recalibrated for PROMPT 3: the pre-change rule
+ * sent the child to `unclear from this page` on ANY ambiguity, which threw away answers that
+ * were on the page (measured: 5 of fetch's 10 failures were deterministic false-"unclear").
+ * It now (5) answers from the content whenever the content supports one, even partially;
+ * (6) reports a page-coverage MISS distinctly, so it is not conflated with ambiguity; and
+ * (7) reserves `unclear` for genuinely-ambiguous content — never for absence, and never as
+ * licence to invent. The abstention was relaxed WITHOUT relaxing rules 1-2 (verbatim
+ * excerpt) — the fabrication guard the A/B scores is untouched.
+ */
 function buildPrompt(args) {
+    const sectionNote = args.section ?
+        `<page-section>The content below has been narrowed to the "#${args.section}" section of\n`
+            + `the page — the section the URL points to. Treat it as the relevant part of the page.</page-section>\n`
+        : '';
     return (`You extract a single piece of information from a web page to answer one question.\n`
         + `\n`
         + `Rules:\n`
@@ -76,16 +163,31 @@ function buildPrompt(args) {
         + `   specifically about page UI.\n`
         + `4. If the page is not in English, write the <answer> in English (translate key\n`
         + `   non-English terms) and keep the original-language text in <excerpt>.\n`
-        + `5. If the answer is unclear, ambiguous, or absent from <page-content>, write\n`
-        + `   exactly: <answer>unclear from this page</answer> and put the closest related\n`
-        + `   text in <excerpt>. Do not guess.\n`
-        + `6. Be terse. One short paragraph in <answer> max.\n`
+        + `5. Answer from <page-content> whenever it supports an answer — INCLUDING a partial\n`
+        + `   one. If the content states only part of what is asked, give the part that IS\n`
+        + `   present and note what is missing; do NOT fall back to "unclear" merely because\n`
+        + `   the coverage is incomplete. When <page-content> plainly contains the asked-for\n`
+        + `   thing (e.g. it lists the methods, fields, or signature asked about), you MUST\n`
+        + `   answer it — "unclear" is the wrong response in that case.\n`
+        + `6. If <page-content> is about a DIFFERENT version, topic, or page than the question\n`
+        + `   asks about — the asked-about thing is simply not on this page — write exactly:\n`
+        + `   <answer>${NOT_COVERED_ANSWER}</answer> and quote in <excerpt> the text that\n`
+        + `   shows what this page IS about. Use this, not "unclear", so the caller can try a\n`
+        + `   different page.\n`
+        + `7. Only when the answer is genuinely present but ambiguous or self-contradictory,\n`
+        + `   write exactly: <answer>${UNCLEAR_ANSWER}</answer> with the closest text in\n`
+        + `   <excerpt>. Never invent an answer or state anything not supported by\n`
+        + `   <page-content>.\n`
+        + `8. Be terse. One short paragraph in <answer> max.\n`
         + `\n`
         + `<question>${args.query}</question>\n`
         + `<url>${args.url}</url>\n`
         + `<page-title>${args.title}</page-title>\n`
+        + sectionNote
         + `<page-content>\n${args.content}\n</page-content>\n`);
 }
+/** The shipped strategy: fragment-aware selection + the recalibrated prompt. */
+export const shippedStrategy = { selectContent, buildPrompt };
 // ─── Thin wrapper: fetch-core formatResultText (no header) ───────────────────
 export function formatResultText(parsed, verified) {
     return formatResultTextShared('', parsed, verified);

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

@@ -1,5 +1,7 @@
 import { type ContextSnapshot, type SpawnFn } from '../shared/child-process.js';
 import { type LoopHit } from '../task/loop-detector.js';
+/** True when a tool call retrieves content an APIS entry could be grounded in. */
+export declare function isGroundingRetrieval(toolName: string): boolean;
 export interface RunWorkerInput {
     prompt: string;
     cwd: string;
@@ -102,6 +104,15 @@ export interface RunWorkerResult {
      * elapsed when the child never produced output.
      */
     workMs: number;
+    /**
+     * How many GROUNDING retrieval tool calls the FINAL attempt made — the calls
+     * that returned content an APIS entry could be cited from (see
+     * isGroundingRetrieval; `ls`/`find` excluded on purpose). Counted over the
+     * attempt that produced `text`, not summed across restarts (a restarted
+     * attempt discards its predecessor's calls along with its text). Zero here on
+     * a non-empty section means every symbol in it came from parametric memory.
+     */
+    groundingRetrievalCount: number;
     /**
      * Set when the worker exhausted its re-prompts still leaking a tool call as
      * text (wrong dialect, never executed). The caller must treat this as a