@north-light/api 0.3.580 → 0.3.587

package/dist/commands/push.js

@@ -0,0 +1,263 @@
+// `crtr push` — the one verb up the graph.
+//
+//   crtr push update [body]   — report progress to subscribers
+//   crtr push final  [body]   — finish: write result, mark node done, close window
+//   crtr push result [json]   — answer a pending structured-output request
+//
+// "push" is THE verb a node uses to talk to its managers. `update` reports
+// progress; its --tier sets delivery urgency. The caller's node is resolved from
+// CRTR_NODE_ID (injected by the runtime into every node process). Absent ⇒
+// InputError — push is only meaningful inside a live node.
+//
+// STAGE B-5: this verb is a PURE crtrd API client. Every report goes through
+// `POST /nodes/{id}/reports` (`client.pushReport`); the report file write, the
+// per-subscriber inbox fan, and (final only) the lifecycle transition all happen
+// server-side inside feed `push()` (spec §7.4). This file reaches ZERO canvas
+// state-store code — no `core/feed`, no `core/canvas` accessors, no
+// `core/worktree`. The only node identity read is `CRTR_NODE_ID` (client-side).
+import { envNodeId } from '../shared/env.js';
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError, readStdinRaw } from '../core/io.js';
+import { ApiError } from '../api/index.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+function requireCallerNode() {
+    const id = envNodeId();
+    if (id === undefined || id.trim() === '') {
+        throw new InputError({
+            error: 'no_node_context',
+            message: 'CRTR_NODE_ID is not set — push runs inside a canvas node.',
+            next: 'Run push from a node process spawned by the runtime.',
+        });
+    }
+    return id.trim();
+}
+const PUSH_BLURB = {
+    update: 'report progress to subscribers',
+    final: 'finish: write the canonical result, mark the node done, close its window',
+};
+const PUSH_WHEN_TO_USE = {
+    update: 'you have progress worth surfacing to your managers while work remains in flight. Use normal delivery unless it can wait for their next real wake (--tier deferred) or needs immediate attention (--tier urgent); use push final only when the work is actually done.',
+    final: 'the work this node was spawned to do is complete and you are ready to hand back the canonical result — this writes that result, marks the node done, and closes its window, so it is the LAST thing you do here, not a progress note. Use push update while work is still in flight, and do not reach for final on a node working directly with the user: it has no manager to report up to and would close mid-conversation (the guard blocks it unless you pass --force after the user confirms).',
+};
+/** `crtr push result` — submit the JSON answer to a pending structured-output
+ *  request. A pure API client like its siblings: JSON is parsed client-side
+ *  only to fail fast with a clean error; validation against the schema, the
+ *  result write, the report push, and the schema clear all happen server-side
+ *  in `POST /nodes/{id}/result`. */
+function makeResultLeaf() {
+    return defineLeaf({
+        name: 'result',
+        description: 'answer a pending structured-output request with the required JSON result, or decline it',
+        whenToUse: 'your system prompt names a pending structured-output request you must answer. The value is validated against the required schema server-side; a mismatch rejects with field errors and records nothing, so fix and rerun. When the schema cannot be honestly satisfied (blocked, unavailable, bad input), pass `--decline "<reason>" --code <token>` (plus `--retryable` when the same request could succeed later) instead of inventing a value; your requester names the code tokens it accepts. For a terminal request either path IS how the node finishes — never call `crtr push final` alongside it.',
+        help: {
+            name: 'push result',
+            summary: 'answer a pending structured-output request',
+            params: [
+                { kind: 'stdin', name: 'value', required: false, constraint: "The JSON result. Pipe it from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes. Required unless `--decline` is passed." },
+                { kind: 'flag', name: 'request', type: 'string', required: true, constraint: 'The request id from the structured-output instruction. It binds this result to that exact request; crouter never selects a pending request implicitly.' },
+                { kind: 'flag', name: 'decline', type: 'string', required: false, constraint: 'Decline instead of answering: one plain sentence on why the schema cannot be honestly satisfied (blocked, unavailable, bad input). Requires `--code`. Records a failure outcome with reason `declined` carrying the reason, code, and retryable flag, and clears the request; for a terminal request this finishes the node.' },
+                { kind: 'flag', name: 'code', type: 'string', required: false, constraint: 'With `--decline`: one whitespace-free token (≤ 64 chars) naming the decline class. crouter carries it verbatim; the requester validates it against the tokens it documented for you.' },
+                { kind: 'flag', name: 'retryable', type: 'bool', required: false, default: false, constraint: 'With `--decline`: the same request could succeed if issued again later (a transient block). Omit when the decline is final for this input.' },
+            ],
+            output: [
+                { name: 'mode', type: 'string', required: true, constraint: 'Which request this answered: `terminal` finished the node; `oneoff` left it working.' },
+                { name: 'declined', type: 'object', required: false, constraint: 'Present only when the request was declined: { reason, code, retryable } as recorded.' },
+                { name: 'report', type: 'string', required: true, constraint: 'Name of the report document pushed alongside the result, `<node-id>/reports/<name>`.' },
+                { name: 'notified', type: 'string[]', required: true, constraint: 'Subscriber node ids that received an inbox pointer.' },
+                { name: 'transitioned', type: 'object', required: false, constraint: 'Present only for a terminal request that flipped the node — { from, to } lifecycle-status transition applied server-side.' },
+            ],
+            outputKind: 'object',
+            effects: [
+                'Validates the value against the pending schema server-side; a mismatch records nothing and the request stays pending.',
+                'Records the accepted result (or the decline) on the pending request and clears it.',
+                'A terminal decline records a `failure` outcome with reason `declined` whose `declined` field carries { reason, code, retryable }; the requester sees no value.',
+                'Pushes the mode-matched report: final for a terminal request (the node finishes — same effects as `push final`), update for a one-off request (the node keeps working).',
+            ],
+        },
+        run: async (input) => {
+            const nodeId = requireCallerNode();
+            const requestId = typeof input['request'] === 'string' ? input['request'].trim() : '';
+            if (requestId === '') {
+                throw new InputError({ error: 'request_id_required', message: 'a structured result needs its request id', field: 'request', next: 'Copy the request id named in the structured-output instruction and rerun with `--request <request-id>`.' });
+            }
+            const decline = typeof input['decline'] === 'string' ? input['decline'].trim() : '';
+            const code = typeof input['code'] === 'string' ? input['code'].trim() : '';
+            let request;
+            if (decline !== '') {
+                if (code === '') {
+                    throw new InputError({ error: 'missing_decline_code', message: 'a decline needs a code', field: 'code', next: 'Pass `--code <token>` — the whitespace-free token your requester documented for this decline class.' });
+                }
+                request = { request_id: requestId, decline, code, retryable: input['retryable'] === true };
+            }
+            else {
+                if (code !== '' || input['retryable'] === true) {
+                    throw new InputError({ error: 'decline_flags_without_decline', message: '--code and --retryable only apply with --decline', next: 'Pass `--decline "<reason>"` alongside them, or drop them and submit the JSON result.' });
+                }
+                let raw = typeof input['value'] === 'string' ? input['value'].trim() : '';
+                if (raw === '')
+                    raw = (await readStdinRaw()).trim();
+                if (raw === '') {
+                    throw new InputError({ error: 'missing_value', message: 'no result value', field: 'value', next: 'Pass the JSON result as an argument or on stdin, or `--decline "<reason>" --code <token>` when the schema cannot be honestly satisfied.' });
+                }
+                let value;
+                try {
+                    value = JSON.parse(raw);
+                }
+                catch (err) {
+                    throw new InputError({
+                        error: 'bad_result_json',
+                        message: `the result is not valid JSON: ${err.message}`,
+                        field: 'value',
+                        next: 'Pass one valid JSON value matching the requested schema.',
+                    });
+                }
+                request = { request_id: requestId, value };
+            }
+            try {
+                const result = await cliClient().submitResult(nodeId, request);
+                return {
+                    mode: result.mode,
+                    report: result.report,
+                    notified: result.notified,
+                    ...(result.declined === undefined ? {} : { declined: result.declined }),
+                    ...(result.transitioned !== undefined ? { transitioned: result.transitioned } : {}),
+                    ...(result.worktree_auto_dropped === true
+                        ? { worktree_auto_dropped: true, worktree_auto_dropped_path: result.worktree_auto_dropped_path }
+                        : {}),
+                };
+            }
+            catch (err) {
+                rethrowAsCliError(err);
+            }
+        },
+        render: (r) => {
+            const declined = r['declined'];
+            const line = r['mode'] === 'terminal'
+                ? `${declined ? 'Decline recorded' : 'Result recorded'} — node finished; its engine shuts down on next stop. Nothing more to do here: STOP your turn immediately. Reply with just "Done." and nothing else.`
+                : `${declined ? 'One-off request declined' : 'One-off result recorded'} and pushed — the structured-output gate is cleared; continue working normally.`;
+            const declinedLine = declined === undefined ? '' : `\n- code: ${declined.code} (${declined.retryable ? 'retryable' : 'not retryable'})`;
+            return `${line}\n\n- report: ${r['report']}${declinedLine}`;
+        },
+    });
+}
+function makePushLeaf(kind) {
+    return defineLeaf({
+        name: kind,
+        description: PUSH_BLURB[kind],
+        whenToUse: PUSH_WHEN_TO_USE[kind],
+        help: {
+            name: `push ${kind}`,
+            summary: PUSH_BLURB[kind],
+            params: [
+                { kind: 'stdin', name: 'body', required: true, constraint: "Report body (markdown). Pipe it from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes." },
+                ...(kind === 'update'
+                    ? [{ kind: 'flag', name: 'tier', type: 'enum', choices: ['deferred', 'normal', 'urgent'], required: false, default: 'normal', constraint: 'Delivery urgency: deferred holds for the receiver’s next non-deferred wake; normal wakes normally; urgent steers a live receiver and wakes an idle receiver.' }]
+                    : [{ kind: 'flag', name: 'force', type: 'bool', required: false, default: false, constraint: 'Override the guard that blocks `push final` on a node the user is attending (a resident with no one to report up to). Only pass this after the user explicitly confirms they want this node finished.' }]),
+            ],
+            output: [
+                { name: 'report', type: 'string', required: true, constraint: 'Name of the written report document, `<node-id>/reports/<name>`.' },
+                { name: 'notified', type: 'string[]', required: true, constraint: 'Subscriber node ids that received an inbox pointer.' },
+                ...(kind === 'final'
+                    ? [
+                        { name: 'transitioned', type: 'object', required: false, constraint: 'Present only for a final that flipped the node — { from, to } lifecycle-status transition applied server-side.' },
+                        { name: 'worktree_auto_dropped', type: 'boolean', required: false, constraint: 'Present only when the server closed this node’s managed-worktree record without requiring `node worktree close`; cleanup of an existing checkout remains pending (see worktree_auto_dropped_path).' },
+                        { name: 'worktree_auto_dropped_path', type: 'string', required: false, constraint: 'Present only alongside worktree_auto_dropped: the closed worktree path; an existing checkout remains until pending cleanup.' },
+                    ]
+                    : []),
+            ],
+            outputKind: 'object',
+            effects: [
+                'Creates the report document `<node-id>/reports/<compact-ts>-<uuid8>-<kind>` (server-side).',
+                'Appends one inbox pointer per subscriber.',
+                ...(kind === 'final'
+                    ? [
+                        'Marks the node done (status + intent) server-side; its engine shuts down on next stop.',
+                        'When this node owns a clean managed worktree already contained in its local base, the server closes its record with cleanup pending instead of blocking on `node worktree close`. A clean worktree whose exact tip exists on any branch on origin may also finalize while retaining its branch and checkout; uncommitted changes or a tip absent from origin still block with open_managed_worktree.',
+                    ]
+                    : []),
+            ],
+        },
+        run: async (input) => {
+            const nodeId = requireCallerNode();
+            let body = typeof input['body'] === 'string' ? input['body'].trim() : '';
+            if (body === '')
+                body = (await readStdinRaw()).trim();
+            if (body === '') {
+                throw new InputError({ error: 'missing_body', message: 'no report body', field: 'body', next: 'Pass the body as an argument or on stdin.' });
+            }
+            const client = cliClient();
+            // A RESIDENT node with no subscribers is human-driven and has no one to
+            // submit a canonical result to: `push final` fans to subscribers, and a
+            // resident root conversation has none. Finishing it would shut its engine
+            // down mid-conversation. Block that unless the user confirms (--force).
+            // Keyed on lifecycle, NOT subscriber-count alone: a TERMINAL node with no
+            // subscribers was deliberately terminalized to owe a final — it
+            // self-completes server-side. This preflight reads the node through the
+            // API (NodeDetailDTO), never canvas.db — no state-store reach.
+            if (kind === 'final' && input['force'] !== true) {
+                let detail = null;
+                try {
+                    detail = await client.getNode(nodeId);
+                }
+                catch (err) {
+                    // A 404 here means the push itself will surface the canonical
+                    // unknown-node error — fall through and let it. Any other API failure
+                    // is a real problem worth surfacing now.
+                    if (!(err instanceof ApiError && err.status === 404)) {
+                        rethrowAsCliError(err);
+                    }
+                }
+                if (detail !== null && detail.lifecycle === 'resident' && detail.edges.subscribers.length === 0) {
+                    throw new InputError({
+                        error: 'no_final_recipient',
+                        message: 'This node is working directly with the user — it has no manager to submit a final result to. `push final` would end the conversation mid-stream.',
+                        next: 'You almost certainly do NOT need to finish here — just keep working with the user. If the user has explicitly asked you to finish and close this node, confirm with them first, then rerun with `crtr push final --force "<result>"`.',
+                    });
+                }
+            }
+            try {
+                const deliveryTier = input['tier'];
+                const result = await client.pushReport(nodeId, {
+                    tier: kind,
+                    body,
+                    ...(deliveryTier === undefined ? {} : { delivery_tier: deliveryTier }),
+                });
+                return {
+                    report: result.report,
+                    notified: result.notified,
+                    ...(result.transitioned !== undefined ? { transitioned: result.transitioned } : {}),
+                    ...(result.worktree_auto_dropped === true
+                        ? { worktree_auto_dropped: true, worktree_auto_dropped_path: result.worktree_auto_dropped_path }
+                        : {}),
+                };
+            }
+            catch (err) {
+                rethrowAsCliError(err);
+            }
+        },
+        render: (r) => {
+            const n = Array.isArray(r['notified']) ? r['notified'].length : 0;
+            const line = kind === 'final'
+                ? 'Result recorded — node finished; its engine shuts down on next stop. Nothing more to do here: STOP your turn immediately. Reply with just "Done." and nothing else.'
+                : `Progress report fanned to ${n} subscriber(s).`;
+            const dropNote = r['worktree_auto_dropped'] === true ? `\n\nClosed a clean managed-worktree record at ${String(r['worktree_auto_dropped_path'])} — nothing to land; cleanup remains pending if the checkout still exists.` : '';
+            return `${line}\n\n- report: ${r['report']}${dropNote}`;
+        },
+    });
+}
+export function registerPush() {
+    return defineBranch({
+        name: 'push',
+        rootEntry: {
+            concept: 'the one verb up the graph — a node reports to whoever subscribes to it',
+            desc: 'push an update or final report to your subscribers',
+            useWhen: 'sharing progress, raising an alert, or finishing your work',
+        },
+        help: {
+            name: 'push',
+            summary: 'push a report to your subscribers',
+            model: "A push writes a report document the node owns and fans a lightweight pointer to every subscriber's inbox. Delivery inlines reports under 1,000 characters; a longer report is read with `crtr canvas read <name>`. Point at documents you wrote as `[[<node-id>/<name>]]`, never as a file path. Nothing is pushed automatically — the feed contains only what a node pushes explicitly, so push whenever you want a manager to see something. Pipe markdown via a single-quoted heredoc so it reaches the report literally. `push final` is how ANY node finishes: write the canonical result, mark done, close the window.",
+        },
+        children: [makePushLeaf('update'), makePushLeaf('final'), makeResultLeaf()],
+    });
+}

package/dist/commands/revive.d.ts

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

package/dist/commands/revive.js

@@ -0,0 +1,183 @@
+// `crtr canvas revive` — mass node recovery.
+//
+// Sweeps EVERY disconnected node (engine not running, resumable session) in
+// one shot — the recovery for a reboot / mass-crash / daemon-down-a-while
+// event. It is a two-step gate: run it once to PREVIEW the candidates
+// (nothing is launched), then confirm to actually revive them.
+//
+// Reviving ONE named node is a per-node lifecycle action and lives instead at
+// `crtr node lifecycle revive <id>` (src/commands/node-lifecycle-revive.ts).
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { requireScope } from '../core/errors.js';
+import { cliClient } from './api-client.js';
+import { routes } from '../api/index.js';
+// Purity (spec §1/§10, plan B-2): a `crtr` CLI process never opens canvas.db, so
+// this leaf's transitive RUNTIME import graph must not reach `core/canvas/db.ts`
+// or `core/canvas/canvas.ts`. The pre-API imports — `listDisconnected`/`reviveAll`
+// (revive-all.js) and `getNode`/`fullName` (the canvas barrel index.js) — all
+// reached `openDb`, so they are replaced by: the daemon client (`cliClient`),
+// `fullName` from labels.js DIRECTLY (labels.ts has zero runtime imports), and
+// `recordedPidLiveness` (pid.js → fs/ps only). The disconnected PREVIEW predicate
+// is re-implemented client-side over the API's node projections; the authoritative
+// sweep is the daemon's own `POST /nodes/revive-all` (which runs `reviveAll()`
+// server-side).
+import { fullName } from '../core/canvas/labels.js';
+import { recordedPidLiveness } from '../core/canvas/pid.js';
+// revive --all
+export const reviveLeaf = defineLeaf({
+    name: 'revive',
+    description: 'mass-reconnect every disconnected node',
+    whenToUse: 'you need to bring back EVERY disconnected node at once (engine not running but a saved session intact) — the recovery after a reboot, a killed login/tmux session, a mass crash, or the daemon being down a while. You rarely need this for an ordinary crash — the daemon auto-revives those. To bring back ONE named node (a follow-up on a finished worker, a canceled node, or an on-demand kick of a hanging one), use `node lifecycle revive <id>` instead',
+    help: {
+        name: 'canvas revive',
+        summary: 'mass-reconnect every disconnected node (engine not running, resumable saved session)',
+        params: [
+            {
+                kind: 'flag',
+                name: 'all',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Required (rejected without it) — confirms this is the graph-wide sweep, not a typo for a single-node revive (that lives at `node lifecycle revive <id>`). Excludes done/canceled (terminal-by-choice). Run it once to PREVIEW the candidates; nothing is launched until you confirm.',
+            },
+            // --force is a DELIBERATELY UNDOCUMENTED confirmation gate (hidden from
+            // -h; see FlagParam.hidden). Silas's intent (2026-06-13): a mass revive
+            // can have large, unforeseen consequences, so the agent must NOT be able
+            // to discover a one-shot bypass by reading the schema. The unforced --all
+            // path PREVIEWS the candidates and instructs the agent to double-check
+            // with the USER before re-running; only then, having been told the flag,
+            // does it pass --force. Documenting it here would defeat that gate.
+            {
+                kind: 'flag',
+                name: 'force',
+                type: 'bool',
+                required: false,
+                default: false,
+                hidden: true,
+                constraint: 'Confirm the sweep (internal gate; see code comment).',
+            },
+        ],
+        output: [
+            { name: 'mode', type: 'string', required: true, constraint: '"preview" (the candidate list, nothing launched) or "revived" (the sweep ran).' },
+            { name: 'candidates', type: 'string', required: false, constraint: 'Preview: the node ids that WOULD be revived (newline-joined). Empty when none are disconnected.' },
+            { name: 'revived', type: 'string', required: false, constraint: 'Sweep: the node ids whose broker engine was relaunched (newline-joined).' },
+            { name: 'failed', type: 'string', required: false, constraint: 'Sweep: node ids whose relaunch threw, with the error (newline-joined). Absent when none failed.' },
+            { name: 'frozen', type: 'string', required: false, constraint: 'Sweep: node ids the live-broker cap turned away (newline-joined). Not failures — the daemon launches each as a slot frees. Absent when none were frozen.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Launches the detached headless broker engine (no tmux window) for every disconnected node.',
+            'Updates each revived node\'s canvas record: status=active, intent=null.',
+            'Without --force: launches NOTHING — only previews the disconnected candidates.',
+        ],
+    },
+    run: async (input) => {
+        requireScope('crtr:act', 'crtr canvas revive');
+        if (input['all'] !== true) {
+            throw new InputError({
+                error: 'missing_parameter',
+                message: '`canvas revive` is the mass-recovery sweep and requires --all.',
+                next: 'Run `crtr canvas revive --all` to reconnect every disconnected node, or `crtr node lifecycle revive <id>` to bring back one named node.',
+            });
+        }
+        return runReviveAll(input);
+    },
+});
+/** Statuses a node lands in DELIBERATELY (`done`/`canceled`) — the daemon never
+ *  auto-revives these and neither does mass-revive. Mirrors
+ *  `runtime/revive-all.ts`'s `TERMINAL_BY_CHOICE`, inlined so this leaf never
+ *  imports that (db-reaching) module (plan B-2 purity). */
+const TERMINAL_BY_CHOICE = ['done', 'canceled'];
+/** Client-side re-implementation of `runtime/revive-all.ts`'s `isDisconnected`
+ *  PREVIEW predicate, over the API's `NodeSummaryDTO` (spec §6 parity is
+ *  structural, not byte-identical). Two differences from the server predicate,
+ *  both display-only — the --force sweep re-computes authoritatively server-side:
+ *   - liveness identity degrades to null (the summary omits `pi_pid_identity`),
+ *     so `recordedPidLiveness(pi_pid, null)` uses the trust-isPidAlive path.
+ *   - the resumable-session check is deferred to `sessionResumable` below (the
+ *     summary carries no session marker; detail carries `pi_session_id`). */
+function passesCheapDisconnectedFilter(s) {
+    if (s.kind === 'human')
+        return false; // the `crtr human` bridge is never a pi engine
+    if (recordedPidLiveness(s.pi_pid, null) === 'alive')
+        return false; // engine running → connected
+    // hasNoNaturalCycle: finished its own work, or terminal-by-choice — never mass-revive.
+    if (s.final_report != null || TERMINAL_BY_CHOICE.includes(s.status))
+        return false;
+    return true;
+}
+/** One line per candidate: `<id>  <full name>  [<status>]`. `fullName` needs the
+ *  node's description (its first-task label), which lives only on the detail
+ *  projection — so this renders from `NodeDetailDTO`s. */
+function describe(details) {
+    return details
+        .map((d) => `  ${d.node_id}  ${fullName(d)}  [${d.status}]`)
+        .join('\n');
+}
+/** The --all sweep, gated on confirmation. Without `--force` it PREVIEWS the
+ *  disconnected candidates and returns WITHOUT launching anything, telling the
+ *  agent to double-check with the user first (a mass revive can have large,
+ *  unforeseen consequences). With `--force` it delegates the authoritative sweep
+ *  to the daemon (`POST /nodes/revive-all` → `reviveAll()` server-side). */
+async function runReviveAll(input) {
+    const force = input['force'] ?? false;
+    const client = cliClient();
+    // Preview: replicate the disconnected set client-side. The cheap filter runs
+    // over the list projection; then each survivor's detail is fetched to confirm a
+    // resumable saved session (`pi_session_id`, the DTO's session proxy — the
+    // summary carries no session marker; `pi_session_file` is not projected, so a
+    // rare file-only node under-lists here, but the --force sweep still revives it).
+    const summaries = await client.listNodes();
+    const shortlist = summaries.filter(passesCheapDisconnectedFilter);
+    const details = [];
+    for (const s of shortlist) {
+        const detail = await client.getNode(s.node_id);
+        if (detail.pi_session_id != null)
+            details.push(detail);
+    }
+    if (details.length === 0) {
+        return {
+            mode: 'preview',
+            candidates: '',
+            message: 'No disconnected nodes — every node with a resumable session already has a running engine. Nothing to revive.',
+        };
+    }
+    if (!force) {
+        const list = describe(details);
+        return {
+            mode: 'preview',
+            candidates: details.map((d) => d.node_id).join('\n'),
+            // Directive for the AGENT (not a documented flag): this is a preview, and a
+            // mass revive can have large, unforeseen consequences — so confirm with the
+            // USER before proceeding, then re-run to actually revive.
+            message: `${details.length} disconnected node(s) WOULD be revived (RESUME). Nothing has been launched yet:\n\n` +
+                `${list}\n\n` +
+                `Reviving all of these at once can have large, unforeseen consequences (a flood of resumed engines, ` +
+                `cost, side effects from each node continuing its work). This is a preview only — DOUBLE-CHECK WITH THE ` +
+                `USER that they want every node above brought back before you proceed. Once they confirm, re-run the ` +
+                `revive with confirmation to actually relaunch them.`,
+        };
+    }
+    const res = await client.request('POST', routes.reviveAll());
+    const out = {
+        mode: 'revived',
+        revived: res.revived.join('\n'),
+        message: `Revived ${res.revived.length} disconnected node(s) (RESUME).`,
+    };
+    if (res.failed.length > 0) {
+        out['failed'] = res.failed.map((f) => `${f.node_id}: ${f.error}`).join('\n');
+    }
+    if (res.frozen.length > 0) {
+        out['frozen'] = res.frozen.join('\n');
+    }
+    const total = res.revived.length + res.failed.length + res.frozen.length;
+    if (total > res.revived.length) {
+        out['message'] =
+            `Revived ${res.revived.length} of ${total} disconnected node(s) (RESUME)` +
+                (res.failed.length > 0 ? `; ${res.failed.length} failed to relaunch (see failed)` : '') +
+                (res.frozen.length > 0 ? `; ${res.frozen.length} frozen at the broker cap and launched as slots free (see frozen)` : '') +
+                '.';
+    }
+    return out;
+}

package/dist/commands/surface/node/cycle.d.ts

@@ -0,0 +1 @@
+export declare const surfaceNodeCycleLeaf: import("../../../core/command.js").LeafDef;

package/dist/commands/surface/node/cycle.js

@@ -0,0 +1,83 @@
+// `crtr surface node cycle` — walk live viewers in DFS order.
+import { defineLeaf } from '../../../core/command.js';
+import { cliCanvasSource, getNodeOrNull, rethrowAsCliError } from '../../api-client.js';
+import { currentTmux, focusViewer, nodeInPane } from './placement.js';
+/** Every live node in DFS pre-order across the whole forest. The spawn tree is
+ *  the `parent` field; children inherit their parent's row order (created), so
+ *  the walk descends into a node's children before moving to its siblings —
+ *  exactly "next in pre-order is your first child". Roots are live nodes with no
+ *  live parent (a done/dead parent orphans its live children up to the top).
+ *  Cycle-safe: a final pass appends any node a cycle kept from being reached. */
+async function liveDfsOrder() {
+    const rows = await cliCanvasSource().listNodes({ status: ['active', 'idle'] }).catch(rethrowAsCliError); // ORDER BY created
+    const liveIds = new Set(rows.map((r) => r.node_id));
+    const childrenOf = new Map();
+    for (const r of rows) {
+        const p = r.parent;
+        if (p != null && liveIds.has(p)) {
+            const arr = childrenOf.get(p) ?? [];
+            arr.push(r.node_id);
+            childrenOf.set(p, arr);
+        }
+    }
+    const out = [];
+    const seen = new Set();
+    const visit = (id) => {
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        out.push(id);
+        for (const c of childrenOf.get(id) ?? [])
+            visit(c);
+    };
+    for (const r of rows)
+        if (r.parent == null || !liveIds.has(r.parent))
+            visit(r.node_id);
+    for (const r of rows)
+        visit(r.node_id); // stragglers (parent cycles)
+    return out;
+}
+export const surfaceNodeCycleLeaf = defineLeaf({
+    name: 'cycle',
+    description: 'DFS-walk to the next/prev live node\'s viewer',
+    whenToUse: 'sweeping the canvas one viewer at a time, descending into children before siblings (bound to Alt+] forward / Alt+[ back). Use `surface node focus` instead to jump straight to a named node',
+    help: {
+        name: 'surface node cycle',
+        summary: 'focus the next/previous live node\'s viewer in DFS pre-order — the canvas walked one viewer at a time, descending into a node\'s children before its siblings (bound to Alt+] forward / Alt+[ back)',
+        params: [
+            { kind: 'flag', name: 'dir', type: 'enum', choices: ['next', 'prev'], required: false, default: 'next', constraint: 'Direction along the pre-order: next (Alt+], rightward/deeper into children) or prev (Alt+[, back). Wraps at the ends.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane to cycle FROM. Defaults to $TMUX_PANE / your current pane. The Alt+] / Alt+[ bindings pass this for you.' },
+        ],
+        output: [
+            { name: 'focused', type: 'boolean', required: true, constraint: 'True when the neighbor was brought into view.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The node now in front of you.' },
+            { name: 'name', type: 'string', required: false, constraint: 'Its display name.' },
+            { name: 'from', type: 'string', required: false, constraint: 'The node you cycled away from.' },
+        ],
+        outputKind: 'object',
+        effects: ['Brings the neighbor\'s viewer forefront beside the caller (like `surface node focus`); the viewer you were watching drops to the background.', 'Opens a parked resident from its saved snapshot without waking it; submitted input wakes it through the normal message path.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane ?? undefined;
+        const dir = (input['dir'] ?? 'next');
+        const fromId = nodeInPane(pane);
+        if (fromId === undefined)
+            return { focused: false };
+        const order = await liveDfsOrder();
+        const i = order.indexOf(fromId);
+        if (i === -1 || order.length < 2)
+            return { focused: false, node_id: fromId, from: fromId };
+        const step = dir === 'next' ? 1 : -1;
+        const targetId = order[(i + step + order.length) % order.length];
+        const target = await getNodeOrNull(targetId);
+        if (target === null)
+            return { focused: false, from: fromId };
+        // Placement brings the neighbor's viewer forefront beside the caller; the
+        // server keeps an exact parked resident offline until submitted input.
+        const res = await focusViewer(targetId, { cwd: target.cwd, name: target.name, pane });
+        return { focused: res.focused, node_id: targetId, name: target.name, from: fromId };
+    },
+    render: (r) => r['focused'] === true
+        ? `Cycled to "${r['name'] ?? ''}" (${r['node_id']}) — from ${r['from'] ?? '?'}.`
+        : 'No other live node to focus.',
+});

package/dist/commands/surface/node/focus.d.ts

@@ -0,0 +1 @@
+export declare const surfaceNodeFocusLeaf: import("../../../core/command.js").LeafDef;

package/dist/commands/surface/node/focus.js

@@ -0,0 +1,60 @@
+// `crtr surface node focus` — bring one viewer forward.
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { focusNode } from '../../../core/runtime/focus-viewer.js';
+import { cliClient, rethrowAsCliError } from '../../api-client.js';
+import { currentTmux } from './placement.js';
+/** The shared focus decision (`core/runtime/focus-viewer.ts`, also run
+ *  in-process by the attach viewer), shaped as this leaf's output. A human-ask
+ *  is refused before the pane check, as it always was. */
+async function focusNodeOrThrow(client, node, pane, newPane = false, inPlace = false, keepOtherViewers = false, openTicket) {
+    const res = await focusNode(client, node, { pane, newPane, inPlace, keepOtherViewers, ...(openTicket === undefined ? {} : { openTicket }) }).catch((err) => rethrowAsCliError(err));
+    return { focused: res.focused, session: res.session, revived: res.revived, in_place: res.inPlace };
+}
+export const surfaceNodeFocusLeaf = defineLeaf({
+    name: 'focus',
+    description: 'bring a node into view without waking parked or finished work',
+    whenToUse: 'you want to bring a specific node into view — a live node opens beside your pane, while a parked resident opens its saved conversation without waking until input is submitted. FINISHED work — a terminal worker, or any node that pushed a final report — opens its saved transcript instead of being put back to work. Use `node lifecycle revive` to deliberately relaunch finished work anyway. Use `surface node cycle` to walk neighbors, and `node message send` to steer without leaving where you are',
+    help: {
+        name: 'surface node focus',
+        summary: 'bring a node into view — attach live, open a parked resident without waking it, or inspect finished work as a saved transcript',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id to focus.' },
+            { kind: 'flag', name: 'new-pane', type: 'bool', required: false, constraint: 'Always open a NEW viewer SIDE-BY-SIDE with your current pane instead of moving/reusing the node\'s existing viewer. Two agents on screen at once (F4).' },
+            { kind: 'flag', name: 'in-place', type: 'bool', required: false, constraint: 'Re-exec the --pane pane ONTO this node, REPLACING whatever viewer it showed (a swap in place, not a split beside). Backs the attach viewer\'s subagent scroll+swap (↓ into the reports roster, Enter dives into the child right in your pane). MUST be driven from OUTSIDE that pane\'s process tree (e.g. `tmux run-shell`) — respawn-pane -k kills whatever runs in it. Mutually exclusive with --new-pane.' },
+            { kind: 'flag', name: 'keep-other-viewers', type: 'bool', required: false, constraint: 'With --in-place: leave the node\'s viewer in another pane open instead of closing it, so the conversation shows in both panes.' },
+            { kind: 'flag', name: 'open-ticket', type: 'string', required: false, constraint: 'With --in-place: an inbox ticket id the new viewer opens before it shows the conversation; once the ask is answered or closed the pane shows the conversation. An already-answered ticket shows a notice instead.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to focus beside (default: caller TMUX_PANE). Used by the canvas browser popup to focus back into the originating pane.' },
+        ],
+        output: [
+            { name: 'focused', type: 'boolean', required: true, constraint: 'True when the node\'s viewer was brought into view.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The tmux session the viewer lives in.' },
+            { name: 'revived', type: 'boolean', required: true, constraint: 'True when focusing had to recover a non-parked node\'s broker; false for an already attached viewer, an offline parked resident, or saved-transcript inspection.' },
+            { name: 'in_place', type: 'boolean', required: true, constraint: 'True when an existing viewer was navigated to (no new pane); false when a fresh viewer pane was opened or moved beside you.' },
+        ],
+        outputKind: 'object',
+        effects: ['For active/idle nodes: opens/moves the one surface-attach viewer beside the caller, or navigates to its existing viewer.', 'For an unfinalized parked resident: opens the normal conversation viewer from its saved snapshot without launching a broker or changing lifecycle; submitting input sends the durable human message that wakes it.', 'For finished work (a terminal node, or any node with a final report): opens a read-only saved transcript popup. It does not launch a broker or change node status.', 'With --new-pane/--in-place on a conversation viewer: controls whether the viewer splits beside or replaces the caller pane.'],
+    },
+    run: async (input) => {
+        const id = input['node'];
+        const client = cliClient();
+        const node = await client
+            .getNode(id)
+            .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
+        if (node.kind === 'human')
+            return focusNodeOrThrow(client, node, '');
+        // Every focus needs a pane to place the viewer or popup into. Resolve it ONCE
+        // here and fail loudly when there is none: both downstream paths would
+        // otherwise return `focused: false` with no explanation, which reads as the
+        // command silently doing nothing.
+        const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+        if (pane === undefined || pane === '') {
+            throw new InputError({
+                error: 'no_pane',
+                message: `no tmux pane to focus ${id} into — surfaces need a tmux server, and this call has neither --pane nor a caller pane.`,
+                next: `Run it from inside tmux, pass \`--pane <id>\`, or read the node without a surface: \`crtr node inspect transcript ${id}\`.`,
+            });
+        }
+        return focusNodeOrThrow(client, node, pane, input['newPane'] === true, input['inPlace'] === true, input['keepOtherViewers'] === true, input['openTicket']);
+    },
+});

package/dist/commands/surface/node/id.d.ts

@@ -0,0 +1 @@
+export declare const surfaceNodeIdLeaf: import("../../../core/command.js").LeafDef;