@north-light/crouter 0.3.172 → 0.3.174

package/dist/commands/node/create.js

@@ -0,0 +1,207 @@
+// `crtr node new` — creation commands and persona-kind helpers.
+import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { mark } from '../../core/timing.js';
+import { parseOutputSchemaValue } from '../../core/runtime/structured-output.js';
+import { readMergedLaunchConfig } from '../../core/config.js';
+import { profilesStateBlock } from '../../core/profiles/state-block.js';
+import { stateBlock } from '../../core/help.js';
+import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
+import { openSpawnViewer } from '../surface/node/placement.js';
+const YIELD_NUDGE_THRESHOLD = 100_000;
+const STD_CHILD_FOLLOW_UP = "Do not wait, poll, or duplicate this child's assignment in your own context — there is no result to await, stopping will not strand you, and duplicated work wastes the delegated context. You're auto-subscribed, so its finish wakes you on its own. Two moves only: do other independent work right now, or stop and end your turn — the wake brings you back.";
+/** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
+ *  but when the SPAWNER is an orchestrator whose context has already grown past
+ *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
+ *  the child's result. */
+export async function childFollowUp(spawnerId) {
+    if (spawnerId === undefined || spawnerId === '')
+        return STD_CHILD_FOLLOW_UP;
+    const spawner = await getNodeOrNull(spawnerId);
+    if (spawner === null || spawner.mode !== 'orchestrator')
+        return STD_CHILD_FOLLOW_UP;
+    const ctxTokens = spawner.context_tokens ?? null;
+    if (ctxTokens === null || ctxTokens < YIELD_NUDGE_THRESHOLD)
+        return STD_CHILD_FOLLOW_UP;
+    const k = Math.round(ctxTokens / 1000);
+    return `Child spawned — you're auto-subscribed, so its finish wakes you on its own; never wait, poll, or duplicate the child's assignment in your own context. But you're an orchestrator already carrying ~${k}k of context: rather than hold this window open for the result, checkpoint context/roadmap.md and \`crtr node yield\` now. Yielding ends this turn, and the child's completion then revives you fresh against your roadmap — let that clean revive absorb the result instead of this bloated context.`;
+}
+/** Validate a `--kind` against the installed personas; throws a listing InputError. */
+export function assertKind(kind) {
+    const kinds = Object.keys(readMergedLaunchConfig().kinds).sort();
+    if (!kinds.includes(kind)) {
+        throw new InputError({ error: 'unknown_kind', message: `unknown kind: ${kind}`, field: 'kind', next: `Valid kinds: ${kinds.join(', ')}.` });
+    }
+}
+/** A live `<kinds count=N>` state element — one `<kind> — <whenToUse>` line per
+ *  installed top-level persona kind (project > user > builtin), lazily built so
+ *  it reflects the caller's cwd/project scope. Appended to `node new -h` and
+ *  `node promote -h` so custom kinds appear in help. Soft-fails via the renderer.
+ *
+ *  Keep this block cheap and caller-agnostic: help should not depend on the
+ *  running node's current persona env, which can lag after polymorph. Sub-kinds
+ *  (e.g. `plan/reviewers/security`) are OMITTED here — `KindConfig.availableTo`
+ *  defaults to the sub-kind's own top-level ancestor, and this generic block has
+ *  no single ancestor to check against, so only an explicit `availableTo: ['*']`
+ *  sub-kind (universally available) earns a place in this list. A direct launch
+ *  by full sub-kind string is always valid regardless (visibility-only
+ *  filtering) — discover the roster for a specific kind via
+ *  `crtr sys prompt-review --list --kind <kind>`. */
+export function kindsStateBlock() {
+    const registry = readMergedLaunchConfig().kinds;
+    const kinds = Object.keys(registry)
+        .filter((k) => {
+        const slash = k.indexOf('/');
+        if (slash === -1)
+            return true;
+        const availableTo = registry[k]?.availableTo ?? [k.slice(0, slash)];
+        return availableTo.includes('*');
+    })
+        .sort();
+    const lines = kinds
+        .map((k) => {
+        const w = registry[k]?.whenToUse ?? '';
+        return w ? `${k} — ${w}` : k;
+    })
+        .join('\n');
+    return stateBlock('kinds', { count: kinds.length }, lines);
+}
+function nodeNewParams() {
+    return [
+        { kind: 'stdin', name: 'prompt', required: false, constraint: 'First user message. Required unless --no-kickoff is given.' },
+        { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind. The <kinds> list below names every top-level installable kind.' },
+        { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for hands-on work; orchestrator when the unit itself needs decomposition across children.' },
+        { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Directory the node is pinned to. Defaults to the caller cwd.' },
+        { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name. Defaults to the kind.' },
+        { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node.' },
+        { kind: 'flag', name: 'node-id', type: 'string', required: false, constraint: 'Exact id for the new node; lowercase letters, digits, and hyphens only, at most 128 characters. Rejected if already present.' },
+        { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an independent resident root with no parent or subscription. Mutually exclusive with --worktree.' },
+        { kind: 'flag', name: 'worktree', type: 'string', required: false, constraint: 'Local base branch for a crouter-managed worktree for this child. Mutually exclusive with --root.' },
+        { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'Fork the new node from an existing node id, absolute session path, or partial pi session uuid.' },
+        { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Durable model override: provider/id; provider/tier where provider is anthropic|openai and tier is ultra|strong|medium|light; bare tier (ultra|strong|medium|light); or family alias (opus|sonnet|haiku).' },
+        { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or unique profile name. Omit to inherit the caller profile.' },
+        { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Hidden ambient context appended to injected bearings, never visible chat.' },
+        { kind: 'flag', name: 'no-kickoff', type: 'bool', required: false, constraint: 'With --root, start the broker and session idle without a first message or model turn. Mutually exclusive with a prompt and --mode orchestrator.' },
+        { kind: 'flag', name: 'output-schema', type: 'string', required: false, constraint: 'Path to a JSON Schema file, or inline JSON beginning with `{`. The node must submit a conforming result to finish.' },
+    ];
+}
+function nodeNewOutput() {
+    return [
+        { name: 'node_id', type: 'string', required: true, constraint: 'New node id.' },
+        { name: 'name', type: 'string', required: true, constraint: 'Display name.' },
+        { name: 'status', type: 'string', required: true, constraint: 'Always "active".' },
+        { name: 'window', type: 'string', required: false, constraint: 'tmux window id when a viewer opens.' },
+        { name: 'session', type: 'string', required: false, constraint: 'tmux session when a viewer opens.' },
+        { name: 'follow_up', type: 'string', required: true, constraint: 'Managed child: continue unrelated work or stop; its final report wakes you. Root: hand it off; no report wakes you.' },
+    ];
+}
+async function runNodeCreation(input) {
+    const prompt = input['prompt'] ?? '';
+    const noKickoff = input['noKickoff'] === true;
+    if (!noKickoff && prompt.trim() === '') {
+        throw new InputError({ error: 'empty_prompt', message: 'a prompt is required (stdin or positional)', next: 'Pipe a task on stdin or pass it as an argument, or pass --no-kickoff to spawn an idle node with none.' });
+    }
+    if (noKickoff && prompt.trim() !== '') {
+        throw new InputError({ error: 'no_kickoff_with_prompt', message: '--no-kickoff cannot be combined with a prompt', field: 'no-kickoff', next: 'Drop --no-kickoff, or drop the prompt.' });
+    }
+    const kind = input['kind'] ?? 'general';
+    const mode = (input['mode'] ?? 'base');
+    const cwd = input['cwd'] ?? process.cwd();
+    const name = input['name'];
+    const parent = input['parent'];
+    const root = input['root'] === true;
+    const worktreeBaseRaw = input['worktree'];
+    if (worktreeBaseRaw !== undefined && worktreeBaseRaw.trim() === '') {
+        throw new InputError({ error: 'worktree_base_required', message: '--worktree requires a base branch', field: 'worktree', next: 'Pass an existing local branch that landing can fast-forward.' });
+    }
+    const worktreeBase = worktreeBaseRaw?.trim();
+    const forkFrom = input['forkFrom'];
+    const modelSpec = input['model']?.trim();
+    if (modelSpec === '') {
+        throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: 'Pass a provider/id, provider/tier where provider is anthropic|openai and tier is ultra|strong|medium|light, a bare tier (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku).' });
+    }
+    const profile = input['profile'];
+    const situationalContextRaw = input['situationalContext']?.trim();
+    const situationalContext = situationalContextRaw !== undefined && situationalContextRaw !== '' ? situationalContextRaw : undefined;
+    const outputSchemaParsed = parseOutputSchemaValue(input['outputSchema']);
+    const outputSchema = outputSchemaParsed !== null ? JSON.stringify(outputSchemaParsed) : null;
+    const nodeId = input['nodeId']?.trim();
+    if (root && worktreeBase !== undefined) {
+        throw new InputError({ error: 'worktree_root_conflict', message: '--worktree is mutually exclusive with --root', field: 'worktree', next: 'Drop either --root or --worktree.' });
+    }
+    if (noKickoff && !root) {
+        throw new InputError({ error: 'no_kickoff_requires_root', message: '--no-kickoff is only valid with --root', field: 'no-kickoff', next: 'Add --root, or drop --no-kickoff and provide a prompt.' });
+    }
+    if (noKickoff && mode === 'orchestrator') {
+        throw new InputError({ error: 'no_kickoff_orchestrator_unsupported', message: '--no-kickoff cannot be combined with --mode orchestrator', field: 'no-kickoff', next: 'Drop --no-kickoff and provide a prompt, or spawn in base mode.' });
+    }
+    const parentId = parent ?? process.env['CRTR_NODE_ID'];
+    mark('node_new.create_start', { root });
+    const detail = await cliClient().createNode({
+        kind,
+        mode,
+        cwd,
+        ...(name !== undefined ? { name } : {}),
+        prompt,
+        ...(root ? { root: true } : { parent: parentId ?? null }),
+        ...(worktreeBase !== undefined ? { worktree: worktreeBase } : {}),
+        ...(forkFrom !== undefined ? { fork_from: forkFrom } : {}),
+        ...(modelSpec !== undefined ? { model: modelSpec } : {}),
+        ...(profile !== undefined ? { profile } : {}),
+        ...(situationalContext !== undefined ? { situational_context: situationalContext } : {}),
+        ...(noKickoff ? { no_kickoff: true } : {}),
+        ...(outputSchema !== null ? { output_schema: outputSchema } : {}),
+        ...(nodeId !== undefined && nodeId !== '' ? { node_id: nodeId } : {}),
+        // A bare `--root --no-kickoff` create is exactly what the warm pool holds
+        // ready; every other shape is rejected server-side and cold-spawns.
+        ...(root ? { prefer_warm: true } : {}),
+    }).catch(rethrowAsCliError);
+    mark('node_new.node_created', { node: detail.node_id });
+    let placement = {};
+    if (root)
+        placement = openSpawnViewer(detail.node_id, detail.cwd, detail.name);
+    if (root)
+        mark('node_new.viewer_window_opened');
+    const result = {
+        node_id: detail.node_id,
+        name: detail.name,
+        window: placement.window,
+        session: placement.session,
+        status: detail.status,
+        follow_up: root
+            ? (noKickoff
+                ? 'Independent root spawned idle. No kickoff turn ran; hand it off or attach and prompt it. No report wakes you.'
+                : 'Independent root spawned. You are not subscribed, so its finish does not wake you; hand it off and move on.')
+            : await childFollowUp(parentId),
+    };
+    return result;
+}
+export const nodeNew = defineLeaf({
+    name: 'new',
+    description: 'create and start a node immediately',
+    whenToUse: 'you need a managed child or independent root to start immediately',
+    tier: 'important',
+    help: {
+        name: 'node new',
+        summary: 'create a node immediately and start its detached broker',
+        params: nodeNewParams(),
+        output: nodeNewOutput(),
+        dynamicState: () => [kindsStateBlock(), profilesStateBlock()].join('\n'),
+        outputKind: 'object',
+        effects: [
+            'Creates nodes/<id>/ in the canvas home, indexes the node in canvas.db, and starts its detached broker engine.',
+            'A managed child creates an active parent subscription; its pushes wake the parent. --root creates an independent node with spawned_by provenance and no parent subscription.',
+            '--worktree creates a managed worktree at ~/.crouter/canvas/worktrees/<node-id>/ on a new crtr/<node-id> branch. --output-schema writes nodes/<id>/output-schema.json. --no-kickoff starts an idle root without a first model turn.',
+            'An in-tmux root opens a viewer in the current tmux session. When auto_open_child_viewers is true, a managed child opens beside a live spawner viewer; false leaves it running in the background.',
+        ],
+    },
+    run: (input) => runNodeCreation(input),
+    render: (r) => {
+        const win = r['window'] ? ` in window ${r['window']}` : '';
+        const lines = [`Spawned "${r['name']}" (${r['node_id']}) — ${r['status']}${win}.`];
+        if (r['session'])
+            lines.push(`- session: ${r['session']}`);
+        lines.push('', String(r['follow_up']));
+        return lines.join('\n');
+    },
+});

package/dist/commands/node/inspect.d.ts

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

package/dist/commands/node/inspect.js

@@ -0,0 +1,302 @@
+// `crtr node inspect` — roster, detail, and conversation fork reads.
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { isPidAlive } from '../../core/canvas/pid.js';
+import { fullName } from '../../core/canvas/labels.js';
+import { fuzzyMatch } from '../../core/canvas/browse/model.js';
+import { loadProfileManifest } from '../../core/profiles/manifest.js';
+import { profilesStateBlock } from '../../core/profiles/state-block.js';
+import { nodeSnapshotLeaf } from '../node-snapshot.js';
+import { nodeTranscriptLeaf } from '../node-transcript.js';
+import { nodeContextLeaf } from '../node-context.js';
+import { nodeArtifactsLeaf } from '../node-inspect-artifacts.js';
+import { cliClient, cliCanvasSource, rethrowAsCliError } from '../api-client.js';
+import { RemoteCanvasSource } from '../../core/canvas/remote-canvas-source.js';
+import { kindsStateBlock } from './create.js';
+import { focusViewer, nodeInPane } from '../surface/node/placement.js';
+const nodeList = defineLeaf({
+    name: 'list',
+    description: 'list nodes on the canvas',
+    whenToUse: 'you want a flat roster of the nodes on the canvas, sliced by displayed name, status, kind, mode, lifecycle, profile, cwd, and graph scope (--under a node, for that node plus its subscription descendants). The filters AND together. Use `node inspect show` instead to drill into one node and its spine neighbors, `canvas dashboard` for the tree shape, and `canvas attention` to find nodes blocked on a human',
+    help: {
+        name: 'node inspect list',
+        summary: 'list nodes on the canvas, filtered by any combination of attribute slices and a graph-scope (--under) that AND together',
+        params: [
+            { kind: 'flag', name: 'status', type: 'string', required: false, constraint: 'Filter status (comma-separated for several; accepted values: active, idle, done, dead, canceled). NOTE: `active` means the engine process is live (never closed), NOT that the node is generating right now — an active node is usually dormant between turns. To tell working-vs-idle, check the pi session-file mtime or CPU, not status.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Filter by persona kind (comma-separated for several). The <kinds> list below names every top-level installable kind; a sub-kind (e.g. plan/reviewers/security) filters too even though it is not listed.' },
+            { kind: 'flag', name: 'mode', type: 'string', required: false, constraint: 'Filter by mode (comma-separated for several; accepted values: base, orchestrator).' },
+            { kind: 'flag', name: 'lifecycle', type: 'string', required: false, constraint: 'Filter by lifecycle (comma-separated for several; accepted values: terminal, resident).' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Filter by profile. On the local canvas, accepts an exact profile id or a unique manifest name from the <profiles> list below. Against a remote canvas, pass the exact profile id carried by its node rows.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Filter by the displayed node label (handle plus generated description) with the canvas browser’s case-insensitive fuzzy subsequence match.' },
+            { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Filter to nodes pinned to this exact cwd (absolute path). Roster is canvas-wide (all cwds) by default.' },
+            { kind: 'flag', name: 'under', type: 'string', required: false, constraint: 'Graph scope: restrict to this node and its subscription descendants (the sub-DAG reachable downward — its reports, theirs, …). This is "one initiative / my subtree". ANDs with every attribute filter above, narrowing any of them to this subtree.' },
+            { kind: 'flag', name: 'canvas', type: 'string', required: false, constraint: 'Read from the named remote canvas target (see `crtr canvas config list`) instead of the local canvas. Overrides `crtr canvas use`.' },
+        ],
+        output: [
+            { name: 'nodes', type: 'object[]', required: true, constraint: 'Rows include {node_id, name, kind, mode, lifecycle, status, cwd, profile_id, parent, created}. `name` is the displayed node label searched by --name and shown in canvas views. `profile_id` is the stable profile-directory id (null only for historical no-profile nodes).' },
+        ],
+        outputKind: 'object',
+        dynamicState: () => [kindsStateBlock(), profilesStateBlock()].join('\n'),
+        effects: ['Read-only: lists nodes through the daemon API.'],
+    },
+    run: async (input) => {
+        const csv = (k) => {
+            const raw = input[k];
+            return raw !== undefined && raw !== '' ? raw.split(',').map((s) => s.trim()).filter((s) => s !== '') : undefined;
+        };
+        const status = csv('status');
+        const kinds = csv('kind');
+        const modes = csv('mode');
+        const lifecycles = csv('lifecycle');
+        const profile = input['profile'];
+        const name = input['name'];
+        const cwd = input['cwd'];
+        const under = input['under'];
+        const canvasSource = cliCanvasSource({ canvasName: input['canvas'] });
+        // The selected source owns roster filtering, graph scope, missing-node
+        // checks, and node-name hydration for both local and remote canvases. Local
+        // profiles remain the one command-side compatibility lookup: remote guests
+        // cannot resolve this machine's manifest names.
+        const profileId = canvasSource instanceof RemoteCanvasSource
+            ? profile
+            : profile === undefined ? undefined : loadProfileManifest(profile).profileId;
+        let scope;
+        if (under !== undefined && under !== '') {
+            if (await canvasSource.getNode(under).catch(rethrowAsCliError) === null) {
+                throw new InputError({ error: 'not_found', message: `no node: ${under}`, next: 'List nodes with `crtr node inspect list`, then pass a real id to --under.' });
+            }
+            scope = new Set([under, ...(await canvasSource.view(under))]);
+        }
+        const rows = (await canvasSource.listNodes(status !== undefined ? { status } : undefined).catch(rethrowAsCliError)).filter((row) => {
+            if (scope !== undefined && !scope.has(row.node_id))
+                return false;
+            if (kinds !== undefined && !kinds.includes(row.kind))
+                return false;
+            if (modes !== undefined && !modes.includes(row.mode))
+                return false;
+            if (lifecycles !== undefined && !lifecycles.includes(row.lifecycle))
+                return false;
+            if (profileId !== undefined && row.profile_id !== profileId)
+                return false;
+            if (cwd !== undefined && cwd !== '' && row.cwd !== cwd)
+                return false;
+            return true;
+        });
+        const nodes = (await Promise.all(rows.map(async (row) => {
+            const detail = await canvasSource.getNode(row.node_id).catch(rethrowAsCliError);
+            return { ...row, name: fullName(detail ?? row) };
+        }))).filter((row) => name === undefined || name === '' || fuzzyMatch(name, row.name));
+        return { nodes };
+    },
+});
+// ---------------------------------------------------------------------------
+// node inspect show — a node + its place in the spine
+// ---------------------------------------------------------------------------
+// The renderer receives only the command result, while JSON output bypasses it.
+// Keep remote provenance out of the returned DTO-shaped object without adding a
+// second wire field or mutating the remote response.
+const remoteShowResults = new WeakSet();
+// Enrich a declared source edge so a debugger reads who a report/manager is
+// without rebuilding a NodeMeta compatibility object.
+async function enrichNeighbor(source, ref) {
+    const node = await source.getNode(ref.node_id).catch(rethrowAsCliError);
+    return {
+        node_id: ref.node_id,
+        name: node ? fullName(node) : '(missing)',
+        kind: node?.kind ?? '?',
+        status: node ? (node.intent ? `${node.status}/${node.intent}` : node.status) : '?',
+        active: ref.active,
+    };
+}
+const nodeShow = defineLeaf({
+    name: 'show',
+    description: 'show a node + its spine neighbors, artifacts, and drill-in pointers',
+    whenToUse: 'you want one node in depth — the debugging entrypoint: a glanceable meta slice, named spine neighbors, artifact and pending-cron counts, and exact drill-in paths. Use `node inspect list` for the flat roster or `canvas dashboard` for the whole-tree shape',
+    help: {
+        name: 'node inspect show',
+        summary: 'show a node in depth — meta slice, named neighbors, artifact/pending-cron counts, and drill-in pointers',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id.' },
+            { kind: 'flag', name: 'canvas', type: 'string', required: false, constraint: 'Read from the named remote canvas target (see `crtr canvas config list`) instead of the local canvas. Overrides `crtr canvas use`.' },
+        ],
+        output: [
+            { name: 'node', type: 'object', required: true, constraint: 'The full node meta (system prompt + every telemetry field). The render surfaces a glanceable slice; `--json` carries the complete dump.' },
+            { name: 'reports', type: 'object[]', required: true, constraint: 'Who this node subscribes to (its reports/down), each enriched with {node_id, name, kind, status, active} — these are typically its spawned children.' },
+            { name: 'managers', type: 'object[]', required: true, constraint: 'Who subscribes to this node (its managers/up), same enriched shape.' },
+            { name: 'artifacts', type: 'object', required: true, constraint: 'Counts of what the node left on disk by corpus: {report, doc, roadmap}. Enumerate them with `node inspect artifacts <id>`.' },
+            { name: 'pending_crons', type: 'number', required: true, constraint: 'How many pending crons were created by this node. Inspect with `crtr cron list`.' },
+            { name: 'paths', type: 'object', required: true, constraint: 'Resolved on-disk locations: {context_dir, reports_dir, session_file} — read these directly to debug.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'The concrete next commands to drill deeper.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads the node, its edges and artifacts, and pending crons through crtrd.'],
+        // The node meta object inlines the full system prompt + every telemetry
+        // field — a machine-readable dump we suppress from the viewer preview; the
+        // render below surfaces only a glanceable slice. Same preview rationale as
+        // canvas snapshot / node inspect snapshot.
+        preview: { suppressOutput: true },
+    },
+    run: async (input) => {
+        const id = input['node'];
+        const canvasName = input['canvas'];
+        const canvasSource = cliCanvasSource({ canvasName });
+        // The remote source declares this exact command-read operation; preserve
+        // its guest-computed artifact/path fields instead of deriving them locally.
+        if (canvasSource instanceof RemoteCanvasSource) {
+            const result = await canvasSource.rawShow(id);
+            if (result === null) {
+                throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list --canvas <name>`.' });
+            }
+            const shown = { ...result };
+            remoteShowResults.add(shown);
+            return shown;
+        }
+        // The source owns existence and topology. Locally its detail projection is
+        // the daemon DTO that carries the path fields used below.
+        const sourceNode = await canvasSource.getNode(id).catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
+        if (sourceNode === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const node = sourceNode;
+        const client = cliClient();
+        const reports = await Promise.all((await canvasSource.subscriptionsOf(id)).map((ref) => enrichNeighbor(canvasSource, ref)));
+        const managers = await Promise.all((await canvasSource.subscribersOf(id)).map((ref) => enrichNeighbor(canvasSource, ref)));
+        const arts = await client.getArtifacts(id);
+        const artifacts = {
+            report: arts.artifacts.filter((a) => a.source.startsWith('report')).length,
+            doc: arts.artifacts.filter((a) => a.source === 'doc').length,
+            roadmap: arts.artifacts.filter((a) => a.source === 'roadmap').length,
+        };
+        const pending_crons = (await client.listCrons().catch(rethrowAsCliError)).filter((cron) => cron.created_by === id).length;
+        const paths = {
+            context_dir: node.paths.context_dir,
+            reports_dir: node.paths.reports_dir,
+            ...(node.pi_session_file !== undefined ? { session_file: node.pi_session_file } : {}),
+        };
+        // Auto-gathered drill-in pointers: the exact commands a debugger reaches for
+        // next, populated only when there is actually something behind them.
+        const hints = [];
+        const artTotal = artifacts.report + artifacts.doc + artifacts.roadmap;
+        if (artTotal > 0)
+            hints.push(`Read its ${artTotal} artifact(s): \`crtr node inspect artifacts ${id}\` → each ref feeds \`crtr canvas history read <ref>\`.`);
+        hints.push(`Browse its context + reports dirs (and its subscriptions') in nvim: \`crtr node inspect context ${id}\`.`);
+        if (paths.session_file)
+            hints.push(`Read the raw conversation transcript: ${paths.session_file}`);
+        hints.push(`On-disk context dir (ls/read directly): ${paths.context_dir}`);
+        if (pending_crons > 0)
+            hints.push(`It created ${pending_crons} pending cron(s): \`crtr cron list\`.`);
+        if (reports.length > 0)
+            hints.push(`Drill into a child/report: \`crtr node inspect show <node_id>\` (${reports.map((r) => r['node_id']).join(', ')}).`);
+        hints.push(`Full machine dump (system prompt + all telemetry): \`crtr --json node inspect show ${id}\`.`);
+        return { node, reports, managers, artifacts, pending_crons, paths, follow_up: hints.join('\n') };
+    },
+    render: (r) => {
+        const node = r['node'];
+        const id = String(node['node_id']);
+        const pid = node['pi_pid'];
+        const isRemoteShow = remoteShowResults.has(r);
+        const alive = isRemoteShow ? 'remote (liveness not checked locally)' : (isPidAlive(pid) ? 'alive' : 'dead');
+        const intent = node['intent'] ? `/${String(node['intent'])}` : '';
+        const parts = [];
+        // 1) Glanceable meta slice — the debug-critical fields, not the full dump.
+        parts.push(`# ${fullName(node)}  (${id})`);
+        const meta = [
+            `- kind/mode/lifecycle: ${node['kind']} / ${node['mode']} / ${node['lifecycle']}`,
+            `- status: ${node['status']}${intent}`,
+            `- broker pid: ${pid ?? '(none)'} — ${alive}`,
+            `- cwd: ${node['cwd']}`,
+            `- host: ${node['host_kind']}` + (node['profile_id'] ? ` · profile ${node['profile_id']}` : ''),
+            `- cycles: ${node['cycles']} · created ${node['created']}`,
+        ];
+        if (node['parent'])
+            meta.push(`- parent: ${node['parent']}`);
+        if (node['waiting_for'])
+            meta.push(`- waiting for message: ${node['waiting_for']}`);
+        parts.push(meta.join('\n'));
+        // 2) Neighbor tables (reports down, managers up), pre-enriched with names.
+        const table = (label, rows) => {
+            if (rows.length === 0)
+                return `${label}: none`;
+            const cols = ['node_id', 'name', 'kind', 'status', 'active'];
+            const head = `| ${cols.join(' | ')} |`;
+            const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+            const body = rows.map((row) => `| ${cols.map((c) => String(row[c] ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ')).join(' | ')} |`).join('\n');
+            return `${rows.length} ${label}:\n\n${head}\n${sep}\n${body}`;
+        };
+        parts.push(table('reports (down — subscriptions, usually children)', r['reports']));
+        parts.push(table('managers (up — subscribers)', r['managers']));
+        // 3) On-disk footprint at a glance.
+        const a = r['artifacts'];
+        parts.push(`artifacts: ${a['report']} report(s), ${a['doc']} doc(s), ${a['roadmap']} roadmap · ${r['pending_crons']} pending cron(s)`);
+        // 4) Auto-gathered drill-in pointers.
+        parts.push(`Drill deeper:\n${String(r['follow_up'])}`);
+        return parts.join('\n\n');
+    },
+});
+// ---------------------------------------------------------------------------
+// node fork — branch a conversation + durable context into an idle root
+// ---------------------------------------------------------------------------
+export const nodeFork = defineLeaf({
+    name: 'fork',
+    description: 'fork a node into an independent idle root with the same conversation and durable context',
+    whenToUse: 'a conversation has already accumulated the context you want, and you want a new human-driven branch beside it without sending a prompt or inheriting any graph-management responsibility. This copies the conversation and durable context, then waits for the fork’s first real user message to supply its mandate. Use `node new --fork-from` instead when spawning a managed worker with an immediate task',
+    help: {
+        name: 'node fork',
+        summary: 'create an independent resident root from a node’s conversation and durable context, with no kickoff prompt or model turn',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Source node id. Mutually exclusive with --pane; one of them is required.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the source node. Mutually exclusive with --node; one of them is required. The prefix menu passes this for you and the new viewer splits beside this pane.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The new independent root id.' },
+            { name: 'focused', type: 'boolean', required: true, constraint: 'True when a new viewer pane opened beside the caller; false outside tmux.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The tmux session containing the new viewer, when one opened.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates a resident base-mode root with the source node’s copied pi conversation, cwd, profile, kind, model override, and durable context files. Top-level initial-prompt.md, yield-message.md, and result.json are omitted.',
+            'Copies no parent, subscriptions, subscribers, children, crons, worktree, situational context, or lifecycle responsibility. Sends no prompt and consumes no model turn; the first real user message becomes the fork’s mandate.',
+            'Inside tmux, opens and focuses a surface-attach viewer as an even-horizontal split in the source pane’s window. Outside tmux, the root is still created but no interactive fallback opens.',
+        ],
+    },
+    run: async (input) => {
+        const pane = input['pane'];
+        const explicitNode = input['node'];
+        if (explicitNode !== undefined && pane !== undefined) {
+            throw new InputError({ error: 'conflicting_target', message: '--node and --pane are mutually exclusive', next: 'Pass the source node id or its viewer pane, not both.' });
+        }
+        let sourceId = explicitNode;
+        if (sourceId === undefined && pane !== undefined)
+            sourceId = nodeInPane(pane);
+        if (sourceId === undefined || sourceId === '') {
+            throw new InputError({ error: 'no_node', message: 'no source node was provided or found in the pane', next: 'Pass --node <id>, or --pane <pane-id> for a pane showing a node.' });
+        }
+        const detail = await cliClient().forkNode(sourceId).catch(rethrowAsCliError);
+        const placement = await focusViewer(detail.node_id, {
+            cwd: detail.cwd,
+            name: detail.name,
+            ...(pane !== undefined ? { pane } : {}),
+            newPane: true,
+        });
+        return { node_id: detail.node_id, focused: placement.focused, session: placement.session };
+    },
+    render: (result) => {
+        const placement = result['focused'] === true
+            ? ` Viewer opened beside the source${result['session'] ? ` in session ${result['session']}` : ''}.`
+            : ' No viewer opened because no tmux pane was available.';
+        return `Forked independent idle root ${result['node_id']}.${placement} It will make no model call until its first real user message.`;
+    },
+});
+// ---------------------------------------------------------------------------
+// node inspect — read the graph (list, show, context)
+// ---------------------------------------------------------------------------
+export const nodeInspect = defineBranch({
+    name: 'inspect',
+    description: 'read one node — its graph position, context, and artifacts',
+    whenToUse: 'reading everything about ONE node you can name: enumerate the roster (`list`), inspect a node and its spine neighbors (`show`), browse its on-disk context dir (`context`), or list its reports/docs as refs (`artifacts`). Use `canvas dashboard` instead to render the whole tree SHAPE, or `canvas attention` to find which nodes are blocked on a human',
+    help: {
+        name: 'node inspect',
+        summary: 'read one node (or the roster) — topology, context dir, and artifacts',
+    },
+    children: [nodeList, nodeShow, nodeSnapshotLeaf, nodeTranscriptLeaf, nodeContextLeaf, nodeArtifactsLeaf],
+});

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

@@ -0,0 +1,4 @@
+export declare const nodeConfig: import("../../core/command.js").LeafDef;
+export declare const nodePromote: import("../../core/command.js").LeafDef;
+export declare const nodeLifecycle: import("../../core/command.js").BranchDef;
+export declare const nodeYield: import("../../core/command.js").LeafDef;