@mjasnikovs/pi-task 0.38.29 → 0.38.31

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

@@ -1,24 +1,19 @@
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { runChildDefault } from '../shared/child-process.js';
-import { CommandWatchdog, commandTimeoutHint, realTimerDeps } from '../shared/command-watchdog.js';
+import { commandCeilingForAttempt, commandTimeoutHint, commandWatch } from '../shared/command-watchdog.js';
+export { commandCeilingForAttempt } from '../shared/command-watchdog.js';
 import { isGroundingRetrieval as isGrounding, workerChannel } from './worker-channels.js';
 import { childBaseArgs } from '../shared/child-extensions.js';
-import { LoopDetector } from '../task/loop-detector.js';
+import { LoopDetector, MAX_LOOP_RESTARTS } from '../task/loop-detector.js';
 import { StallDetector, formatStallHint } from '../task/stall-detector.js';
-import { MAX_LOOP_RESTARTS, formatLoopHint, isConnectionError, connectionRetryBackoffMs } from '../task/child-runner.js';
+import { formatLoopHint, isConnectionError, connectionRetryBackoffMs } from '../task/child-runner.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 import { discoverModelEndpoints, probeModelEndpoints } from '../shared/model-endpoint.js';
 import { streamStallHint } from '../shared/stream-watchdog.js';
 import { classifyWorkerFailure } from './worker-failure.js';
-import { CARRY_FORWARD_IDS } from './worker-kill.js';
+import { CARRY_FORWARD_IDS, RESTART_ORDER } from './worker-kill.js';
 import { applyOverride, WORKER_PROFILES } from './worker-profiles.js';
-// `--mode json` makes pi emit structured events as they happen instead of
-// buffering the assistant text and flushing on exit. That matters for the
-// wait/work timing split: in text mode the first stdout chunk only arrives at
-// the very end, so onFirstByte fires moments before close and workMs is
-// effectively zero. With JSON events the first byte lands as soon as the
-// model starts producing — making waitMs the real queue/cold-start cost and
-// workMs the real generation+tool-call cost.
+/** The tool whitelist a caller gets when it names none. */
 const DEFAULT_TOOLS = 'read,grep,find,ls';
 /**
  * The one place `'unknown'` becomes the 0 both consumers already treat as
@@ -33,18 +28,19 @@ function contextWindowTokens(cw) {
  * 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.
+ * `ls` and `find` are deliberately EXCLUDED: they return file and directory
+ * NAMES, and APIS owns symbols by name only, never paths (see
+ * RESEARCH_APIS_PROMPT in prompts.ts). Bare enumeration cannot verify a
+ * signature, so a worker that fabricates its section from memory cannot launder
+ * itself grounded by calling `ls` once — "one trivial `ls` then fabricate the
+ * rest" still leaves groundingRetrievalCount at 0.
+ *
+ * The set is DERIVED from WORKER_CHANNELS (worker-channels.ts), not hand-kept.
+ * Re-exported here only so worker-channels.test.ts can assert this module hands
+ * back the same predicate.
  */
-// The grounding set is derived from WORKER_CHANNELS (worker-channels.ts), not
-// hand-kept — this was a second copy of the four tool names. Re-exported because
-// several call sites and tests import it from here.
 export { isGroundingRetrieval } from './worker-channels.js';
-// RESEARCH_WORKER_TIMEOUT_MS and STALL_AFTER_MS live on the profile table now
+// RESEARCH_WORKER_TIMEOUT_MS and STALL_AFTER_MS live on the profile table
 // (worker-profiles.ts): they are the default VALUES of two guard rows, and a
 // default that lives apart from the table stating it is a second place to look.
 /**
@@ -59,49 +55,44 @@ const WORKER_TIMEOUT_HINT = '[SYSTEM NOTE: Your previous attempt ran out of time
 /**
  * How much of a discarded attempt's answer is carried into the next one.
  *
- * A restart used to hand the re-spawn nothing but a hint — which is why
- * WORKER_TIMEOUT_HINT above can tell a worker "do not re-explore ground you have
- * already covered" while giving it no record of what that ground was. It could
- * not comply. mx5 run 18 shows the cost: on tasks with >=46 project-source
- * lookups, 5 of 5 workers burned the FULL restart budget, because every attempt
- * re-read the same files against the same clock and died in the same place.
+ * A restart that hands the re-spawn nothing but a hint is why WORKER_TIMEOUT_HINT
+ * above can tell a worker "do not re-explore ground you have already covered"
+ * while giving it no record of what that ground was. It cannot comply, so it
+ * re-reads the same files against the same clock and dies in the same place.
  *
- * Carrying the partial answer forward is what makes a restart converge instead
- * of repeat. The risk it takes is real and is the thing the A/B measures: a
- * half-written or speculative entry, replayed under "already established", is
- * exactly how a fabrication gets laundered into a final answer. That is what the
- * ungrounded-symbol and anti-synthesis guards are pointed at, so the carry is
- * framed as findings to VERIFY-or-DROP rather than as settled fact.
+ * Carrying the partial forward is what lets a restart converge instead of repeat.
+ * The risk is real: a half-written or speculative entry, replayed under "already
+ * established", is how a fabrication gets laundered into a final answer. That is
+ * why `formatCarryForward` frames it as findings to VERIFY-or-DROP rather than as
+ * settled fact.
  */
 const CARRY_FORWARD_LIMIT = 24_000;
 /**
  * Restart reasons whose partial output is worth keeping.
  *
- * A clock kill (`worker-timeout`), a hung tool (`command-timeout`), an idle
- * stream (`stream-stall`) and a dropped socket (`connection-error`) all discard
- * work the model genuinely did. A loop kill and a leaked tool call do not — the
- * first is by definition the same call repeated, the second is malformed
- * protocol text, and replaying either would feed the failure back to itself.
+ * Exactly four, derived from WORKER_KILLS: `command-timeout`, `stream-stall`,
+ * `worker-timeout` and `connection-error` all discard work the model genuinely
+ * did. A loop kill and a leaked tool call do not — the first is by definition the
+ * same call repeated, the second is malformed protocol text, and replaying either
+ * would feed the failure back to itself.
  */
 const CARRY_FORWARD_REASONS = CARRY_FORWARD_IDS;
 /**
  * Does this partial output carry ANSWER CONTENT, or is it the model clearing its
  * throat?
  *
- * Salvage originally kept the LONGEST partial, which is not the same question. On
- * the live carry arm, TASK_0020 and TASK_0021 both timed out on all three
- * attempts and salvage shipped this as the section:
+ * Keeping the LONGEST partial is not the same question, and it has an obvious
+ * failure: a preamble sentence like
  *
  *     "Now let me get more details on the specific APIs and components I need:"
  *
- * — a preamble sentence, which beats an empty string on length and carries
- * nothing. Both trials scored 2 entries and DEGRADED, against 22 and 5 for the
- * same fixtures in baseline.
+ * beats an empty string on length and carries nothing.
  *
  * A research worker's answer is a list of lines that each name something and
- * describe it. The test is therefore structural, not lexical: at least two lines
- * that look like entries — a name, then a gap, then a description. Prose wraps
- * at no particular column and does not repeat that shape.
+ * describe it. The test is therefore structural, not lexical: at least TWO lines
+ * that look like entries — a name, then a gap, then a description. Prose wraps at
+ * no particular column and does not repeat that shape; the sentence above scores
+ * zero entry lines.
  */
 export function hasAnswerContent(text) {
     return text.split('\n').filter(isEntryLine).length >= 2;
@@ -109,13 +100,15 @@ export function hasAnswerContent(text) {
 /**
  * Is ONE line an entry — a name, a gap, then a description — rather than prose?
  *
- * Split out of `hasAnswerContent` so the same rule can decide what a line IS,
- * not just how many of them there are. A FILES section's paths are read back
- * with it, and a scorer that used its own idea of an entry counted a preamble
- * sentence and a leaked `</tool_call>` as invented paths.
+ * Split out of `hasAnswerContent` so the same rule can decide what a line IS, not
+ * just how many of them there are — a reader of a FILES section needs the same
+ * test, and its own idea of an entry would count a preamble sentence or a leaked
+ * `</tool_call>` as one.
  *
- * Prose wraps at no particular column, so it carries no two-space gap and no
- * spaced dash; when it does, it ends in `.` or `:` and an entry does not.
+ * A leading `-`, `*`, `•` or `1.`/`1)` bullet is stripped first. What remains must
+ * hold a two-space gap or a spaced dash and must NOT end in `.` or `:`. Prose
+ * wraps at no particular column, so it carries neither; when it does carry one, it
+ * ends in punctuation and an entry does not.
  */
 export function isEntryLine(raw) {
     const l = raw.replace(/^\s*(?:[-*•]|\d+[.)])\s+/, '').trim();
@@ -183,10 +176,10 @@ absoluteCeilingMs) {
     return {
         signal: ctrl.signal,
         timedOut: () => timedOut,
-        // SCALE arm of nexttask 5B, inert unless a caller calls it: push the
-        // deadline out, never past `started + ceilingMs`. A disabled timeout
-        // (nothing armed) stays disabled — extending "never" is meaningless — and
-        // an already-fired timer is not resurrected.
+        // Push the deadline out, never past `started + ceilingMs`. Inert unless a
+        // caller calls it. A disabled timeout (nothing armed) stays disabled —
+        // extending "never" is meaningless — and an already-fired timer is not
+        // resurrected.
         extend: (byMs, ceilingMs) => {
             if (!armed || timedOut || ctrl.signal.aborted)
                 return;
@@ -224,33 +217,6 @@ absoluteCeilingMs) {
         }
     };
 }
-/**
- * The per-command ceiling for attempt N, halving each time a hang recurs.
- *
- * The first attempt gets the full configured ceiling — a genuinely slow build or
- * test suite deserves it. But every hang-caused restart carries
- * commandTimeoutHint, which tells the model in as many words to bound its
- * command; a SECOND hang means it ignored an explicit instruction, and a third
- * means it ignored it twice. Giving a non-complying child the full ceiling again
- * would put the worst case at 3 × 15 min = 45 minutes of dead time, resting
- * entirely on the model obeying prose. Halving bounds it at ~26 min while
- * costing a complying child nothing.
- *
- * `priorHangs` counts watchdog kills specifically, NOT total restarts — the
- * restart budget is shared with loop kills, and a child restarted for LOOPING
- * never received the bound-your-command hint, so its first hang still deserves
- * the full ceiling. Only a hang after a hang is defiance.
- *
- * Floored at 30s so repeated halving cannot shrink the ceiling to something no
- * real command could finish inside — but never ABOVE the configured ceiling
- * itself, or a caller asking for 10s would silently get 30.
- */
-export function commandCeilingForAttempt(baseMs, priorHangs) {
-    if (!(baseMs > 0))
-        return 0;
-    const floor = Math.min(baseMs, 30_000);
-    return Math.max(floor, Math.round(baseMs / 2 ** priorHangs));
-}
 /**
  * The restart ladder, in precedence order. FIRST MATCH WINS.
  *
@@ -323,8 +289,8 @@ export const RESTART_RULES = [
         // a loop also tripped — the loop hint above is more specific.
         reason: 'worker-timeout',
         detect: s => s.timedOut && !s.loopHit && s.restartBudgetSpent < MAX_LOOP_RESTARTS ?
-            // The EFFECTIVE cap, which the SCALE arm moves — reporting the
-            // configured one would misname why this attempt died.
+            // The EFFECTIVE cap, which `extend`/`progress` can have moved —
+            // reporting the configured one would misname why this attempt died.
             { detail: `cap ${s.effectiveCapMs}ms` }
             : null,
         hint: () => WORKER_TIMEOUT_HINT,
@@ -332,22 +298,15 @@ export const RESTART_RULES = [
     },
     {
         // A connection-class model error is restartable on the same budget, exactly
-        // as runPhaseChild already treats it — a research worker had no such
-        // retry, so one dropped fetch failed the whole task at research while the
-        // identical blip in refine/compose was absorbed.
+        // as runPhaseChild already treats it. Without it one dropped socket fails
+        // the whole task at research, while the identical blip in refine or compose
+        // is absorbed.
         //
-        // What this can and cannot buy, measured (flaky proxy in front of the local
-        // llama-server, dropping every connection for a fixed outage window): pi
-        // retries a failed turn itself, 4 attempts over ~15s, and a run that
-        // recovers no longer reports modelError at all (see JsonEventSink). So a
-        // surfaced connection error means pi's own ~15s budget is already spent, and
-        // a re-spawn only helps when the outage outlasts it. It does: at a 20s
-        // outage the baseline never recovered and this policy always did, 0/8 → 8/8
-        // (Fisher p=0.00016), and the same at 35s. Below ~15s pi absorbs it alone —
-        // 8/8 both arms, so the retry neither helps nor costs there. Beyond ~46s
-        // (three spawns' combined budget) both arms fail. The price is paid only on
-        // a backend that is really gone: time-to-report goes ~15s → ~46s. Re-run:
-        // scripts/connection-retry-ab.ts.
+        // pi retries a failed turn itself before reporting anything, and a run that
+        // recovers reports no modelError at all (see JsonEventSink). So a SURFACED
+        // connection error means pi's own budget is already spent, and a re-spawn
+        // only helps when the outage outlasts it. The price is paid only on a
+        // backend that is really gone: time-to-report grows by the extra spawns.
         //
         // Connection class ONLY. Auth, bad request and context overflow still fail
         // fast: re-issuing the same request cannot fix them, so spending the budget
@@ -374,60 +333,15 @@ export const RESTART_RULES = [
         counters: { leak: true }
     }
 ];
-/**
- * Build the child-side command watchdog for ONE attempt: a per-tool-call timer
- * machine (shared with the main session) whose `onFire` aborts `signal`, which
- * runChild turns into a process-GROUP kill — reaping the hung command itself,
- * not just the pi child holding it.
- *
- * LIMIT: the group kill only reaches processes still IN the group. A hung
- * command that detached a daemon (setsid/nohup dev server) leaves it running —
- * the fresh attempt can then hit a port the dead attempt's escapee still holds
- * (the run-9 orphan-dev-server → false-EADDRINUSE shape). No cheap fix from
- * here; the restart hint's "check current state" line is the mitigation.
- *
- * Returns null when the watchdog is off, so the caller keeps the plain timeout
- * signal and no per-call bookkeeping happens at all.
- */
-function commandWatch(timeoutMs) {
-    if (!(timeoutMs > 0))
-        return null;
-    const ctrl = new AbortController();
-    // pi's toolCallId pairs start↔end. When it is absent (a fake stream in a
-    // test, an older pi), fall back to one shared slot: tool executions in a
-    // child are sequential, so a single slot is still correctly paired.
-    const key = (id) => id ?? 'anon';
-    const details = new Map();
-    let killed;
-    const watchdog = new CommandWatchdog({
-        getTimeoutMs: () => timeoutMs,
-        ...realTimerDeps,
-        onFire: (toolCallId, toolName, ms) => {
-            killed = {
-                toolName,
-                timeoutMs: ms,
-                ...(details.has(toolCallId) ? { detail: details.get(toolCallId) } : {})
-            };
-            ctrl.abort();
-        }
-    });
-    return {
-        onStart: call => {
-            const id = key(call.toolCallId);
-            const args = call.args;
-            if (typeof args?.command === 'string') {
-                details.set(id, args.command.slice(0, 120));
-            }
-            watchdog.onStart(id, call.name);
-        },
-        onEnd: id => watchdog.onEnd(key(id)),
-        killed: () => killed,
-        signal: ctrl.signal,
-        clear: () => watchdog.clearAll()
-    };
-}
 export async function runWorker(input) {
     const tools = input.tools ?? DEFAULT_TOOLS;
+    // `--mode json` makes pi emit structured events as they happen instead of
+    // buffering the assistant text and flushing on exit. Its print-mode source
+    // shows both halves: under `json` a session subscriber writes every event to
+    // stdout as it arrives, while under `text` NOTHING is written until after the
+    // prompt resolves, when the last assistant message is printed once. That is
+    // what makes the wait/work split real — onFirstByte would otherwise fire
+    // moments before close and leave workMs at nearly zero.
     const baseArgs = [
         ...childBaseArgs(input.extensions ?? []),
         ...(input.thinking ?? []),
@@ -475,11 +389,10 @@ export async function runWorker(input) {
     const salvage = { text: null };
     for (;;) {
         const carried = salvage.text === null ? null : formatCarryForward(salvage.text);
-        // Announce the INJECTION, not just the restart. Without this, "the carry
-        // reached the re-spawn" can only be inferred from entry counts — and
-        // inferring what a worker did from what it produced is the exact gap 5A
-        // exists to close. The prompt goes to the child on stdin, so no log
-        // downstream of here can show it.
+        // Announce the INJECTION, not just the restart. The prompt goes to the child
+        // on stdin, so no log downstream of here can show it — without this hook
+        // "the carry reached the re-spawn" could only be inferred from the answer,
+        // which is inferring what a worker did from what it produced.
         if (carried !== null) {
             input.onCarryForward?.({
                 attempt: restarts.length + 1,
@@ -506,8 +419,8 @@ export async function runWorker(input) {
             null
             : new StallDetector(guards.loop.progress.limit, guards.loop.progress.churnFactor);
         // Arm the churn rule BEFORE the first tool call. pi's stream carries no
-        // context event (issue #16), so waiting for one leaves the rule
-        // permanently disarmed. The parent knows the window at spawn time.
+        // context event at all, so waiting for one leaves the rule permanently
+        // disarmed. The parent knows the window at spawn time.
         stallDetector?.noteContext(contextWindowTokens(input.contextWindow));
         // Capture the hit the detector reports (it also returns it to the unified
         // runner, which kills the child on a hit). Without capturing it here the
@@ -546,8 +459,9 @@ export async function runWorker(input) {
                     // A tool call is the worker working. Inert unless the
                     // caller opted into a progress-based deadline.
                     timeout.progress();
-                    // The generic child runner used to name ONE tool and ONE of
-                    // its parameters here. It asks the tool's own row now.
+                    // Naming ONE tool and ONE of its parameters here would put
+                    // that knowledge in the generic runner, so it asks the
+                    // tool's own row in WORKER_CHANNELS instead.
                     if (clock.fanout
                         && workerChannel(call.name)?.isProjectSourceLookup?.(call.args ?? {}) === true) {
                         timeout.extend(clock.fanout.perLookupMs, clock.fanout.ceilingMs);
@@ -570,11 +484,11 @@ export async function runWorker(input) {
                     timeout.progress();
                     input.onLine?.(line);
                 },
-                // Always wired now (it used to be conditional on the command
-                // watchdog): the sink only emits tool_execution_end if a
-                // handler exists, and a completed tool call is the clearest
-                // progress signal there is. Without it a worker whose tool
-                // calls all succeed would still look idle to the deadline.
+                // Always wired, never conditional on the command watchdog: the
+                // sink only emits a tool-execution-end if a handler exists, and
+                // a completed tool call is the clearest progress signal there
+                // is. Without it a worker whose tool calls all succeed would
+                // still look idle to the deadline.
                 onToolResult: r => {
                     timeout.progress();
                     cmdWatch?.onEnd(r.toolCallId);
@@ -637,7 +551,7 @@ export async function runWorker(input) {
         // there would just mislabel the real failure.
         const leaked = result.exitCode === 0 && !result.aborted ? detectLeakedToolCall(text) : null;
         // THE RESTART LADDER. Precedence is RESTART_RULES' row order; this loop
-        // owns the ritual every rule used to repeat: budget, hint, counters,
+        // owns the ritual every rule would otherwise repeat: budget, hint, counters,
         // record-and-announce, backoff, re-spawn.
         const state = {
             ...(loopHit ? { loopHit } : {}),
@@ -678,24 +592,22 @@ export async function runWorker(input) {
         }
         if (restarted)
             continue;
-        // SALVAGE. The run used to return the LAST attempt's text unconditionally,
-        // so a worker whose final attempt was killed early reported nothing at all
-        // — even when a discarded attempt had produced a usable answer that was
-        // still in hand at the moment it was thrown away. A restart budget is
-        // meant to buy more chances at an answer, not to overwrite a good attempt
-        // with a worse one.
+        // SALVAGE. Returning the LAST attempt's text unconditionally makes a
+        // worker whose final attempt was killed early report nothing at all — even
+        // when a discarded attempt produced a usable answer that was still in hand
+        // at the moment it was thrown away. A restart budget is meant to buy more
+        // chances at an answer, not to overwrite a good attempt with a worse one.
         //
         // Gated on the final attempt having FAILED, not on it being shorter. A
         // worker that finished cleanly has answered, and a short answer is a
         // legitimate answer — length would let a long half-finished fragment
         // override a concise correct one, which is the opposite of the fix.
-        // ASK THE LADDER — do not restate it. This was an eight-term disjunction,
-        // a fifth hand-written statement of the taxonomy `worker-failure.ts` exists
-        // to own, and it had already drifted: `leakedToolCall` and a plain non-zero
-        // `exitCode` are rows in FAILURE_RULES and were missing here. Both are cases
-        // where an attempt that produced nothing usable counted as NOT failed, so
-        // salvage was skipped and a good earlier partial was overwritten — the exact
-        // outcome the comment above forbids.
+        // ASK THE LADDER — do not restate it. Hand-writing this test restates the
+        // taxonomy `worker-failure.ts` owns, and a restatement drifts: drop
+        // `leakedToolCall` or a plain non-zero `exitCode` from it and an attempt
+        // that produced nothing usable counts as NOT failed, so salvage is skipped
+        // and a good earlier partial is overwritten — the outcome the comment above
+        // forbids.
         //
         // The two non-kill terms stay explicit because `worker-failure.ts`
         // deliberately excludes them as CONSUMER policy: an empty answer and a

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

@@ -23,21 +23,25 @@ interface DocsDetails {
     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.
+     * The answer restated a declaration for a question that needed usage semantics, so
+     * it is UNANSWERED. Set by isTypeOnlyAnswer; read by `docsCacheable` 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. */
+    /** The project-lookup budget for this attempt is spent, so the call was refused
+     *  before any work. Only set when PI_TASK_PROJECT_DOCS_BUDGET is configured. */
     budgetSpent?: boolean;
 }
 /**
  * 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.
+ * When the answer to a type-only lookup is not in the package, it is often at the
+ * `@see` URL the excerpt being returned already carries. Surfacing that link costs
+ * nothing: the pointer is already in hand.
+ *
+ * Matches `{@link URL}` and a bare `@link URL`, case-insensitively; strips a trailing
+ * `.`/`,`/`;` the surrounding prose added; deduplicates. A bare URL with no `@see` is
+ * not a pointer and is not returned.
  */
 export declare function extractSeeUrls(content: string): string[];
 /**
@@ -57,24 +61,25 @@ export interface PiWorkerDocsInternals {
 }
 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.
+ * The 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.
+ * As a property of the adapter literal it would be reachable only through
+ * `registerTool → execute()`, so a test would have to retype the rule and would then
+ * assert against its own copy — green even after the shipped rule changed. Exported,
+ * the test imports the rule it is checking.
  */
 export declare function docsCacheable(d: Pick<DocsDetails, '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. */
+/** The docs cache key: a package's answer is per (module, question), with the question
+ *  lowercased and its whitespace collapsed so phrasing variants share one entry. Returns
+ *  null for the project-source `.` lookup, which 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. */
+/** Package provenance for per-entry resume invalidation: the package ROOT of the
+ *  specifier (`hono/client` → `hono`), and undefined for the project-source `.`. */
 export declare function docsCachePkg(params: {
     module: string;
 }): string | undefined;