@north-light/api 0.3.580 → 0.3.587

package/dist/commands/node/lifecycle.js

@@ -0,0 +1,577 @@
+// `crtr node` lifecycle and durable configuration commands.
+import { readFileSync } from 'node:fs';
+import { envNodeId } from '../../shared/env.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
+import { DEFAULT_BASH_NICENESS, MAX_BASH_NICENESS, writeBashNiceness } from '../../core/bash-jobs.js';
+import { nodeReviveLeaf } from '../node-lifecycle-revive.js';
+import { kindsStateBlock } from '../profile/daemon-profiles.js';
+import { MODEL_SPEC_FORMS } from '../../core/runtime/model-selection.js';
+import { closePane, paneExists, respawnPaneSync, viewerEnv, viewerPaneOf, nodeInPane } from '../surface/node/placement.js';
+const nodeRecycle = defineLeaf({
+    name: 'recycle',
+    description: 'finish the agent in your pane + recycle it into a fresh root',
+    whenToUse: 'you are at an agent\'s pane and done with it: finish it cleanly and recycle the pane in one move — push its last message as a final report to everyone waiting on it, mark it done, then boot a fresh crtr root in the same pane to keep working. The hands-on way to end an agent and immediately start over in place. Use `node lifecycle demote` instead to put it on a finishing track IN PLACE (flip terminal, keep it running) without ending it now, `node lifecycle close` to tear a node and its subtree down WITHOUT finishing (no report, revivable), and `push final` when the agent should finish ITSELF from inside its own turn',
+    help: {
+        name: 'node lifecycle recycle',
+        summary: 'finish the agent in your current pane and recycle the pane — push its last message as a final report to everyone waiting on it, mark it done, then boot a fresh crtr root in the same pane',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to finish. Defaults to the node occupying --pane (or your current pane).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to recycle. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you.' },
+        ],
+        output: [
+            { name: 'recycled', type: 'boolean', required: true, constraint: 'True when the pane was recycled into a fresh root.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The finished node.' },
+            { name: 'new_root', type: 'string', required: false, constraint: 'The fresh root node booted into the pane.' },
+        ],
+        outputKind: 'object',
+        effects: ['Pushes a final report from the node (fans out to all subscribers) and marks it done.', 'Kills the agent\'s pi and respawns a fresh resident root in the same tmux pane.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        let id = input['node'];
+        if (id === undefined || id === '') {
+            // Derive the node from the pane: which node's window holds it?
+            id = nodeInPane(pane);
+        }
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node found in this pane to finish', next: 'Pass --node <id>, or run from inside the agent\'s pane.' });
+        }
+        const detail = await cliClient()
+            .getNode(id)
+            .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
+        // The server finalizes the node + spawns a fresh root (pane-less); the local
+        // tail re-execs the caller's pane onto a fresh `crtr` root so the human keeps
+        // working in place.
+        const recycled = await cliClient().recycleNode(id).catch(rethrowAsCliError);
+        const newRoot = recycled.node_id;
+        let paneRecycled = false;
+        if (pane !== undefined && pane !== '') {
+            paneRecycled = respawnPaneSync({ pane, cwd: detail.cwd, env: viewerEnv(), command: 'crtr' });
+        }
+        return { recycled: paneRecycled, node_id: id, new_root: newRoot };
+    },
+    render: (r) => {
+        if (r['recycled'] !== true) {
+            // A broker recycle that finalized + spawned a fresh root but whose new
+            // broker never served its socket: the state DID change (node finished, root
+            // born), only the viewer re-attach failed — say so, don't call it a no-op.
+            if (r['new_root']) {
+                return `Finished ${r['node_id']} and spawned a fresh broker root (${r['new_root']}), but its viewer did not attach — the new broker did not come up. Re-focus the root to view it.`;
+            }
+            return `Recycle failed for ${r['node_id'] ?? '?'} — not in tmux, or no agent in this pane.`;
+        }
+        const lines = [`Recycled the pane — finished ${r['node_id']}.`];
+        if (r['new_root'])
+            lines.push(`- new root: ${r['new_root']}`);
+        return lines.join('\n');
+    },
+});
+// node lifecycle close — close a node + cascade-cancel its exclusive subtree (Alt+C → x)
+const nodeClose = defineLeaf({
+    name: 'close',
+    description: 'close a node + cascade-cancel its exclusive subtree',
+    whenToUse: 'you want to tear a node down WITHOUT finishing it, cascade-cancelling every descendant it exclusively owns: abandoning a line of work, killing a stuck or wrong-turn subtree, clearing a branch you no longer need. A node that never produced substantive assistant output is deleted and cannot be revived; streaming nodes and nodes with an open managed worktree are retained. Other closed nodes keep their pi session and can be revived later (`node lifecycle revive`). Use `node lifecycle recycle` instead to FINISH the agent in your pane with a final report, and `push final` when a worker should end its own work normally (Alt+C → x)',
+    help: {
+        name: 'node lifecycle close',
+        summary: 'close a node and cascade-cancel its subtree — kill its tmux window plus those of every descendant it EXCLUSIVELY owns (down the subscription spine — the watches each manager holds on its children), mark retained nodes canceled, and leave them a notice they read on resume. A descendant still subscribed to by a manager outside the subtree is left running. A node that never produced substantive assistant output is deleted and cannot be revived; streaming nodes and nodes with an open managed worktree are retained. Other closed nodes keep their pi session and can be revived later (`crtr node lifecycle revive`)',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to close. Defaults to the node occupying --pane (or your current pane).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose node to close. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: false, constraint: 'The node that was closed — the cascade root.' },
+            { name: 'count', type: 'number', required: false, constraint: 'How many nodes were closed (root + cascaded descendants).' },
+            { name: 'closed_ids', type: 'string[]', required: false, constraint: 'All closed node ids, kill order (leaves first, root last).' },
+            { name: 'spared', type: 'string[]', required: false, constraint: 'Descendants left alive because a manager outside the subtree still subscribes to them.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Marks retained nodes and their exclusive descendants `canceled` and clears intent (the daemon never revives a canceled node).',
+            'Deletes a non-streaming node with no substantive assistant output unless it has an open managed worktree; a deleted node cannot be revived.',
+            'Kills each closed node\'s tmux window; retained nodes keep their pi sessions and canvas edges for a later revive.',
+            'Appends a cancellation notice to each retained node\'s inbox, surfaced on its next resume.',
+        ],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        let id = input['node'];
+        if (id === undefined || id === '')
+            id = nodeInPane(pane);
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node found in this pane to close', next: 'Pass --node <id>, or run from inside the agent\'s pane.' });
+        }
+        const res = await cliClient()
+            .closeNode(id, process.ppid > 0 ? { caller_pid: process.ppid } : {})
+            .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
+        return { node_id: res.root, count: res.closed.length, closed_ids: res.closed, spared: res.spared };
+    },
+    render: (r) => {
+        const spared = r['spared']?.length ?? 0;
+        return `Closed ${r['node_id']} and its exclusive subtree — ${r['count']} node(s) closed${spared > 0 ? `, ${spared} spared (still managed from outside the subtree)` : ''}.`;
+    },
+});
+// node config — reconfigure a node's settings headlessly (model/lifecycle/kind/mode/name/listen/cwd repair)
+const NODE_CONFIG_MODEL_EFFECT = 'Model change first: a running broker, including one still starting right after `node new`, switches over its socket; a dormant node persists the durable model override and launch recipe for its next revive.';
+export const nodeConfig = defineLeaf({
+    name: 'config',
+    description: 'reconfigure a node\'s settings headlessly — model, lifecycle (terminal/resident), kind, mode, name; repair a missing cwd',
+    whenToUse: 'you want to reconfigure a node\'s settings headlessly after spawn — swap its model/provider, flip it terminal↔resident (interactable), respecialize its kind, switch base↔orchestrator mode, or rename it — without opening its viewer. It also repairs a dormant node whose recorded cwd is gone, starting its next revive in a fresh conversation. The durable attribute setter; reuses the same recipes a revive reads. Use `node promote` for the opinionated self-promotion path, and `node lifecycle` for teardown actions (recycle/close/demote).',
+    help: {
+        name: 'node config',
+        summary: 'reconfigure a node\'s settings headlessly — model, lifecycle, kind, mode, name; repair a missing cwd',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, repeatable: true, constraint: 'Target node id. Defaults to the node in --pane, else CRTR_NODE_ID. Repeat it, or use --nodes-from, to apply a --profile or --cwd change to many nodes; a bulk run reports each node and keeps going past a failure.' },
+            { kind: 'flag', name: 'nodes-from', type: 'string', required: false, constraint: 'File of node ids, one per line (blank lines and #-comments ignored), or `-` for stdin. Bulk form of --node; only with --profile or --cwd.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to resolve the node from. Defaults to $TMUX_PANE.' },
+            {
+                kind: 'flag',
+                name: 'model',
+                type: 'string',
+                required: false,
+                constraint: 'Durable model change. Omit unless the task or governing guidance requires a different model.',
+                focusedHelp: {
+                    whenToUse: 'Use only when intentionally changing this node’s durable model because the user, task, or governing agent guidance requires a specific provider, model, capability tier, or family. Omit it to keep the current model; do not use it merely to inspect available models or experiment with a live node.',
+                    value: `Accepted durable forms: ${MODEL_SPEC_FORMS}. A live broker also accepts a free-text substring matched against its loaded model registry; a dormant node cannot resolve a substring and requires a durable form.`,
+                    effects: [
+                        NODE_CONFIG_MODEL_EFFECT,
+                        'A concrete provider/id runs exactly that model on every launch and revive. A portable provider/tier, bare tier, or family alias keeps its tier: when that model\'s provider is rate-limited or rejects its credential, the node moves to the next model in its route: another provider\'s model at the same tier first, then the configured fallback tier (strong by default).',
+                    ],
+                },
+            },
+            { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Set lifecycle headlessly without closing the viewer. terminal owes a final and reaps when done; resident stays interactable while attached or awaiting something live.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here.' },
+            { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Set persona mode headlessly. base is hands-on; orchestrator holds a roadmap and delegates. orchestrator creates your document `roadmap` if absent.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Rename the node; if the node has a live window, also rename that viewer window.' },
+            { kind: 'flag', name: 'nice', type: 'int', required: false, constraint: `Scheduler niceness every command this node's bash tool starts at, 0–${MAX_BASH_NICENESS} (default ${DEFAULT_BASH_NICENESS}). ${DEFAULT_BASH_NICENESS} keeps the node's builds and test suites below the daemon, the brokers, the viewers, and the person's own shell; 0 lets them compete on equal terms with everything else on the host; ${MAX_BASH_NICENESS} makes them yield to it. Applies to the node's very next command, foreground and background alike.` },
+            { kind: 'flag', name: 'listen', type: 'string', required: false, constraint: 'The node\'s default listening configuration, as JSON mapping an event level ("1".."10") to how events at or above it reach the node: interrupt, steer, after-turn, or next-turn (e.g. \'{"3":"next-turn"}\' — events of level 3+ wait for its next turn and never wake it). Applies to every watch with no configuration of its own. Pass `null` to reset to the global default.' },
+            { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Replacement launch directory (absolute, existing). Alone, or with --keep-session / --restart. Without --keep-session it is a repair: only a dormant, non-forked node with no open managed worktree whose recorded cwd is gone, and it clears the saved Pi session (next revive starts fresh). When the new path is the same directory as the recorded one (a symlink alias) it relocates and keeps the conversation automatically — see --keep-session.' },
+            { kind: 'flag', name: 'keep-session', type: 'bool', required: false, constraint: 'With --cwd: assert the new path is the SAME directory as the recorded cwd and relocate WITHOUT clearing the Pi session. Needed only when the recorded path is already gone (e.g. the symlink was deleted); while it still exists the daemon verifies by realpath and refuses a different directory. Allowed for live, idle, dormant and finished nodes, forks included. Rewrites the recorded cwd and the cwd in the node\'s transcript header so a later resume finds it. Refused while the node owns an open managed worktree.' },
+            { kind: 'flag', name: 'rewrite-prefix', type: 'string', required: false, constraint: 'Bulk cwd form, `OLD=NEW` (absolute paths): with several nodes, each node\'s recorded cwd that equals OLD or lies beneath it is relocated to the same place under NEW, keeping its session (as --keep-session); nodes whose cwd is elsewhere are reported as failed "not under OLD". Use instead of --cwd when the nodes sit in different subdirectories.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Reassign the node to this profile (id or exact name; must be an active profile of the node\'s app that defines the node\'s kind). Works for live, idle, dormant, finished and profile-less (detached) nodes. Used alone, or with --restart.' },
+            { kind: 'flag', name: 'restart', type: 'bool', required: false, constraint: 'With --profile, or --cwd on a live node: after the change, SIGTERM the node\'s live broker so crtrd resumes it from the same transcript (continuing an interrupted turn) with the new profile/cwd. No effect on a node with no live broker.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: false, constraint: 'The reconfigured node, present for ordinary config changes.' },
+            { name: 'model', type: 'string', required: false, constraint: 'The resolved model, present only when --model changed it.' },
+            { name: 'lifecycle', type: 'string', required: false, constraint: 'The new lifecycle, present only when --lifecycle changed it.' },
+            { name: 'kind', type: 'string', required: false, constraint: 'The new kind, present only when --kind changed it.' },
+            { name: 'mode', type: 'string', required: false, constraint: 'The new mode, present only when --mode changed it.' },
+            { name: 'name', type: 'string', required: false, constraint: 'The new name, present only when --name changed it.' },
+            { name: 'nice', type: 'number', required: false, constraint: 'The new bash niceness, present only when --nice changed it.' },
+            { name: 'listen', type: 'object', required: false, constraint: 'The new default listening configuration (null = global default), present only when --listen changed it.' },
+            { name: 'cwd', type: 'string', required: false, constraint: 'The resolved replacement directory, present only after a cwd change.' },
+            { name: 'session_kept', type: 'boolean', required: false, constraint: 'With a cwd change: true when the node still has its Pi session bound (conversation preserved).' },
+            { name: 'profile', type: 'string', required: false, constraint: 'The node\'s profile id after --profile.' },
+            { name: 'bulk', type: 'boolean', required: false, constraint: 'True for a multi-node run.' },
+            { name: 'applied', type: 'number', required: false, constraint: 'Bulk: nodes changed (or already in the requested state).' },
+            { name: 'failed', type: 'number', required: false, constraint: 'Bulk: nodes that errored; the exit code is 1 when any did.' },
+            { name: 'results', type: 'array', required: false, constraint: 'Bulk: one {node_id, ok, error?} per node, in input order.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            NODE_CONFIG_MODEL_EFFECT,
+            'Kind, mode, and lifecycle changes rebuild the launch spec from the fresh node meta; setting mode to orchestrator creates your document `roadmap` if absent.',
+            'Name changes update the row and, when the node already has a live window, rename that viewer window to the new full name.',
+            'A cwd repair (gone recorded cwd, no --keep-session) writes only the lexically resolved cwd and clears saved Pi session pointers; the old transcript and durable node work remain untouched.',
+            'A session-keeping cwd relocation (--keep-session, or --cwd naming a symlink alias of the recorded directory) rewrites the recorded cwd and the cwd line in the header of each of the node\'s transcripts; the Pi session stays bound and the next revive resumes the same conversation. A LIVE broker keeps the old cwd string in its environment and tools until it restarts: it keeps working while the old path exists, so pass --restart (or revive it) BEFORE deleting an old symlink.',
+            'A profile reassignment rewrites the node\'s profile and rebuilds its launch recipe. Profile env, documents delivered at boot, purview and bearings are read at launch, so a LIVE broker keeps the old profile until it next restarts; --restart bounces it now. Dormant or finished nodes simply carry the new profile into their next revive. The node\'s deadlines and profile pause follow the new profile immediately.',
+            'A niceness change is stored with the node\'s own bash-job state, so it takes effect on the next command without a revive and survives one.',
+            'A listen change sets the node\'s default listening configuration; it never changes which watches it holds.',
+            'Every successful change publishes a `configured` event on the node (level 1) naming the changed settings, so its watchers can see it.',
+        ],
+    },
+    helpState: { leaf: kindsStateBlock },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        const nodeFlags = input['node'];
+        const nodeList = Array.isArray(nodeFlags) ? nodeFlags : nodeFlags === undefined ? [] : [nodeFlags];
+        const nodesFrom = input['nodesFrom'];
+        if (nodesFrom !== undefined) {
+            const raw = nodesFrom === '-' ? readFileSync(0, 'utf8') : readFileSync(nodesFrom, 'utf8');
+            for (const line of raw.split('\n')) {
+                const id = line.replace(/#.*/, '').trim();
+                if (id !== '')
+                    nodeList.push(id);
+            }
+        }
+        const placementSpec = input['profile'];
+        const cwdFlag = input['cwd'];
+        const prefixSpec = input['rewritePrefix'];
+        if (nodeList.length > 1 || nodesFrom !== undefined || prefixSpec !== undefined) {
+            if (nodeList.length === 0) {
+                throw new InputError({ error: 'no_nodes', message: 'bulk config needs at least one node', next: 'Pass --node ID (repeatable) or --nodes-from FILE|-.' });
+            }
+            if (placementSpec === undefined && cwdFlag === undefined && prefixSpec === undefined) {
+                throw new InputError({ error: 'bulk_unsupported', message: 'several nodes are accepted only with --profile, --cwd or --rewrite-prefix', next: 'Pass --profile <profile>, --cwd <dir> or --rewrite-prefix OLD=NEW with the node list.' });
+            }
+            let prefix;
+            if (prefixSpec !== undefined) {
+                const eq = prefixSpec.indexOf('=');
+                const from = eq < 0 ? '' : prefixSpec.slice(0, eq).replace(/\/+$/, '');
+                const to = eq < 0 ? '' : prefixSpec.slice(eq + 1).replace(/\/+$/, '');
+                if (!from.startsWith('/') || !to.startsWith('/')) {
+                    throw new InputError({ error: 'bad_rewrite_prefix', message: `--rewrite-prefix must be OLD=NEW with absolute paths: ${prefixSpec}`, field: 'rewrite-prefix', next: 'Pass e.g. --rewrite-prefix /Users/me/Code/northlight=/Users/me/Code/northlight-systems.' });
+                }
+                prefix = [from, to];
+            }
+            const client = cliClient();
+            const results = [];
+            for (const id of [...new Set(nodeList)]) {
+                try {
+                    const patch = placementSpec !== undefined ? { profile: placementSpec } : { cwd: cwdFlag ?? '' };
+                    if (prefix !== undefined) {
+                        const current = (await client.getNode(id)).cwd;
+                        if (current !== prefix[0] && !current.startsWith(`${prefix[0]}/`))
+                            throw new Error(`cwd ${current} is not under ${prefix[0]}`);
+                        patch.cwd = prefix[1] + current.slice(prefix[0].length);
+                        patch.keep_session = true;
+                    }
+                    if (input['keepSession'] === true)
+                        patch.keep_session = true;
+                    if (input['restart'] === true)
+                        patch.restart = true;
+                    await client.patchConfig(id, patch);
+                    results.push({ node_id: id, ok: true });
+                }
+                catch (err) {
+                    let message = err instanceof Error ? err.message : String(err);
+                    try {
+                        rethrowAsCliError(err);
+                    }
+                    catch (cli) {
+                        if (cli instanceof Error)
+                            message = cli.message;
+                    }
+                    results.push({ node_id: id, ok: false, error: message });
+                }
+            }
+            const failed = results.filter((r) => !r.ok).length;
+            if (failed > 0)
+                process.exitCode = 1;
+            return { bulk: true, applied: results.length - failed, failed, results };
+        }
+        const nodeId = await resolveLifecycleNode({ ...input, node: nodeList[0] }, pane);
+        // Validate the model spec's SHAPE client-side (the server owns the
+        // live/dormant resolution branch); build the patch from the flags set. The
+        // kind is validated against the caller's installed personas here for the
+        // clean listing error, and re-validated server-side against the TARGET
+        // node's scope as a backstop.
+        const cwdSpec = cwdFlag;
+        if (cwdSpec !== undefined && ['model', 'kind', 'lifecycle', 'mode', 'name', 'nice', 'listen', 'profile'].some((flag) => input[flag] !== undefined)) {
+            throw new InputError({ error: 'cwd_not_exclusive', message: 'cwd cannot be combined with another config flag except --keep-session and --restart', field: 'cwd', next: 'Pass --cwd alone (plus --keep-session / --restart).' });
+        }
+        if (placementSpec !== undefined && ['model', 'kind', 'lifecycle', 'mode', 'name', 'nice', 'listen'].some((flag) => input[flag] !== undefined)) {
+            throw new InputError({ error: 'profile_not_exclusive', message: 'profile cannot be combined with another config flag except --restart', field: 'profile', next: 'Pass --profile alone (plus --restart).' });
+        }
+        if (input['keepSession'] === true && cwdSpec === undefined) {
+            throw new InputError({ error: 'keep_session_needs_cwd', message: '--keep-session only applies with --cwd', field: 'keep-session', next: 'Pass --cwd <dir> --keep-session.' });
+        }
+        if (input['restart'] === true && cwdSpec === undefined && placementSpec === undefined) {
+            throw new InputError({ error: 'restart_needs_change', message: '--restart only applies with --profile or --cwd', field: 'restart', next: 'Pass --profile <profile> or --cwd <dir> with --restart.' });
+        }
+        const modelSpec = input['model']?.trim();
+        if (modelSpec === '') {
+            throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: 'Run `crtr node config --model -h` and read the focused contract before retrying.' });
+        }
+        const kindSpec = input['kind']?.trim();
+        const lifecycleSpec = input['lifecycle']?.trim();
+        const modeSpec = input['mode']?.trim();
+        const nameSpec = input['name'];
+        const niceSpec = input['nice'];
+        const listenRaw = input['listen']?.trim();
+        let listenSpec;
+        if (listenRaw !== undefined) {
+            try {
+                listenSpec = JSON.parse(listenRaw);
+            }
+            catch {
+                throw new InputError({ error: 'invalid_listen', message: `--listen is not JSON: ${listenRaw}`, field: 'listen', next: 'Pass a JSON object such as \'{"3":"next-turn"}\', or null.' });
+            }
+        }
+        if (niceSpec !== undefined && (niceSpec < 0 || niceSpec > MAX_BASH_NICENESS)) {
+            throw new InputError({
+                error: 'bad_nice',
+                message: `niceness must be between 0 and ${MAX_BASH_NICENESS}: ${niceSpec}`,
+                field: 'nice',
+                next: `A negative niceness needs root, so pass 0–${MAX_BASH_NICENESS}.`,
+            });
+        }
+        if (lifecycleSpec !== undefined && lifecycleSpec.toLowerCase() !== 'terminal' && lifecycleSpec.toLowerCase() !== 'resident') {
+            throw new InputError({ error: 'bad_lifecycle', message: `invalid lifecycle: ${lifecycleSpec}`, field: 'lifecycle', next: 'Pass `terminal` or `resident`.' });
+        }
+        if (modeSpec !== undefined && modeSpec.toLowerCase() !== 'base' && modeSpec.toLowerCase() !== 'orchestrator') {
+            throw new InputError({ error: 'bad_mode', message: `invalid mode: ${modeSpec}`, field: 'mode', next: 'Pass `base` or `orchestrator`.' });
+        }
+        const applied = [];
+        const patch = {};
+        if (modelSpec !== undefined) {
+            patch.model = modelSpec;
+            applied.push('model');
+        }
+        if (kindSpec !== undefined) {
+            patch.kind = kindSpec;
+            applied.push('kind');
+        }
+        if (lifecycleSpec !== undefined) {
+            patch.lifecycle = lifecycleSpec.toLowerCase();
+            applied.push('lifecycle');
+        }
+        if (modeSpec !== undefined) {
+            patch.mode = modeSpec.toLowerCase();
+            applied.push('mode');
+        }
+        if (nameSpec !== undefined) {
+            patch.name = nameSpec;
+            applied.push('name');
+        }
+        if (cwdSpec !== undefined) {
+            patch.cwd = cwdSpec;
+            applied.push('cwd');
+            if (input['keepSession'] === true)
+                patch.keep_session = true;
+            if (input['restart'] === true)
+                patch.restart = true;
+        }
+        if (placementSpec !== undefined) {
+            patch.profile = placementSpec;
+            applied.push('profile');
+            if (input['restart'] === true)
+                patch.restart = true;
+        }
+        if (listenRaw !== undefined) {
+            patch.listen = listenSpec ?? null;
+            applied.push('listen');
+        }
+        // Niceness is node-local bash-lane state, not canvas state: it is stored
+        // beside this node's job dirs so the valve reads it when it starts the next
+        // command, rather than waiting for a launch recipe to be rebuilt.
+        if (niceSpec !== undefined) {
+            const node = await cliClient().getNode(nodeId).catch((err) => rethrowAsCliError(err));
+            writeBashNiceness(node.paths.context_dir, niceSpec);
+            applied.push('nice');
+            if (applied.length === 1)
+                return { node_id: nodeId, nice: niceSpec };
+        }
+        if (applied.length === 0) {
+            throw new InputError({ error: 'no_change', message: 'no config changes requested', next: 'Pass at least one of --model, --lifecycle, --kind, --mode, --name, --nice, --listen, --cwd.' });
+        }
+        const detail = await cliClient()
+            .patchConfig(nodeId, patch)
+            .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
+        if (cwdSpec !== undefined)
+            return { cwd: detail.cwd, node_id: nodeId, ...(patch.keep_session === true || detail.pi_session_id != null ? { session_kept: detail.pi_session_id != null } : {}) };
+        if (placementSpec !== undefined)
+            return { node_id: nodeId, profile: detail.profile_id ?? null };
+        const result = { node_id: nodeId };
+        if (applied.includes('model'))
+            result.model = detail.model_override ?? modelSpec;
+        if (applied.includes('lifecycle'))
+            result.lifecycle = detail.lifecycle;
+        if (applied.includes('kind'))
+            result.kind = detail.kind;
+        if (applied.includes('mode'))
+            result.mode = detail.mode;
+        if (applied.includes('name'))
+            result.name = detail.name;
+        if (applied.includes('nice'))
+            result.nice = niceSpec;
+        if (applied.includes('listen'))
+            result.listen = patch.listen;
+        return result;
+    },
+    render: (r) => {
+        if (r['bulk'] === true) {
+            const results = r['results'];
+            return [`Applied to ${r['applied']} node(s), ${r['failed']} failed.`, ...results.filter((x) => !x.ok).map((x) => `  FAILED ${x.node_id}: ${x.error}`)].join('\n');
+        }
+        if (r['cwd'] !== undefined)
+            return `Set cwd of ${r['node_id']}: ${r['cwd']}${r['session_kept'] === true ? ' (conversation kept)' : ''}.`;
+        if (r['profile'] !== undefined)
+            return `Reassigned ${r['node_id']} to profile ${r['profile']}.`;
+        const bits = [];
+        if (r['model'] !== undefined)
+            bits.push(`model=${r['model']}`);
+        if (r['lifecycle'] !== undefined)
+            bits.push(`lifecycle=${r['lifecycle']}`);
+        if (r['kind'] !== undefined)
+            bits.push(`kind=${r['kind']}`);
+        if (r['mode'] !== undefined)
+            bits.push(`mode=${r['mode']}`);
+        if (r['name'] !== undefined)
+            bits.push(`name=${r['name']}`);
+        if (r['nice'] !== undefined)
+            bits.push(`nice=${r['nice']}`);
+        if (r['listen'] !== undefined)
+            bits.push(`listen=${JSON.stringify(r['listen'])}`);
+        return `Configured ${r['node_id']} — ${bits.join(', ')}`;
+    },
+});
+export const nodePromote = defineLeaf({
+    name: 'promote',
+    description: 'become an orchestrator of a chosen kind',
+    whenToUse: 'the remaining work contains independent units that can run in parallel, and the task is large enough that coordinating and integrating them will materially improve intelligence, productivity, or elapsed throughput. Become a long-lived, roadmap-holding orchestrator whose primary job is steering those children across refreshes (`node yield`). Keep sequential or tightly coupled work in base mode even when it spans phases or context windows; spawning one helper does not itself require promotion',
+    tier: 'important',
+    help: {
+        name: 'node promote',
+        summary: 'promote yourself to an orchestrator when worthwhile parallel delegation should make coordination your primary job; task duration, sequential phases, or one helper do not qualify. Mode only — lifecycle stays as-is unless you pass --resident',
+        params: [
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here. For an exact composed persona list, use `crtr sys context prompt-review --list --kind <kind>` with the target kind. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
+            { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'ALSO flip lifecycle→resident: make the node interactable — it is never forced to submit a final, and unattended grace parks it after a summary turn instead, leaving it revivable fresh against its goal and roadmap. Omit to stay terminal/orchestrator (delegates + holds a roadmap, but still owes a final up the spine and reaps when done).' },
+            { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model you run on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. An orchestrator steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The promoted node.' },
+            { name: 'kind', type: 'string', required: true, constraint: 'The kind it now orchestrates as.' },
+            { name: 'model', type: 'string', required: false, constraint: 'The model tier it now runs on, present only when you changed it with --model.' },
+            { name: 'lifecycle', type: 'string', required: true, constraint: '"resident" if you passed --resident, else unchanged (typically "terminal").' },
+            { name: 'roadmap_written', type: 'boolean', required: true, constraint: 'True if the `roadmap` document was created by this call.' },
+            { name: 'roadmap_ref', type: 'string', required: true, constraint: 'Your roadmap document (`<node>/roadmap`) — author your plan with `crtr doc edit roadmap`.' },
+            { name: 'goal_path', type: 'string', required: true, constraint: 'Absolute path to your goal doc (context/initial-prompt.md) — the mandate you were spawned with.' },
+        ],
+        outputKind: 'object',
+        effects: ['Flips mode→orchestrator + kind→chosen (lifecycle unchanged unless --resident, which also flips lifecycle→resident); --model durably sets the model; rewrites the launch spec to that kind\'s orchestrator persona; creates your document `roadmap` (rule `on: boot`, `deliver: content`) if absent.', 'The next model request is gated on appending and persisting your new-role guidance. If a fresh context starts first, its rebuilt baseline carries the new role.'],
+    },
+    helpState: { leaf: kindsStateBlock },
+    run: async (input) => {
+        const id = input['node'] ?? envNodeId();
+        if (id === undefined || id === '')
+            throw new InputError({ error: 'no_node', message: 'no node to promote (set CRTR_NODE_ID or pass --node)', next: 'Run from inside a node, or pass --node <id>.' });
+        const kind = input['kind'];
+        const model = input['model'];
+        const resident = input['resident'] === true;
+        const detail = await cliClient()
+            .promoteNode(id, { ...(kind !== undefined ? { kind } : {}), ...(resident ? { resident: true } : {}), ...(model !== undefined ? { model } : {}) })
+            .catch((err) => rethrowAsCliError(err));
+        return {
+            node_id: detail.node_id,
+            kind: detail.kind,
+            lifecycle: detail.lifecycle,
+            ...(model !== undefined && detail.model_override != null ? { model: detail.model_override } : {}),
+            roadmap_written: detail.roadmap_written ?? false,
+            roadmap_ref: detail.roadmap_ref ?? '',
+            goal_path: detail.goal_path ?? '',
+        };
+    },
+});
+// The target resolver is shared by `node config` and `node lifecycle demote`;
+// each command owns its direct config patch path.
+/** Resolve the node a demote/config command acts on: explicit --node, else
+ *  the node occupying --pane (the Alt+C menu passes #{pane_id}), else the caller
+ *  (CRTR_NODE_ID). Throws a rendered error when none resolves or it is unknown. */
+async function resolveLifecycleNode(input, pane) {
+    let id = input['node'];
+    if (id === undefined || id === '')
+        id = nodeInPane(pane);
+    if (id === undefined || id === '')
+        id = envNodeId();
+    if (id === undefined || id === '')
+        throw new InputError({ error: 'no_node', message: 'no node (set CRTR_NODE_ID, pass --node, or run from the agent\'s pane)', next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
+    const exists = await getNodeOrNull(id);
+    if (exists === null)
+        throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+    return id;
+}
+// node lifecycle demote — flip a node to TERMINAL in place (the friendly half
+// of the promote/demote pair; bound to Alt+C → d, and → D with --detach). It
+// stays focused and running but now owes a final up the spine. `node config
+// --lifecycle` remains the orthogonal low-level command (it also does resident).
+// See vision F5.
+const nodeDemote = defineLeaf({
+    name: 'demote',
+    description: 'demote a node to terminal in place; it stays focused and running but now owes a final; --detach also closes its viewer (broker keeps running off-screen)',
+    whenToUse: 'you are watching a resident/interactive node and want to put it on a finishing track WITHOUT disturbing it: flip it terminal IN PLACE — it keeps its viewer and your focus, keeps running, but now owes a final report up the spine and reaps when done. The friendly counterpart to `node promote`. You can also let go entirely and close its viewer so the agent finishes off-screen on its broker. Use `node lifecycle recycle` instead to FINISH it now and reboot a fresh root in its pane, and `node config --lifecycle` for the orthogonal low-level flip (incl. terminal→resident)',
+    help: {
+        name: 'node lifecycle demote',
+        summary: 'demote a node to terminal IN PLACE — it stays focused and running but now owes a final up the spine and reaps when done. Pairs with `node promote` (mode↑); `--detach` also closes its viewer (the broker engine keeps running off-screen)',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to demote. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose node to demote, when --node is omitted. Defaults to $TMUX_PANE. The Alt+C menu passes this for you.' },
+            { kind: 'flag', name: 'detach', type: 'bool', required: false, constraint: 'After flipping terminal, stop foregrounding the agent by closing its viewer pane. The broker engine keeps generating off-screen and — now terminal — pushes a final up the spine when done; a later `focus` reattaches a viewer. The Alt+C → D move.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The demoted node.' },
+            { name: 'detached', type: 'boolean', required: false, constraint: 'True when --detach closed the agent\'s viewer pane (broker keeps running).' },
+        ],
+        outputKind: 'object',
+        effects: ['Flips the node\'s lifecycle→terminal and rebuilds its launch spec so a future revive boots terminal — it stays focused and running, now owing a final up the spine.', 'The next model request is gated on appending and persisting the role transition. If a fresh context starts first, its rebuilt baseline carries the new lifecycle.', 'With --detach: closes the agent\'s viewer pane WITHOUT touching the broker engine — it keeps generating off-screen, reconnectable by a later `focus`.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        const id = await resolveLifecycleNode(input, pane);
+        // The server owns the lifecycle flip + launch-spec rebuild. Keep the patch
+        // before pane close so a failed patch never strands a running viewer.
+        const detail = await cliClient()
+            .patchConfig(id, { lifecycle: 'terminal' })
+            .catch((err) => rethrowAsCliError(err));
+        let detached = false;
+        if (input['detach'] === true) {
+            const viewer = viewerPaneOf(id) ?? pane;
+            if (viewer !== undefined && viewer !== '' && paneExists(viewer))
+                detached = closePane(viewer);
+        }
+        return { node_id: detail.node_id, detached };
+    },
+    render: (r) => `Demoted ${r['node_id']} — lifecycle now terminal (in place)${r['detached'] === true ? ', viewer closed (broker still running off-screen)' : ''}.`,
+});
+// node lifecycle — recycle, close, or demote a node
+export const nodeLifecycle = defineBranch({
+    name: 'lifecycle',
+    description: 'lifecycle actions — recycle, close, demote, or revive a node',
+    whenToUse: 'you are ending, transitioning, or bringing back one node you can name: finish the agent in your pane and reboot a fresh root (`recycle`), tear a node + its exclusive subtree down without finishing (`close`), flip a node onto a finishing track in place (`demote`), or bring a dormant node back (`revive`). To merely SET the terminal/resident attribute headlessly use `node config --lifecycle`; to FINISH from inside a node\'s own turn use `crtr push final`; to mass-reconnect EVERY disconnected node at once use `canvas revive --all`.',
+    help: {
+        name: 'node lifecycle',
+        summary: 'end, transition, or revive a node — recycle the pane, close + cascade-cancel a subtree, demote to terminal in place, or revive a dormant node',
+        model: 'Lifecycle actions preserve or replace an existing node identity. Finishing is permanent, closing is revivable, demotion changes the completion obligation in place, and revival relaunches a dormant broker. Teardown cascades only through descendants exclusively managed by the affected subtree.',
+    },
+    children: [nodeRecycle, nodeClose, nodeDemote, nodeReviveLeaf],
+});
+// node yield — refresh: discard context, revive fresh in the same mode against roadmap or goal
+export const nodeYield = defineLeaf({
+    name: 'yield',
+    description: 'refresh your context, same mode, against your roadmap or goal',
+    whenToUse: 'your context is filling but the mandate remains; refresh in the same mode, or combine the refresh with promotion when meaningful independent work can run in parallel and coordinating it should become your primary job',
+    help: {
+        name: 'node yield',
+        summary: 'request a fresh context window against your roadmap or original goal; mode stays unchanged unless --promote is passed',
+        guide: 'The yield aborts your turn the instant this command returns: no text or tool call you planned after it will run. So anything the user is owed — an answer, a status — must already be a visible message in the conversation before you call it; never plan to reply after yielding. Before invoking: (1) If you hold a document `roadmap`, bring it current (`crtr doc edit roadmap`). It, not the yield note, carries your task into the fresh window. It has four sections: Goal (its first line is also the roadmap’s preview, so set it with `--preview` whenever the goal changes), Exit criteria, Where things stand, and Working set. Keep it at your own level of abstraction. Detail below your level belongs to the node or document that holds it: link to it, don’t copy it. Where things stand is present tense; delete what is done instead of marking it. Name units by what they are and how they fit, never by child node id or status: your bearings already list your children with their status. Working set holds `[[links]]`. Their previews load with the roadmap, so write no note beside a link. When a unit lands, delete its links: its evidence belongs in its report. (2) Give content its own document when it lives on a different timescale from the roadmap (exploration that outlives the current work), goes to a different reader (a brief for a child), or matters only when something specific happens. Link each such document from the Working set. Anything you had to re-derive in this window that a future window will need again belongs in a document: one you own for this task, `--owner repo` for lessons that would help others in the repo. A document that only points at other documents is not worth the extra hop. (3) Actions waiting on one specific event (“when X reports, send Y first”) go in the yield note, not the roadmap. They are spent once they fire. (4) Send any pending human question; asks already in flight survive the refresh.',
+        params: [
+            { kind: 'flag', name: 'promote', type: 'bool', required: false, constraint: 'Also become an orchestrator as you refresh. Pass only when (1) the remaining work contains independent units that can run in parallel and (2) the task is large enough that parallel execution will materially improve intelligence, productivity, or elapsed throughput after coordination and synthesis. Task length, context exhaustion, sequential phases, or one helper are not enough; keep hands-on work in base mode and yield again as needed. Promote when coordinating and integrating children becomes your primary job. Already an orchestrator? This is not an error: your mode stays orchestrator and a missing roadmap is seeded.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Respecialize as you refresh. The <kinds> list below names every top-level available kind and when to choose it; a registered sub-kind is valid too by exact path but not listed here. Defaults to your current kind. With --promote it sets the orchestrator kind you become; without --promote it changes the kind while preserving your current mode.' },
+            { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model your fresh revive runs on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. A node steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
+            // Deliberate fail-first contract: builtin orchestration guidance shows bare
+            // `crtr node yield`; that invocation fails fast and surfaces yield's full help just in
+            // time, at the point of use. Keep the note required rather than pre-documenting stdin
+            // in kernel guidance.
+            { kind: 'stdin', name: 'message', required: true, constraint: 'A note to your future self — what you just tried, where things stand, the first move on waking, and any action waiting on a specific event: enough to continue efficiently, no more. Never describe a reply as sent unless it is visible in the conversation above this call. Your task and its state belong in the roadmap. Surfaced as <yield-message> in the next revive. Pass as a positional or pipe via heredoc.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The yielding node.' },
+            { name: 'model', type: 'string', required: false, constraint: 'The model tier your fresh revive will run on, present only when you changed it with --model.' },
+        ],
+        outputKind: 'object',
+        effects: ['Aborts your current turn as soon as this command returns — nothing after it runs — then the daemon revives the node fresh.', '--kind and/or --model durably reshape the node (kind respecialization, model change) before the refresh-revive; --promote additionally flips mode→orchestrator and creates your document `roadmap` — mode is otherwise left exactly as it was.'],
+    },
+    helpState: { leaf: kindsStateBlock },
+    run: async (input) => {
+        const id = envNodeId();
+        if (id === undefined || id === '')
+            throw new InputError({ error: 'no_node', message: 'no node to yield (CRTR_NODE_ID unset)', next: 'Run from inside a node.' });
+        const kind = input['kind'];
+        const model = input['model'];
+        const doPromote = input['promote'] === true;
+        const message = typeof input['message'] === 'string' ? input['message'].trim() : '';
+        if (message === '') {
+            throw new InputError({ error: 'empty_message', message: 'a yield message is required (stdin or positional)', next: 'Pass a note to your future self as an argument or pipe it on stdin.' });
+        }
+        // The server writes the yield note + sets intent=refresh (handleYield);
+        // `promoted`/`will_refresh` are derived client-side (a yield always refreshes;
+        // promoted iff --promote was passed).
+        const detail = await cliClient()
+            .yieldNode(id, { note: message, ...(kind !== undefined ? { kind } : {}), ...(model !== undefined ? { model } : {}), ...(doPromote ? { promote: true } : {}) })
+            .catch((err) => rethrowAsCliError(err));
+        return { node_id: detail.node_id, ...(model !== undefined && detail.model_override != null ? { model: detail.model_override } : {}) };
+    },
+});

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

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