@mjasnikovs/pi-task 0.38.28 → 0.38.30

package/dist/workers/worker-failure.js

@@ -5,25 +5,24 @@
  * Why this module exists. `RunWorkerResult` reports each kill cause as its own
  * optional field (`loopHit`, `timedOut`, `stalled`, `commandTimedOut`,
  * `streamStalled`, `leakedToolCall`, `aborted`, `exitCode`), and every kill path
- * ALSO sets `aborted` and a non-zero exit — killProc flips those on every route
- * out. So a consumer cannot read the fields in any order it likes: the specific
- * causes must be matched before the generic `aborted`/`exitCode` ones, or a dead
- * backend is reported to the user as "you cancelled".
+ * ALSO sets the two generic ones. `killProc` sets `aborted` on every route out,
+ * and pi's own print/json mode installs a SIGTERM handler that exits 143, so a
+ * terminated child carries a non-zero exit too. So a consumer cannot read the
+ * fields in any order it likes: the specific causes must be matched before the
+ * generic `aborted`/`exitCode` ones, or a dead backend is reported to the user as
+ * "you cancelled".
  *
- * That rule used to live as prose in three doc comments and as the source order
- * of three hand-written ladders (`classifyEnforceChildFailure`,
- * `classifyResearchWorker`, and the gate's own reading). Three copies of an
- * ordering is three chances to drift, and it had already drifted: `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` — the
- * exact mislabel the comment above that line warns against.
+ * Written as prose, or as the source order of each consumer's own hand-rolled
+ * ladder, that rule gets a fresh chance to drift per consumer — and the failure is
+ * silent: add a new kill cause to the result, forget one ladder's arm for it, and
+ * that consumer falls through to `if (aborted)` and reports a cancel.
  *
- * The fix is to make the order data. `FAILURE_RULES` is ordered, the first
- * matching row wins, and consumers `switch` on the resulting `kind` instead of
- * re-deriving the ladder. A new kill cause is one row here plus a compile error
- * in every consumer that has not handled it — which is what makes the drift that
- * caused the bug impossible rather than merely fixed.
+ * So the order is DATA. `FAILURE_RULES` is ordered, the first matching row wins,
+ * and consumers `switch` on the resulting `kind` — `classifyEnforceChildFailure`
+ * (enforce-guidelines.ts) and `classifyResearchWorker` (research-worker.ts) both
+ * call `classifyWorkerFailure` and say only what each cause means to THEM. A new
+ * kill cause is one row here plus a compile error in every consumer that has not
+ * handled it.
  */
 const _kindsAreKills = true;
 void _kindsAreKills;
@@ -45,9 +44,8 @@ void _kindsAreKills;
  *     class of event: a watchdog, not the model, ended the attempt.
  *  4. `worker-timeout` — the wall-clock backstop.
  *  5. `loop` — killed for repeating one tool call past threshold. After the
- *     timeouts, matching the enforce ladder this replaces; in practice the two
- *     cannot both fire, since a loop kill stops the attempt before its own timer
- *     can expire.
+ *     timeouts: a loop kill ends the attempt, so its own timer does not go on to
+ *     expire as well.
  *  6. `leaked-tool-call` — the model wrote a call as prose instead of invoking
  *     it. Only ever set on an otherwise clean run.
  *  7. `aborted` — no specific cause survived, so this really is a cancel.
@@ -78,31 +76,20 @@ export const FAILURE_RULES = [
     { id: 'aborted', match: r => (r.aborted ? { kind: 'aborted' } : null) },
     { id: 'exit', match: r => (r.exitCode !== 0 ? { kind: 'exit', code: r.exitCode } : null) }
 ];
-/**
- * Classify a finished child. Returns `undefined` when nothing killed it —
- * which is not the same as "it answered": the text may still be empty, and that
- * judgement belongs to the caller.
- */
 /**
  * What a worker failure SAYS to the caller that asked for the work.
  *
- * WHY IT EXISTS. The ladder above already names the cause exactly, with its
- * detail — which tool hung, how long the stream was idle, which exit code. None
- * of that reached a human. `formatChildFailure` was handed a `ChildOutcome`
- * (`{aborted, exitCode, stderr}`) and answered `if (aborted) return
- * abortedMessage`, so a 240s wall-clock kill, a hung `bash`, a dead model
- * backend, a loop kill and a user pressing ESC all printed the SAME four words.
- * The discriminating value was computed a line later by `childFailureReason` and
- * put in the debug trail, which a user reading a tool result never sees.
- *
- * That is not only unhelpful; it is why the `pi-worker` tool's 240s cap has no
- * base rate. 53 recorded invocations across eight repos carry 14 failures, and
- * NOTHING in the transcript says which of them ran out of time — the honest
- * bound recoverable from timestamps alone is "somewhere between 0 and 8".
+ * WHY IT EXISTS. The ladder above already names the cause exactly, with its detail
+ * — which tool hung, how long the stream was idle, which exit code. Answering
+ * `if (aborted) return abortedMessage` instead throws all of it away: a wall-clock
+ * kill, a hung `bash`, a dead model backend, a loop kill and a user pressing ESC
+ * then print the SAME words, and the discriminating value only reaches a debug
+ * trail a user reading a tool result never sees. Every arm below returns a
+ * different message, and only `aborted` returns the caller's own.
  *
  * A switch, not a table: `WorkerFailure` is a discriminated union carrying a
  * different payload per arm, so the exhaustiveness check is the compiler's and a
- * ninth arm cannot be added without a message.
+ * new arm cannot be added without a message.
  */
 export function describeWorkerFailure(f, 
 /** What a genuine user cancel says. The caller's wording — only this arm is theirs. */
@@ -137,6 +124,11 @@ stderr = '') {
             return `Worker exited ${f.code}.\n${stderr.trim().slice(-500) || '(no stderr)'}`;
     }
 }
+/**
+ * Classify a finished child against the ladder. Returns `undefined` when nothing
+ * killed it — which is not the same as "it answered": the text may still be empty,
+ * and that judgement belongs to the caller.
+ */
 export function classifyWorkerFailure(r) {
     for (const rule of FAILURE_RULES) {
         const hit = rule.match(r);

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

@@ -1,31 +1,28 @@
 /**
  * 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
+ * WHY IT EXISTS. Without it, one kill cause is 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.
+ * `WorkerRestartReason` union, a `RESTART_RULES` row, the carry-forward set, and a
+ * `FAILURE_RULES` row. Adding a cause is six coordinated edits, and most of them
+ * still compile if one is skipped — so the new cause simply does not exist on
+ * whichever path was missed. `worker-failure.ts` closes the READER side of that;
+ * 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.
+ * 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. 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.
+ * Not every cause appears in both ladders, and that asymmetry is real. Six of the
+ * nine are `restartable` and those six are exactly RESTART_ORDER; eight are
+ * `reported` and those eight are exactly FAILURE_ORDER. `connection-error` is the
+ * one that restarts without ever being reported as a kill — it reaches the caller
+ * as a `modelError`. `stalled`, `aborted` and `exit` end an attempt outright, and
+ * no hint would help.
  */
 /** Every way a worker attempt can end other than by answering. */
 export type WorkerKillId = 'stalled' | 'command-timeout' | 'stream-stall' | 'worker-timeout' | 'connection-error' | 'loop' | 'leaked-tool-call' | 'aborted' | 'exit';
@@ -37,18 +34,20 @@ export interface WorkerKill {
      * (`connection-error` arrives as `modelError`; `aborted` and `exit` are the
      * generic fields every kill path also sets).
      *
-     * A string rather than `keyof RunWorkerResult` so this module stays free of
-     * pi-worker-core's import graph; `worker-kill.test.ts` checks it against the
-     * real interface.
+     * Null for three rows: `connection-error`, `aborted` and `exit`. A string rather
+     * than `keyof RunWorkerResult` so this module stays out of pi-worker-core's
+     * import graph; worker-kill.test.ts checks every non-null one against a real
+     * result object.
      */
     resultField: string | null;
     /**
      * Is a killed attempt's partial output worth carrying into the next one?
      *
-     * A clock kill, a hung tool, an idle stream and a dropped socket all discard
-     * work the model genuinely did. A loop kill and a leaked tool call do not —
-     * the first is by definition the same call repeated, the second is malformed
-     * protocol text, and replaying either would feed the failure back to itself.
+     * True for exactly four: a clock kill, a hung tool, an idle stream and a dropped
+     * socket all discard work the model genuinely did. A loop kill and a leaked tool
+     * call do not — the first is by definition the same call repeated, the second is
+     * malformed protocol text, and replaying either would feed the failure back to
+     * itself.
      */
     carryForward: boolean;
     /** Does the restart ladder have a rule for this cause? */

package/dist/workers/worker-kill.js

@@ -1,31 +1,28 @@
 /**
  * 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
+ * WHY IT EXISTS. Without it, one kill cause is 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.
+ * `WorkerRestartReason` union, a `RESTART_RULES` row, the carry-forward set, and a
+ * `FAILURE_RULES` row. Adding a cause is six coordinated edits, and most of them
+ * still compile if one is skipped — so the new cause simply does not exist on
+ * whichever path was missed. `worker-failure.ts` closes the READER side of that;
+ * 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.
+ * 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. 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.
+ * Not every cause appears in both ladders, and that asymmetry is real. Six of the
+ * nine are `restartable` and those six are exactly RESTART_ORDER; eight are
+ * `reported` and those eight are exactly FAILURE_ORDER. `connection-error` is the
+ * one that restarts without ever being reported as a kill — it reaches the caller
+ * as a `modelError`. `stalled`, `aborted` and `exit` end an attempt outright, and
+ * no hint would help.
  */
 export const WORKER_KILLS = [
     {

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

@@ -2,25 +2,14 @@
  * 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 EXISTS. As independent options on `RunWorkerInput`, ten guard knobs in
+ * four different shapes, each of the three production callers hand-picks its own
+ * subset — and "a gate child runs unbounded but with a per-command watchdog; a
+ * research worker is the reverse" then exists only as three option literals in
+ * three files. The reasoning attaches to whichever line happened to need
+ * defending, a caller that names nothing gets a full policy silently, and no file
+ * is the place to say which child is the strictest-clocked of the three. That is
+ * not a decision; it is the residue of having nowhere 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 —
@@ -55,8 +44,8 @@
  *   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.
+ *   `projectDocsBudget()` (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.
@@ -67,18 +56,20 @@ import type { WorkerKillId } from './worker-kill.js';
  * 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.
+ * after this long with no clean exit, abort and restart with a hint.
+ *
+ * A fixed elapsed-time cap is a poor bound on a read-only worker — see the
+ * `adhoc` profile's `why`, which is why that profile disables it. The two
+ * profiles that keep it pair it with a progress ceiling or accept the trade.
  */
 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.
+ * Output-stall window before the dead-backend probe fires: a model server that
+ * dies mid-child leaves it hung MUTE with nothing else to notice. This is NOT a
+ * wall-clock cap — output progress resets it, and even a fully stalled child is
+ * killed only when the model endpoint is actually unreachable. Sized so a long
+ * local prompt-processing pass, which is minutes of legitimate silence from a
+ * live server, gets probed and then waited on.
  */
 export declare const STALL_AFTER_MS = 180000;
 /**
@@ -111,8 +102,8 @@ export interface StalledGuard {
  * 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.
+ * `fanout` is off unless BOTH of its env vars are set — `fanoutTimeoutPolicy`
+ * returns null when either the per-lookup or the ceiling value is missing.
  */
 export interface WorkerTimeoutGuard {
     /** 0 disables the wall clock entirely: the child runs until it exits. */
@@ -138,15 +129,13 @@ export interface WorkerTimeoutGuard {
  *
  * `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.
+ * key occurs once per window and the count never reaches the threshold. A worker
+ * rotating over as many distinct files as the window holds can re-read every one
+ * of them repeatedly without either the exact rule or the path rule tripping, and
+ * then die on the absolute deadline having produced almost nothing.
  *
- * `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.
+ * `progress` judges RESULTS, which a rotating reader cannot vary. It is the rule
+ * written for exactly that class.
  *
  * Either can be `false` independently — a pass that legitimately revisits one
  * file raises `pathThreshold`; a harness isolating one rule turns the other off.
@@ -192,20 +181,19 @@ interface WorkerGuardShapes {
     /**
      * 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.
+     * The dead-backend probe cannot catch a HUNG stream on a HEALTHY backend: it
+     * reads a reachable endpoint as proof of life, which a hung stream leaves
+     * intact. 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.
+     * actually binds — a worker that already spent the budget looping does not get
+     * extra lives here. 0 turns the retry off entirely, which is how a harness
+     * obtains a no-retry arm from a build that ships the retry.
      */
     'connection-error': number;
     loop: LoopGuard;
@@ -266,7 +254,8 @@ export interface WorkerPolicyInputs {
     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. */
+    /** research: the env reader the fanout and progress-ceiling levers use.
+     *  Injectable so a test does not depend on the machine's environment. */
     env?: (key: string) => string | undefined;
 }
 export interface WorkerProfile {
@@ -306,9 +295,10 @@ export declare function workerPolicy(id: WorkerProfileId, inputs?: WorkerPolicyI
 /**
  * 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.
+ * For tests and 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 scans src/ for a leading `override:` and fails
+ * on any hit.
  */
 export declare function applyOverride(policy: WorkerGuardPolicy, override: WorkerGuardOverride | undefined): WorkerGuardPolicy;
 export {};

package/dist/workers/worker-profiles.js

@@ -2,25 +2,14 @@
  * 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 EXISTS. As independent options on `RunWorkerInput`, ten guard knobs in
+ * four different shapes, each of the three production callers hand-picks its own
+ * subset — and "a gate child runs unbounded but with a per-command watchdog; a
+ * research worker is the reverse" then exists only as three option literals in
+ * three files. The reasoning attaches to whichever line happened to need
+ * defending, a caller that names nothing gets a full policy silently, and no file
+ * is the place to say which child is the strictest-clocked of the three. That is
+ * not a decision; it is the residue of having nowhere 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 —
@@ -55,8 +44,8 @@
  *   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.
+ *   `projectDocsBudget()` (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.
@@ -69,18 +58,20 @@ import { fanoutTimeoutPolicy, workerCarryForward, workerProgressCeilingMs } from
  * 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.
+ * after this long with no clean exit, abort and restart with a hint.
+ *
+ * A fixed elapsed-time cap is a poor bound on a read-only worker — see the
+ * `adhoc` profile's `why`, which is why that profile disables it. The two
+ * profiles that keep it pair it with a progress ceiling or accept the trade.
  */
 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.
+ * Output-stall window before the dead-backend probe fires: a model server that
+ * dies mid-child leaves it hung MUTE with nothing else to notice. This is NOT a
+ * wall-clock cap — output progress resets it, and even a fully stalled child is
+ * killed only when the model endpoint is actually unreachable. Sized so a long
+ * local prompt-processing pass, which is minutes of legitimate silence from a
+ * live server, gets probed and then waited on.
  */
 export const STALL_AFTER_MS = 180_000;
 /** The shipped `detector` half of the `loop` row: the read-only research/impl guard. */
@@ -219,19 +210,20 @@ export function workerPolicy(id, 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.
+ * For tests and 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 scans src/ for a leading `override:` and fails
+ * on any hit.
  */
 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.
+    // Present-but-`undefined` is DROPPED, not laid down. A conditional row is the
+    // natural way to write one — `{'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`. This tsconfig does not set
+    // `exactOptionalPropertyTypes`, so the compiler allows it through.
     const set = Object.fromEntries(Object.entries(rows).filter(([, v]) => v !== undefined));
     return {
         guards: { ...policy.guards, ...set },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.38.28",
+    "version": "0.38.30",
     "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",
@@ -13,8 +13,9 @@
     ],
     "scripts": {
         "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
-        "lint": "prettier --log-level warn --write 'src/**/*.ts' && eslint --fix . && tsc --noEmit && tsc -p scripts/tsconfig.json --noEmit",
-        "test": "cross-env AGENT=1 bun test --isolate src/ scripts/",
+        "lint": "prettier --log-level warn --write '{src,test}/**/*.ts' && eslint --fix . && tsc --noEmit",
+        "lint:check": "prettier --check '{src,test}/**/*.ts' && eslint . --max-warnings 0 && tsc --noEmit",
+        "test": "cross-env AGENT=1 bun test --isolate test/ scripts/",
         "prepublishOnly": "bun run build"
     },
     "peerDependencies": {
@@ -41,12 +42,13 @@
         "@types/turndown": "5.0.6",
         "@types/web-push": "3.6.4",
         "@types/ws": "8.18.1",
-        "cross-env": "^10.1.0",
-        "eslint": "10.2.1",
-        "globals": "17.5.0",
-        "prettier": "3.8.3",
+        "cross-env": "10.1.0",
+        "eslint": "10.9.1",
+        "eslint-config-prettier": "10.1.8",
+        "globals": "17.11.0",
+        "prettier": "3.9.6",
         "typescript": "6.0.3",
-        "typescript-eslint": "8.58.2"
+        "typescript-eslint": "8.68.0"
     },
     "keywords": [
         "pi-package",