@mjasnikovs/pi-task 0.38.22 → 0.38.24

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

@@ -0,0 +1,72 @@
+/**
+ * The docs TAIL — concatenate the chunks, extract against them, verify the
+ * citation, format the answer — written once, with the corpus as a row.
+ *
+ * WHY. This sequence existed three times: the project-source arm of
+ * `pi-worker-docs`, its package arm, and `docsFocused` in `docs-core`. The fetch
+ * channel proves the shape is avoidable — `fetchFocused` is one core and
+ * `pi-worker-fetch`'s `run` is 60 lines, while the docs registration was 293 for
+ * the same job over two corpora.
+ *
+ * The copies had drifted, in the place hand-flattening always drifts: the
+ * package arm's ERROR path dropped `autoInstallPin`, which both of its sibling
+ * paths keep — so a package that was auto-installed and then failed to re-resolve
+ * lost the `versionSource`/`declaredRange` provenance the last defect in this
+ * area was about.
+ *
+ * A CORPUS is what genuinely varies: the prompt, the header the answer is
+ * introduced by, and what an abort of it is called. Everything a corpus does NOT
+ * vary — where the content comes from, the version banner, the type-only
+ * detector, the details bag — stays with its caller, because those differ in kind
+ * and not in value.
+ */
+import type { SpawnFn } from '../shared/child-process.js';
+import { type FocusedAnswer, type FocusedFailure } from './focused-extractor.js';
+/** The two corpora a docs lookup can read. A third (`page`) already has a prompt. */
+export type DocsCorpusId = 'package' | 'project';
+export interface DocsCorpus {
+    id: DocsCorpusId;
+    /** The extraction prompt for this corpus, over the concatenated content. */
+    buildPrompt: (query: string, content: string) => string;
+    /** The line the formatted answer is introduced by. */
+    header: string;
+    /** What an abort of this corpus's lookup is called, in the failure text. */
+    abortedMessage: string;
+}
+export interface DocsLookupInput {
+    corpus: DocsCorpus;
+    /** The retrieved chunks, in retrieval order. */
+    chunks: ReadonlyArray<{
+        content: string;
+    }>;
+    query: string;
+    cwd: string;
+    signal?: AbortSignal;
+    spawn?: SpawnFn;
+    /**
+     * The `extraction` group's `--thinking` fragment. Resolved by the CALLER so
+     * this module — like the extractor it wraps — never reads ambient config.
+     */
+    thinking: readonly string[];
+}
+export type DocsLookup = {
+    kind: 'answer';
+    /** The formatted answer: header, answer, and the verified excerpt. */
+    body: string;
+    /** Exactly what was prompted with, and what the citation was verified against. */
+    content: string;
+    extraction: FocusedAnswer;
+    /** Undefined when there was no excerpt to check. */
+    excerptVerified?: boolean;
+} | {
+    kind: 'failed';
+    extraction: FocusedFailure;
+};
+/**
+ * Run one docs lookup over already-retrieved chunks.
+ *
+ * The citation is verified against exactly the text that was prompted with — the
+ * concatenation, not a superset. (`fetch` is the one site that verifies against a
+ * superset; see `FocusedRequest.verifyAgainst`.)
+ */
+export declare function docsLookup(input: DocsLookupInput): Promise<DocsLookup>;

package/dist/workers/docs-lookup.js

@@ -0,0 +1,53 @@
+/**
+ * The docs TAIL — concatenate the chunks, extract against them, verify the
+ * citation, format the answer — written once, with the corpus as a row.
+ *
+ * WHY. This sequence existed three times: the project-source arm of
+ * `pi-worker-docs`, its package arm, and `docsFocused` in `docs-core`. The fetch
+ * channel proves the shape is avoidable — `fetchFocused` is one core and
+ * `pi-worker-fetch`'s `run` is 60 lines, while the docs registration was 293 for
+ * the same job over two corpora.
+ *
+ * The copies had drifted, in the place hand-flattening always drifts: the
+ * package arm's ERROR path dropped `autoInstallPin`, which both of its sibling
+ * paths keep — so a package that was auto-installed and then failed to re-resolve
+ * lost the `versionSource`/`declaredRange` provenance the last defect in this
+ * area was about.
+ *
+ * A CORPUS is what genuinely varies: the prompt, the header the answer is
+ * introduced by, and what an abort of it is called. Everything a corpus does NOT
+ * vary — where the content comes from, the version banner, the type-only
+ * detector, the details bag — stays with its caller, because those differ in kind
+ * and not in value.
+ */
+import { formatResultText } from '../shared/child-output.js';
+import { runFocusedExtraction } from './focused-extractor.js';
+/**
+ * Run one docs lookup over already-retrieved chunks.
+ *
+ * The citation is verified against exactly the text that was prompted with — the
+ * concatenation, not a superset. (`fetch` is the one site that verifies against a
+ * superset; see `FocusedRequest.verifyAgainst`.)
+ */
+export async function docsLookup(input) {
+    const content = input.chunks.map(c => c.content).join('\n\n');
+    const extraction = await runFocusedExtraction({
+        prompt: input.corpus.buildPrompt(input.query, content),
+        verifyAgainst: content,
+        cwd: input.cwd,
+        signal: input.signal,
+        spawn: input.spawn,
+        thinking: input.thinking,
+        abortedMessage: input.corpus.abortedMessage
+    });
+    if (!extraction.ok)
+        return { kind: 'failed', extraction };
+    const excerptVerified = extraction.excerptVerified;
+    return {
+        kind: 'answer',
+        body: formatResultText(input.corpus.header, extraction, excerptVerified),
+        content,
+        extraction,
+        excerptVerified
+    };
+}

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

@@ -1,6 +1,7 @@
 import type { CacheHandle } from './docs-cache.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import type { RetrievedChunk } from './docs-retrieve.js';
+import type { DocsCorpus } from './docs-lookup.js';
 export declare function getProjectName(cwd: string): string;
 export declare function cwdKey(cwd: string): string;
 /**
@@ -50,3 +51,11 @@ export declare function projectDocsRaw(cache: CacheHandle, cwd: string, query: s
 /** How to enumerate the project's sources. See getProjectFiles. */
 listFiles?: (cwd: string) => string[]): ProjectDocsRawResult;
 export declare function buildProjectPrompt(projectName: string, query: string, content: string): string;
+/**
+ * The PROJECT corpus row: the current repo's own indexed `.ts`/`.tsx` source.
+ *
+ * Named after the project so a reader of the answer can tell a project-source
+ * citation from a package one at a glance — they are read and cited the same way
+ * and mean very different things.
+ */
+export declare function projectCorpus(projectName: string): DocsCorpus;

package/dist/workers/docs-project.js

@@ -208,3 +208,18 @@ export function buildProjectPrompt(projectName, query, content) {
         content
     });
 }
+/**
+ * The PROJECT corpus row: the current repo's own indexed `.ts`/`.tsx` source.
+ *
+ * Named after the project so a reader of the answer can tell a project-source
+ * citation from a package one at a glance — they are read and cited the same way
+ * and mean very different things.
+ */
+export function projectCorpus(projectName) {
+    return {
+        id: 'project',
+        buildPrompt: (query, content) => buildProjectPrompt(projectName, query, content),
+        header: `Per ${projectName} (project source):`,
+        abortedMessage: 'Project docs lookup aborted.'
+    };
+}

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

@@ -1,4 +1,5 @@
 import { type ContextSnapshot, type LoopHit, type SpawnFn } from '../shared/child-process.js';
+import { RESTART_ORDER } from './worker-kill.js';
 /**
  * Tool calls that can GROUND an APIS claim — i.e. return content a signature or
  * command could be cited from. `pi-worker-docs` (the primary), `read` and `grep`
@@ -246,7 +247,7 @@ export interface RunWorkerInput {
  * Why an attempt was thrown away. One value per restart branch in runWorker, so
  * a log line naming the reason points at exactly one piece of code.
  */
-export type WorkerRestartReason = 'loop' | 'command-timeout' | 'stream-stall' | 'worker-timeout' | 'connection-error' | 'leaked-tool-call';
+export type WorkerRestartReason = (typeof RESTART_ORDER)[number];
 /** One DISCARDED attempt: its cause and the wall clock it consumed and lost. */
 export interface WorkerRestart {
     /** 1-based number of the attempt being discarded (the 1st restart ends attempt 1). */
@@ -411,4 +412,89 @@ export interface RunWorkerResult {
  * itself, or a caller asking for 10s would silently get 30.
  */
 export declare function commandCeilingForAttempt(baseMs: number, priorHangs: number): number;
+/**
+ * Everything the restart ladder reads about one finished attempt, plus the
+ * budgets it draws on. Assembled once per attempt so the rules below can be
+ * module-level data instead of six `if` blocks welded into `runWorker`'s closure.
+ */
+interface RestartState {
+    loopHit?: LoopHit;
+    commandKill?: CommandKill;
+    streamStalled?: {
+        idleMs: number;
+    };
+    timedOut: boolean;
+    modelError?: string;
+    leaked: string | null;
+    /** The cap this attempt actually died against — the SCALE arm moves it. */
+    effectiveCapMs: number;
+    /** The child's tool string, which decides whether its edits can persist. */
+    tools: string;
+    restartBudgetSpent: number;
+    connRetries: number;
+    connectionRetries: number;
+    leakRetries: number;
+}
+/** What a rule does to the budgets when it fires. */
+interface RestartCounters {
+    /** Consume one of the shared loop/timeout/connection restarts. */
+    shared?: boolean;
+    /** Consume one of the leaked-tool-call retries (a separate budget). */
+    leak?: boolean;
+    /** Count a WATCHDOG kill specifically — drives the command-ceiling halving. */
+    hang?: boolean;
+    /** Count a CONNECTION restart specifically — drives the backoff schedule. */
+    connection?: boolean;
+}
+/**
+ * One restartable failure: how to spot it, what to tell the fresh child, which
+ * budget it spends, and how long to wait first.
+ */
+interface RestartRule {
+    reason: WorkerRestartReason;
+    /**
+     * Does this rule apply to the attempt, and is its budget unspent? Returns
+     * the restart's detail line, or null to fall through to the next rule.
+     *
+     * Detection and budget are ONE test on purpose. An out-of-budget failure must
+     * fall through to the return path, not stop the ladder — a loop kill with the
+     * shared budget spent still has to let the plain-abort return happen.
+     */
+    detect: (s: RestartState) => {
+        detail: string;
+    } | null;
+    /**
+     * The corrective preamble prepended to the next attempt's prompt. Omitted by
+     * `connection-error` alone: nothing the model did caused a dropped socket, so
+     * there is nothing to correct — and any hint already in flight from an
+     * earlier restart must survive the retry rather than be cleared by it.
+     */
+    hint?: (s: RestartState) => string;
+    counters: RestartCounters;
+    /** Backoff before re-spawning, in ms. Only the connection rule waits. */
+    backoffMs?: (s: RestartState) => number;
+}
+/**
+ * The restart ladder, in precedence order. FIRST MATCH WINS.
+ *
+ * Read the `!loopHit` guards as "a loop kill outranks me even when it has no
+ * budget left". They are not redundant with row order: when a loop is detected
+ * but the shared budget is spent, row 1 declines, and without those guards row 2
+ * or 4 would then restart the same runaway child under a hint that does not
+ * describe why it died.
+ *
+ * The whole ritual — check the budget, set the hint, spend the counters, record
+ * and announce the discarded attempt, sleep, re-spawn — belongs to the loop in
+ * `runWorker`, so a new failure mode is one row here and cannot be added without
+ * becoming visible in `restarts`.
+ */
+export declare const RESTART_RULES: readonly RestartRule[];
+/** What the command watchdog recorded when it killed an attempt. */
+interface CommandKill {
+    toolName: string;
+    timeoutMs: number;
+    /** The command line itself, when the tool carried one — quoted into the hint
+     *  so the fresh child knows which call it must not repeat unbounded. */
+    detail?: string;
+}
 export declare function runWorker(input: RunWorkerInput): Promise<RunWorkerResult>;

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

@@ -10,6 +10,7 @@ import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../s
 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';
 // `--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
@@ -89,12 +90,7 @@ const CARRY_FORWARD_LIMIT = 24_000;
  * 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 = new Set([
-    'worker-timeout',
-    'command-timeout',
-    'stream-stall',
-    'connection-error'
-]);
+const CARRY_FORWARD_REASONS = CARRY_FORWARD_IDS;
 /**
  * Does this partial output carry ANSWER CONTENT, or is it the model clearing its
  * throat?
@@ -276,7 +272,7 @@ export function commandCeilingForAttempt(baseMs, priorHangs) {
  * `runWorker`, so a new failure mode is one row here and cannot be added without
  * becoming visible in `restarts`.
  */
-const RESTART_RULES = [
+export const RESTART_RULES = [
     {
         // A loop-kill gets the same restart-with-hint treatment every other phase
         // already gets (runPhaseChild) — name the offending call so the

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

@@ -3,15 +3,15 @@ import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
-import { formatResultText } from '../shared/child-output.js';
-import { docsRaw, packageHeader, buildPrompt, buildVersionBanner } from './docs-core.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 { runFocusedExtraction } from './focused-extractor.js';
 import { childFailureReason, makeWorkerTool, workerAnswer, workerUnavailable } from './shared.js';
 import { isTypeOnlyAnswer } from '../task/type-only-answer.js';
 import { logDocsAnswer } from './typeonly-log.js';
 import { normalizeQuery } from './research-cache.js';
-import { projectDocsRaw, buildProjectPrompt } from './docs-project.js';
+import { projectDocsRaw } from './docs-project.js';
 import { projectDocsBudget, projectDocsBudgetExhausted } from '../task/research-fanout-budget.js';
 import { isAbstention } from './abstention.js';
 import { groupThinkingArgs } from '../config/reasoning-args.js';
@@ -128,20 +128,18 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             // 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.
             const spawn = internals.spawn ?? defaultSpawn;
-            // Both paths below run the SAME extraction against this call's cwd/signal/spawn
-            // and verify the citation against exactly the content they prompted with; only
-            // the prompt body and the abort wording differ. (fetch is the site that verifies
-            // against a superset — see FocusedRequest.verifyAgainst.)
-            const extract = (prompt, content, abortedMessage) => runFocusedExtraction({
-                prompt,
-                verifyAgainst: content,
+            // Both arms below run the SAME tail — concatenate, extract, verify,
+            // format — through `docsLookup`; only the CORPUS differs. The
+            // `extraction` group's level is resolved here so neither the lookup
+            // nor the extractor reads ambient config.
+            const lookup = (corpus, chunks) => docsLookup({
+                corpus,
+                chunks,
+                query: params.query,
                 cwd: ctx.cwd,
                 signal,
                 spawn,
-                // The `extraction` group's level. Resolved at the call site so the
-                // extractor itself never reads ambient config.
-                thinking: groupThinkingArgs('extraction'),
-                abortedMessage
+                thinking: groupThinkingArgs('extraction')
             });
             // ── Project source lookup ───────────────────────────────────────
             if (params.module === '.') {
@@ -182,12 +180,10 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                     indexedFiles: filesIngested,
                     indexingMs
                 };
-                const concatenated = chunks.map(c => c.content).join('\n\n');
-                const extraction = await extract(buildProjectPrompt(projectName, params.query, concatenated), concatenated, 'Project docs lookup aborted.');
-                if (!extraction.ok)
-                    return docsFailureResult(extraction, baseDetails, '');
-                const verified = extraction.excerptVerified;
-                const text = formatResultText(`Per ${projectName} (project source):`, extraction, verified);
+                const r = await lookup(projectCorpus(projectName), chunks);
+                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
@@ -243,14 +239,16 @@ 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.
+                    ...pinDetails(rawResult.autoInstallPin),
                     ...npmDetails
                 };
                 return workerUnavailable(npmHeader + rawResult.message, details, 'docs-error');
             }
-            if (rawResult.kind === 'not_installed') {
-                return workerUnavailable(npmHeader
-                    + `Package "${rawResult.pkg}" is not installed and auto-install failed.`, { resolveError: 'not_installed', ...npmDetails }, 'not-installed');
-            }
             if (rawResult.kind === 'no_chunks') {
                 const banner = buildVersionBanner(rawResult.autoInstallPin, rawResult.pkg.name, rawResult.pkg.version, ctx.cwd);
                 // The package resolved and genuinely ships nothing to read — an
@@ -280,13 +278,11 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 ...pinDetails(rawResult.autoInstallPin),
                 ...npmDetails
             };
-            const concatenated = chunks.map(c => c.content).join('\n\n');
-            const extraction = await extract(buildPrompt(pkg, params.query, concatenated), concatenated, 'Docs lookup aborted.');
-            if (!extraction.ok) {
-                return docsFailureResult(extraction, baseDetails, versionBanner + npmHeader);
+            const r = await lookup(packageCorpus(pkg), chunks);
+            if (r.kind === 'failed') {
+                return docsFailureResult(r.extraction, baseDetails, versionBanner + npmHeader);
             }
-            const verified = extraction.excerptVerified;
-            const body = formatResultText(packageHeader(pkg), extraction, verified);
+            const { extraction, excerptVerified: verified, body, content: concatenated } = r;
             // F-2: 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

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

@@ -20,22 +20,9 @@
  * model and nothing renders at all.
  */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { type PiTaskConfig } from '../config/config.js';
-import { REASONING_GROUPS, resolveReasoning } from '../config/reasoning.js';
+import { type GroupSetting, type ReasoningGroup } from '../config/reasoning.js';
 import { type ReasoningMismatch } from '../shared/reasoning-capability.js';
-/** Every group's current setting, in the shape `reasoningMismatches` wants. */
-export type GroupSettings = Array<{
-    group: (typeof REASONING_GROUPS)[number];
-    setting: ReturnType<typeof resolveReasoning>;
-}>;
-/**
- * Read every group's effective setting from a config.
- *
- * Takes the config rather than calling `getConfig()` so the caller decides where
- * it comes from. A test that has to mutate the live singleton to drive this is a
- * test whose result depends on whatever the developer had saved before it ran.
- */
-export declare function settingsFrom(cfg: PiTaskConfig): GroupSettings;
+import { type ChatTemplateCaps } from '../shared/model-endpoint.js';
 /**
  * The warning line for a set of mismatches.
  *
@@ -61,4 +48,11 @@ export declare function registerReasoningWarning(pi: ExtensionAPI,
  * `session_start` so a /task-config change since the last session counts.
  * Injected by tests, which must not depend on the developer's saved config.
  */
-readSettings?: () => GroupSettings): void;
+readSettings?: () => Readonly<Record<ReasoningGroup, GroupSetting>>, 
+/**
+ * The server-side chat-template probe. Injected so the REFINE path — the
+ * only half of this hint that talks to a network — is drivable at all; with
+ * the real probe it is reachable only from a model entry carrying a
+ * `baseUrl`, which no test model has.
+ */
+probe?: (baseUrl: string) => Promise<ChatTemplateCaps | null>): void;

package/dist/workers/reasoning-warning.js

@@ -20,20 +20,11 @@
  * model and nothing renders at all.
  */
 import { getConfig } from '../config/config.js';
-import { REASONING_GROUPS, resolveReasoning } from '../config/reasoning.js';
+import { effectiveReasoning } from '../config/reasoning.js';
 import { reasoningMismatches } from '../shared/reasoning-capability.js';
 import { probeChatTemplateCaps } from '../shared/model-endpoint.js';
+import { registerSessionHint } from './session-hint.js';
 const WIDGET_KEY = 'pi-task-reasoning-warning';
-/**
- * Read every group's effective setting from a config.
- *
- * Takes the config rather than calling `getConfig()` so the caller decides where
- * it comes from. A test that has to mutate the live singleton to drive this is a
- * test whose result depends on whatever the developer had saved before it ran.
- */
-export function settingsFrom(cfg) {
-    return REASONING_GROUPS.map(group => ({ group, setting: resolveReasoning(group, cfg) }));
-}
 /**
  * The warning line for a set of mismatches.
  *
@@ -83,60 +74,37 @@ export function registerReasoningWarning(pi,
  * `session_start` so a /task-config change since the last session counts.
  * Injected by tests, which must not depend on the developer's saved config.
  */
-readSettings = () => settingsFrom(getConfig())) {
-    pi.on('session_start', (_event, ctx) => {
-        // Terminal-only hint: needs an interactive TUI to render and to catch the
-        // keystroke that dismisses it.
-        if (ctx.mode !== 'tui')
-            return;
+readSettings = () => effectiveReasoning(getConfig()), 
+/**
+ * The server-side chat-template probe. Injected so the REFINE path — the
+ * only half of this hint that talks to a network — is drivable at all; with
+ * the real probe it is reachable only from a model entry carrying a
+ * `baseUrl`, which no test model has.
+ */
+probe = probeChatTemplateCaps) {
+    registerSessionHint(pi, WIDGET_KEY, ctx => {
         const model = ctx.model;
         const mismatches = reasoningMismatches(model, readSettings());
         if (mismatches.length === 0)
-            return;
+            return null;
         const base = formatReasoningWarning(model?.name ?? model?.id ?? 'unknown', mismatches);
         if (base === null)
-            return;
-        let unsubscribe = null;
-        let cleared = false;
-        const clear = () => {
-            cleared = true;
-            try {
-                ctx.ui.setWidget(WIDGET_KEY, undefined);
-            }
-            catch {
-                /* stale ctx after a session switch — nothing to clear */
-            }
-            unsubscribe?.();
-            unsubscribe = null;
-        };
-        const render = (text) => {
-            try {
-                ctx.ui.setWidget(WIDGET_KEY, [ctx.ui.theme.fg('warning', text)]);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        };
-        if (!render(base))
-            return;
-        unsubscribe = ctx.ui.onTerminalInput(() => {
-            clear();
-            return undefined;
-        });
+            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.
-        if (model?.baseUrl) {
-            void probeChatTemplateCaps(model.baseUrl)
-                .then(caps => {
-                if (cleared || caps === null)
-                    return;
-                const extra = formatCapabilityConflict(caps.supportsReasoningEffort, model.reasoning);
-                if (extra)
-                    render(base + extra);
+        const baseUrl = model?.baseUrl;
+        if (model === undefined || baseUrl === undefined || baseUrl === '')
+            return { text: base };
+        const declares = model.reasoning;
+        return {
+            text: base,
+            refine: probe(baseUrl).then(caps => {
+                if (caps === null)
+                    return null;
+                const extra = formatCapabilityConflict(caps.supportsReasoningEffort, declares);
+                return extra === null ? null : base + extra;
             })
-                .catch(() => { });
-        }
+        };
     });
 }

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

@@ -0,0 +1,37 @@
+/**
+ * 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`.
+ *
+ * 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),
+ * 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.
+ */
+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.
+     */
+    refine?: Promise<string | null>;
+}
+/**
+ * Register one startup hint.
+ *
+ * `compose` is the seam: it runs at `session_start` inside the TUI gate and
+ * returns the hint, or null to say nothing at all. Everything it returns is
+ * text; nothing about widgets, keystrokes or teardown reaches it.
+ */
+export declare function registerSessionHint(pi: ExtensionAPI, key: string, compose: (ctx: ExtensionContext) => SessionHint | null): void;