@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/workers/reasoning-warning.js

@@ -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 { getConfig } from '../config/config.js';
 import { effectiveReasoning } from '../config/reasoning.js';
@@ -30,9 +30,9 @@ const WIDGET_KEY = 'pi-task-reasoning-warning';
  *
  * 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 function formatReasoningWarning(modelName, mismatches) {
     if (mismatches.length === 0)
@@ -51,9 +51,10 @@ export function formatReasoningWarning(modelName, mismatches) {
  * 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 function formatCapabilityConflict(serverSupportsEffort, modelDeclaresReasoning) {
     if (serverSupportsEffort === null)
@@ -90,9 +91,10 @@ probe = probeChatTemplateCaps) {
         const base = formatReasoningWarning(model?.name ?? model?.id ?? 'unknown', mismatches);
         if (base === null)
             return null;
-        // Fire-and-forget: the server probe only ever REFINES the cause line, so
-        // it must not delay the warning or be able to prevent it. A 2s budget and
-        // a swallowed failure mean a non-llama.cpp backend costs nothing.
+        // Fire-and-forget: the server probe only ever REFINES the cause line, so it
+        // must not delay the warning or be able to prevent it. `probeChatTemplateCaps`
+        // carries its own short timeout and returns null on any failure, so a
+        // backend that does not answer `/props` costs nothing.
         const baseUrl = model?.baseUrl;
         if (model === undefined || baseUrl === undefined || baseUrl === '')
             return { text: base };

package/dist/workers/research-cache.js

@@ -2,13 +2,11 @@
  * research-cache — a per-run cache of docs/search/fetch worker RESULTS, shared
  * across the sibling task pipelines of one /task-auto run.
  *
- * The failure this serves (mx5 run 8, F10): the research phase alone burned 75 of
- * 363 minutes because ~20 sibling task pipelines each re-fetched the SAME external
- * docs and re-ran the SAME searches (the tailwind CLI docs fetched anew for task
- * after task). Each of those worker results is a deterministic function of (tool,
- * package/url, query) that does not change within a run — so the first pipeline to
- * ask a question can answer every later one from a shared digest instead of a fresh
- * network round-trip plus child-summariser spawn.
+ * The failure it serves: every sibling task pipeline in a run re-fetches the SAME
+ * external docs and re-runs the SAME searches. Each of those worker results is a
+ * deterministic function of (tool, package/url, query) that does not change within a
+ * run — so the first pipeline to ask a question can answer every later one from a
+ * shared digest instead of a fresh network round-trip plus a child-summariser spawn.
  *
  * SCOPE — stable external lookups only: npm-package docs, web search, web fetch. A
  * PROJECT-SOURCE (`.`) docs lookup is deliberately NOT cached: the working tree
@@ -25,27 +23,17 @@
  * a run started with the feature flag OFF (no id in the environment) does not cache
  * at all — the cache is inert unless the orchestrator turned it on for this run.
  *
- * RESUME REUSE (mx5 run 13, measured from the file's own git history — the cache is
- * committed with every task, so the whole run is recoverable): a 32-task run built the
- * cache to 201 entries over 20 tasks under one run id, then three /task-auto-resume
- * invocations each stamped a fresh id and the first store of each dropped everything —
- * 201 → 11 → 3 → 5 → 8. The audit read the 8-entry tail and concluded the cache was
- * near-useless; it was in fact working, and the resume threw the work away. The old
- * comment called a resume re-fetch "only slightly less reuse", which holds for a
- * 5-task run and fails badly for a 32-task one.
+ * RESUME REUSE. A resume that stamps a fresh id makes the first store drop everything
+ * the interrupted run had built, so the longer the run, the more a resume throws away.
+ * A resume therefore REUSES the interrupted run's id — but only on POSITIVE evidence
+ * that the digests still describe the same dependency surface.
  *
- * So a resume now REUSES the interrupted run's id — but only on POSITIVE evidence that
- * the digests still describe the same dependency surface.
+ * PER-PACKAGE INVALIDATION. One fingerprint over the whole dependency block cannot be
+ * that evidence: a greenfield run ADDS dependencies every few tasks, so every resume
+ * sees a moved fingerprint and keeps nothing. Adding a package invalidates nothing that
+ * was already cached; only the package a digest is ABOUT going stale does.
  *
- * PER-PACKAGE INVALIDATION (mx5 run 14). The first shape of that evidence was one md5
- * over the whole dependency block: any change anywhere ⇒ wipe. That gate can never hold
- * on the projects /task actually builds — a greenfield run ADDS dependencies every few
- * tasks (run 14: hono/zod at T10, shadcn at T25, playwright-ct at T28), so all five of
- * its resumes saw a moved fingerprint and the run ended with ONE cached entry. Adding a
- * package invalidates nothing that was already cached; only the package a digest is
- * ABOUT going stale does.
- *
- * So invalidation is now per entry. Every docs entry records the package it describes
+ * So invalidation is per entry. Every docs entry records the package it describes
  * and the version declared for it at store time (a structured field on the entry, not
  * something re-parsed out of the key — keys embed the tool name with a \0 separator and
  * are the wrong place to carry meaning). A resume keeps the run id and drops only the
@@ -53,45 +41,38 @@
  *
  * STALENESS TRADE, decided deliberately: search and fetch entries are kept
  * unconditionally, even across a dependency bump. A kept search result about package X
- * may describe an older X. That is accepted — docs is the version-sensitive channel (it
- * is version-pinned to the INSTALLED package since pi-worker fixes #1) and search is
- * discovery, where re-running every query on every resume costs far more than the rare
- * staleness costs. A run that must not tolerate it can disable the cache outright.
+ * may describe an older X. That is accepted — docs is the version-sensitive channel,
+ * pinned to the INSTALLED package, and search is discovery, where re-running every query
+ * on every resume costs far more than the rare staleness does. A run that must not
+ * tolerate it can disable the cache outright.
  *
  * A file written before per-entry provenance shipped (no `pkgv` marker) carries no way
  * to tell its docs entries apart, so it still falls back to a fresh id: every
  * inconclusive path costs time, never correctness.
  *
- * CONCURRENT WRITERS (nexttask TASK 4). Storing is a read-modify-write over ONE file,
- * and its writers are concurrent on two axes at once: makeWorkerTool registers the
- * research tools with executionMode 'parallel', so a single child can issue 4-6 docs
- * calls in the same millisecond, and the research phase runs four worker children as
- * separate PROCESSES. Unsynchronised, that is a classic lost update — last writer wins,
- * and everything read before it is discarded. Measured on this box: 40 concurrent stores
- * left 1 entry in-process and 11 of 40 across four child processes.
+ * CONCURRENT WRITERS. Storing is a read-modify-write over ONE file, and its writers are
+ * concurrent on two axes at once: makeWorkerTool registers the research tools with
+ * `executionMode: 'parallel'`, so a single child can issue several docs calls in the same
+ * millisecond, and the research phase runs its worker children as separate PROCESSES.
+ * Unsynchronised, that is a classic lost update — last writer wins, and everything read
+ * before it is discarded.
  *
  * So the read-modify-write is serialised twice over: an in-process queue per cache file
  * (siblings inside one child never touch the filesystem lock at all) wrapped in an
  * advisory lock directory beside the file, which is what makes it hold across processes.
- * An atomic `mkdir` is the lock — it is the one primitive that both POSIX and Windows
- * give us with create-or-fail semantics and no fd bookkeeping.
+ * An atomic `mkdir` is the lock — create-or-fail with no fd bookkeeping. With both in
+ * place, 40 concurrent stores keep 40 entries, whether they come from one process or
+ * from four.
  *
  * The lock is BEST-EFFORT LIKE EVERYTHING ELSE HERE: acquisition is bounded, and a
  * writer that cannot get in within the timeout SKIPS its store rather than waiting. A
  * skipped store costs one re-lookup later; a blocked store would stall a worker, which
- * this cache is never allowed to do.
- *
- * WHAT THE FIX IS WORTH, measured before it was built (scripts/research-cache-
- * write-loss-step0.ts, re-runnable): the lost updates are real but nearly free. mx5 lost
- * ~70 of 204 attempted keys, all in the docs channel — and asked ZERO of them twice, so
- * nothing lost was ever wanted again. IAR1 and godot-engine retained more distinct keys
- * than the logs show attempted, i.e. lost nothing at all. Estimated recovery on all three
- * projects: 0s per run. This is a correctness fix, not a performance one; it stops the
- * cache silently discarding work, and it will matter to a run whose research phase does
- * repeat itself. Do not oversell it.
+ * this cache is never allowed to do. This is a correctness fix, not a performance one:
+ * it stops the cache silently discarding work.
  *
  * Stored under `.pi-tasks/` (sibling of env-notes.md / contracts.md), which the
- * git-state guard and discardEdits both exclude. Best-effort throughout: any I/O or
+ * git-state guard excludes by pathspec (`:(exclude).pi-tasks`) and discardEdits leaves
+ * alone. Best-effort throughout: any I/O or
  * parse failure falls back to a live fetch — the cache only ever saves time, it can
  * never change an answer or block a worker.
  */
@@ -103,16 +84,14 @@ const RESEARCH_CACHE_FILE = 'research-cache.json';
 export const RESEARCH_RUN_ID_ENV = 'PI_TASK_RUN_ID';
 /**
  * Cap stored entries so a chatty run cannot grow the file unboundedly; the newest
- * (by write time) are kept. Sized well above a 20-task run's distinct external
- * lookups (dozens), so a real run never evicts a still-useful digest.
+ * (by write time) are kept and the oldest evicted.
  */
 const MAX_ENTRIES = 250;
 /** Lock directory guarding the cache file's read-modify-write, created beside it. */
 const LOCK_SUFFIX = '.lock';
 /**
- * How long a writer waits for the lock before giving up and skipping its store. Sized
- * well above a real critical section (one small read + one small write, sub-millisecond
- * at these file sizes) and well below anything a worker would notice.
+ * How long a writer waits for the lock before giving up and skipping its store. The
+ * critical section it queues behind is one small read plus one small write.
  */
 const LOCK_TIMEOUT_MS = 2_000;
 /** Poll interval while the lock is held by someone else. */
@@ -125,26 +104,20 @@ const LOCK_POLL_MS = 10;
 const RENAME_TIMEOUT_MS = 500;
 /**
  * A lock older than this is treated as abandoned and removed. Two writers can both
- * decide that and both proceed, which degrades exactly to the pre-lock behaviour (one
- * lost update) — strictly better than a crashed child wedging the cache for the rest of
- * the run. Sized far above the critical section, so a live holder is never stolen from.
+ * decide that and both proceed, which degrades to one lost update — strictly better
+ * than a crashed child wedging the cache for the rest of the run. Sized far above the
+ * critical section, so a live holder is never stolen from.
  */
 const LOCK_STALE_MS = 30_000;
 /**
  * Filesystem errors that mean "try again in a moment", not "this will never work".
  *
  * POSIX gives `mkdir` two clean answers when someone else holds the lock: it succeeds,
- * or it is EEXIST. Windows has a third. A directory that another process is removing
- * enters a DELETE-PENDING state, and a create against it fails with EPERM/EACCES/EBUSY
- * instead of EEXIST — so the exact moment the previous writer released the lock is a
- * window in which the next writer's `mkdir` fails with a code that used to be read as
- * fatal. The store was then silently skipped: no throw, no log, exit code 0, one entry
- * missing. That is the whole of CI's `39 of 40` on windows-latest; the same run's
- * ubuntu half is green because POSIX never produces the code.
- *
- * `rename` over an existing file has the same shape on Windows — it fails while any
- * other handle is open on the target, including a scanner's — so the cache write
- * retries on this set too.
+ * or it is EEXIST. Other platforms add more, and a lock contention reported under a code
+ * an EEXIST-only check reads as fatal skips the store SILENTLY — no throw, no log, exit
+ * code 0, one entry missing. `rename` over an existing file has the same shape. Both
+ * therefore retry on this whole set; research-cache.test.ts is what holds the membership
+ * in place.
  */
 const RETRYABLE_FS_CODES = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY', 'ENOTEMPTY']);
 /** Is this a transient filesystem error worth retrying inside the caller's deadline? */
@@ -343,11 +316,10 @@ async function writeCacheFile(cwd, out) {
     try {
         await fsp.mkdir(tasksDir(cwd), { recursive: true });
         await fsp.writeFile(tmp, JSON.stringify(out), 'utf8');
-        // The replace, not the write, is the part Windows can transiently refuse — any
-        // other open handle on the target (a reader, a scanner) fails it with EPERM.
-        // The whole point of the lock above is that this write is not lost, so a
-        // transient refusal is retried inside the same bounded budget rather than
-        // swallowed. The lock is still held throughout.
+        // The replace, not the write, is the part a filesystem can transiently refuse
+        // when another handle is open on the target. The whole point of the lock above
+        // is that this write is not lost, so a refusal in RETRYABLE_FS_CODES is retried
+        // inside a bounded budget rather than swallowed. The lock is held throughout.
         const deadline = Date.now() + RENAME_TIMEOUT_MS;
         for (;;) {
             try {
@@ -391,10 +363,10 @@ async function acquireLock(lockPath, deadline) {
         catch (err) {
             if (!isRetryableFsError(err))
                 return false;
-            // Not EEXIST but still retryable ⇒ Windows delete-pending (see
-            // RETRYABLE_FS_CODES). There is no lock to inspect for staleness: the
-            // directory is on its way out, so wait one poll and try to create it again
-            // rather than reporting a hold that nobody has.
+            // Retryable but NOT EEXIST ⇒ the directory is on its way out (see
+            // RETRYABLE_FS_CODES), so there is no lock to inspect for staleness. Wait
+            // one poll and try to create it again rather than reporting a hold that
+            // nobody has.
             if (!isHeldError(err)) {
                 if (Date.now() >= deadline)
                     return false;

package/dist/workers/search-core.js

@@ -45,11 +45,13 @@ export async function search(input) {
     }
     catch (err) {
         // Which throws already carry a finished user-facing message is the engine's
-        // own fact, so it is a row. This used to be an `err.name ===
-        // 'BraveSearchError'` STRING match in a brave-only branch — the check
-        // existed only because brave was reached down a different path from the
-        // other two, and it is the reason a subclass rename would have gone
-        // unnoticed.
+        // own fact, so `errorName` is a row rather than an `err.name` check welded
+        // into a brave-only branch. It stays a STRING match either way — a class
+        // rename that leaves the row untouched goes unnoticed, and only the wrapped
+        // wording changes.
+        //
+        // No `errorName` means every throw's message is used verbatim; a name that
+        // does not match is passed through `wrapUnknownError`.
         const message = err instanceof Error ? err.message : String(err);
         const known = adapter.errorName === undefined
             || (err instanceof Error && err.name === adapter.errorName);

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

@@ -8,26 +8,27 @@ export interface SearchResult {
  * Which engine backs pi-worker-search and the freshness/enrichment lookups.
  * - `exa`   — Exa's public MCP endpoint; no key needed (default).
  * - `ddg`   — DuckDuckGo's HTML endpoint; no key needed.
- * - `brave` — Brave Search API; needs BRAVE_SEARCH_API_KEY.
+ * - `brave` — Brave Search API; needs BRAVE_SEARCH_API_KEY, or BRAVE_API_KEY.
  */
 export type SearchProvider = 'exa' | 'ddg' | 'brave';
 export declare const SEARCH_PROVIDERS: readonly SearchProvider[];
 /**
  * The API-key env vars an engine needs, in lookup order. Empty = keyless.
  *
- * Declared beside the engine ids rather than inside `search()`, because two
- * places ask the question: the search itself, and `searchConfigured` in
- * phases.ts, which decides whether the APIS research worker is even given the
- * search tool. That second copy was a hand-written re-statement of brave's env
- * pair with a comment saying it "mirrors search-core's lookup" — the shape a
- * table exists to make impossible.
+ * Declared beside the engine ids rather than inside `search()`, because two places
+ * ask the question: the search itself, and `searchConfigured` in phases.ts, which
+ * decides whether the APIS research worker is handed the search tool at all. Both
+ * go through {@link searchProviderKey}, so neither can restate the env pair.
  */
 export declare const SEARCH_PROVIDER_KEY_ENV: Record<SearchProvider, readonly string[]>;
-/** The engine's key, or `null` when it needs one and none is set. `''` = keyless. */
+/** The engine's key, or `null` when it needs one and none is set. `''` = keyless.
+ *  The vars are tried in list order and the first non-empty one wins. */
 export declare function searchProviderKey(provider: SearchProvider, getEnv: (k: string) => string | undefined): string | null;
 /**
  * Human-readable engine names for the config UI. The short ids stay the stored
- * value (config-file compat); only the display layer uses these.
+ * value, so a config file survives a label change; register.ts is the display
+ * layer that maps between them, and search-core uses a label only inside a
+ * fallback message.
  */
 export declare const SEARCH_PROVIDER_LABELS: Record<SearchProvider, string>;
 export declare function providerForLabel(label: string): SearchProvider | undefined;

package/dist/workers/search-types.js

@@ -2,19 +2,18 @@ export const SEARCH_PROVIDERS = ['exa', 'ddg', 'brave'];
 /**
  * The API-key env vars an engine needs, in lookup order. Empty = keyless.
  *
- * Declared beside the engine ids rather than inside `search()`, because two
- * places ask the question: the search itself, and `searchConfigured` in
- * phases.ts, which decides whether the APIS research worker is even given the
- * search tool. That second copy was a hand-written re-statement of brave's env
- * pair with a comment saying it "mirrors search-core's lookup" — the shape a
- * table exists to make impossible.
+ * Declared beside the engine ids rather than inside `search()`, because two places
+ * ask the question: the search itself, and `searchConfigured` in phases.ts, which
+ * decides whether the APIS research worker is handed the search tool at all. Both
+ * go through {@link searchProviderKey}, so neither can restate the env pair.
  */
 export const SEARCH_PROVIDER_KEY_ENV = {
     exa: [],
     ddg: [],
     brave: ['BRAVE_SEARCH_API_KEY', 'BRAVE_API_KEY']
 };
-/** The engine's key, or `null` when it needs one and none is set. `''` = keyless. */
+/** The engine's key, or `null` when it needs one and none is set. `''` = keyless.
+ *  The vars are tried in list order and the first non-empty one wins. */
 export function searchProviderKey(provider, getEnv) {
     const vars = SEARCH_PROVIDER_KEY_ENV[provider];
     if (vars.length === 0)
@@ -28,7 +27,9 @@ export function searchProviderKey(provider, getEnv) {
 }
 /**
  * Human-readable engine names for the config UI. The short ids stay the stored
- * value (config-file compat); only the display layer uses these.
+ * value, so a config file survives a label change; register.ts is the display
+ * layer that maps between them, and search-core uses a label only inside a
+ * fallback message.
  */
 export const SEARCH_PROVIDER_LABELS = {
     exa: 'Exa',

package/dist/workers/session-hint.d.ts

@@ -1,29 +1,28 @@
 /**
  * A one-line startup hint in the TUI, and the whole widget lifetime around it.
  *
- * WHY IT IS ONE MODULE. Two hints exist (brave-warning, reasoning-warning) and
- * both had written the same ritual out: the `session_start` subscription, the
- * TUI gate, the `setWidget` in a try/catch, the `onTerminalInput` that clears on
- * the first keystroke, the unsubscribe, and the swallow for a stale ctx — down
- * to a byte-identical comment. Two adapters is a real seam, so the ritual lives
- * here once and each hint supplies only its `compose`.
+ * WHY IT IS ONE MODULE. Its two callers — brave-warning and reasoning-warning —
+ * would otherwise each write the same ritual: the `session_start` subscription,
+ * the TUI gate, the `setWidget` in a try/catch, the `onTerminalInput` that clears
+ * on the first keystroke, the unsubscribe, and the swallow for a stale ctx. Here
+ * the ritual lives once and each hint supplies only its `compose`.
  *
  * The REFINE half is why this is not just deduplication. A hint may learn
- * something after it has painted (the reasoning hint probes the model's server),
+ * something after it has painted — the reasoning hint probes the model's server —
  * and the rule that a refinement must never repaint a widget the user already
- * dismissed lived in one closure variable in one of the two files. It is now a
- * property of this module, asserted once.
+ * dismissed is a property of this module rather than a closure variable in one of
+ * the two files. session-hint.test.ts is where it is asserted.
  */
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 export interface SessionHint {
     /** The line to paint now. */
     text: string;
     /**
-     * A later refinement of that line, if this hint has one. Resolving to null —
-     * or rejecting — leaves the first line standing, so a refinement can never
-     * remove a warning it was only meant to sharpen. It is fire-and-forget: it
-     * cannot delay or prevent the first paint, and it is dropped if the user has
-     * already cleared the hint.
+     * A later refinement of that line, if this hint has one. Resolving to null — or
+     * rejecting — leaves the first line standing, so a refinement can never remove a
+     * warning it was only meant to sharpen. It is fire-and-forget: it cannot delay
+     * or prevent the first paint, and a refinement that lands AFTER the user cleared
+     * the hint repaints nothing.
      */
     refine?: Promise<string | null>;
 }

package/dist/workers/session-hint.js

@@ -1,18 +1,17 @@
 /**
  * A one-line startup hint in the TUI, and the whole widget lifetime around it.
  *
- * WHY IT IS ONE MODULE. Two hints exist (brave-warning, reasoning-warning) and
- * both had written the same ritual out: the `session_start` subscription, the
- * TUI gate, the `setWidget` in a try/catch, the `onTerminalInput` that clears on
- * the first keystroke, the unsubscribe, and the swallow for a stale ctx — down
- * to a byte-identical comment. Two adapters is a real seam, so the ritual lives
- * here once and each hint supplies only its `compose`.
+ * WHY IT IS ONE MODULE. Its two callers — brave-warning and reasoning-warning —
+ * would otherwise each write the same ritual: the `session_start` subscription,
+ * the TUI gate, the `setWidget` in a try/catch, the `onTerminalInput` that clears
+ * on the first keystroke, the unsubscribe, and the swallow for a stale ctx. Here
+ * the ritual lives once and each hint supplies only its `compose`.
  *
  * The REFINE half is why this is not just deduplication. A hint may learn
- * something after it has painted (the reasoning hint probes the model's server),
+ * something after it has painted — the reasoning hint probes the model's server —
  * and the rule that a refinement must never repaint a widget the user already
- * dismissed lived in one closure variable in one of the two files. It is now a
- * property of this module, asserted once.
+ * dismissed is a property of this module rather than a closure variable in one of
+ * the two files. session-hint.test.ts is where it is asserted.
  */
 /**
  * Register one startup hint.

package/dist/workers/shared.d.ts

@@ -19,19 +19,16 @@ export interface ChildOutcome {
  * The one place worker child-failure is turned into a user-facing message.
  * Returns `null` when the child succeeded (caller proceeds to format output).
  *
- * It ASKS THE LADDER now (`classifyWorkerFailure` -> `describeWorkerFailure`)
- * rather than re-deriving the answer from two fields. It used to be
- * `if (aborted) return abortedMessage`, and every kill path also sets `aborted`,
- * so a wall-clock kill, a hung command, a dead backend, a loop kill and a user
- * ESC all produced the same four words — while `childFailureReason`, one line
- * later at the only caller that had the richer result, computed the real cause
- * and sent it to a debug trail nobody reads. That is the same shape as the bug
- * `worker-failure.ts`'s own header records, one layer out: a second author of a
- * taxonomy the module exists to own.
+ * It ASKS THE LADDER (`classifyWorkerFailure` -> `describeWorkerFailure`) rather
+ * than re-deriving the answer from two fields. Every kill path also sets
+ * `aborted`, so an `if (aborted) return abortedMessage` would give a wall-clock
+ * kill, a hung command, a dead backend, a loop kill and a user ESC the same four
+ * words. Through the ladder each gets its own diagnosis.
  *
- * A caller with only a `ChildOutcome` is unaffected. It carries no kill flags,
- * so the ladder falls through to `aborted`/`exit` and returns exactly what this
- * function returned before — which `shared.test.ts` pins.
+ * A caller with only a `ChildOutcome` is unaffected: it carries no kill flags, so
+ * the ladder falls through to `aborted`/`exit` — null on a clean exit, the abort
+ * message when aborted, and `Worker exited N` plus the stderr tail otherwise.
+ * `shared.test.ts` pins those three.
  */
 export declare function formatChildFailure(child: ChildOutcome | (WorkerFailureInput & {
     stderr?: string;
@@ -39,15 +36,13 @@ export declare function formatChildFailure(child: ChildOutcome | (WorkerFailureI
 /**
  * What a worker tool PRODUCED — an answer, or a statement that it has none.
  *
- * This used to be a bare `{text, details}` bag, and "did it succeed" was
- * re-derived downstream from `details.childExitCode === 0`. That derivation was
- * wrong in the one case it most needed to be right: a signal-killed child reports
- * `code ?? 0` = 0 (shared/child-process.ts), so an aborted lookup arrived with
- * exit code 0, `docsCacheable`/`fetchCacheable` said yes, and `"Docs lookup
- * aborted."` was memoised for the whole run and re-served to every later sibling —
- * exactly the failure `abstention.ts` exists to stop, with escalation unable to
- * re-fire. `docsFailureResult`'s own contract said it recorded the code "NOT as
- * 0"; the value it copied was 0.
+ * As a bare `{text, details}` bag, "did it succeed" gets re-derived downstream
+ * from `details.childExitCode === 0`. That derivation is wrong in the one case it
+ * most needs to be right: node reports a signal kill as `close` with
+ * `code === null`, which child-process.ts settles as `code ?? 0` — so an ABORTED
+ * lookup arrives carrying exit code 0, the cache rules say yes, and
+ * `"Docs lookup aborted."` is memoised for the whole run and re-served to every
+ * later sibling.
  *
  * Stating the outcome makes that unrepresentable: `makeWorkerTool` stores only an
  * `answer`, so no cache rule has to know anything about process health, and the
@@ -92,20 +87,21 @@ export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
     run(params: Static<TParams>, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<WorkerOutcome<TDetails>>;
     renderCall(args: Static<TParams>, theme: Theme): Text;
     /**
-     * Per-run research-cache policy (F10). Return a stable cache key for this call —
+     * Per-run research-cache policy. Return a stable cache key for this call —
      * a result keyed on it is a deterministic function of the inputs that does not
      * change within a run, so a later sibling task can reuse it instead of re-running
      * the network fetch + child summariser. Return `null` to opt a particular call
      * OUT of caching (e.g. a project-source `.` lookup, whose answer the working tree
      * mutates within a run). Omit entirely and the tool is never cached. The stored
-     * key is namespaced by tool name, so keys need only be unique within a tool.
+     * key is namespaced by tool name — joined with a literal NUL, which is why the
+     * separator is invisible to `grep` and to a plain editor.
      */
     cacheKey?(params: Static<TParams>): string | null;
     /**
      * The npm package this call's answer is ABOUT, for a package-scoped tool (docs).
      * Recorded as structured provenance on the cache entry so a resume can drop just the
-     * entries whose package moved version, instead of the whole run's cache (run 14: a
-     * greenfield run adds packages every few tasks, so a whole-file gate never holds).
+     * entries whose package moved version, instead of the whole run's cache. A
+     * greenfield run adds packages every few tasks, so a whole-file gate never holds.
      * Omit — or return undefined — and the entry survives every resume of its run.
      */
     cachePkg?(params: Static<TParams>): string | undefined;

package/dist/workers/single-read-extension.d.ts

@@ -1,11 +1,18 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 /**
- * Loaded via `-e` into the TOOLING research worker only. Two in-run thrash
- * blocks, each returning a reason the model receives as an error tool result
- * (agent-loop: block → createErrorToolResult) so the worker continues instead of
- * looping:
- *   - read: blocks a re-read of LINES already delivered; forward paging passes.
- *   - grep/find/ls: blocks an identical repeat of the same call (args-keyed).
- * See single-read-guard.ts for why this is scoped to TOOLING.
+ * Loaded via `-e` into two kinds of child, both of which have their source
+ * INLINED and so can only be thrashing when they re-read: the TOOLING research
+ * worker (phases.ts) and the planning children (auto-orchestrator.ts).
+ *
+ * Two in-run blocks. Each returns a `reason`, which pi turns into an error tool
+ * result — `agent-loop.js` does `createErrorToolResult(beforeResult.reason)` on a
+ * blocked call — so the child reads the explanation and continues instead of
+ * dying:
+ *   - read: blocks a re-read of LINES already delivered; forward paging passes,
+ *     and the reason names the line to resume from.
+ *   - grep/find/ls: blocks a byte-identical repeat, keyed on the args; a call
+ *     with any different argument passes.
+ * A tool outside this set is never touched. See single-read-guard.ts for why the
+ * read-once rule is safe only where it is armed.
  */
 export default function (pi: ExtensionAPI): void;

package/dist/workers/single-read-extension.js

@@ -3,13 +3,20 @@ import { RepeatedCallGuard, SingleReadGuard } from './single-read-guard.js';
 /** Read-like tools whose byte-identical repeats are blocked (read is handled separately). */
 const DEDUP_TOOLS = new Set(['grep', 'find', 'ls']);
 /**
- * Loaded via `-e` into the TOOLING research worker only. Two in-run thrash
- * blocks, each returning a reason the model receives as an error tool result
- * (agent-loop: block → createErrorToolResult) so the worker continues instead of
- * looping:
- *   - read: blocks a re-read of LINES already delivered; forward paging passes.
- *   - grep/find/ls: blocks an identical repeat of the same call (args-keyed).
- * See single-read-guard.ts for why this is scoped to TOOLING.
+ * Loaded via `-e` into two kinds of child, both of which have their source
+ * INLINED and so can only be thrashing when they re-read: the TOOLING research
+ * worker (phases.ts) and the planning children (auto-orchestrator.ts).
+ *
+ * Two in-run blocks. Each returns a `reason`, which pi turns into an error tool
+ * result — `agent-loop.js` does `createErrorToolResult(beforeResult.reason)` on a
+ * blocked call — so the child reads the explanation and continues instead of
+ * dying:
+ *   - read: blocks a re-read of LINES already delivered; forward paging passes,
+ *     and the reason names the line to resume from.
+ *   - grep/find/ls: blocks a byte-identical repeat, keyed on the args; a call
+ *     with any different argument passes.
+ * A tool outside this set is never touched. See single-read-guard.ts for why the
+ * read-once rule is safe only where it is armed.
  */
 export default function (pi) {
     const reads = new SingleReadGuard();