@crouton-kit/crouter 0.3.28 → 0.3.29

package/dist/core/view/contract.d.ts

@@ -0,0 +1,171 @@
+import type { Draw, Rect } from '../tui/draw.js';
+export interface ViewManifest {
+    id: string;
+    title: string;
+    subtitle?: string;
+    description: string;
+    refreshMs?: number;
+}
+/** Severity of a {@link HostSignals.setBanner} banner — drives glyph + hue and
+ *  the derived state chip (error→blocked, action→attention, info→neutral). */
+export type BannerLevel = 'info' | 'action' | 'error';
+export interface Banner {
+    msg: string;
+    level: BannerLevel;
+}
+/** Optional host context passed to the text presenter's dump on the piped path. */
+export interface DumpContext {
+    banner: Banner | null;
+}
+/** Semantic chrome signals the core raises; each target renders them in its own
+ *  idiom (TUI footer/banner/title-chip vs web status line/alert bar/pill). */
+export interface HostSignals {
+    setStatus(msg: string | null): void;
+    setBanner(msg: string, level: BannerLevel): void;
+    clearBanner(): void;
+    setSubtitle(s: string | null): void;
+    /** Interaction-mode chip override (compose/react); null returns to derived. */
+    setMode(mode: string | null): void;
+    /** TUI: leave the pane; web: no-op/close tab. */
+    quit(): void;
+}
+/** The host-tracked chrome record both targets render. */
+export interface ChromeState {
+    status: string | null;
+    banner: Banner | null;
+    subtitle: string | null;
+    mode: string | null;
+    busy: boolean;
+    loaded: boolean;
+    lastRefresh: number;
+}
+/** A transport-agnostic request descriptor the host fulfills. The core never
+ *  executes anything itself — it describes WHAT to run/read/fetch and the
+ *  host's Transport decides HOW (local exec today, a cloud endpoint later). */
+export type SourceRequest = {
+    kind: 'exec';
+    bin: string;
+    args: string[];
+    cwd?: string;
+    stdin?: string;
+} | {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'http';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+};
+export interface RawResponse {
+    ok: boolean;
+    exitCode?: number;
+    status?: number;
+    stdout: string;
+    stderr: string;
+}
+/** Typed error with a render-ready display. Presenters render `display`
+ *  VERBATIM and never branch on `kind` (the view-internal taxonomy). */
+export interface SourceError {
+    kind: string;
+    display: {
+        headline: string;
+        explanation: string;
+        nextStep: string;
+        level: BannerLevel;
+        blocking: boolean;
+    };
+}
+export type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: SourceError;
+};
+/** A READ: declarative descriptor + pure parse + optional cadence. Resolved by
+ *  the host through its Transport via `ctx.resolve(source, args)`. */
+export interface Source<T, A = void> {
+    id: string;
+    request(args: A): SourceRequest;
+    parse(raw: RawResponse): Result<T>;
+    refreshMs?: number;
+}
+/** A WRITE: same {request, parse} pair, no cadence — invoked by an intent via
+ *  `ctx.execute(command, args)`. */
+export interface Command<T, A = void> {
+    id: string;
+    request(args: A): SourceRequest;
+    parse(raw: RawResponse): Result<T>;
+}
+/** A semantic action. State updates are immutable via `ctx.set`; async effects
+ *  (transport calls) live in the same handler — a thunk, not a pure reducer.
+ *  Sync intents call `ctx.set` once; async intents `await ctx.resolve/execute`
+ *  between `set`s. The host serializes async intents in its single-flight lane. */
+export type Intent<S, P = void> = (ctx: IntentCtx<S>, payload: P) => void | Promise<void>;
+export interface IntentCtx<S> {
+    /** Snapshot of state at read time. */
+    readonly state: S;
+    /** Immutable update → triggers a re-render. Value or (prev)=>next fn. */
+    set(next: S | ((prev: S) => S)): void;
+    /** Run a READ source through the host's transport → typed Result. */
+    resolve<T, A>(source: Source<T, A>, args?: A): Promise<Result<T>>;
+    /** Run a WRITE command through the host's transport → typed Result. */
+    execute<T, A>(command: Command<T, A>, args?: A): Promise<Result<T>>;
+    /** Semantic chrome signals (status/banner/subtitle/mode/quit). */
+    signal: HostSignals;
+    /** Chain another intent by name. */
+    dispatch(intent: string, payload?: unknown): Promise<void>;
+}
+export interface ViewCore<S = unknown> {
+    manifest: ViewManifest;
+    /** Cheap, synchronous initial state. No fetch, no screen. The host mounts,
+     *  paints a loading frame, then dispatches the first 'refresh'. */
+    init(opts: Readonly<Record<string, string>>): S;
+    /** Declarative READ dependencies the host resolves through the transport. */
+    sources?: Record<string, Source<any, any>>;
+    /** WRITE descriptors invoked from intents. */
+    commands?: Record<string, Command<any, any>>;
+    /** Semantic actions. Both presenters emit these. */
+    intents: Record<string, Intent<S, any>>;
+}
+export interface KeyHint {
+    keys: string;
+    label: string;
+}
+export type KeyBinding<S> = {
+    keys: string[];
+    intent: string;
+    payload?: (state: S) => unknown;
+    when?: (state: S) => boolean;
+    hint?: KeyHint;
+} | {
+    /** Text-capture binding: while `when(state)` is true the host runs a
+     *  built-in line-edit buffer over raw printable/backspace keys and
+     *  dispatches `capture` with the next draft value on each edit. */
+    capture: string;
+    when: (state: S) => boolean;
+    hint?: KeyHint;
+};
+export interface TuiPresenter<S = unknown> {
+    /** Pure read of state, paints via draw.*; never ANSI. */
+    render(state: S, draw: Draw, content: Rect): void;
+    /** Pure input→intent mapping. */
+    keymap: KeyBinding<S>[];
+}
+/** Props handed to web.jsx's default-export React component. The component is a
+ *  pure function of state; DOM events call `dispatch`. (Typed loosely here so
+ *  the core contract carries no React type dependency.) */
+export interface ViewProps<S = unknown> {
+    state: S;
+    dispatch: (intent: string, payload?: unknown) => void;
+    chrome: ChromeState;
+}
+export type WebPresenter<S = unknown> = (props: ViewProps<S>) => unknown;
+export interface TextPresenter<S = unknown> {
+    /** Static text for the non-TTY / piped path. Snapshot of current state. */
+    dump(state: S, ctx?: DumpContext): string;
+}
+export declare function ok<T>(data: T): Result<T>;
+export declare function fail<T = never>(error: SourceError): Result<T>;

package/dist/core/view/contract.js

@@ -0,0 +1,23 @@
+// contract.ts — the dual-target view contract (portable core + thin presenters).
+//
+// One view definition renders to two targets — the tmux TUI (`crtr view run`)
+// and a React+Tailwind web page (`crtr view serve`) — from ONE portable core.
+// On disk a view is a directory of up to four files, each loaded only by the
+// runtime that can execute it:
+//
+//   <view>/
+//     core.mjs   REQUIRED  manifest · init · sources · commands · intents.
+//                          Runs in BOTH Node and the browser. Imports NOTHING —
+//                          no `node:*`, no crtr. Pure JS + the injected ctx.
+//     tui.mjs    optional  render(state, draw, content) + keymap   (Node only)
+//     web.jsx    optional  default React component (Tailwind)      (browser only)
+//     text.mjs   optional  dump(state, ctx) for the piped path     (Node only)
+//
+// The invariant: ALL state + ALL behavior live in the core; presenters are pure
+// reads of state that emit named intents. It is enforced structurally — only
+// `core.mjs` ever sees a mutating `IntentCtx`; presenters receive `state` plus a
+// `dispatch`/`keymap` that names intents, so a presenter has no path to data or
+// logic.
+// ── Result helpers (re-exported for view authors' convenience in tests) ─────
+export function ok(data) { return { ok: true, data }; }
+export function fail(error) { return { ok: false, error }; }

package/dist/core/view/loader.d.ts

@@ -0,0 +1,31 @@
+import type { ViewCore, TuiPresenter, TextPresenter } from './contract.js';
+export interface ResolvedView {
+    id: string;
+    dir: string;
+    scope: 'project' | 'user' | 'builtin';
+    core: string;
+    tui: string | null;
+    web: string | null;
+    text: string | null;
+}
+/** Scope search project→user→builtin; first hit wins. null if no scope holds a
+ *  `<name>/core.mjs`. */
+export declare function resolveView(name: string): ResolvedView | null;
+/** Find a directory named `name` across scopes even when it holds no core.mjs —
+ *  lets a caller distinguish "no such view" from "a dir that isn't a valid view"
+ *  (e.g. a pre-contract `view.mjs`-only dir) and name the contract in the error. */
+export declare function findViewDir(name: string): string | null;
+/** Enumerate every resolvable core-shaped view across scopes (first scope wins
+ *  per id). Targets per view are derivable from the tui/web/text fields. */
+export declare function listViews(): ResolvedView[];
+/** Import + validate the portable core. Throws a guided error if malformed. */
+export declare function loadCore(r: ResolvedView): Promise<ViewCore>;
+/** Import + validate the TUI presenter. Call requireTui first. */
+export declare function loadTui(r: ResolvedView): Promise<TuiPresenter>;
+/** Import the text presenter if present; null otherwise (the host synthesizes a
+ *  generic one-line dump when a view ships no text.mjs). */
+export declare function loadText(r: ResolvedView): Promise<TextPresenter | null>;
+/** Per-host presenter validation: `view run` requires a TUI presenter. */
+export declare function requireTui(r: ResolvedView): void;
+/** Per-host presenter validation: `view serve` requires a web presenter. */
+export declare function requireWeb(r: ResolvedView): void;

package/dist/core/view/loader.js

@@ -0,0 +1,188 @@
+// loader.ts — resolve + load dual-target (core.mjs) views across scopes.
+//
+// A view = a directory containing `core.mjs` (the portable core). Up to three
+// presenter files sit beside it: `tui.mjs` (Node), `web.jsx`/`web.tsx` (browser,
+// via Vite — NEVER Node-imported), `text.mjs` (Node, piped path). Targets are
+// derived from which presenter files exist — no manifest field.
+//
+// Resolution order: project → user → builtin, first hit wins (scope.ts
+// viewsDir). Node-side loads are plain `import(pathToFileURL())` — no
+// transpile, no bundle. A directory without a `core.mjs` is not a view.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { viewsDir } from '../scope.js';
+import { InputError } from '../io.js';
+const SCOPE_ORDER = ['project', 'user', 'builtin'];
+function probe(dir, scope, id) {
+    const core = join(dir, 'core.mjs');
+    if (!existsSync(core))
+        return null;
+    const tui = join(dir, 'tui.mjs');
+    const webJsx = join(dir, 'web.jsx');
+    const webTsx = join(dir, 'web.tsx');
+    const text = join(dir, 'text.mjs');
+    return {
+        id, dir, scope, core,
+        tui: existsSync(tui) ? tui : null,
+        web: existsSync(webJsx) ? webJsx : existsSync(webTsx) ? webTsx : null,
+        text: existsSync(text) ? text : null,
+    };
+}
+/** Scope search project→user→builtin; first hit wins. null if no scope holds a
+ *  `<name>/core.mjs`. */
+export function resolveView(name) {
+    for (const scope of SCOPE_ORDER) {
+        const root = viewsDir(scope);
+        if (!root)
+            continue;
+        const r = probe(join(root, name), scope, name);
+        if (r)
+            return r;
+    }
+    return null;
+}
+/** Find a directory named `name` across scopes even when it holds no core.mjs —
+ *  lets a caller distinguish "no such view" from "a dir that isn't a valid view"
+ *  (e.g. a pre-contract `view.mjs`-only dir) and name the contract in the error. */
+export function findViewDir(name) {
+    for (const scope of SCOPE_ORDER) {
+        const root = viewsDir(scope);
+        if (!root)
+            continue;
+        const dir = join(root, name);
+        try {
+            if (statSync(dir).isDirectory())
+                return dir;
+        }
+        catch { /* not here */ }
+    }
+    return null;
+}
+/** Enumerate every resolvable core-shaped view across scopes (first scope wins
+ *  per id). Targets per view are derivable from the tui/web/text fields. */
+export function listViews() {
+    const seen = new Set();
+    const out = [];
+    for (const scope of SCOPE_ORDER) {
+        const root = viewsDir(scope);
+        if (!root || !existsSync(root))
+            continue;
+        let names;
+        try {
+            names = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names.sort()) {
+            if (seen.has(name))
+                continue; // first scope wins
+            const dir = join(root, name);
+            let isDir = false;
+            try {
+                isDir = statSync(dir).isDirectory();
+            }
+            catch {
+                isDir = false;
+            }
+            if (!isDir)
+                continue;
+            const r = probe(dir, scope, name);
+            if (!r)
+                continue;
+            seen.add(name);
+            out.push(r);
+        }
+    }
+    return out;
+}
+/** Import + validate the portable core. Throws a guided error if malformed. */
+export async function loadCore(r) {
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(r.core).href));
+    }
+    catch (e) {
+        throw guided(r, 'core.mjs', `failed to import: ${errText(e)}`);
+    }
+    const c = mod['default'];
+    if (!c || typeof c !== 'object')
+        throw guided(r, 'core.mjs', 'no default export that is a ViewCore object');
+    const m = c.manifest;
+    if (!m || typeof m.id !== 'string' || typeof m.title !== 'string') {
+        throw guided(r, 'core.mjs', 'manifest.id and manifest.title must be strings');
+    }
+    if (typeof c.init !== 'function')
+        throw guided(r, 'core.mjs', 'init() is required');
+    if (!c.intents || typeof c.intents !== 'object')
+        throw guided(r, 'core.mjs', 'intents must be an object of intent functions');
+    return c;
+}
+/** Import + validate the TUI presenter. Call requireTui first. */
+export async function loadTui(r) {
+    if (!r.tui)
+        throw notTarget(r, 'tui');
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(r.tui).href));
+    }
+    catch (e) {
+        throw guided(r, 'tui.mjs', `failed to import: ${errText(e)}`);
+    }
+    // Accept named exports { render, keymap } or a default-exported object.
+    const candidate = (typeof mod['render'] === 'function' ? mod : mod['default']);
+    if (!candidate || typeof candidate.render !== 'function')
+        throw guided(r, 'tui.mjs', 'render(state, draw, content) is required');
+    if (!Array.isArray(candidate.keymap))
+        throw guided(r, 'tui.mjs', 'keymap must be an array of key bindings');
+    return candidate;
+}
+/** Import the text presenter if present; null otherwise (the host synthesizes a
+ *  generic one-line dump when a view ships no text.mjs). */
+export async function loadText(r) {
+    if (!r.text)
+        return null;
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(r.text).href));
+    }
+    catch (e) {
+        throw guided(r, 'text.mjs', `failed to import: ${errText(e)}`);
+    }
+    const candidate = (typeof mod['dump'] === 'function' ? mod : mod['default']);
+    if (!candidate || typeof candidate.dump !== 'function')
+        throw guided(r, 'text.mjs', 'dump(state, ctx) is required');
+    return candidate;
+}
+/** Per-host presenter validation: `view run` requires a TUI presenter. */
+export function requireTui(r) {
+    if (!r.tui) {
+        throw new InputError({
+            error: 'view_web_only',
+            message: `'${r.id}' is web-only — it ships no tui.mjs presenter`,
+            next: `Run \`crtr view serve ${r.id}\` to open it in the browser.`,
+        });
+    }
+}
+/** Per-host presenter validation: `view serve` requires a web presenter. */
+export function requireWeb(r) {
+    if (!r.web) {
+        throw new InputError({
+            error: 'view_tui_only',
+            message: `'${r.id}' is tui-only — it ships no web.jsx presenter`,
+            next: `Run \`crtr view run ${r.id}\` to open it in a tmux pane.`,
+        });
+    }
+}
+function notTarget(r, target) {
+    return new Error(`view "${r.id}" has no ${target} presenter`);
+}
+function guided(r, file, problem) {
+    return new Error(`invalid view "${r.id}" (${r.scope}) at ${join(r.dir, file)}: ${problem}.\n` +
+        'A dual-target view dir holds core.mjs (default export: { manifest: { id, title }, init(), intents }) ' +
+        'plus optional tui.mjs (render + keymap), web.jsx, text.mjs (dump).');
+}
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/core/view/transport-local.d.ts

@@ -0,0 +1,7 @@
+import type { Transport } from './transport.js';
+export interface LocalTransportOptions {
+    /** Working directory for `exec` requests that don't carry their own cwd.
+     *  Defaults to process.cwd(). */
+    cwd?: string;
+}
+export declare function createLocalTransport(opts?: LocalTransportOptions): Transport;

package/dist/core/view/transport-local.js

@@ -0,0 +1,70 @@
+// transport-local.ts — the BUILT local transport: fulfills SourceRequests on
+// this machine. exec→execFile (cwd = the view's cwd unless the request says
+// otherwise), file→readFile, http→fetch.
+//
+// Never throws. Transport-level failure (binary missing, file unreadable,
+// network down) ⇒ { ok:false, stderr }. A spawned process exiting non-zero is
+// transport-level SUCCESS (ok:true + exitCode) — classifying that is the
+// source's parse() job.
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+const MAX_BUFFER = 10 * 1024 * 1024;
+export function createLocalTransport(opts = {}) {
+    const baseCwd = opts.cwd ?? process.cwd();
+    return {
+        async send(req) {
+            switch (req.kind) {
+                case 'exec': return sendExec(req, baseCwd);
+                case 'file': return sendFile(req);
+                case 'http': return sendHttp(req);
+            }
+        },
+    };
+}
+function sendExec(req, baseCwd) {
+    return new Promise((resolve) => {
+        const child = execFile(req.bin, req.args, { cwd: req.cwd ?? baseCwd, maxBuffer: MAX_BUFFER, encoding: 'utf8' }, (err, stdout, stderr) => {
+            if (!err) {
+                resolve({ ok: true, exitCode: 0, stdout, stderr });
+                return;
+            }
+            const code = err.code;
+            if (typeof code === 'number') {
+                // Ran but exited non-zero: transport-level success; parse() classifies.
+                resolve({ ok: true, exitCode: code, stdout: stdout ?? '', stderr: stderr ?? '' });
+                return;
+            }
+            if (err.signal) {
+                // Killed by signal: it ran; surface as a non-zero exit.
+                resolve({ ok: true, exitCode: 1, stdout: stdout ?? '', stderr: stderr ?? '' });
+                return;
+            }
+            // Spawn-level failure (ENOENT/EACCES/maxBuffer): transport failure.
+            const msg = code === 'ENOENT' ? `${req.bin}: command not found` : err.message;
+            resolve({ ok: false, stdout: stdout ?? '', stderr: msg });
+        });
+        if (req.stdin != null && child.stdin) {
+            child.stdin.write(req.stdin);
+            child.stdin.end();
+        }
+    });
+}
+async function sendFile(req) {
+    try {
+        const text = await readFile(req.path, 'utf8');
+        return { ok: true, stdout: text, stderr: '' };
+    }
+    catch (e) {
+        return { ok: false, stdout: '', stderr: e instanceof Error ? e.message : String(e) };
+    }
+}
+async function sendHttp(req) {
+    try {
+        const res = await fetch(req.url, { method: req.method, headers: req.headers, body: req.body });
+        const body = await res.text();
+        return { ok: true, status: res.status, stdout: body, stderr: res.ok ? '' : res.statusText };
+    }
+    catch (e) {
+        return { ok: false, stdout: '', stderr: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/core/view/transport.d.ts

@@ -0,0 +1,4 @@
+import type { SourceRequest, RawResponse } from './contract.js';
+export interface Transport {
+    send(req: SourceRequest): Promise<RawResponse>;
+}

package/dist/core/view/transport.js

@@ -0,0 +1,15 @@
+// transport.ts — the transport seam between a view's declarative SourceRequests
+// and whatever fulfills them.
+//
+// The core is transport-blind: it only ever calls ctx.resolve(source, args) /
+// ctx.execute(command, args); the host threads Transport.send → source.parse.
+// Implementations:
+//   • transport-local.ts (BUILT) — Node-side: exec→execFile, file→readFile,
+//     http→fetch. Used directly by the TUI host and by the `view serve` bridge
+//     server on behalf of the browser bundle.
+//   • src/web/transport-http.ts (BUILT) — browser-side: POSTs the SourceRequest
+//     to the local bridge (`/__crtr/source`).
+//   • cloud (SEAM ONLY, not built) — same interface; send() POSTs the request
+//     to an endpoint that runs it server-side, or maps it to a real API call.
+//     Wiring a different Transport is the entire cloud migration.
+export {};

package/dist/daemon/crtrd.d.ts

@@ -1,36 +1,47 @@
 import { type NodeRow } from '../core/canvas/index.js';
 import { isPidAlive } from '../core/canvas/pid.js';
 export declare const YIELD_STALL_GRACE_MS: number;
-export declare const NEVER_LAUNCHED_GRACE_MS: number;
-/** Never-launched decision (audit 2026-06-09, Bug 4 — node mq45b6ch-9ecc2f03):
- *  a spawn that opened its window but whose pi never came up leaves a row with
- *  ZERO cycles, NO session, NO pid — and, when the window lingers (e.g. a
- *  remain-on-exit corpse), the live-pane pass read "no pid to judge" and left it
- *  forever; the parent waited on a node that was never going to run. Pure core:
- *  a node that has ever booted (session recorded) or ever been revived (cycles
- *  bumped) is NOT never-launched — the cycles gate also bounds this to ONE
- *  automatic retry (the relaunch bumps cycles), so a persistently failing
- *  launch can't loop. Age below the grace is a normal in-flight boot. */
-export declare function neverLaunchedVerdict(piSessionId: string | null, cycles: number, ageMs: number): 'leave' | 'relaunch';
-/** Yield-stall decision (audit 2026-06-09, Bug 1 — node mq5v9hfa-74493d45 and
- *  three sibling orchestrators): a `node yield` records intent='refresh' and
- *  agent_end dispatches the in-place respawn, but at very large contexts the pi
- *  process can HANG instead of exiting — leaving pi alive, the turn over, and
- *  the intent pending forever. The daemon only revives DEAD pis, so without
- *  this verdict the node is permanently stuck (no revive, no wake). Pure core,
- *  mirroring livenessVerdict; the kill side effects live in handleYieldStall.
+/** Refresh-stall decision (§H refresh-authority; audit 2026-06-09, Bug 1 — node
+ *  mq5v9hfa-74493d45 and siblings; stuck-refresh — parent mq7s5o93): a `node
+ *  yield` / refresh records intent='refresh' and relies on the in-process
+ *  stophook to call shutdown at stop, but the engine can be left ALIVE — either
+ *  it HANGS instead of exiting (very large contexts) or a STALE stophook (pi
+ *  extensions never reload) ignores intent='refresh' entirely and never calls
+ *  shutdown. Either way: engine alive, turn over, intent pending forever. The
+ *  daemon only revives DEAD engines, so without this verdict the node is
+ *  permanently stuck (no revive, no wake). Pure core, mirroring livenessVerdict;
+ *  the kill side effects live in handleYieldStall.
  *
- *  'kill' ONLY when ALL of: pi alive, intent='refresh', the turn is over (busy
- *  marker absent — a node may legitimately keep working for many minutes after
- *  running `node yield` mid-turn, and a working pi must never be killed), and
- *  the state has persisted past YIELD_STALL_GRACE_MS. */
+ *  'kill' ONLY when ALL of: engine alive, intent='refresh', the turn is over
+ *  (busy marker absent — a node may legitimately keep working for many minutes
+ *  after running `node yield` mid-turn, and a working engine must never be
+ *  killed), and the state has persisted past YIELD_STALL_GRACE_MS. */
 export declare function yieldStallVerdict(piPidAlive: boolean | null, intent: NodeRow['intent'], busy: boolean, stalledFor: number | null): 'leave' | 'pending' | 'kill';
+export declare const ERROR_STALL_QUIET_MS: number;
+/** The §I wedge signature, from a session-jsonl tail: the LAST assistant
+ *  message stopped with 'error' (retry budget exhausted — pi appends the error
+ *  turn and parks). Returns its errorMessage for the daemon log (the "why it
+ *  wedged" trace), or null when the last assistant turn ended any other way —
+ *  'stop'/'length' is a healthy park, 'aborted' is a human Esc, and trailing
+ *  non-assistant lines (toolResults, an injected user message) are walked past.
+ *  The first line of a mid-file tail cut fails JSON.parse and is skipped. */
+export declare function trailingEngineError(tail: string | null): string | null;
+/** Error-stall decision (§I; gh issue #4 — node mqaeqzdu-0746b3b7, a 9h zombie
+ *  after an Anthropic outage). Pure, mirroring yieldStallVerdict; the kill side
+ *  effects live in handleErrorStall.
+ *
+ *  'kill' ONLY when ALL of: engine alive, NO pending intent (refresh is §H's
+ *  domain; idle-release chose dormancy), the turn is over (busy absent — a node
+ *  wedged mid-bash must be recovered by killing the subprocess, never the node),
+ *  the session file has been quiet past ERROR_STALL_QUIET_MS, and its last
+ *  assistant message stopped with 'error'. */
+export declare function errorStallVerdict(piPidAlive: boolean | null, intent: NodeRow['intent'], busy: boolean, quietForMs: number | null, trailingError: boolean): 'leave' | 'kill';
 export type LivenessVerdict = 'leave' | 'pending' | 'revive';
-/** Decide what to do with a node whose tmux pane is alive, from its pi
- *  liveness and how long it's been dead. Pure — the time-and-tmux side effects
- *  live in handleLiveWindow; this is the unit-testable core.
- *    piPidAlive: true=alive, false=dead, null=no pid recorded (legacy node, or a
- *      relaunch in flight) — leave those to the pane-gone pass.
+/** Decide what to do with a node whose engine pid is DEAD, from how long it's
+ *  been dead. Pure — the time/revive side effects live in handleNodeLiveness;
+ *  this is the unit-testable core. (piPidAlive carries dead/alive/unknown, but
+ *  only `false` ever reaches a revive decision here — alive and null are routed
+ *  upstream by handleNodeLiveness.)
  *    deadFor: ms since first observed dead, or null on the first observation. */
 export declare function livenessVerdict(piPidAlive: boolean | null, deadFor: number | null): LivenessVerdict;
 export declare const DEAD_REAP_GRACE_MS: number;