@mjasnikovs/pi-task 0.38.30 → 0.38.31

package/dist/index.js

@@ -6,6 +6,7 @@ import { registerWorkers } from './workers/index.js';
 import { registerRemote } from './remote/register.js';
 import { registerCommandWatchdog } from './task/command-watchdog.js';
 import { registerStreamWatchdog } from './task/stream-watchdog.js';
+import { registerImplementationGuards } from './task/implementation-guards.js';
 export default function (pi) {
     registerConfig(pi);
     registerTask(pi);
@@ -15,4 +16,5 @@ export default function (pi) {
     registerRemote(pi);
     registerCommandWatchdog(pi);
     registerStreamWatchdog(pi);
+    registerImplementationGuards(pi);
 }

package/dist/shared/command-watchdog.d.ts

@@ -122,3 +122,66 @@ export declare class CommandWatchdog {
  * the call it watches.
  */
 export declare const realTimerDeps: Pick<WatchdogDeps, 'schedule' | 'cancel'>;
+/** What the command watchdog recorded when it killed a child attempt. */
+export 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;
+}
+/**
+ * The tool-call fields the child-side watchdog reads. Structural rather than
+ * `ToolCall` from child-process.ts, so this module keeps its zero imports and a
+ * caller cannot be forced to reach for the runner's types to arm a timer.
+ */
+export interface WatchedToolCall {
+    name: string;
+    toolCallId?: string;
+    args: unknown;
+}
+/**
+ * Build the child-side command watchdog for ONE attempt: a per-tool-call timer
+ * machine 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.
+ */
+export declare function commandWatch(timeoutMs: number): {
+    onStart: (call: WatchedToolCall) => void;
+    onEnd: (toolCallId: string | undefined) => void;
+    killed: () => CommandKill | undefined;
+    signal: AbortSignal;
+    clear: () => void;
+} | null;
+/**
+ * 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;

package/dist/shared/command-watchdog.js

@@ -172,3 +172,90 @@ export const realTimerDeps = {
     schedule: (fn, ms) => setTimeout(fn, ms),
     cancel: handle => clearTimeout(handle)
 };
+/**
+ * Build the child-side command watchdog for ONE attempt: a per-tool-call timer
+ * machine 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.
+ */
+export 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 => {
+            // Drop the command line with its call. The `'anon'` fallback above is a
+            // SHARED slot, so a stale entry would be attributed to whatever ran
+            // next: a `read` that later overran would be reported as
+            // "ran a `read` command (bun run dev)".
+            details.delete(key(id));
+            watchdog.onEnd(key(id));
+        },
+        killed: () => killed,
+        signal: ctrl.signal,
+        clear: () => watchdog.clearAll()
+    };
+}
+/**
+ * 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));
+}

package/dist/task/auto-orchestrator.js

@@ -22,7 +22,7 @@ import { drainRepairQueue, mergeRepairCandidates, planHasRepairFor, parseRepairT
 import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasksDir } from './task-io.js';
 import { readTextFile } from '../shared/fs-text.js';
 import { findPhantomImports, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
-import { prependHint, USER_CANCELLED } from './child-runner.js';
+import { isFatalChildCause, prependHint, USER_CANCELLED } from './child-runner.js';
 import { requestCancel, resetCancel, isCancelRequested, cancelCheckpoint } from './cancel-points.js';
 import { withRun, announceTerminal } from './run-bracket.js';
 import { refineExistingFilesBlock, SINGLE_READ_EXTENSION_PATH } from './phases.js';
@@ -493,8 +493,15 @@ export async function orientFeature(cwd, feature, deps) {
         reqEntries = capRequirements(reqEntries, passages, featureForModel);
         logPlanDebug(cwd, `requirement extraction: ${reqEntries.length} grounded requirement(s) kept`);
     }
-    catch {
-        // best-effort channel
+    catch (e) {
+        // Best-effort covers a child that answered badly. It must NOT cover a user
+        // ESC or a dead backend: planning would continue on an EMPTY ledger, moving
+        // the granularity floor and shipping a degraded plan instead of a cancel or
+        // a failure. Same rule as verify-resolution.ts.
+        if (isFatalChildCause(e))
+            throw e;
+        // Best-effort, but not silent: nothing else records a guard kill here.
+        logPlanDebug(cwd, `requirement extraction: skipped — ${e.message}`);
     }
     // Granularity floor: without it the plan's task COUNT is set by an
     // auto-resolved clarify line the user never sees, so the same spec and the same
@@ -1101,8 +1108,12 @@ function defaultDeps(ctx, cwd, signal, title) {
     const status = new ChildStatus({ parentContextWindow });
     const phaseDeps = {
         cwd,
+        // No task file, so appendLoopEvent swallows its ENOENT. Its docblock
+        // allows that because "the kill is already reported through the debug
+        // log" — which is why logDebug below is not optional here.
         taskId: '',
         signal,
+        logDebug: msg => logPlanDebug(cwd, msg),
         // IN-RUN thrash guard for the planning children: without it a decompose
         // child can re-read its design document until it fills the whole context
         // window, and never return. Every planning child

package/dist/task/child-runner.d.ts

@@ -6,15 +6,14 @@
  * for phase-level child pi invocations.
  */
 import { type SpawnFn, type ContextSnapshot, type ToolCall, type LoopHit } from '../shared/child-process.js';
+import { type CommandKill } from '../shared/command-watchdog.js';
+import { type WorkerGuardPolicy } from '../workers/worker-profiles.js';
 import type { DebugLine } from './debug-log.js';
 import type { RunWorkerInput, RunWorkerResult } from '../workers/pi-worker-core.js';
 import type { docsRaw, docsFocused } from '../workers/docs-core.js';
 import type { fetchRaw, fetchFocused } from '../workers/fetch-core.js';
 import type { npmVersionLookup } from '../workers/npm-version.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
-export declare const LOOP_WINDOW = 20;
-export declare const LOOP_THRESHOLD = 5;
-export declare const MAX_LOOP_RESTARTS = 2;
 /**
  * Optional wall-clock bound on ONE spawn of a phase child. DEFAULT: OFF.
  *
@@ -50,6 +49,54 @@ export declare class PhaseTimeoutError extends Error {
     readonly attempts: number;
     constructor(childName: string, budgetMs: number, attempts: number);
 }
+/**
+ * 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 declare function guardKillError(name: string, r: PhaseRunResult, opts?: {
+    finalAttempt?: boolean;
+}): Error | 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 declare class BackendDownError extends Error {
+    readonly childName: string;
+    constructor(childName: string);
+}
+/**
+ * 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 declare class CommandTimeoutError extends Error {
+    readonly childName: string;
+    readonly kill: CommandKill;
+    constructor(childName: string, kill: CommandKill);
+}
+/**
+ * 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 declare function isFatalChildCause(e: unknown): boolean;
+/**
+ * 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 declare function isConnectionError(cause: string): boolean;
 /** Exponential backoff before a connection-error retry: 500ms, 1s, 2s, …, so a
  *  brief saturation window can drain before we re-issue the request. */
@@ -63,6 +110,18 @@ export interface PhaseRunResult {
     leakedToolCall?: string;
     /** Set when the child's final turn failed with stopReason "error" (model/provider failure). */
     modelError?: string;
+    /**
+     * Set when the per-command watchdog killed the child: one tool call outran
+     * `requestTimeoutMs`. RESTARTABLE (worker-kill.ts) — a hung command is a
+     * mistake the next attempt can be told not to repeat.
+     */
+    commandKill?: CommandKill;
+    /**
+     * Set when the dead-backend probe killed the child: no output for the stall
+     * window AND the model endpoint unreachable. NOT restartable (worker-kill.ts):
+     * re-spawning against a backend that is down buys nothing.
+     */
+    stalled?: boolean;
 }
 export declare function childArgs(tools: string, extensions?: readonly string[], 
 /**
@@ -120,8 +179,23 @@ export interface ChildRun {
      * group, or `[]`/omitted to inherit the session default as before.
      */
     thinking?: readonly string[];
+    /**
+     * This attempt's per-command ceiling, already halved for prior hangs by the
+     * caller's strike loop. Omitted -> the `phase` row's full configured ceiling,
+     * which is the right value for a single-attempt caller.
+     */
+    commandCeilingMs?: number;
 }
-export declare function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking }: ChildRun): Promise<PhaseRunResult>;
+/**
+ * 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 declare function phasePolicy(): WorkerGuardPolicy;
+export declare function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking, commandCeilingMs }: ChildRun): Promise<PhaseRunResult>;
 export interface PhaseDeps {
     cwd: string;
     taskId: string;