@mjasnikovs/pi-task 0.38.29 → 0.38.31

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

@@ -2,11 +2,13 @@ import { spawn as defaultSpawn } from 'node:child_process';
 import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
 import { openCache as defaultOpenCache } from './docs-cache.js';
+import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
+import { resolvePackage as defaultResolvePackage } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { docsLookup } from './docs-lookup.js';
 import { projectCorpus } from './docs-project.js';
 import { docsRaw, packageCorpus, buildVersionBanner } from './docs-core.js';
-import { formatNpmVersionSection } from './npm-version.js';
+import { npmVersionLookup as defaultNpmVersionLookup, formatNpmVersionSection } from './npm-version.js';
 import { childFailureReason, makeWorkerTool, workerAnswer, workerUnavailable } from './shared.js';
 import { isTypeOnlyAnswer } from '../task/type-only-answer.js';
 import { logDocsAnswer } from './typeonly-log.js';
@@ -27,10 +29,13 @@ const Params = Type.Object({
 /**
  * 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 function extractSeeUrls(content) {
     const out = [];
@@ -57,16 +62,15 @@ function pinDetails(pin) {
     return pin ? { versionSource: pin.source, declaredRange: pin.range } : {};
 }
 /**
- * The tool result for a focused-extraction child that failed, shared by both docs paths —
- * the last chunk they still held in common after the extractor seam took the child running.
- * The paths differ only in `prefix`: the npm path leads every result, failures included, with
- * its version banner and npm-version header; the project path has neither.
+ * The tool result for a focused-extraction child that failed, shared by both docs paths.
+ * They differ only in `prefix`: the npm path leads every result, failures included, with
+ * its version banner and npm-version header; the project path passes ''.
  *
- * It says UNAVAILABLE, so the cache cannot take it. It used to say so by writing a
- * non-zero `childExitCode` and letting `docsCacheable` re-derive the verdict — a
- * derivation that failed on the case it mattered most for: a signal-killed child
- * reports exit code 0, so `"Docs lookup aborted."` was cached for the whole run.
- * `aborted` was written here and read by nothing, which is what let that hide.
+ * It says UNAVAILABLE, so the cache cannot take it. Writing a non-zero `childExitCode`
+ * and letting `docsCacheable` re-derive the verdict would fail on the case it matters
+ * most for: node reports a signal kill as `close` with `code === null`, and
+ * child-process.ts settles that as `code ?? 0` — so an aborted child carries exit code
+ * ZERO and `"Docs lookup aborted."` would be cached for the whole run.
  */
 function docsFailureResult(extraction, baseDetails, prefix) {
     return workerUnavailable(prefix + extraction.failure, {
@@ -76,13 +80,12 @@ function docsFailureResult(extraction, baseDetails, prefix) {
     }, childFailureReason({ exitCode: extraction.exitCode, aborted: extraction.aborted }));
 }
 export function registerPiWorkerDocs(pi, internals = {}) {
-    // CAP arm of nexttask 5B — OFF unless PI_TASK_PROJECT_DOCS_BUDGET is set, and
-    // then per-ATTEMPT by construction: the extension is loaded into a fresh pi
-    // child on every spawn, so a restarted attempt starts this counter at 0. The
-    // budget it enforces is the one the worker was told about in its prompt
-    // (projectDocsBudgetNotice) — enforcement without the notice would be a
-    // silent tool failure, and the notice without enforcement is what run 18
-    // already shows does not bind.
+    // Project-lookup budget — OFF unless PI_TASK_PROJECT_DOCS_BUDGET is set, and then
+    // per-ATTEMPT by construction: the extension is loaded into a fresh pi child on
+    // every spawn, so a restarted attempt starts this counter at 0. The budget it
+    // enforces is the one the worker was told about in its prompt
+    // (projectDocsBudgetNotice). Enforcement without the notice would be a silent
+    // tool failure; the notice without enforcement binds nothing.
     let projectLookups = 0;
     makeWorkerTool(pi, {
         name: 'pi-worker-docs',
@@ -121,12 +124,9 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             + '- You need docs for a specific newer version than what is installed — use pi-worker-fetch on the upstream docs site',
         parameters: Params,
         async run(params, signal, ctx) {
-            // Always node:child_process spawn (matching fetch-core and every other
-            // worker). The former globalThis.Bun branch called Bun.spawn — whose signature
-            // is Bun.spawn([cmd, ...args], opts), NOT the node (cmd, args, opts) that
-            // runChild/SpawnFn require — so it threw "cmd must be an array" whenever it ran.
-            // It was DEAD in production (pi runs under node) and BYPASSED under bun test
-            // (internals.spawn is always injected), i.e. untested, unreachable, and wrong.
+            // Always node:child_process spawn, matching fetch-core and every other
+            // worker. `SpawnFn` is the node `(cmd, args, opts)` shape; Bun.spawn takes
+            // `([cmd, ...args], opts)` and would throw here.
             const spawn = internals.spawn ?? defaultSpawn;
             // Both arms below run the SAME tail — concatenate, extract, verify,
             // format — through `docsLookup`; only the CORPUS differs. The
@@ -184,12 +184,10 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 if (r.kind === 'failed')
                     return docsFailureResult(r.extraction, baseDetails, '');
                 const { extraction, excerptVerified: verified, body: text } = r;
-                // SAME instrumentation channel as the package path below, extended to the
-                // project-source branch because that branch is the MAJORITY of what
-                // worker:apis asks — 13 of 17 docs calls in run 15's fatal task, 7 of 12 in
-                // the first live diagnostic rep. With only the package path recorded, "the
-                // last docs answer before the worker stopped" was unanswerable: the sink's
-                // last row was routinely not the worker's last answer.
+                // SAME instrumentation channel as the package path below. Both branches
+                // record, or "the last docs answer before the worker stopped" is
+                // unanswerable whenever the last answer came from the branch that does
+                // not log.
                 //
                 // `typeOnly` is recorded FALSE with an explicit reason rather than by running
                 // the detector: this path never applies it, and the record must say what the
@@ -239,11 +237,11 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                     hitCache: rawResult.hitCache,
                     cacheError: rawResult.cacheError,
                     autoInstalled: rawResult.autoInstalled,
-                    // BUG FIX. Both sibling arms carry the pin and this one dropped
-                    // it, so a package that WAS auto-installed and then failed to
-                    // re-resolve lost its `versionSource`/`declaredRange` — the
-                    // provenance the last defect in this area was about. `docsRaw`
-                    // sets `autoInstallPin` on three of its five error returns.
+                    // Carry the pin here as the sibling arms do. Without it a package
+                    // that WAS auto-installed and then failed to re-resolve loses its
+                    // `versionSource`/`declaredRange`, and the answer cannot say what
+                    // version it is grounded in. `docsRaw` sets `autoInstallPin` on
+                    // every error return that follows an auto-install.
                     ...pinDetails(rawResult.autoInstallPin),
                     ...npmDetails
                 };
@@ -265,7 +263,6 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                     ...npmDetails
                 });
             }
-            // kind === 'ok'
             const { pkg, chunks, hitCache, indexingMs, cacheError, autoInstalled } = rawResult;
             const versionBanner = buildVersionBanner(rawResult.autoInstallPin, pkg.name, pkg.version, ctx.cwd);
             const baseDetails = {
@@ -283,18 +280,16 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 return docsFailureResult(r.extraction, baseDetails, versionBanner + npmHeader);
             }
             const { extraction, excerptVerified: verified, body, content: concatenated } = r;
-            // F-2: a TYPE-ONLY answer is the dangerous failure. "unclear from this package"
+            // A TYPE-ONLY answer is the dangerous failure. "unclear from this package"
             // is honest and already escalates; a signature is a well-formed, confident,
             // on-topic answer that names the very parameter asked about, so the worker
-            // stops — and worker:context then fills the semantic gap from memory (F-1).
-            // Measured: 14 of 17 live reps terminated on exactly this shape.
+            // stops asking — and the semantic gap then gets filled from memory.
             //
             // The retrieved type is KEPT (it is real and useful) and an UNANSWERED banner
             // is prepended, naming the gap and — when the excerpt carries one — the `@see`
-            // URL that actually documents the semantics. That pointer is free: F-2(d) found
-            // hono.dev present in run-15 cache values ONLY inside these JSDoc links, never
-            // fetched. Prompting the escalation beats performing it here: this tool runs in
-            // parallel execution mode and cannot cleanly spawn a fetch of its own.
+            // URL that actually documents the semantics. Prompting the escalation beats
+            // performing it here: this tool runs in parallel execution mode and cannot
+            // cleanly spawn a fetch of its own.
             const typeOnly = isTypeOnlyAnswer(extraction.answer, params.query);
             let text = versionBanner + npmHeader + body;
             if (typeOnly.typeOnly) {
@@ -315,15 +310,14 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                         + '\nThe declaration that WAS retrieved (context only, not the answer):\n'
                         + body;
             }
-            // STAGE 1 INSTRUMENTATION — off unless PI_TASK_TYPEONLY_LOG names a sink, and
-            // side-effect only: nothing below reads it, and every failure inside is
-            // swallowed. It records EVERY answer, flagged or not, because the open question
-            // is a RATE — how often this fires — and a log of firings alone has no
-            // denominator. See typeonly-log.ts.
+            // Off unless PI_TASK_TYPEONLY_LOG names a sink, and side-effect only: nothing
+            // below reads it, and every failure inside is swallowed. It records EVERY
+            // answer, flagged or not — a log of firings alone would have no denominator to
+            // read a rate against. See typeonly-log.ts.
             //
-            // It sits AFTER `text` is final (it used to sit above `text`'s first assignment)
+            // It sits AFTER `text` is final, not above `text`'s first assignment,
             // so the record carries what the worker was actually handed, banner and cited
-            // excerpt included, not just the child's prose. Purely a move: logDocsAnswer
+            // excerpt included, not just the child's prose. Position only: logDocsAnswer
             // returns nothing and nothing between the two positions reads it, so the tool's
             // behaviour and its return value are unchanged.
             logDocsAnswer({
@@ -362,16 +356,12 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         // matched against package.json verbatim (npm names are case-sensitive), unlike
         // the cache key, which normalises for phrasing collisions.
         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.
-        //
-        // F-2(e): process health is NOT answer quality. A child that ran fine and answered
-        // "unclear from this package" exits 0, so the NON-ANSWER was memoised and re-served
-        // as a cache hit to every later sibling task — 52 of run 15's cached entries were
-        // "unclear" with hitCache true. One dead end, paid for many times, and escalation
-        // could never re-fire because the miss never recurred. So a non-answer is now never
-        // stored: the next task that asks pays for a real lookup and can escalate.
+        // Process health is NOT answer quality, and this rule only judges quality.
+        // not-installed, resolve and cache errors, and aborts return `unavailable`, which
+        // makeWorkerTool refuses before reaching here. What is left is real answers, and a
+        // child that ran fine and answered "unclear from this package" exits 0 — so a rule
+        // keyed on exit code would memoise that non-answer and re-serve it as a hit to
+        // every later sibling, with nothing left to re-trigger an escalation.
         //
         // `text` is supplied by makeWorkerTool (shared.ts) alongside details, so the
         // content check needs no new plumbing.
@@ -379,31 +369,32 @@ export function registerPiWorkerDocs(pi, internals = {}) {
     });
 }
 /**
- * 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 function docsCacheable(d, text) {
     // Answer QUALITY only. Whether there IS an answer is `WorkerOutcome.kind`, and
     // `makeWorkerTool` has already refused an `unavailable` before reaching here —
-    // this used to open with `childExitCode === 0`, which a signal-killed child
-    // satisfies, so an aborted lookup was memoised for the run.
+    // opening this with `childExitCode === 0` memoises an aborted lookup for the
+    // whole run, because a signal-killed child satisfies it.
     return 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. */
+/** 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 function docsCacheKey(params) {
     return params.module === '.' ?
         null
         : `${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`;
 }
-/** 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 function docsCachePkg(params) {
     return params.module === '.' ? undefined : packageRootOf(params.module);
 }

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

@@ -24,9 +24,13 @@ export interface PiWorkerFetchInternals {
 }
 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.
+ * The cache rule for the fetch channel, named for the same reason as `docsCacheable`:
+ * left anonymous inside the adapter literal, a test can only hand-retype it, and then
+ * asserts against a copy a change to the shipped rule would leave green.
+ *
+ * A coverage MISS is cacheable. "not covered by this page" is a real, correct answer
+ * ABOUT that page, and re-fetching cannot change it — only the abstention sentinel is
+ * refused.
  */
 export declare function fetchCacheable(_d: Pick<FetchDetails, never>, text: string): boolean;
 /** The fetch cache key. URL verbatim (path case can matter), question normalised —

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

@@ -1,6 +1,6 @@
 import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
-import { FetchAndCleanError } from './html-clean.js';
+import { fetchAndClean as defaultFetchAndClean, FetchAndCleanError } from './html-clean.js';
 import { fetchFocused } from './fetch-core.js';
 import { formatResultText } from '../shared/child-output.js';
 import { childFailureReason, makeWorkerTool, workerAnswer, workerUnavailable } from './shared.js';
@@ -47,8 +47,8 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                     spawn: internals.spawn
                 });
                 // Child failure is decided and formatted once, inside the focused extractor
-                // (workers/focused-extractor.ts) — this used to re-map the result back into a
-                // ChildOutcome just to ask formatChildFailure the same question.
+                // (workers/focused-extractor.ts) — re-mapping the result back into a
+                // ChildOutcome here would just ask formatChildFailure the same question.
                 if (result.failure !== undefined) {
                     return workerUnavailable(result.failure, { childExitCode: result.childExitCode }, childFailureReason({
                         exitCode: result.childExitCode,
@@ -85,30 +85,38 @@ export function registerPiWorkerFetch(pi, internals = {}) {
             text += `\n${theme.fg('dim', `  query: ${truncatedQuery}`)}`;
             return new Text(text, 0, 0);
         },
-        // Cache fetch answers per run (the same page re-fetched across sibling tasks
-        // otherwise). The URL is kept verbatim (path case can matter); the query is
-        // normalised. Both parts key the entry — same page, different question is a
+        // Cache fetch answers per run, or the same page is re-fetched by every sibling
+        // task. Both parts key the entry: the URL trimmed but otherwise VERBATIM, since
+        // path case can matter, and the query lowercased with its whitespace collapsed
+        // so phrasing variants share an entry. Same page, different question is a
         // different answer.
         cacheKey: fetchCacheKey,
-        // Only a completed fetch (child exited 0) is a real answer; invalid-URL,
-        // fetch failures, and aborts omit childExitCode:0 and fall through.
-        // F-2(e), on the fetch channel. A child that ran fine and answered
-        // "unclear from this page" exits 0, so caching on process health alone
-        // memoised the NON-ANSWER and re-served it to every later sibling task —
-        // the same dead-end-paid-many-times shape pi-worker-docs already closed
-        // for packages, with escalation unable to re-fire because the miss never
-        // recurred. One predicate now covers every corpus (workers/abstention.ts).
+        // Only a completed fetch is a real answer; invalid-URL, fetch failures and
+        // aborts come back as `unavailable`, which makeWorkerTool refuses before the
+        // cache is consulted at all.
+        //
+        // Process health is NOT answer quality. A child that ran fine and answered
+        // "unclear from this page" exits 0, so caching on health alone memoises the
+        // NON-ANSWER and re-serves it to every later sibling task — one dead end paid
+        // for many times, with escalation unable to re-fire because the miss never
+        // recurs. One predicate covers every corpus (workers/abstention.ts).
         cacheable: fetchCacheable
     });
 }
 /**
- * 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.
+ * The cache rule for the fetch channel, named for the same reason as `docsCacheable`:
+ * left anonymous inside the adapter literal, a test can only hand-retype it, and then
+ * asserts against a copy a change to the shipped rule would leave green.
+ *
+ * A coverage MISS is cacheable. "not covered by this page" is a real, correct answer
+ * ABOUT that page, and re-fetching cannot change it — only the abstention sentinel is
+ * refused.
  */
 export function fetchCacheable(_d, text) {
-    // Answer QUALITY only — see docsCacheable. `childExitCode === 0` used to lead
-    // this rule and was true of an aborted child, so `"Fetch aborted."` cached.
+    // Answer QUALITY only — see docsCacheable. This predicate returns true for
+    // `"Fetch aborted."` on its own; what keeps an aborted fetch out of the cache is
+    // the `unavailable` outcome upstream. Leading the rule with `childExitCode === 0`
+    // would not, because an aborted child settles at exit code 0.
     return !isAbstention(text);
 }
 /** The fetch cache key. URL verbatim (path case can matter), question normalised —

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

@@ -41,8 +41,9 @@ export function registerPiWorkerSearch(pi, internals = {}) {
                 return workerUnavailable(result.message, { resultCount: 0 }, result.kind);
             }
             const { results } = result;
-            // Zero results IS an answer: the search ran and the web has nothing.
-            // Only a search that could not run is unavailable.
+            // Zero results IS an answer: the search ran and the web has nothing, so it
+            // comes back as `workerAnswer` with resultCount 0. Only a search that could
+            // not run — no key, or an engine error — is `unavailable`.
             if (results.length === 0) {
                 return workerAnswer(`No results for: ${params.query}`, { resultCount: 0 });
             }
@@ -57,13 +58,16 @@ export function registerPiWorkerSearch(pi, internals = {}) {
             }
             return new Text(text, 0, 0);
         },
-        // Cache search results per run (the same query re-run across sibling tasks hits
-        // the live web anew otherwise). Count is part of the key — a larger request is a
-        // different result set — and so is the provider: two engines' result sets for
-        // one query are different answers and must not serve for each other.
+        // Cache search results per run, or the same query re-run by a sibling task hits
+        // the live web again. Three parts key the entry: the PROVIDER, because two
+        // engines' result sets for one query are different answers and must not serve
+        // for each other; the query, lowercased and whitespace-collapsed by
+        // `normalizeQuery` so phrasing variants share an entry; and the COUNT, because a
+        // larger request is a different result set.
         cacheKey: params => `${provider()}::${normalizeQuery(params.query)}::${params.count ?? ''}`,
-        // Only a non-empty result set is worth caching; no-key, error, and empty results
-        // (resultCount 0) fall through so a later attempt can succeed.
+        // Only a non-empty result set is worth caching. An empty one falls through so a
+        // later attempt can succeed; no-key and engine errors never reach this at all,
+        // since makeWorkerTool refuses to store an `unavailable` outcome.
         cacheable: d => d.resultCount > 0
     });
 }

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

@@ -1,10 +1,15 @@
 /**
  * pi-worker — minimal subagent tool.
  *
- * Spawns a sandboxed child `pi --print` for each call, returns its stdout.
- * Child has read+grep+find+ls only (no bash, write, or edit) — no skills,
- * extensions, prompt templates, context files, or session storage. Cannot
- * recurse into another worker.
+ * Spawns one child pi per call and returns its assistant text. `childBaseArgs`
+ * gives the child `--print --no-skills --no-extensions --no-prompt-templates
+ * --no-context-files --no-session`, and runWorker adds `--mode json` plus its
+ * default `--tools read,grep,find,ls`.
+ *
+ * That tool string is what makes the child read-only and non-recursive: no bash,
+ * write or edit, and no `pi-worker` of its own to dispatch. `--no-extensions`
+ * disables DISCOVERY, so the user's whitelisted `-e` extensions are still loaded
+ * — the tool whitelist, not the extension flag, is the bound that holds.
  */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 export declare function registerPiWorker(pi: ExtensionAPI): void;

package/dist/workers/pi-worker.js

@@ -1,10 +1,15 @@
 /**
  * pi-worker — minimal subagent tool.
  *
- * Spawns a sandboxed child `pi --print` for each call, returns its stdout.
- * Child has read+grep+find+ls only (no bash, write, or edit) — no skills,
- * extensions, prompt templates, context files, or session storage. Cannot
- * recurse into another worker.
+ * Spawns one child pi per call and returns its assistant text. `childBaseArgs`
+ * gives the child `--print --no-skills --no-extensions --no-prompt-templates
+ * --no-context-files --no-session`, and runWorker adds `--mode json` plus its
+ * default `--tools read,grep,find,ls`.
+ *
+ * That tool string is what makes the child read-only and non-recursive: no bash,
+ * write or edit, and no `pi-worker` of its own to dispatch. `--no-extensions`
+ * disables DISCOVERY, so the user's whitelisted `-e` extensions are still loaded
+ * — the tool whitelist, not the extension flag, is the bound that holds.
  */
 import { Text } from '@earendil-works/pi-tui';
 import { Type } from '@sinclair/typebox';
@@ -41,24 +46,26 @@ export function registerPiWorker(pi) {
             + '- The task needs the web — use `pi-worker-search` / `pi-worker-fetch`',
         parameters: WorkerParams,
         async run(params, signal, ctx) {
-            // Grouped with `research`: this is the same read-only exploration
-            // loop the four research workers run, just dispatched by a model
-            // rather than by the pipeline. Left ungrouped it would be the one
-            // child that never honoured a profile.
+            // `adhoc` guards, `research` thinking — deliberately not the same word.
+            // Guards answer "how may this child die"; the reasoning group answers
+            // "how hard may it think", and this is the same read-only exploration
+            // loop the research workers run, just dispatched by a model rather than
+            // by the pipeline. See the header of worker-profiles.ts.
             const result = await runWorker({
                 prompt: params.prompt,
                 cwd: ctx.cwd,
                 signal,
                 profile: 'adhoc',
-                // The user's own `stuck reply retry` is what bounds this worker
-                // now — it kills on SILENCE, never on slowness. It is an INPUT and
+                // The `adhoc` profile carries NO wall clock (`timeoutMs: 0`); what
+                // bounds this worker is the user's own `stuck reply retry` setting,
+                // which kills on SILENCE and never on slowness. It is an INPUT and
                 // not policy for the same reason the gate's two ceilings are: the
                 // number is the user's, the decision to arm it is the profile's.
                 policyInputs: { streamInactivityMs: getConfig().streamInactivityMs },
-                // The session's own window, handed down. The child is spawned
-                // without `-m`, so the parent's model IS the child's model and
-                // its window is the honest one. Without this the churn rule
-                // cannot fire — see RunWorkerInput.contextWindow.
+                // The session's own window, handed down. No child argv anywhere in
+                // this codebase passes `-m`, so the parent's model IS the child's
+                // model and its window is the honest one. Without this the churn
+                // rule cannot fire — see RunWorkerInput.contextWindow.
                 contextWindow: getParentContextWindow(ctx) || 'unknown',
                 thinking: groupThinkingArgs('research')
             });

package/dist/workers/reasoning-warning.d.ts

@@ -2,22 +2,22 @@
  * One-line startup hint shown when /task-config asks for a thinking level the
  * connected model will not honour.
  *
- * WHY IT HAS TO EXIST. pi never says it ignored or downgraded a level. Measured
- * live with a proxy on the request body: a model with `reasoning: false` given
- * `--thinking medium` sends no reasoning field at all, and a model whose
- * `thinkingLevelMap` nulls `off` given `--thinking off` is clamped UP to
- * `medium` — thinking stays on. Both are silent. A reasoning profile the user
- * set and the model erased is worse than no profile feature, because it looks
- * like it worked.
+ * WHY IT HAS TO EXIST. pi silently rewrites the level and says nothing. Its own
+ * `clampThinkingLevel` (pi-ai models.js) shows both halves: a model with
+ * `reasoning: false` supports only `["off"]`, so every requested level collapses
+ * there; and a level the model's `thinkingLevelMap` nulls is filtered out, after
+ * which the clamp scans UPWARD before downward — so asking for `off` on a model
+ * that nulls `off` gets the next level that IS available, and thinking stays on.
+ * A reasoning profile the user set and the model erased is worse than no profile
+ * feature, because it looks like it worked.
  *
  * ANTI-NAG. This warns once per session and clears on the first keystroke, and
  * that is the whole mechanism — deliberately no "already warned about model X"
  * file. Such a record goes stale the moment models.json is edited, and would
  * suppress the warning at exactly the moment a `/model` switch made it true.
- * brave-warning.ts nags every session for a standing misconfiguration and that
- * is correct; this is the same class. The real anti-nag is `inherit`: with the
- * shipped all-`inherit` table, `reasoningMismatches` returns empty for every
- * model and nothing renders at all.
+ * brave-warning.ts nags every session for a standing misconfiguration and that is
+ * correct; this is the same class. Setting a group back to `inherit` is what
+ * silences it: an all-`inherit` table yields no mismatches for any model.
  */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { type GroupSetting, type ReasoningGroup } from '../config/reasoning.js';
@@ -28,18 +28,19 @@ import { type ChatTemplateCaps } from '../shared/model-endpoint.js';
  *
  * Names the MODEL it checked, because children carry no `-m` and resolve pi's
  * default model, which need not be the host session's — a warning that does not
- * say what it looked at cannot be acted on. Names at most two groups; the count
- * carries the rest, since a line long enough to list seven is a line nobody
- * reads.
+ * say what it looked at cannot be acted on. Names at most two groups and appends
+ * `(+N more)` only when there are more than two, since a line long enough to list
+ * every group is a line nobody reads. Null when nothing mismatched.
  */
 export declare function formatReasoningWarning(modelName: string, mismatches: readonly ReasoningMismatch[]): string | null;
 /**
  * The extra cause line, when the SERVER disagrees with models.json.
  *
  * This is the `/login llama.cpp` case and the only thing the host-side clamp
- * cannot see: pi's built-in llama.cpp provider hardcodes `reasoning: false`, so
- * a perfectly capable server is described to pi as having no reasoning at all.
- * Returns null whenever the two agree, or when there was nothing to compare.
+ * cannot see: pi ships llama.cpp as a built-in extension whose provider entry
+ * hardcodes `reasoning: false`, so a perfectly capable server is described to pi
+ * as having no reasoning at all. Returns null whenever the two agree, and null
+ * when the probe answered nothing, so an unreachable server adds no cause line.
  */
 export declare function formatCapabilityConflict(serverSupportsEffort: boolean | null, modelDeclaresReasoning: boolean): string | null;
 export declare function registerReasoningWarning(pi: ExtensionAPI,