@mjasnikovs/pi-task 0.38.30 → 0.38.31

package/dist/task/implementation-turn.js

@@ -17,6 +17,7 @@
  */
 import { SessionUI } from '../remote/bridge.js';
 import { consumeWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js';
+import { consumeGuardTermination } from './implementation-guards.js';
 const isAssistant = (e) => e.message !== undefined && e.message.role === 'assistant';
 /** Index of the last assistant message and of the last compaction boundary. */
 function tailPositions(entries) {
@@ -160,6 +161,9 @@ export const CONTINUE_AFTER_COMPACTION = 'Your context was automatically compact
  * lets the verify gate and `/task-auto-resume` catch any leftover incompleteness.
  */
 export const MAX_COMPACTION_RESUMES = 20;
+/** How a guard-stopped turn is reported. Named so a caller can tell it from a
+ *  provider error: the fix is a different task, not a retry of this one. */
+export const GUARD_TERMINATED = 'the runaway guard stopped this turn: one tool call was repeated past every warning';
 /**
  * Resume an implementation turn that went idle at a threshold-compaction boundary.
  * The runtime compacts and parks at idle without auto-continuing; we send a
@@ -260,6 +264,13 @@ export async function superviseWith(deps) {
     const interrupted = await steerUntilDone(deps);
     // A user-declined steer (interrupted) is its own paused path; otherwise
     // inspect how the turn actually ended.
-    const error = interrupted ? undefined : turnErrorMessage(deps.entries());
+    // The runaway guard ends a turn WITHOUT an error stopReason, so classifyTurnEnd
+    // reads `'stop'` and the caller would verify a half-done implementation and
+    // re-deliver to a model that deterministically re-thrashes. Consumed here
+    // because this is the one place that reports how the turn really ended.
+    const guardEnded = deps.consumeGuardTermination?.() ?? consumeGuardTermination();
+    const error = interrupted ? undefined
+        : guardEnded ? GUARD_TERMINATED
+            : turnErrorMessage(deps.entries());
     return { interrupted, error, resumes };
 }

package/dist/task/loop-detector.d.ts

@@ -12,7 +12,19 @@
  *
  * Either pattern returns a LoopHit so the caller can kill the child and re-spawn
  * with a hint. No I/O. No imports from index.ts. Trivially unit-testable.
+ *
+ * The three tuning constants live here rather than in child-runner.ts because
+ * worker-profiles.ts reads them at module top level to build DEFAULT_LOOP_DETECTOR.
+ * From child-runner.ts that is a cycle — child-runner → worker-profiles →
+ * child-runner — and the failure is a TDZ ReferenceError on import order, which
+ * no compile step catches. This module imports nothing, so it cannot close one.
  */
+/** Recent tool calls the exact-repeat rule looks back over. */
+export declare const LOOP_WINDOW = 20;
+/** Repeats of one key within the window that trip the detector. */
+export declare const LOOP_THRESHOLD = 5;
+/** Re-spawns allowed after a loop kill — 3 attempts total with the initial one. */
+export declare const MAX_LOOP_RESTARTS = 2;
 export interface ToolCall {
     name: string;
     args: unknown;
@@ -27,6 +39,12 @@ export interface LoopHit {
  * Arrays preserve their order (positional). undefined / primitives passthrough.
  */
 export declare function stableStringify(value: unknown): string;
+/**
+ * The exact-match identity of a tool call. Exported because implementation-guards.ts
+ * keys its own per-call strike count on it, and a second hand-written copy of this
+ * expression is free to drift away from the one `record` uses.
+ */
+export declare function loopKey(call: ToolCall): string;
 /**
  * The primary file path a tool call targets, mirroring summarizeToolArgs' field
  * precedence. Returns null when the call names no path (e.g. bash, or a grep

package/dist/task/loop-detector.js

@@ -12,7 +12,19 @@
  *
  * Either pattern returns a LoopHit so the caller can kill the child and re-spawn
  * with a hint. No I/O. No imports from index.ts. Trivially unit-testable.
+ *
+ * The three tuning constants live here rather than in child-runner.ts because
+ * worker-profiles.ts reads them at module top level to build DEFAULT_LOOP_DETECTOR.
+ * From child-runner.ts that is a cycle — child-runner → worker-profiles →
+ * child-runner — and the failure is a TDZ ReferenceError on import order, which
+ * no compile step catches. This module imports nothing, so it cannot close one.
  */
+/** Recent tool calls the exact-repeat rule looks back over. */
+export const LOOP_WINDOW = 20;
+/** Repeats of one key within the window that trip the detector. */
+export const LOOP_THRESHOLD = 5;
+/** Re-spawns allowed after a loop kill — 3 attempts total with the initial one. */
+export const MAX_LOOP_RESTARTS = 2;
 /**
  * JSON.stringify with sorted object keys so {a:1,b:2} and {b:2,a:1} hash equal.
  * Arrays preserve their order (positional). undefined / primitives passthrough.
@@ -28,6 +40,14 @@ export function stableStringify(value) {
         return sorted;
     });
 }
+/**
+ * The exact-match identity of a tool call. Exported because implementation-guards.ts
+ * keys its own per-call strike count on it, and a second hand-written copy of this
+ * expression is free to drift away from the one `record` uses.
+ */
+export function loopKey(call) {
+    return `${call.name}\x00${stableStringify(call.args)}`;
+}
 /**
  * The primary file path a tool call targets, mirroring summarizeToolArgs' field
  * precedence. Returns null when the call names no path (e.g. bash, or a grep
@@ -78,7 +98,7 @@ export class LoopDetector {
     threshold;
     pathThreshold;
     buf = [];
-    constructor(window = 20, threshold = 5, 
+    constructor(window = LOOP_WINDOW, threshold = LOOP_THRESHOLD, 
     /** Revisits of one path needed to trip; defaults to the exact threshold. */
     pathThreshold = threshold) {
         this.window = window;
@@ -87,7 +107,7 @@ export class LoopDetector {
     }
     /** Record a tool call. Returns LoopHit if either threshold is breached, else null. */
     record(call) {
-        const key = `${call.name}\x00${stableStringify(call.args)}`;
+        const key = loopKey(call);
         const offset = readOffset(call.args);
         this.buf.push({ key, path: primaryPath(call.args), offset, end: readEnd(call.args, offset) });
         if (this.buf.length > this.window)

package/dist/task/orchestrator.js

@@ -26,6 +26,7 @@ import { readTextFile } from '../shared/fs-text.js';
 import { allocateTaskId, ensureTasksDir, readSection, readTaskFile, setTaskSection, taskFilePath, tasksDir, updateTaskFrontMatter, writeTaskFile } from './task-io.js';
 import { startWidget } from './widget.js';
 import { armImplWidget, disarmImplWidget, setupImplWidget } from './impl-widget.js';
+import { armImplementationGuard, disarmImplementationGuard } from './implementation-guards.js';
 import { publishViewer, publishNotify, registerBridgeCommand, getBridge } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { getConfig } from '../config/config.js';
@@ -364,12 +365,24 @@ export class TaskRunner {
         };
         if (this._sendSpec) {
             armImplWidget(meta, { oneShot: !this._implAwaited });
+            // Same lifetime as the widget, and for the same reason: an awaited run
+            // spans resume and steer turns, a fire-and-forget one does not.
+            armImplementationGuard({ oneShot: !this._implAwaited });
+            let delivered = false;
             try {
                 await this._sendSpec(spec);
+                delivered = true;
             }
             finally {
-                if (this._implAwaited)
+                // Arming precedes delivery because the turn can begin inside it. So a
+                // delivery that THREW leaves a guard watching a turn that will never
+                // run: pi's `prompt` rejects on a compaction already in progress, a
+                // missing model, or a failed auth. The next unrelated turn would
+                // inherit it, and this guard can end a turn outright.
+                if (this._implAwaited || !delivered) {
                     disarmImplWidget();
+                    disarmImplementationGuard();
+                }
             }
             return;
         }
@@ -377,12 +390,24 @@ export class TaskRunner {
             throw new Error('extension not initialised (no ExtensionAPI captured)');
         }
         armImplWidget(meta, { oneShot: true });
+        armImplementationGuard({ oneShot: true });
+        // Same reason as the awaited path's `delivered` flag: this send can throw
+        // SYNCHRONOUSLY — the loader gates every ExtensionAPI action behind
+        // `assertActive()` — and a guard left armed over a turn that never starts
+        // is inherited by the next one, which it can terminate.
         // Always name a delivery mode. pi's `prompt()` consults `streamingBehavior`
         // only inside `if (this.isStreaming)`, so naming one is inert on an idle
         // session and queues on a busy one — correct in both cases, where an
         // isIdle() check is a check-then-act race that loses to any turn starting
         // in between.
-        piApi.sendUserMessage(spec, { deliverAs: 'followUp' });
+        try {
+            piApi.sendUserMessage(spec, { deliverAs: 'followUp' });
+        }
+        catch (e) {
+            disarmImplWidget();
+            disarmImplementationGuard();
+            throw e;
+        }
     }
     /**
      * The spec as the implementer should receive it (Layer B). Layer A strips phantom

package/dist/task/phases.js

@@ -38,7 +38,7 @@ import { readContracts, buildContractsBlock, buildContractsVerifyBlock } from '.
 import { readRequirements, buildRequirementsBlock, buildOwnedRequirementsBlock, readOwnedRequirements, writeOwnedRequirements, ownedForTitle, appendOwnedConstraints } from './requirements.js';
 import { detachUnsatisfiableRequirements, claimPendingRequirements, unclaimedPendingRequirements, formatReassignActions } from './owned-freeze-reassign.js';
 import { trackedSourceOracle } from './owned-freeze-conflict.js';
-import { thinkingForChild, runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED } from './child-runner.js';
+import { thinkingForChild, runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED, CommandTimeoutError, isFatalChildCause } from './child-runner.js';
 import { runResearchWorker, researchWorkerCacheHeading } from './research-worker.js';
 import { SessionUI } from '../remote/bridge.js';
 import { isYoloMode, yoloPickAutoAnswer } from './yolo.js';
@@ -301,7 +301,16 @@ export async function phaseVerifyTooling(deps, research) {
     try {
         verifyOutput = await runPhaseChild(deps, 'verify-tooling', 'read,bash', VERIFY_TOOLING_PROMPT(toolingList));
     }
-    catch {
+    catch (e) {
+        if (isFatalChildCause(e))
+            throw e;
+        // The fallback ships the tooling list UNVERIFIED, which is the right
+        // degrade for a child that merely failed. A hung command is different: it
+        // cost the ceiling on every strike and says the SPEC named something
+        // unbounded, so it is the one cause worth a trail line rather than silence.
+        if (e instanceof CommandTimeoutError) {
+            deps.logDebug?.(`verify-tooling: ${e.message} — shipping the list unverified`);
+        }
         return replaceToolingWithVerified(research, commands);
     }
     const parsed = parseVerifyToolingOutput(verifyOutput);
@@ -761,7 +770,9 @@ export async function phaseAutoAnswer(deps, refined, research, question) {
                     if (autoAnswerHasTag(text2))
                         reasked = parseAutoAnswer(text2);
                 }
-                catch {
+                catch (e) {
+                    if (isFatalChildCause(e))
+                        throw e;
                     reasked = null;
                 }
                 if (reasked === null
@@ -1024,7 +1035,9 @@ extraDefects) {
             // needs no file access.
             verdict = await runPhaseChild(deps, 'critique-triage', '', CRITIQUE_TRIAGE_PROMPT(spec, refined, qa, contractsBlock));
         }
-        catch {
+        catch (e) {
+            if (isFatalChildCause(e))
+                throw e;
             verdict = null;
         }
         deps.recordSubStep?.('triage', Date.now() - tTriage);

package/dist/workers/focused-extractor.d.ts

@@ -78,7 +78,8 @@ export type FocusedResult = FocusedFailure | FocusedAnswer;
  * `<answer>`/`<excerpt>` and verify the excerpt against `verifyAgainst`.
  *
  * Never retries — a re-ask of a deterministic extraction over unchanged content is a second
- * bill for the same answer. Exactly one child is spawned per call.
+ * bill for the same answer. Exactly one child is spawned per call, on every path including
+ * the empty-output failure below.
  */
 export declare function runFocusedExtraction(req: FocusedRequest): Promise<FocusedResult>;
 export {};

package/dist/workers/focused-extractor.js

@@ -44,7 +44,8 @@ export const focusedChildArgs = (thinking = []) => [
  * `<answer>`/`<excerpt>` and verify the excerpt against `verifyAgainst`.
  *
  * Never retries — a re-ask of a deterministic extraction over unchanged content is a second
- * bill for the same answer. Exactly one child is spawned per call.
+ * bill for the same answer. Exactly one child is spawned per call, on every path including
+ * the empty-output failure below.
  */
 export async function runFocusedExtraction(req) {
     const spawn = req.spawn ?? defaultSpawn;
@@ -59,6 +60,16 @@ export async function runFocusedExtraction(req) {
     const failure = formatChildFailure(child, req.abortedMessage);
     if (failure !== null)
         return { ok: false, failure, ...evidence };
+    // A dropped provider exits 0 with empty text, and TEXT mode never populates
+    // `modelError`. Returned as an empty answer it is MEMOISED: both caches keep
+    // it and re-serve a dead socket as a real answer for the rest of the run.
+    if (child.stdout.trim().length === 0) {
+        return {
+            ok: false,
+            failure: 'Worker exited 0 without writing anything — no answer to parse',
+            ...evidence
+        };
+    }
     const parsed = parseChildOutput(child.stdout);
     const excerptCheck = parsed.excerpt ? verifyExcerpt(parsed.excerpt, req.verifyAgainst) : undefined;
     return {

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 { type CommandKill } from '../shared/command-watchdog.js';
+export { commandCeilingForAttempt } from '../shared/command-watchdog.js';
 import { RESTART_ORDER } from './worker-kill.js';
 import { type WorkerGuardOverride, type WorkerGuardPolicy, type WorkerPolicyInputs, type WorkerProfileId } from './worker-profiles.js';
 /**
@@ -337,29 +339,6 @@ export interface RunWorkerResult {
         idleMs: number;
     };
 }
-/**
- * The per-command ceiling for attempt N, halving each time a hang recurs.
- *
- * The first attempt gets the full configured ceiling — a genuinely slow build or
- * test suite deserves it. But every hang-caused restart carries
- * commandTimeoutHint, which tells the model in as many words to bound its
- * command; a SECOND hang means it ignored an explicit instruction, and a third
- * means it ignored it twice. Giving a non-complying child the full ceiling again
- * makes the worst case three times the ceiling, resting entirely on the model
- * obeying prose. Halving bounds it at under twice the ceiling while costing a
- * complying child nothing.
- *
- * `priorHangs` counts watchdog kills specifically, NOT total restarts — the
- * restart budget is shared with loop kills, and a child restarted for LOOPING
- * never received the bound-your-command hint, so its first hang still deserves
- * the full ceiling. Only a hang after a hang is defiance.
- *
- * Floored at 30s so repeated halving cannot shrink the ceiling to something no
- * real command could finish inside — but the floor is `min(base, 30s)`, never
- * above the configured ceiling, so a caller asking for 10s keeps 10s at every
- * hang count. A base of 0 or less disables the watchdog and stays 0.
- */
-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
@@ -438,12 +417,4 @@ interface RestartRule {
  * 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

@@ -1,11 +1,12 @@
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { runChildDefault } from '../shared/child-process.js';
-import { CommandWatchdog, commandTimeoutHint, realTimerDeps } from '../shared/command-watchdog.js';
+import { commandCeilingForAttempt, commandTimeoutHint, commandWatch } from '../shared/command-watchdog.js';
+export { commandCeilingForAttempt } from '../shared/command-watchdog.js';
 import { isGroundingRetrieval as isGrounding, workerChannel } from './worker-channels.js';
 import { childBaseArgs } from '../shared/child-extensions.js';
-import { LoopDetector } from '../task/loop-detector.js';
+import { LoopDetector, MAX_LOOP_RESTARTS } from '../task/loop-detector.js';
 import { StallDetector, formatStallHint } from '../task/stall-detector.js';
-import { MAX_LOOP_RESTARTS, formatLoopHint, isConnectionError, connectionRetryBackoffMs } from '../task/child-runner.js';
+import { 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';
@@ -216,34 +217,6 @@ absoluteCeilingMs) {
         }
     };
 }
-/**
- * The per-command ceiling for attempt N, halving each time a hang recurs.
- *
- * The first attempt gets the full configured ceiling — a genuinely slow build or
- * test suite deserves it. But every hang-caused restart carries
- * commandTimeoutHint, which tells the model in as many words to bound its
- * command; a SECOND hang means it ignored an explicit instruction, and a third
- * means it ignored it twice. Giving a non-complying child the full ceiling again
- * makes the worst case three times the ceiling, resting entirely on the model
- * obeying prose. Halving bounds it at under twice the ceiling while costing a
- * complying child nothing.
- *
- * `priorHangs` counts watchdog kills specifically, NOT total restarts — the
- * restart budget is shared with loop kills, and a child restarted for LOOPING
- * never received the bound-your-command hint, so its first hang still deserves
- * the full ceiling. Only a hang after a hang is defiance.
- *
- * Floored at 30s so repeated halving cannot shrink the ceiling to something no
- * real command could finish inside — but the floor is `min(base, 30s)`, never
- * above the configured ceiling, so a caller asking for 10s keeps 10s at every
- * hang count. A base of 0 or less disables the watchdog and stays 0.
- */
-export function commandCeilingForAttempt(baseMs, priorHangs) {
-    if (!(baseMs > 0))
-        return 0;
-    const floor = Math.min(baseMs, 30_000);
-    return Math.max(floor, Math.round(baseMs / 2 ** priorHangs));
-}
 /**
  * The restart ladder, in precedence order. FIRST MATCH WINS.
  *
@@ -360,58 +333,6 @@ export const RESTART_RULES = [
         counters: { leak: true }
     }
 ];
-/**
- * Build the child-side command watchdog for ONE attempt: a per-tool-call timer
- * machine (shared with the main session) whose `onFire` aborts `signal`, which
- * runChild turns into a process-GROUP kill — reaping the hung command itself,
- * not just the pi child holding it.
- *
- * LIMIT: the group kill only reaches processes still IN the group. A hung command
- * that detached a daemon (setsid, nohup, a background dev server) leaves it
- * running, so the fresh attempt can hit a port the dead attempt's escapee still
- * holds. There is no cheap fix from here; the restart hint's "check current state"
- * line is the mitigation.
- *
- * Returns null when the watchdog is off, so the caller keeps the plain timeout
- * signal and no per-call bookkeeping happens at all.
- */
-function commandWatch(timeoutMs) {
-    if (!(timeoutMs > 0))
-        return null;
-    const ctrl = new AbortController();
-    // pi's toolCallId pairs start↔end. When it is absent (a fake stream in a
-    // test, an older pi), fall back to one shared slot: tool executions in a
-    // child are sequential, so a single slot is still correctly paired.
-    const key = (id) => id ?? 'anon';
-    const details = new Map();
-    let killed;
-    const watchdog = new CommandWatchdog({
-        getTimeoutMs: () => timeoutMs,
-        ...realTimerDeps,
-        onFire: (toolCallId, toolName, ms) => {
-            killed = {
-                toolName,
-                timeoutMs: ms,
-                ...(details.has(toolCallId) ? { detail: details.get(toolCallId) } : {})
-            };
-            ctrl.abort();
-        }
-    });
-    return {
-        onStart: call => {
-            const id = key(call.toolCallId);
-            const args = call.args;
-            if (typeof args?.command === 'string') {
-                details.set(id, args.command.slice(0, 120));
-            }
-            watchdog.onStart(id, call.name);
-        },
-        onEnd: id => watchdog.onEnd(key(id)),
-        killed: () => killed,
-        signal: ctrl.signal,
-        clear: () => watchdog.clearAll()
-    };
-}
 export async function runWorker(input) {
     const tools = input.tools ?? DEFAULT_TOOLS;
     // `--mode json` makes pi emit structured events as they happen instead of

package/dist/workers/single-read-guard.d.ts

@@ -21,10 +21,10 @@
  *
  *   - RepeatedCallGuard: "no identical search twice", for grep/find/ls — the
  *     shapes the read guard cannot see, such as the same grep pattern re-run
- *     against the same path. Keyed on `${toolName}\0${stableStringify(args)}`,
- *     byte-identical to the key `LoopDetector.record` builds, so argument key
- *     order never causes a miss and only an identical repeat trips. A different
- *     pattern on the same file still passes.
+ *     against the same path. Keyed with `loopKey`, the same identity
+ *     `LoopDetector.record` uses, so argument key order never causes a miss and
+ *     only an identical repeat trips. A different pattern on the same file still
+ *     passes.
  *
  * Pure logic, no I/O — the extension does path resolution and tool routing.
  */
@@ -62,8 +62,8 @@ export declare class RepeatedCallGuard {
     /**
      * Record a `toolName` call with `args`. Returns a ReadBlock the second time
      * the same (toolName, stable-stringified args) pair is seen (and every time
-     * after), else null on the first. Uses the LoopDetector's stableStringify so
-     * argument key-order never causes a miss; only byte-identical calls collapse.
+     * after), else null on the first. Shares the LoopDetector's key, so argument
+     * key-order never causes a miss; only byte-identical calls collapse.
      */
     check(toolName: string, args: unknown): ReadBlock | null;
 }

package/dist/workers/single-read-guard.js

@@ -21,14 +21,14 @@
  *
  *   - RepeatedCallGuard: "no identical search twice", for grep/find/ls — the
  *     shapes the read guard cannot see, such as the same grep pattern re-run
- *     against the same path. Keyed on `${toolName}\0${stableStringify(args)}`,
- *     byte-identical to the key `LoopDetector.record` builds, so argument key
- *     order never causes a miss and only an identical repeat trips. A different
- *     pattern on the same file still passes.
+ *     against the same path. Keyed with `loopKey`, the same identity
+ *     `LoopDetector.record` uses, so argument key order never causes a miss and
+ *     only an identical repeat trips. A different pattern on the same file still
+ *     passes.
  *
  * Pure logic, no I/O — the extension does path resolution and tool routing.
  */
-import { stableStringify } from '../task/loop-detector.js';
+import { loopKey } from '../task/loop-detector.js';
 /**
  * The error text the model receives in place of the re-read's contents.
  *
@@ -105,11 +105,11 @@ export class RepeatedCallGuard {
     /**
      * Record a `toolName` call with `args`. Returns a ReadBlock the second time
      * the same (toolName, stable-stringified args) pair is seen (and every time
-     * after), else null on the first. Uses the LoopDetector's stableStringify so
-     * argument key-order never causes a miss; only byte-identical calls collapse.
+     * after), else null on the first. Shares the LoopDetector's key, so argument
+     * key-order never causes a miss; only byte-identical calls collapse.
      */
     check(toolName, args) {
-        const key = `${toolName}\x00${stableStringify(args)}`;
+        const key = loopKey({ name: toolName, args });
         if (this.seen.has(key)) {
             return { block: true, reason: repeatedCallReason(toolName) };
         }

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

@@ -242,15 +242,15 @@ export declare const DEFAULT_LOOP_PROGRESS: {
     readonly limit: 8;
     readonly churnFactor: 2;
 };
-export type WorkerProfileId = 'research' | 'gate' | 'adhoc';
+export type WorkerProfileId = 'research' | 'gate' | 'adhoc' | 'phase';
 /**
  * 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`. */
+    /** gate, phase: `config.requestTimeoutMs`. */
     commandTimeoutMs?: number;
-    /** gate: `config.streamInactivityMs`. */
+    /** gate, phase: `config.streamInactivityMs`. */
     streamInactivityMs?: number;
     /** research: only `worker:apis` fans out, so only it can be scaled. */
     fanoutBounded?: boolean;
@@ -289,6 +289,14 @@ export declare const WORKER_PROFILES: {
             carryForward: false;
         };
     };
+    readonly phase: {
+        readonly id: "phase";
+        readonly why: string;
+        readonly resolve: (inputs: WorkerPolicyInputs) => {
+            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;

package/dist/workers/worker-profiles.js

@@ -50,7 +50,10 @@
  *   `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';
+// From loop-detector.ts, NOT child-runner.ts: child-runner reads this table, and
+// these are evaluated at module top level below, so that import would close a
+// cycle whose only symptom is a TDZ ReferenceError on import order.
+import { LOOP_THRESHOLD, LOOP_WINDOW, MAX_LOOP_RESTARTS } from '../task/loop-detector.js';
 import { CONTEXT_CHURN_FACTOR, NO_PROGRESS_LIMIT } from '../task/stall-detector.js';
 import { fanoutTimeoutPolicy, workerCarryForward, workerProgressCeilingMs } from '../task/research-fanout-budget.js';
 /**
@@ -198,6 +201,35 @@ export const WORKER_PROFILES = {
             guards['stream-stall'] = inputs.streamInactivityMs ?? 0;
             return { guards, carryForward: false };
         }
+    },
+    phase: {
+        id: 'phase',
+        why: 'The spec-pipeline and planning children (runPhaseChild). Every call site '
+            + "but one passes `read` or `''`, and none of them EDITS, so the "
+            + 'path-revisit rule stays ON, unlike gate: re-reading one file here is '
+            + 'the thrash it was written for, not the job. '
+            + 'THE COMMAND WATCHDOG IS WHY THIS ROW EXISTS. verify-tooling holds '
+            + '`read,bash`, and a hung command there was unkillable: the stream '
+            + 'watchdog SUSPENDS for the duration of a tool call, the dead-backend '
+            + 'probe reads a reachable endpoint as alive, and both runaway detectors '
+            + 'wait on a result that never arrives. Only a user ESC could end it. '
+            + 'The wall clock stays OFF as PHASE_CHILD_TIMEOUT_MS decided for a FIXED '
+            + "cap; that does not settle research's progress-based ceiling. "
+            + 'PARTIALLY CONSUMED: runPhaseChild has its own strike loop and reads '
+            + 'only `command-timeout`, `stream-stall`, `stalled` and `loop`, so '
+            + 'setting `worker-timeout` or `connection-error` here does NOTHING.',
+        resolve: inputs => {
+            const guards = baseGuards();
+            // INERT for this profile — runPhaseChild never reads it. Zeroed anyway
+            // so the row cannot be mistaken for research's armed 240s cap.
+            guards['worker-timeout'] = { timeoutMs: 0, progressCeilingMs: null, fanout: null };
+            // Both ceilings are the user's own settings, as they are for gate: the
+            // number is theirs, the decision to arm it is this row's. 0 from a
+            // caller that hands none, so a harness cannot silently acquire a guard.
+            guards['command-timeout'] = inputs.commandTimeoutMs ?? 0;
+            guards['stream-stall'] = inputs.streamInactivityMs ?? 0;
+            return { guards, 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.

package/package.json

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