@mjasnikovs/pi-task 0.38.25 → 0.38.27

package/dist/workers/pi-worker.js

@@ -8,6 +8,7 @@
  */
 import { Text } from '@earendil-works/pi-tui';
 import { Type } from '@sinclair/typebox';
+import { getConfig } from '../config/config.js';
 import { groupThinkingArgs } from '../config/reasoning-args.js';
 import { runWorker } from './pi-worker-core.js';
 import { childFailureReason, formatChildFailure, makeWorkerTool, workerAnswer, workerUnavailable } from './shared.js';
@@ -47,12 +48,12 @@ export function registerPiWorker(pi) {
                 prompt: params.prompt,
                 cwd: ctx.cwd,
                 signal,
-                // `adhoc` is every guard at its default — which is what this call
-                // site already got by naming none of them. Named now so it is a
-                // decision, and so the one asymmetry it carries (a FIXED 240s cap
-                // where a research worker gets 240s without progress) is written
-                // down. See the `adhoc` row in workers/worker-profiles.ts.
                 profile: 'adhoc',
+                // The user's own `stuck reply retry` is what bounds this worker
+                // now — it kills on SILENCE, never on slowness. It is an INPUT and
+                // not policy for the same reason the gate's two ceilings are: the
+                // number is the user's, the decision to arm it is the profile's.
+                policyInputs: { streamInactivityMs: getConfig().streamInactivityMs },
                 thinking: groupThinkingArgs('research')
             });
             const details = { exitCode: result.exitCode };

package/dist/workers/shared.d.ts

@@ -17,12 +17,25 @@ export interface ChildOutcome {
 }
 /**
  * The one place worker child-failure is turned into a user-facing message.
- * Returns `null` when the child succeeded (caller proceeds to format output),
- * otherwise the standard abort/exit message. Concentrating this here keeps the
- * stderr-tail rule identical across every worker — it had already drifted
- * (`pi-worker` skipped the `.trim()` the others applied).
+ * Returns `null` when the child succeeded (caller proceeds to format output).
+ *
+ * It ASKS THE LADDER now (`classifyWorkerFailure` -> `describeWorkerFailure`)
+ * rather than re-deriving the answer from two fields. It used to be
+ * `if (aborted) return abortedMessage`, and every kill path also sets `aborted`,
+ * so a wall-clock kill, a hung command, a dead backend, a loop kill and a user
+ * ESC all produced the same four words — while `childFailureReason`, one line
+ * later at the only caller that had the richer result, computed the real cause
+ * and sent it to a debug trail nobody reads. That is the same shape as the bug
+ * `worker-failure.ts`'s own header records, one layer out: a second author of a
+ * taxonomy the module exists to own.
+ *
+ * A caller with only a `ChildOutcome` is unaffected. It carries no kill flags,
+ * so the ladder falls through to `aborted`/`exit` and returns exactly what this
+ * function returned before — which `shared.test.ts` pins.
  */
-export declare function formatChildFailure(child: ChildOutcome, abortedMessage: string): string | null;
+export declare function formatChildFailure(child: ChildOutcome | (WorkerFailureInput & {
+    stderr?: string;
+}), abortedMessage: string): string | null;
 /**
  * What a worker tool PRODUCED — an answer, or a statement that it has none.
  *

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

@@ -122,4 +122,30 @@ export declare const FAILURE_RULES: ReadonlyArray<{
  * which is not the same as "it answered": the text may still be empty, and that
  * judgement belongs to the caller.
  */
+/**
+ * What a worker failure SAYS to the caller that asked for the work.
+ *
+ * WHY IT EXISTS. The ladder above already names the cause exactly, with its
+ * detail — which tool hung, how long the stream was idle, which exit code. None
+ * of that reached a human. `formatChildFailure` was handed a `ChildOutcome`
+ * (`{aborted, exitCode, stderr}`) and answered `if (aborted) return
+ * abortedMessage`, so a 240s wall-clock kill, a hung `bash`, a dead model
+ * backend, a loop kill and a user pressing ESC all printed the SAME four words.
+ * The discriminating value was computed a line later by `childFailureReason` and
+ * put in the debug trail, which a user reading a tool result never sees.
+ *
+ * That is not only unhelpful; it is why the `pi-worker` tool's 240s cap has no
+ * base rate. 53 recorded invocations across eight repos carry 14 failures, and
+ * NOTHING in the transcript says which of them ran out of time — the honest
+ * bound recoverable from timestamps alone is "somewhere between 0 and 8".
+ *
+ * A switch, not a table: `WorkerFailure` is a discriminated union carrying a
+ * different payload per arm, so the exhaustiveness check is the compiler's and a
+ * ninth arm cannot be added without a message.
+ */
+export declare function describeWorkerFailure(f: WorkerFailure, 
+/** What a genuine user cancel says. The caller's wording — only this arm is theirs. */
+abortedMessage: string, 
+/** stderr for the `exit` arm; ignored by every other. */
+stderr?: string): string;
 export declare function classifyWorkerFailure(r: WorkerFailureInput): WorkerFailure | undefined;

package/dist/workers/worker-failure.js

@@ -83,6 +83,60 @@ export const FAILURE_RULES = [
  * which is not the same as "it answered": the text may still be empty, and that
  * judgement belongs to the caller.
  */
+/**
+ * What a worker failure SAYS to the caller that asked for the work.
+ *
+ * WHY IT EXISTS. The ladder above already names the cause exactly, with its
+ * detail — which tool hung, how long the stream was idle, which exit code. None
+ * of that reached a human. `formatChildFailure` was handed a `ChildOutcome`
+ * (`{aborted, exitCode, stderr}`) and answered `if (aborted) return
+ * abortedMessage`, so a 240s wall-clock kill, a hung `bash`, a dead model
+ * backend, a loop kill and a user pressing ESC all printed the SAME four words.
+ * The discriminating value was computed a line later by `childFailureReason` and
+ * put in the debug trail, which a user reading a tool result never sees.
+ *
+ * That is not only unhelpful; it is why the `pi-worker` tool's 240s cap has no
+ * base rate. 53 recorded invocations across eight repos carry 14 failures, and
+ * NOTHING in the transcript says which of them ran out of time — the honest
+ * bound recoverable from timestamps alone is "somewhere between 0 and 8".
+ *
+ * A switch, not a table: `WorkerFailure` is a discriminated union carrying a
+ * different payload per arm, so the exhaustiveness check is the compiler's and a
+ * ninth arm cannot be added without a message.
+ */
+export function describeWorkerFailure(f, 
+/** What a genuine user cancel says. The caller's wording — only this arm is theirs. */
+abortedMessage, 
+/** stderr for the `exit` arm; ignored by every other. */
+stderr = '') {
+    switch (f.kind) {
+        case 'stalled':
+            return ('Worker stopped: it produced no output and the model backend was '
+                + 'unreachable. This is an infrastructure failure, not a bad question — '
+                + 'retrying the same request once the backend is back is reasonable.');
+        case 'command-timeout':
+            return (`Worker killed: \`${f.toolName}\` ran past its `
+                + `${Math.round(f.timeoutMs / 1000)}s per-command limit and was still `
+                + 'running. A command that does not terminate on its own (a dev server, a '
+                + 'watcher) has to be bounded by the command itself.');
+        case 'stream-stall':
+            return (`Worker killed: no output for ${Math.round(f.idleMs / 1000)}s while the `
+                + 'model backend was still reachable — a hung stream, not a slow one.');
+        case 'worker-timeout':
+            return ('Worker ran out of time before answering, on every attempt, and returned '
+                + 'nothing. The question was too broad for one worker: narrow it to one '
+                + 'directory or one question, or split it across several workers.');
+        case 'loop':
+            return ('Worker killed: it repeated the same tool call without making progress. '
+                + 'Nothing it had already read was answering the question as asked.');
+        case 'leaked-tool-call':
+            return 'Worker produced a malformed tool call instead of an answer.';
+        case 'aborted':
+            return abortedMessage;
+        case 'exit':
+            return `Worker exited ${f.code}.\n${stderr.trim().slice(-500) || '(no stderr)'}`;
+    }
+}
 export function classifyWorkerFailure(r) {
     for (const rule of FAILURE_RULES) {
         const hit = rule.match(r);

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

@@ -295,7 +295,7 @@ export declare const WORKER_PROFILES: {
     readonly adhoc: {
         readonly id: "adhoc";
         readonly why: string;
-        readonly resolve: () => {
+        readonly resolve: (inputs: WorkerPolicyInputs) => {
             guards: WorkerGuards;
             carryForward: false;
         };

package/dist/workers/worker-profiles.js

@@ -175,18 +175,37 @@ export const WORKER_PROFILES = {
     },
     adhoc: {
         id: 'adhoc',
-        why: 'The model-dispatched `pi-worker` tool. Every guard at its default, and '
-            + 'this row exists so that is a DECISION rather than the absence of one — '
-            + 'the call site passed nothing, and nobody could see what it therefore '
-            + 'got. What the table now makes visible is an asymmetry: this is the '
-            + 'strictest-clocked of the three children. It runs a FIXED 240s cap, '
-            + 'because `progressCeilingMs` is null and the deadline re-arm is inert '
-            + 'without one, while a research worker doing the same read-only '
-            + 'exploration gets 240s WITHOUT PROGRESS up to 20 minutes. That '
-            + 'difference is preserved exactly here and is NOT defended: the progress '
-            + 'deadline was measured for the research workers (nexttask 9) and has '
-            + 'never been measured for this tool. It is a candidate, not a bug.',
-        resolve: () => ({ guards: baseGuards(), carryForward: false })
+        why: 'The model-dispatched `pi-worker` tool: a read-only child with '
+            + '`read,grep,find,ls` and nothing else, asked a question the MODEL wrote. '
+            + 'It has NO WALL CLOCK, and that is a decision with evidence behind it. '
+            + 'It used to run a FIXED 240s cap — total elapsed, not idle — inherited by '
+            + 'naming no guards at all. A fixed wall clock on a read-only worker makes '
+            + "answer quality a function of the user's hardware: the same prompt on a "
+            + 'slower local model loses its work and degrades, which is the argument '
+            + 'research-fanout-budget.ts already records against every wall-clock lever '
+            + '("no constant fixes that"). It is worse than that — the constant was '
+            + 'sized against "~25-130s on the local backend", and MEASURED on 37 '
+            + 'replayed real prompts after only a MODEL swap on the SAME machine: '
+            + 'median 76s, p90 371s, max 442s, with 14/37 above the 130s it was '
+            + 'calibrated to and 8/37 (22%) past the cap outright. A bound that has to '
+            + 'be re-measured whenever the model changes is the wrong bound. '
+            + "What replaces it is `stream-stall`, armed from the user's own "
+            + '`stuck reply retry` setting: it kills on SILENCE, never on slowness — '
+            + '"one token every 30s is a working local model and must never be killed; '
+            + 'zero events for the whole window is a hang" — so it needs no calibration '
+            + 'and no new setting. Real thrash is still caught by the two runaway '
+            + 'detectors and the dead-backend probe, all of which stay on.',
+        resolve: inputs => {
+            const guards = baseGuards();
+            // No wall clock. See `why`: a fixed elapsed-time cap on a read-only
+            // worker is a hardware test, not a work test.
+            guards['worker-timeout'] = { timeoutMs: 0, progressCeilingMs: null, fanout: null };
+            // The silence bound that replaces it — the user's own setting, not a
+            // new one. 0 when the caller hands none, which is off, exactly as
+            // before: a harness must not silently acquire a guard.
+            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.25",
+    "version": "0.38.27",
     "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",