@mjasnikovs/pi-task 0.38.1 → 0.38.3

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

@@ -176,7 +176,16 @@ export declare function docsRaw(input: DocsRawInput): Promise<DocsRawResult>;
 export declare function docsFocused(input: DocsFocusedInput): Promise<DocsFocusedResult>;
 export declare function buildPrompt(pkg: ResolvedPackage, query: string, content: string): string;
 /** Thin wrapper so existing callers using the pkg-based signature still work. */
-export declare function formatResultText(pkg: ResolvedPackage, parsed: {
+/**
+ * The provenance header a docs answer carries. Takes the HEADER, not a package:
+ * the whole body is one string, and the project-source path — which has no
+ * package — used to fabricate a `ResolvedPackage`
+ * (`{name, version: 'local', root, entryDts: null, readme: null}`) purely to make
+ * this call compile, with three of the five fields existing only for that.
+ */
+export declare function formatResultText(header: string, parsed: {
     answer: string;
     excerpt?: string;
 }, verified: boolean | undefined): string;
+/** The header for an npm package answer. */
+export declare function packageHeader(pkg: ResolvedPackage): string;

package/dist/workers/docs-core.js

@@ -9,6 +9,7 @@ import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import { runChild } from '../shared/child-process.js';
 import { runFocusedExtraction } from './focused-extractor.js';
+import { buildExtractionPrompt } from './abstention.js';
 import { formatResultText as formatResultTextShared } from '../shared/child-output.js';
 const DEFAULT_LIMIT = 8;
 const DEFAULT_BUDGET = 24_000;
@@ -550,26 +551,28 @@ export async function docsFocused(input) {
     };
 }
 export function buildPrompt(pkg, query, content) {
-    return (`You answer one question about an npm package, using only the provided content.\n`
-        + `\n`
-        + `Rules:\n`
-        + `1. Output ONLY two tags, in this order, with NO text outside them:\n`
-        + `   <answer>...your answer...</answer>\n`
-        + `   <excerpt>...verbatim quote from <package-content>...</excerpt>\n`
-        + `2. The <excerpt> MUST be copied character-for-character from <package-content>.\n`
-        + `   Do not paraphrase, translate, or summarise inside <excerpt>.\n`
-        + `3. Prefer type signatures, function declarations, and code blocks as evidence over prose.\n`
-        + `4. If the answer is unclear, ambiguous, or absent from <package-content>, write exactly:\n`
-        + `   <answer>unclear from this package</answer> and put the closest related text in <excerpt>.\n`
-        + `   Do not guess.\n`
-        + `5. Be terse. One short paragraph in <answer> max.\n`
-        + `\n`
-        + `<package>${pkg.name}@${pkg.version}</package>\n`
-        + `<question>${query}</question>\n`
-        + `<package-content>\n${content}\n</package-content>\n`);
+    return buildExtractionPrompt({
+        kind: 'package',
+        subject: 'an npm package',
+        tag: 'package',
+        identity: `${pkg.name}@${pkg.version}`,
+        query,
+        content
+    });
 }
 // ─── Backward-compatible wrappers (thin — delegates to shared/) ─────────────
 /** Thin wrapper so existing callers using the pkg-based signature still work. */
-export function formatResultText(pkg, parsed, verified) {
-    return formatResultTextShared(`Per ${pkg.name}@${pkg.version}:`, parsed, verified);
+/**
+ * The provenance header a docs answer carries. Takes the HEADER, not a package:
+ * the whole body is one string, and the project-source path — which has no
+ * package — used to fabricate a `ResolvedPackage`
+ * (`{name, version: 'local', root, entryDts: null, readme: null}`) purely to make
+ * this call compile, with three of the five fields existing only for that.
+ */
+export function formatResultText(header, parsed, verified) {
+    return formatResultTextShared(header, parsed, verified);
+}
+/** The header for an npm package answer. */
+export function packageHeader(pkg) {
+    return `Per ${pkg.name}@${pkg.version}:`;
 }

package/dist/workers/docs-index.js

@@ -2,10 +2,8 @@ import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { isDtsFile } from './docs-resolve.js';
-const MAX_CHUNK_BYTES = 8 * 1024;
+import { chunkDeclarations, chunkReadme } from './docs-chunk.js';
 const ZERO_SEP = Buffer.from([0]);
-const DECL_SPLIT_RE = /^(?:export\s+|declare\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|namespace|module|const|let|var|enum)\s+/m;
-const README_SPLIT_RE = /^#{1,2} /m;
 function computeContentHash(pkg) {
     const hash = createHash('sha256');
     hash.update(Buffer.from(`${pkg.name}@${pkg.version}`, 'utf8'));
@@ -67,71 +65,6 @@ function collectFiles(pkg) {
         readme: pkg.readme
     };
 }
-function chunkDts(content, relPath) {
-    const splits = splitAtMatches(content, new RegExp(DECL_SPLIT_RE.source, 'gm'));
-    const chunks = [];
-    for (const part of splits) {
-        const trimmed = part.trim();
-        if (!trimmed)
-            continue;
-        const prefixed = `// ${relPath}\n${trimmed}`;
-        if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
-            for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES)) {
-                chunks.push(slice);
-            }
-        }
-        else {
-            chunks.push(prefixed);
-        }
-    }
-    return chunks;
-}
-function chunkReadme(content) {
-    const splits = splitAtMatches(content, new RegExp(README_SPLIT_RE.source, 'gm'));
-    const chunks = [];
-    for (const part of splits) {
-        const trimmed = part.replace(/\s+$/, '');
-        if (!trimmed)
-            continue;
-        const headingMatch = /^(#{1,2}) (.+)$/m.exec(trimmed);
-        const heading = headingMatch ? headingMatch[2] : '(intro)';
-        const prefixed = `<!-- README: ${heading} -->\n${trimmed}`;
-        if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
-            for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES))
-                chunks.push(slice);
-        }
-        else {
-            chunks.push(prefixed);
-        }
-    }
-    return chunks;
-}
-function splitAtMatches(text, re) {
-    const parts = [];
-    let lastIndex = 0;
-    let m;
-    while ((m = re.exec(text))) {
-        if (m.index > lastIndex)
-            parts.push(text.slice(lastIndex, m.index));
-        lastIndex = m.index;
-        re.lastIndex = m.index + 1;
-    }
-    if (lastIndex < text.length)
-        parts.push(text.slice(lastIndex));
-    return parts.length ? parts : [text];
-}
-function sliceBytes(s, maxBytes) {
-    const out = [];
-    let buf = Buffer.from(s, 'utf8');
-    while (buf.length > maxBytes) {
-        const slice = buf.subarray(0, maxBytes).toString('utf8');
-        out.push(slice);
-        buf = buf.subarray(Buffer.byteLength(slice, 'utf8'));
-    }
-    if (buf.length)
-        out.push(buf.toString('utf8'));
-    return out;
-}
 function ingestBody(cache, pkg, contentHash) {
     const inside = cache.db
         .prepare('SELECT content_hash FROM packages WHERE name = ? AND version = ?')
@@ -156,7 +89,7 @@ function ingestBody(cache, pkg, contentHash) {
         catch {
             continue;
         }
-        const chunks = chunkDts(raw, rel);
+        const chunks = chunkDeclarations(raw, rel);
         if (!chunks.length)
             continue;
         filesIngested++;

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

@@ -3,6 +3,18 @@ import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import type { RetrievedChunk } from './docs-retrieve.js';
 export declare function getProjectName(cwd: string): string;
 export declare function cwdKey(cwd: string): string;
+/**
+ * Which source files make up the project.
+ *
+ * `git ls-files` is the source of truth when there is one — it already knows
+ * what is tracked and what `.gitignore` excludes, which no hand-rolled walk gets
+ * right — and the walk is the fallback for a directory that is not a repo.
+ *
+ * Injectable through `projectDocsRaw` because it is the only unmockable
+ * dependency left in the docs cluster: without a seam, ANY test of the project
+ * path needs a real temp directory, real files on disk, and a machine where git
+ * is installed and the temp dir is not itself inside a repo.
+ */
 export declare function getProjectFiles(cwd: string): string[];
 export declare function getMaxMtime(files: string[]): string;
 export interface ProjectIndexResult {
@@ -34,5 +46,7 @@ export type ProjectDocsRawResult = {
     projectName: string;
     message: string;
 };
-export declare function projectDocsRaw(cache: CacheHandle, cwd: string, query: string, retrieveChunksFn?: typeof defaultRetrieveChunks): ProjectDocsRawResult;
+export declare function projectDocsRaw(cache: CacheHandle, cwd: string, query: string, retrieveChunksFn?: typeof defaultRetrieveChunks, 
+/** 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;

package/dist/workers/docs-project.js

@@ -3,10 +3,10 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
-const MAX_CHUNK_BYTES = 8 * 1024;
+import { buildExtractionPrompt } from './abstention.js';
+import { chunkDeclarations } from './docs-chunk.js';
 const DEFAULT_LIMIT = 50;
 const DEFAULT_BUDGET = 24_000;
-const DECL_SPLIT_RE = /^(?:export\s+|declare\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|namespace|module|const|let|var|enum)\s+/m;
 export function getProjectName(cwd) {
     try {
         const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -19,6 +19,18 @@ export function getProjectName(cwd) {
 export function cwdKey(cwd) {
     return createHash('sha256').update(cwd).digest('hex').slice(0, 8);
 }
+/**
+ * Which source files make up the project.
+ *
+ * `git ls-files` is the source of truth when there is one — it already knows
+ * what is tracked and what `.gitignore` excludes, which no hand-rolled walk gets
+ * right — and the walk is the fallback for a directory that is not a repo.
+ *
+ * Injectable through `projectDocsRaw` because it is the only unmockable
+ * dependency left in the docs cluster: without a seam, ANY test of the project
+ * path needs a real temp directory, real files on disk, and a machine where git
+ * is installed and the temp dir is not itself inside a repo.
+ */
 export function getProjectFiles(cwd) {
     try {
         const result = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '*.ts', '*.tsx'], { cwd, encoding: 'utf8', timeout: 5000 });
@@ -72,50 +84,6 @@ export function getMaxMtime(files) {
     }
     return String(Math.floor(max));
 }
-function chunkTs(content, relPath) {
-    const splits = splitAtMatches(content, new RegExp(DECL_SPLIT_RE.source, 'gm'));
-    const chunks = [];
-    for (const part of splits) {
-        const trimmed = part.trim();
-        if (!trimmed)
-            continue;
-        const prefixed = `// ${relPath}\n${trimmed}`;
-        if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
-            for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES))
-                chunks.push(slice);
-        }
-        else {
-            chunks.push(prefixed);
-        }
-    }
-    return chunks;
-}
-function splitAtMatches(text, re) {
-    const parts = [];
-    let lastIndex = 0;
-    let m;
-    while ((m = re.exec(text))) {
-        if (m.index > lastIndex)
-            parts.push(text.slice(lastIndex, m.index));
-        lastIndex = m.index;
-        re.lastIndex = m.index + 1;
-    }
-    if (lastIndex < text.length)
-        parts.push(text.slice(lastIndex));
-    return parts.length ? parts : [text];
-}
-function sliceBytes(s, maxBytes) {
-    const out = [];
-    let buf = Buffer.from(s, 'utf8');
-    while (buf.length > maxBytes) {
-        const slice = buf.subarray(0, maxBytes).toString('utf8');
-        out.push(slice);
-        buf = buf.subarray(Buffer.byteLength(slice, 'utf8'));
-    }
-    if (buf.length)
-        out.push(buf.toString('utf8'));
-    return out;
-}
 export function ensureProjectIndexed(cache, name, version, files, cwd) {
     const existing = cache.db
         .prepare('SELECT content_hash FROM packages WHERE name = ? AND version = ?')
@@ -140,7 +108,7 @@ export function ensureProjectIndexed(cache, name, version, files, cwd) {
                 continue;
             }
             const rel = path.relative(cwd, abs);
-            const chunks = chunkTs(raw, rel);
+            const chunks = chunkDeclarations(raw, rel);
             if (!chunks.length)
                 continue;
             filesIngested++;
@@ -160,10 +128,12 @@ export function ensureProjectIndexed(cache, name, version, files, cwd) {
         throw err;
     }
 }
-export function projectDocsRaw(cache, cwd, query, retrieveChunksFn = defaultRetrieveChunks) {
+export function projectDocsRaw(cache, cwd, query, retrieveChunksFn = defaultRetrieveChunks, 
+/** How to enumerate the project's sources. See getProjectFiles. */
+listFiles = getProjectFiles) {
     const projectName = getProjectName(cwd);
     const cacheKey = `project:${cwdKey(cwd)}`;
-    const files = getProjectFiles(cwd);
+    const files = listFiles(cwd);
     const version = getMaxMtime(files);
     let indexResult;
     try {
@@ -229,21 +199,12 @@ export function projectDocsRaw(cache, cwd, query, retrieveChunksFn = defaultRetr
     };
 }
 export function buildProjectPrompt(projectName, query, content) {
-    return (`You answer one question about a local project's source code, using only the provided content.\n`
-        + `\n`
-        + `Rules:\n`
-        + `1. Output ONLY two tags, in this order, with NO text outside them:\n`
-        + `   <answer>...your answer...</answer>\n`
-        + `   <excerpt>...verbatim quote from <project-content>...</excerpt>\n`
-        + `2. The <excerpt> MUST be copied character-for-character from <project-content>.\n`
-        + `   Do not paraphrase, translate, or summarise inside <excerpt>.\n`
-        + `3. Prefer type signatures, function declarations, and code blocks as evidence over prose.\n`
-        + `4. If the answer is unclear, ambiguous, or absent from <project-content>, write exactly:\n`
-        + `   <answer>unclear from this project</answer> and put the closest related text in <excerpt>.\n`
-        + `   Do not guess.\n`
-        + `5. Be terse. One short paragraph in <answer> max.\n`
-        + `\n`
-        + `<project>${projectName}</project>\n`
-        + `<question>${query}</question>\n`
-        + `<project-content>\n${content}\n</project-content>\n`);
+    return buildExtractionPrompt({
+        kind: 'project',
+        subject: "a local project's source code",
+        tag: 'project',
+        identity: projectName,
+        query,
+        content
+    });
 }

package/dist/workers/fetch-core.d.ts

@@ -2,7 +2,7 @@ import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
 import type { SpawnFn } from '../shared/child-process.js';
 import { type ExcerptVerification } from '../shared/child-output.js';
 /** The exact non-answers the child is instructed to emit, matched at the tool layer. */
-export declare const UNCLEAR_ANSWER = "unclear from this page";
+export declare const UNCLEAR_ANSWER: string;
 export declare const NOT_COVERED_ANSWER = "not covered by this page";
 export declare function normaliseSourceUrl(url: string): string;
 export interface FetchRawInput {

package/dist/workers/fetch-core.js

@@ -1,12 +1,13 @@
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
 import { runFocusedExtraction } from './focused-extractor.js';
+import { abstentionSentence } from './abstention.js';
 import { formatResultText as formatResultTextShared } from '../shared/child-output.js';
 const CONTENT_BUDGET = 30_000;
 const HEAD_CHARS = 25_000;
 const TAIL_CHARS = 5_000;
 const TRUNCATION_MARKER = '\n\n[...page continues, truncated...]\n\n';
 /** The exact non-answers the child is instructed to emit, matched at the tool layer. */
-export const UNCLEAR_ANSWER = 'unclear from this page';
+export const UNCLEAR_ANSWER = abstentionSentence('page');
 export const NOT_COVERED_ANSWER = 'not covered by this page';
 /**
  * Rule 6 asks the child to write the sentinel and NOTHING else, so the sentinel is the whole

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

@@ -255,6 +255,122 @@ export function commandCeilingForAttempt(baseMs, priorHangs) {
     const floor = Math.min(baseMs, 30_000);
     return Math.max(floor, Math.round(baseMs / 2 ** priorHangs));
 }
+/**
+ * The restart ladder, in precedence order. FIRST MATCH WINS.
+ *
+ * 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`.
+ */
+const RESTART_RULES = [
+    {
+        // A loop-kill gets the same restart-with-hint treatment every other phase
+        // already gets (runPhaseWithLoopGuard) — name the offending call so the
+        // re-spawn avoids it. Bounded by the shared restart budget.
+        reason: 'loop',
+        detect: s => s.loopHit && s.restartBudgetSpent < MAX_LOOP_RESTARTS ?
+            { detail: `${s.loopHit.call.name} ×${s.loopHit.count}/${s.loopHit.windowSize}` }
+            : null,
+        hint: s => formatLoopHint(s.loopHit),
+        counters: { shared: true }
+    },
+    {
+        // A hung COMMAND is restartable too, on the same budget, but checked
+        // before the whole-worker timeout because its hint is the specific one:
+        // bound the command. (The two can't be confused — a watchdog kill leaves
+        // timeout.timedOut() false, since that flag tracks only its own timer.)
+        reason: 'command-timeout',
+        detect: s => s.commandKill && !s.loopHit && s.restartBudgetSpent < MAX_LOOP_RESTARTS ?
+            {
+                detail: `${s.commandKill.toolName} > ${s.commandKill.timeoutMs}ms`
+                    + (s.commandKill.detail ? `: ${s.commandKill.detail}` : '')
+            }
+            : null,
+        hint: s => commandTimeoutHint(s.commandKill.toolName, s.commandKill.timeoutMs, {
+            commandDetail: s.commandKill.detail,
+            // Nothing reverts the tree between attempts, so a child that can
+            // mutate it (edit/write, or bash side effects) must not be told
+            // its previous attempt left no trace. Same capability test the
+            // gate logger uses — decided by tools, not by phase.
+            editsMayPersist: /\b(?:edit|bash|write)\b/.test(s.tools)
+        }),
+        counters: { shared: true, hang: true }
+    },
+    {
+        // A hung model stream is restartable on the same budget. Checked before
+        // the wall-clock timeout because it is the more specific diagnosis (and
+        // its hint does not blame the model: nothing it did caused the hang).
+        reason: 'stream-stall',
+        detect: s => s.streamStalled && !s.loopHit && s.restartBudgetSpent < MAX_LOOP_RESTARTS ?
+            { detail: `idle ${s.streamStalled.idleMs}ms` }
+            : null,
+        hint: s => streamStallHint(s.streamStalled.idleMs),
+        counters: { shared: true }
+    },
+    {
+        // A wall-clock timeout (the backstop for varied thrash the exact-match
+        // detector misses) is also restartable, sharing the same budget. Skip when
+        // a loop also tripped — the loop hint above is more specific.
+        reason: 'worker-timeout',
+        detect: s => s.timedOut && !s.loopHit && s.restartBudgetSpent < MAX_LOOP_RESTARTS ?
+            // The EFFECTIVE cap, which the SCALE arm moves — reporting the
+            // configured one would misname why this attempt died.
+            { detail: `cap ${s.effectiveCapMs}ms` }
+            : null,
+        hint: () => WORKER_TIMEOUT_HINT,
+        counters: { shared: true }
+    },
+    {
+        // A connection-class model error is restartable on the same budget, exactly
+        // as runPhaseWithLoopGuard already treats it — a research worker had no such
+        // retry, so one dropped fetch failed the whole task at research while the
+        // identical blip in refine/compose was absorbed.
+        //
+        // What this can and cannot buy, measured (flaky proxy in front of the local
+        // llama-server, dropping every connection for a fixed outage window): pi
+        // retries a failed turn itself, 4 attempts over ~15s, and a run that
+        // recovers no longer reports modelError at all (see JsonEventSink). So a
+        // surfaced connection error means pi's own ~15s budget is already spent, and
+        // a re-spawn only helps when the outage outlasts it. It does: at a 20s
+        // outage the baseline never recovered and this policy always did, 0/8 → 8/8
+        // (Fisher p=0.00016), and the same at 35s. Below ~15s pi absorbs it alone —
+        // 8/8 both arms, so the retry neither helps nor costs there. Beyond ~46s
+        // (three spawns' combined budget) both arms fail. The price is paid only on
+        // a backend that is really gone: time-to-report goes ~15s → ~46s. Re-run:
+        // scripts/connection-retry-ab.ts.
+        //
+        // Connection class ONLY. Auth, bad request and context overflow still fail
+        // fast: re-issuing the same request cannot fix them, so spending the budget
+        // would only delay the report.
+        reason: 'connection-error',
+        detect: s => (s.modelError !== undefined
+            && isConnectionError(s.modelError)
+            && s.restartBudgetSpent < MAX_LOOP_RESTARTS
+            && s.connRetries < s.connectionRetries) ?
+            { detail: s.modelError.slice(0, 120) }
+            : null,
+        counters: { shared: true, connection: true },
+        backoffMs: s => connectionRetryBackoffMs(s.connRetries)
+    },
+    {
+        // Only reached on a clean, complete run — see how `leaked` is computed. A
+        // non-zero exit or abort yields partial text the caller already handles,
+        // and detecting there would just mislabel the real failure.
+        reason: 'leaked-tool-call',
+        detect: s => s.leaked && s.leakRetries < MAX_LEAK_RETRIES ?
+            { detail: s.leaked.trim().slice(0, 80) }
+            : null,
+        hint: s => leakedToolCallHint(s.leaked),
+        counters: { leak: true }
+    }
+];
 /**
  * Build the child-side command watchdog for ONE attempt: a per-tool-call timer
  * machine (shared with the main session) whose `onFire` aborts `signal`, which
@@ -479,97 +595,52 @@ export async function runWorker(input) {
         const timedOut = timeout.timedOut();
         const commandKill = cmdWatch?.killed();
         const streamStalled = result.streamStalled;
-        // A loop-kill gets the same restart-with-hint treatment every other phase
-        // already gets (runPhaseWithLoopGuard) — name the offending call so the
-        // re-spawn avoids it. Bounded by the shared restart budget.
-        if (loopHit && restartBudgetSpent < MAX_LOOP_RESTARTS) {
-            hint = formatLoopHint(loopHit);
-            restartBudgetSpent++;
-            noteRestart('loop', `${loopHit.call.name} ×${loopHit.count}/${loopHit.windowSize}`);
-            continue;
-        }
-        // A hung COMMAND is restartable too, on the same budget, but checked
-        // before the whole-worker timeout because its hint is the specific one:
-        // bound the command. (The two can't be confused — a watchdog kill leaves
-        // timeout.timedOut() false, since that flag tracks only its own timer.)
-        if (commandKill && !loopHit && restartBudgetSpent < MAX_LOOP_RESTARTS) {
-            hint = commandTimeoutHint(commandKill.toolName, commandKill.timeoutMs, {
-                commandDetail: commandKill.detail,
-                // Nothing reverts the tree between attempts, so a child that can
-                // mutate it (edit/write, or bash side effects) must not be told
-                // its previous attempt left no trace. Same capability test the
-                // gate logger uses — decided by tools, not by phase.
-                editsMayPersist: /\b(?:edit|bash|write)\b/.test(tools)
-            });
-            restartBudgetSpent++;
-            hangKills++;
-            noteRestart('command-timeout', `${commandKill.toolName} > ${commandKill.timeoutMs}ms`
-                + (commandKill.detail ? `: ${commandKill.detail}` : ''));
-            continue;
-        }
-        // A hung model stream is restartable on the same budget. Checked before
-        // the wall-clock timeout because it is the more specific diagnosis (and
-        // its hint does not blame the model: nothing it did caused the hang).
-        if (streamStalled && !loopHit && restartBudgetSpent < MAX_LOOP_RESTARTS) {
-            hint = streamStallHint(streamStalled.idleMs);
-            restartBudgetSpent++;
-            noteRestart('stream-stall', `idle ${streamStalled.idleMs}ms`);
-            continue;
-        }
-        // A wall-clock timeout (the backstop for varied thrash the exact-match
-        // detector misses) is also restartable, sharing the same budget. Skip when
-        // a loop also tripped — the loop hint above is more specific.
-        if (timedOut && !loopHit && restartBudgetSpent < MAX_LOOP_RESTARTS) {
-            hint = WORKER_TIMEOUT_HINT;
-            restartBudgetSpent++;
-            // The EFFECTIVE cap, which the SCALE arm moves — reporting the
-            // configured one would misname why this attempt died.
-            noteRestart('worker-timeout', `cap ${effectiveCapMs}ms`);
-            continue;
-        }
-        // A connection-class model error is restartable on the same budget, exactly
-        // as runPhaseWithLoopGuard already treats it — a research worker had no such
-        // retry, so one dropped fetch failed the whole task at research while the
-        // identical blip in refine/compose was absorbed.
-        //
-        // What this can and cannot buy, measured (flaky proxy in front of the local
-        // llama-server, dropping every connection for a fixed outage window): pi
-        // retries a failed turn itself, 4 attempts over ~15s, and a run that
-        // recovers no longer reports modelError at all (see JsonEventSink). So a
-        // surfaced connection error means pi's own ~15s budget is already spent, and
-        // a re-spawn only helps when the outage outlasts it. It does: at a 20s
-        // outage the baseline never recovered and this policy always did, 0/8 → 8/8
-        // (Fisher p=0.00016), and the same at 35s. Below ~15s pi absorbs it alone —
-        // 8/8 both arms, so the retry neither helps nor costs there. Beyond ~46s
-        // (three spawns' combined budget) both arms fail. The price is paid only on
-        // a backend that is really gone: time-to-report goes ~15s → ~46s. Re-run:
-        // scripts/connection-retry-ab.ts.
-        //
-        // Connection class ONLY. Auth, bad request and context overflow still fail
-        // fast: re-issuing the same request cannot fix them, so spending the budget
-        // would only delay the report.
-        if (result.modelError
-            && isConnectionError(result.modelError)
-            && restartBudgetSpent < MAX_LOOP_RESTARTS
-            && connRetries < (input.connectionRetries ?? MAX_LOOP_RESTARTS)) {
-            // Noted BEFORE the backoff sleep, so the record's wallMs stays the
-            // attempt's own clock; the sleep lands in totalWallMs, where it belongs.
-            noteRestart('connection-error', result.modelError.slice(0, 120));
-            await (input.sleepFor ?? defaultSleep)(connectionRetryBackoffMs(connRetries));
-            restartBudgetSpent++;
-            connRetries++;
-            continue;
-        }
         // Only treat output as a leak on a clean, complete run — a non-zero exit
         // or abort yields partial text the caller already handles, and detecting
         // there would just mislabel the real failure.
         const leaked = result.exitCode === 0 && !result.aborted ? detectLeakedToolCall(text) : null;
-        if (leaked && leakRetries < MAX_LEAK_RETRIES) {
-            hint = leakedToolCallHint(leaked);
-            leakRetries++;
-            noteRestart('leaked-tool-call', leaked.trim().slice(0, 80));
-            continue;
+        // THE RESTART LADDER. Precedence is RESTART_RULES' row order; this loop
+        // owns the ritual every rule used to repeat: budget, hint, counters,
+        // record-and-announce, backoff, re-spawn.
+        const state = {
+            ...(loopHit ? { loopHit } : {}),
+            ...(commandKill ? { commandKill } : {}),
+            ...(streamStalled ? { streamStalled } : {}),
+            timedOut,
+            ...(result.modelError !== undefined ? { modelError: result.modelError } : {}),
+            leaked,
+            effectiveCapMs,
+            tools,
+            restartBudgetSpent,
+            connRetries,
+            connectionRetries: input.connectionRetries ?? MAX_LOOP_RESTARTS,
+            leakRetries
+        };
+        let restarted = false;
+        for (const rule of RESTART_RULES) {
+            const hit = rule.detect(state);
+            if (!hit)
+                continue;
+            if (rule.hint)
+                hint = rule.hint(state);
+            if (rule.counters.shared)
+                restartBudgetSpent++;
+            if (rule.counters.leak)
+                leakRetries++;
+            if (rule.counters.hang)
+                hangKills++;
+            if (rule.counters.connection)
+                connRetries++;
+            // Noted BEFORE any backoff sleep, so the record's wallMs stays the
+            // attempt's own clock; the sleep lands in totalWallMs, where it belongs.
+            noteRestart(rule.reason, hit.detail);
+            if (rule.backoffMs)
+                await (input.sleepFor ?? defaultSleep)(rule.backoffMs(state));
+            restarted = true;
+            break;
         }
+        if (restarted)
+            continue;
         // SALVAGE. The run used to return the LAST attempt's text unconditionally,
         // so a worker whose final attempt was killed early reported nothing at all
         // — even when a discarded attempt had produced a usable answer that was