@mjasnikovs/pi-task 0.38.22 → 0.38.24

package/dist/workers/session-hint.js

@@ -0,0 +1,82 @@
+/**
+ * A one-line startup hint in the TUI, and the whole widget lifetime around it.
+ *
+ * WHY IT IS ONE MODULE. Two hints exist (brave-warning, reasoning-warning) and
+ * both had written the same ritual out: the `session_start` subscription, the
+ * TUI gate, the `setWidget` in a try/catch, the `onTerminalInput` that clears on
+ * the first keystroke, the unsubscribe, and the swallow for a stale ctx — down
+ * to a byte-identical comment. Two adapters is a real seam, so the ritual lives
+ * here once and each hint supplies only its `compose`.
+ *
+ * The REFINE half is why this is not just deduplication. A hint may learn
+ * something after it has painted (the reasoning hint probes the model's server),
+ * and the rule that a refinement must never repaint a widget the user already
+ * dismissed lived in one closure variable in one of the two files. It is now a
+ * property of this module, asserted once.
+ */
+/**
+ * Register one startup hint.
+ *
+ * `compose` is the seam: it runs at `session_start` inside the TUI gate and
+ * returns the hint, or null to say nothing at all. Everything it returns is
+ * text; nothing about widgets, keystrokes or teardown reaches it.
+ */
+export function registerSessionHint(pi, key, compose) {
+    pi.on('session_start', (_event, ctx) => {
+        // Terminal-only hint: needs an interactive TUI to render and to catch the
+        // keystroke that dismisses it.
+        if (ctx.mode !== 'tui')
+            return;
+        const hint = compose(ctx);
+        if (hint === null)
+            return;
+        let unsubscribe = null;
+        let cleared = false;
+        let painted = false;
+        const clear = () => {
+            cleared = true;
+            try {
+                ctx.ui.setWidget(key, undefined);
+            }
+            catch {
+                /* stale ctx after a session switch — nothing to clear */
+            }
+            unsubscribe?.();
+            unsubscribe = null;
+        };
+        const render = (text) => {
+            try {
+                ctx.ui.setWidget(key, [ctx.ui.theme.fg('warning', text)]);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        // Handled BEFORE the paint can bail. `compose` builds this promise
+        // eagerly — the reasoning hint kicks its probe off inside it — so a
+        // rejection with the handler attached later is an unhandled rejection on
+        // exactly the path the try/catch around `setWidget` exists for: a stale
+        // ctx after a session switch. `refine`'s contract says a rejection leaves
+        // the first line standing, and that has to hold when there is no first
+        // line either.
+        if (hint.refine !== undefined) {
+            void hint.refine
+                .then(text => {
+                if (cleared || !painted || text === null)
+                    return;
+                render(text);
+            })
+                .catch(() => { });
+        }
+        painted = render(hint.text);
+        if (!painted)
+            return;
+        // Disappear on any interaction — the first raw keystroke clears it.
+        // Returning undefined leaves the input untouched (we only observe it).
+        unsubscribe = ctx.ui.onTerminalInput(() => {
+            clear();
+            return undefined;
+        });
+    });
+}

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

@@ -26,6 +26,7 @@
  * caused the bug impossible rather than merely fixed.
  */
 import type { LoopHit } from '../task/loop-detector.js';
+import type { WorkerKillId } from './worker-kill.js';
 /**
  * The subset of a finished child result this classification reads.
  *
@@ -83,6 +84,39 @@ export type WorkerFailure = {
 };
 /** The `kind` of every row, for exhaustiveness checks in consumers. */
 export type WorkerFailureKind = WorkerFailure['kind'];
+/**
+ * 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.
+ */
+export declare const FAILURE_RULES: ReadonlyArray<{
+    /** The roster id this row matches. `worker-kill.test.ts` checks the sequence
+     *  against `FAILURE_ORDER`, so a reordering or an omission is a test failure
+     *  rather than a silently different precedence. */
+    id: WorkerKillId;
+    match: (r: WorkerFailureInput) => WorkerFailure | 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

package/dist/workers/worker-failure.js

@@ -25,6 +25,8 @@
  * in every consumer that has not handled it — which is what makes the drift that
  * caused the bug impossible rather than merely fixed.
  */
+const _kindsAreKills = true;
+void _kindsAreKills;
 /**
  * The ordered ladder. FIRST MATCH WINS — row order IS the precedence, and it is
  * the only statement of it in the codebase.
@@ -51,21 +53,30 @@
  *  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)
+export const FAILURE_RULES = [
+    { id: 'stalled', match: r => (r.stalled === true ? { kind: 'stalled' } : null) },
+    {
+        id: 'command-timeout',
+        match: r => r.commandTimedOut ?
+            {
+                kind: 'command-timeout',
+                toolName: r.commandTimedOut.toolName,
+                timeoutMs: r.commandTimedOut.timeoutMs
+            }
+            : null
+    },
+    {
+        id: 'stream-stall',
+        match: r => r.streamStalled ? { kind: 'stream-stall', idleMs: r.streamStalled.idleMs } : null
+    },
+    { id: 'worker-timeout', match: r => (r.timedOut === true ? { kind: 'worker-timeout' } : null) },
+    { id: 'loop', match: r => (r.loopHit ? { kind: 'loop', hit: r.loopHit } : null) },
+    {
+        id: 'leaked-tool-call',
+        match: r => r.leakedToolCall ? { kind: 'leaked-tool-call', text: String(r.leakedToolCall) } : null
+    },
+    { id: 'aborted', match: r => (r.aborted ? { kind: 'aborted' } : null) },
+    { id: 'exit', match: r => (r.exitCode !== 0 ? { kind: 'exit', code: r.exitCode } : null) }
 ];
 /**
  * Classify a finished child. Returns `undefined` when nothing killed it —
@@ -74,7 +85,7 @@ const FAILURE_RULES = [
  */
 export function classifyWorkerFailure(r) {
     for (const rule of FAILURE_RULES) {
-        const hit = rule(r);
+        const hit = rule.match(r);
         if (hit)
             return hit;
     }

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

@@ -0,0 +1,84 @@
+/**
+ * The ROSTER of ways a worker child can die, and what each one implies.
+ *
+ * WHY IT EXISTS. One kill cause was named in six unlinked places: a
+ * `RunWorkerInput` guard option, a `RunWorkerResult` field, the
+ * `WorkerRestartReason` union, a `RESTART_RULES` row, the `CARRY_FORWARD_REASONS`
+ * set, and a `FAILURE_RULES` row. Adding one meant six coordinated edits, and
+ * only two of them failed to compile if you skipped one. That is not
+ * hypothetical: `worker-failure.ts`'s own header records the bug it cost —
+ * *"`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`"*. That fix closed the READER side. This closes the author
+ * side.
+ *
+ * WHAT IS AND IS NOT UNIFIED. The roster is one table. The two ORDERINGS stay
+ * two, because they genuinely disagree and each says so in its own prose: the
+ * restart ladder puts `loop` first (its hint is the most specific thing to tell a
+ * re-spawn), and the failure ladder puts `stalled` first (the diagnosis most
+ * easily lost behind the `aborted` every kill path sets). Folding two
+ * precedences into one row type would need an escape hatch per row — the same
+ * objection that got a `WriteGuard` row table rejected. 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:
+ * `connection-error` is restartable but is reported as a `modelError`, never as a
+ * kill; `stalled`, `aborted` and `exit` end an attempt outright and no hint would
+ * help.
+ */
+/** 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 interface WorkerKill {
+    id: WorkerKillId;
+    /**
+     * The `RunWorkerResult` field that reports this cause on the FINAL attempt,
+     * or null when the cause never reaches the result under its own name
+     * (`connection-error` arrives as `modelError`; `aborted` and `exit` are the
+     * generic fields every kill path also sets).
+     *
+     * A string rather than `keyof RunWorkerResult` so this module stays free of
+     * pi-worker-core's import graph; `worker-kill.test.ts` checks it against the
+     * real interface.
+     */
+    resultField: string | null;
+    /**
+     * Is a killed attempt's partial output worth carrying into the next one?
+     *
+     * A clock kill, a hung tool, an idle stream and a dropped socket all discard
+     * work the model genuinely did. A loop kill and a leaked tool call do not —
+     * the first is by definition the same call repeated, the second is malformed
+     * protocol text, and replaying either would feed the failure back to itself.
+     */
+    carryForward: boolean;
+    /** Does the restart ladder have a rule for this cause? */
+    restartable: boolean;
+    /** Does this cause reach a consumer as a `WorkerFailure`? */
+    reported: 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;
+/**
+ * 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.
+ */
+export declare const RESTART_ORDER: readonly ["loop", "command-timeout", "stream-stall", "worker-timeout", "connection-error", "leaked-tool-call"];
+/**
+ * The failure ladder's precedence, as ids. `FAILURE_RULES` must be exactly this,
+ * in this order.
+ *
+ * DIFFERENT from `RESTART_ORDER`, deliberately. Every kill path also sets
+ * `aborted` and a non-zero exit, so the specific causes must all be matched
+ * before the two generic ones or a dead backend is reported as "you cancelled".
+ * `stalled` leads because it is both the most specific diagnosis and the one most
+ * easily lost.
+ */
+export declare const FAILURE_ORDER: readonly ["stalled", "command-timeout", "stream-stall", "worker-timeout", "loop", "leaked-tool-call", "aborted", "exit"];
+/** The causes whose partial output is worth keeping. Derived, never hand-kept. */
+export declare const CARRY_FORWARD_IDS: ReadonlySet<WorkerKillId>;

package/dist/workers/worker-kill.js

@@ -0,0 +1,124 @@
+/**
+ * The ROSTER of ways a worker child can die, and what each one implies.
+ *
+ * WHY IT EXISTS. One kill cause was named in six unlinked places: a
+ * `RunWorkerInput` guard option, a `RunWorkerResult` field, the
+ * `WorkerRestartReason` union, a `RESTART_RULES` row, the `CARRY_FORWARD_REASONS`
+ * set, and a `FAILURE_RULES` row. Adding one meant six coordinated edits, and
+ * only two of them failed to compile if you skipped one. That is not
+ * hypothetical: `worker-failure.ts`'s own header records the bug it cost —
+ * *"`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`"*. That fix closed the READER side. This closes the author
+ * side.
+ *
+ * WHAT IS AND IS NOT UNIFIED. The roster is one table. The two ORDERINGS stay
+ * two, because they genuinely disagree and each says so in its own prose: the
+ * restart ladder puts `loop` first (its hint is the most specific thing to tell a
+ * re-spawn), and the failure ladder puts `stalled` first (the diagnosis most
+ * easily lost behind the `aborted` every kill path sets). Folding two
+ * precedences into one row type would need an escape hatch per row — the same
+ * objection that got a `WriteGuard` row table rejected. 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:
+ * `connection-error` is restartable but is reported as a `modelError`, never as a
+ * kill; `stalled`, `aborted` and `exit` end an attempt outright and no hint would
+ * help.
+ */
+export const WORKER_KILLS = [
+    {
+        id: 'stalled',
+        resultField: 'stalled',
+        carryForward: false,
+        restartable: false,
+        reported: true
+    },
+    {
+        id: 'command-timeout',
+        resultField: 'commandTimedOut',
+        carryForward: true,
+        restartable: true,
+        reported: true
+    },
+    {
+        id: 'stream-stall',
+        resultField: 'streamStalled',
+        carryForward: true,
+        restartable: true,
+        reported: true
+    },
+    {
+        id: 'worker-timeout',
+        resultField: 'timedOut',
+        carryForward: true,
+        restartable: true,
+        reported: true
+    },
+    {
+        id: 'connection-error',
+        resultField: null,
+        carryForward: true,
+        restartable: true,
+        reported: false
+    },
+    { id: 'loop', resultField: 'loopHit', carryForward: false, restartable: true, reported: true },
+    {
+        id: 'leaked-tool-call',
+        resultField: 'leakedToolCall',
+        carryForward: false,
+        restartable: true,
+        reported: true
+    },
+    { id: 'aborted', resultField: null, carryForward: false, restartable: false, reported: true },
+    { id: 'exit', resultField: null, carryForward: false, restartable: false, reported: true }
+];
+/** 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);
+}
+/**
+ * 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.
+ */
+export const RESTART_ORDER = [
+    'loop',
+    'command-timeout',
+    'stream-stall',
+    'worker-timeout',
+    'connection-error',
+    'leaked-tool-call'
+    // `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
+    // let `noteRestart('aborted')` compile for a cause the restart ladder has no
+    // rule for. `satisfies` keeps the membership check without the widening.
+];
+/**
+ * The failure ladder's precedence, as ids. `FAILURE_RULES` must be exactly this,
+ * in this order.
+ *
+ * DIFFERENT from `RESTART_ORDER`, deliberately. Every kill path also sets
+ * `aborted` and a non-zero exit, so the specific causes must all be matched
+ * before the two generic ones or a dead backend is reported as "you cancelled".
+ * `stalled` leads because it is both the most specific diagnosis and the one most
+ * easily lost.
+ */
+export const FAILURE_ORDER = [
+    'stalled',
+    'command-timeout',
+    'stream-stall',
+    'worker-timeout',
+    'loop',
+    'leaked-tool-call',
+    'aborted',
+    'exit'
+];
+/** The causes whose partial output is worth keeping. Derived, never hand-kept. */
+export const CARRY_FORWARD_IDS = new Set(WORKER_KILLS.filter(k => k.carryForward).map(k => k.id));

package/package.json

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

package/dist/task/reasoning-groups.d.ts

@@ -1,36 +0,0 @@
-/**
- * Child NAME → reasoning group, for every child that goes through
- * `runPhaseChild` / `runPlanningChild`.
- *
- * WHY KEYED ON THE NAME
- * ---------------------
- * The name is the only identifier in scope at all three spawn paths (phases,
- * /task-auto planning, /task-plan), it is what the loader and the debug trail
- * already print, and it is the one thing a reader can check against the phase
- * list without following the call graph. Threading a group parameter through
- * `PhaseDeps` / `AutoDeps` instead would touch both orchestrators' dep bags to
- * express something the call site already says out loud.
- *
- * AN UNMAPPED NAME IS A BUILD FAILURE, not a silent `inherit`.
- * `reasoning-groups.test.ts` scans every literal child name in src/ and fails if
- * it is missing here. A defaulting lookup would let a phase added next year opt
- * itself out of a measured setting without anyone deciding to — which is exactly
- * how `/no_think` ended up applied to eight prompts and read by none of them.
- *
- * The gate, research and extraction groups are NOT here: those children reach the
- * model through `runWorker` / `focusedChildArgs`, where the group is a property
- * of the call site rather than of a name, and is passed directly.
- */
-import type { ReasoningGroup } from '../config/reasoning.js';
-export declare const REASONING_GROUP_BY_CHILD: Readonly<Record<string, ReasoningGroup>>;
-/**
- * The group a named child belongs to.
- *
- * Returns `undefined` for a name the table does not know, and the CALLER decides
- * what that means. `runPhaseChild` treats it as `inherit` — a child that reaches
- * the model with today's argv is always safe — while the test treats it as a
- * failure. That split is deliberate: the guard belongs at build time, where
- * someone can fix it, not at run time, where it would abort a user's task over a
- * missing table row.
- */
-export declare function reasoningGroupForChild(name: string): ReasoningGroup | undefined;

package/dist/task/reasoning-groups.js

@@ -1,36 +0,0 @@
-export const REASONING_GROUP_BY_CHILD = {
-    // ── phase: task/phases.ts + task/title-label.ts ──────────────────────────
-    refine: 'phase',
-    'verify-tooling': 'phase',
-    'grill-auto': 'phase',
-    'grill-gen': 'phase',
-    compose: 'phase',
-    critique: 'phase',
-    'critique-triage': 'phase',
-    'compress-label': 'phase',
-    // ── planning: task/auto-orchestrator.ts ──────────────────────────────────
-    'clarify-triage': 'planning',
-    'auto-clarify': 'planning',
-    'auto-decompose': 'planning',
-    'requirement-extract': 'planning',
-    'decompose-coverage': 'planning',
-    'coverage-map': 'planning',
-    'contract-extract': 'planning',
-    'launch-extract': 'planning',
-    // ── plan: task/plan-orchestrator.ts ──────────────────────────────────────
-    'plan-question': 'plan',
-    'plan-answer': 'plan'
-};
-/**
- * The group a named child belongs to.
- *
- * Returns `undefined` for a name the table does not know, and the CALLER decides
- * what that means. `runPhaseChild` treats it as `inherit` — a child that reaches
- * the model with today's argv is always safe — while the test treats it as a
- * failure. That split is deliberate: the guard belongs at build time, where
- * someone can fix it, not at run time, where it would abort a user's task over a
- * missing table row.
- */
-export function reasoningGroupForChild(name) {
-    return REASONING_GROUP_BY_CHILD[name];
-}