@north-light/crouter 0.3.154

package/dist/commands/node-inspect-artifacts.js

@@ -0,0 +1,109 @@
+// `crtr node inspect artifacts` — enumerate one node's artifacts as refs.
+// Re-plumbed onto the API (Stage B-3): the artifact listing runs server-side in
+// crtrd (`GET /v1/nodes/{id}/artifacts?type=`). `--sort` is applied client-side
+// (the DTO carries the timestamp), and the byte-size suffix is reconstructed
+// client-side from each artifact's `<node-id>:<relpath>` ref via the pure
+// `nodeDir` path helper (the DTO deliberately omits size).
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { nodeDir } from '../core/canvas/paths.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+const TYPES = ['report', 'doc', 'roadmap', 'inbox'];
+/** Byte size of the file behind an artifact ref (`<node-id>:<relpath>`), or 0
+ *  when the ref is synthetic (inbox) or the file is unreadable — matching the
+ *  pre-API leaf, which sized only file-backed artifacts. */
+function sizeForRef(ref, source) {
+    if (source === 'inbox' || source === 'meta')
+        return 0;
+    const idx = ref.indexOf(':');
+    if (idx < 0)
+        return 0;
+    const nodeId = ref.slice(0, idx);
+    const relpath = ref.slice(idx + 1);
+    if (relpath === '' || relpath === 'meta')
+        return 0;
+    try {
+        return statSync(join(nodeDir(nodeId), relpath)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+export const nodeArtifactsLeaf = defineLeaf({
+    name: 'artifacts',
+    description: 'enumerate one node\'s artifacts as refs',
+    whenToUse: 'you have a node id and want to see everything it left behind — its reports and context docs as refs ready for `canvas history read`. The bridge from "found the node" to "read its artifacts". Use `node inspect show` instead for the node\'s topology/neighbors, not its content.',
+    help: {
+        name: 'node inspect artifacts',
+        summary: 'list one node\'s artifacts (reports + context docs) as refs ready for `canvas history read`',
+        params: [
+            { kind: 'positional', name: 'node-id', required: true, constraint: 'The node whose artifacts to list.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...TYPES], required: false, constraint: 'Narrow to one corpus: report | doc | roadmap | inbox. Default: report, doc, roadmap (inbox is opt-in only — the node\'s raw inbox.jsonl history, cursor-independent and including full un-clipped direct-message bodies; a diagnostic surface, not curated past work).' },
+            { kind: 'flag', name: 'sort', type: 'enum', choices: ['recency', 'oldest'], required: false, constraint: 'Order by artifact timestamp. Default recency.' },
+        ],
+        output: [
+            { name: 'node', type: 'string', required: true, constraint: 'Node name + id.' },
+            { name: 'artifacts', type: 'object[]', required: true, constraint: 'Each: {ref, source, ts, detail}. source = report:<kind> | doc | roadmap | inbox. detail = report title / doc heading + size (inbox: `[kind] label`, no size). ref passes verbatim to `canvas history read`.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nodeId = input['nodeId'].trim();
+        const type = input['type'];
+        const sort = input['sort'] ?? 'recency';
+        const client = cliClient();
+        let name;
+        let arts;
+        try {
+            // getNode both resolves the node name and enforces existence (404 → the
+            // clean not_found payload); getArtifacts serves the (optionally narrowed)
+            // corpus. Both round-trips run against the same daemon read.
+            const [detail, list] = await Promise.all([
+                client.getNode(nodeId),
+                client.getArtifacts(nodeId, type !== undefined ? { type } : undefined),
+            ]);
+            name = detail.name;
+            arts = list.artifacts;
+        }
+        catch (err) {
+            rethrowAsCliError(err, 'List nodes with `crtr node inspect list`, or find one with `canvas history search`.');
+        }
+        const ms = (ts) => Date.parse(ts) || 0;
+        arts.sort((a, b) => (sort === 'oldest' ? ms(a.ts) - ms(b.ts) : ms(b.ts) - ms(a.ts)) || a.ref.localeCompare(b.ref));
+        const artifacts = arts.map((a) => {
+            const size = sizeForRef(a.ref, a.source);
+            return {
+                ref: a.ref,
+                source: a.source,
+                ts: a.ts,
+                detail: a.title + (size > 0 ? `  (${size}B)` : ''),
+            };
+        });
+        return {
+            node: `${name} (${nodeId})`,
+            artifacts,
+            follow_up: 'Read one with `canvas history read <ref>`; reopen the node with `node lifecycle revive ' + nodeId + '`.',
+        };
+    },
+    render: (r) => {
+        const arts = r['artifacts'];
+        const parts = [`node: ${r['node']}`];
+        if (arts.length === 0) {
+            parts.push('0 artifacts.');
+        }
+        else {
+            const cols = Object.keys(arts[0]);
+            const head = `| ${cols.join(' | ')} |`;
+            const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+            const body = arts
+                .map((a) => `| ${cols.map((c) => String(a[c] ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ')).join(' | ')} |`)
+                .join('\n');
+            parts.push(`${arts.length} artifacts:\n\n${head}\n${sep}\n${body}`);
+        }
+        parts.push(String(r['follow_up']));
+        return parts.join('\n\n');
+    },
+});

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

@@ -0,0 +1,12 @@
+import type { LeafDef } from '../core/command.js';
+import type { Fault } from '../core/runtime/fault.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 (issue #115).
+ *  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: Fault | null): boolean;
+export declare const nodeReviveLeaf: LeafDef;

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

@@ -0,0 +1,287 @@
+// `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 { createConnection } from 'node:net';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.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),
+// `readFault` (fault.js → paths.js pure helpers + events), `faultNeedsYou`
+// (status-glyph.js → fault.js), and `fullName` from labels.js DIRECTLY (NOT the
+// canvas barrel `index.js`, which re-exports `openDb`). `viewSocketPath`/`jobDir`
+// are pure path helpers (allowed). The former direct `reviveNode`/`getNode`/
+// `assertReopenGate`/`waitForBrokerViewSocket`/`isBusy` imports all reached the
+// db barrel and are replaced by the client call + the inlined helpers below.
+import { recordedPidLiveness } from '../core/canvas/pid.js';
+import { readFault } from '../core/runtime/fault.js';
+import { fullName } from '../core/canvas/labels.js';
+import { faultNeedsYou } from '../core/canvas/status-glyph.js';
+import { viewSocketPath, jobDir } from '../core/canvas/paths.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 (issue #115).
+ *  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';
+}
+// ---------------------------------------------------------------------------
+// Local, db-free helpers (inlined so the leaf never imports the canvas barrel)
+// ---------------------------------------------------------------------------
+const VIEW_SOCKET_WAIT_MS = 30_000;
+const VIEW_SOCKET_RETRY_MS = 100;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Inlined from `runtime/busy.ts` (which reaches the canvas barrel via `jobDir`):
+ *  is the node mid-turn right now? `<jobDir>/busy` exists for the span pi is
+ *  inside a run. `jobDir` here is the PURE path helper from paths.js. */
+function nodeIsBusy(nodeId) {
+    return existsSync(join(jobDir(nodeId), 'busy'));
+}
+/** Copy of `placement.ts`'s `probeBrokerViewSocket` (placement reaches the canvas
+ *  barrel, so it cannot be imported here): resolve true iff the socket accepts a
+ *  connection within `timeoutMs`. */
+function probeViewSocket(sockPath, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let socket = null;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            if (socket !== null)
+                socket.destroy();
+            resolve(ok);
+        };
+        try {
+            socket = createConnection(sockPath);
+        }
+        catch {
+            finish(false);
+            return;
+        }
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+        socket.setTimeout(timeoutMs, () => finish(false));
+    });
+}
+/** Drop-in for `placement.ts`'s `waitForBrokerViewSocket` (sans the broker-exit
+ *  race — the CLI leaf drives the revive over the daemon and holds no launch
+ *  handle). Poll the node's view.sock until it accepts a connection or the
+ *  deadline passes; a `connect` (not mere file existence) proves a live listener,
+ *  so the caller can attach/dial immediately on return. */
+async function waitForViewSocketReady(nodeId) {
+    const sockPath = viewSocketPath(nodeId);
+    const deadline = Date.now() + VIEW_SOCKET_WAIT_MS;
+    while (Date.now() <= deadline) {
+        if (await probeViewSocket(sockPath, VIEW_SOCKET_RETRY_MS))
+            return true;
+        await sleep(VIEW_SOCKET_RETRY_MS);
+    }
+    return false;
+}
+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: 'window', type: 'string', required: false, constraint: 'Always null — the revived broker is headless and opens no tmux window. Kept for caller back-compat.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The node\'s last live location session, or null — the headless broker has no tmux session of its own.' },
+            { 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 revived broker\'s view.sock accepted a connection before return — the node is immediately attachable/drivable. Absent for a --now kick.' },
+            { 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.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Launches the node\'s detached headless broker engine (no tmux window).',
+            'Updates the node\'s canvas record: status=active, intent=null.',
+            'Blocks until the broker\'s view.sock accepts a connection (up to ~30s), so a caller can attach/dial immediately on return.',
+            '--now: SIGTERMs the live broker instead of launching anything (the daemon\'s own crash-grace path resumes it).',
+        ],
+    },
+    run: async (input) => {
+        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 (#339) 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 = readFault(nodeId);
+            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 a live busy marker): a node mid-turn is making progress, not wedged —
+            // refuse rather than SIGTERM it mid-flight.
+            if (nodeIsBusy(nodeId)) {
+                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 {
+                window: null,
+                // The DTO carries no `tmux_session` (the headless broker has none); the
+                // pre-API leaf returned `meta.tmux_session ?? null`, which is null here.
+                session: null,
+                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 #339 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);
+        }
+        // The revive route returns once the broker process is launched, which can be
+        // seconds before its view.sock listens. Callers (attach, the web shell's Wake)
+        // dial immediately on return, so block here until the socket accepts.
+        const ready = await waitForViewSocketReady(nodeId);
+        return {
+            // Always null (broker headless, no tmux window); `undefined` omits it from
+            // the JSON payload, matching the pre-API leaf's `result.window ?? undefined`.
+            window: undefined,
+            // The revive DTO carries no location session (the headless broker has none);
+            // the pre-API leaf returned `result.session`, which was null here.
+            session: null,
+            resumed: result.resumed,
+            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;

package/dist/commands/node-transcript.js

@@ -0,0 +1,62 @@
+// `crtr node inspect transcript` — read a node's saved conversation without
+// reviving its broker. The transcript is rendered into a temporary Markdown
+// file and opened read-only in nvim; the persisted session and canvas row are
+// never changed.
+//
+// Re-plumbed onto the API (Stage B-3): the markdown is rendered server-side in
+// crtrd (`GET /v1/nodes/{id}/transcript`, backed by `core/runtime/node-read.ts`).
+// The nvim viewer tail stays local (a viewer surface, not canvas state).
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+function nvimAvailable() {
+    const r = spawnSync('nvim', ['--version'], { stdio: 'ignore' });
+    return r.error === undefined && (r.status === 0 || r.status === null);
+}
+export const nodeTranscriptLeaf = defineLeaf({
+    name: 'transcript',
+    description: 'read a node’s saved conversation without reviving it',
+    whenToUse: 'you have a node id and need to inspect its past conversation without changing its lifecycle or launching an agent',
+    help: {
+        name: 'node inspect transcript',
+        summary: 'open a node’s saved conversation read-only in nvim; never launches or revives its broker',
+        params: [{ kind: 'positional', name: 'node-id', required: true, constraint: 'The node whose saved conversation to inspect.' }],
+        output: [{ name: 'transcript', type: 'string', required: true, constraint: 'Markdown transcript on the non-TTY path.' }],
+        outputKind: 'object',
+        effects: ['TTY: opens a temporary read-only nvim buffer and deletes it after exit. Non-TTY: prints the transcript. Never changes node status or starts a broker.'],
+    },
+    run: async (input) => {
+        const nodeId = input['nodeId'];
+        let transcript;
+        try {
+            transcript = (await cliClient().getTranscript(nodeId)).markdown;
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+        if (!process.stdout.isTTY)
+            return { transcript };
+        if (!nvimAvailable()) {
+            throw new InputError({
+                error: 'nvim_missing',
+                message: 'nvim is not on PATH — `crtr node inspect transcript` opens saved conversations in nvim',
+                next: 'Install Neovim, then retry.',
+            });
+        }
+        const dir = mkdtempSync(join(tmpdir(), 'crtr-transcript-'));
+        const path = join(dir, 'transcript.md');
+        try {
+            writeFileSync(path, transcript);
+            spawnSync('nvim', ['-R', path], { stdio: 'inherit' });
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        return { transcript };
+    },
+    render: (result) => String(result['transcript']),
+});

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

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

package/dist/commands/node-worktree.js

@@ -0,0 +1,102 @@
+// `crtr node worktree` — the node-owned managed-worktree lifecycle. Birth is
+// `node new --worktree <base>`; this branch holds the single close
+// verb, symmetric with birth, so a git worktree's whole lifecycle sits under
+// `node`.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { ApiError } from '../api/index.js';
+import { cliClient } from './api-client.js';
+function requireCallerNode() {
+    const id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id.trim() === '') {
+        throw new InputError({
+            error: 'no_node_context',
+            message: 'CRTR_NODE_ID is not set — worktree commands run inside a canvas node.',
+            next: 'Run this command from a node process spawned by the runtime.',
+        });
+    }
+    return id.trim();
+}
+// The worktree leaf preserves a RICHER error contract than the generic
+// `rethrowAsCliError`: the daemon's `handlers/worktree.ts` rethrows the core
+// `WorktreeError`'s SPECIFIC code (`dirty_worktree`, `rebase_failed`,
+// `no_managed_worktree`, `unknown_node`, …) as a `CrtrError` carrying
+// `details.{next,received}`, which survive `toErrorBody` into the response.
+// So we surface the code/next/received verbatim rather than collapsing to a
+// status bucket — keeping the pre-API agent-facing contract byte-for-byte.
+function mapWorktreeApiError(err) {
+    if (err instanceof ApiError) {
+        const details = (err.details ?? {});
+        throw new InputError({
+            error: err.code,
+            message: err.message,
+            ...(typeof details.received === 'string' ? { received: details.received } : {}),
+            next: typeof details.next === 'string'
+                ? details.next
+                : 'Inspect the error and adjust the call. See -h for the schema.',
+        });
+    }
+    throw err;
+}
+const worktreeClose = defineLeaf({
+    name: 'close',
+    description: 'land and close the current node-managed worktree',
+    whenToUse: 'you are inside the node that owns an open managed worktree and are ready to rebase it onto its recorded local base branch, fast-forward that base onto it, and (best-effort) remove the worktree and delete the branch before finishing',
+    help: {
+        name: 'node worktree close',
+        summary: 'land and close the current node-managed worktree',
+        params: [],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The caller node id whose managed worktree was closed.' },
+            { name: 'branch', type: 'string', required: true, constraint: 'The worktree branch that was fast-forwarded into its recorded local base branch.' },
+            { name: 'landed_sha', type: 'string', required: true, constraint: 'The commit SHA that the recorded local base branch was fast-forwarded onto.' },
+            { name: 'worktree_path', type: 'string', required: true, constraint: 'The managed worktree path that was closed (best-effort removed; see worktree_removed).' },
+            { name: 'worktree_removed', type: 'boolean', required: true, constraint: 'True when the worktree directory was removed; false means the landing still happened (the close is done) but automatic removal failed and needs a manual follow-up.' },
+            { name: 'worktree_remove_error', type: 'string', required: false, constraint: 'Present only when worktree_removed is false: the manual cleanup command to run.' },
+            { name: 'branch_deleted', type: 'boolean', required: true, constraint: 'True when the local branch was deleted; false means the landing still happened (the close is done) but the local branch cleanup failed and needs a manual follow-up.' },
+            { name: 'branch_delete_error', type: 'string', required: false, constraint: 'Present only when branch_deleted is false: the manual cleanup command to run.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Rebases the worktree onto its recorded local base branch, fast-forwards that base onto it (never pushes to origin), marks the node-managed worktree closed, then attempts (best-effort) to remove the worktree and delete the local branch.',
+        ],
+    },
+    run: async () => {
+        const nodeId = requireCallerNode();
+        try {
+            return { ...(await cliClient().closeWorktree(nodeId)) };
+        }
+        catch (err) {
+            mapWorktreeApiError(err);
+        }
+    },
+    render: (r) => {
+        const branch = String(r['branch'] ?? '');
+        const sha = String(r['landed_sha'] ?? '');
+        const path = String(r['worktree_path'] ?? '');
+        let base = `Managed worktree landed — its local base branch fast-forwarded to ${branch} at ${sha}.`;
+        const notes = [];
+        if (r['worktree_removed'] === false) {
+            notes.push(String(r['worktree_remove_error'] ?? `worktree checkout at ${path} could not be removed automatically.`));
+        }
+        else {
+            base += ` Worktree removed at ${path}.`;
+        }
+        if (r['branch_deleted'] === false) {
+            notes.push(String(r['branch_delete_error'] ?? `local branch ${branch} could not be deleted automatically.`));
+        }
+        if (notes.length > 0)
+            return `${base} Note: ${notes.join(' ')}`;
+        return base;
+    },
+});
+export const nodeWorktreeBranch = defineBranch({
+    name: 'worktree',
+    description: 'manage a node-owned git worktree — close the one born by `node new --worktree <base>`',
+    whenToUse: 'you are inside a node that was spawned with `node new --worktree <base>` and are ready to land it: rebase onto its recorded local base branch, fast-forward that base onto it, and close the worktree. Symmetric with `node new --worktree <base>`, which births it',
+    help: {
+        name: 'node worktree',
+        summary: 'manage a node-owned git worktree — birth is `node new --worktree <base>`; this branch closes it',
+    },
+    children: [worktreeClose],
+});