@north-light/api 0.3.580 → 0.3.587

package/dist/commands/node/wait.js

@@ -0,0 +1,165 @@
+// `crtr node wait` — durable controller and deadline waits.
+import { envNodeId, envProfileId } from '../../shared/env.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { requireScope } from '../../core/errors.js';
+import { parseWhen } from '../../core/wake.js';
+import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
+import { shellQuote } from '../surface/node/placement.js';
+function armerId() {
+    const id = envNodeId();
+    if (id === undefined || id === '') {
+        throw new InputError({ error: 'no_node', message: 'no node to anchor a deadline cron (CRTR_NODE_ID unset)', next: 'Run from inside a node.' });
+    }
+    return id;
+}
+/** Build ParseOpts, including `tz` only when actually provided. */
+function parseOpts(now, tz) {
+    return tz !== undefined && tz.trim() !== '' ? { tz, now } : { now };
+}
+/** Map a time-grammar error to the rendered error block. */
+function throwTimeError(e) {
+    const next = {
+        wake_in_past: 'Pick a future instant — a positive duration ("5m","2h") or an ISO time later than now.',
+        bad_when: 'Use a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00").',
+        bad_cadence: 'Use a duration ("6h"), a 5-field cron ("0 9 * * *"), or an @alias ("@daily").',
+        unknown_zone: 'Pass --tz with an IANA zone name (e.g. "America/New_York").',
+        cadence_too_fast: 'Use a cadence of at least 60s (e.g. "1m","5m","1h").',
+    };
+    throw new InputError({ error: e.code, message: e.message, received: e.received, next: next[e.code] ?? 'Fix the time value and retry.' });
+}
+/** A human ETA hint like " (~5m)" from a fire-at ISO relative to now. '' if past. */
+function etaHint(fireAt, now) {
+    const ms = new Date(fireAt).getTime() - now.getTime();
+    if (!Number.isFinite(ms) || ms <= 0)
+        return '';
+    const mins = Math.round(ms / 60_000);
+    if (mins < 60)
+        return ` (~${mins}m)`;
+    const hrs = Math.round(ms / 3_600_000);
+    if (hrs < 48)
+        return ` (~${hrs}h)`;
+    return ` (~${Math.round(ms / 86_400_000)}d)`;
+}
+function deadlineHeredoc(body, nodeId) {
+    let delimiter = 'CRTR_DEADLINE';
+    let suffix = 0;
+    const lines = new Set(body.split('\n'));
+    while (lines.has(delimiter))
+        delimiter = `CRTR_DEADLINE_${++suffix}`;
+    return `crtr cron cancel "$CRTR_CRON_ID"\ncrtr node message send --to ${shellQuote(nodeId)} --tier urgent <<'${delimiter}'\n${body}\n${delimiter}`;
+}
+const nodeWaitDeadline = defineLeaf({
+    name: 'deadline',
+    description: 'race this node’s next wake against one urgent deadline cron',
+    whenToUse: 'you are waiting on an event nothing can push for, so a self-scheduled deadline must settle the wait',
+    help: {
+        name: 'node wait deadline',
+        summary: 'arm one cancel-on-wake deadline cron for this node',
+        params: [
+            { kind: 'stdin', name: 'body', required: true, constraint: 'Policy delivered urgently to this node if the deadline fires first.' },
+            { kind: 'flag', name: 'until', type: 'string', required: true, constraint: 'Future duration, zoned ISO timestamp, or bare ISO timestamp interpreted in --tz or host-local time.' },
+            { kind: 'flag', name: 'tz', type: 'string', required: false, constraint: 'IANA timezone for a bare ISO --until value.' },
+        ],
+        output: [
+            { name: 'id', type: 'string', required: true, constraint: 'The armed cron id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The cron label.' },
+            { name: 'fires_at', type: 'string', required: true, constraint: 'Absolute UTC deadline.' },
+            { name: 'guidance', type: 'string', required: true, constraint: 'How to inspect the cron and dorm.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Arms one anchored cancel-on-wake cron. Any wake of this node cancels it; otherwise it urgently sends the body to this node at the deadline.',
+            'Re-arming replaces this node’s pending deadline rather than stacking a second.',
+        ],
+    },
+    run: async (input) => {
+        requireScope('crtr:schedule', 'crtr node wait deadline');
+        const self = armerId();
+        const body = typeof input['body'] === 'string' ? input['body'].trim() : '';
+        if (body === '')
+            throw new InputError({ error: 'empty_body', message: 'a deadline body is required', field: 'body', next: 'Pass the timeout policy on stdin.' });
+        const until = typeof input['until'] === 'string' ? input['until'].trim() : '';
+        if (until === '')
+            throw new InputError({ error: 'missing_until', message: '--until is required', field: 'until', next: 'Pass a future duration or timestamp.' });
+        const tz = typeof input['tz'] === 'string' && input['tz'].trim() !== '' ? input['tz'] : undefined;
+        const now = new Date();
+        const parsed = parseWhen(until, parseOpts(now, tz));
+        if ('error' in parsed)
+            throwTimeError(parsed.error);
+        const profile = envProfileId();
+        // One deadline per node: the arm seam REPLACES this node's pending
+        // cancel-on-wake cron rather than stacking a second one (see armCron in
+        // core/canvas/crons.ts, where the invariant is enforced for every caller).
+        const cron = await cliClient().armCron({
+            name: `deadline:${self}`,
+            command: deadlineHeredoc(body, self),
+            fire_at: parsed.fireAt,
+            recur: null,
+            tz: tz ?? null,
+            created_by: self,
+            cwd: process.cwd(),
+            profile: profile !== undefined && profile !== '' ? profile : null,
+            scope: 'profile',
+            on_output: 'on-failure',
+            sink: null,
+            tier: 'normal',
+            expires_at: null,
+            anchor_node: self,
+            cancel_on_wake: true,
+            run_timeout_s: 300,
+            overlap: 'skip',
+        }).catch(rethrowAsCliError);
+        const guidance = `Deadline cron armed for ${cron.fire_at}${etaHint(cron.fire_at, now)}. End your turn to dorm; any earlier wake cancels it. Inspect pending schedules with \`crtr cron list\`.`;
+        return { id: cron.cron_id, name: cron.name, fires_at: cron.fire_at, guidance };
+    },
+    render: (r) => `Deadline cron armed — ${r['name']} (${r['id']}), fires ${r['fires_at']}.\n\n${r['guidance']}`,
+});
+const nodeWait = defineLeaf({
+    name: 'controller',
+    description: 'wait durably for a named controller message',
+    whenToUse: 'you are a terminal node blocked on one specific live parent or controller and have no managed-child subscription whose report will wake you',
+    help: {
+        name: 'node wait controller',
+        summary: 'declare that your next stop may dorm only until one live controller delivers an inbox message',
+        params: [
+            { kind: 'positional', name: 'controller', type: 'string', required: true, constraint: 'Live node id expected to send the message. It may be your parent or another named controller, but cannot be yourself.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The terminal node that declared the wait.' },
+        ],
+        outputKind: 'object',
+        effects: ['Durably records the controller on this node. The stop guard permits dormancy only while that controller remains active or idle; its next inbox delivery clears the record before the delivery wakes this node.'],
+    },
+    run: async (input) => {
+        const nodeId = envNodeId();
+        if (nodeId === undefined || nodeId === '')
+            throw new InputError({ error: 'no_node', message: 'no node to wait (CRTR_NODE_ID unset)', next: 'Run from inside the terminal node that is blocked.' });
+        const node = await getNodeOrNull(nodeId);
+        if (node === null)
+            throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, next: 'Run from a live canvas node.' });
+        if (node.lifecycle !== 'terminal')
+            throw new InputError({ error: 'resident_node', message: `node ${nodeId} is resident and may already dorm on its inbox`, next: 'Use this only from a terminal node that needs the stop guard to recognize a controller dependency.' });
+        const controller = String(input['controller']).trim();
+        if (controller === nodeId)
+            throw new InputError({ error: 'self_controller', message: 'a node cannot wait for its own message', field: 'controller', next: 'Name the parent or external controller expected to send the message.' });
+        // The server validates the controller exists + is live and records the wait
+        // (handleWait); a 404/422 surfaces as the clean CLI error.
+        await cliClient()
+            .waitNode(nodeId, { controller })
+            .catch((err) => rethrowAsCliError(err));
+        return { node_id: nodeId };
+    },
+    render: () => 'Waiting for the controller. End your turn to dorm; its next message wakes you and clears this wait.',
+});
+export const nodeWaitBranch = defineBranch({
+    name: 'wait',
+    description: 'declare a durable controller or deadline wait',
+    whenToUse: 'a terminal node must dorm for one named controller, or race its inbox against a self-scheduled deadline',
+    help: {
+        name: 'node wait',
+        summary: 'declare durable wait state; choose the event that settles it',
+        model: 'Both waits belong to the calling terminal node and settle on one future event. A controller wait records an existing node as the wake source; a deadline wait arms an urgent one-shot cron that races any earlier inbox delivery and is canceled when that delivery wins.',
+    },
+    children: [nodeWait, nodeWaitDeadline],
+});

package/dist/commands/node-context.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const nodeContextLeaf: LeafDef;

package/dist/commands/node-context.js

@@ -0,0 +1,145 @@
+// `crtr node inspect context` — browse this node's context dir and those of
+// every node it subscribes to, in one read-only nvim file explorer. Reports are
+// canvas documents (read with `crtr canvas read`), not files, so they are not here.
+//
+// crtr makes a STRONG CLAIM that nvim is installed (see
+// .crouter/memory/INDEX.md): the file explorer + file viewer are nvim, not a
+// hand-rolled view-contract surface.
+// We synthesize a temp dir of LABELLED NODE DIRS — `self` first, then one per
+// subscription — and place a `context` symlink inside each label dir
+// for the node's existing on-disk context dir. We then open `nvim -R` on the temp tree
+// (read-only: this is a viewer into siblings' state, edits never write back).
+// The symlinks are torn down when nvim exits; the real node dirs are untouched.
+//
+// Re-plumbed onto the API (Stage B-3): the ROSTER (self + the nodes it
+// subscribes to) comes from crtrd (`GET /v1/nodes/{id}/context`). The nvim
+// viewer tail stays a local viewer surface — the symlink tree uses the daemon's
+// resolved paths from the roster, and the on-disk existence filter is a local
+// fs read (neither opens canvas state). The /context popup
+// (src/pi-extensions/canvas-context.ts) shells this leaf inside a tmux
+// display-popup. Piped / non-TTY it prints the roster.
+import { envNodeId } from '../shared/env.js';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { nvimArgs, nvimAvailable } from '../core/nvim-launch.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+/** Make a node label safe as a directory name (netrw shows it verbatim). */
+function sanitize(s) {
+    return s.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'node';
+}
+/** Resolve the current node + every node it subscribes to into browse roots via
+ *  the API, which keeps only a node whose `context/` dir exists or that has reports.
+ *  `self` is always first and labelled `self-<name>`. */
+async function resolveRoots(selfId) {
+    const listing = await cliClient().getContext(selfId);
+    const roots = [];
+    for (const r of listing.roots) {
+        const ctx = r.dir;
+        const short = r.node_id.slice(0, 8);
+        const label = r.self ? `self-${sanitize(r.label)}` : `${sanitize(r.label)}-${short}`;
+        roots.push({
+            nodeId: r.node_id,
+            label,
+            dir: dirname(ctx),
+            self: r.self,
+            fileCount: r.files,
+            contextDir: ctx,
+        });
+    }
+    return roots;
+}
+/** Build a temp dir of labelled node dirs. Self's label is prefixed `0-` so it
+ *  sorts first in netrw; each label dir contains a `context` symlink when that
+ *  dir exists on disk. */
+function buildSymlinkTree(roots) {
+    const tree = mkdtempSync(join(tmpdir(), 'crtr-context-'));
+    for (const r of roots) {
+        const name = r.self ? `0-${r.label}` : r.label;
+        const nodeRoot = join(tree, name);
+        mkdirSync(nodeRoot, { recursive: true });
+        try {
+            if (existsSync(r.contextDir)) {
+                symlinkSync(r.contextDir, join(nodeRoot, 'context'), 'dir');
+            }
+        }
+        catch {
+            /* best-effort: a label collision or symlink failure just drops that node */
+        }
+    }
+    return tree;
+}
+export const nodeContextLeaf = defineLeaf({
+    name: 'context',
+    description: 'browse this node + its subscriptions’ context dirs in an nvim popup',
+    whenToUse: 'you want to SEE what the nodes you subscribe to have written — open a read-only nvim file explorer over this node’s context dir and every subscribed node’s context dir at once (reports are documents: `crtr canvas read <node>/reports/<name>`). The /context popup shells this. Piped it prints the roster instead',
+    help: {
+        name: 'node inspect context',
+        summary: 'open a read-only nvim file explorer over this node’s context dir and those of every node it subscribes to',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node id to root on. Defaults to $CRTR_NODE_ID (the calling node).' },
+        ],
+        output: [
+            { name: 'roots', type: 'object[]', required: true, constraint: 'Resolved browse roots: {node_id, label, dir, self, files}. Returned on the piped/non-TTY path.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'TTY: builds a temp dir of labelled node dirs, symlinking each available `context` dir inside it, then execs `nvim -R` on the tree; the temp links are removed on exit (real dirs untouched).',
+            'Requires nvim on PATH (a crtr strong dependency). Missing nvim -> error with an install hint.',
+            'Non-TTY / piped: prints the resolved roster and exits 0; opens nothing.',
+        ],
+    },
+    run: async (input) => {
+        const selfId = input['node']?.trim() || envNodeId();
+        if (selfId === undefined || selfId === '') {
+            throw new InputError({
+                error: 'no_node',
+                message: 'no current node: $CRTR_NODE_ID is unset and --node was not given',
+                field: 'node',
+                next: 'Run this from inside a canvas node (the /context popup does), or pass --node <id>.',
+            });
+        }
+        let roots;
+        try {
+            roots = await resolveRoots(selfId);
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+        const rosterOut = roots.map((r) => ({ node_id: r.nodeId, label: r.label, dir: r.dir, self: r.self, files: r.fileCount }));
+        // Non-TTY: print the roster and exit. Opens nothing.
+        if (!process.stdout.isTTY) {
+            return { roots: rosterOut };
+        }
+        if (!nvimAvailable()) {
+            throw new InputError({
+                error: 'nvim_missing',
+                message: 'nvim is not on PATH — `crtr node inspect context` opens the context explorer in nvim',
+                next: 'Install Neovim (macOS: `brew install neovim`; Debian/Ubuntu: `apt install neovim`), then retry.',
+            });
+        }
+        const tree = buildSymlinkTree(roots);
+        try {
+            // `nvim -R .` opens netrw (or the user's dir handler) read-only, cwd = the
+            // symlink tree, so the explorer roots on `self` + each subscription.
+            spawnSync('nvim', [...nvimArgs('readonly'), '.'], { cwd: tree, stdio: 'inherit' });
+        }
+        finally {
+            rmSync(tree, { recursive: true, force: true }); // removes symlinks only; targets untouched
+        }
+        return { roots: rosterOut };
+    },
+    render: (result) => {
+        const roots = result['roots'] ?? [];
+        if (roots.length === 0)
+            return 'No node dirs to show (no subscriptions with written context or reports, and this node’s own context dir is empty/absent).';
+        const lines = roots.map((r) => {
+            const tag = r['self'] === true ? ' (self)' : '';
+            return `  ${String(r['label'])}${tag}\t${String(r['files'])} files\t${String(r['dir'])}`;
+        });
+        return [`Context roots (${roots.length}):`, ...lines].join('\n');
+    },
+});

package/dist/commands/node-lifecycle-revive.d.ts

@@ -0,0 +1,12 @@
+import type { LeafDef } from '../core/command.js';
+import type { NodeFaultDTO } from '../api/dto/nodes.js';
+/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
+ *  (kick it early instead of waiting out the schedule), or any fault the
+ *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
+ *  disposition that otherwise has NO sanctioned recovery verb.
+ *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
+ *  (redialing) already in flight, and refuses any OTHER link — notably a
+ *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
+ *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
+export declare function isNowEligibleFault(fault: NodeFaultDTO | null): boolean;
+export declare const nodeReviveLeaf: LeafDef;

package/dist/commands/node-lifecycle-revive.js

@@ -0,0 +1,217 @@
+// `crtr node lifecycle revive` — bring back ONE named node.
+//
+// Bypasses the daemon: directly relaunches the broker engine for a node that is
+// done, idle, dead, or canceled. Default behavior resumes the saved pi
+// conversation by its absolute session-file path (--session <path>) when that
+// .jsonl still exists, else falls through to a fresh launch. `--fresh` skips
+// the true resume: if the `.jsonl` already exists it CYCLES in place instead
+// (same file, a fresh `crtr-cycle` branch — `resumed:false`), and only starts a
+// genuinely clean session when no `.jsonl` exists yet (also `resumed:false`).
+//
+// `--now` is the on-demand kick for a hanging node (live broker parked on an
+// eligible pi→provider fault): SIGTERM the broker so the daemon's own
+// crash→grace→resume path brings it back, instead of waiting out the schedule.
+//
+// The mass-recovery form — reconnect EVERY disconnected node at once after a
+// reboot/crash — is genuinely graph-wide and stays at `canvas revive --all`
+// (src/commands/revive.ts).
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { requireScope } from '../core/errors.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+// Purity (spec §1/§10, plan B-2): this leaf's transitive RUNTIME import graph
+// must never reach `core/canvas/db.ts` (`openDb`) or `core/canvas/canvas.ts`
+// accessors — a `crtr` CLI process never opens canvas.db. So the revive itself
+// goes through the daemon (`cliClient().reviveNode`), and every helper below is
+// imported from a db-free module: `recordedPidLiveness` (pid.js → fs/ps only),
+// `faultNeedsYou` (status-glyph.js → fault.js), and `fullName` from labels.js
+// DIRECTLY (NOT the canvas barrel `index.js`, which re-exports `openDb`).
+// View-socket readiness is checked by the daemon and returned in the revive
+// result: this process may sit in a sandbox that cannot see the target's
+// socket. The node's active fault and mid-turn state are projected fields on the detail DTO this leaf
+// already fetches. The former direct
+// `reviveNode`/`getNode`/`assertReopenGate`/`waitForBrokerViewSocket`/`isBusy`
+// imports all reached the db barrel and are replaced by the client call + helpers below.
+import { recordedPidLiveness } from '../core/canvas/pid.js';
+import { fullName } from '../core/canvas/labels.js';
+import { faultNeedsYou } from '../core/canvas/status-glyph.js';
+/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
+ *  (kick it early instead of waiting out the schedule), or any fault the
+ *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
+ *  disposition that otherwise has NO sanctioned recovery verb.
+ *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
+ *  (redialing) already in flight, and refuses any OTHER link — notably a
+ *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
+ *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
+export function isNowEligibleFault(fault) {
+    if (fault === null || fault.link !== 'pi→provider')
+        return false;
+    if (faultNeedsYou(fault))
+        return true;
+    return fault.retry.by === 'daemon';
+}
+export const nodeReviveLeaf = defineLeaf({
+    name: 'revive',
+    description: 'reopen a window for a done/idle/dead/canceled node',
+    whenToUse: 'you want to bring a dormant node back yourself — reopen a window for one that is done, idle, dead, or canceled: resume a node you closed with `node lifecycle close`, reopen a finished worker for a follow-up, or restart a crashed one now instead of waiting. It resumes the saved conversation by default, or can restart the node clean. You rarely need this for crashes — the daemon auto-revives those; reach for it to bring a node back on demand, to revive a canceled node the daemon will never touch on its own, or to kick a hanging one early (--now). To mass-reconnect EVERY disconnected node at once (after a reboot, a killed login/tmux session, or the daemon being down a while), use `canvas revive --all` instead',
+    help: {
+        name: 'node lifecycle revive',
+        summary: 'relaunch a node\'s broker engine (resuming its saved conversation), or kick a hanging one (--now)',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node',
+                required: true,
+                constraint: 'Node id to revive.',
+            },
+            {
+                kind: 'flag',
+                name: 'fresh',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'When set, do NOT do a true resume. If the node already has a session `.jsonl`, this instead CYCLES it in place — reuses that SAME file, resets the tree leaf, and roots a fresh `crtr-cycle` branch (a clean-context restart that still carries the file\'s history, output `resumed:false`). Only when no `.jsonl` exists yet does this start a genuinely brand-new session (also `resumed:false`). Default (no --fresh): a true resume — replays the existing `.jsonl` as-is (`resumed:true`).',
+            },
+            {
+                kind: 'flag',
+                name: 'now',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'On-demand kick of an active-fault node (parked on a `pi→provider` fault, broker still alive). Its broker pid is alive, so an ordinary revive no-ops (double-launch guard) — --now SIGTERMs the live broker instead, so the daemon\'s crash→grace→resume path brings it back in ~20s. Valid for a live `pi→provider` fault that is either a daemon-owned auto retry (kicks it early), or ANY fault the canvas dashboard flags "needs you" (e.g. exhausted retries, an auth fault you just fixed) — that disposition otherwise has no recovery verb. Mutually exclusive with --fresh.',
+            },
+            {
+                kind: 'flag',
+                name: 'reopen',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Clear a latched node\'s finalization latch (final_report/finalized_at only — the old report file and every delivered feed event are untouched) before reviving it. Rejected against a node that is not finalized. Mutually exclusive with --now.',
+            },
+        ],
+        output: [
+            { name: 'resumed', type: 'boolean', required: false, constraint: 'True ONLY for a true resume (the existing `.jsonl` replayed as-is). False for a --fresh revive, whether that landed as an in-place CYCLE (an existing `.jsonl` reused with a fresh `crtr-cycle` branch — pi is still told --session, but this is not a resume) or a genuinely fresh launch (no `.jsonl` existed). Absent for a --now kick.' },
+            { name: 'ready', type: 'boolean', required: false, constraint: 'True when the daemon saw the node\'s view.sock accept a connection within ~10s of the revive — the node is attachable. It does not show the task was delivered or the model is making progress. False when it did not (still starting, broker exited, or no free broker slot). Absent for a --now kick, and when the daemon predates this field (readiness unknown).' },
+            { name: 'kicked', type: 'boolean', required: false, constraint: 'True when --now SIGTERM\'d the hanging node\'s live broker (the daemon resumes it on the saved session within ~20s). Absent for an ordinary revive.' },
+            { name: 'message', type: 'string', required: false, constraint: 'Kick confirmation naming the signalled node, pid, and the daemon\'s ~20s resume handoff. Present only for --now.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Launches the node\'s detached headless broker engine (no tmux window).',
+            'Updates the node\'s canvas record: status=active, intent=null.',
+            'Waits up to ~10s for the daemon to see the broker\'s view.sock accept a connection, so `ready:true` means a caller can attach on return.',
+            '--now: SIGTERMs the live broker instead of launching anything (the daemon\'s own crash-grace path resumes it).',
+        ],
+    },
+    run: async (input) => {
+        requireScope('crtr:act', 'crtr node lifecycle revive');
+        const now = input['now'] ?? false;
+        const nodeId = input['node'];
+        const fresh = input['fresh'] ?? false;
+        const reopen = input['reopen'] ?? false;
+        if (now && reopen) {
+            throw new InputError({
+                error: 'conflicting_args',
+                message: '`--now` kicks a LIVE broker (nothing to reopen — a finalized node has no live broker); `--reopen` is meaningless there.',
+                next: 'Run `crtr node lifecycle revive <node> --now` on a hanging node, or `crtr node lifecycle revive <node> --reopen` (no --now) to re-task a finalized one.',
+            });
+        }
+        if (now && fresh) {
+            throw new InputError({
+                error: 'conflicting_args',
+                message: '`--now` kicks a live hanging broker (SIGTERM → daemon resumes the SAVED session); `--fresh` is meaningless there.',
+                next: 'Run `crtr node lifecycle revive <node> --now` (resumes), or `crtr node lifecycle revive <node> --fresh` (no --now) to relaunch clean.',
+            });
+        }
+        const client = cliClient();
+        // --now: the on-demand kick for an active fault. The broker is ALIVE (so an
+        // ordinary revive would no-op the double-launch guard) — SIGTERM it so the
+        // daemon's ordinary crash→grace→resume path recovers it on the saved session,
+        // the same thing the daemon does at the auto-recovery grace, just on demand.
+        // Gated on a live pid and an eligible pi→provider fault (`isNowEligibleFault`
+        // above) so it can't be used to nuke a healthy node. This whole path stays
+        // LOCAL: the kick is a direct SIGTERM to the broker pid (there is no revive
+        // API call), and the node detail comes from the daemon read (`getNode`). The
+        // reopen gate is NOT invoked here — --now targets a LIVE broker, and a
+        // finalized node has none (its own live-pid check below refuses it anyway).
+        if (now) {
+            // The detail DTO projects `pi_pid_identity` (the launch-time process-identity
+            // baseline captured alongside `pi_pid`), so the pid-reuse guard is intact:
+            // `recordedPidLiveness(pid, identity)` refuses to treat a recycled pid as
+            // "alive-and-ours", and the SIGTERM below only fires on a positively
+            // confirmed-alive-and-ours pid. Null identity (node predates the field, or
+            // launch-time capture failed) fails open to the trust-isPidAlive branch.
+            let detail;
+            try {
+                detail = await client.getNode(nodeId);
+            }
+            catch (e) {
+                rethrowAsCliError(e);
+            }
+            const pid = detail.pi_pid;
+            const stall = detail.fault ?? null;
+            if (pid == null || recordedPidLiveness(pid, detail.pi_pid_identity ?? null) !== 'alive') {
+                throw new InputError({
+                    error: 'not_hanging',
+                    message: `${nodeId} has no live broker — nothing to kick. --now is for a HANGING node (live broker parked on an active fault).`,
+                    next: 'Revive a dormant node with `crtr node lifecycle revive ' + nodeId + '` (no --now).',
+                });
+            }
+            if (!isNowEligibleFault(stall)) {
+                throw new InputError({
+                    error: 'not_hanging',
+                    message: `${nodeId} is live but has no pi→provider fault eligible for --now (either healthy, or a client-owned retry / non-provider fault already being handled elsewhere) — --now refuses to SIGTERM a node that isn't stuck on a kickable provider fault.`,
+                    next: 'Use --now only on a node the canvas shows as hanging (⚠) with a `pi→provider` fault. For a routine relaunch, omit --now.',
+                });
+            }
+            // The daemon never kills a BUSY engine (its verdict paths all return 'leave'
+            // on an open turn): a node mid-turn is making progress, not wedged —
+            // refuse rather than SIGTERM it mid-flight.
+            if (detail.streaming === true) {
+                throw new InputError({
+                    error: 'busy',
+                    message: `${nodeId} is mid-turn right now (busy) — --now refuses to SIGTERM a working engine; it has recovered on its own.`,
+                    next: 'Re-check the canvas — if it\'s no longer marked hanging (⚠), nothing to do.',
+                });
+            }
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch {
+                /* best-effort: the broker may have just died; the daemon owns the resume */
+            }
+            return {
+                kicked: true,
+                message: `Sent SIGTERM to ${fullName(detail)} (${nodeId}, pid ${pid}). The daemon will resume it on the saved session within ~20s (crash→grace→resume).`,
+            };
+        }
+        // Ordinary revive: the daemon relaunches the broker (the ONLY sanctioned
+        // launcher). Node-existence validation (`not_found`) and the reopen gate
+        // are both enforced server-side in `handleRevive`; a thrown gate/not-found
+        // error round-trips through `ApiError.details` and is reconstructed into the
+        // identical `InputError` by the shared `apiErrorToCliError` (via
+        // `rethrowAsCliError`).
+        // Wake provenance: when this leaf is running inside a cron's run (the daemon
+        // stamps CRTR_CRON_ID into every run's environment), forward that id so
+        // crtrd can inject the `<crtr-wake>` block and the revived node learns a
+        // CLOCK woke it, not a message. Absent outside a cron run.
+        const cronId = process.env['CRTR_CRON_ID'];
+        let result;
+        try {
+            result = await client.reviveNode(nodeId, {
+                resume: !fresh,
+                reopen,
+                ...(cronId !== undefined && cronId !== '' ? { cron_id: cronId } : {}),
+            });
+        }
+        catch (e) {
+            rethrowAsCliError(e);
+        }
+        return {
+            resumed: result.resumed,
+            // The daemon's own check. A daemon that predates the field sends none,
+            // and unknown readiness is not reported as true or false.
+            ...(result.ready !== undefined ? { ready: result.ready } : {}),
+        };
+    },
+});

package/dist/commands/node-snapshot.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const nodeSnapshotLeaf: LeafDef;

package/dist/commands/node-snapshot.js

@@ -0,0 +1,37 @@
+// `crtr node inspect snapshot` — read a dormant node's session snapshot without
+// launching its broker. Re-plumbed onto the API (Stage B-3): the session read
+// itself now runs server-side in crtrd (`GET /v1/nodes/{id}/snapshot`, backed by
+// `core/runtime/node-read.ts`); this leaf is a pure client.
+import { defineLeaf } from '../core/command.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+export const nodeSnapshotLeaf = defineLeaf({
+    name: 'snapshot',
+    description: 'read a dormant node session snapshot without launching its broker',
+    whenToUse: 'you need a read-only broker-compatible snapshot of a dormant node; it copies the session JSONL before parsing and never revives the node',
+    tier: 'hidden',
+    help: {
+        name: 'node inspect snapshot',
+        summary: 'read-only dormant node snapshot in the broker welcome shape',
+        params: [{ kind: 'positional', name: 'id', type: 'string', required: true, constraint: 'Canvas node id.' }],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node id.' },
+            { name: 'snapshot', type: 'object', required: true, constraint: 'BrokerSnapshot-compatible {messages, stats, state, display}; `display` is always empty here — extension display state is live broker process state, not persisted.' },
+            { name: 'commands', type: 'object[]', required: true, constraint: "Builtin slash commands only: {name,description,source:'builtin'}." },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: crtrd copies the session JSONL to a temp dir, parses the copy, then deletes the temp dir. Does not launch or revive brokers.'],
+        // Full session reconstruction (every message) for tooling, not a
+        // human/agent glance — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
+    },
+    run: async (input) => {
+        const id = input['id'];
+        try {
+            const dto = await cliClient().getSnapshot(id);
+            return { node_id: dto.node_id, snapshot: dto.snapshot, commands: dto.commands };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+});

package/dist/commands/node-transcript.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const nodeTranscriptLeaf: LeafDef;