@mjasnikovs/pi-task 0.38.23 → 0.38.25

package/dist/workers/worker-kill.js

@@ -0,0 +1,124 @@
+/**
+ * The ROSTER of ways a worker child can die, and what each one implies.
+ *
+ * WHY IT EXISTS. One kill cause was named in six unlinked places: a
+ * `RunWorkerInput` guard option, a `RunWorkerResult` field, the
+ * `WorkerRestartReason` union, a `RESTART_RULES` row, the `CARRY_FORWARD_REASONS`
+ * set, and a `FAILURE_RULES` row. Adding one meant six coordinated edits, and
+ * only two of them failed to compile if you skipped one. That is not
+ * hypothetical: `worker-failure.ts`'s own header records the bug it cost —
+ * *"`streamStalled` was added to the result and to `finalAttemptFailed`, but the
+ * enforce ladder never grew an arm for it, so an enforcement child killed for a
+ * hung model stream fell all the way through to `if (aborted) return
+ * USER_CANCELLED`"*. That fix closed the READER side. This closes the author
+ * side.
+ *
+ * WHAT IS AND IS NOT UNIFIED. The roster is one table. The two ORDERINGS stay
+ * two, because they genuinely disagree and each says so in its own prose: the
+ * restart ladder puts `loop` first (its hint is the most specific thing to tell a
+ * re-spawn), and the failure ladder puts `stalled` first (the diagnosis most
+ * easily lost behind the `aborted` every kill path sets). Folding two
+ * precedences into one row type would need an escape hatch per row — the same
+ * objection that got a `WriteGuard` row table rejected. What the orderings gain
+ * here is that neither can name a cause with no row, nor silently omit one.
+ *
+ * Not every cause appears in both ladders, and that asymmetry is real:
+ * `connection-error` is restartable but is reported as a `modelError`, never as a
+ * kill; `stalled`, `aborted` and `exit` end an attempt outright and no hint would
+ * help.
+ */
+export const WORKER_KILLS = [
+    {
+        id: 'stalled',
+        resultField: 'stalled',
+        carryForward: false,
+        restartable: false,
+        reported: true
+    },
+    {
+        id: 'command-timeout',
+        resultField: 'commandTimedOut',
+        carryForward: true,
+        restartable: true,
+        reported: true
+    },
+    {
+        id: 'stream-stall',
+        resultField: 'streamStalled',
+        carryForward: true,
+        restartable: true,
+        reported: true
+    },
+    {
+        id: 'worker-timeout',
+        resultField: 'timedOut',
+        carryForward: true,
+        restartable: true,
+        reported: true
+    },
+    {
+        id: 'connection-error',
+        resultField: null,
+        carryForward: true,
+        restartable: true,
+        reported: false
+    },
+    { id: 'loop', resultField: 'loopHit', carryForward: false, restartable: true, reported: true },
+    {
+        id: 'leaked-tool-call',
+        resultField: 'leakedToolCall',
+        carryForward: false,
+        restartable: true,
+        reported: true
+    },
+    { id: 'aborted', resultField: null, carryForward: false, restartable: false, reported: true },
+    { id: 'exit', resultField: null, carryForward: false, restartable: false, reported: true }
+];
+/** Look one cause up. `undefined` only for an id with no row, which the suite forbids. */
+export function workerKill(id) {
+    return WORKER_KILLS.find(k => k.id === id);
+}
+/**
+ * The restart ladder's precedence, as ids. `RESTART_RULES` must be exactly this,
+ * in this order.
+ *
+ * `loop` leads: its hint names the offending call, which is the most useful thing
+ * to tell a re-spawn. The two watchdogs come before the wall clock because each
+ * is the narrower diagnosis, and they cannot be confused with it — a watchdog
+ * kill leaves the worker's own timeout flag false.
+ */
+export const RESTART_ORDER = [
+    'loop',
+    'command-timeout',
+    'stream-stall',
+    'worker-timeout',
+    'connection-error',
+    'leaked-tool-call'
+    // `as const satisfies`, not an annotation: `WorkerRestartReason` is
+    // `(typeof RESTART_ORDER)[number]`, and a `readonly WorkerKillId[]`
+    // annotation collapses that to the whole `WorkerKillId` union — which would
+    // let `noteRestart('aborted')` compile for a cause the restart ladder has no
+    // rule for. `satisfies` keeps the membership check without the widening.
+];
+/**
+ * The failure ladder's precedence, as ids. `FAILURE_RULES` must be exactly this,
+ * in this order.
+ *
+ * DIFFERENT from `RESTART_ORDER`, deliberately. Every kill path also sets
+ * `aborted` and a non-zero exit, so the specific causes must all be matched
+ * before the two generic ones or a dead backend is reported as "you cancelled".
+ * `stalled` leads because it is both the most specific diagnosis and the one most
+ * easily lost.
+ */
+export const FAILURE_ORDER = [
+    'stalled',
+    'command-timeout',
+    'stream-stall',
+    'worker-timeout',
+    'loop',
+    'leaked-tool-call',
+    'aborted',
+    'exit'
+];
+/** The causes whose partial output is worth keeping. Derived, never hand-kept. */
+export const CARRY_FORWARD_IDS = new Set(WORKER_KILLS.filter(k => k.carryForward).map(k => k.id));

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.23",
+    "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",