@north-light/crouter 0.3.154

package/dist/core/runtime/reset.js

@@ -0,0 +1,198 @@
+// `/new` handling — root relaunch + child session-id refresh — plus clean-exit
+// termination.
+//
+// A node's engine is a detached broker process bound to one CRTR_NODE_ID, and
+// its on-screen viewer is a SEPARATE `crtr surface attach` pane. `/new` splits by who
+// ran it:
+//
+//   • relaunchRoot — a `/new` on a ROOT starts a genuinely new node: the old
+//     root is parked `done` (kept as history), a fresh node id + broker is
+//     minted in the same pane/cwd, and the viewer pane is re-pointed at the new
+//     broker. The new broker is booted FIRST, so any failure before the commit
+//     point leaves the old root fully intact.
+//   • resetRoot — a `/new` on a non-root child refreshes its session id only, so
+//     a later `--session <id>` wakes the right conversation.
+//
+// Termination semantics: a pi that ends cleanly resolves its node to `done`
+// (markCleanExitDone); only a true crash leaves it `dead`. A force-kill fires NO
+// clean session_shutdown, so reaped descendants are marked `canceled` explicitly
+// here (A5: an externally-reaped node did not finish its own work — done is
+// reserved for finish).
+//
+// Best-effort throughout: a tmux/fs failure on one node never aborts the reap.
+import { getNode, updateNode, fullName, closeFocusRow, view, } from '../canvas/index.js';
+import { transition } from './lifecycle.js';
+import { headlessBrokerHost } from './host.js';
+import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, windowOfPane, renameWindow, } from './placement.js';
+import { viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
+import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { spawnNode, rootOfSpine } from './nodes.js';
+// ---------------------------------------------------------------------------
+// reapDescendants — tear down a root's descendant sub-DAG (shared helper)
+// ---------------------------------------------------------------------------
+/** Reap the descendant sub-DAG of `rootId`: mark each **canceled** (the user
+ *  moved on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
+ *  window (closes the daemon revive race). Edges are LEFT INTACT — descendants
+ *  keep parent=rootId. No wipe. Returns the reaped ids.
+ *
+ *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
+ *  whether via `node lifecycle close` OR a root reset — did not finish its OWN work, so it
+ *  unifies on `canceled`; `done` is reserved for finish. Why marking is STILL
+ *  explicit: an abrupt broker teardown fires NO clean `session_shutdown`, so the
+ *  general quit→done rule does NOT auto-resolve a force-killed descendant — we
+ *  mark it `canceled` here via the same `cancel` event the close cascade uses. */
+export function reapDescendants(rootId) {
+    const reaped = [];
+    for (const id of view(rootId)) {
+        try {
+            // Reap BEFORE tearing down the engine (the crash-safety invariant the
+            // `cancel` event encodes): a non-supervised status + cleared intent first,
+            // so the daemon can't revive a descendant mid-teardown. Teardown then sends
+            // the broker the `shutdown` frame so its PROCESS exits and releases the
+            // sole .jsonl writer; tearDownNode then proactively closes the on-screen
+            // viewer pane + registry row (attach auto-reconnects, so the viewer must be
+            // closed here or it lingers ~30s in a misleading "reconnecting…" state).
+            transition(id, 'cancel');
+            headlessBrokerHost.teardown(id);
+            tearDownNode(id);
+            reaped.push(id);
+        }
+        catch {
+            /* one bad node never aborts the reap */
+        }
+    }
+    return reaped;
+}
+/** Relaunch a ROOT on `/new`: park the old root `done` (kept as history) and
+ *  mint a fresh node id + broker in the same pane/cwd, re-pointing the viewer at
+ *  it. The new broker is booted FIRST and its pid confirmed BEFORE the old root
+ *  is touched, so any pre-commit failure leaves the old root fully intact and
+ *  live. Returns null when `oldId` is not a relaunchable root (unknown, a child,
+ *  or already parked), or when the new broker failed to launch. */
+export async function relaunchRoot(oldId, deps = {}) {
+    const launchBroker = deps.launchBroker ?? headlessBrokerHost.launch;
+    const waitForViewSocket = deps.waitForViewSocket ?? waitForBrokerViewSocket;
+    const respawnViewer = deps.respawnViewer ?? respawnPaneSync;
+    const teardownBroker = deps.teardownBroker ?? headlessBrokerHost.teardown;
+    const old = getNode(oldId);
+    if (old === null || old.parent != null)
+        return null; // roots only
+    if (old.status === 'done')
+        return null; // defensive: a double `/new`
+    const oldFocus = focusOf(oldId); // capture the viewer BEFORE any teardown
+    // --- mint + boot the NEW broker FIRST (a failure here leaves the old root
+    //     untouched) ---
+    // A relaunched root is a fresh resident base, exactly like the front door.
+    const { launch } = buildLaunchSpec(old.kind, 'base', {
+        lifecycle: 'resident',
+        hasManager: false,
+        model: old.model_override ?? undefined,
+        // A `/new` relaunch carries no new --model — preserve the old root's pin
+        // verbatim rather than re-deriving it from model_override's shape.
+        modelProviderPinned: old.launch?.modelProviderPinned,
+        // The OLD root's cwd + profile, not this process's ambient scope — the
+        // relaunch is the same seat, so profile-scope kind defaults keep applying.
+        cwd: old.cwd,
+        profileId: old.profile_id,
+    });
+    const newMeta = spawnNode({
+        kind: old.kind,
+        mode: 'base',
+        lifecycle: 'resident',
+        cwd: old.cwd,
+        name: old.kind,
+        parent: null,
+        profile_id: old.profile_id,
+        launch,
+        modelOverride: old.model_override ?? undefined,
+    });
+    const inv = buildPiArgv(newMeta, {});
+    // Mirror bootRoot's subtree routing on inv.env (the broker host merges it; it
+    // sets CRTR_FRONT_DOOR itself).
+    inv.env = {
+        ...inv.env,
+        CRTR_SUBTREE: rootOfSpine(newMeta.node_id),
+    };
+    const placed = launchBroker(newMeta.node_id, inv, {
+        cwd: old.cwd,
+        name: fullName(newMeta),
+        resuming: false,
+    });
+    if (placed.pid == null) {
+        // The new broker never started — crash the half-born node and BAIL. The old
+        // root is still live and untouched (nothing below this point has run).
+        transition(newMeta.node_id, 'crash');
+        return null;
+    }
+    await waitForViewSocket(newMeta.node_id, placed.exited); // best-effort; attach auto-redials on miss
+    // --- COMMIT: park + reap the old root, re-point the viewer, kill the old
+    //     broker. Past this point the new node is the live root. ---
+    reapDescendants(oldId); // old workers → canceled + torn down
+    // Park the old root DONE (kept as history; NOT canceled — a relaunched root
+    // finished cleanly, the user just started fresh). Its reports/inbox/roadmap
+    // are left on disk as the record of that session.
+    transition(oldId, 'finish');
+    if (oldFocus?.pane != null) {
+        closeFocusRow(oldFocus.focus_id);
+        respawnViewer({
+            pane: oldFocus.pane,
+            cwd: old.cwd,
+            env: viewerSplitEnv(),
+            command: `crtr surface attach to ${newMeta.node_id}`,
+        });
+        const window = windowOfPane(oldFocus.pane);
+        if (window !== null)
+            renameWindow(window, fullName(newMeta));
+        registerViewerFocus(newMeta.node_id, oldFocus.pane, oldFocus.session, window);
+    }
+    teardownBroker(oldId); // old broker exits cleanly (its /new work is discarded)
+    return { newNodeId: newMeta.node_id };
+}
+/** Refresh a non-root child's pi session id on `/new`, so a later
+ *  `--session <id>` wakes the right conversation. A `/new` on a child is NOT a
+ *  graph reset — a root's `/new` is handled by relaunchRoot, never here; a root
+ *  that reaches this is a no-op. */
+export function resetRoot(nodeId, newSessionId, newSessionFile) {
+    const meta = getNode(nodeId);
+    const empty = { reaped: [], detached: [], reset: false };
+    if (meta === null || meta.parent == null)
+        return empty; // unknown or a root
+    if (newSessionId !== undefined) {
+        updateNode(nodeId, {
+            pi_session_id: newSessionId,
+            ...(newSessionFile !== undefined ? { pi_session_file: newSessionFile } : {}),
+        });
+    }
+    return empty;
+}
+/** The child-side `/new` entry the stophook calls (the root side goes to
+ *  relaunchRoot directly). The broker already drove the engine-side new_session;
+ *  this only refreshes the child's session id on the SAME node id. */
+export function handleNewSession(nodeId, newSessionId, newSessionFile) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { path: 'noop' };
+    resetRoot(nodeId, newSessionId, newSessionFile);
+    return { path: 'reset-child' };
+}
+// ---------------------------------------------------------------------------
+// markCleanExitDone — the clean-exit→done termination guard
+// ---------------------------------------------------------------------------
+/** Resolve a cleanly-exiting node to `done`. Returns true iff it transitioned.
+ *  Guard: only a real quit, and only a node still active|idle with no pending
+ *  intent — so it never clobbers a node already routed by agent_end to done
+ *  (push final), refresh (yield), or idle-release. Pure/DB-only (no pi/tmux) so
+ *  the guard is unit-testable without a live pi. */
+export function markCleanExitDone(nodeId, reason) {
+    if (reason !== 'quit')
+        return false; // new/reload/resume/fork → no-op
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return false;
+    if (meta.status !== 'active' && meta.status !== 'idle')
+        return false; // already done/dead/canceled
+    if (meta.intent != null)
+        return false; // refresh / idle-release in flight
+    transition(nodeId, 'finish');
+    return true;
+}

package/dist/core/runtime/resume-root.d.ts

@@ -0,0 +1,6 @@
+/** Resolve a front-door resume: pick a target root (MRU or via picker), then
+ *  open this terminal to view it. On success it execs the viewer inline and
+ *  never returns. Otherwise reports why it did not: `'empty'` (no resumable root
+ *  here → caller boots a fresh one) or `'aborted'` (the picker was dismissed →
+ *  caller exits without surprise-booting). */
+export declare function resumeRoot(cwd: string, pick: boolean): Promise<'empty' | 'aborted'>;

package/dist/core/runtime/resume-root.js

@@ -0,0 +1,292 @@
+// Front-door resume — `crtr -c` / `crtr -r`, canvas-free.
+//
+//   crtr -c | --continue   → revive + attach the MRU root pinned to this cwd,
+//                            inline in THIS terminal (no picker). If no root is
+//                            resumable here, boot a fresh one.
+//   crtr -r | --resume     → same, but choose from a keypress menu of the roots
+//                            pinned to this cwd first.
+//
+// A "session" in the Claude-Code sense is a crtr ROOT node: a durable pi
+// conversation pinned to a cwd that never dies, only goes dormant. So resuming
+// is reviving the last root here and making THIS pane its writable viewer —
+// mirroring the front-door boot tail (register the pane as the viewer focus,
+// then exec `crtr surface attach` inline). cwd is the key so it never teleports
+// across projects.
+//
+// crtrd is the sole owner of canvas state (see crtrd-sole-state-owner), so this
+// module opens NO canvas.db: the resumable-root list, the stale-focus drop, and
+// the new viewer-focus row all route through the /v1 API client. The revive
+// itself is delegated to the inline `crtr surface attach` exec, whose
+// ensureAttach revives the broker and waits for its view socket server-side.
+// The only work that stays client-side is the interactive picker, the
+// tmux-binding reconcile, and the inline attach exec — so this resume path
+// (cli.js → front-door.js → here) reaches zero canvas code.
+import { spawn } from 'node:child_process';
+import { emitKeypressEvents } from 'node:readline';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isPidAlive } from '../canvas/pid.js';
+import { contextDir } from '../canvas/paths.js';
+import { installTmuxBindings } from './tmux-chrome.js';
+import { currentTmux, inTmux, viewerSplitEnv } from './placement-tmux.js';
+import { cliClient } from '../../commands/api-client.js';
+import { stdoutColor } from '../output.js';
+const dim = stdoutColor.dim;
+const bold = stdoutColor.bold;
+const accent = stdoutColor.cyan;
+/** Resumable ROOT conversations pinned to `cwd`, most-recently-created first.
+ *  A "root" is the top of a spine (`parent === null`) that is a real
+ *  conversation (not a `kind:'human'` ask) and still resumable (`active`/`idle`,
+ *  never a `done`/`dead`/`canceled` node). cwd is the key (the Claude-Code
+ *  mental model — "my last session HERE"). Replicates `listResumableRoots`'
+ *  filter over the /v1 node list. */
+async function listResumableRoots(cwd) {
+    const all = await cliClient().listNodes();
+    return all
+        .filter((n) => n.parent === null &&
+        n.kind !== 'human' &&
+        (n.status === 'active' || n.status === 'idle') &&
+        n.cwd === cwd)
+        .sort((a, b) => (a.created < b.created ? 1 : a.created > b.created ? -1 : 0)); // created DESC = MRU
+}
+/** Resolve a front-door resume: pick a target root (MRU or via picker), then
+ *  open this terminal to view it. On success it execs the viewer inline and
+ *  never returns. Otherwise reports why it did not: `'empty'` (no resumable root
+ *  here → caller boots a fresh one) or `'aborted'` (the picker was dismissed →
+ *  caller exits without surprise-booting). */
+export async function resumeRoot(cwd, pick) {
+    const roots = await listResumableRoots(cwd);
+    if (roots.length === 0)
+        return 'empty';
+    let target;
+    if (pick && roots.length > 1) {
+        target = await pickRoot(roots, cwd);
+        if (target === null)
+            return 'aborted';
+    }
+    else {
+        target = roots[0]; // MRU (also the sole root under `-r` with one candidate)
+    }
+    await attachInline(target.node_id);
+    return 'aborted'; // unreachable — attachInline execs and exits
+}
+/** Register THIS pane as the target root's foreground viewer, then exec
+ *  `crtr surface attach` inline so this terminal becomes a writable viewer. The attach's
+ *  own ensureAttach revives the dormant broker + waits for its view socket
+ *  server-side, so this does NOT revive in-process. Mirrors the front-door boot
+ *  tail. Does not return. */
+async function attachInline(nodeId) {
+    if (!inTmux()) {
+        throw new Error('crtr must be resumed from inside a tmux session — start tmux first (e.g. `tmux new -s work`), then run `crtr -c` there.');
+    }
+    try {
+        installTmuxBindings();
+    }
+    catch { /* best-effort */ }
+    // Make THIS pane the node's foreground viewer. A dormant root's prior focus row
+    // points at a stale/detached pane (the front door keeps the row across a
+    // clean detach), so drop it and claim the current pane — the exact --new-pane
+    // discipline of registerViewerFocus,
+    // routed through crtrd since it is a canvas write.
+    const here = currentTmux();
+    if (here !== null) {
+        try {
+            const prior = await cliClient().focusOf(nodeId);
+            if (prior !== null) {
+                try {
+                    await cliClient().closeFocus(prior.focus_id);
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        catch { /* best-effort */ }
+        try {
+            await cliClient().registerFocus({ node_id: nodeId, pane: here.pane, session: here.session, window: here.window });
+        }
+        catch { /* best-effort */ }
+    }
+    const attachEnv = { ...process.env, ...viewerSplitEnv(), CRTR_ATTACH_WAIT_MS: '30000' };
+    const child = spawn('crtr', ['surface', 'attach', 'to', nodeId], { stdio: 'inherit', env: attachEnv });
+    const code = await new Promise((res) => {
+        child.once('exit', (c) => res(c ?? 0));
+        child.once('error', () => res(1));
+    });
+    process.exit(code);
+}
+// ---------------------------------------------------------------------------
+// `-r` picker — a minimal raw-mode keypress menu (pre-boot, we own the TTY).
+// ---------------------------------------------------------------------------
+const HILITE = accent('\u25b8');
+const cursorUp = (n) => (n > 0 ? `\u001b[${n}A\r` : '');
+const CLEAR_DOWN = '\u001b[0J';
+const ANSI_RE = /\u001b\[[0-9;]*m/g;
+/** Terminal rows a just-written block occupies — counts each '\n' AND the extra
+ *  rows a long line WRAPS into at the current terminal width (ANSI color codes
+ *  stripped so they don't inflate the width). A plain newline count undershoots
+ *  in a narrow pane, so redraws stack instead of clearing. Mirrors the
+ *  profile-menu blockRows. */
+function blockRows(block) {
+    const cols = process.stdout.columns ?? 80;
+    const segs = block.split('\n');
+    const newlines = segs.length - 1; // block ends with '\n' → last seg is ''
+    let extra = 0;
+    for (let i = 0; i < newlines; i++) {
+        const w = segs[i].replace(ANSI_RE, '').length;
+        if (cols > 0 && w > cols)
+            extra += Math.ceil(w / cols) - 1;
+    }
+    return newlines + extra;
+}
+/** Truncate to a visible-column budget, preserving ANSI escapes (they cost no
+ *  width). Appends '…' when it cuts. Keeps a styled row on one terminal line so
+ *  nothing wraps. */
+function fitWidth(s, width) {
+    if (width <= 0)
+        return s;
+    let out = '';
+    let vis = 0;
+    for (let i = 0; i < s.length;) {
+        if (s[i] === '\u001b') {
+            const m = /^\u001b\[[0-9;]*m/.exec(s.slice(i));
+            if (m !== null) {
+                out += m[0];
+                i += m[0].length;
+                continue;
+            }
+        }
+        if (vis >= width - 1 && s.replace(ANSI_RE, '').length > width) {
+            out += '\u2026';
+            break;
+        }
+        out += s[i];
+        vis++;
+        i++;
+    }
+    return out;
+}
+function label(r) {
+    // Liveness is the broker pid, not the row status: a dormant resident root
+    // keeps status='active' while its engine is down.
+    const live = isPidAlive(r.pi_pid ?? null) ? accent('\u25cf live') : dim('\u25cb dormant');
+    // The node's display name — same handle the Alt-G graph shows. A never-named
+    // root carries the bare kind, useless in a roster where every root is
+    // 'general'; rescue it with the goal's first line (the spawning prompt), read
+    // canvas-free from the node's context dir, so unnamed convos are tellable
+    // apart.
+    let name = r.name;
+    if (name === r.kind) {
+        const goal = firstLine(readGoalBody(r.node_id));
+        if (goal !== '')
+            name = goal;
+    }
+    return `${name}  ${live}`;
+}
+/** The node's goal body (`initial-prompt.md`), read canvas-free from its context
+ *  dir. `contextDir` is a pure path builder (fs only). */
+function readGoalBody(nodeId) {
+    try {
+        return readFileSync(join(contextDir(nodeId), 'initial-prompt.md'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** First non-empty line of a goal body, trimmed and length-capped. */
+function firstLine(text) {
+    if (text === null)
+        return '';
+    const line = text.split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+    return line.length > 72 ? line.slice(0, 71) + '\u2026' : line;
+}
+function detail(r, cwd) {
+    const when = ago(r.created);
+    const where = r.cwd === cwd ? '' : `  ${r.cwd}`;
+    // Short id keeps the row on one line; the full id is rarely needed to pick.
+    return `${when}${where}  ${r.node_id.slice(0, 8)}`;
+}
+function ago(iso) {
+    const ms = Date.now() - new Date(iso).getTime();
+    if (!Number.isFinite(ms) || ms < 0)
+        return '';
+    const m = Math.floor(ms / 60000);
+    if (m < 1)
+        return 'just now';
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+/** Drive a highlighted keypress menu of resumable roots. ↑/↓ or j/k move,
+ *  digits jump, Enter picks, q/Esc/Ctrl-C abort → null. Restores the TTY on
+ *  every exit path so the inline viewer gets a clean terminal. */
+function pickRoot(roots, cwd) {
+    const title = 'Resume a session here';
+    const subtitle = `${roots.length} roots pinned to ${cwd}`;
+    return new Promise((resolve) => {
+        const out = process.stdout;
+        const input = process.stdin;
+        let sel = 0;
+        let prevLines = 0;
+        const render = () => {
+            const cols = process.stdout.columns ?? 80;
+            let s = `\n  ${bold(title)}\n  ${dim(subtitle)}\n\n`;
+            roots.forEach((r, i) => {
+                const mark = i === sel ? HILITE : ' ';
+                const slot = i < 9 ? key(`${i + 1}`) : '  ';
+                const row = `  ${mark} ${slot}  ${label(r)}  ${dim(detail(r, cwd))}`;
+                s += fitWidth(row, cols) + '\n';
+            });
+            s += `\n  ${dim('↑/↓ move  enter resume  q quit')}\n`;
+            return s;
+        };
+        const draw = () => {
+            const block = render();
+            out.write((prevLines > 0 ? cursorUp(prevLines) + CLEAR_DOWN : '') + block);
+            prevLines = blockRows(block);
+        };
+        emitKeypressEvents(input);
+        const wasRaw = input.isRaw ?? false;
+        if (input.isTTY)
+            input.setRawMode(true);
+        input.resume();
+        const finish = (result) => {
+            input.removeListener('keypress', onKey);
+            if (input.isTTY)
+                input.setRawMode(wasRaw);
+            input.pause();
+            out.write(cursorUp(prevLines) + CLEAR_DOWN);
+            resolve(result);
+        };
+        const onKey = (_str, k) => {
+            const name = k.name ?? '';
+            if (k.ctrl && name === 'c') {
+                finish(null);
+                process.exit(130);
+            }
+            if (name === 'q' || name === 'escape')
+                return finish(null);
+            if (name === 'up' || name === 'k') {
+                sel = (sel - 1 + roots.length) % roots.length;
+                return draw();
+            }
+            if (name === 'down' || name === 'j') {
+                sel = (sel + 1) % roots.length;
+                return draw();
+            }
+            if (name === 'return' || name === 'enter')
+                return finish(roots[sel]);
+            const digit = Number.parseInt(k.sequence ?? '', 10);
+            if (Number.isInteger(digit) && digit >= 1 && digit <= Math.min(9, roots.length)) {
+                sel = digit - 1;
+                return finish(roots[sel]);
+            }
+        };
+        input.on('keypress', onKey);
+        draw();
+    });
+}
+function key(s) {
+    return accent(s);
+}

package/dist/core/runtime/revive-all.d.ts

@@ -0,0 +1,61 @@
+import type { NodeMeta, NodeStatus } from '../canvas/types.js';
+/** Statuses a node lands in DELIBERATELY: a worker that finished its own work
+ *  (`done`) or a node a human closed/reaped (`canceled`). The daemon never
+ *  auto-revives these (see reapDeadResidue in crtrd.ts), and revive-all leaves
+ *  them alone too — resurrecting finished and closed conversations en masse would
+ *  flood the canvas with work nobody asked to reopen. `dead` is NOT here: a crash
+ *  is involuntary, so it is swept. (Silas, 2026-06-13: no opt-in to include these
+ *  — the exclusion is unconditional.) */
+export declare const TERMINAL_BY_CHOICE: readonly NodeStatus[];
+/** True when `meta` has no natural future cycle ahead of it — either its own
+ *  work is finished (`final_report` set) or it landed deliberately in one of
+ *  TERMINAL_BY_CHOICE. Nothing in the runtime (daemon supervision, the live
+ *  inbox watcher's own hold-and-flush) ever brings such a node back on its
+ *  own — only an explicit revive/reopen does. Shared by `isDisconnected`
+ *  (mass-revive scope, below) and `node message send --tier deferred`'s terminal-edge
+ *  rejection (gh #341) — a deferred entry appended to such a target would
+ *  never be delivered, so that doorway rejects instead of silently holding
+ *  it forever. */
+export declare function hasNoNaturalCycle(meta: Pick<NodeMeta, 'status' | 'final_report'>): boolean;
+/** True when `meta`'s engine is NOT running but it has a resumable saved session
+ *  — the precise "disconnected" predicate (gh #9).
+ *
+ *  - engine not running: no live `pi_pid` (a dead/absent broker pid).
+ *  - reconnectable: a captured pi session marker (`pi_session_file` or
+ *    `pi_session_id`) — without one there is nothing to reopen. reviveNode
+ *    resumes by the `.jsonl` path when it still exists, else relaunches fresh (a
+ *    bare `pi_session_id` alone no longer resumes — the broker preflight rejects
+ *    it — so such a node comes back fresh).
+ *  - `human`-kind rows are the `crtr human` bridge, never a pi engine, so they
+ *    are never "disconnected" (mirrors the daemon's superviseTick carve-out).
+ *  - terminal-by-choice (`done`/`canceled`) is always excluded.
+ *  - a node that already pushed its FINAL REPORT (`final_report` set) FINISHED
+ *    its own work — it is excluded regardless of status. A crash mid-reap can
+ *    leave it `dead` (not terminal-by-choice) with its report already committed;
+ *    resurrecting it as `active` strands it re-reviving forever and cannot
+ *    re-reap (the stuck-node incident). Mass revive must never resurrect
+ *    finished work; an explicit `node lifecycle revive <id>` still can.
+ *
+ *  Pure: the liveness probe is injected so scope is unit-testable without real
+ *  processes. */
+export declare function isDisconnected(meta: NodeMeta, isAlive: (pid: number | null | undefined) => boolean): boolean;
+/** Every disconnected node on the canvas — the set a revive-all WOULD relaunch.
+ *  This is the PREVIEW: it has no side effects, so the command can list the
+ *  candidates and gate on confirmation before any engine is launched. */
+export declare function listDisconnected(): NodeMeta[];
+export interface ReviveAllResult {
+    /** Node ids whose broker engine reviveAll relaunched (RESUME). */
+    revived: string[];
+    /** Per-node failures — reviveNode threw (its launch failed). One bad node
+     *  never aborts the sweep. */
+    failed: {
+        node_id: string;
+        error: string;
+    }[];
+}
+/** RESUME every disconnected node. reviveNode is the ONLY sanctioned launcher
+ *  and self-guards the double-spawn (a node whose broker pid is already live is a
+ *  no-op), so this is a thin orchestrator over `listDisconnected`: revive each
+ *  with resume:true. One failing node never aborts the sweep — its error is
+ *  collected and the rest proceed. */
+export declare function reviveAll(): ReviveAllResult;

package/dist/core/runtime/revive-all.js

@@ -0,0 +1,106 @@
+// revive-all — resume EVERY disconnected node in one shot (gh issue #9).
+//
+// After a mass-disconnect event (a reboot, a killed login/tmux session, a mass
+// crash, or the daemon being down a while) many nodes end up with their
+// canvas.db row + saved conversation intact but NO broker engine running. The
+// daemon recovers active|idle rows during its explicit startup sweep and from
+// broker exit events during its own epoch, but it deliberately never touches
+// terminal/dormant states, so the operator is left reviving survivors one id at
+// a time.
+//
+// This module is the single sweep: `listDisconnected` selects every DISCONNECTED
+// node (engine not running, but a resumable saved session exists), and
+// `reviveAll` RESUMEs each via reviveNode — the only sanctioned launcher, which
+// self-guards the double-spawn. The selection predicate (`isDisconnected`) is
+// pure so the scope rules are unit-testable without booting a single process.
+import { listNodes, getNode } from '../canvas/index.js';
+import { recordedPidLiveness } from '../canvas/pid.js';
+import { reviveNode } from './revive.js';
+/** Statuses a node lands in DELIBERATELY: a worker that finished its own work
+ *  (`done`) or a node a human closed/reaped (`canceled`). The daemon never
+ *  auto-revives these (see reapDeadResidue in crtrd.ts), and revive-all leaves
+ *  them alone too — resurrecting finished and closed conversations en masse would
+ *  flood the canvas with work nobody asked to reopen. `dead` is NOT here: a crash
+ *  is involuntary, so it is swept. (Silas, 2026-06-13: no opt-in to include these
+ *  — the exclusion is unconditional.) */
+export const TERMINAL_BY_CHOICE = ['done', 'canceled'];
+/** True when `meta` has no natural future cycle ahead of it — either its own
+ *  work is finished (`final_report` set) or it landed deliberately in one of
+ *  TERMINAL_BY_CHOICE. Nothing in the runtime (daemon supervision, the live
+ *  inbox watcher's own hold-and-flush) ever brings such a node back on its
+ *  own — only an explicit revive/reopen does. Shared by `isDisconnected`
+ *  (mass-revive scope, below) and `node message send --tier deferred`'s terminal-edge
+ *  rejection (gh #341) — a deferred entry appended to such a target would
+ *  never be delivered, so that doorway rejects instead of silently holding
+ *  it forever. */
+export function hasNoNaturalCycle(meta) {
+    return meta.final_report != null || TERMINAL_BY_CHOICE.includes(meta.status);
+}
+/** True when `meta`'s engine is NOT running but it has a resumable saved session
+ *  — the precise "disconnected" predicate (gh #9).
+ *
+ *  - engine not running: no live `pi_pid` (a dead/absent broker pid).
+ *  - reconnectable: a captured pi session marker (`pi_session_file` or
+ *    `pi_session_id`) — without one there is nothing to reopen. reviveNode
+ *    resumes by the `.jsonl` path when it still exists, else relaunches fresh (a
+ *    bare `pi_session_id` alone no longer resumes — the broker preflight rejects
+ *    it — so such a node comes back fresh).
+ *  - `human`-kind rows are the `crtr human` bridge, never a pi engine, so they
+ *    are never "disconnected" (mirrors the daemon's superviseTick carve-out).
+ *  - terminal-by-choice (`done`/`canceled`) is always excluded.
+ *  - a node that already pushed its FINAL REPORT (`final_report` set) FINISHED
+ *    its own work — it is excluded regardless of status. A crash mid-reap can
+ *    leave it `dead` (not terminal-by-choice) with its report already committed;
+ *    resurrecting it as `active` strands it re-reviving forever and cannot
+ *    re-reap (the stuck-node incident). Mass revive must never resurrect
+ *    finished work; an explicit `node lifecycle revive <id>` still can.
+ *
+ *  Pure: the liveness probe is injected so scope is unit-testable without real
+ *  processes. */
+export function isDisconnected(meta, isAlive) {
+    if (meta.kind === 'human')
+        return false;
+    if (isAlive(meta.pi_pid))
+        return false; // engine running → connected
+    if (meta.pi_session_id == null && meta.pi_session_file == null)
+        return false; // nothing to resume
+    if (hasNoNaturalCycle(meta))
+        return false; // finished its own work, or terminal-by-choice — never mass-revive
+    return true;
+}
+/** Every disconnected node on the canvas — the set a revive-all WOULD relaunch.
+ *  This is the PREVIEW: it has no side effects, so the command can list the
+ *  candidates and gate on confirmation before any engine is launched. */
+export function listDisconnected() {
+    const out = [];
+    for (const row of listNodes()) {
+        const meta = getNode(row.node_id);
+        // IDENTITY-aware AND requires CONFIRMED alive: a bare isPidAlive would
+        // misread a recycled pi_pid as "engine running" and SKIP the node, so it
+        // never reaches reviveNode's own identity-aware double-launch guard
+        // (Round 2 of the pid-reuse-liveness fix, fold-in Major). `dead` OR
+        // `indeterminate` both count as disconnected/eligible here — only a
+        // positively confirmed-alive read is treated as "still connected".
+        if (meta !== null && isDisconnected(meta, (pid) => recordedPidLiveness(pid, meta.pi_pid_identity) === 'alive'))
+            out.push(meta);
+    }
+    return out;
+}
+/** RESUME every disconnected node. reviveNode is the ONLY sanctioned launcher
+ *  and self-guards the double-spawn (a node whose broker pid is already live is a
+ *  no-op), so this is a thin orchestrator over `listDisconnected`: revive each
+ *  with resume:true. One failing node never aborts the sweep — its error is
+ *  collected and the rest proceed. */
+export function reviveAll() {
+    const result = { revived: [], failed: [] };
+    for (const meta of listDisconnected()) {
+        try {
+            reviveNode(meta.node_id, { resume: true });
+            result.revived.push(meta.node_id);
+        }
+        catch (err) {
+            result.failed.push({ node_id: meta.node_id, error: err.message });
+        }
+    }
+    return result;
+}