@mjasnikovs/pi-task 0.38.28 → 0.38.30

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

@@ -35,16 +35,17 @@ export declare function hasTypeFiles(root: string): boolean;
  * lines, and the pointer lines a redirect stub is made of (`/// <reference .. />`
  * and `export * from "X"`).
  *
- * This is the discriminator `detectTypesRedirect` needs: a redirect stub is a
- * file with essentially nothing in it but the pointer, while an API surface that
- * merely *declares an ambient dependency* on another types package (the
- * `sharp` -> `/// <reference types="node" />` shape) carries its own
- * declarations. Counting `.d.ts` FILES cannot tell those apart — sharp ships one
- * 1971-line file and `@types/bun` ships one 1-line file, and both count as 1.
+ * This is the discriminator `detectTypesRedirect` needs. A redirect stub has
+ * nothing in it but the pointer and counts 0. A real API surface that merely
+ * declares an AMBIENT DEPENDENCY on another types package —
+ * `/// <reference types="node" />` above its own declarations — counts those
+ * declarations and is not a stub. A `.d.ts` FILE count cannot tell the two apart:
+ * both ship exactly one file.
  *
- * Deliberately lexical, not a TypeScript parse: this runs in the shipped worker,
- * which has no compiler dependency. Over-counting is the safe direction (a
- * declaration found ⇒ not a stub ⇒ keep the package's own types).
+ * Deliberately lexical, not a TypeScript parse: `typescript` is a devDependency
+ * here, so the shipped worker has no compiler to call. Over-counting is the safe
+ * direction — a declaration found means not a stub, so the package keeps its own
+ * types.
  */
 export declare function countEntryDeclarations(content: string): number;
 /** When a package is a pure pointer to another types package — a single-file
@@ -57,18 +58,16 @@ 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.
+ * the declarations — `bun` → `@types/bun` → `bun-types`. Bounded to three hops:
+ * a chain of pure stubs stops after exactly three. The `visited` set cuts a cycle,
+ * and the package it started from comes back 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.
+ * This is what the four predicates above exist for, and the walk is written once
+ * for its two callers.
  *
- * `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.
+ * `resolveHop` is the one thing those callers genuinely disagree about: docs-core
+ * resolves the next hop through an auto-installing async lookup, while
+ * phantom-imports wraps a bare sync `resolvePackage` that must never install.
+ * Returning null stops the walk.
  */
 export declare function resolveTypeSource(start: ResolvedPackage, seed: string, resolveHop: (name: string) => Promise<ResolvedPackage | null>): Promise<ResolvedPackage>;

package/dist/workers/docs-resolve.js

@@ -22,10 +22,11 @@ function isValidModuleName(name) {
 }
 // Runtimes whose builtin `<runtime>:<sub>` imports are typed by the runtime's own
 // types package, not by a literal package named "<runtime>:<sub>". `node:fs` and
-// `bun:sqlite` are real imports, but their declarations live in @types/node and
-// bun-types — and a phantom like `bun:sql` (no such submodule) is only disprovable
-// by resolving the runtime and finding the symbol absent. Either way the docs
-// lookup target is the runtime, never the colon-name.
+// `bun:sqlite` are real imports whose declarations live in @types/node and
+// bun-types. `bun:sql` is a phantom — importing it fails with "Cannot find
+// package 'sql'" — and the only way to disprove it is to resolve the runtime and
+// find the symbol absent. Either way the docs lookup target is the runtime, never
+// the colon-name.
 const RUNTIME_NAMESPACES = new Set(['bun', 'node', 'deno']);
 /**
  * Split a runtime builtin specifier (`bun:sql`, `node:fs/promises`) into its
@@ -120,7 +121,9 @@ export function resolvePackage(moduleName, cwd) {
         throw new ResolveError('invalid_name', `Invalid module name: "${moduleName}"`);
     }
     const parent = parentPackageName(moduleName);
-    // First try: use createRequire (works when package.json is exported)
+    // First try: `createRequire`. It only works when the package EXPORTS
+    // `./package.json`; a package that does not gives ERR_PACKAGE_PATH_NOT_EXPORTED
+    // and falls through. Any other resolve error is rethrown.
     const requireFromCwd = createRequire(path.join(cwd, '__pi-worker-docs-sentinel__'));
     let pkgJsonPath = null;
     try {
@@ -130,9 +133,10 @@ export function resolvePackage(moduleName, cwd) {
         const code = err.code;
         if (code !== 'MODULE_NOT_FOUND' && code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED')
             throw err;
-        // Fall through to direct filesystem fallback below
     }
-    // Second try: walk node_modules directly (handles packages that don't export package.json)
+    // Second try: walk node_modules upward from cwd. This is what handles a package
+    // that does not export its package.json, and it is the only path that reports
+    // `not_installed`.
     if (!pkgJsonPath) {
         const direct = findPackageJsonInNodeModules(parent, cwd);
         if (!direct) {
@@ -230,16 +234,17 @@ const DECLARATION_RE = /^\s*(?:export\s+(?:default\s+)?)?(?:declare\s+)?(?:abstr
  * lines, and the pointer lines a redirect stub is made of (`/// <reference .. />`
  * and `export * from "X"`).
  *
- * This is the discriminator `detectTypesRedirect` needs: a redirect stub is a
- * file with essentially nothing in it but the pointer, while an API surface that
- * merely *declares an ambient dependency* on another types package (the
- * `sharp` -> `/// <reference types="node" />` shape) carries its own
- * declarations. Counting `.d.ts` FILES cannot tell those apart — sharp ships one
- * 1971-line file and `@types/bun` ships one 1-line file, and both count as 1.
+ * This is the discriminator `detectTypesRedirect` needs. A redirect stub has
+ * nothing in it but the pointer and counts 0. A real API surface that merely
+ * declares an AMBIENT DEPENDENCY on another types package —
+ * `/// <reference types="node" />` above its own declarations — counts those
+ * declarations and is not a stub. A `.d.ts` FILE count cannot tell the two apart:
+ * both ship exactly one file.
  *
- * Deliberately lexical, not a TypeScript parse: this runs in the shipped worker,
- * which has no compiler dependency. Over-counting is the safe direction (a
- * declaration found ⇒ not a stub ⇒ keep the package's own types).
+ * Deliberately lexical, not a TypeScript parse: `typescript` is a devDependency
+ * here, so the shipped worker has no compiler to call. Over-counting is the safe
+ * direction — a declaration found means not a stub, so the package keeps its own
+ * types.
  */
 export function countEntryDeclarations(content) {
     const stripped = content.replace(BLOCK_COMMENT_RE, '');
@@ -295,11 +300,11 @@ export function detectTypesRedirect(pkg) {
     if (!target)
         return null;
     // A pointer line is not a redirect when the file it sits in also declares an
-    // API. `/// <reference types="node" />` in a package like sharp is an AMBIENT
-    // DEPENDENCY declaration — "my types need node's" — not "my types ARE node's";
-    // following it answered every sharp question out of @types/node (tty.d.ts,
-    // zlib.d.ts) while sharp's own 1971-line surface sat one file away. The .d.ts
-    // FILE count cannot see this: sharp ships one file and so does @types/bun.
+    // API. `/// <reference types="node" />` above a package's own declarations
+    // means "my types NEED node's", not "my types ARE node's". Following it would
+    // answer every question about that package out of @types/node while its own
+    // surface sat one file away — and the .d.ts FILE count cannot see the
+    // difference, because a stub and a single-file API surface both count 1.
     if (countEntryDeclarations(content) > 0)
         return null;
     return target;
@@ -307,19 +312,17 @@ export function detectTypesRedirect(pkg) {
 /**
  * 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.
+ * the declarations — `bun` → `@types/bun` → `bun-types`. Bounded to three hops:
+ * a chain of pure stubs stops after exactly three. The `visited` set cuts a cycle,
+ * and the package it started from comes back 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.
+ * This is what the four predicates above exist for, and the walk is written once
+ * for its two callers.
  *
- * `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.
+ * `resolveHop` is the one thing those callers genuinely disagree about: docs-core
+ * resolves the next hop through an auto-installing async lookup, while
+ * phantom-imports wraps a bare sync `resolvePackage` that must never install.
+ * Returning null stops the walk.
  */
 export async function resolveTypeSource(start, seed, resolveHop) {
     const visited = new Set([start.name, seed]);

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

@@ -13,13 +13,12 @@ export interface RetrieveOptions {
     contentBudget?: number;
 }
 /**
- * How many chunks a retrieval returns, per corpus.
+ * How many chunks a retrieval returns, per corpus. An npm package gets 8 and
+ * project source gets 50.
  *
- * 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.
+ * Nothing in this repo records WHY they differ. They are stated here, together,
+ * so the divergence is at least visible — and changing either is a
+ * retrieval-policy change, not a tidy-up.
  */
 export declare const PACKAGE_RETRIEVE_LIMIT = 8;
 export declare const PROJECT_RETRIEVE_LIMIT = 50;

package/dist/workers/docs-retrieve.js

@@ -1,18 +1,18 @@
 /**
- * How many chunks a retrieval returns, per corpus.
+ * How many chunks a retrieval returns, per corpus. An npm package gets 8 and
+ * project source gets 50.
  *
- * 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.
+ * Nothing in this repo records WHY they differ. They are stated here, together,
+ * so the divergence is at least visible — and changing either is a
+ * retrieval-policy change, not a tidy-up.
  */
 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.
+// Both callers pass `limit` and `contentBudget` explicitly — docs-core with the
+// package pair, docs-project with the project pair — 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;
@@ -25,13 +25,11 @@ const FALLBACK_README_CHARS = 4_000;
  * multi-part identifiers into one string that occurs nowhere in the corpus:
  *   "src/server/routes/auth.ts"  ->  "srcserverroutesauthts"
  *   "Bun.password.hash"          ->  "Bunpasswordhash"
- * Because buildFtsQuery ORs the tokens, such a token contributes no MATCH at all, so the
- * single most informative term in the query — the path, or the dotted API symbol — was
- * dropped and ranking fell to the surrounding prose. Measured on the 141 real project
- * queries of mx5 run 13, that cost 18% of them any chunk from the file they named
- * (82% -> 99% retrieved once split on punctuation); on the 44 gradable npm queries,
- * discriminative-symbol recall 89.5% -> 96.4%.
- * See scripts/live-project-docs-retrieval-ab.ts and scripts/live-npm-tokenizer-regression.ts.
+ * Because buildFtsQuery ORs the tokens, a welded token contributes no MATCH at all.
+ * The single most informative term in the query — the path, or the dotted API
+ * symbol — is then dropped, and when it was the only term the retrieval falls all
+ * the way through to `fallbackChunks`: the alphabetically-first `.d.ts` and the
+ * first README, exactly what an empty query returns.
  */
 function tokenize(query) {
     return query.split(/[^a-zA-Z0-9_]+/).filter(t => t.length >= MIN_TOKEN_LEN);
@@ -65,6 +63,11 @@ function fallbackChunks(cache, name, version) {
     }
     return out;
 }
+/**
+ * Trim the chunk list to the character budget, in retrieval order. The FIRST
+ * chunk is always kept, whatever its size — a top-ranked chunk larger than the
+ * whole budget would otherwise return nothing at all.
+ */
 function enforceBudget(chunks, budget) {
     if (!chunks.length)
         return chunks;

package/dist/workers/exa-search.d.ts

@@ -1,11 +1,14 @@
 /**
- * Web search via Exa's public MCP endpoint — no API key required.
+ * Web search via Exa's public MCP endpoint. No API key: search-types.ts gives
+ * `exa` an empty env-var list, and the endpoint answers an unauthenticated POST.
  *
- * Exa hosts https://mcp.exa.ai/mcp as an intentionally keyless entry point: a
- * single JSON-RPC `tools/call` of `web_search_exa` returns search results with
- * content snippets. The response is SSE-framed (`data:` lines) or plain JSON,
- * and the result payload is one text blob of `Title:`/`URL:`/`Text:` blocks
- * separated by `---`, which we parse back into structured results.
+ * One JSON-RPC `tools/call` of `web_search_exa` against https://mcp.exa.ai/mcp
+ * returns the results. The response comes back `text/event-stream` — an
+ * `event: message` line and one `data:` frame — and `parseRpcBody` also accepts a
+ * plain JSON body. Inside the RPC result is a single text blob of blocks
+ * separated by `---`, each carrying `Title:`, `URL:`, and then either a `Text:`
+ * label or a `Highlights:` line. `parseResultBlocks` turns that back into
+ * structured results.
  */
 import { type FetchLike } from './http-request.js';
 import type { SearchResult } from './search-types.js';

package/dist/workers/exa-search.js

@@ -1,11 +1,14 @@
 /**
- * Web search via Exa's public MCP endpoint — no API key required.
+ * Web search via Exa's public MCP endpoint. No API key: search-types.ts gives
+ * `exa` an empty env-var list, and the endpoint answers an unauthenticated POST.
  *
- * Exa hosts https://mcp.exa.ai/mcp as an intentionally keyless entry point: a
- * single JSON-RPC `tools/call` of `web_search_exa` returns search results with
- * content snippets. The response is SSE-framed (`data:` lines) or plain JSON,
- * and the result payload is one text blob of `Title:`/`URL:`/`Text:` blocks
- * separated by `---`, which we parse back into structured results.
+ * One JSON-RPC `tools/call` of `web_search_exa` against https://mcp.exa.ai/mcp
+ * returns the results. The response comes back `text/event-stream` — an
+ * `event: message` line and one `data:` frame — and `parseRpcBody` also accepts a
+ * plain JSON body. Inside the RPC result is a single text blob of blocks
+ * separated by `---`, each carrying `Title:`, `URL:`, and then either a `Text:`
+ * label or a `Highlights:` line. `parseResultBlocks` turns that back into
+ * structured results.
  */
 import { httpRequest, HttpRequestError } from './http-request.js';
 const EXA_MCP_ENDPOINT = 'https://mcp.exa.ai/mcp';
@@ -31,7 +34,10 @@ export async function exaSearch(query, opts = {}) {
         ...(opts.fetchImpl === undefined ? {} : { fetchImpl: opts.fetchImpl })
     }, count, query);
 }
-/** The Exa-specific half: its argv, its status policy, its error type. */
+/** The Exa-specific half: the JSON-RPC body it posts, its status policy, and its
+ *  error type. Every failure leaves here as an ExaSearchError — `http` for a
+ *  non-2xx, `protocol` for an RPC error / an `isError` result / no text content /
+ *  an unparseable body, and `network` or `aborted` for a transport fault. */
 async function request(bounds, count, query) {
     try {
         return await httpRequest(EXA_MCP_ENDPOINT, {
@@ -83,9 +89,10 @@ async function request(bounds, count, query) {
     }
 }
 /**
- * The endpoint answers either as a text/event-stream (`data: {json}` lines) or
- * as a plain JSON body; accept both and take the first frame carrying a
- * JSON-RPC result or error.
+ * The endpoint answers as a text/event-stream (`data: {json}` lines) in practice,
+ * but a plain JSON body parses too. Take the FIRST `data:` frame that carries a
+ * JSON-RPC `result` or `error` — frames without either (a bare
+ * `{"jsonrpc":"2.0"}`) are skipped, not treated as the answer.
  */
 function parseRpcBody(body) {
     for (const line of body.split('\n')) {
@@ -116,8 +123,12 @@ function parseRpcBody(body) {
 /**
  * Split the tool's text payload into `Title:`/`URL:` blocks. The per-result
  * content lives after a `Text:` label (full text) or a `Highlights:` line
- * (snippet mode); either becomes the description, whitespace-collapsed and
- * capped so a result line stays a snippet, not a page dump.
+ * (snippet mode); either becomes the description, whitespace-collapsed, its
+ * trailing `---` removed, and capped at MAX_DESCRIPTION_CHARS so a result line
+ * stays a snippet, not a page dump.
+ *
+ * A block with no `URL:` is dropped entirely. A block with an empty `Title:`
+ * keeps the URL as its title, so a result is never nameless.
  */
 function parseResultBlocks(text) {
     const blocks = text.split(/(?=^Title: )/m).filter(b => b.trim().length > 0);

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

@@ -17,10 +17,9 @@ export interface FetchRawResult {
 }
 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}.
+ * How the page content is turned into the child's prompt. A seam, so a harness can run a
+ * variant selection or prompt against the shipped one in the SAME process. Nothing in this
+ * repo overrides it: {@link shippedStrategy} is the only implementation.
  */
 export interface PromptStrategy {
     selectContent(markdown: string, requestedUrl: string): SelectedContent;
@@ -47,25 +46,23 @@ export interface FetchFocusedResult {
     excerpt?: string;
     excerptVerified?: boolean;
     /**
-     * The page did not cover the asked-about version/topic — a DISTINCT outcome from
+     * The page did not cover the asked-about version or 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).
+     * "page has no answer" and "answer is ambiguous" as the same thing.
      */
     coverageMiss: boolean;
     /**
-     * What to do INSTEAD, present only on a coverage miss. `coverageMiss` was computed and
-     * stored and read nowhere, so the distinct channel it exists to provide never reached the
-     * worker: all it ever saw was the bare sentence "not covered by this page", which reads
-     * as "ask again, differently". It did — 9 of the 84 corpus fetches re-read a URL that had
-     * already returned a non-answer, one release-notes page three times with near-identical
-     * questions.
+     * What to do INSTEAD, present only on a coverage miss. Without it the worker sees only
+     * the bare sentence "not covered by this page", which reads as "ask again, differently"
+     * — and re-reading the same URL with a reworded question returns the same answer.
      */
     nextStep?: string;
     /** 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. */
+    /** The prompt actually handed to the child, returned so a caller can see exactly what
+     *  the selection and the strategy produced. */
     assembledPrompt: string;
     /**
      * Set exactly when the child failed (aborted, or non-zero exit): the standard
@@ -96,10 +93,10 @@ export interface SelectedContent {
 /**
  * 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}
+ * a section that sits past the head window. 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.
+ * page changed since the link was captured), so a fragment that cannot be honoured never
+ * degrades a page that could otherwise be read.
  */
 export declare function selectContent(markdown: string, requestedUrl: string): SelectedContent;
 /** The shipped strategy: fragment-aware selection + the recalibrated prompt. */

package/dist/workers/fetch-core.js

@@ -1,6 +1,7 @@
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { abstentionSentence } from './abstention.js';
+import {} from '../shared/child-output.js';
 import { groupThinkingArgs } from '../config/reasoning-args.js';
 const CONTENT_BUDGET = 30_000;
 const HEAD_CHARS = 25_000;
@@ -14,19 +15,15 @@ export const NOT_COVERED_ANSWER = 'not covered by this page';
  * answer — anchored, not a substring search. A substring search misreads the opposite case:
  * rule 5 tells the child to answer partially and say what is missing, and it says it in the
  * prompt's own words ("… `obs_add_raw_audio_callback` and `obs_remove_raw_audio_callback`
- * are not covered by this page"). That is a sourced answer, and the loose match filed it as
- * a coverage miss. Observed twice in 5 reps of scripts/fetch-url-normalise-ab.ts once the
- * rewrite started delivering pages that could half-answer; never in the 84 recorded corpus
- * fetches, where 11 of 11 sentinel answers are the bare sentinel — so tightening it changes
- * no recorded verdict.
+ * are not covered by this page"). That is a sourced answer, and a loose match would file it
+ * as a coverage miss.
  */
 const NOT_COVERED_RE = /^not covered by this page[.\s]*$/i;
 /**
  * `github.com/{owner}/{repo}/blob/{ref}/{path}` renders the file through a client-side
- * viewer, so the HTML we clean carries GitHub chrome ("Sign in", "Appearance settings")
- * and none of the file. Every one of the 8 blob URLs in the three-project research-cache
- * corpus came back a non-answer for that reason. `raw.githubusercontent.com` serves the
- * same bytes as text/plain.
+ * viewer. The HTML carries GitHub chrome ("Sign in", "Appearance settings") and NOT the
+ * file: fetching one blob URL returns 282 KB of text/html that does not contain the file's
+ * bytes anywhere, while `raw.githubusercontent.com` returns the file itself as text/plain.
  *
  * Only the URL handed to the fetcher is rewritten — the caller's URL still keys the cache
  * and still supplies the #fragment — so a worker that retries the raw URL by hand hits the
@@ -141,10 +138,10 @@ function fragmentOf(url) {
 /**
  * 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}
+ * a section that sits past the head window. 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.
+ * page changed since the link was captured), so a fragment that cannot be honoured never
+ * degrades a page that could otherwise be read.
  */
 export function selectContent(markdown, requestedUrl) {
     const frag = fragmentOf(requestedUrl);
@@ -159,9 +156,10 @@ 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`. */
+ *  heading line up to the next heading of the same or HIGHER level, so a `##` section keeps
+ *  its `###` subsections. Anchors are matched on the heading line in both the Docusaurus
+ *  (`### Title[](#slug "…")`) and GitHub (`## [Title](#slug)`) shapes, and the trailing
+ *  `(?![a-z0-9-])` is what keeps `#foo` from matching `#foobar`. */
 function sliceSection(markdown, frag) {
     const lines = markdown.split('\n');
     const anchor = new RegExp('#' + escapeRegExp(frag) + '(?![a-z0-9-])', 'i');
@@ -194,14 +192,16 @@ function truncate(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.
+ * The shipped extraction prompt. Its three abstention rules are deliberately separate, and a
+ * child that collapses them loses information the caller needs:
+ *   5. answer from the content whenever it supports one, even partially — "unclear" is the
+ *      wrong response merely because coverage is incomplete;
+ *   6. a page about a DIFFERENT version or topic is a coverage MISS, `NOT_COVERED_ANSWER`,
+ *      which the caller turns into "try a different URL";
+ *   7. `UNCLEAR_ANSWER` is reserved for content that IS present but ambiguous — never for
+ *      absence, and never as licence to invent.
+ * Rules 1 and 2, the verbatim-excerpt requirement the fabrication check rests on, are
+ * independent of all three.
  */
 function buildPrompt(args) {
     const sectionNote = args.section ?

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

@@ -1,9 +1,9 @@
 import { type SpawnFn } from '../shared/child-process.js';
 import { type ExcerptVerification } from '../shared/child-output.js';
 /**
- * The argv every focused extraction child runs with: the shared child base (whitelisted
- * extensions + `--print --no-session …`) plus `--no-tools`. This was three byte-identical
- * one-liners in fetch-core, docs-core and pi-worker-docs.
+ * The argv every focused extraction child runs with: the shared child base — any whitelisted
+ * extensions, then `--print --no-skills --no-extensions --no-prompt-templates
+ * --no-context-files --no-session` — then the caller's thinking fragment, then `--no-tools`.
  *
  * `--no-tools` is the contract, not a default: the child is given all the content it may use
  * inside its prompt, so a tool call could only reach for something unsourced.
@@ -13,11 +13,11 @@ export interface FocusedRequest {
     /** The fully assembled prompt, including the content block. Delivered on stdin. */
     prompt: string;
     /**
-     * The text the cited excerpt is checked against — a NAMED knob, because the four call
-     * sites deliberately disagree and the disagreement used to be invisible.
+     * The text the cited excerpt is checked against — a NAMED knob, because the two call
+     * sites deliberately disagree, and unnamed the disagreement is invisible.
      *
-     * `pi-worker-docs` and `docsFocused` pass exactly the concatenated chunks that went into
-     * the prompt. `fetchFocused` passes the FULL cleaned page while prompting with only the
+     * `docsLookup` passes exactly the concatenated chunks that went into the prompt.
+     * `fetchFocused` passes the FULL cleaned page while prompting with only the
      * anchored `#fragment` section: the slice is a substring of the page, so a genuine excerpt
      * still verifies, and an excerpt pulled from the model's memory still fails — fragment
      * anchoring therefore cannot change the hallucination detector's discrimination.
@@ -37,11 +37,10 @@ export interface FocusedRequest {
      * An already-resolved `['--thinking', level]` fragment, or `[]`/omitted to
      * inherit the session default.
      *
-     * Supplied by the CALLER even though all three call sites are the same
+     * Supplied by the CALLER even though both call sites resolve the same
      * `extraction` group. Resolving it inside this module would make
      * `focusedChildArgs` read ambient config, and a function that reads config
-     * internally cannot be tested without the developer's own machine state —
-     * which is exactly how a `getConfig()` assertion got into a unit test.
+     * internally cannot be tested without the developer's own machine state.
      */
     thinking?: readonly string[];
 }
@@ -50,7 +49,8 @@ interface FocusedChildEvidence {
     exitCode: number;
     aborted: boolean;
     stderr: string;
-    /** The child's raw stdout, retained for A/B harnesses and failure diagnosis. */
+    /** The child's raw stdout, retained so a failure is diagnosable from the result alone —
+     *  it is the only place a crashed child's output survives. */
     stdout: string;
 }
 /** The child aborted or exited non-zero. There is deliberately no `answer` here. */
@@ -78,7 +78,7 @@ export type FocusedResult = FocusedFailure | FocusedAnswer;
  * `<answer>`/`<excerpt>` and verify the excerpt against `verifyAgainst`.
  *
  * Never retries — a re-ask of a deterministic extraction over unchanged content is a second
- * bill for the same answer, and all four call sites already had it that way.
+ * bill for the same answer. Exactly one child is spawned per call.
  */
 export declare function runFocusedExtraction(req: FocusedRequest): Promise<FocusedResult>;
 export {};