@mjasnikovs/pi-task 0.27.0 → 0.28.0

package/dist/task/gate-deps.js

@@ -400,6 +400,14 @@ export function buildGateDeps(params) {
                     // (a healthy endpoint reads as proof of life).
                     streamInactivityMs: getConfig().streamInactivityMs,
                     loop: { pathThreshold: Number.POSITIVE_INFINITY },
+                    // A discarded attempt is otherwise invisible here too: the
+                    // returned exitCode/text describe the FINAL attempt, so a
+                    // gate child that burned two attempts and its wall clock
+                    // reads exactly like one that ran clean.
+                    onRestart: rs => log(`=== ${kind} RESTART (attempt ${rs.attempt} discarded)`
+                        + ` reason=${rs.reason} wall=${rs.wallMs}ms`
+                        + (rs.detail ? ` — ${rs.detail}` : '')
+                        + ' ==='),
                     onLine: line => {
                         // `lastLine` feeds the LIVE status widget and is not
                         // logging — it stays outside the gate, or a quiet
@@ -618,6 +626,12 @@ export function buildGateDeps(params) {
                             // file (which IS this pass's job) never trips — only a
                             // literally-identical call repeated past threshold does.
                             loop: { pathThreshold: Number.POSITIVE_INFINITY },
+                            // Same reasoning as the gate child: without this a
+                            // discarded attempt leaves no trace anywhere.
+                            onRestart: rs => logEnforce(`=== enforce RESTART (attempt ${rs.attempt} discarded)`
+                                + ` reason=${rs.reason} wall=${rs.wallMs}ms`
+                                + (rs.detail ? ` — ${rs.detail}` : '')
+                                + ' ==='),
                             onLine: line => {
                                 // `lastLine` drives the live widget, not the trail.
                                 lastLine = line;

package/dist/task/phases.js

@@ -10,6 +10,7 @@ import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
 import { search as defaultSearch } from '../workers/search-core.js';
 import { extractEnrichTargets } from './enrichment.js';
+import { fanoutTimeoutPolicy, workerCarryForward, workerProgressCeilingMs, projectDocsBudget, projectDocsBudgetNotice } from './research-fanout-budget.js';
 import { isIntegrationUnknown } from './unknown-routing.js';
 import { extractUserDirectives, preserveDirectivesBlock, enforceDirectives } from './user-directives.js';
 import { demoteUnsourcedAttributions } from './context-attribution.js';
@@ -560,6 +561,13 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     // the pattern nexxtasks exists to prevent. To re-run the experiment, restore the block
     // this comment replaces — see the git history of this file and the PROMPT 4 entry in
     // nexxtasks.txt RESULTS.
+    // nexttask 5B fan-out bounds. Both read their env ONCE per research phase, so
+    // every worker in a run sees the same policy and a harness cannot half-apply
+    // an arm; both are null in the shipped configuration.
+    const fanoutBudget = projectDocsBudget();
+    const fanoutTimeout = fanoutTimeoutPolicy();
+    const carryForward = workerCarryForward();
+    const progressCeilingMs = workerProgressCeilingMs();
     let doneCount = 0;
     const updateProgress = () => {
         doneCount++;
@@ -572,9 +580,18 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     // per-worker measurement — waitMs the worker's own cold-start, workMs its
     // generation+tool-call cost. Under the opt-in parallel mode the numbers are
     // wall-clock-relative (queueing shows up in waitMs).
+    //
+    // Restarted attempts get their OWN row. Without one the widget contradicts
+    // itself: mx5 run 18 printed `workers 722.2s` over a longest member reading
+    // `worker:apis work 239.3s`, because wait/work describe the final attempt
+    // while the phase clock counts all three. The discarded time is the whole
+    // gap, so naming it is what closes the widget.
     const recordWorker = (label, p) => p.then(r => {
         deps.recordSubStep?.(`${label} wait`, r.waitMs);
         deps.recordSubStep?.(`${label} work`, r.workMs);
+        if (r.attempts > 1) {
+            deps.recordSubStep?.(`${label} discarded (${r.attempts - 1} restart${r.attempts > 2 ? 's' : ''})`, Math.max(0, r.totalWallMs - r.waitMs - r.workMs));
+        }
         return r;
     });
     // Run the four workers ONE AT A TIME. Settled by an A/B on the local
@@ -617,9 +634,15 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             prompt: prior => appendNoThink(orientation.block
                 + promptHeader
                 + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined)
-                + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')),
+                + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')
+                // 5B CAP arm — empty unless PI_TASK_PROJECT_DOCS_BUDGET is
+                // set. The tool-side half lives in pi-worker-docs.ts; a
+                // budget enforced without being announced would just read
+                // to the worker as a broken tool.
+                + (fanoutBudget === null ? '' : projectDocsBudgetNotice(fanoutBudget))),
             tools: 'read,grep,find,ls,pi-worker-docs'
                 + (searchConfigured() ? ',pi-worker-search,pi-worker-fetch' : ''),
+            fanoutBounded: true,
             extensions: [
                 DOCS_EXTENSION_PATH,
                 ...(searchConfigured() ? [SEARCH_EXTENSION_PATH] : [])
@@ -738,6 +761,32 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             spawn: deps.spawn,
             ...(spec.tools ? { tools: spec.tools } : {}),
             ...(spec.extensions ? { extensions: spec.extensions } : {}),
+            // 5B SCALE arm — null unless both env vars are set. Only the
+            // docs-capable worker can fan out, so only it can be scaled.
+            ...(spec.fanoutBounded && fanoutTimeout ? { fanoutTimeout } : {}),
+            // 5B RESCUE arm — off unless its env vars are set. Applies to
+            // EVERY research worker, not just the docs-capable one: any
+            // worker that gets killed loses its work the same way.
+            ...(carryForward ? { carryForward: true } : {}),
+            ...(progressCeilingMs !== null ?
+                { progressTimeoutCeilingMs: progressCeilingMs }
+                : {}),
+            // One line per DISCARDED attempt. The `done` line below reports
+            // the final attempt only, so a worker that timed out twice at
+            // 240s and then answered used to log exactly like a clean one —
+            // 8 minutes of burned compute recoverable only by subtracting
+            // its own wait+work from the start/done timestamps.
+            onCarryForward: ci => {
+                deps.logDebug?.(`${spec.label}: CARRY-FORWARD injected into attempt ${ci.attempt}`
+                    + ` (${ci.chars} chars onto a ${ci.promptCharsBefore}-char prompt)`);
+            },
+            onRestart: rs => {
+                deps.logDebug?.(`${spec.label}: RESTART (attempt ${rs.attempt} discarded)`
+                    + ` reason=${rs.reason} wall=${rs.wallMs}ms`
+                    + ` wait=${rs.waitMs}ms work=${rs.workMs}ms`
+                    + (rs.detail ? ` — ${rs.detail}` : ''));
+                deps.onChildOutput?.(`${spec.label}: restart (${rs.reason})`);
+            },
             onLine: line => {
                 // The one 'stream' site in this file: raw research-worker
                 // output. Every other logDebug here records a decision.
@@ -838,6 +887,18 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             }
         }
         deps.logDebug?.(`${spec.label}: done exit=${r.exitCode} wait=${r.waitMs}ms work=${r.workMs}ms`
+            // attempts/total are the pair that makes wait+work honest: they are
+            // the FINAL attempt's split, and only `total` sees the discarded ones.
+            + ` attempts=${r.attempts} total=${r.totalWallMs}ms`
+            + (r.restarts.length > 0 ?
+                ` restarts=[${r.restarts.map(x => x.reason).join(',')}]`
+                : '')
+            // Attribution for the RESCUE arm: a run with zero restarts was
+            // never killed (the progress deadline did it), while a run that
+            // restarted and salvaged was killed but kept its work. Without
+            // this the two are indistinguishable in the logs, and "0
+            // timeouts" cannot be traced to the half that earned it.
+            + (r.salvagedFromDiscardedAttempt ? ' salvaged=1' : '')
             + (r.stderr ? ` stderr=${r.stderr.slice(0, 300)}` : '')
             + (r.leakedToolCall ? ` leaked=${r.leakedToolCall.trim().slice(0, 80)}` : ''));
         updateProgress();

package/dist/task/research-fanout-budget.d.ts

@@ -0,0 +1,121 @@
+/**
+ * nexttask 5B — the two candidate bounds on worker:apis's project-source fan-out.
+ *
+ * ⚠ NOT WIRED. Both levers here are OFF unless their env var is set, so the
+ * shipped path is bit-for-bit what it was. They exist so
+ * `scripts/live-research-fanout-budget-ab.ts` can run them against the shipped
+ * baseline in the SAME build — the alternative (dist surgery) measures a patched
+ * copy of the code and not the code. Nothing may read these outside that harness
+ * until it reports PASS; a lever wired on argument rather than measurement is the
+ * failure mode nexttasks exists to prevent.
+ *
+ * THE FAULT THEY TARGET (mx5 run 18, measured — scripts/research-restart-baserate.ts):
+ * `worker:apis` fans out `pi-worker-docs(module: ".")` project-source lookups, each
+ * of which spawns its own summarising child, and the per-worker wall-clock cap is
+ * 240s. Pearson r(project lookups, worker wall clock) = 0.909 over 24 tasks. 0-4
+ * lookups never timed out; every worker at >=46 lookups burned the FULL restart
+ * budget — 3 attempts, 720s, two of them discarded whole. The 240s ceiling and a
+ * 46-call fan-out are jointly unsatisfiable, so the timeout is not a backstop
+ * there, it is the guaranteed outcome.
+ *
+ * TWO WAYS TO MAKE THEM SATISFIABLE, and the A/B — not this comment — decides:
+ *
+ *   CAP     bound the fan-out to fit the ceiling. Told to the worker upfront
+ *           (projectDocsBudgetNotice) and enforced in the tool
+ *           (projectDocsBudgetExhausted), because run 18 shows the prompt alone
+ *           does not bind: the same worker is ALREADY told "be decisive" by
+ *           WORKER_TIMEOUT_HINT on every restart.
+ *   SCALE   bound the ceiling to fit the fan-out: each project-source lookup
+ *           pushes the deadline out, up to a hard ceiling, so a worker that is
+ *           making progress is not killed for making progress.
+ *
+ * The risk each carries, and why the A/B's quality invariant is load-bearing: CAP
+ * can produce a faster worker that ships a THINNER APIS section, which is a
+ * regression wearing a win's clothes (memory/apis-contract-stage2-failed.md: a
+ * lever moved behaviour 20/20 while fabricating 15% of it). SCALE can simply
+ * spend the extra time and still time out, buying nothing.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * BOTH OF THE ABOVE ANSWER THE WRONG QUESTION. Kept for the record and for the
+ * A/B's other arms, but they are not the fix.
+ *
+ * They argue about how long a worker may run. The actual defect is what happens
+ * when it runs out: the attempt is killed and everything it produced is THROWN
+ * AWAY, and the re-spawn is given a hint but no findings — so it re-reads the
+ * same files against the same clock and dies in the same place. That is why
+ * every worker at >=46 lookups burned the FULL budget rather than converging.
+ * The r=0.909 correlation measures the amnesia, not an over-long task.
+ *
+ * Judged against "the worker must return its work", CAP makes the worker read
+ * LESS — lowering the requirement so the metric goes green — and SCALE is a
+ * per-file constant that dies on one big file, and, being wall-clock, makes
+ * answer quality a function of the user's hardware: the same task on a slower
+ * local model loses its work and degrades. No constant fixes that.
+ *
+ *   RESCUE  (pi-worker-core.ts) carry the killed attempt's findings into the
+ *           next one and never return less than the best attempt produced, so a
+ *           restart CONVERGES instead of repeating; and deadline on lack of
+ *           PROGRESS rather than elapsed time, so "slow" and "stuck" stop being
+ *           the same verdict. Being stuck is already detected separately and
+ *           correctly by the output-stall probe (STALL_AFTER_MS), which resets
+ *           on progress and only kills when the model endpoint is unreachable.
+ *
+ * Its risk is its own, and the same quality invariant catches it: a half-written
+ * entry replayed under "work already done" is exactly how a fabrication gets
+ * laundered into a final answer. Hence the carry is framed as unverified, and
+ * ungrounded-symbol and anti-synthesis counts gate the arm.
+ */
+/** Max project-source (`module: "."`) docs lookups per worker ATTEMPT. Unset = no cap. */
+export declare const PROJECT_DOCS_BUDGET_ENV = "PI_TASK_PROJECT_DOCS_BUDGET";
+/** Deadline extension granted per project-source lookup, in ms. Unset = no extension. */
+export declare const FANOUT_TIMEOUT_PER_LOOKUP_ENV = "PI_TASK_FANOUT_TIMEOUT_PER_LOOKUP_MS";
+/** Hard ceiling the extensions may never push the deadline past, in ms. */
+export declare const FANOUT_TIMEOUT_CEILING_ENV = "PI_TASK_FANOUT_TIMEOUT_CEILING_MS";
+/** RESCUE: carry a killed attempt's findings into the re-spawn, and salvage its output. `1` = on. */
+export declare const WORKER_CARRY_FORWARD_ENV = "PI_TASK_WORKER_CARRY_FORWARD";
+/** RESCUE: deadline on lack of progress instead of elapsed time. Value = absolute ceiling, ms. */
+export declare const WORKER_PROGRESS_CEILING_ENV = "PI_TASK_WORKER_PROGRESS_CEILING_MS";
+type Env = (key: string) => string | undefined;
+/**
+ * The CAP arm's budget, or null when the lever is off (the shipped default).
+ * A non-numeric or non-positive value is off too: a typo'd env var must not
+ * silently cap the worker at 0 lookups.
+ */
+export declare function projectDocsBudget(env?: Env): number | null;
+/**
+ * The SCALE arm's policy, or null when off. Both halves are required: an
+ * extension with no ceiling is an unbounded worker, which is the one thing the
+ * 240s cap exists to prevent.
+ */
+export declare function fanoutTimeoutPolicy(env?: Env): {
+    perLookupMs: number;
+    ceilingMs: number;
+} | null;
+/**
+ * The RESCUE arm's two halves, or nulls when off.
+ *
+ * Separated because they are independent claims and the A/B should be able to
+ * attribute a win: RESCUE_CARRY says a restart should keep what the killed
+ * attempt found, RESCUE_PROGRESS_CEILING says a worker should be killed for
+ * going quiet rather than for taking a while. Either can pay off without the
+ * other, and either can fabricate or hang without the other.
+ */
+export declare function workerCarryForward(env?: Env): boolean;
+/**
+ * The absolute backstop for the progress-based deadline, or null when off.
+ * Required rather than defaulted: a progress deadline with no ceiling is an
+ * unbounded worker, which is the one thing the fixed cap exists to prevent.
+ */
+export declare function workerProgressCeilingMs(env?: Env): number | null;
+/**
+ * The upfront half of the CAP arm, appended to the APIS worker's prompt.
+ *
+ * Upfront and NUMERIC on purpose. The worker cannot ration a budget it learns
+ * about only when it is spent, and "be decisive" — which it already receives on
+ * every timeout restart — is exactly the unquantified version that run 18 shows
+ * it ignoring until the third attempt.
+ */
+export declare function projectDocsBudgetNotice(budget: number): string;
+/** The enforcement half: what the tool returns once the budget is spent. */
+export declare function projectDocsBudgetExhausted(budget: number): string;
+export {};

package/dist/task/research-fanout-budget.js

@@ -0,0 +1,148 @@
+/**
+ * nexttask 5B — the two candidate bounds on worker:apis's project-source fan-out.
+ *
+ * ⚠ NOT WIRED. Both levers here are OFF unless their env var is set, so the
+ * shipped path is bit-for-bit what it was. They exist so
+ * `scripts/live-research-fanout-budget-ab.ts` can run them against the shipped
+ * baseline in the SAME build — the alternative (dist surgery) measures a patched
+ * copy of the code and not the code. Nothing may read these outside that harness
+ * until it reports PASS; a lever wired on argument rather than measurement is the
+ * failure mode nexttasks exists to prevent.
+ *
+ * THE FAULT THEY TARGET (mx5 run 18, measured — scripts/research-restart-baserate.ts):
+ * `worker:apis` fans out `pi-worker-docs(module: ".")` project-source lookups, each
+ * of which spawns its own summarising child, and the per-worker wall-clock cap is
+ * 240s. Pearson r(project lookups, worker wall clock) = 0.909 over 24 tasks. 0-4
+ * lookups never timed out; every worker at >=46 lookups burned the FULL restart
+ * budget — 3 attempts, 720s, two of them discarded whole. The 240s ceiling and a
+ * 46-call fan-out are jointly unsatisfiable, so the timeout is not a backstop
+ * there, it is the guaranteed outcome.
+ *
+ * TWO WAYS TO MAKE THEM SATISFIABLE, and the A/B — not this comment — decides:
+ *
+ *   CAP     bound the fan-out to fit the ceiling. Told to the worker upfront
+ *           (projectDocsBudgetNotice) and enforced in the tool
+ *           (projectDocsBudgetExhausted), because run 18 shows the prompt alone
+ *           does not bind: the same worker is ALREADY told "be decisive" by
+ *           WORKER_TIMEOUT_HINT on every restart.
+ *   SCALE   bound the ceiling to fit the fan-out: each project-source lookup
+ *           pushes the deadline out, up to a hard ceiling, so a worker that is
+ *           making progress is not killed for making progress.
+ *
+ * The risk each carries, and why the A/B's quality invariant is load-bearing: CAP
+ * can produce a faster worker that ships a THINNER APIS section, which is a
+ * regression wearing a win's clothes (memory/apis-contract-stage2-failed.md: a
+ * lever moved behaviour 20/20 while fabricating 15% of it). SCALE can simply
+ * spend the extra time and still time out, buying nothing.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * BOTH OF THE ABOVE ANSWER THE WRONG QUESTION. Kept for the record and for the
+ * A/B's other arms, but they are not the fix.
+ *
+ * They argue about how long a worker may run. The actual defect is what happens
+ * when it runs out: the attempt is killed and everything it produced is THROWN
+ * AWAY, and the re-spawn is given a hint but no findings — so it re-reads the
+ * same files against the same clock and dies in the same place. That is why
+ * every worker at >=46 lookups burned the FULL budget rather than converging.
+ * The r=0.909 correlation measures the amnesia, not an over-long task.
+ *
+ * Judged against "the worker must return its work", CAP makes the worker read
+ * LESS — lowering the requirement so the metric goes green — and SCALE is a
+ * per-file constant that dies on one big file, and, being wall-clock, makes
+ * answer quality a function of the user's hardware: the same task on a slower
+ * local model loses its work and degrades. No constant fixes that.
+ *
+ *   RESCUE  (pi-worker-core.ts) carry the killed attempt's findings into the
+ *           next one and never return less than the best attempt produced, so a
+ *           restart CONVERGES instead of repeating; and deadline on lack of
+ *           PROGRESS rather than elapsed time, so "slow" and "stuck" stop being
+ *           the same verdict. Being stuck is already detected separately and
+ *           correctly by the output-stall probe (STALL_AFTER_MS), which resets
+ *           on progress and only kills when the model endpoint is unreachable.
+ *
+ * Its risk is its own, and the same quality invariant catches it: a half-written
+ * entry replayed under "work already done" is exactly how a fabrication gets
+ * laundered into a final answer. Hence the carry is framed as unverified, and
+ * ungrounded-symbol and anti-synthesis counts gate the arm.
+ */
+/** Max project-source (`module: "."`) docs lookups per worker ATTEMPT. Unset = no cap. */
+export const PROJECT_DOCS_BUDGET_ENV = 'PI_TASK_PROJECT_DOCS_BUDGET';
+/** Deadline extension granted per project-source lookup, in ms. Unset = no extension. */
+export const FANOUT_TIMEOUT_PER_LOOKUP_ENV = 'PI_TASK_FANOUT_TIMEOUT_PER_LOOKUP_MS';
+/** Hard ceiling the extensions may never push the deadline past, in ms. */
+export const FANOUT_TIMEOUT_CEILING_ENV = 'PI_TASK_FANOUT_TIMEOUT_CEILING_MS';
+/** RESCUE: carry a killed attempt's findings into the re-spawn, and salvage its output. `1` = on. */
+export const WORKER_CARRY_FORWARD_ENV = 'PI_TASK_WORKER_CARRY_FORWARD';
+/** RESCUE: deadline on lack of progress instead of elapsed time. Value = absolute ceiling, ms. */
+export const WORKER_PROGRESS_CEILING_ENV = 'PI_TASK_WORKER_PROGRESS_CEILING_MS';
+const defaultEnv = key => process.env[key];
+function positiveInt(raw) {
+    if (raw === undefined)
+        return null;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+/**
+ * The CAP arm's budget, or null when the lever is off (the shipped default).
+ * A non-numeric or non-positive value is off too: a typo'd env var must not
+ * silently cap the worker at 0 lookups.
+ */
+export function projectDocsBudget(env = defaultEnv) {
+    return positiveInt(env(PROJECT_DOCS_BUDGET_ENV));
+}
+/**
+ * The SCALE arm's policy, or null when off. Both halves are required: an
+ * extension with no ceiling is an unbounded worker, which is the one thing the
+ * 240s cap exists to prevent.
+ */
+export function fanoutTimeoutPolicy(env = defaultEnv) {
+    const perLookupMs = positiveInt(env(FANOUT_TIMEOUT_PER_LOOKUP_ENV));
+    const ceilingMs = positiveInt(env(FANOUT_TIMEOUT_CEILING_ENV));
+    return perLookupMs !== null && ceilingMs !== null ? { perLookupMs, ceilingMs } : null;
+}
+/**
+ * The RESCUE arm's two halves, or nulls when off.
+ *
+ * Separated because they are independent claims and the A/B should be able to
+ * attribute a win: RESCUE_CARRY says a restart should keep what the killed
+ * attempt found, RESCUE_PROGRESS_CEILING says a worker should be killed for
+ * going quiet rather than for taking a while. Either can pay off without the
+ * other, and either can fabricate or hang without the other.
+ */
+export function workerCarryForward(env = defaultEnv) {
+    return env(WORKER_CARRY_FORWARD_ENV) === '1';
+}
+/**
+ * The absolute backstop for the progress-based deadline, or null when off.
+ * Required rather than defaulted: a progress deadline with no ceiling is an
+ * unbounded worker, which is the one thing the fixed cap exists to prevent.
+ */
+export function workerProgressCeilingMs(env = defaultEnv) {
+    return positiveInt(env(WORKER_PROGRESS_CEILING_ENV));
+}
+/**
+ * The upfront half of the CAP arm, appended to the APIS worker's prompt.
+ *
+ * Upfront and NUMERIC on purpose. The worker cannot ration a budget it learns
+ * about only when it is spent, and "be decisive" — which it already receives on
+ * every timeout restart — is exactly the unquantified version that run 18 shows
+ * it ignoring until the third attempt.
+ */
+export function projectDocsBudgetNotice(budget) {
+    return (`\n\nLOOKUP BUDGET: you may make at most ${budget} project-source `
+        + '`pi-worker-docs` calls (module: ".") in this attempt. They are the most '
+        + 'expensive thing you can do — each one runs a separate model pass — and '
+        + 'past the budget the tool returns nothing at all. Spend them only on '
+        + 'symbols you will actually list in APIS, batch related questions about '
+        + 'one file into a single call, and read a file directly with `read` when '
+        + 'you just need to see it. When the budget runs out, write your answer '
+        + 'from what you already have.');
+}
+/** The enforcement half: what the tool returns once the budget is spent. */
+export function projectDocsBudgetExhausted(budget) {
+    return (`PROJECT LOOKUP BUDGET SPENT — you have used all ${budget} project-source `
+        + 'docs lookups for this attempt and no further ones will run. Do NOT retry '
+        + 'this call or rephrase it; it will return this same message. Use `read` or '
+        + '`grep` if you must see one more file, then write your answer now from what '
+        + 'you already retrieved.');
+}

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

@@ -2,6 +2,35 @@ import { type ContextSnapshot, type SpawnFn } from '../shared/child-process.js';
 import { type LoopHit } from '../task/loop-detector.js';
 /** True when a tool call retrieves content an APIS entry could be grounded in. */
 export declare function isGroundingRetrieval(toolName: string): boolean;
+/**
+ * Does this partial output carry ANSWER CONTENT, or is it the model clearing its
+ * throat?
+ *
+ * Salvage originally kept the LONGEST partial, which is not the same question. On
+ * the live carry arm, TASK_0020 and TASK_0021 both timed out on all three
+ * attempts and salvage shipped this as the section:
+ *
+ *     "Now let me get more details on the specific APIs and components I need:"
+ *
+ * — a preamble sentence, which beats an empty string on length and carries
+ * nothing. Both trials scored 2 entries and DEGRADED, against 22 and 5 for the
+ * same fixtures in baseline.
+ *
+ * A research worker's answer is a list of lines that each name something and
+ * describe it. The test is therefore structural, not lexical: at least two lines
+ * that look like entries — a name, then a gap, then a description. Prose wraps
+ * at no particular column and does not repeat that shape.
+ */
+export declare function hasAnswerContent(text: string): boolean;
+/**
+ * Frame a discarded attempt's output as work already done.
+ *
+ * Kept deliberately blunt about status. Appended text loses to preserved text
+ * when the two disagree, so the carry must not read as a finished answer the
+ * model can simply re-emit: it is labelled partial, unverified, and truncated
+ * when it is.
+ */
+export declare function formatCarryForward(text: string): string | null;
 export interface RunWorkerInput {
     prompt: string;
     cwd: string;
@@ -88,15 +117,90 @@ export interface RunWorkerInput {
     streamInactivityMs?: number;
     /** Backoff sleep, injectable so tests don't wait out the real delays. */
     sleepFor?: (ms: number) => Promise<void>;
+    /**
+     * SCALE arm of nexttask 5B — OFF unless set, and set only by the harness that
+     * is measuring it (src/task/research-fanout-budget.ts explains both arms).
+     * Each project-source `pi-worker-docs` call pushes this attempt's deadline out
+     * by `perLookupMs`, never past `ceilingMs` from the attempt's start: a worker
+     * that is making retrieval progress is not killed for making it, while a
+     * worker that is thrashing still hits a hard bound.
+     */
+    fanoutTimeout?: {
+        perLookupMs: number;
+        ceilingMs: number;
+    };
+    /**
+     * Absolute backstop that turns `timeoutMs` from "total time allowed" into
+     * "time allowed WITHOUT PROGRESS". A tool call or a line of output re-arms
+     * the deadline; only a worker that goes quiet for `timeoutMs` — or exceeds
+     * this ceiling outright — is killed.
+     *
+     * This is the difference between "took too long" and "stopped working". The
+     * first is a property of the machine (a slower local model, a bigger file)
+     * and must not cost the user their answer; the second is a real fault, and
+     * one the output-stall probe already catches on its own terms.
+     */
+    progressTimeoutCeilingMs?: number;
+    /**
+     * Carry a killed attempt's findings into the re-spawn, and never return less
+     * than the best attempt produced. OFF by default so the shipped path is
+     * unchanged while the A/B runs — see src/task/research-fanout-budget.ts.
+     */
+    carryForward?: boolean;
+    /**
+     * Called when a carried-forward partial is INJECTED into an attempt's prompt
+     * — once per attempt that receives one. Distinct from `onRestart`, which says
+     * an attempt was thrown away; this says the next one was actually handed its
+     * findings. The two are separately observable because they can diverge: a
+     * restart whose partial had no answer content injects nothing.
+     */
+    onCarryForward?: (info: {
+        attempt: number;
+        chars: number;
+        promptCharsBefore: number;
+    }) => void;
+    /**
+     * Called once per DISCARDED attempt, at the moment the worker decides to
+     * re-spawn — the only window in which a restart is observable at all.
+     *
+     * WHY: every restart branch below throws away a whole attempt's wall clock
+     * along with its text, and `waitMs`/`workMs` describe the FINAL attempt only.
+     * With no hook here those attempts were structurally invisible: mx5 run 18
+     * burned 30 wall-clock timeouts / 120 minutes of compute that appeared in no
+     * log and no timing widget, and 21 of the 23 affected workers reported
+     * `exit=0` — clean successes as far as the run could tell. The discrepancy
+     * was only recoverable by subtracting reported wait+work from the timestamps
+     * of the `start` and `done` lines around it.
+     */
+    onRestart?: (restart: WorkerRestart) => void;
     /**
      * Connection-error restart budget. Defaults to MAX_LOOP_RESTARTS, and even
-     * then the SHARED `restarts` counter is what actually binds — a worker that
+     * then the SHARED restart counter is what actually binds — a worker that
      * already spent the budget looping does not get extra lives here. 0 turns the
      * retry off, which is how scripts/connection-retry-ab.ts gets a baseline arm
      * out of a build that already ships the retry.
      */
     connectionRetries?: number;
 }
+/**
+ * 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';
+/** 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). */
+    attempt: number;
+    reason: WorkerRestartReason;
+    /** Wall clock this attempt spent before it was killed — time with no output. */
+    wallMs: number;
+    /** The discarded attempt's own spawn → first-byte split. */
+    waitMs: number;
+    /** The discarded attempt's own first-byte → exit split. */
+    workMs: number;
+    /** Reason-specific diagnosis: the looping call, the hung tool, the error text. */
+    detail?: string;
+}
 export interface RunWorkerResult {
     text: string;
     exitCode: number;
@@ -130,14 +234,44 @@ export interface RunWorkerResult {
      * Milliseconds between spawn and the child's first stdout chunk. When
      * multiple workers run concurrently and the upstream model API queues at
      * some concurrency cap, this is the queue-wait portion of the run.
+     *
+     * FINAL ATTEMPT ONLY — a restarted attempt's clock is discarded with its
+     * text. `waitMs + workMs` is therefore NOT the worker's wall clock whenever
+     * `attempts > 1`; `totalWallMs` is.
      */
     waitMs: number;
     /**
      * Milliseconds between first stdout chunk and process exit — the
      * generation/tool-call portion, independent of queue wait. Equals total
-     * elapsed when the child never produced output.
+     * elapsed when the child never produced output. Final attempt only, same as
+     * `waitMs`.
      */
     workMs: number;
+    /**
+     * How many attempts (spawns) this call made, including the one that produced
+     * `text`. 1 for a worker that ran clean. Always `restarts.length + 1`.
+     */
+    attempts: number;
+    /**
+     * The worker's TRUE wall clock: entry to return, spanning every discarded
+     * attempt and every connection backoff. `totalWallMs - waitMs - workMs` is
+     * the time this worker spent on output that was thrown away.
+     */
+    totalWallMs: number;
+    /**
+     * One entry per discarded attempt, in order — empty on a clean run. The only
+     * record that a restart happened: the returned `exitCode`/`text` describe the
+     * final attempt and look identical whether it was the first or the third.
+     */
+    restarts: ReadonlyArray<WorkerRestart>;
+    /**
+     * True when `text` came from a DISCARDED attempt rather than the final one,
+     * because the final attempt returned less. The answer is real output the
+     * worker produced, but it was cut off mid-flight, so it is likelier to be
+     * incomplete than a clean return — callers that grade completeness should
+     * treat it as partial rather than as a finished answer.
+     */
+    salvagedFromDiscardedAttempt: boolean;
     /**
      * How many GROUNDING retrieval tool calls the FINAL attempt made — the calls
      * that returned content an APIS entry could be cited from (see

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

@@ -66,6 +66,91 @@ const STALL_AFTER_MS = 180_000;
 const WORKER_TIMEOUT_HINT = '[SYSTEM NOTE: Your previous attempt ran out of time before answering — you '
     + 'were exploring too long. Be decisive: do the minimum reads/greps needed, '
     + 'then write your answer now. Do not re-explore ground you have already covered.]';
+/**
+ * How much of a discarded attempt's answer is carried into the next one.
+ *
+ * A restart used to hand the re-spawn nothing but a hint — which is why
+ * WORKER_TIMEOUT_HINT above can tell a worker "do not re-explore ground you have
+ * already covered" while giving it no record of what that ground was. It could
+ * not comply. mx5 run 18 shows the cost: on tasks with >=46 project-source
+ * lookups, 5 of 5 workers burned the FULL restart budget, because every attempt
+ * re-read the same files against the same clock and died in the same place.
+ *
+ * Carrying the partial answer forward is what makes a restart converge instead
+ * of repeat. The risk it takes is real and is the thing the A/B measures: a
+ * half-written or speculative entry, replayed under "already established", is
+ * exactly how a fabrication gets laundered into a final answer. That is what the
+ * ungrounded-symbol and anti-synthesis guards are pointed at, so the carry is
+ * framed as findings to VERIFY-or-DROP rather than as settled fact.
+ */
+const CARRY_FORWARD_LIMIT = 24_000;
+/**
+ * Restart reasons whose partial output is worth keeping.
+ *
+ * A clock kill (`worker-timeout`), a hung tool (`command-timeout`), an idle
+ * stream (`stream-stall`) and a dropped socket (`connection-error`) 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.
+ */
+const CARRY_FORWARD_REASONS = new Set([
+    'worker-timeout',
+    'command-timeout',
+    'stream-stall',
+    'connection-error'
+]);
+/**
+ * Does this partial output carry ANSWER CONTENT, or is it the model clearing its
+ * throat?
+ *
+ * Salvage originally kept the LONGEST partial, which is not the same question. On
+ * the live carry arm, TASK_0020 and TASK_0021 both timed out on all three
+ * attempts and salvage shipped this as the section:
+ *
+ *     "Now let me get more details on the specific APIs and components I need:"
+ *
+ * — a preamble sentence, which beats an empty string on length and carries
+ * nothing. Both trials scored 2 entries and DEGRADED, against 22 and 5 for the
+ * same fixtures in baseline.
+ *
+ * A research worker's answer is a list of lines that each name something and
+ * describe it. The test is therefore structural, not lexical: at least two lines
+ * that look like entries — a name, then a gap, then a description. Prose wraps
+ * at no particular column and does not repeat that shape.
+ */
+export function hasAnswerContent(text) {
+    const entryish = text
+        .split('\n')
+        .map(l => l.replace(/^\s*(?:[-*•]|\d+[.)])\s+/, '').trim())
+        .filter(l => /^\S.*?(?:\s{2,}|\s+[—–-]\s+)\S/.test(l) && !/[.:]$/.test(l));
+    return entryish.length >= 2;
+}
+/**
+ * Frame a discarded attempt's output as work already done.
+ *
+ * Kept deliberately blunt about status. Appended text loses to preserved text
+ * when the two disagree, so the carry must not read as a finished answer the
+ * model can simply re-emit: it is labelled partial, unverified, and truncated
+ * when it is.
+ */
+export function formatCarryForward(text) {
+    const body = text.trim();
+    if (body.length === 0)
+        return null;
+    const truncated = body.length > CARRY_FORWARD_LIMIT;
+    // Keep the TAIL: the model writes progressively, so the end of a partial
+    // answer is the furthest it got and the best statement of where to resume.
+    const kept = truncated ? body.slice(body.length - CARRY_FORWARD_LIMIT) : body;
+    return ('[WORK ALREADY DONE — from your previous attempt, which was cut off before '
+        + 'it could answer. These findings came from real reads of this project, so '
+        + 'do NOT gather them again; spend your time on what is still missing. They '
+        + 'are PARTIAL and UNVERIFIED: keep every item you can confirm, and drop any '
+        + 'item you cannot — do not carry an unconfirmed item into your answer, and '
+        + 'do not treat this as your answer.'
+        + (truncated ? ' (Earlier portion omitted; this is the most recent part.)' : '')
+        + ']\n'
+        + kept);
+}
 const defaultSleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 /**
  * Combine an external abort signal with an internal wall-clock timeout into one
@@ -73,17 +158,25 @@ const defaultSleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
  * only when the timer fired (not when the external signal aborted), so the caller
  * can restart on a timeout but not on a user cancel.
  */
-function workerTimeout(external, ms) {
+function workerTimeout(external, ms, 
+/**
+ * Absolute backstop for the progress-based deadline. When set, `ms` stops
+ * meaning "total time allowed" and starts meaning "time allowed WITHOUT
+ * PROGRESS"; this is the hard limit no amount of progress can pass.
+ */
+absoluteCeilingMs) {
     const ctrl = new AbortController();
     let timedOut = false;
+    const armed = ms > 0 && Number.isFinite(ms);
+    const started = Date.now();
+    let deadline = started + ms;
+    const fire = () => {
+        timedOut = true;
+        ctrl.abort();
+    };
     // ms <= 0 (or non-finite) disables the wall-clock timeout: no timer is armed,
     // so only the external signal can abort and timedOut() stays false forever.
-    const timer = ms > 0 && Number.isFinite(ms) ?
-        setTimeout(() => {
-            timedOut = true;
-            ctrl.abort();
-        }, ms)
-        : undefined;
+    let timer = armed ? setTimeout(fire, ms) : undefined;
     const onExternal = () => ctrl.abort();
     if (external) {
         if (external.aborted)
@@ -94,6 +187,41 @@ function workerTimeout(external, ms) {
     return {
         signal: ctrl.signal,
         timedOut: () => timedOut,
+        // SCALE arm of nexttask 5B, inert unless a caller calls it: push the
+        // deadline out, never past `started + ceilingMs`. A disabled timeout
+        // (nothing armed) stays disabled — extending "never" is meaningless — and
+        // an already-fired timer is not resurrected.
+        extend: (byMs, ceilingMs) => {
+            if (!armed || timedOut || ctrl.signal.aborted)
+                return;
+            const next = Math.min(deadline + byMs, started + ceilingMs);
+            if (next <= deadline)
+                return;
+            deadline = next;
+            clearTimeout(timer);
+            timer = setTimeout(fire, Math.max(0, deadline - Date.now()));
+        },
+        // PROGRESS-BASED DEADLINE. A worker that is making tool calls and
+        // emitting text is not stuck — it is slow, and how slow is a property of
+        // the user's machine, not of the task. Killing it on total elapsed time
+        // makes answer quality depend on the hardware: the same task on a slower
+        // local model loses its work and degrades, which no per-file constant can
+        // fix. Being STUCK is already detected separately and correctly, by the
+        // output-stall probe (STALL_AFTER_MS), which resets on progress and only
+        // kills when the model endpoint is unreachable.
+        progress: () => {
+            if (absoluteCeilingMs === undefined)
+                return;
+            if (!armed || timedOut || ctrl.signal.aborted)
+                return;
+            const next = Math.min(Date.now() + ms, started + absoluteCeilingMs);
+            if (next <= deadline)
+                return;
+            deadline = next;
+            clearTimeout(timer);
+            timer = setTimeout(fire, Math.max(0, deadline - Date.now()));
+        },
+        budgetMs: () => deadline - started,
         cleanup: () => {
             clearTimeout(timer);
             external?.removeEventListener('abort', onExternal);
@@ -188,19 +316,49 @@ export async function runWorker(input) {
     // runPhaseWithLoopGuard: a runaway worker gets re-spawned with a corrective
     // hint up to MAX_LOOP_RESTARTS times before we give up. Leaked tool calls
     // keep their own MAX_LEAK_RETRIES budget below — a different failure mode.
-    let restarts = 0;
+    let restartBudgetSpent = 0;
     // Watchdog kills specifically — drives the ceiling halving. Kept apart from
-    // `restarts` (the shared budget) so a loop-caused restart doesn't shorten
+    // `restartBudgetSpent` (the shared budget) so a loop-caused restart doesn't shorten
     // the rope of a child that has never hung (see commandCeilingForAttempt).
     let hangKills = 0;
     // Connection-error restarts specifically — drives the backoff schedule (and
     // lets a harness set the budget to 0 without touching the shared counter).
     let connRetries = 0;
     let leakRetries = 0;
+    // Entry-to-return wall clock. tAttemptStart below is per-attempt (it is what
+    // waitMs/workMs are measured from); this one is the only thing that sees the
+    // attempts that were killed and re-spawned.
+    const tRunStart = Date.now();
+    const restarts = [];
+    // The best partial answer any discarded attempt produced, RAW. Without this a
+    // restart is amnesiac: it re-reads the same files against the same clock and
+    // dies in the same place (see CARRY_FORWARD_LIMIT). Held unformatted because
+    // it has two consumers — the next attempt's prompt, which wants it wrapped in
+    // the carry-forward framing, and the final return, which must never emit that
+    // framing as if it were the worker's answer.
+    // Held in a box, not a bare `let`: the only writer is the `noteRestart`
+    // closure below, and TypeScript narrows a closure-assigned `let` back to its
+    // initialiser at the return site.
+    const salvage = { text: null };
     for (;;) {
-        const prompt = hint === null ? input.prompt : `${hint}\n\n${input.prompt}`;
+        const carried = salvage.text === null ? null : formatCarryForward(salvage.text);
+        // Announce the INJECTION, not just the restart. Without this, "the carry
+        // reached the re-spawn" can only be inferred from entry counts — and
+        // inferring what a worker did from what it produced is the exact gap 5A
+        // exists to close. The prompt goes to the child on stdin, so no log
+        // downstream of here can show it.
+        if (carried !== null) {
+            input.onCarryForward?.({
+                attempt: restarts.length + 1,
+                chars: carried.length,
+                promptCharsBefore: input.prompt.length
+            });
+        }
+        const prompt = [hint, carried, input.prompt]
+            .filter((p) => p !== null)
+            .join('\n\n');
         const invocation = getPiInvocation([...baseArgs], prompt);
-        const tStart = Date.now();
+        const tAttemptStart = Date.now();
         let tFirstByte = null;
         // loop === false turns the guard off entirely (detector is null and no
         // tool call is ever flagged); otherwise build a detector from the override
@@ -221,7 +379,7 @@ export async function runWorker(input) {
         // discarded with its text, so the count must describe only the attempt
         // whose text this call returns.
         let groundingRetrievalCount = 0;
-        const timeout = workerTimeout(input.signal, timeoutMs);
+        const timeout = workerTimeout(input.signal, timeoutMs, input.progressTimeoutCeilingMs);
         // Per-tool-call watchdog for this attempt (null when off). Its abort is
         // OR'd with the worker timeout / external cancel into the child's signal.
         const cmdWatch = commandWatch(commandCeilingForAttempt(input.commandTimeoutMs ?? 0, hangKills));
@@ -245,6 +403,14 @@ export async function runWorker(input) {
                 onFirstByte: () => (tFirstByte = Date.now()),
                 onToolCall: call => {
                     cmdWatch?.onStart(call);
+                    // A tool call is the worker working. Inert unless the
+                    // caller opted into a progress-based deadline.
+                    timeout.progress();
+                    if (input.fanoutTimeout
+                        && call.name === 'pi-worker-docs'
+                        && call.args?.module === '.') {
+                        timeout.extend(input.fanoutTimeout.perLookupMs, input.fanoutTimeout.ceilingMs);
+                    }
                     if (isGroundingRetrieval(call.name))
                         groundingRetrievalCount++;
                     if (!loopDetector)
@@ -254,16 +420,23 @@ export async function runWorker(input) {
                         loopHit = hit;
                     return hit;
                 },
-                onLine: input.onLine,
-                // Always wired when the watchdog is on — the sink only emits
-                // tool_execution_end if a handler exists, and without it every
-                // timer would stay armed and fire on a finished command.
-                onToolResult: cmdWatch ?
-                    r => {
-                        cmdWatch.onEnd(r.toolCallId);
-                        input.onToolResult?.(r);
-                    }
-                    : input.onToolResult,
+                // Output is the other half of "still working": a worker
+                // writing its answer is making progress even when it has no
+                // more tool calls to make.
+                onLine: line => {
+                    timeout.progress();
+                    input.onLine?.(line);
+                },
+                // Always wired now (it used to be conditional on the command
+                // watchdog): the sink only emits tool_execution_end if a
+                // handler exists, and a completed tool call is the clearest
+                // progress signal there is. Without it a worker whose tool
+                // calls all succeed would still look idle to the deadline.
+                onToolResult: r => {
+                    timeout.progress();
+                    cmdWatch?.onEnd(r.toolCallId);
+                    input.onToolResult?.(r);
+                },
                 onContextUsage: input.onContextUsage
             }, input.spawn);
         }
@@ -272,8 +445,36 @@ export async function runWorker(input) {
             cmdWatch?.clear();
         }
         const tEnd = Date.now();
-        const waitMs = tFirstByte === null ? tEnd - tStart : tFirstByte - tStart;
+        const effectiveCapMs = timeout.budgetMs();
+        const waitMs = tFirstByte === null ? tEnd - tAttemptStart : tFirstByte - tAttemptStart;
         const workMs = tFirstByte === null ? 0 : tEnd - tFirstByte;
+        // Record + announce a discarded attempt. Called from every `continue`
+        // branch below, so a restart cannot be added without becoming visible.
+        const noteRestart = (reason, detail) => {
+            const record = {
+                attempt: restarts.length + 1,
+                reason,
+                wallMs: tEnd - tAttemptStart,
+                waitMs,
+                workMs,
+                ...(detail ? { detail } : {})
+            };
+            restarts.push(record);
+            input.onRestart?.(record);
+            // Harvest here rather than in each branch: `noteRestart` is the one
+            // place every `continue` already has to pass through, so a restart
+            // path cannot be added that silently drops the attempt's work.
+            // Longest-wins — a later attempt killed early should not replace a
+            // fuller answer an earlier one had already reached.
+            if (input.carryForward === true && CARRY_FORWARD_REASONS.has(reason)) {
+                const partial = text.trim();
+                // Longest-with-CONTENT wins. Length alone let a preamble sentence
+                // become the answer — see hasAnswerContent.
+                if (partial.length > (salvage.text?.length ?? 0) && hasAnswerContent(partial)) {
+                    salvage.text = partial;
+                }
+            }
+        };
         const text = result.text ?? '';
         const timedOut = timeout.timedOut();
         const commandKill = cmdWatch?.killed();
@@ -281,16 +482,17 @@ export async function runWorker(input) {
         // 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 && restarts < MAX_LOOP_RESTARTS) {
+        if (loopHit && restartBudgetSpent < MAX_LOOP_RESTARTS) {
             hint = formatLoopHint(loopHit);
-            restarts++;
+            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 && restarts < MAX_LOOP_RESTARTS) {
+        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
@@ -299,24 +501,30 @@ export async function runWorker(input) {
                 // gate logger uses — decided by tools, not by phase.
                 editsMayPersist: /\b(?:edit|bash|write)\b/.test(tools)
             });
-            restarts++;
+            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 && restarts < MAX_LOOP_RESTARTS) {
+        if (streamStalled && !loopHit && restartBudgetSpent < MAX_LOOP_RESTARTS) {
             hint = streamStallHint(streamStalled.idleMs);
-            restarts++;
+            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 && restarts < MAX_LOOP_RESTARTS) {
+        if (timedOut && !loopHit && restartBudgetSpent < MAX_LOOP_RESTARTS) {
             hint = WORKER_TIMEOUT_HINT;
-            restarts++;
+            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
@@ -342,10 +550,13 @@ export async function runWorker(input) {
         // would only delay the report.
         if (result.modelError
             && isConnectionError(result.modelError)
-            && restarts < MAX_LOOP_RESTARTS
+            && 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));
-            restarts++;
+            restartBudgetSpent++;
             connRetries++;
             continue;
         }
@@ -356,15 +567,44 @@ export async function runWorker(input) {
         if (leaked && leakRetries < MAX_LEAK_RETRIES) {
             hint = leakedToolCallHint(leaked);
             leakRetries++;
+            noteRestart('leaked-tool-call', leaked.trim().slice(0, 80));
             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
+        // still in hand at the moment it was thrown away. A restart budget is
+        // meant to buy more chances at an answer, not to overwrite a good attempt
+        // with a worse one.
+        //
+        // Gated on the final attempt having FAILED, not on it being shorter. A
+        // worker that finished cleanly has answered, and a short answer is a
+        // legitimate answer — length would let a long half-finished fragment
+        // override a concise correct one, which is the opposite of the fix.
+        const finalAttemptFailed = timedOut === true
+            || result.aborted
+            || result.modelError !== undefined
+            || result.stalled === true
+            || streamStalled !== undefined
+            || commandKill !== undefined
+            || loopHit !== undefined
+            || text.trim().length === 0;
+        const answer = (finalAttemptFailed
+            && salvage.text !== null
+            && salvage.text.length > text.trim().length) ?
+            salvage.text
+            : text;
         return {
-            text,
+            text: answer,
+            salvagedFromDiscardedAttempt: answer !== text,
             exitCode: result.exitCode,
             stderr: result.stderr.trim(),
             aborted: result.aborted,
             waitMs,
             workMs,
+            attempts: restarts.length + 1,
+            totalWallMs: Date.now() - tRunStart,
+            restarts,
             sawOutput: tFirstByte !== null,
             groundingRetrievalCount,
             ...(result.modelError ? { modelError: result.modelError } : {}),

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

@@ -14,6 +14,7 @@ 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 { projectDocsBudget, projectDocsBudgetExhausted } from '../task/research-fanout-budget.js';
 const childArgs = () => [...childBaseArgs(), '--no-tools'];
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
@@ -57,6 +58,14 @@ function pinDetails(pin) {
     return pin ? { versionSource: pin.source, declaredRange: pin.range } : {};
 }
 export function registerPiWorkerDocs(pi, internals = {}) {
+    // CAP arm of nexttask 5B — OFF unless PI_TASK_PROJECT_DOCS_BUDGET is set, and
+    // then per-ATTEMPT by construction: the extension is loaded into a fresh pi
+    // child on every spawn, so a restarted attempt starts this counter at 0. The
+    // budget it enforces is the one the worker was told about in its prompt
+    // (projectDocsBudgetNotice) — enforcement without the notice would be a
+    // silent tool failure, and the notice without enforcement is what run 18
+    // already shows does not bind.
+    let projectLookups = 0;
     makeWorkerTool(pi, {
         name: 'pi-worker-docs',
         label: 'Pi Worker Docs',
@@ -103,6 +112,15 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             const spawn = internals.spawn ?? defaultSpawn;
             // ── Project source lookup ───────────────────────────────────────
             if (params.module === '.') {
+                const budget = projectDocsBudget();
+                if (budget !== null && ++projectLookups > budget) {
+                    // Refused BEFORE any work: the point of the cap is the child
+                    // spawn and the model pass this branch would otherwise run.
+                    return {
+                        text: projectDocsBudgetExhausted(budget),
+                        details: { budgetSpent: true }
+                    };
+                }
                 const openCache = internals.openCache ?? defaultOpenCache;
                 let cache;
                 let cacheError;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.27.0",
+    "version": "0.28.0",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",