@mjasnikovs/pi-task 0.38.23 → 0.38.25

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

@@ -0,0 +1,72 @@
+/**
+ * The docs TAIL — concatenate the chunks, extract against them, verify the
+ * citation, format the answer — written once, with the corpus as a row.
+ *
+ * WHY. This sequence existed three times: the project-source arm of
+ * `pi-worker-docs`, its package arm, and `docsFocused` in `docs-core`. The fetch
+ * channel proves the shape is avoidable — `fetchFocused` is one core and
+ * `pi-worker-fetch`'s `run` is 60 lines, while the docs registration was 293 for
+ * the same job over two corpora.
+ *
+ * The copies had drifted, in the place hand-flattening always drifts: the
+ * package arm's ERROR path dropped `autoInstallPin`, which both of its sibling
+ * paths keep — so a package that was auto-installed and then failed to re-resolve
+ * lost the `versionSource`/`declaredRange` provenance the last defect in this
+ * area was about.
+ *
+ * A CORPUS is what genuinely varies: the prompt, the header the answer is
+ * introduced by, and what an abort of it is called. Everything a corpus does NOT
+ * vary — where the content comes from, the version banner, the type-only
+ * detector, the details bag — stays with its caller, because those differ in kind
+ * and not in value.
+ */
+import type { SpawnFn } from '../shared/child-process.js';
+import { type FocusedAnswer, type FocusedFailure } from './focused-extractor.js';
+/** The two corpora a docs lookup can read. A third (`page`) already has a prompt. */
+export type DocsCorpusId = 'package' | 'project';
+export interface DocsCorpus {
+    id: DocsCorpusId;
+    /** The extraction prompt for this corpus, over the concatenated content. */
+    buildPrompt: (query: string, content: string) => string;
+    /** The line the formatted answer is introduced by. */
+    header: string;
+    /** What an abort of this corpus's lookup is called, in the failure text. */
+    abortedMessage: string;
+}
+export interface DocsLookupInput {
+    corpus: DocsCorpus;
+    /** The retrieved chunks, in retrieval order. */
+    chunks: ReadonlyArray<{
+        content: string;
+    }>;
+    query: string;
+    cwd: string;
+    signal?: AbortSignal;
+    spawn?: SpawnFn;
+    /**
+     * The `extraction` group's `--thinking` fragment. Resolved by the CALLER so
+     * this module — like the extractor it wraps — never reads ambient config.
+     */
+    thinking: readonly string[];
+}
+export type DocsLookup = {
+    kind: 'answer';
+    /** The formatted answer: header, answer, and the verified excerpt. */
+    body: string;
+    /** Exactly what was prompted with, and what the citation was verified against. */
+    content: string;
+    extraction: FocusedAnswer;
+    /** Undefined when there was no excerpt to check. */
+    excerptVerified?: boolean;
+} | {
+    kind: 'failed';
+    extraction: FocusedFailure;
+};
+/**
+ * Run one docs lookup over already-retrieved chunks.
+ *
+ * The citation is verified against exactly the text that was prompted with — the
+ * concatenation, not a superset. (`fetch` is the one site that verifies against a
+ * superset; see `FocusedRequest.verifyAgainst`.)
+ */
+export declare function docsLookup(input: DocsLookupInput): Promise<DocsLookup>;

package/dist/workers/docs-lookup.js

@@ -0,0 +1,53 @@
+/**
+ * The docs TAIL — concatenate the chunks, extract against them, verify the
+ * citation, format the answer — written once, with the corpus as a row.
+ *
+ * WHY. This sequence existed three times: the project-source arm of
+ * `pi-worker-docs`, its package arm, and `docsFocused` in `docs-core`. The fetch
+ * channel proves the shape is avoidable — `fetchFocused` is one core and
+ * `pi-worker-fetch`'s `run` is 60 lines, while the docs registration was 293 for
+ * the same job over two corpora.
+ *
+ * The copies had drifted, in the place hand-flattening always drifts: the
+ * package arm's ERROR path dropped `autoInstallPin`, which both of its sibling
+ * paths keep — so a package that was auto-installed and then failed to re-resolve
+ * lost the `versionSource`/`declaredRange` provenance the last defect in this
+ * area was about.
+ *
+ * A CORPUS is what genuinely varies: the prompt, the header the answer is
+ * introduced by, and what an abort of it is called. Everything a corpus does NOT
+ * vary — where the content comes from, the version banner, the type-only
+ * detector, the details bag — stays with its caller, because those differ in kind
+ * and not in value.
+ */
+import { formatResultText } from '../shared/child-output.js';
+import { runFocusedExtraction } from './focused-extractor.js';
+/**
+ * Run one docs lookup over already-retrieved chunks.
+ *
+ * The citation is verified against exactly the text that was prompted with — the
+ * concatenation, not a superset. (`fetch` is the one site that verifies against a
+ * superset; see `FocusedRequest.verifyAgainst`.)
+ */
+export async function docsLookup(input) {
+    const content = input.chunks.map(c => c.content).join('\n\n');
+    const extraction = await runFocusedExtraction({
+        prompt: input.corpus.buildPrompt(input.query, content),
+        verifyAgainst: content,
+        cwd: input.cwd,
+        signal: input.signal,
+        spawn: input.spawn,
+        thinking: input.thinking,
+        abortedMessage: input.corpus.abortedMessage
+    });
+    if (!extraction.ok)
+        return { kind: 'failed', extraction };
+    const excerptVerified = extraction.excerptVerified;
+    return {
+        kind: 'answer',
+        body: formatResultText(input.corpus.header, extraction, excerptVerified),
+        content,
+        extraction,
+        excerptVerified
+    };
+}

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

@@ -1,6 +1,7 @@
 import type { CacheHandle } from './docs-cache.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import type { RetrievedChunk } from './docs-retrieve.js';
+import type { DocsCorpus } from './docs-lookup.js';
 export declare function getProjectName(cwd: string): string;
 export declare function cwdKey(cwd: string): string;
 /**
@@ -50,3 +51,11 @@ export declare function projectDocsRaw(cache: CacheHandle, cwd: string, query: s
 /** How to enumerate the project's sources. See getProjectFiles. */
 listFiles?: (cwd: string) => string[]): ProjectDocsRawResult;
 export declare function buildProjectPrompt(projectName: string, query: string, content: string): string;
+/**
+ * The PROJECT corpus row: the current repo's own indexed `.ts`/`.tsx` source.
+ *
+ * Named after the project so a reader of the answer can tell a project-source
+ * citation from a package one at a glance — they are read and cited the same way
+ * and mean very different things.
+ */
+export declare function projectCorpus(projectName: string): DocsCorpus;

package/dist/workers/docs-project.js

@@ -208,3 +208,18 @@ export function buildProjectPrompt(projectName, query, content) {
         content
     });
 }
+/**
+ * The PROJECT corpus row: the current repo's own indexed `.ts`/`.tsx` source.
+ *
+ * Named after the project so a reader of the answer can tell a project-source
+ * citation from a package one at a glance — they are read and cited the same way
+ * and mean very different things.
+ */
+export function projectCorpus(projectName) {
+    return {
+        id: 'project',
+        buildPrompt: (query, content) => buildProjectPrompt(projectName, query, content),
+        header: `Per ${projectName} (project source):`,
+        abortedMessage: 'Project docs lookup aborted.'
+    };
+}

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

@@ -1,4 +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`
@@ -87,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.
+     * 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.
      */
-    commandTimeoutMs?: number;
+    profile: WorkerProfileId;
     /**
-     * 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.
+     * The facts the profile needs that are NOT policy: the gate's two watchdog
+     * ceilings (user config) and which research worker is docs-capable.
      */
-    loop?: {
-        window?: number;
-        threshold?: number;
-        pathThreshold?: number;
-    } | false;
+    policyInputs?: WorkerPolicyInputs;
     /**
-     * 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).
-     */
-    stallGuard?: {
-        limit?: number;
-        churnFactor?: number;
-    } | false;
-    /**
-     * 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
@@ -233,20 +159,12 @@ 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
  * a log line naming the reason points at exactly one piece of code.
  */
-export type WorkerRestartReason = 'loop' | 'command-timeout' | 'stream-stall' | 'worker-timeout' | 'connection-error' | 'leaked-tool-call';
+export type WorkerRestartReason = (typeof RESTART_ORDER)[number];
 /** One DISCARDED attempt: its cause and the wall clock it consumed and lost. */
 export interface WorkerRestart {
     /** 1-based number of the attempt being discarded (the 1st restart ends attempt 1). */
@@ -411,4 +329,89 @@ export interface RunWorkerResult {
  * itself, or a caller asking for 10s would silently get 30.
  */
 export declare function commandCeilingForAttempt(baseMs: number, priorHangs: number): number;
+/**
+ * Everything the restart ladder reads about one finished attempt, plus the
+ * budgets it draws on. Assembled once per attempt so the rules below can be
+ * module-level data instead of six `if` blocks welded into `runWorker`'s closure.
+ */
+interface RestartState {
+    loopHit?: LoopHit;
+    commandKill?: CommandKill;
+    streamStalled?: {
+        idleMs: number;
+    };
+    timedOut: boolean;
+    modelError?: string;
+    leaked: string | null;
+    /** The cap this attempt actually died against — the SCALE arm moves it. */
+    effectiveCapMs: number;
+    /** The child's tool string, which decides whether its edits can persist. */
+    tools: string;
+    restartBudgetSpent: number;
+    connRetries: number;
+    connectionRetries: number;
+    leakRetries: number;
+}
+/** What a rule does to the budgets when it fires. */
+interface RestartCounters {
+    /** Consume one of the shared loop/timeout/connection restarts. */
+    shared?: boolean;
+    /** Consume one of the leaked-tool-call retries (a separate budget). */
+    leak?: boolean;
+    /** Count a WATCHDOG kill specifically — drives the command-ceiling halving. */
+    hang?: boolean;
+    /** Count a CONNECTION restart specifically — drives the backoff schedule. */
+    connection?: boolean;
+}
+/**
+ * One restartable failure: how to spot it, what to tell the fresh child, which
+ * budget it spends, and how long to wait first.
+ */
+interface RestartRule {
+    reason: WorkerRestartReason;
+    /**
+     * Does this rule apply to the attempt, and is its budget unspent? Returns
+     * the restart's detail line, or null to fall through to the next rule.
+     *
+     * Detection and budget are ONE test on purpose. An out-of-budget failure must
+     * fall through to the return path, not stop the ladder — a loop kill with the
+     * shared budget spent still has to let the plain-abort return happen.
+     */
+    detect: (s: RestartState) => {
+        detail: string;
+    } | null;
+    /**
+     * The corrective preamble prepended to the next attempt's prompt. Omitted by
+     * `connection-error` alone: nothing the model did caused a dropped socket, so
+     * there is nothing to correct — and any hint already in flight from an
+     * earlier restart must survive the retry rather than be cleared by it.
+     */
+    hint?: (s: RestartState) => string;
+    counters: RestartCounters;
+    /** Backoff before re-spawning, in ms. Only the connection rule waits. */
+    backoffMs?: (s: RestartState) => number;
+}
+/**
+ * The restart ladder, in precedence order. FIRST MATCH WINS.
+ *
+ * Read the `!loopHit` guards as "a loop kill outranks me even when it has no
+ * budget left". They are not redundant with row order: when a loop is detected
+ * but the shared budget is spent, row 1 declines, and without those guards row 2
+ * or 4 would then restart the same runaway child under a hint that does not
+ * describe why it died.
+ *
+ * The whole ritual — check the budget, set the hint, spend the counters, record
+ * and announce the discarded attempt, sleep, re-spawn — belongs to the loop in
+ * `runWorker`, so a new failure mode is one row here and cannot be added without
+ * becoming visible in `restarts`.
+ */
+export declare const RESTART_RULES: readonly RestartRule[];
+/** What the command watchdog recorded when it killed an attempt. */
+interface CommandKill {
+    toolName: string;
+    timeoutMs: number;
+    /** The command line itself, when the tool carried one — quoted into the hint
+     *  so the fresh child knows which call it must not repeat unbounded. */
+    detail?: string;
+}
 export declare function runWorker(input: RunWorkerInput): Promise<RunWorkerResult>;

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

@@ -5,11 +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
@@ -34,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
@@ -89,12 +75,7 @@ const CARRY_FORWARD_LIMIT = 24_000;
  * first is by definition the same call repeated, the second is malformed
  * protocol text, and replaying either would feed the failure back to itself.
  */
-const CARRY_FORWARD_REASONS = new Set([
-    'worker-timeout',
-    'command-timeout',
-    'stream-stall',
-    'connection-error'
-]);
+const CARRY_FORWARD_REASONS = CARRY_FORWARD_IDS;
 /**
  * Does this partial output carry ANSWER CONTENT, or is it the model clearing its
  * throat?
@@ -276,7 +257,7 @@ export function commandCeilingForAttempt(baseMs, priorHangs) {
  * `runWorker`, so a new failure mode is one row here and cannot be added without
  * becoming visible in `restarts`.
  */
-const RESTART_RULES = [
+export const RESTART_RULES = [
     {
         // A loop-kill gets the same restart-with-hint treatment every other phase
         // already gets (runPhaseChild) — name the offending call so the
@@ -447,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
@@ -500,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.
@@ -526,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);
@@ -555,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++;
@@ -625,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.
@@ -656,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;