@mjasnikovs/pi-task 0.18.49 → 0.18.51

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.51",
     "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",