@mjasnikovs/pi-task 0.38.10 → 0.38.12

package/dist/task/verify-work.js

@@ -122,15 +122,21 @@ export function extractSpecForVerification(taskBody) {
  */
 function probeAdapter(row) {
     const { key, stage, block, ruleId, rule } = row;
+    const source = row.source
+        ?? ((deps) => 
+        // One channel per key, so the bag's entry for this key IS this row's
+        // thunk; the cast only re-narrows what the mapped type already says.
+        deps.probes?.[key]);
     return {
         key,
+        bound: !row.source,
         stage,
         block,
         ruleId,
         rule,
         run: async (deps, onStage) => {
-            const probe = row.dep(deps);
-            // Probes are INDEPENDENTLY OPTIONAL: an absent dep is "skipped", and a
+            const probe = source(deps);
+            // Probes are INDEPENDENTLY OPTIONAL: an absent probe is "skipped", and a
             // probe that throws degrades to its own empty value — it is a sharpener,
             // never a blocker, so a fault in one can neither block the gate nor
             // leak into another row.
@@ -165,7 +171,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'substitution',
         stage: 'substitution probe',
-        dep: deps => deps.probe,
         empty: [],
         findings: asLines,
         ruleId: '3b',
@@ -198,7 +203,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'prohibition',
         stage: 'prohibition probe',
-        dep: deps => deps.prohibitionProbe,
         empty: [],
         findings: asLines,
         ruleId: '4b',
@@ -238,7 +242,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'crossTaskDeletion',
         stage: 'cross-task deletion probe',
-        dep: deps => deps.crossTaskDeletionProbe,
         empty: [],
         findings: crossTaskDeletionVerifyFindings,
         ruleId: '4d',
@@ -277,7 +280,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'probeGaming',
         stage: 'probe-gaming probe',
-        dep: deps => deps.probeGamingProbe,
         empty: [],
         findings: asLines,
         ruleId: '4c',
@@ -322,7 +324,7 @@ const PROBE_ADAPTERS = [
      */
     probeAdapter({
         key: 'skipEscape',
-        dep: deps => () => Promise.resolve(skipEscapeVerifyFindings(findSkipEscapes(deps.spec ?? ''))),
+        source: deps => () => Promise.resolve(skipEscapeVerifyFindings(findSkipEscapes(deps.spec ?? ''))),
         empty: [],
         findings: asLines,
         ruleId: '5c',
@@ -349,7 +351,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'foreignPath',
         stage: 'foreign-path probe',
-        dep: deps => deps.foreignPathProbe,
         empty: [],
         findings: asLines,
         ruleId: '4e',
@@ -392,7 +393,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'scriptEscape',
         stage: 'script-escape probe',
-        dep: deps => deps.scriptEscapeProbe,
         empty: [],
         findings: asLines,
         ruleId: '4f',
@@ -431,7 +431,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'runnerGlob',
         stage: 'runner-glob probe',
-        dep: deps => deps.runnerGlobProbe,
         empty: [],
         findings: asLines,
         ruleId: '4g',
@@ -466,7 +465,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'testAssembly',
         stage: 'test-assembly probe',
-        dep: deps => deps.testAssemblyProbe,
         empty: [],
         findings: asLines,
         ruleId: '3f',
@@ -487,6 +485,12 @@ const PROBE_ADAPTERS = [
         ]
     })
 ];
+/**
+ * The channels a caller must bind — the table rows that read `deps.probes`, in
+ * table order. Exported so the one binder (gate-deps' `buildVerifyProbes`) can be
+ * checked against the table rather than against a hand-kept list.
+ */
+export const BOUND_PROBE_KEYS = PROBE_ADAPTERS.filter(a => a.bound).map(a => a.key);
 /**
  * Build the verification child's prompt. Kept pure so the wording is unit-tested
  * without spawning pi. The contract: run the spec's own verification in the real

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

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

package/dist/workers/docs-core.js

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

package/dist/workers/docs-project.js

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

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

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

package/dist/workers/docs-resolve.js

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

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

@@ -12,4 +12,17 @@ export interface RetrieveOptions {
     limit?: number;
     contentBudget?: number;
 }
+/**
+ * How many chunks a retrieval returns, per corpus.
+ *
+ * The two values differ and always have; this is the first place they sit side by
+ * side, and no comment in the history explains WHY an npm package gets 8 and
+ * project source gets 50. Recorded as-is rather than harmonised: changing either is
+ * a retrieval-policy change with its own A/B, not a tidy-up. Before this they were
+ * three declarations across three files, so the divergence was invisible.
+ */
+export declare const PACKAGE_RETRIEVE_LIMIT = 8;
+export declare const PROJECT_RETRIEVE_LIMIT = 50;
+/** Character budget for the assembled chunk text. The same for both corpora. */
+export declare const RETRIEVE_CONTENT_BUDGET = 24000;
 export declare function retrieveChunks(cache: CacheHandle, opts: RetrieveOptions): RetrievedChunk[];

package/dist/workers/docs-retrieve.js

@@ -1,5 +1,20 @@
-const DEFAULT_LIMIT = 50;
-const DEFAULT_BUDGET = 24_000;
+/**
+ * How many chunks a retrieval returns, per corpus.
+ *
+ * The two values differ and always have; this is the first place they sit side by
+ * side, and no comment in the history explains WHY an npm package gets 8 and
+ * project source gets 50. Recorded as-is rather than harmonised: changing either is
+ * a retrieval-policy change with its own A/B, not a tidy-up. Before this they were
+ * three declarations across three files, so the divergence was invisible.
+ */
+export const PACKAGE_RETRIEVE_LIMIT = 8;
+export const PROJECT_RETRIEVE_LIMIT = 50;
+/** Character budget for the assembled chunk text. The same for both corpora. */
+export const RETRIEVE_CONTENT_BUDGET = 24_000;
+// Both callers always pass `limit`/`contentBudget` explicitly, so these defaults are
+// only a backstop for a third caller that does not.
+const DEFAULT_LIMIT = PROJECT_RETRIEVE_LIMIT;
+const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
 const MIN_TOKEN_LEN = 2;
 const FALLBACK_DTS_CHARS = 12_000;
 const FALLBACK_README_CHARS = 4_000;

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

@@ -104,7 +104,3 @@ export interface SelectedContent {
 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;
-}, verified: boolean | undefined): string;

package/dist/workers/fetch-core.js

@@ -1,7 +1,6 @@
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { abstentionSentence } from './abstention.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;
@@ -243,7 +242,5 @@ function buildPrompt(args) {
 }
 /** 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);
-}
+// A fetch answer carries no package header, so the shared formatter is bound with an
+// empty one at the single call site rather than behind a wrapper of its own.

package/dist/workers/phantom-imports.d.ts

@@ -26,14 +26,14 @@ export interface RuntimeImportVerdict {
  */
 export declare function classifyRuntimeImport(spec: string, runtime: string, sub: string, typeText: string): RuntimeImportVerdict;
 /** Default loader: resolve the runtime's installed types and read their .d.ts. */
-export declare function loadRuntimeTypeText(runtime: string, cwd: string): string | null;
+export declare function loadRuntimeTypeText(runtime: string, cwd: string): Promise<string | null>;
 /**
  * Scan `text` for runtime-namespace specifiers and return the ones the installed
  * types do not declare. `loadText` is injectable for tests; in production it reads
  * the runtime's type package. A runtime whose types can't be loaded is skipped
  * (we never flag what we can't verify), so this is silent when types are absent.
  */
-export declare function findPhantomImports(text: string, cwd: string, loadText?: (runtime: string, cwd: string) => string | null): PhantomImport[];
+export declare function findPhantomImports(text: string, cwd: string, loadText?: (runtime: string, cwd: string) => string | null | Promise<string | null>): Promise<PhantomImport[]>;
 /** Render flagged phantoms as an authoritative research section, or '' if none. */
 export declare function formatApiCorrections(phantoms: PhantomImport[]): string;
 /**
@@ -54,7 +54,7 @@ export declare function formatApiOverrideBanner(phantoms: PhantomImport[]): stri
  * Unreadable mentions are skipped; silent when types are absent or nothing is flagged.
  * Drives the impl-handoff override banner (Layer B).
  */
-export declare function findDeliveryPhantoms(spec: string, cwd: string): PhantomImport[];
+export declare function findDeliveryPhantoms(spec: string, cwd: string): Promise<PhantomImport[]>;
 /**
  * Subtractively rewrite every flagged phantom specifier in `text` to the canonical
  * import the installed types prove, so NO affirmative occurrence of the non-existent

package/dist/workers/phantom-imports.js

@@ -13,7 +13,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { resolvePackage, splitRuntimeNamespace, detectTypesRedirect, typesPackageName, hasTypeFiles, isDtsFile, ResolveError } from './docs-resolve.js';
+import { resolvePackage, splitRuntimeNamespace, hasTypeFiles, isDtsFile, resolveTypeSource, ResolveError } from './docs-resolve.js';
 // Runtime builtin specifiers as they appear in prose/code: `bun:sql`,
 // `node:fs/promises`. Bounded to the runtimes splitRuntimeNamespace accepts.
 const SPEC_RE = /\b(?:bun|node|deno):[a-z0-9][a-z0-9/_-]*/gi;
@@ -67,40 +67,27 @@ function suggestionFor(v, runtime) {
     return (`\`${v.spec}\` is NOT a real module.${list} Import the needed symbol from `
         + `"${runtime}" or verify the correct specifier with pi-worker-docs; do not declare a module for it.`);
 }
-/** Sync resolution of a runtime to the package that actually holds its type
- *  declarations (bun -> @types/bun -> bun-types), bounded to a few hops. No
- *  auto-install: a runtime whose types aren't installed simply can't be verified
- *  (returns null), so we never flag what we can't prove. */
-function resolveRuntimeTypesRoot(runtime, cwd) {
-    let cur;
+/** The phantom-import checker's adapter over the shared redirect walk: hops resolve
+ *  SYNCHRONOUSLY and never install. A runtime whose types aren't on disk simply
+ *  can't be verified (null), so we never flag what we can't prove. */
+async function resolveRuntimeTypesRoot(runtime, cwd) {
+    let start;
     try {
-        cur = resolvePackage(runtime, cwd);
+        start = resolvePackage(runtime, cwd);
     }
     catch (err) {
         if (err instanceof ResolveError)
             return null;
         throw err;
     }
-    const visited = new Set([cur.name, runtime]);
-    for (let hop = 0; hop < 3; hop++) {
-        let next = detectTypesRedirect(cur);
-        if (next && visited.has(next))
-            next = null;
-        if (!next && !hasTypeFiles(cur.root)) {
-            const types = typesPackageName(cur.name);
-            if (types && !visited.has(types))
-                next = types;
-        }
-        if (!next)
-            break;
-        visited.add(next);
+    const cur = await resolveTypeSource(start, runtime, next => {
         try {
-            cur = resolvePackage(next, cwd);
+            return Promise.resolve(resolvePackage(next, cwd));
         }
         catch {
-            break;
+            return Promise.resolve(null);
         }
-    }
+    });
     return hasTypeFiles(cur.root) ? cur.root : null;
 }
 const MAX_TYPE_BYTES = 4_000_000;
@@ -141,8 +128,8 @@ function readRuntimeTypeText(root) {
     return parts.join('\n');
 }
 /** Default loader: resolve the runtime's installed types and read their .d.ts. */
-export function loadRuntimeTypeText(runtime, cwd) {
-    const root = resolveRuntimeTypesRoot(runtime, cwd);
+export async function loadRuntimeTypeText(runtime, cwd) {
+    const root = await resolveRuntimeTypesRoot(runtime, cwd);
     if (!root)
         return null;
     const text = readRuntimeTypeText(root);
@@ -154,7 +141,7 @@ export function loadRuntimeTypeText(runtime, cwd) {
  * the runtime's type package. A runtime whose types can't be loaded is skipped
  * (we never flag what we can't verify), so this is silent when types are absent.
  */
-export function findPhantomImports(text, cwd, loadText = loadRuntimeTypeText) {
+export async function findPhantomImports(text, cwd, loadText = loadRuntimeTypeText) {
     const out = [];
     const typeTextByRuntime = new Map();
     for (const spec of extractRuntimeSpecifiers(text)) {
@@ -162,7 +149,7 @@ export function findPhantomImports(text, cwd, loadText = loadRuntimeTypeText) {
         if (!ns)
             continue;
         if (!typeTextByRuntime.has(ns.runtime)) {
-            typeTextByRuntime.set(ns.runtime, loadText(ns.runtime, cwd));
+            typeTextByRuntime.set(ns.runtime, await loadText(ns.runtime, cwd));
         }
         const typeText = typeTextByRuntime.get(ns.runtime);
         if (!typeText)
@@ -219,7 +206,7 @@ const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
  * Unreadable mentions are skipped; silent when types are absent or nothing is flagged.
  * Drives the impl-handoff override banner (Layer B).
  */
-export function findDeliveryPhantoms(spec, cwd) {
+export async function findDeliveryPhantoms(spec, cwd) {
     let text = spec;
     const seen = new Set();
     for (const m of spec.matchAll(MENTION_RE)) {

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

@@ -5,6 +5,32 @@ 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';
+interface DocsDetails {
+    version?: string;
+    hitCache?: boolean;
+    chunksRetrieved?: number;
+    excerptVerified?: boolean;
+    childExitCode?: number;
+    indexingMs?: number;
+    indexedFiles?: number;
+    resolveError?: 'not_installed' | 'invalid_name';
+    cacheError?: string;
+    aborted?: boolean;
+    autoInstalled?: boolean;
+    installError?: string;
+    npmLatest?: string;
+    npmPublishedAt?: string;
+    versionSource?: 'declared-range' | 'npm-latest';
+    declaredRange?: string;
+    /**
+     * The answer restated a declaration for a question that needed usage semantics, so it
+     * is UNANSWERED (F-2). Set by isTypeOnlyAnswer; read by `cacheable` so a non-answer is
+     * never memoised and re-served to a later sibling task.
+     */
+    typeOnly?: boolean;
+    /** The 5B CAP arm refused this call: the attempt's project-lookup budget is spent. */
+    budgetSpent?: boolean;
+}
 /**
  * Pull `@see {@link https://…}` pointers out of retrieved .d.ts/README text.
  *
@@ -30,3 +56,26 @@ export interface PiWorkerDocsInternals {
     npmVersionLookup?: typeof defaultNpmVersionLookup;
 }
 export declare function registerPiWorkerDocs(pi: ExtensionAPI, internals?: PiWorkerDocsInternals): void;
+/**
+ * The F-2(e) cache rule for the docs channel, as a NAMED export rather than an
+ * anonymous property of an adapter literal.
+ *
+ * It was reachable only through `registerTool → execute()`, so
+ * pi-worker-docs-typeonly.test.ts gave up and hand-retyped it under a
+ * "keep in sync" comment — six tests asserting against a copy that a change to the
+ * shipped rule would leave green. That is the same drift class the rule itself
+ * exists to prevent: four regexes matching three phrasings, documented at length in
+ * abstention.ts, which cost a real bug.
+ */
+export declare function docsCacheable(d: Pick<DocsDetails, 'childExitCode' | 'typeOnly' | 'excerptVerified'>, text: string): boolean;
+/** The docs cache key: a package's answer is per (module, question). A project-source
+ *  `.` lookup is never cached — the working tree mutates as tasks implement. */
+export declare function docsCacheKey(params: {
+    module: string;
+    query: string;
+}): string | null;
+/** Package provenance for per-entry resume invalidation. */
+export declare function docsCachePkg(params: {
+    module: string;
+}): string | undefined;
+export {};

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

@@ -3,7 +3,8 @@ import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
-import { docsRaw, formatResultText, packageHeader, buildPrompt, buildVersionBanner } from './docs-core.js';
+import { formatResultText } from '../shared/child-output.js';
+import { docsRaw, packageHeader, buildPrompt, buildVersionBanner } from './docs-core.js';
 import { formatNpmVersionSection } from './npm-version.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { makeWorkerTool } from './shared.js';
@@ -374,15 +375,13 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         // version do not change within a run). A project-source `.` lookup is NOT cached:
         // the working tree mutates as tasks implement, so its answer can go stale mid-run
         // (the docs SQLite index already keys those on file mtime).
-        cacheKey: params => params.module === '.' ?
-            null
-            : `${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`,
+        cacheKey: docsCacheKey,
         // Package provenance for per-entry resume invalidation: a docs digest describes
         // one package at one declared version, so a resume drops it only when THAT
         // package moves — an unrelated install no longer discards it. Package names are
         // matched against package.json verbatim (npm names are case-sensitive), unlike
         // the cache key, which normalises for phrasing collisions.
-        cachePkg: params => (params.module === '.' ? undefined : packageRootOf(params.module)),
+        cachePkg: docsCachePkg,
         // 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.
@@ -396,9 +395,34 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         //
         // `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
-            && !isAbstention(text)
+        cacheable: docsCacheable
     });
 }
+/**
+ * The F-2(e) cache rule for the docs channel, as a NAMED export rather than an
+ * anonymous property of an adapter literal.
+ *
+ * It was reachable only through `registerTool → execute()`, so
+ * pi-worker-docs-typeonly.test.ts gave up and hand-retyped it under a
+ * "keep in sync" comment — six tests asserting against a copy that a change to the
+ * shipped rule would leave green. That is the same drift class the rule itself
+ * exists to prevent: four regexes matching three phrasings, documented at length in
+ * abstention.ts, which cost a real bug.
+ */
+export function docsCacheable(d, text) {
+    return (d.childExitCode === 0
+        && d.typeOnly !== true
+        && d.excerptVerified !== false
+        && !isAbstention(text));
+}
+/** The docs cache key: a package's answer is per (module, question). A project-source
+ *  `.` lookup is never cached — the working tree mutates as tasks implement. */
+export function docsCacheKey(params) {
+    return params.module === '.' ?
+        null
+        : `${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`;
+}
+/** Package provenance for per-entry resume invalidation. */
+export function docsCachePkg(params) {
+    return params.module === '.' ? undefined : packageRootOf(params.module);
+}

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

@@ -1,6 +1,12 @@
 import type { EventEmitter } from 'node:events';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
+interface FetchDetails {
+    childExitCode?: number;
+    answer?: string;
+    excerpt?: string;
+    excerptVerified?: boolean;
+}
 interface ProcLike extends EventEmitter {
     stdout: EventEmitter | null;
     stderr: EventEmitter | null;
@@ -17,4 +23,16 @@ export interface PiWorkerFetchInternals {
     spawn?: SpawnFn;
 }
 export declare function registerPiWorkerFetch(pi: ExtensionAPI, internals?: PiWorkerFetchInternals): void;
+/**
+ * The F-2(e) cache rule for the fetch channel, named for the same reason as
+ * `docsCacheable`: pi-worker-fetch.test.ts carried a hand-retyped copy driving four
+ * tests, which a change to the shipped rule would leave green.
+ */
+export declare function fetchCacheable(d: Pick<FetchDetails, 'childExitCode'>, text: string): boolean;
+/** The fetch cache key. URL verbatim (path case can matter), question normalised —
+ *  same page, different question is a different answer. */
+export declare function fetchCacheKey(params: {
+    url: string;
+    query: string;
+}): string;
 export {};