@mjasnikovs/pi-task 0.38.30 → 0.38.31

package/dist/task/child-runner.js

@@ -9,21 +9,20 @@ import { spawn } from 'node:child_process';
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { runChild as runChildUnified } from '../shared/child-process.js';
 import { childBaseArgs } from '../shared/child-extensions.js';
-import { LoopDetector } from './loop-detector.js';
+import { LoopDetector, MAX_LOOP_RESTARTS } from './loop-detector.js';
 import { StallDetector, formatStallHint } from './stall-detector.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 import { readSection, setTaskSection } from './task-io.js';
 import { streamStallCause } from '../shared/stream-watchdog.js';
+import { commandCeilingForAttempt, commandTimeoutHint, commandWatch } from '../shared/command-watchdog.js';
+import { discoverModelEndpoints, probeModelEndpoints } from '../shared/model-endpoint.js';
+// VALUE import, and it is only safe because worker-profiles.ts reads its loop
+// constants from loop-detector.ts. Point those back at this file and the graph
+// closes into a TDZ ReferenceError that no compile step catches.
+import { workerPolicy } from '../workers/worker-profiles.js';
 import { getConfig } from '../config/config.js';
 import { groupThinkingArgs } from '../config/reasoning-args.js';
 import { reasoningGroupForChild } from '../config/reasoning.js';
-// ─── Loop detection constants ────────────────────────────────────────────────
-// Defined here (not in phases.ts) to avoid a circular dependency:
-//   phases.ts → child-runner.ts → phases.ts
-export const LOOP_WINDOW = 20;
-export const LOOP_THRESHOLD = 5;
-export const MAX_LOOP_RESTARTS = 2; // 3 strikes total (initial attempt + 2 restarts)
-// MAX_LEAK_RETRIES lives in shared/leaked-tool-call.ts (imported above).
 // ─── Phase-child wall-clock cap ──────────────────────────────────────────────
 /**
  * Optional wall-clock bound on ONE spawn of a phase child. DEFAULT: OFF.
@@ -105,6 +104,75 @@ export class PhaseTimeoutError extends Error {
         this.name = 'PhaseTimeoutError';
     }
 }
+/**
+ * The terminal error for a guard kill, or null when the child was not killed.
+ *
+ * Both spawn paths must ask. A kill reports `exitCode: 0` (child-process.ts uses
+ * `code ?? 0`, and a signal gives null), so a path that tests the exit code
+ * instead returns the truncated text as the phase's answer.
+ */
+export function guardKillError(name, r, opts = {}) {
+    if (r.commandKill)
+        return new CommandTimeoutError(name, r.commandKill);
+    // A dead-backend verdict is only trusted once every attempt has produced it.
+    // `discoverModelEndpoints` reads EVERY provider in models.json, not the one
+    // this child's model uses, so a stopped local server can condemn a run against
+    // a healthy cloud backend. The asymmetry settles it: a backend that really is
+    // down costs three 5s probes, a wrong verdict costs the whole run.
+    if (r.stalled)
+        return opts.finalAttempt === false ? null : new BackendDownError(name);
+    return null;
+}
+/**
+ * The dead-backend probe killed a phase child on its LAST attempt.
+ *
+ * Reaching this means every attempt found no endpoint answering, not one. The
+ * single-probe verdict is not trusted on its own: `discoverModelEndpoints` reads
+ * every provider in models.json rather than the one this child's model uses, so a
+ * stopped local server can condemn a run against a healthy cloud backend. Three
+ * failed probes cost ~15s; one wrong verdict costs the run.
+ */
+export class BackendDownError extends Error {
+    childName;
+    constructor(childName) {
+        super(`${childName} child killed: no output for the stall window and the model `
+            + `endpoint did not answer a probe`);
+        this.childName = childName;
+        this.name = 'BackendDownError';
+    }
+}
+/**
+ * A phase child spent every attempt on a command that never returned. Its own
+ * class because the fix is in the SPEC, not the model's exploration: a VERIFY
+ * block naming an unbounded `dev` command re-hangs every attempt.
+ */
+export class CommandTimeoutError extends Error {
+    childName;
+    kill;
+    constructor(childName, kill) {
+        super(`${childName} child ran \`${kill.toolName}\``
+            + `${kill.detail ? ` (${kill.detail})` : ''} past its `
+            + `${Math.round(kill.timeoutMs / 1000)}s ceiling on every attempt`);
+        this.childName = childName;
+        this.kill = kill;
+        this.name = 'CommandTimeoutError';
+    }
+}
+/**
+ * Causes a best-effort `catch` must NOT absorb.
+ *
+ * A phase child that merely answered badly should degrade — that is what those
+ * catches are for. These two are different in kind: the run is over either way,
+ * and swallowing them ships a half-built spec while every later phase dies
+ * against the same dead backend, or turns a user's ESC into silent progress.
+ * `failure-classifier.ts` has a verdict for both; a catch that eats them makes it
+ * unreachable.
+ */
+export function isFatalChildCause(e) {
+    if (e instanceof BackendDownError)
+        return true;
+    return e instanceof Error && e.message === USER_CANCELLED;
+}
 // ─── Connection-error retry ──────────────────────────────────────────────────
 /**
  * A connection-class model error is transient: a single dropped fetch to a live
@@ -120,9 +188,54 @@ export class PhaseTimeoutError extends Error {
  * provider 5xx that names a real fault) still fails fast: re-spawning against
  * the same request won't fix it, so burning the budget only delays the report.
  */
-const CONNECTION_ERROR_RE = /\b(?:connection error|connection (?:lost|closed|reset|refused|aborted)|econnreset|econnrefused|econnaborted|epipe|etimedout|enetunreach|enetdown|eai_again|socket hang up|fetch failed|network (?:error|timeout)|premature close|request timed out|terminated|unreachable)\b/i;
+/**
+ * Transport-level failures worth another attempt.
+ *
+ * SCOPE, and it is deliberate: connection classes only. pi's own
+ * `isRetryableAssistantError` (@earendil-works/pi-ai, `dist/utils/retry.js`) also
+ * retries the provider-LOAD family — `429`, `5xx`, `rate limit`, `overloaded` —
+ * which `does NOT match real, non-transient faults` in child-runner.test.ts
+ * explicitly rejects. That disagreement is real and OPEN; it is not settled here,
+ * because this backoff starts at 500ms and a 429 answered that fast is a retry
+ * storm, not a recovery.
+ *
+ * MEASURED against pi before widening: the transport entries added here — a bare
+ * `timed out`, `getaddrinfo ENOTFOUND`, `upstream connect`, `reset before
+ * headers`, a truncated Anthropic stream and a closed websocket — were all
+ * MISSES. Every one is a REMOTE-provider failure, which is why a local llama.cpp
+ * setup never surfaced the gap. The errno spellings are pi-task's own: a child
+ * reports them through stderr, and pi never sees them.
+ *
+ * pi's bare `timeout` is deliberately NOT reproduced. It matched a provider 400
+ * that merely echoed a `timeout` field back, turning a fail-fast into a full
+ * retry budget, and it caught nothing the `timed out` spellings above miss.
+ */
+const CONNECTION_ERROR_RE = /\b(?:connection error|connection (?:lost|closed|reset|refused|aborted)|econnreset|econnrefused|econnaborted|epipe|etimedout|enetunreach|enetdown|eai_again|socket hang up|socket connection was closed|fetch failed|network (?:error|timeout)|premature close|terminated|unreachable|getaddrinfo|enotfound|upstream.?connect|reset before headers|timed? out|ended without|stream ended before message_stop|websocket.?(?:closed|error))\b/i;
+/**
+ * Provider LOAD, which is transient in a different way: the server is up and
+ * saying "not now". pi retries all of these; 53f0488 did not, but its own message
+ * names only "context overflow, bad request, auth" as the fail-fast set — a
+ * throttle was never argued for, it just rode along in a list written for a LOCAL
+ * server, where none of these can occur.
+ *
+ * Words carry no trailing \b (`overloaded_error` joins on `_`, which is a word
+ * character); the bare status codes carry one, or `500` matches inside `15000`.
+ */
+const PROVIDER_LOAD_RE = /(?:overloaded|rate.?limit|too many requests|service.?unavailable|server.?error|internal.?error|provider.?returned.?error)|\b(?:429|500|502|503|504|524)\b/i;
+/**
+ * Account facts, not liveness: a budget does not refill on a retry. Checked FIRST,
+ * because these arrive worded as a throttle — `429 GoUsageLimitError` is a
+ * subscription limit, not a queue.
+ */
+const NON_RETRYABLE_RE = /\b(?:insufficient_quota|quota exceeded|out of budget|billing|usage limit reached|available balance|GoUsageLimitError|FreeUsageLimitError)\b/i;
+/**
+ * Retry budget is three attempts at 500ms/1s/2s — three requests over 3.5s, which
+ * is not a storm even against a throttle. pi's own ladder is three at 2s/4s/8s.
+ */
 export function isConnectionError(cause) {
-    return CONNECTION_ERROR_RE.test(cause);
+    if (NON_RETRYABLE_RE.test(cause))
+        return false;
+    return CONNECTION_ERROR_RE.test(cause) || PROVIDER_LOAD_RE.test(cause);
 }
 /** Exponential backoff before a connection-error retry: 500ms, 1s, 2s, …, so a
  *  brief saturation window can drain before we re-issue the request. */
@@ -165,30 +278,75 @@ thinking = []) {
 // Sentinel error thrown when the user dismisses a grill-me dialog.
 // Defined here (not in failure-classifier.ts) to avoid circular dependency.
 export const USER_CANCELLED = '__user_cancelled__';
-export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking }) {
+/**
+ * The `phase` row of WORKER_PROFILES, resolved with this machine's config.
+ *
+ * Read here rather than at module load so a /task-config change reaches the next
+ * child, the same contract childBaseArgs already keeps. Both spawn paths in this
+ * file go through it, so the degraded final attempt cannot drift from the ordinary
+ * one — the mislabel class runDegradedFinalAttempt's own comment warns about.
+ */
+export function phasePolicy() {
+    return workerPolicy('phase', {
+        commandTimeoutMs: getConfig().requestTimeoutMs,
+        streamInactivityMs: getConfig().streamInactivityMs
+    });
+}
+export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking, commandCeilingMs }) {
     const invocation = getPiInvocation(childArgs(tools, extensions, thinking), prompt);
     let loopHit;
-    const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
-        mode: 'json-events',
-        // A hung model stream reports nothing at all, so without this the
-        // phase child waits forever. The kill
-        // is reported below as a connection-class cause, which routes it into
-        // the retry/backoff path this file already has for a LOUD disconnect.
-        streamInactivityMs: getConfig().streamInactivityMs,
-        onLine,
-        onContextUsage,
-        ...(contextWindow && contextWindow > 0 ? { contextWindow } : {}),
-        onToolResult: onToolResult ? r => onToolResult(r.text, r.isError) : undefined,
-        onToolCall: call => {
-            if (!onToolCall)
-                return null;
-            const hit = onToolCall(call);
-            if (hit && !loopHit) {
-                loopHit = hit;
+    const guards = phasePolicy().guards;
+    // Null when the user set the ceiling to `off`. Why a phase child needs this at
+    // all is the `phase` row's `why` in worker-profiles.ts.
+    const cmdWatch = commandWatch(commandCeilingMs ?? guards['command-timeout']);
+    const childSignal = cmdWatch ? AbortSignal.any([signal, cmdWatch.signal]) : signal;
+    let result;
+    try {
+        result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, childSignal, {
+            mode: 'json-events',
+            // A hung model stream reports nothing at all, so without this the
+            // phase child waits forever. The kill
+            // is reported below as a connection-class cause, which routes it into
+            // the retry/backoff path this file already has for a LOUD disconnect.
+            streamInactivityMs: guards['stream-stall'],
+            ...(guards.stalled === false ?
+                {}
+                : {
+                    stall: {
+                        afterMs: guards.stalled.afterMs,
+                        probe: guards.stalled.probe
+                            ?? (() => probeModelEndpoints(discoverModelEndpoints()))
+                    }
+                }),
+            onLine,
+            onContextUsage,
+            ...(contextWindow && contextWindow > 0 ? { contextWindow } : {}),
+            // ALWAYS wired, never conditional on the caller wanting results:
+            // the sink emits a tool-execution-end only when a handler exists,
+            // and without that end the command watchdog's timer is never
+            // disarmed — every healthy tool call would then look hung.
+            onToolResult: r => {
+                cmdWatch?.onEnd(r.toolCallId);
+                onToolResult?.(r.text, r.isError);
+            },
+            onToolCall: call => {
+                // Before the detectors: a call they let through still needs its
+                // clock started.
+                cmdWatch?.onStart(call);
+                if (!onToolCall)
+                    return null;
+                const hit = onToolCall(call);
+                if (hit && !loopHit) {
+                    loopHit = hit;
+                }
+                return hit; // propagate to unified runner so it can kill
             }
-            return hit; // propagate to unified runner so it can kill
-        }
-    });
+        });
+    }
+    finally {
+        cmdWatch?.clear();
+    }
+    const commandKill = cmdWatch?.killed();
     // Use `||` (not `??`) so an empty string from json-events mode falls
     // back to raw stdout. Without this, a child that exits 0 but emits no
     // assistant text (e.g. model API error swallowed in json mode) always
@@ -202,14 +360,16 @@ export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUs
         ?? (result.streamStalled ? streamStallCause(result.streamStalled.idleMs) : undefined);
     return {
         text,
-        // WE killed this child, so its exit status describes our own SIGTERM, not
-        // the child's verdict. Report 0 and let `modelError` carry the cause —
-        // otherwise the wrappers' `exitCode !== 0` guard throws a bare "child
-        // failed" before the connection-error retry ever gets to look.
-        exitCode: result.streamStalled ? 0 : result.exitCode,
+        // WE killed this child, so its exit status is our own SIGTERM. Report 0
+        // and let the named cause carry it. EVERY guard kill must be listed: one
+        // omitted here arrives as exit 0 with partial text, and triageChildResult
+        // returns it as a successful answer.
+        exitCode: result.streamStalled || result.stalled || commandKill ? 0 : result.exitCode,
         stderr: result.stderr.trim(),
         loopHit,
         modelError,
+        ...(commandKill ? { commandKill } : {}),
+        ...(result.stalled ? { stalled: true } : {}),
         // A tool call the model wrote as text (wrong dialect) never executed and
         // sailed past the structured-event guards above; flag it so the wrappers
         // can re-prompt instead of accepting the unexecuted call. Only meaningful
@@ -346,17 +506,29 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
     let hint = null;
     const loopHistory = [];
     const budgetMs = deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS;
+    // From the `phase` row, not from literals here, so the table is the one place
+    // that answers "how may this child die". The row resolves to the same
+    // DEFAULT_LOOP_DETECTOR / DEFAULT_LOOP_PROGRESS this file used to hard-code.
+    const loopGuard = phasePolicy().guards.loop;
+    // Watchdog kills, NOT total strikes: a loop restart never saw the
+    // bound-your-command hint. Without the halving, three attempts at the default
+    // ceiling cost 45 minutes and nothing else bounds this path.
+    let hangKills = 0;
     for (let attempt = 0; attempt <= MAX_LEAK_RETRIES; attempt++) {
         // A cancel between attempts must not buy another spawn.
         if (deps.signal.aborted)
             throw new Error(USER_CANCELLED);
-        const detector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
-        const stall = new StallDetector();
+        const detector = loopGuard.detector === false ?
+            null
+            : new LoopDetector(loopGuard.detector.window, loopGuard.detector.threshold, loopGuard.detector.pathThreshold);
+        const stall = loopGuard.progress === false ?
+            null
+            : new StallDetector(loopGuard.progress.limit, loopGuard.progress.churnFactor);
         // Arm the churn rule BEFORE the first tool call. pi's stream carries no
         // context WINDOW, so a detector that waited to be told one would sit at 0,
         // and the churn rule returns false on a non-positive window. The parent
         // knows the value at spawn time — say it then, not later.
-        stall.noteContext(deps.contextWindow ?? 0);
+        stall?.noteContext(deps.contextWindow ?? 0);
         const clock = phaseTimeout(deps.signal, budgetMs);
         let r;
         try {
@@ -370,11 +542,12 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
                     // why the parent's value must be supplied at spawn — a
                     // stream that only ever reports 0 leaves the churn rule
                     // permanently disarmed.
-                    stall.noteContext(snapshot.contextWindow);
+                    stall?.noteContext(snapshot.contextWindow);
                     deps.onContextUsage?.(snapshot);
                 },
-                onToolCall: call => detector.record(call) ?? stall.record(call),
-                onToolResult: (text, isError) => stall.noteResult(text, isError)
+                commandCeilingMs: commandCeilingForAttempt(phasePolicy().guards['command-timeout'], hangKills),
+                onToolCall: call => detector?.record(call) ?? stall?.record(call) ?? null,
+                onToolResult: (text, isError) => stall?.noteResult(text, isError)
             }));
         }
         finally {
@@ -404,6 +577,36 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
             hint = r.loopHit.stall ? formatStallHint(r.loopHit.stall) : formatLoopHint(r.loopHit);
             continue;
         }
+        // Ordered after the loop rule and before the clock, matching RESTART_ORDER
+        // (worker-kill.ts): the loop hint names the offending call and is the more
+        // specific thing to tell a re-spawn, and a watchdog kill leaves the phase
+        // clock's own flag false, so the two cannot be confused.
+        if (r.commandKill) {
+            hangKills++;
+            if (attempt === MAX_LEAK_RETRIES) {
+                throw new CommandTimeoutError(name, r.commandKill);
+            }
+            deps.logDebug?.(`${name}: ${r.commandKill.toolName} outran `
+                + `${Math.round(r.commandKill.timeoutMs / 1000)}s — `
+                + `${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`);
+            // Tracks the TOOLS, not the phase: verify-tooling holds `read,bash`,
+            // and a half-written node_modules survives the kill.
+            hint = commandTimeoutHint(r.commandKill.toolName, r.commandKill.timeoutMs, {
+                ...(r.commandKill.detail ? { commandDetail: r.commandKill.detail } : {}),
+                editsMayPersist: /\b(?:bash|edit|write)\b/.test(tools)
+            });
+            continue;
+        }
+        // A dead-backend kill spends a strike like the others; guardKillError says
+        // when the verdict has been earned.
+        const killed = guardKillError(name, r, { finalAttempt: attempt === MAX_LEAK_RETRIES });
+        if (killed)
+            throw killed;
+        if (r.stalled) {
+            deps.logDebug?.(`${name}: no output for the stall window and no endpoint answered — `
+                + `${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`);
+            continue;
+        }
         if (clock.timedOut()) {
             if (attempt === MAX_LEAK_RETRIES) {
                 throw new PhaseTimeoutError(name, budgetMs, MAX_LEAK_RETRIES + 1);
@@ -501,6 +704,12 @@ async function runDegradedFinalAttempt(deps, name, prompt, hit, loopHistory) {
     finally {
         clock.cleanup();
     }
+    // BEFORE the exit-code test, not inside it: a guard kill reports exit 0, so
+    // asking afterwards would already have returned the truncated text as this
+    // phase's deliverable.
+    const killed = guardKillError(name, r);
+    if (killed)
+        throw killed;
     if (r.exitCode !== 0 || r.modelError || r.text.trim().length === 0) {
         // A wall-clock kill is NOT a loop. Without this check a child that outran
         // its budget is reported as "loop budget exhausted", carrying a loop

package/dist/task/failure-classifier.js

@@ -5,13 +5,36 @@
 import { updateTaskFrontMatter } from './task-io.js';
 import { flashTerminalWidget } from './widget.js';
 import { publishLifecycleNotice } from '../remote/bridge.js';
-import { LoopExhaustedError, LeakedToolCallError, ModelError, USER_CANCELLED } from './child-runner.js';
+import { BackendDownError, CommandTimeoutError, LoopExhaustedError, LeakedToolCallError, ModelError, USER_CANCELLED } from './child-runner.js';
 // ─── Classifier ──────────────────────────────────────────────────────────────
 export function classifyFailure(err, aborted) {
     const msg = err instanceof Error ? err.message : String(err);
     if (aborted || msg === USER_CANCELLED) {
         return { state: 'cancelled', notify: 'cancelled.', level: 'warning' };
     }
+    // Classified by TYPE, above the message-sniffing branch below: this is the one
+    // case where the probe positively established the endpoint did not answer, and
+    // its message names no errno for that branch to match.
+    if (err instanceof BackendDownError) {
+        return {
+            state: 'failed',
+            reason: `model_unreachable: ${err.message}`,
+            flash: 'model_unreachable',
+            notify: 'failed: model unreachable — restart the model, then resume.',
+            level: 'error'
+        };
+    }
+    // The fix is in the SPEC, not the model, so the notify says which command.
+    if (err instanceof CommandTimeoutError) {
+        return {
+            state: 'failed',
+            reason: err.message.slice(0, 200),
+            flash: 'command_timeout',
+            notify: `failed: \`${err.kill.toolName}\` never returned on any attempt. `
+                + `Resume to bound it in VERIFY.`,
+            level: 'error'
+        };
+    }
     if (err instanceof LoopExhaustedError) {
         return {
             state: 'failed',

package/dist/task/implementation-guards.d.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/** `oneShot` mirrors the impl widget's split: fire-and-forget lets the settle
+ *  event disarm; an awaited run spans resume/steer turns and disarms in its finally. */
+export declare function armImplementationGuard(opts: {
+    oneShot: boolean;
+}): void;
+export declare function disarmImplementationGuard(): void;
+/** @internal Test seam: is a turn currently guarded? */
+export declare function implementationGuardArmed(): boolean;
+/**
+ * Present tense, unlike `formatLoopHint`, which addresses a re-spawned child
+ * about an attempt that does not exist here.
+ *
+ * It claims nothing about the call's RESULT, which this hook fires too early to
+ * see, and it does not offer "change the call" — that is an escape, not advice:
+ * one altered byte is a new key and a clean slate on both counters.
+ */
+export declare function blockedCallReason(toolName: string, count: number): string;
+/** The reason on the final block, which also ends the turn. */
+export declare function terminalCallReason(): string;
+export declare function consumeGuardTermination(): boolean;
+/**
+ * Inert until armed. Registering ANY `tool_call` handler switches on pi's
+ * `beforeToolCall` for every call in the session, so the armed check comes first.
+ */
+export declare function registerImplementationGuards(pi: ExtensionAPI): void;

package/dist/task/implementation-guards.js

@@ -0,0 +1,177 @@
+import { LoopDetector, loopKey, LOOP_THRESHOLD, LOOP_WINDOW, MAX_LOOP_RESTARTS } from './loop-detector.js';
+/**
+ * Runaway guard for the IMPLEMENTATION TURN — the one model surface with none.
+ *
+ * MEASURED: one turn ran 5h16m and 6,760 tool calls, alternating two
+ * byte-identical bash commands 3,300 times each with its output frozen and zero
+ * edits. The command watchdog is per call (each took ~2.5s), the stream was never
+ * silent, and MAX_COMPACTION_RESUMES counts only compactions that PARK at idle,
+ * while all 18 of these were inside the turn. The two detectors are built only in
+ * the CHILD spawn paths, and this turn runs in the user's own session.
+ *
+ * IT BLOCKS RATHER THAN KILLS because there is no re-spawn here — the argument
+ * single-read-extension.ts already makes: "detect-and-kill only re-spawns a model
+ * that deterministically re-thrashes". pi's ctx.abort() would also empty the
+ * queued-message list into the user's editor. That also raises the bar on false
+ * positives: a `gate` child killed by mistake costs one attempt of three, this
+ * costs the user their turn.
+ *
+ * WHY PROGRESS IS READ OFF THE CALL, NOT THE RESULT. The gate profile pairs its
+ * LoopDetector with a StallDetector, which judges results. That cannot work here:
+ * pi's edit tool returns the constant `Successfully replaced N block(s) in <path>.`
+ * and puts the diff in `details`, not `content`, so every real edit to one file is
+ * byte-identical result text and scores as dead ground. An edit's ARGUMENTS carry
+ * the progress its result throws away, so an edit is what resets the window.
+ *
+ * Known blind spots, all deliberate: a bash-driven mutation (`sed -i`, `>`,
+ * `git apply`) does not reset; one varying `write` per iteration buys unlimited
+ * immunity; a repeat cycle of LOOP_WINDOW/LOOP_THRESHOLD or longer never fills the
+ * window; polling a booting server with an identical curl trips at five; and
+ * schema-invalid calls never reach this hook at all, since pi validates first.
+ */
+/** Tool names that mutate the tree. pi ships exactly seven core tools, and
+ *  pi-task's own four (pi-worker, -search, -fetch, -docs) are all read-only. */
+const MUTATING_TOOLS = new Set(['edit', 'write']);
+/**
+ * Path-revisit is OFF for both detectors (that is the Infinity). MEASURED: at the
+ * default threshold, six DISTINCT edits to one file trip the path rule, because
+ * an edit names a `file_path` and no `limit`, so the first one sets the
+ * high-water mark and every later one scores as already-covered ground. Six edits
+ * to one file is the most ordinary thing an implementation turn does. mx5
+ * TASK_0002 is the same lesson from the other side: the rule killed an enforce
+ * child that was editing one file as its job.
+ */
+function freshDetector() {
+    return new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD, Number.POSITIVE_INFINITY);
+}
+/** The armed turn's state, or null outside one. One slot: one task runs at a time. */
+let armed = null;
+/** Built, never spread from the previous state: a leaked `terminating` would
+ *  block every call for the rest of an awaited run. */
+function freshArmedState(oneShot) {
+    return {
+        loop: freshDetector(),
+        edits: freshDetector(),
+        strikes: new Map(),
+        terminating: false,
+        oneShot
+    };
+}
+/** `oneShot` mirrors the impl widget's split: fire-and-forget lets the settle
+ *  event disarm; an awaited run spans resume/steer turns and disarms in its finally. */
+export function armImplementationGuard(opts) {
+    armed = freshArmedState(opts.oneShot);
+}
+export function disarmImplementationGuard() {
+    armed = null;
+}
+/** @internal Test seam: is a turn currently guarded? */
+export function implementationGuardArmed() {
+    return armed !== null;
+}
+/**
+ * Present tense, unlike `formatLoopHint`, which addresses a re-spawned child
+ * about an attempt that does not exist here.
+ *
+ * It claims nothing about the call's RESULT, which this hook fires too early to
+ * see, and it does not offer "change the call" — that is an escape, not advice:
+ * one altered byte is a new key and a clean slate on both counters.
+ */
+export function blockedCallReason(toolName, count) {
+    return (`Blocked: this is the ${count}th identical ${toolName} call in this turn. `
+        + `Use what you already have, or do something different, then continue the task.`);
+}
+/** The reason on the final block, which also ends the turn. */
+export function terminalCallReason() {
+    return (`Blocked: this turn repeated one call past every warning, so it is being stopped `
+        + `here. Nothing further will run.`);
+}
+/**
+ * One-shot: the guard ended a turn, and nothing in the session state says so.
+ *
+ * `terminate` lets the agent loop finish normally — the last assistant message
+ * keeps `stopReason: "toolUse"`, so `classifyTurnEnd` reads `'stop'` and the run
+ * reports a clean finish over work that was cut off mid-task. Verified against a
+ * live model: a real guard-terminated turn ends exactly that way. Same shape as
+ * `consumeWatchdogAbort`, and consumed for the same reason — one reader, then it
+ * is gone.
+ */
+let terminatedTurn = false;
+export function consumeGuardTermination() {
+    const hit = terminatedTurn;
+    terminatedTurn = false;
+    return hit;
+}
+/**
+ * Inert until armed. Registering ANY `tool_call` handler switches on pi's
+ * `beforeToolCall` for every call in the session, so the armed check comes first.
+ */
+export function registerImplementationGuards(pi) {
+    pi.on('tool_call', event => {
+        const state = armed;
+        if (!state)
+            return;
+        try {
+            // Every call, whatever it is: pi terminates only when EVERY finalized
+            // result in the batch carries the flag (agent-loop.js
+            // shouldTerminateToolBatch). The batch that trips it has already
+            // finalized its earlier calls without it and so survives; the next one
+            // ends. One batch, and it is the only bound this path has.
+            if (state.terminating) {
+                return { block: true, terminate: true, reason: terminalCallReason() };
+            }
+            const call = { name: event.toolName, args: event.input };
+            const mutating = MUTATING_TOOLS.has(event.toolName);
+            const hit = mutating ? state.edits.record(call) : state.loop.record(call);
+            if (!hit) {
+                if (mutating) {
+                    state.loop = freshDetector();
+                    // Strikes go with the window. Keeping them made a LATER episode
+                    // terminate on its first hit, skipping both warnings, because an
+                    // earlier one had part-spent the budget. MEASURED over 494 real
+                    // turns: this loses no catch — the incident still ends at call
+                    // 173 of 6,760, both live-model loops still end — and drops one
+                    // termination of a turn that was editing between episodes.
+                    // A determined model is still bounded: three hits inside ONE
+                    // episode terminate, which is the runaway shape (it makes no
+                    // edits at all).
+                    state.strikes.clear();
+                }
+                return;
+            }
+            const key = loopKey(call);
+            const strikes = (state.strikes.get(key) ?? 0) + 1;
+            state.strikes.set(key, strikes);
+            // Blocking alone does not stop a determined model: nothing prevents the
+            // next identical call.
+            if (strikes > MAX_LOOP_RESTARTS) {
+                state.terminating = true;
+                terminatedTurn = true;
+                return { block: true, terminate: true, reason: terminalCallReason() };
+            }
+            return { block: true, reason: blockedCallReason(event.toolName, hit.count) };
+        }
+        catch {
+            // pi does not guard this hook, and a throw here would block a
+            // legitimate call. A broken guard must cost nothing.
+            return;
+        }
+    });
+    // NOT `agent_end`, which fires again for every auto-retry, every threshold
+    // compaction and every queued message — pi drives those with `agent.continue()`,
+    // each a fresh agent loop. The measured runaway compacted 18 times INSIDE its
+    // turn, so a one-shot disarm on agent_end would have retired the guard after the
+    // first ~375 of its 6,760 calls. `agent_settled` is the boundary that means what
+    // this needs: no retry, compaction or queued continuation left to run.
+    pi.on('agent_settled', () => {
+        if (!armed)
+            return;
+        if (armed.oneShot)
+            disarmImplementationGuard();
+        // An awaited run spans resume and steer turns. Counters are per TURN, so a
+        // fresh one starts clean rather than inheriting the last one's strikes.
+        else
+            armed = freshArmedState(false);
+    });
+    pi.on('session_shutdown', disarmImplementationGuard);
+}

package/dist/task/implementation-turn.d.ts

@@ -96,6 +96,8 @@ export interface SteerWatchdogDeps {
 export interface ImplementationTurnDeps {
     /** The live session entries — the only thing the classifier reads. */
     entries: () => ReadonlyArray<SessionEntryLike>;
+    /** Test seam over the module-level one-shot; the real reader is the default. */
+    consumeGuardTermination?: () => boolean;
     /** Queue a follow-up user turn on the (idle) session. */
     send: (text: string) => Promise<void>;
     /** Wait for the session to go idle again. */
@@ -139,6 +141,9 @@ export declare const CONTINUE_AFTER_COMPACTION: string;
  * lets the verify gate and `/task-auto-resume` catch any leftover incompleteness.
  */
 export declare 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 declare 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