@mjasnikovs/pi-task 0.39.0 → 0.39.1

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

@@ -17,15 +17,21 @@
  * row type would need an escape hatch per row. What the orderings gain here is that
  * neither can name a cause with no row, nor silently omit one.
  *
- * Not every cause appears in both ladders, and that asymmetry is real. Six of the
- * nine are `restartable` and those six are exactly RESTART_ORDER; eight are
- * `reported` and those eight are exactly FAILURE_ORDER. `connection-error` is the
- * one that restarts without ever being reported as a kill — it reaches the caller
- * as a `modelError`. `stalled`, `aborted` and `exit` end an attempt outright, and
- * no hint would help.
+ * Not every cause appears in both ladders, and that asymmetry is real. Eight of
+ * the ten are `restartable` and those eight are exactly RESTART_ORDER; eight are
+ * `reported` and those eight are exactly FAILURE_ORDER. `connection-error` and
+ * `empty-answer` restart without ever being reported as a kill — the first
+ * reaches the caller as a `modelError`, the second as empty text, and whether
+ * either counts as a failure is the consumer's policy. `aborted` and `exit` end
+ * an attempt outright, and no hint would help.
+ *
+ * Whether a restartable cause actually restarts is the PROFILE's decision
+ * (worker-profiles.ts): `stalled` and `empty-answer` each carry a switch there,
+ * because the phase children re-spawn on both and the research workers on
+ * neither.
  */
 /** Every way a worker attempt can end other than by answering. */
-export type WorkerKillId = 'stalled' | 'command-timeout' | 'stream-stall' | 'worker-timeout' | 'connection-error' | 'loop' | 'leaked-tool-call' | 'aborted' | 'exit';
+export type WorkerKillId = 'stalled' | 'command-timeout' | 'stream-stall' | 'worker-timeout' | 'connection-error' | 'loop' | 'leaked-tool-call' | 'empty-answer' | 'aborted' | 'exit';
 export interface WorkerKill {
     id: WorkerKillId;
     /**
@@ -54,20 +60,33 @@ export interface WorkerKill {
     restartable: boolean;
     /** Does this cause reach a consumer as a `WorkerFailure`? */
     reported: boolean;
+    /**
+     * Must a best-effort `catch` in the phase pipeline rethrow this?
+     *
+     * A child that merely answered badly should degrade — that is what those
+     * catches are for. A dead backend is different in kind: the run is over
+     * either way, and swallowing it ships a half-built spec while every later
+     * phase dies against the same dead server. A property of the cause, so a
+     * catch asks the roster rather than keeping its own list.
+     */
+    fatal: boolean;
 }
 export declare const WORKER_KILLS: readonly WorkerKill[];
 /** Look one cause up. `undefined` only for an id with no row, which the suite forbids. */
 export declare function workerKill(id: WorkerKillId): WorkerKill | undefined;
+/** Takes any string: the phase failure union carries kinds that are not kills. */
+export declare function isFatalKill(kind: string): boolean;
 /**
  * The restart ladder's precedence, as ids. `RESTART_RULES` must be exactly this,
  * in this order.
  *
  * `loop` leads: its hint names the offending call, which is the most useful thing
- * to tell a re-spawn. The two watchdogs come before the wall clock because each
- * is the narrower diagnosis, and they cannot be confused with it — a watchdog
- * kill leaves the worker's own timeout flag false.
+ * to tell a re-spawn. The two watchdogs and the dead-backend probe come before
+ * the wall clock because each is the narrower diagnosis, and they cannot be
+ * confused with it — a guard kill leaves the worker's own timeout flag false.
+ * `empty-answer` is last: like a leaked call it exists only on a clean run.
  */
-export declare const RESTART_ORDER: readonly ["loop", "command-timeout", "stream-stall", "worker-timeout", "connection-error", "leaked-tool-call"];
+export declare const RESTART_ORDER: readonly ["loop", "command-timeout", "stream-stall", "stalled", "worker-timeout", "connection-error", "leaked-tool-call", "empty-answer"];
 /**
  * The failure ladder's precedence, as ids. `FAILURE_RULES` must be exactly this,
  * in this order.

package/dist/workers/worker-kill.js

@@ -17,80 +17,128 @@
  * row type would need an escape hatch per row. What the orderings gain here is that
  * neither can name a cause with no row, nor silently omit one.
  *
- * Not every cause appears in both ladders, and that asymmetry is real. Six of the
- * nine are `restartable` and those six are exactly RESTART_ORDER; eight are
- * `reported` and those eight are exactly FAILURE_ORDER. `connection-error` is the
- * one that restarts without ever being reported as a kill — it reaches the caller
- * as a `modelError`. `stalled`, `aborted` and `exit` end an attempt outright, and
- * no hint would help.
+ * Not every cause appears in both ladders, and that asymmetry is real. Eight of
+ * the ten are `restartable` and those eight are exactly RESTART_ORDER; eight are
+ * `reported` and those eight are exactly FAILURE_ORDER. `connection-error` and
+ * `empty-answer` restart without ever being reported as a kill — the first
+ * reaches the caller as a `modelError`, the second as empty text, and whether
+ * either counts as a failure is the consumer's policy. `aborted` and `exit` end
+ * an attempt outright, and no hint would help.
+ *
+ * Whether a restartable cause actually restarts is the PROFILE's decision
+ * (worker-profiles.ts): `stalled` and `empty-answer` each carry a switch there,
+ * because the phase children re-spawn on both and the research workers on
+ * neither.
  */
 export const WORKER_KILLS = [
     {
         id: 'stalled',
         resultField: 'stalled',
         carryForward: false,
-        restartable: false,
-        reported: true
+        restartable: true,
+        reported: true,
+        fatal: true
     },
     {
         id: 'command-timeout',
         resultField: 'commandTimedOut',
         carryForward: true,
         restartable: true,
-        reported: true
+        reported: true,
+        fatal: false
     },
     {
         id: 'stream-stall',
         resultField: 'streamStalled',
         carryForward: true,
         restartable: true,
-        reported: true
+        reported: true,
+        fatal: false
     },
     {
         id: 'worker-timeout',
         resultField: 'timedOut',
         carryForward: true,
         restartable: true,
-        reported: true
+        reported: true,
+        fatal: false
     },
     {
         id: 'connection-error',
         resultField: null,
         carryForward: true,
         restartable: true,
-        reported: false
+        reported: false,
+        fatal: false
+    },
+    {
+        id: 'loop',
+        resultField: 'loopHit',
+        carryForward: false,
+        restartable: true,
+        reported: true,
+        fatal: false
     },
-    { id: 'loop', resultField: 'loopHit', carryForward: false, restartable: true, reported: true },
     {
         id: 'leaked-tool-call',
         resultField: 'leakedToolCall',
         carryForward: false,
         restartable: true,
-        reported: true
+        reported: true,
+        fatal: false
+    },
+    {
+        id: 'empty-answer',
+        resultField: null,
+        carryForward: false,
+        restartable: true,
+        reported: false,
+        fatal: false
     },
-    { id: 'aborted', resultField: null, carryForward: false, restartable: false, reported: true },
-    { id: 'exit', resultField: null, carryForward: false, restartable: false, reported: true }
+    {
+        id: 'aborted',
+        resultField: null,
+        carryForward: false,
+        restartable: false,
+        reported: true,
+        fatal: false
+    },
+    {
+        id: 'exit',
+        resultField: null,
+        carryForward: false,
+        restartable: false,
+        reported: true,
+        fatal: false
+    }
 ];
 /** Look one cause up. `undefined` only for an id with no row, which the suite forbids. */
 export function workerKill(id) {
     return WORKER_KILLS.find(k => k.id === id);
 }
+/** Takes any string: the phase failure union carries kinds that are not kills. */
+export function isFatalKill(kind) {
+    return WORKER_KILLS.some(k => k.id === kind && k.fatal);
+}
 /**
  * The restart ladder's precedence, as ids. `RESTART_RULES` must be exactly this,
  * in this order.
  *
  * `loop` leads: its hint names the offending call, which is the most useful thing
- * to tell a re-spawn. The two watchdogs come before the wall clock because each
- * is the narrower diagnosis, and they cannot be confused with it — a watchdog
- * kill leaves the worker's own timeout flag false.
+ * to tell a re-spawn. The two watchdogs and the dead-backend probe come before
+ * the wall clock because each is the narrower diagnosis, and they cannot be
+ * confused with it — a guard kill leaves the worker's own timeout flag false.
+ * `empty-answer` is last: like a leaked call it exists only on a clean run.
  */
 export const RESTART_ORDER = [
     'loop',
     'command-timeout',
     'stream-stall',
+    'stalled',
     'worker-timeout',
     'connection-error',
-    'leaked-tool-call'
+    'leaked-tool-call',
+    'empty-answer'
     // `as const satisfies`, not an annotation: `WorkerRestartReason` is
     // `(typeof RESTART_ORDER)[number]`, and a `readonly WorkerKillId[]`
     // annotation collapses that to the whole `WorkerKillId` union — which would

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

@@ -89,6 +89,12 @@ export interface StalledGuard {
      * harnesses inject a real probe through the override.
      */
     probe: (() => Promise<boolean>) | null;
+    /**
+     * Re-spawn on a dead-backend kill, within the shared restart budget, so the
+     * verdict is earned on every attempt rather than on one probe sample. Off
+     * for a worker whose caller would rather hear "unreachable" at once.
+     */
+    restart: boolean;
 }
 /**
  * The whole-worker deadline. All three fields move the SAME timer, which is why
@@ -198,6 +204,14 @@ interface WorkerGuardShapes {
     'connection-error': number;
     loop: LoopGuard;
     'leaked-tool-call': null;
+    /**
+     * Re-spawn on an empty completion — exit 0, no text, no reported error —
+     * within the shared restart budget. For a phase child that is almost always
+     * a provider error swallowed inside `--mode json`, not a repeatable mistake.
+     * Off for the research workers, which decide what an empty section means
+     * themselves (research-worker.ts).
+     */
+    'empty-answer': boolean;
     aborted: null;
     exit: null;
 }
@@ -252,6 +266,12 @@ export interface WorkerPolicyInputs {
     commandTimeoutMs?: number;
     /** gate, phase: `config.streamInactivityMs`. */
     streamInactivityMs?: number;
+    /**
+     * phase: a wall clock on ONE spawn, for a caller that genuinely wants a hard
+     * stop. Nothing sets it in production — see the phase row's `why` — and
+     * tests inject a short one.
+     */
+    timeoutMs?: number;
     /** research: only `worker:apis` fans out, so only it can be scaled. */
     fanoutBounded?: boolean;
     /** research: the env reader the fanout and progress-ceiling levers use.

package/dist/workers/worker-profiles.js

@@ -102,7 +102,7 @@ export const DEFAULT_LOOP_PROGRESS = {
  */
 function baseGuards() {
     return {
-        stalled: { afterMs: STALL_AFTER_MS, probe: null },
+        stalled: { afterMs: STALL_AFTER_MS, probe: null, restart: false },
         'command-timeout': 0,
         'stream-stall': 0,
         'worker-timeout': {
@@ -113,6 +113,7 @@ function baseGuards() {
         'connection-error': MAX_LOOP_RESTARTS,
         loop: { detector: { ...DEFAULT_LOOP_DETECTOR }, progress: { ...DEFAULT_LOOP_PROGRESS } },
         'leaked-tool-call': null,
+        'empty-answer': false,
         aborted: null,
         exit: null
     };
@@ -213,21 +214,33 @@ export const WORKER_PROFILES = {
             + '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.',
+            + 'The wall clock is OFF. A wall clock on a model child measures the '
+            + "MODEL'S SPEED, not its health: the same planning child that answers "
+            + 'in seconds on one backend takes minutes on another, so any cap loose '
+            + 'enough to be safe catches nothing and any cap tight enough to catch a '
+            + 'runaway kills healthy work. The runaway it would catch — forward-paging '
+            + "through a whole context window — is the StallDetector's, which bounds "
+            + 'non-progress and churn rather than elapsed time. '
+            + 'Two departures the research workers do not share. A dead-backend kill '
+            + 'is RETRIED: one probe sample cannot tell a blip from a death, three '
+            + 'failed probes cost the stall window three times, and one wrong verdict '
+            + 'ends the whole run. And an EMPTY completion is retried: inside '
+            + '`--mode json` a swallowed provider error arrives as exit 0 with no '
+            + 'text, and a fresh spawn almost always answers.',
         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 };
+            guards['worker-timeout'] = {
+                timeoutMs: inputs.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;
+            guards.stalled = { afterMs: STALL_AFTER_MS, probe: null, restart: true };
+            guards['empty-answer'] = true;
             return { guards, carryForward: false };
         }
         // `as const satisfies`, not an annotation — the same reason RESTART_ORDER

package/package.json

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