@mjasnikovs/pi-task 0.18.49 → 0.18.50

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

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

@@ -15,6 +15,29 @@ import { streamStallHint } from '../shared/stream-watchdog.js';
 // model starts producing — making waitMs the real queue/cold-start cost and
 // workMs the real generation+tool-call cost.
 const DEFAULT_TOOLS = 'read,grep,find,ls';
+/**
+ * Tool calls that can GROUND an APIS claim — i.e. return content a signature or
+ * command could be cited from. `pi-worker-docs` (the primary), `read` and `grep`
+ * (project source), and the web escalations `pi-worker-search`/`pi-worker-fetch`.
+ *
+ * `ls` and `find` are deliberately EXCLUDED: they return file/directory NAMES,
+ * and APIS owns symbols by name only, never paths (RESEARCH_APIS_PROMPT). Bare
+ * enumeration cannot verify a signature, so a worker that fabricates its section
+ * from memory does not launder itself grounded by calling `ls` once. That
+ * exclusion is the anti-gaming property of any gate built on this count: "one
+ * trivial `ls` then fabricate the rest" leaves groundingRetrievalCount at 0.
+ */
+const GROUNDING_RETRIEVAL_TOOLS = new Set([
+    'pi-worker-docs',
+    'read',
+    'grep',
+    'pi-worker-search',
+    'pi-worker-fetch'
+]);
+/** True when a tool call retrieves content an APIS entry could be grounded in. */
+export function isGroundingRetrieval(toolName) {
+    return GROUNDING_RETRIEVAL_TOOLS.has(toolName);
+}
 /**
  * Hard wall-clock bound on a single research worker run (one spawn). The
  * exact-match LoopDetector only catches *identical* repeated tool calls; a model
@@ -190,6 +213,10 @@ export async function runWorker(input) {
         // SIGTERM that kill produces would surface as a bare non-zero exit the
         // caller couldn't distinguish from a crash.
         let loopHit;
+        // Reset EACH attempt: on a restart the previous attempt's calls are
+        // discarded with its text, so the count must describe only the attempt
+        // whose text this call returns.
+        let groundingRetrievalCount = 0;
         const timeout = workerTimeout(input.signal, timeoutMs);
         // Per-tool-call watchdog for this attempt (null when off). Its abort is
         // OR'd with the worker timeout / external cancel into the child's signal.
@@ -214,6 +241,8 @@ export async function runWorker(input) {
                 onFirstByte: () => (tFirstByte = Date.now()),
                 onToolCall: call => {
                     cmdWatch?.onStart(call);
+                    if (isGroundingRetrieval(call.name))
+                        groundingRetrievalCount++;
                     if (!loopDetector)
                         return null;
                     const hit = loopDetector.record(call);
@@ -302,6 +331,7 @@ export async function runWorker(input) {
             aborted: result.aborted,
             waitMs,
             workMs,
+            groundingRetrievalCount,
             ...(leaked ? { leakedToolCall: leaked } : {}),
             ...(loopHit ? { loopHit } : {}),
             ...(timedOut ? { timedOut: true } : {}),

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

@@ -5,6 +5,15 @@ 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';
+/**
+ * Pull `@see {@link https://…}` pointers out of retrieved .d.ts/README text.
+ *
+ * F-2(d): the answer to a type-only lookup usually is not in the package at all — it lives
+ * at the `@see` URL that the very excerpt being returned already carries. In run 15,
+ * hono.dev appeared in cache values ONLY inside these JSDoc links, and was never fetched.
+ * Surfacing the link is therefore free: the pointer is already in hand.
+ */
+export declare function extractSeeUrls(content: string): string[];
 /**
  * The package NAME a module specifier belongs to — `hono/client` → `hono`,
  * `@scope/name/sub` → `@scope/name`. The cache stores this (not the raw specifier) as an

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

@@ -1,3 +1,4 @@
+import { spawn as defaultSpawn } from 'node:child_process';
 import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
 import { openCache as defaultOpenCache } from './docs-cache.js';
@@ -9,6 +10,8 @@ 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 { 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';
 const childArgs = () => [...childBaseArgs(), '--no-tools'];
@@ -21,6 +24,25 @@ const Params = Type.Object({
         description: 'What to extract from the docs. The child pi reads ranked chunks and returns ONLY content answering this.'
     })
 });
+/**
+ * Pull `@see {@link https://…}` pointers out of retrieved .d.ts/README text.
+ *
+ * F-2(d): the answer to a type-only lookup usually is not in the package at all — it lives
+ * at the `@see` URL that the very excerpt being returned already carries. In run 15,
+ * hono.dev appeared in cache values ONLY inside these JSDoc links, and was never fetched.
+ * Surfacing the link is therefore free: the pointer is already in hand.
+ */
+export function extractSeeUrls(content) {
+    const out = [];
+    const re = /@see\s*\{?\s*@?link\s+(https?:\/\/[^}\s)]+)/gi;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        const url = m[1].replace(/[.,;]+$/, '');
+        if (!out.includes(url))
+            out.push(url);
+    }
+    return out;
+}
 /**
  * The package NAME a module specifier belongs to — `hono/client` → `hono`,
  * `@scope/name/sub` → `@scope/name`. The cache stores this (not the raw specifier) as an
@@ -72,10 +94,13 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             + '- You need docs for a specific newer version than what is installed — use pi-worker-fetch on the upstream docs site',
         parameters: Params,
         async run(params, signal, ctx) {
-            const spawn = internals.spawn
-                ?? (globalThis.Bun !== undefined ?
-                    globalThis.Bun.spawn
-                    : (await import('node:child_process')).spawn);
+            // Always node:child_process spawn (matching fetch-core and every other
+            // worker). The former globalThis.Bun branch called Bun.spawn — whose signature
+            // is Bun.spawn([cmd, ...args], opts), NOT the node (cmd, args, opts) that
+            // runChild/SpawnFn require — so it threw "cmd must be an array" whenever it ran.
+            // 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;
             // ── Project source lookup ───────────────────────────────────────
             if (params.module === '.') {
                 const openCache = internals.openCache ?? defaultOpenCache;
@@ -138,6 +163,27 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                     entryDts: null,
                     readme: null
                 }, parsed, 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
+                // the first live diagnostic rep. With only the package path recorded, "the
+                // last docs answer before the worker stopped" was unanswerable: the sink's
+                // last row was routinely not the worker's last answer.
+                //
+                // `typeOnly` is recorded FALSE with an explicit reason rather than by running
+                // the detector: this path never applies it, and the record must say what the
+                // shipped tool decided, not what it would have decided. Inventing a verdict
+                // here would let a firing-rate computed off this sink count answers the lever
+                // does not reach.
+                logDocsAnswer({
+                    module: params.module,
+                    query: params.query,
+                    answer: parsed.answer,
+                    typeOnly: false,
+                    reason: 'project-source lookup — the type-only detector is not applied here',
+                    excerptVerified: verified,
+                    toolText: text
+                });
                 return {
                     text,
                     details: {
@@ -233,13 +279,66 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             }
             const parsed = parseChildOutput(child.stdout);
             const verified = parsed.excerpt ? isExcerptInContent(parsed.excerpt, concatenated) : undefined;
-            const text = versionBanner + npmHeader + formatResultText(pkg, parsed, verified);
+            const body = formatResultText(pkg, parsed, 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
+            // stops — and worker:context then fills the semantic gap from memory (F-1).
+            // Measured: 14 of 17 live reps terminated on exactly this shape.
+            //
+            // The retrieved type is KEPT (it is real and useful) and an UNANSWERED banner
+            // is prepended, naming the gap and — when the excerpt carries one — the `@see`
+            // URL that actually documents the semantics. That pointer is free: F-2(d) found
+            // 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);
+            let text = versionBanner + npmHeader + body;
+            if (typeOnly.typeOnly) {
+                const seeUrls = extractSeeUrls(concatenated);
+                text =
+                    versionBanner
+                        + npmHeader
+                        + 'UNANSWERED — TYPE-ONLY: the package gave a declaration, not the '
+                        + 'usage semantics this question needs. A signature says what the '
+                        + 'parameter IS, not what it MEANS. Do NOT answer from memory and do '
+                        + 'NOT treat the type below as the answer.\n'
+                        + (seeUrls.length > 0 ?
+                            `NEXT STEP: the retrieved excerpt itself cites documentation — `
+                                + `fetch ${seeUrls[0]} (pi-worker-fetch) and re-ask this same `
+                                + `question.\n`
+                            : 'NEXT STEP: use pi-worker-search / pi-worker-fetch for the official '
+                                + 'documentation of this API, then re-ask this same question.\n')
+                        + '\nThe declaration that WAS retrieved (context only, not the answer):\n'
+                        + body;
+            }
+            // STAGE 1 INSTRUMENTATION — off unless PI_TASK_TYPEONLY_LOG names a sink, and
+            // side-effect only: nothing below reads it, and every failure inside is
+            // swallowed. It records EVERY answer, flagged or not, because the open question
+            // is a RATE — how often this fires — and a log of firings alone has no
+            // denominator. See typeonly-log.ts.
+            //
+            // It sits AFTER `text` is final (it used to sit above `text`'s first assignment)
+            // so the record carries what the worker was actually handed, banner and cited
+            // excerpt included, not just the child's prose. Purely a move: logDocsAnswer
+            // returns nothing and nothing between the two positions reads it, so the tool's
+            // behaviour and its return value are unchanged.
+            logDocsAnswer({
+                module: params.module,
+                query: params.query,
+                answer: parsed.answer,
+                typeOnly: typeOnly.typeOnly,
+                reason: typeOnly.reason,
+                excerptVerified: verified,
+                toolText: text
+            });
             return {
                 text,
                 details: {
                     ...baseDetails,
                     childExitCode: 0,
-                    excerptVerified: verified
+                    excerptVerified: verified,
+                    ...(typeOnly.typeOnly ? { typeOnly: true } : {})
                 }
             };
         },
@@ -268,6 +367,19 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         // Only a completed lookup (child exited 0) is a real answer; not-installed,
         // no-chunks, resolve/cache errors, and aborts omit childExitCode:0 and fall
         // through to a live retry next time.
-        cacheable: d => d.childExitCode === 0
+        //
+        // F-2(e): process health is NOT answer quality. A child that ran fine and answered
+        // "unclear from this package" exits 0, so the NON-ANSWER was memoised and re-served
+        // as a cache hit to every later sibling task — 52 of run 15's cached entries were
+        // "unclear" with hitCache true. One dead end, paid for many times, and escalation
+        // could never re-fire because the miss never recurred. So a non-answer is now never
+        // stored: the next task that asks pays for a real lookup and can escalate.
+        //
+        // `text` is supplied by makeWorkerTool (shared.ts) alongside details, so the
+        // content check needs no new plumbing.
+        cacheable: (d, text) => d.childExitCode === 0
+            && d.typeOnly !== true
+            && d.excerptVerified !== false
+            && !/unclear from this package/i.test(text)
     });
 }

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

@@ -59,7 +59,9 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                         childExitCode: 0,
                         answer: result.answer,
                         excerpt: result.excerpt,
-                        excerptVerified: result.excerptVerified
+                        excerptVerified: result.excerptVerified,
+                        coverageMiss: result.coverageMiss,
+                        anchoredSection: result.anchoredSection
                     }
                 };
             }

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

@@ -0,0 +1,45 @@
+/** 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. */
+export interface TypeOnlyLogRecord {
+    /** ISO timestamp — lets records be attributed to a rep/phase window after the fact. */
+    at: string;
+    /** The `module` param: a package specifier, or "." for project source. */
+    module: string;
+    /** The query verbatim as the worker asked it (NOT the lowercased cache key). */
+    query: string;
+    /** The child's `<answer>` prose — retained so every counter can be re-scored offline. */
+    answer: string;
+    /** The shipped detector's verdict for (answer, query). */
+    typeOnly: boolean;
+    /** The detector's reason string — names which gate decided, for auditing precision. */
+    reason: string;
+    /** True when the answer is the explicit "unclear from this package" non-answer. */
+    unclear: boolean;
+    /** child-output's excerpt check; undefined when the child cited no excerpt. */
+    excerptVerified?: boolean;
+    /**
+     * 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
+     * field existed still parse.
+     *
+     * WHY IT IS NOT REDUNDANT WITH `answer`. `answer` is the child's prose only. The worker
+     * receives strictly more than that, and the extra part is where the SYMBOL NAMES live: the
+     * cited `.d.ts` excerpt. Asking "did the worker write an APIS entry it had actually looked
+     * up, or one it produced from memory" is a substring question against what the worker was
+     * GIVEN, and answering it off `answer` alone would score a symbol that appeared verbatim in
+     * the retrieved declaration as ungrounded. That would inflate the very counter it is meant
+     * to measure. Recording the full text makes the grounding test conservative in the
+     * direction that cannot manufacture a finding.
+     */
+    toolText?: string;
+}
+/**
+ * Append one record to the JSONL sink named by `PI_TASK_TYPEONLY_LOG`, if set.
+ *
+ * @param rec everything but `at` and `unclear`, which are derived here so every call site
+ *            stamps them identically.
+ */
+export declare function logDocsAnswer(rec: Omit<TypeOnlyLogRecord, 'at' | 'unclear'>, getEnv?: (k: string) => string | undefined): void;
+/** Parse a sink written by {@link logDocsAnswer}; malformed lines are skipped, not thrown. */
+export declare function readTypeOnlyLog(text: string): TypeOnlyLogRecord[];

package/dist/workers/typeonly-log.js

@@ -0,0 +1,88 @@
+/**
+ * STAGE 1 INSTRUMENTATION for F-2 / PROMPT 2 — firing-rate observability, no behaviour.
+ *
+ * WHY THIS EXISTS. PROMPT 2's live A/B measured 82% baseline vs 91% treatment, p = 0.88,
+ * and was written off as "the lever does not work". It was a broken EXPERIMENT, and it was
+ * broken for a reason this module fixes: the metric counted ALL research terminations while
+ * the lever touches only TYPE-ONLY answers, and nothing anywhere recorded how often a
+ * type-only answer actually occurs. The causal claim "workers stop BECAUSE of type-only
+ * answers" was asserted from one static corpus (1 flag in 150 recorded answers, 0.7%) and
+ * never measured live. You cannot size an arm, pick a metric, or decide whether the lever is
+ * a population fix or a single-case guard without that firing rate.
+ *
+ * WHAT IT DOES. When `PI_TASK_TYPEONLY_LOG` names a file, every pi-worker-docs answer — not
+ * only the flagged ones — appends one JSON line there. Denominator and numerator both, from
+ * the same channel, so a rate is computable rather than inferable. With the variable unset
+ * this is a no-op and nothing is written.
+ *
+ * MECHANICAL, NOT SELF-REPORT. The record is written at the TOOL layer from the verdict the
+ * shipped detector just returned, next to the same `details` the caller receives. No model is
+ * asked whether it thought the answer was a type signature.
+ *
+ * BEHAVIOUR-NEUTRALITY IS THE WHOLE POINT — this lands in a stage that forbids src/ behaviour
+ * change, so:
+ *   - it is called for its side effect only; nothing reads its return value;
+ *   - every failure is swallowed (a full disk or an unwritable path must not turn a working
+ *     docs lookup into an error — instrumentation that can break the thing it measures is
+ *     worse than no instrumentation);
+ *   - it appends synchronously, because the process that writes it (a pi child running the
+ *     docs extension) can exit immediately after the tool returns and a queued async write
+ *     would be lost.
+ *
+ * THE FULL ANSWER TEXT IS RETAINED, deliberately. Run 15's audit could not decide F-3(f) —
+ * whether an `excerptVerified === false` was fabrication or a normaliser gap — because the
+ * text it judged was kept nowhere. The same hole would make every stability question here
+ * unanswerable: whether a question is type-only in EVERY rep or churns between identical
+ * reps can only be settled by re-scoring the recorded answers. Cheap to keep, impossible to
+ * reconstruct later.
+ */
+import * as fs from 'node:fs';
+/** Env var naming the JSONL sink. Unset (or empty) ⇒ instrumentation is entirely off. */
+export const TYPEONLY_LOG_ENV = 'PI_TASK_TYPEONLY_LOG';
+/**
+ * The honest non-answer, in BOTH wordings the tool can emit. A package lookup is told to
+ * write "unclear from this package" (docs-core.ts:622); a project-source lookup is told
+ * "unclear from this project" (docs-project.ts:310). Matching only the first silently scored
+ * every project-source abstention as a valid answer — and project-source is the MAJORITY of
+ * what worker:apis asks (13 of 17 calls in run 15's fatal task), so that one missing word
+ * would have put the wrong denominator under the whole termination diagnostic.
+ */
+const UNCLEAR = /unclear from this (package|project)/i;
+/**
+ * Append one record to the JSONL sink named by `PI_TASK_TYPEONLY_LOG`, if set.
+ *
+ * @param rec everything but `at` and `unclear`, which are derived here so every call site
+ *            stamps them identically.
+ */
+export function logDocsAnswer(rec, getEnv = k => process.env[k]) {
+    const sink = getEnv(TYPEONLY_LOG_ENV);
+    if (!sink || sink.trim().length === 0)
+        return;
+    const full = {
+        at: new Date().toISOString(),
+        ...rec,
+        unclear: UNCLEAR.test(rec.answer)
+    };
+    try {
+        fs.appendFileSync(sink, `${JSON.stringify(full)}\n`, 'utf8');
+    }
+    catch {
+        // Deliberately silent. This is a measurement side-channel; a docs lookup that
+        // succeeded must not be reported as failed because the sink was unwritable.
+    }
+}
+/** Parse a sink written by {@link logDocsAnswer}; malformed lines are skipped, not thrown. */
+export function readTypeOnlyLog(text) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // A truncated final line is normal when a process is killed mid-append.
+        }
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.49",
+    "version": "0.18.50",
     "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",