@mjasnikovs/pi-task 0.38.2 → 0.38.3

package/dist/workers/pi-worker-docs.js

@@ -3,7 +3,7 @@ import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
-import { docsRaw, formatResultText, buildPrompt, buildVersionBanner } from './docs-core.js';
+import { docsRaw, formatResultText, packageHeader, buildPrompt, buildVersionBanner } from './docs-core.js';
 import { formatNpmVersionSection } from './npm-version.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { makeWorkerTool } from './shared.js';
@@ -12,6 +12,7 @@ import { logDocsAnswer } from './typeonly-log.js';
 import { normalizeQuery } from './research-cache.js';
 import { projectDocsRaw, buildProjectPrompt } from './docs-project.js';
 import { projectDocsBudget, projectDocsBudgetExhausted } from '../task/research-fanout-budget.js';
+import { isAbstention } from './abstention.js';
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
     module: Type.String({
@@ -189,13 +190,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 if (!extraction.ok)
                     return docsFailureResult(extraction, baseDetails, '');
                 const verified = extraction.excerptVerified;
-                const text = formatResultText({
-                    name: projectName,
-                    version: 'local',
-                    root: ctx.cwd,
-                    entryDts: null,
-                    readme: null
-                }, extraction, verified);
+                const text = formatResultText(`Per ${projectName} (project source):`, extraction, verified);
                 // SAME instrumentation channel as the package path below, extended to the
                 // project-source branch because that branch is the MAJORITY of what
                 // worker:apis asks — 13 of 17 docs calls in run 15's fatal task, 7 of 12 in
@@ -302,7 +297,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 return docsFailureResult(extraction, baseDetails, versionBanner + npmHeader);
             }
             const verified = extraction.excerptVerified;
-            const body = formatResultText(pkg, extraction, verified);
+            const body = formatResultText(packageHeader(pkg), extraction, verified);
             // F-2: a TYPE-ONLY answer is the dangerous failure. "unclear from this package"
             // is honest and already escalates; a signature is a well-formed, confident,
             // on-topic answer that names the very parameter asked about, so the worker
@@ -404,6 +399,6 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         cacheable: (d, text) => d.childExitCode === 0
             && d.typeOnly !== true
             && d.excerptVerified !== false
-            && !/unclear from this package/i.test(text)
+            && !isAbstention(text)
     });
 }

package/dist/workers/pi-worker-fetch.js

@@ -4,6 +4,7 @@ import { FetchAndCleanError } from './html-clean.js';
 import { fetchFocused, formatResultText } from './fetch-core.js';
 import { makeWorkerTool } from './shared.js';
 import { normalizeQuery } from './research-cache.js';
+import { isAbstention } from './abstention.js';
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
     url: Type.String({ description: 'URL to fetch. Must be http or https.' }),
@@ -92,6 +93,12 @@ export function registerPiWorkerFetch(pi, internals = {}) {
         cacheKey: params => `${params.url.trim()}::${normalizeQuery(params.query)}`,
         // Only a completed fetch (child exited 0) is a real answer; invalid-URL,
         // fetch failures, and aborts omit childExitCode:0 and fall through.
-        cacheable: d => d.childExitCode === 0
+        // F-2(e), on the fetch channel. A child that ran fine and answered
+        // "unclear from this page" exits 0, so caching on process health alone
+        // memoised the NON-ANSWER and re-served it to every later sibling task —
+        // the same dead-end-paid-many-times shape pi-worker-docs already closed
+        // for packages, with escalation unable to re-fire because the miss never
+        // recurred. One predicate now covers every corpus (workers/abstention.ts).
+        cacheable: (d, text) => d.childExitCode === 0 && !isAbstention(text)
     });
 }

package/dist/workers/typeonly-log.js

@@ -37,17 +37,9 @@
  * reconstruct later.
  */
 import * as fs from 'node:fs';
+import { isAbstention } from './abstention.js';
 /** Env var naming the JSONL sink. Unset (or empty) ⇒ instrumentation is entirely off. */
 export const TYPEONLY_LOG_ENV = 'PI_TASK_TYPEONLY_LOG';
-/**
- * The honest non-answer, in BOTH wordings the tool can emit. A package lookup is told to
- * write "unclear from this package" (docs-core.ts:622); a project-source lookup is told
- * "unclear from this project" (docs-project.ts:310). Matching only the first silently scored
- * every project-source abstention as a valid answer — and project-source is the MAJORITY of
- * what worker:apis asks (13 of 17 calls in run 15's fatal task), so that one missing word
- * would have put the wrong denominator under the whole termination diagnostic.
- */
-const UNCLEAR = /unclear from this (package|project)/i;
 /**
  * Append one record to the JSONL sink named by `PI_TASK_TYPEONLY_LOG`, if set.
  *
@@ -61,7 +53,7 @@ export function logDocsAnswer(rec, getEnv = k => process.env[k]) {
     const full = {
         at: new Date().toISOString(),
         ...rec,
-        unclear: UNCLEAR.test(rec.answer)
+        unclear: isAbstention(rec.answer)
     };
     try {
         fs.appendFileSync(sink, `${JSON.stringify(full)}\n`, 'utf8');

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

@@ -0,0 +1,91 @@
+/**
+ * How a worker child DIED — the one classification of a finished `runWorker`
+ * result, and the single place its precedence is written down.
+ *
+ * Why this module exists. `RunWorkerResult` reports each kill cause as its own
+ * optional field (`loopHit`, `timedOut`, `stalled`, `commandTimedOut`,
+ * `streamStalled`, `leakedToolCall`, `aborted`, `exitCode`), and every kill path
+ * ALSO sets `aborted` and a non-zero exit — killProc flips those on every route
+ * out. So a consumer cannot read the fields in any order it likes: the specific
+ * causes must be matched before the generic `aborted`/`exitCode` ones, or a dead
+ * backend is reported to the user as "you cancelled".
+ *
+ * That rule used to live as prose in three doc comments and as the source order
+ * of three hand-written ladders (`classifyEnforceChildFailure`,
+ * `classifyResearchWorker`, and the gate's own reading). Three copies of an
+ * ordering is three chances to drift, and it had already drifted: `streamStalled`
+ * was added to the result and to `finalAttemptFailed`, but the enforce ladder
+ * never grew an arm for it, so an enforcement child killed for a hung model
+ * stream fell all the way through to `if (aborted) return USER_CANCELLED` — the
+ * exact mislabel the comment above that line warns against.
+ *
+ * The fix is to make the order data. `FAILURE_RULES` is ordered, the first
+ * matching row wins, and consumers `switch` on the resulting `kind` instead of
+ * re-deriving the ladder. A new kill cause is one row here plus a compile error
+ * in every consumer that has not handled it — which is what makes the drift that
+ * caused the bug impossible rather than merely fixed.
+ */
+import type { LoopHit } from '../task/loop-detector.js';
+/**
+ * The subset of a finished child result this classification reads.
+ *
+ * Structural on purpose: `runWorker` returns a superset, and
+ * `EnforceChildResult` is a hand-written narrowing of the same shape. Typing the
+ * input as what is actually READ lets both pass without either importing the
+ * other's interface.
+ */
+export interface WorkerFailureInput {
+    exitCode: number;
+    aborted: boolean;
+    timedOut?: boolean;
+    stalled?: boolean;
+    loopHit?: unknown;
+    leakedToolCall?: unknown;
+    commandTimedOut?: {
+        toolName: string;
+        timeoutMs: number;
+    };
+    streamStalled?: {
+        idleMs: number;
+    };
+}
+/**
+ * Why the child died, or `undefined` when it finished under its own power.
+ *
+ * Note what is NOT here: an empty answer, and a reported `modelError` on a run
+ * that still produced text. Neither is a kill — whether they count as a failure
+ * is the consumer's policy (research accepts a genuinely empty section; the gate
+ * does not), so folding them in would move a decision out of the module that
+ * owns it.
+ */
+export type WorkerFailure = {
+    kind: 'stalled';
+} | {
+    kind: 'command-timeout';
+    toolName: string;
+    timeoutMs: number;
+} | {
+    kind: 'stream-stall';
+    idleMs: number;
+} | {
+    kind: 'worker-timeout';
+} | {
+    kind: 'loop';
+    hit: LoopHit;
+} | {
+    kind: 'leaked-tool-call';
+    text: string;
+} | {
+    kind: 'aborted';
+} | {
+    kind: 'exit';
+    code: number;
+};
+/** The `kind` of every row, for exhaustiveness checks in consumers. */
+export type WorkerFailureKind = WorkerFailure['kind'];
+/**
+ * Classify a finished child. Returns `undefined` when nothing killed it —
+ * which is not the same as "it answered": the text may still be empty, and that
+ * judgement belongs to the caller.
+ */
+export declare function classifyWorkerFailure(r: WorkerFailureInput): WorkerFailure | undefined;

package/dist/workers/worker-failure.js

@@ -0,0 +1,82 @@
+/**
+ * How a worker child DIED — the one classification of a finished `runWorker`
+ * result, and the single place its precedence is written down.
+ *
+ * Why this module exists. `RunWorkerResult` reports each kill cause as its own
+ * optional field (`loopHit`, `timedOut`, `stalled`, `commandTimedOut`,
+ * `streamStalled`, `leakedToolCall`, `aborted`, `exitCode`), and every kill path
+ * ALSO sets `aborted` and a non-zero exit — killProc flips those on every route
+ * out. So a consumer cannot read the fields in any order it likes: the specific
+ * causes must be matched before the generic `aborted`/`exitCode` ones, or a dead
+ * backend is reported to the user as "you cancelled".
+ *
+ * That rule used to live as prose in three doc comments and as the source order
+ * of three hand-written ladders (`classifyEnforceChildFailure`,
+ * `classifyResearchWorker`, and the gate's own reading). Three copies of an
+ * ordering is three chances to drift, and it had already drifted: `streamStalled`
+ * was added to the result and to `finalAttemptFailed`, but the enforce ladder
+ * never grew an arm for it, so an enforcement child killed for a hung model
+ * stream fell all the way through to `if (aborted) return USER_CANCELLED` — the
+ * exact mislabel the comment above that line warns against.
+ *
+ * The fix is to make the order data. `FAILURE_RULES` is ordered, the first
+ * matching row wins, and consumers `switch` on the resulting `kind` instead of
+ * re-deriving the ladder. A new kill cause is one row here plus a compile error
+ * in every consumer that has not handled it — which is what makes the drift that
+ * caused the bug impossible rather than merely fixed.
+ */
+/**
+ * The ordered ladder. FIRST MATCH WINS — row order IS the precedence, and it is
+ * the only statement of it in the codebase.
+ *
+ * The order, and why:
+ *
+ *  1. `stalled` — no output AND the model endpoint did not answer a probe. The
+ *     most specific diagnosis there is, and the one most easily lost: the kill
+ *     aborts, so anything checked after `aborted` never sees it.
+ *  2. `command-timeout` — a watchdog kill naming the tool call that hung. Also
+ *     aborts. Before the wall-clock timeout because it is the narrower cause
+ *     (the two cannot be confused: a watchdog kill leaves the worker's own
+ *     timeout flag false).
+ *  3. `stream-stall` — a watchdog kill for a model stream that went silent while
+ *     no tool was running. Sits next to `command-timeout` because it is the same
+ *     class of event: a watchdog, not the model, ended the attempt.
+ *  4. `worker-timeout` — the wall-clock backstop.
+ *  5. `loop` — killed for repeating one tool call past threshold. After the
+ *     timeouts, matching the enforce ladder this replaces; in practice the two
+ *     cannot both fire, since a loop kill stops the attempt before its own timer
+ *     can expire.
+ *  6. `leaked-tool-call` — the model wrote a call as prose instead of invoking
+ *     it. Only ever set on an otherwise clean run.
+ *  7. `aborted` — no specific cause survived, so this really is a cancel.
+ *  8. `exit` — a plain non-zero exit with no kill behind it: a crash.
+ */
+const FAILURE_RULES = [
+    r => (r.stalled === true ? { kind: 'stalled' } : null),
+    r => r.commandTimedOut ?
+        {
+            kind: 'command-timeout',
+            toolName: r.commandTimedOut.toolName,
+            timeoutMs: r.commandTimedOut.timeoutMs
+        }
+        : null,
+    r => (r.streamStalled ? { kind: 'stream-stall', idleMs: r.streamStalled.idleMs } : null),
+    r => (r.timedOut === true ? { kind: 'worker-timeout' } : null),
+    r => (r.loopHit ? { kind: 'loop', hit: r.loopHit } : null),
+    r => (r.leakedToolCall ? { kind: 'leaked-tool-call', text: String(r.leakedToolCall) } : null),
+    r => (r.aborted ? { kind: 'aborted' } : null),
+    r => (r.exitCode !== 0 ? { kind: 'exit', code: r.exitCode } : null)
+];
+/**
+ * Classify a finished child. Returns `undefined` when nothing killed it —
+ * which is not the same as "it answered": the text may still be empty, and that
+ * judgement belongs to the caller.
+ */
+export function classifyWorkerFailure(r) {
+    for (const rule of FAILURE_RULES) {
+        const hit = rule(r);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}

package/package.json

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