@mjasnikovs/pi-task 0.38.23 → 0.38.25

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/pi-worker.js

@@ -47,6 +47,12 @@ export function registerPiWorker(pi) {
                 prompt: params.prompt,
                 cwd: ctx.cwd,
                 signal,
+                // `adhoc` is every guard at its default — which is what this call
+                // site already got by naming none of them. Named now so it is a
+                // decision, and so the one asymmetry it carries (a FIXED 240s cap
+                // where a research worker gets 240s without progress) is written
+                // down. See the `adhoc` row in workers/worker-profiles.ts.
+                profile: 'adhoc',
                 thinking: groupThinkingArgs('research')
             });
             const details = { exitCode: result.exitCode };

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;

package/dist/workers/session-hint.js

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function registerSessionHint(pi, key, compose) {
+    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;
+        const hint = compose(ctx);
+        if (hint === null)
+            return;
+        let unsubscribe = null;
+        let cleared = false;
+        let painted = false;
+        const clear = () => {
+            cleared = true;
+            try {
+                ctx.ui.setWidget(key, undefined);
+            }
+            catch {
+                /* stale ctx after a session switch — nothing to clear */
+            }
+            unsubscribe?.();
+            unsubscribe = null;
+        };
+        const render = (text) => {
+            try {
+                ctx.ui.setWidget(key, [ctx.ui.theme.fg('warning', text)]);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        // Handled BEFORE the paint can bail. `compose` builds this promise
+        // eagerly — the reasoning hint kicks its probe off inside it — so a
+        // rejection with the handler attached later is an unhandled rejection on
+        // exactly the path the try/catch around `setWidget` exists for: a stale
+        // ctx after a session switch. `refine`'s contract says a rejection leaves
+        // the first line standing, and that has to hold when there is no first
+        // line either.
+        if (hint.refine !== undefined) {
+            void hint.refine
+                .then(text => {
+                if (cleared || !painted || text === null)
+                    return;
+                render(text);
+            })
+                .catch(() => { });
+        }
+        painted = render(hint.text);
+        if (!painted)
+            return;
+        // Disappear on any interaction — the first raw keystroke clears it.
+        // Returning undefined leaves the input untouched (we only observe it).
+        unsubscribe = ctx.ui.onTerminalInput(() => {
+            clear();
+            return undefined;
+        });
+    });
+}

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

@@ -26,6 +26,7 @@
  * caused the bug impossible rather than merely fixed.
  */
 import type { LoopHit } from '../task/loop-detector.js';
+import type { WorkerKillId } from './worker-kill.js';
 /**
  * The subset of a finished child result this classification reads.
  *
@@ -83,6 +84,39 @@ export type WorkerFailure = {
 };
 /** The `kind` of every row, for exhaustiveness checks in consumers. */
 export type WorkerFailureKind = WorkerFailure['kind'];
+/**
+ * The ordered ladder. FIRST MATCH WINS — row order IS the precedence, and it is
+ * the only statement of it in the codebase.
+ *
+ * The order, and why:
+ *
+ *  1. `stalled` — no output AND the model endpoint did not answer a probe. The
+ *     most specific diagnosis there is, and the one most easily lost: the kill
+ *     aborts, so anything checked after `aborted` never sees it.
+ *  2. `command-timeout` — a watchdog kill naming the tool call that hung. Also
+ *     aborts. Before the wall-clock timeout because it is the narrower cause
+ *     (the two cannot be confused: a watchdog kill leaves the worker's own
+ *     timeout flag false).
+ *  3. `stream-stall` — a watchdog kill for a model stream that went silent while
+ *     no tool was running. Sits next to `command-timeout` because it is the same
+ *     class of event: a watchdog, not the model, ended the attempt.
+ *  4. `worker-timeout` — the wall-clock backstop.
+ *  5. `loop` — killed for repeating one tool call past threshold. After the
+ *     timeouts, matching the enforce ladder this replaces; in practice the two
+ *     cannot both fire, since a loop kill stops the attempt before its own timer
+ *     can expire.
+ *  6. `leaked-tool-call` — the model wrote a call as prose instead of invoking
+ *     it. Only ever set on an otherwise clean run.
+ *  7. `aborted` — no specific cause survived, so this really is a cancel.
+ *  8. `exit` — a plain non-zero exit with no kill behind it: a crash.
+ */
+export declare const FAILURE_RULES: ReadonlyArray<{
+    /** The roster id this row matches. `worker-kill.test.ts` checks the sequence
+     *  against `FAILURE_ORDER`, so a reordering or an omission is a test failure
+     *  rather than a silently different precedence. */
+    id: WorkerKillId;
+    match: (r: WorkerFailureInput) => WorkerFailure | null;
+}>;
 /**
  * Classify a finished child. Returns `undefined` when nothing killed it —
  * which is not the same as "it answered": the text may still be empty, and that

package/dist/workers/worker-failure.js

@@ -25,6 +25,8 @@
  * in every consumer that has not handled it — which is what makes the drift that
  * caused the bug impossible rather than merely fixed.
  */
+const _kindsAreKills = true;
+void _kindsAreKills;
 /**
  * The ordered ladder. FIRST MATCH WINS — row order IS the precedence, and it is
  * the only statement of it in the codebase.
@@ -51,21 +53,30 @@
  *  7. `aborted` — no specific cause survived, so this really is a cancel.
  *  8. `exit` — a plain non-zero exit with no kill behind it: a crash.
  */
-const FAILURE_RULES = [
-    r => (r.stalled === true ? { kind: 'stalled' } : null),
-    r => r.commandTimedOut ?
-        {
-            kind: 'command-timeout',
-            toolName: r.commandTimedOut.toolName,
-            timeoutMs: r.commandTimedOut.timeoutMs
-        }
-        : null,
-    r => (r.streamStalled ? { kind: 'stream-stall', idleMs: r.streamStalled.idleMs } : null),
-    r => (r.timedOut === true ? { kind: 'worker-timeout' } : null),
-    r => (r.loopHit ? { kind: 'loop', hit: r.loopHit } : null),
-    r => (r.leakedToolCall ? { kind: 'leaked-tool-call', text: String(r.leakedToolCall) } : null),
-    r => (r.aborted ? { kind: 'aborted' } : null),
-    r => (r.exitCode !== 0 ? { kind: 'exit', code: r.exitCode } : null)
+export const FAILURE_RULES = [
+    { id: 'stalled', match: r => (r.stalled === true ? { kind: 'stalled' } : null) },
+    {
+        id: 'command-timeout',
+        match: r => r.commandTimedOut ?
+            {
+                kind: 'command-timeout',
+                toolName: r.commandTimedOut.toolName,
+                timeoutMs: r.commandTimedOut.timeoutMs
+            }
+            : null
+    },
+    {
+        id: 'stream-stall',
+        match: r => r.streamStalled ? { kind: 'stream-stall', idleMs: r.streamStalled.idleMs } : null
+    },
+    { id: 'worker-timeout', match: r => (r.timedOut === true ? { kind: 'worker-timeout' } : null) },
+    { id: 'loop', match: r => (r.loopHit ? { kind: 'loop', hit: r.loopHit } : null) },
+    {
+        id: 'leaked-tool-call',
+        match: r => r.leakedToolCall ? { kind: 'leaked-tool-call', text: String(r.leakedToolCall) } : null
+    },
+    { id: 'aborted', match: r => (r.aborted ? { kind: 'aborted' } : null) },
+    { id: 'exit', match: r => (r.exitCode !== 0 ? { kind: 'exit', code: r.exitCode } : null) }
 ];
 /**
  * Classify a finished child. Returns `undefined` when nothing killed it —
@@ -74,7 +85,7 @@ const FAILURE_RULES = [
  */
 export function classifyWorkerFailure(r) {
     for (const rule of FAILURE_RULES) {
-        const hit = rule(r);
+        const hit = rule.match(r);
         if (hit)
             return hit;
     }

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

@@ -0,0 +1,84 @@
+/**
+ * The ROSTER of ways a worker child can die, and what each one implies.
+ *
+ * WHY IT EXISTS. One kill cause was named in six unlinked places: a
+ * `RunWorkerInput` guard option, a `RunWorkerResult` field, the
+ * `WorkerRestartReason` union, a `RESTART_RULES` row, the `CARRY_FORWARD_REASONS`
+ * set, and a `FAILURE_RULES` row. Adding one meant six coordinated edits, and
+ * only two of them failed to compile if you skipped one. That is not
+ * hypothetical: `worker-failure.ts`'s own header records the bug it cost —
+ * *"`streamStalled` was added to the result and to `finalAttemptFailed`, but the
+ * enforce ladder never grew an arm for it, so an enforcement child killed for a
+ * hung model stream fell all the way through to `if (aborted) return
+ * USER_CANCELLED`"*. That fix closed the READER side. This closes the author
+ * side.
+ *
+ * WHAT IS AND IS NOT UNIFIED. The roster is one table. The two ORDERINGS stay
+ * two, because they genuinely disagree and each says so in its own prose: the
+ * restart ladder puts `loop` first (its hint is the most specific thing to tell a
+ * re-spawn), and the failure ladder puts `stalled` first (the diagnosis most
+ * easily lost behind the `aborted` every kill path sets). Folding two
+ * precedences into one row type would need an escape hatch per row — the same
+ * objection that got a `WriteGuard` row table rejected. What the orderings gain
+ * here is that neither can name a cause with no row, nor silently omit one.
+ *
+ * Not every cause appears in both ladders, and that asymmetry is real:
+ * `connection-error` is restartable but is reported as a `modelError`, never as a
+ * kill; `stalled`, `aborted` and `exit` end an attempt outright and no hint would
+ * help.
+ */
+/** Every way a worker attempt can end other than by answering. */
+export type WorkerKillId = 'stalled' | 'command-timeout' | 'stream-stall' | 'worker-timeout' | 'connection-error' | 'loop' | 'leaked-tool-call' | 'aborted' | 'exit';
+export interface WorkerKill {
+    id: WorkerKillId;
+    /**
+     * The `RunWorkerResult` field that reports this cause on the FINAL attempt,
+     * or null when the cause never reaches the result under its own name
+     * (`connection-error` arrives as `modelError`; `aborted` and `exit` are the
+     * generic fields every kill path also sets).
+     *
+     * A string rather than `keyof RunWorkerResult` so this module stays free of
+     * pi-worker-core's import graph; `worker-kill.test.ts` checks it against the
+     * real interface.
+     */
+    resultField: string | null;
+    /**
+     * Is a killed attempt's partial output worth carrying into the next one?
+     *
+     * A clock kill, a hung tool, an idle stream and a dropped socket all discard
+     * work the model genuinely did. A loop kill and a leaked tool call do not —
+     * the first is by definition the same call repeated, the second is malformed
+     * protocol text, and replaying either would feed the failure back to itself.
+     */
+    carryForward: boolean;
+    /** Does the restart ladder have a rule for this cause? */
+    restartable: boolean;
+    /** Does this cause reach a consumer as a `WorkerFailure`? */
+    reported: boolean;
+}
+export declare const WORKER_KILLS: readonly WorkerKill[];
+/** Look one cause up. `undefined` only for an id with no row, which the suite forbids. */
+export declare function workerKill(id: WorkerKillId): WorkerKill | undefined;
+/**
+ * The restart ladder's precedence, as ids. `RESTART_RULES` must be exactly this,
+ * in this order.
+ *
+ * `loop` leads: its hint names the offending call, which is the most useful thing
+ * to tell a re-spawn. The two watchdogs come before the wall clock because each
+ * is the narrower diagnosis, and they cannot be confused with it — a watchdog
+ * kill leaves the worker's own timeout flag false.
+ */
+export declare const RESTART_ORDER: readonly ["loop", "command-timeout", "stream-stall", "worker-timeout", "connection-error", "leaked-tool-call"];
+/**
+ * The failure ladder's precedence, as ids. `FAILURE_RULES` must be exactly this,
+ * in this order.
+ *
+ * DIFFERENT from `RESTART_ORDER`, deliberately. Every kill path also sets
+ * `aborted` and a non-zero exit, so the specific causes must all be matched
+ * before the two generic ones or a dead backend is reported as "you cancelled".
+ * `stalled` leads because it is both the most specific diagnosis and the one most
+ * easily lost.
+ */
+export declare const FAILURE_ORDER: readonly ["stalled", "command-timeout", "stream-stall", "worker-timeout", "loop", "leaked-tool-call", "aborted", "exit"];
+/** The causes whose partial output is worth keeping. Derived, never hand-kept. */
+export declare const CARRY_FORWARD_IDS: ReadonlySet<WorkerKillId>;