@mjasnikovs/pi-task 0.38.24 → 0.38.25

package/dist/task/gate-child.js

@@ -88,18 +88,18 @@ export function makeGateChild(deps) {
                     cwd: deps.cwd,
                     ...(sig ? { signal: sig } : {}),
                     tools,
-                    // Run to completion: these passes legitimately read and edit the
-                    // same file many times, and the research-worker guards mislabel
-                    // that as a runaway and kill good work (mx5 TASK_0002).
-                    timeoutMs: 0,
-                    commandTimeoutMs: deps.commandTimeoutMs,
-                    streamInactivityMs: deps.streamInactivityMs,
+                    // The four guard literals that used to sit here — run to
+                    // completion, a per-command watchdog, a stream watchdog, and
+                    // the path rule disabled — are the `gate` row of
+                    // WORKER_PROFILES (workers/worker-profiles.ts), which carries
+                    // the reasoning for each. The two ceilings stay inputs
+                    // because they are user config, not policy.
+                    profile: 'gate',
+                    policyInputs: {
+                        commandTimeoutMs: deps.commandTimeoutMs,
+                        streamInactivityMs: deps.streamInactivityMs
+                    },
                     thinking: deps.thinking,
-                    // Exact-match loop guard only: pathThreshold Infinity disables
-                    // the path-revisit heuristic, so revisiting one file (which IS
-                    // the job) never trips — only a literally-identical call
-                    // repeated past threshold does.
-                    loop: { pathThreshold: Number.POSITIVE_INFINITY },
                     // A discarded attempt is otherwise invisible: the returned
                     // exitCode/text describe the FINAL attempt, so a child that
                     // burned two attempts reads exactly like one that ran clean.

package/dist/task/phases.js

@@ -9,7 +9,7 @@ import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
 import { searchProviderKey } from '../workers/search-types.js';
 import { channelSet } from '../workers/worker-channels.js';
-import { fanoutTimeoutPolicy, workerCarryForward, workerProgressCeilingMs, projectDocsBudget, projectDocsBudgetNotice } from './research-fanout-budget.js';
+import { snapshotLeverEnv, 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';
@@ -488,10 +488,9 @@ export async function phaseResearch(deps, refined) {
     // phase, so every worker in a run sees the same policy and a harness cannot
     // half-apply an arm. CAP, SCALE and carry-forward are null/false in the
     // shipped configuration; the progress deadline shipped ON (nexttask 9).
-    const fanoutBudget = projectDocsBudget();
-    const fanoutTimeout = fanoutTimeoutPolicy();
-    const carryForward = workerCarryForward();
-    const progressCeilingMs = workerProgressCeilingMs();
+    const leverEnv = snapshotLeverEnv();
+    const fanoutBudget = projectDocsBudget(leverEnv);
+    const progressCeilingMs = workerProgressCeilingMs(leverEnv);
     // Which deadline policy was in force is a fact about how every number below
     // was produced. Run 18's 120 discarded minutes were only recoverable because
     // 5A started writing down what the workers actually did; a run whose logs do
@@ -695,9 +694,7 @@ export async function phaseResearch(deps, refined) {
         onDone: updateProgress,
         readCached: async (heading) => (await readSection(deps.cwd, deps.taskId, heading)) ?? '',
         persistSection,
-        carryForward,
-        fanoutTimeout,
-        progressCeilingMs
+        leverEnv
     }, prior);
     const sections = [];
     if (!getConfig().parallelResearchWorkers) {

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

@@ -81,6 +81,26 @@ 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;
+/**
+ * Every lever env var this module owns.
+ *
+ * Exists so `snapshotLeverEnv` cannot drift from the levers: adding a lever
+ * without adding it here would leave that one lever read LATE, which is the
+ * half-applied arm the snapshot exists to prevent.
+ */
+export declare const RESEARCH_LEVER_ENVS: readonly string[];
+/**
+ * The levers, read ONCE, as a reader the profile table can be handed.
+ *
+ * WHY A SNAPSHOT AND NOT `process.env`. Every worker in one research phase must
+ * see the same arm. The three lever values used to be resolved once in
+ * `phases.ts` and threaded down as three separate `ResearchWorkerRun` fields for
+ * exactly that reason; moving the resolution into the `research` profile would
+ * have moved the READ down to each worker with it, and a harness that flips a
+ * var mid-phase would then half-apply its own arm. Freezing the reader keeps the
+ * read-once property while letting the profile own what the values MEAN.
+ */
+export declare function snapshotLeverEnv(env?: Env): Env;
 /**
  * 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

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

@@ -81,6 +81,35 @@ 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];
+/**
+ * Every lever env var this module owns.
+ *
+ * Exists so `snapshotLeverEnv` cannot drift from the levers: adding a lever
+ * without adding it here would leave that one lever read LATE, which is the
+ * half-applied arm the snapshot exists to prevent.
+ */
+export const RESEARCH_LEVER_ENVS = [
+    PROJECT_DOCS_BUDGET_ENV,
+    FANOUT_TIMEOUT_PER_LOOKUP_ENV,
+    FANOUT_TIMEOUT_CEILING_ENV,
+    WORKER_CARRY_FORWARD_ENV,
+    WORKER_PROGRESS_CEILING_ENV
+];
+/**
+ * The levers, read ONCE, as a reader the profile table can be handed.
+ *
+ * WHY A SNAPSHOT AND NOT `process.env`. Every worker in one research phase must
+ * see the same arm. The three lever values used to be resolved once in
+ * `phases.ts` and threaded down as three separate `ResearchWorkerRun` fields for
+ * exactly that reason; moving the resolution into the `research` profile would
+ * have moved the READ down to each worker with it, and a harness that flips a
+ * var mid-phase would then half-apply its own arm. Freezing the reader keeps the
+ * read-once property while letting the profile own what the values MEAN.
+ */
+export function snapshotLeverEnv(env = defaultEnv) {
+    const snap = new Map(RESEARCH_LEVER_ENVS.map(k => [k, env(k)]));
+    return key => snap.get(key);
+}
 function positiveInt(raw) {
     if (raw === undefined)
         return null;

package/dist/task/research-worker.d.ts

@@ -88,13 +88,16 @@ export interface ResearchWorkerRun {
     readCached: (heading: string) => Promise<string>;
     /** Write one validated section to the task file. Serialised by the caller. */
     persistSection: (heading: string, text: string) => Promise<void>;
-    /** 5B RESCUE / SCALE knobs, resolved once for the phase. */
-    carryForward: boolean;
-    fanoutTimeout: {
-        perLookupMs: number;
-        ceilingMs: number;
-    } | null;
-    progressCeilingMs: number | null;
+    /**
+     * The 5B lever env vars, READ ONCE for the whole phase.
+     *
+     * Was three resolved values (`carryForward`, `fanoutTimeout`,
+     * `progressCeilingMs`). It is one frozen reader now because the `research`
+     * profile owns what those values mean; what this layer still owns is that
+     * every worker in a run sees the SAME arm, which a live `process.env` read
+     * per worker would lose. See `snapshotLeverEnv`.
+     */
+    leverEnv: (key: string) => string | undefined;
 }
 /**
  * Task-file heading under which a research worker's validated output is cached.

package/dist/task/research-worker.js

@@ -263,20 +263,17 @@ export async function runResearchWorker(spec, run, prior = []) {
         thinking: run.thinkingFor(spec.label),
         ...(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 && run.fanoutTimeout ?
-            { fanoutTimeout: run.fanoutTimeout }
-            : {}),
-        // 5B RESCUE. Applies to EVERY research worker, not just the
-        // docs-capable one: any worker that gets killed loses its work
-        // the same way. carry-forward stays OFF unless asked for
-        // (measured harmful on its own); the progress deadline SHIPPED
-        // ON in nexttask 9 and is null only when explicitly disabled.
-        ...(run.carryForward ? { carryForward: true } : {}),
-        ...(run.progressCeilingMs !== null ?
-            { progressTimeoutCeilingMs: run.progressCeilingMs }
-            : {}),
+        // The three 5B lever spreads that used to sit here are the
+        // `research` row of WORKER_PROFILES (workers/worker-profiles.ts).
+        // Two facts still come from here, and only these two: which of
+        // the four workers is docs-capable (only it can be scaled), and
+        // the phase's FROZEN lever reader, so every worker in one run
+        // sees the same arm.
+        profile: 'research',
+        policyInputs: {
+            ...(spec.fanoutBounded ? { fanoutBounded: true } : {}),
+            env: run.leverEnv
+        },
         // 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 —

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

@@ -1,5 +1,6 @@
 import { type ContextSnapshot, type LoopHit, type SpawnFn } from '../shared/child-process.js';
 import { RESTART_ORDER } from './worker-kill.js';
+import { type WorkerGuardOverride, type WorkerGuardPolicy, type WorkerPolicyInputs, type WorkerProfileId } from './worker-profiles.js';
 /**
  * Tool calls that can GROUND an APIS claim — i.e. return content a signature or
  * command could be cited from. `pi-worker-docs` (the primary), `read` and `grep`
@@ -88,116 +89,40 @@ export interface RunWorkerInput {
      */
     contextWindow?: number;
     /**
-     * Per-worker wall-clock timeout in ms. Defaults to RESEARCH_WORKER_TIMEOUT_MS.
-     * Pass 0 to disable the timeout entirely (run until the child exits on its
-     * own) — for a pass that must be allowed to finish however long it takes.
-     */
-    timeoutMs?: number;
-    /**
-     * PER-TOOL-CALL wall-clock ceiling in ms — the child-side half of the command
-     * watchdog (see shared/command-watchdog.ts). Arms on each tool_execution_start
-     * and disarms on the matching end; on overrun the child is killed and, within
-     * the shared restart budget, re-spawned with commandTimeoutHint.
-     *
-     * WHY SEPARATE FROM `timeoutMs`: that one bounds the whole worker and is
-     * deliberately 0 (unbounded) for gate children, which must run to completion.
-     * Neither it nor the stall guard can catch a hung command — the stall guard
-     * treats a reachable model endpoint as proof of life, which it is, even while
-     * a `bun run dev` the model forgot to bound blocks the child forever.
+     * WHICH KIND of worker child this is — the whole guard policy, in one word.
      *
-     * This is the ceiling for the FIRST attempt; each HANG-caused restart halves
-     * it (see commandCeilingForAttempt — loop-caused restarts don't count), so a
-     * model that ignores the hint cannot spend the full ceiling again on every
-     * retry.
-     *
-     * 0 / omitted = off, so every existing caller is unchanged.
-     */
-    commandTimeoutMs?: number;
-    /**
-     * Per-worker loop-detector tuning. Defaults to the read-only research/impl
-     * guard (LOOP_WINDOW / LOOP_THRESHOLD, path threshold = exact threshold). An
-     * edit/fix pass legitimately revisits one file, so it can raise (or disable
-     * via Infinity) `pathThreshold`. Pass `false` to turn the detector OFF
-     * entirely — no tool-call pattern will ever kill the worker.
+     * REQUIRED, and required on purpose. The ten guard knobs this replaces used
+     * to sit here as independent optionals, so a caller that named none of them
+     * still got a full policy and nobody could see which one. That is how the
+     * ad-hoc `pi-worker` tool came to run the strictest wall clock of the three
+     * children without anyone deciding it should. See worker-profiles.ts.
      */
-    loop?: {
-        window?: number;
-        threshold?: number;
-        pathThreshold?: number;
-    } | false;
+    profile: WorkerProfileId;
     /**
-     * Whole-run progress guard (task/stall-detector.ts). Default ON.
-     *
-     * WHY BOTH. LoopDetector judges ARGUMENTS over a 20-call window, so a child
-     * that rotates through MORE DISTINCT CALLS THAN THE WINDOW HOLDS is invisible
-     * to it — every key occurs once per window and the count never reaches the
-     * threshold. Measured: mx5-n 2026-08-27, worker:tooling made 550 calls over
-     * exactly 20 distinct files, ~36 reads each, and neither the exact rule nor
-     * the path rule ever tripped. It died 20 minutes later on the absolute
-     * progress ceiling, having done 25s of useful work.
-     *
-     * StallDetector judges RESULTS, which a rotating reader cannot vary. It was
-     * written for exactly this class and was wired only into phase children
-     * (task/child-runner.ts) until this option existed.
-     *
-     * Pass `false` to disable, or override the thresholds (tests, harnesses).
+     * The facts the profile needs that are NOT policy: the gate's two watchdog
+     * ceilings (user config) and which research worker is docs-capable.
      */
-    stallGuard?: {
-        limit?: number;
-        churnFactor?: number;
-    } | false;
+    policyInputs?: WorkerPolicyInputs;
     /**
-     * Dead-backend stall guard override. Default ON: no output for
-     * STALL_AFTER_MS → probe the model endpoints pi is configured with →
-     * unreachable → kill + `stalled: true`. Pass `false` to disable, or
-     * override the window/probe (tests, harnesses).
+     * Whole guard rows laid over the profile's. TESTS AND A/B HARNESSES ONLY —
+     * an override at a production call site is the hand-picked subset this
+     * design exists to stop, and `worker-profiles.test.ts` fails the build if
+     * one appears under src/ outside a test.
      */
-    stall?: {
-        afterMs?: number;
-        probe?: () => Promise<boolean>;
-    } | false;
+    override?: WorkerGuardOverride;
     /**
-     * Stream-inactivity ceiling in ms (shared/stream-watchdog.ts). The stall guard
-     * above cannot catch a HUNG stream on a HEALTHY backend — it reads a reachable
-     * endpoint as proof of life, which is exactly what run 14's three hangs looked
-     * like. This one asks nothing of the backend: no output for this long (with
-     * tool executions excluded) ⇒ kill and restart the attempt with
-     * {@link streamStallHint}, inside the same shared restart budget.
-     * 0 / omitted = off.
+     * The resolved policy this run will use, reported once before the first
+     * attempt.
+     *
+     * WHY: asserting that a profile RESOLVES correctly proves nothing about
+     * whether runWorker then READS it correctly — a rewiring that turns "0 means
+     * off" into "0 means on" leaves every profile assertion green. This hook is
+     * what lets a caller's own test (gate-child.test.ts) drive the REAL call
+     * site and check the REAL policy, instead of re-typing the table.
      */
-    streamInactivityMs?: number;
+    onPolicy?: (policy: WorkerGuardPolicy) => void;
     /** 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
@@ -234,14 +159,6 @@ export interface RunWorkerInput {
      * 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 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

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

@@ -5,12 +5,13 @@ import { isGroundingRetrieval as isGrounding, workerChannel } from './worker-cha
 import { childBaseArgs } from '../shared/child-extensions.js';
 import { LoopDetector } from '../task/loop-detector.js';
 import { StallDetector, formatStallHint } from '../task/stall-detector.js';
-import { LOOP_WINDOW, LOOP_THRESHOLD, MAX_LOOP_RESTARTS, formatLoopHint, isConnectionError, connectionRetryBackoffMs } from '../task/child-runner.js';
+import { MAX_LOOP_RESTARTS, formatLoopHint, isConnectionError, connectionRetryBackoffMs } from '../task/child-runner.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 import { discoverModelEndpoints, probeModelEndpoints } from '../shared/model-endpoint.js';
 import { streamStallHint } from '../shared/stream-watchdog.js';
 import { classifyWorkerFailure } from './worker-failure.js';
 import { CARRY_FORWARD_IDS } from './worker-kill.js';
+import { applyOverride, WORKER_PROFILES } from './worker-profiles.js';
 // `--mode json` makes pi emit structured events as they happen instead of
 // buffering the assistant text and flushing on exit. That matters for the
 // wait/work timing split: in text mode the first stdout chunk only arrives at
@@ -35,25 +36,9 @@ const DEFAULT_TOOLS = 'read,grep,find,ls';
 // hand-kept — this was a second copy of the four tool names. Re-exported because
 // several call sites and tests import it from here.
 export { isGroundingRetrieval } from './worker-channels.js';
-/**
- * Hard wall-clock bound on a single research worker run (one spawn). The
- * exact-match LoopDetector only catches *identical* repeated tool calls; a model
- * that thrashes with slightly-varied calls (different grep patterns each time)
- * slips past it and would otherwise run unbounded. This is the backstop for that
- * case: after this long with no clean exit, abort and restart with a hint. Sized
- * well above a healthy worker's observed runtime (~25-130s on the local backend)
- * so it never trips a legitimately slow run.
- */
-const RESEARCH_WORKER_TIMEOUT_MS = 240_000;
-/**
- * Output-stall window before the dead-backend probe fires (mx5 run 7: model
- * server died mid-gate-child, the child hung MUTE for 64 minutes). This is NOT
- * a wall-clock cap — output progress resets it, and even a fully stalled child
- * is only killed when the model endpoint is actually unreachable. Sized so a
- * long local prompt-processing pass (minutes of legitimate silence, server
- * alive) just gets probed and waits on.
- */
-const STALL_AFTER_MS = 180_000;
+// RESEARCH_WORKER_TIMEOUT_MS and STALL_AFTER_MS live on the profile table now
+// (worker-profiles.ts): they are the default VALUES of two guard rows, and a
+// default that lives apart from the table stating it is a second place to look.
 /**
  * Restart hint after a WHOLE-WORKER wall-clock timeout — distinct from both the
  * loop hint and the per-command hint. This one diagnoses over-exploration, which
@@ -443,7 +428,14 @@ export async function runWorker(input) {
         '--tools',
         tools
     ];
-    const timeoutMs = input.timeoutMs ?? RESEARCH_WORKER_TIMEOUT_MS;
+    // ONE resolution, before the first attempt. Every guard read below goes
+    // through `policy`, so "which knobs is this child running" has exactly one
+    // answer and it is observable (`onPolicy`) rather than inferable.
+    const policy = applyOverride(WORKER_PROFILES[input.profile].resolve(input.policyInputs ?? {}), input.override);
+    input.onPolicy?.(policy);
+    const guards = policy.guards;
+    const clock = guards['worker-timeout'];
+    const timeoutMs = clock.timeoutMs;
     let hint = null;
     // Loop-kill and timeout share one restart budget, mirroring
     // runPhaseChild: a runaway worker gets re-spawned with a corrective
@@ -496,19 +488,15 @@ export async function runWorker(input) {
         // loop === false turns the guard off entirely (detector is null and no
         // tool call is ever flagged); otherwise build a detector from the override
         // or the default research/impl thresholds.
-        const loopDetector = input.loop === false ?
+        const loopDetector = guards.loop.detector === false ?
             null
-            : (() => {
-                const window = input.loop?.window ?? LOOP_WINDOW;
-                const threshold = input.loop?.threshold ?? LOOP_THRESHOLD;
-                return new LoopDetector(window, threshold, input.loop?.pathThreshold ?? threshold);
-            })();
+            : new LoopDetector(guards.loop.detector.window, guards.loop.detector.threshold, guards.loop.detector.pathThreshold);
         // Reset EACH attempt, like the loop detector: a restart discards the
         // previous attempt's calls along with its text, so a fresh child must not
         // inherit a dead streak it did not earn.
-        const stallDetector = input.stallGuard === false ?
+        const stallDetector = guards.loop.progress === false ?
             null
-            : new StallDetector(input.stallGuard?.limit, input.stallGuard?.churnFactor);
+            : new StallDetector(guards.loop.progress.limit, guards.loop.progress.churnFactor);
         // Arm the churn rule BEFORE the first tool call. pi's stream carries no
         // context event (issue #16), so waiting for one leaves the rule
         // permanently disarmed. The parent knows the window at spawn time.
@@ -522,27 +510,28 @@ 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, input.progressTimeoutCeilingMs);
+        const timeout = workerTimeout(input.signal, timeoutMs, clock.progressCeilingMs ?? undefined);
         // 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));
+        const cmdWatch = commandWatch(commandCeilingForAttempt(guards['command-timeout'], hangKills));
         const childSignal = cmdWatch ? AbortSignal.any([timeout.signal, cmdWatch.signal]) : timeout.signal;
         let result;
         try {
             result = await runChildDefault(invocation, input.cwd, childSignal, {
                 mode: 'json-events',
-                ...(input.stall === false ?
+                ...(guards.stalled === false ?
                     {}
                     : {
                         stall: {
-                            afterMs: input.stall?.afterMs ?? STALL_AFTER_MS,
-                            probe: input.stall?.probe
+                            afterMs: guards.stalled.afterMs,
+                            // `null` in the policy means the built-in probe.
+                            // Kept as data so a resolved policy stays plain
+                            // comparable data — see StalledGuard.probe.
+                            probe: guards.stalled.probe
                                 ?? (() => probeModelEndpoints(discoverModelEndpoints()))
                         }
                     }),
-                ...(input.streamInactivityMs ?
-                    { streamInactivityMs: input.streamInactivityMs }
-                    : {}),
+                ...(guards['stream-stall'] ? { streamInactivityMs: guards['stream-stall'] } : {}),
                 onFirstByte: () => (tFirstByte = Date.now()),
                 onToolCall: call => {
                     cmdWatch?.onStart(call);
@@ -551,9 +540,9 @@ export async function runWorker(input) {
                     timeout.progress();
                     // The generic child runner used to name ONE tool and ONE of
                     // its parameters here. It asks the tool's own row now.
-                    if (input.fanoutTimeout
+                    if (clock.fanout
                         && workerChannel(call.name)?.isProjectSourceLookup?.(call.args ?? {}) === true) {
-                        timeout.extend(input.fanoutTimeout.perLookupMs, input.fanoutTimeout.ceilingMs);
+                        timeout.extend(clock.fanout.perLookupMs, clock.fanout.ceilingMs);
                     }
                     if (isGrounding(call.name))
                         groundingRetrievalCount++;
@@ -621,7 +610,7 @@ export async function runWorker(input) {
             // 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)) {
+            if (policy.carryForward && CARRY_FORWARD_REASONS.has(reason)) {
                 const partial = text.trim();
                 // Longest-with-CONTENT wins. Length alone let a preamble sentence
                 // become the answer — see hasAnswerContent.
@@ -652,7 +641,7 @@ export async function runWorker(input) {
             tools,
             restartBudgetSpent,
             connRetries,
-            connectionRetries: input.connectionRetries ?? MAX_LOOP_RESTARTS,
+            connectionRetries: guards['connection-error'],
             leakRetries
         };
         let restarted = false;

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/worker-profiles.d.ts

@@ -0,0 +1,314 @@
+/**
+ * The GUARD POLICY each kind of worker child runs under, keyed on the ways it
+ * can die.
+ *
+ * WHY IT EXISTS. `RunWorkerInput` carried ten guard knobs in four different
+ * shapes — two bare millisecond numbers, three `{...} | false` unions, an
+ * optional object, a boolean and two counts — and three production callers each
+ * hand-picked a different subset of them:
+ *
+ *   gate-child.ts      timeoutMs 0, a per-command watchdog, a stream watchdog,
+ *                      and the path rule disabled. Everything else default.
+ *   research-worker.ts a progress deadline and two off-by-default A/B levers.
+ *                      NO command watchdog, NO stream watchdog. Everything else
+ *                      default.
+ *   pi-worker.ts       nothing at all — every default, silently.
+ *
+ * So "a gate child runs unbounded but with a per-command watchdog; a research
+ * worker is the reverse" existed only as three option literals in three files,
+ * and the reasoning was attached to whichever line happened to need defending.
+ * `gate-child.ts` explained why it disables the path rule and said nothing about
+ * why it takes no progress deadline. Nothing anywhere said that the ad-hoc
+ * `pi-worker` tool is the strictest-clocked of the three. That was not a
+ * decision; it was the residue of never having had a place to write one down.
+ *
+ * WHY IT IS KEYED ON `WorkerKillId`. A guard exists to prevent a specific way a
+ * child can die, so the roster of deaths (`worker-kill.ts`) is the correct key —
+ * the same argument that roster makes for kill CAUSES, one level up. The mapped
+ * type means a tenth cause cannot be added to `WORKER_KILLS` without every
+ * profile deciding what to do about it, and it means the three causes with no
+ * dial say so in the table (`null`) instead of being absent from it.
+ *
+ * The key does NOT partition the knobs one-per-row, and pretending otherwise
+ * would be the lie:
+ *
+ *   `worker-timeout` holds THREE — the cap, the progress ceiling that turns the
+ *   cap from "time allowed" into "time allowed without progress", and the
+ *   fan-out extension. All three move the same deadline; splitting them across
+ *   rows would let a profile set a ceiling for a cap it disabled.
+ *
+ *   `loop` holds TWO detectors. `StallDetector`'s hit IS a `LoopHit` with
+ *   `.stall` set (child-process.ts: "so a stall rides the kill/restart plumbing
+ *   the loop hit already has"), and the restart ladder has ONE rule for both.
+ *   One cause, one row.
+ *
+ * WHAT IS DELIBERATELY NOT UNIFIED.
+ *
+ *   `carryForward` is not a row. It is one switch over the whole run, and WHICH
+ *   causes honour it is already decided by `CARRY_FORWARD_IDS`, derived from the
+ *   roster. A per-cause row here would be a second copy of that set, free to
+ *   disagree with it.
+ *
+ *   The reasoning group is not the profile. `pi-worker.ts` runs `adhoc` guards
+ *   but `groupThinkingArgs('research')`, on purpose. Guards answer "how may this
+ *   child die"; `thinking` answers "how hard may it think". Folding them would
+ *   silently re-level a gate child, which is the exact mistake
+ *   `RunWorkerInput.thinking`'s comment already records.
+ *
+ *   `projectDocsBudget()` (the CAP arm, research-fanout-budget.ts) stays out. It
+ *   bounds what a worker ASKS FOR, via its prompt and its tool, not how it dies.
+ *
+ *   `RESTART_ORDER` and `FAILURE_ORDER` are untouched. This is a third view of
+ *   the same key, not a merge of the two orderings.
+ */
+import type { WorkerKillId } from './worker-kill.js';
+/**
+ * Hard wall-clock bound on a single worker run (one spawn). The exact-match
+ * LoopDetector only catches *identical* repeated tool calls; a model that
+ * thrashes with slightly-varied calls (different grep patterns each time) slips
+ * past it and would otherwise run unbounded. This is the backstop for that case:
+ * after this long with no clean exit, abort and restart with a hint. Sized well
+ * above a healthy worker's observed runtime (~25-130s on the local backend) so
+ * it never trips a legitimately slow run.
+ */
+export declare const RESEARCH_WORKER_TIMEOUT_MS = 240000;
+/**
+ * Output-stall window before the dead-backend probe fires (mx5 run 7: model
+ * server died mid-gate-child, the child hung MUTE for 64 minutes). This is NOT
+ * a wall-clock cap — output progress resets it, and even a fully stalled child
+ * is only killed when the model endpoint is actually unreachable. Sized so a
+ * long local prompt-processing pass (minutes of legitimate silence, server
+ * alive) just gets probed and waits on.
+ */
+export declare const STALL_AFTER_MS = 180000;
+/**
+ * The dead-backend probe. No output for `afterMs` -> probe the model endpoints
+ * pi is configured with -> unreachable -> kill and set `stalled: true`. Output
+ * progress resets it, and a reachable endpoint is treated as proof of life, so
+ * this alone will not end a child that is merely quiet.
+ */
+export interface StalledGuard {
+    afterMs: number;
+    /**
+     * `null` means the built-in endpoint probe, and a PROFILE always writes
+     * `null`. Kept as data rather than a closure so a resolved policy is plain
+     * comparable data — which is what makes the no-behaviour-change proof in
+     * `worker-profiles.test.ts` an equality assertion rather than a hand-written
+     * comparer that skips the one field most likely to be wrong. Tests and
+     * harnesses inject a real probe through the override.
+     */
+    probe: (() => Promise<boolean>) | null;
+}
+/**
+ * The whole-worker deadline. All three fields move the SAME timer, which is why
+ * they share a row: `timeoutMs` is the cap (0 = unbounded), `progressCeilingMs`
+ * turns that cap from "total time allowed" into "time allowed WITHOUT PROGRESS"
+ * up to this absolute bound, and `fanout` pushes the deadline out per
+ * project-source lookup.
+ *
+ * The progress ceiling 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 dead-backend probe already catches on its own terms.
+ *
+ * `fanout` is the SCALE arm of nexttask 5B and is OFF unless both its env vars
+ * are set — see task/research-fanout-budget.ts for why it was not the fix.
+ */
+export interface WorkerTimeoutGuard {
+    /** 0 disables the wall clock entirely: the child runs until it exits. */
+    timeoutMs: number;
+    /**
+     * A tool call or a line of output re-arms the deadline to `now + timeoutMs`,
+     * never past this many ms from the attempt's start. `null` leaves the fixed
+     * cap and makes the re-arm inert.
+     */
+    progressCeilingMs: number | null;
+    /**
+     * Each project-source `pi-worker-docs` call pushes this attempt's deadline
+     * out by `perLookupMs`, never past `ceilingMs` from the attempt's start.
+     */
+    fanout: {
+        perLookupMs: number;
+        ceilingMs: number;
+    } | null;
+}
+/**
+ * The two runaway detectors. ONE row because they are one cause: both return a
+ * `LoopHit` and both are handled by the single `loop` restart rule.
+ *
+ * `detector` judges ARGUMENTS over a 20-call window, so a child that rotates
+ * through MORE DISTINCT CALLS THAN THE WINDOW HOLDS is invisible to it — every
+ * key occurs once per window and the count never reaches the threshold.
+ * Measured: mx5-n 2026-08-27, worker:tooling made 550 calls over exactly 20
+ * distinct files, ~36 reads each, and neither the exact rule nor the path rule
+ * ever tripped. It died 20 minutes later on the absolute progress ceiling,
+ * having done 25s of useful work.
+ *
+ * `progress` judges RESULTS, which a rotating reader cannot vary. It was written
+ * for exactly that class and was wired only into phase children until
+ * `runWorker` grew an option for it.
+ *
+ * Either can be `false` independently — a pass that legitimately revisits one
+ * file raises `pathThreshold`; a harness isolating one rule turns the other off.
+ */
+export interface LoopGuard {
+    detector: {
+        window: number;
+        threshold: number;
+        pathThreshold: number;
+    } | false;
+    progress: {
+        limit: number;
+        churnFactor: number;
+    } | false;
+}
+/**
+ * The knob (if any) that governs each way a worker can die.
+ *
+ * The three `null` rows are not filler. They are the statement that those causes
+ * have no dial: a leaked tool call is bounded by the fixed `MAX_LEAK_RETRIES`,
+ * `aborted` is the caller's own signal, and `exit` is the child deciding to
+ * stop. No profile may tune them, and now no profile can pretend to.
+ */
+interface WorkerGuardShapes {
+    stalled: StalledGuard | false;
+    /**
+     * PER-TOOL-CALL ceiling, ms. 0 = off. The child-side half of the command
+     * watchdog (shared/command-watchdog.ts): arms on each `tool_execution_start`,
+     * disarms on the matching end, and on overrun kills the child and — within
+     * the shared restart budget — re-spawns it with `commandTimeoutHint`.
+     *
+     * WHY IT IS NOT THE WALL CLOCK: that one bounds the whole worker and is
+     * deliberately 0 for gate children, which must run to completion. Neither it
+     * nor the dead-backend probe can catch a hung COMMAND — the probe treats a
+     * reachable model endpoint as proof of life, which it is, even while a `bun
+     * run dev` the model forgot to bound blocks the child forever.
+     *
+     * This is the ceiling for the FIRST attempt; each HANG-caused restart halves
+     * it (`commandCeilingForAttempt` — loop-caused restarts don't count), so a
+     * model that ignores the hint cannot spend the full ceiling again every retry.
+     */
+    'command-timeout': number;
+    /**
+     * Stream-inactivity ceiling, ms (shared/stream-watchdog.ts). 0 = off.
+     *
+     * The dead-backend probe cannot catch a HUNG stream on a HEALTHY backend —
+     * it reads a reachable endpoint as proof of life, which is exactly what run
+     * 14's three hangs looked like. This one asks nothing of the backend: no
+     * output for this long, tool executions excluded, means kill and restart the
+     * attempt with `streamStallHint`, inside the same shared restart budget.
+     */
+    'stream-stall': number;
+    'worker-timeout': WorkerTimeoutGuard;
+    /**
+     * Connection-error restart budget. 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.
+     */
+    'connection-error': number;
+    loop: LoopGuard;
+    'leaked-tool-call': null;
+    aborted: null;
+    exit: null;
+}
+/**
+ * One row per `WorkerKillId`. Indexing the shapes BY the roster's union is the
+ * compile-time bite: drop a row and `WorkerGuardShapes[K]` stops resolving.
+ */
+export type WorkerGuards = {
+    [K in WorkerKillId]: WorkerGuardShapes[K];
+};
+export interface WorkerGuardPolicy {
+    guards: WorkerGuards;
+    /**
+     * Carry a killed attempt's findings into the re-spawn, and never return less
+     * than the best attempt produced. Which CAUSES honour it is not settable —
+     * `CARRY_FORWARD_IDS` derives that from the roster. Cross-cutting, so
+     * deliberately NOT a row; see the header.
+     */
+    carryForward: boolean;
+}
+/** A partial policy. Whole rows only: no deep-partial nobody can read. */
+export type WorkerGuardOverride = {
+    [K in WorkerKillId]?: WorkerGuardShapes[K];
+} & {
+    carryForward?: boolean;
+};
+/** The shipped `detector` half of the `loop` row: the read-only research/impl guard. */
+export declare const DEFAULT_LOOP_DETECTOR: {
+    readonly window: 20;
+    readonly threshold: 5;
+    readonly pathThreshold: 5;
+};
+/**
+ * The shipped `progress` half of the `loop` row.
+ *
+ * Exported for the tests that isolate ONE of the two runaway rules. The row is
+ * whole-row-overridable on purpose, so turning the argument detector off means
+ * restating the result detector; naming the default here keeps that honest
+ * instead of tempting a deep-partial that would let a test silently disable both.
+ */
+export declare const DEFAULT_LOOP_PROGRESS: {
+    readonly limit: 8;
+    readonly churnFactor: 2;
+};
+export type WorkerProfileId = 'research' | 'gate' | 'adhoc';
+/**
+ * The facts a profile needs that are NOT policy: user config, and which of the
+ * four research workers is the docs-capable one.
+ */
+export interface WorkerPolicyInputs {
+    /** gate: `config.requestTimeoutMs`. */
+    commandTimeoutMs?: number;
+    /** gate: `config.streamInactivityMs`. */
+    streamInactivityMs?: number;
+    /** research: only `worker:apis` fans out, so only it can be scaled. */
+    fanoutBounded?: boolean;
+    /** research: the A/B levers' env reader. Injectable for tests. */
+    env?: (key: string) => string | undefined;
+}
+export interface WorkerProfile {
+    id: WorkerProfileId;
+    /** Why THIS child's guards differ. The prose no call site was carrying. */
+    why: string;
+    resolve: (inputs: WorkerPolicyInputs) => WorkerGuardPolicy;
+}
+export declare const WORKER_PROFILES: {
+    readonly research: {
+        readonly id: "research";
+        readonly why: string;
+        readonly resolve: (inputs: WorkerPolicyInputs) => {
+            guards: WorkerGuards;
+            carryForward: boolean;
+        };
+    };
+    readonly gate: {
+        readonly id: "gate";
+        readonly why: string;
+        readonly resolve: (inputs: WorkerPolicyInputs) => {
+            guards: WorkerGuards;
+            carryForward: false;
+        };
+    };
+    readonly adhoc: {
+        readonly id: "adhoc";
+        readonly why: string;
+        readonly resolve: () => {
+            guards: WorkerGuards;
+            carryForward: false;
+        };
+    };
+};
+/** Resolve one profile. The only way a caller should obtain a policy. */
+export declare function workerPolicy(id: WorkerProfileId, inputs?: WorkerPolicyInputs): WorkerGuardPolicy;
+/**
+ * Lay whole rows over a resolved policy.
+ *
+ * For tests and A/B harnesses ONLY. Production code names a profile: an override
+ * at a production call site is the exact "hand-pick a subset" this module exists
+ * to stop, and `worker-profiles.test.ts` fails the build if one appears.
+ */
+export declare function applyOverride(policy: WorkerGuardPolicy, override: WorkerGuardOverride | undefined): WorkerGuardPolicy;
+export {};

package/dist/workers/worker-profiles.js

@@ -0,0 +1,220 @@
+/**
+ * The GUARD POLICY each kind of worker child runs under, keyed on the ways it
+ * can die.
+ *
+ * WHY IT EXISTS. `RunWorkerInput` carried ten guard knobs in four different
+ * shapes — two bare millisecond numbers, three `{...} | false` unions, an
+ * optional object, a boolean and two counts — and three production callers each
+ * hand-picked a different subset of them:
+ *
+ *   gate-child.ts      timeoutMs 0, a per-command watchdog, a stream watchdog,
+ *                      and the path rule disabled. Everything else default.
+ *   research-worker.ts a progress deadline and two off-by-default A/B levers.
+ *                      NO command watchdog, NO stream watchdog. Everything else
+ *                      default.
+ *   pi-worker.ts       nothing at all — every default, silently.
+ *
+ * So "a gate child runs unbounded but with a per-command watchdog; a research
+ * worker is the reverse" existed only as three option literals in three files,
+ * and the reasoning was attached to whichever line happened to need defending.
+ * `gate-child.ts` explained why it disables the path rule and said nothing about
+ * why it takes no progress deadline. Nothing anywhere said that the ad-hoc
+ * `pi-worker` tool is the strictest-clocked of the three. That was not a
+ * decision; it was the residue of never having had a place to write one down.
+ *
+ * WHY IT IS KEYED ON `WorkerKillId`. A guard exists to prevent a specific way a
+ * child can die, so the roster of deaths (`worker-kill.ts`) is the correct key —
+ * the same argument that roster makes for kill CAUSES, one level up. The mapped
+ * type means a tenth cause cannot be added to `WORKER_KILLS` without every
+ * profile deciding what to do about it, and it means the three causes with no
+ * dial say so in the table (`null`) instead of being absent from it.
+ *
+ * The key does NOT partition the knobs one-per-row, and pretending otherwise
+ * would be the lie:
+ *
+ *   `worker-timeout` holds THREE — the cap, the progress ceiling that turns the
+ *   cap from "time allowed" into "time allowed without progress", and the
+ *   fan-out extension. All three move the same deadline; splitting them across
+ *   rows would let a profile set a ceiling for a cap it disabled.
+ *
+ *   `loop` holds TWO detectors. `StallDetector`'s hit IS a `LoopHit` with
+ *   `.stall` set (child-process.ts: "so a stall rides the kill/restart plumbing
+ *   the loop hit already has"), and the restart ladder has ONE rule for both.
+ *   One cause, one row.
+ *
+ * WHAT IS DELIBERATELY NOT UNIFIED.
+ *
+ *   `carryForward` is not a row. It is one switch over the whole run, and WHICH
+ *   causes honour it is already decided by `CARRY_FORWARD_IDS`, derived from the
+ *   roster. A per-cause row here would be a second copy of that set, free to
+ *   disagree with it.
+ *
+ *   The reasoning group is not the profile. `pi-worker.ts` runs `adhoc` guards
+ *   but `groupThinkingArgs('research')`, on purpose. Guards answer "how may this
+ *   child die"; `thinking` answers "how hard may it think". Folding them would
+ *   silently re-level a gate child, which is the exact mistake
+ *   `RunWorkerInput.thinking`'s comment already records.
+ *
+ *   `projectDocsBudget()` (the CAP arm, research-fanout-budget.ts) stays out. It
+ *   bounds what a worker ASKS FOR, via its prompt and its tool, not how it dies.
+ *
+ *   `RESTART_ORDER` and `FAILURE_ORDER` are untouched. This is a third view of
+ *   the same key, not a merge of the two orderings.
+ */
+import { LOOP_THRESHOLD, LOOP_WINDOW, MAX_LOOP_RESTARTS } from '../task/child-runner.js';
+import { CONTEXT_CHURN_FACTOR, NO_PROGRESS_LIMIT } from '../task/stall-detector.js';
+import { fanoutTimeoutPolicy, workerCarryForward, workerProgressCeilingMs } from '../task/research-fanout-budget.js';
+/**
+ * Hard wall-clock bound on a single worker run (one spawn). The exact-match
+ * LoopDetector only catches *identical* repeated tool calls; a model that
+ * thrashes with slightly-varied calls (different grep patterns each time) slips
+ * past it and would otherwise run unbounded. This is the backstop for that case:
+ * after this long with no clean exit, abort and restart with a hint. Sized well
+ * above a healthy worker's observed runtime (~25-130s on the local backend) so
+ * it never trips a legitimately slow run.
+ */
+export const RESEARCH_WORKER_TIMEOUT_MS = 240_000;
+/**
+ * Output-stall window before the dead-backend probe fires (mx5 run 7: model
+ * server died mid-gate-child, the child hung MUTE for 64 minutes). This is NOT
+ * a wall-clock cap — output progress resets it, and even a fully stalled child
+ * is only killed when the model endpoint is actually unreachable. Sized so a
+ * long local prompt-processing pass (minutes of legitimate silence, server
+ * alive) just gets probed and waits on.
+ */
+export const STALL_AFTER_MS = 180_000;
+/** The shipped `detector` half of the `loop` row: the read-only research/impl guard. */
+export const DEFAULT_LOOP_DETECTOR = {
+    window: LOOP_WINDOW,
+    threshold: LOOP_THRESHOLD,
+    pathThreshold: LOOP_THRESHOLD
+};
+/**
+ * The shipped `progress` half of the `loop` row.
+ *
+ * Exported for the tests that isolate ONE of the two runaway rules. The row is
+ * whole-row-overridable on purpose, so turning the argument detector off means
+ * restating the result detector; naming the default here keeps that honest
+ * instead of tempting a deep-partial that would let a test silently disable both.
+ */
+export const DEFAULT_LOOP_PROGRESS = {
+    limit: NO_PROGRESS_LIMIT,
+    churnFactor: CONTEXT_CHURN_FACTOR
+};
+/**
+ * Every guard at its default. `adhoc` IS this; the other two are this plus a
+ * named departure, so a diff between two profiles is a short list rather than a
+ * re-reading of two literals.
+ */
+function baseGuards() {
+    return {
+        stalled: { afterMs: STALL_AFTER_MS, probe: null },
+        'command-timeout': 0,
+        'stream-stall': 0,
+        'worker-timeout': {
+            timeoutMs: RESEARCH_WORKER_TIMEOUT_MS,
+            progressCeilingMs: null,
+            fanout: null
+        },
+        'connection-error': MAX_LOOP_RESTARTS,
+        loop: { detector: { ...DEFAULT_LOOP_DETECTOR }, progress: { ...DEFAULT_LOOP_PROGRESS } },
+        'leaked-tool-call': null,
+        aborted: null,
+        exit: null
+    };
+}
+export const WORKER_PROFILES = {
+    research: {
+        id: 'research',
+        why: 'The four read-only survey workers. Their fault is over-EXPLORATION, not '
+            + 'a hung command: they get no bash, so no tool call can block forever, '
+            + 'and the command and stream watchdogs stay off. What they do hit is the '
+            + 'clock — mx5 run 18 measured r(project lookups, wall clock) = 0.909, '
+            + 'with every worker past 46 lookups burning all three attempts. Hence the '
+            + 'progress deadline (nexttask 9, 42 trials/arm: worker-timeout restarts '
+            + '22/24 -> 0/24): the 240s cap now means 240s WITHOUT PROGRESS, up to a '
+            + '20-minute backstop. The fan-out extension and carry-forward remain OFF '
+            + 'unless their env var is set — see research-fanout-budget.ts.',
+        resolve: inputs => {
+            const guards = baseGuards();
+            guards['worker-timeout'] = {
+                timeoutMs: RESEARCH_WORKER_TIMEOUT_MS,
+                progressCeilingMs: workerProgressCeilingMs(inputs.env),
+                fanout: inputs.fanoutBounded === true ? fanoutTimeoutPolicy(inputs.env) : null
+            };
+            return { guards, carryForward: workerCarryForward(inputs.env) };
+        }
+    },
+    gate: {
+        id: 'gate',
+        why: 'The post-implementation verify/enforce/critique children. They WRITE, '
+            + 'and they legitimately read and edit the same file many times, so the '
+            + 'research guards mislabel the job as a runaway and kill good work (mx5 '
+            + 'TASK_0002). Two departures follow from that. The wall clock is OFF — '
+            + 'these passes must be allowed to finish however long they take. And the '
+            + 'path-revisit rule is disabled (pathThreshold Infinity), leaving only '
+            + 'the exact-match rule, so revisiting one file never trips but a '
+            + 'literally-identical call repeated past threshold still does. What '
+            + 'replaces the wall clock is the pair the research workers do not need: '
+            + 'a per-command watchdog, because a gate child HAS bash and a `bun run '
+            + 'dev` it forgot to bound blocks it forever while the stall probe reads '
+            + 'the live model endpoint as proof of life; and a stream watchdog, for '
+            + "run 14's three hangs on a HEALTHY backend. Both take their ceilings "
+            + 'from user config, so they are inputs, not policy.',
+        resolve: inputs => {
+            const guards = baseGuards();
+            guards['command-timeout'] = inputs.commandTimeoutMs ?? 0;
+            guards['stream-stall'] = inputs.streamInactivityMs ?? 0;
+            guards['worker-timeout'] = { timeoutMs: 0, progressCeilingMs: null, fanout: null };
+            guards.loop = {
+                ...guards.loop,
+                detector: { ...DEFAULT_LOOP_DETECTOR, pathThreshold: Number.POSITIVE_INFINITY }
+            };
+            return { guards, carryForward: false };
+        }
+    },
+    adhoc: {
+        id: 'adhoc',
+        why: 'The model-dispatched `pi-worker` tool. Every guard at its default, and '
+            + 'this row exists so that is a DECISION rather than the absence of one — '
+            + 'the call site passed nothing, and nobody could see what it therefore '
+            + 'got. What the table now makes visible is an asymmetry: this is the '
+            + 'strictest-clocked of the three children. It runs a FIXED 240s cap, '
+            + 'because `progressCeilingMs` is null and the deadline re-arm is inert '
+            + 'without one, while a research worker doing the same read-only '
+            + 'exploration gets 240s WITHOUT PROGRESS up to 20 minutes. That '
+            + 'difference is preserved exactly here and is NOT defended: the progress '
+            + 'deadline was measured for the research workers (nexttask 9) and has '
+            + 'never been measured for this tool. It is a candidate, not a bug.',
+        resolve: () => ({ guards: baseGuards(), carryForward: false })
+        // `as const satisfies`, not an annotation — the same reason RESTART_ORDER
+        // gives: an annotation widens each row back to `WorkerProfile`, and the
+        // `why` strings and literal ids stop being visible to a reader or a test.
+    }
+};
+/** Resolve one profile. The only way a caller should obtain a policy. */
+export function workerPolicy(id, inputs = {}) {
+    return WORKER_PROFILES[id].resolve(inputs);
+}
+/**
+ * Lay whole rows over a resolved policy.
+ *
+ * For tests and A/B harnesses ONLY. Production code names a profile: an override
+ * at a production call site is the exact "hand-pick a subset" this module exists
+ * to stop, and `worker-profiles.test.ts` fails the build if one appears.
+ */
+export function applyOverride(policy, override) {
+    if (override === undefined)
+        return policy;
+    const { carryForward, ...rows } = override;
+    // Present-but-`undefined` is DROPPED, not laid down. A conditional row is
+    // the natural way to write a swept arm — `{'command-timeout': on ? ms :
+    // undefined}` — and a plain spread would put `undefined` into the policy,
+    // which either disarms the guard silently or throws on `clock.timeoutMs`.
+    // The repo has no `exactOptionalPropertyTypes`, so the compiler allows it.
+    const set = Object.fromEntries(Object.entries(rows).filter(([, v]) => v !== undefined));
+    return {
+        guards: { ...policy.guards, ...set },
+        carryForward: carryForward ?? policy.carryForward
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.38.24",
+    "version": "0.38.25",
     "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",