@north-light/api 0.3.580 → 0.3.587

package/dist/commands/sys/context/admin.d.ts

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

package/dist/commands/sys/context/admin.js

@@ -0,0 +1,148 @@
+// `crtr sys context admin` — the interactive surface over delivery: dial a
+// node configuration, watch what every document delivers across the planned
+// activities, and edit the rules, preview, and body that decide it. Every plan
+// is the daemon's delivery dry run; every write goes through the same
+// `/v1/docs` routes `crtr doc edit` and `crtr doc move` use.
+import { resolve as resolvePath, sep } from 'node:path';
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { ApiError } from '../../../api/index.js';
+import { cliClient } from '../../api-client.js';
+import { envNodeId } from '../../../shared/env.js';
+import { PLANNED_EVENTS } from './resolve.js';
+export const adminLeaf = defineLeaf({
+    name: 'admin',
+    description: 'browse and edit what documents deliver, interactively',
+    whenToUse: 'you are shaping what agents load rather than answering one question about it — comparing node configurations, sweeping which documents deliver on which activity, and editing their rules in place',
+    help: {
+        name: 'sys context admin',
+        summary: 'interactive browser and editor for document delivery',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Open on this live node: its own documents, cwd, profile, and configuration. Defaults to the calling node (CRTR_NODE_ID); outside a node, the page opens on a node that does not exist, working in the current directory.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Opening node kind. Defaults to the node\u2019s kind, else `general`.' },
+            { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Opening node mode. Defaults to the node\u2019s mode, else `base`.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile (id or name) whose delivery limits apply. Defaults to the node\u2019s profile, else the profile pinned to the directory.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Directory the simulated node works in; the repos enclosing it apply. Defaults to the node\u2019s cwd, else the current directory.' },
+            { kind: 'flag', name: 'event', type: 'enum', choices: [...PLANNED_EVENTS], required: false, constraint: 'Opening activity. Defaults to `boot`.' },
+        ],
+        output: [
+            { name: 'edited', type: 'array', required: false, constraint: 'Names of the documents changed during the session; absent when nothing was changed.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Interactive: requires a TTY.',
+            'Edits documents through the routes `crtr doc edit` and `crtr doc move` use, with rationale `editor`, when you choose an edit action.',
+        ],
+    },
+    run: async (input) => {
+        if (!process.stdout.isTTY) {
+            throw new InputError({
+                error: 'not_a_tty',
+                message: 'sys context admin is interactive and needs a TTY',
+                next: 'Run it in a terminal, or use `crtr sys context resolve` and `crtr sys context doc` for scriptable reads.',
+            });
+        }
+        const client = cliClient();
+        const named = optional(input['node']) ?? optional(envNodeId());
+        const node = named === undefined ? null : await fetchNodeOrNull(named);
+        const profileDTOs = await client.listProfiles();
+        const profiles = profileDTOs.map((profile) => ({ id: profile.id, name: profile.name }));
+        const cwdFlag = optional(input['cwd']);
+        const cwd = cwdFlag !== undefined ? resolvePath(cwdFlag) : (node?.cwd ?? process.cwd());
+        const profileFlag = optional(input['profile']);
+        let profileId;
+        if (profileFlag !== undefined) {
+            const match = profileDTOs.find((profile) => profile.id === profileFlag || profile.name === profileFlag);
+            if (match === undefined) {
+                throw new InputError({
+                    error: 'unknown_profile',
+                    message: `No profile is named ${profileFlag}.`,
+                    next: 'Run `crtr profile list` for the profile ids and names.',
+                });
+            }
+            profileId = match.id;
+        }
+        else {
+            profileId = node !== null ? node.profile_id : pinnedProfileFor(profileDTOs, cwd);
+        }
+        const seed = {
+            kind: optional(input['kind']) ?? node?.kind ?? 'general',
+            mode: input['mode'] ?? node?.mode ?? 'base',
+            lifecycle: node?.lifecycle ?? 'terminal',
+            hasManager: node?.parent != null,
+            profileId,
+            cwd,
+            nodeId: node?.node_id ?? null,
+            ...(node === null ? {} : { grantee: node.grantee }),
+            depth: node === null ? 0 : await spineDepth(node),
+            event: input['event'] ?? 'boot',
+            file: '',
+            docName: '',
+            command: '',
+            seed: node === null ? null : { cwd: node.cwd, profileId: node.profile_id },
+        };
+        // Deferred so the page host, its terminal, and the whole TUI dependency
+        // chain load only for the interactive run — every other `sys context` leaf
+        // stays a plain read.
+        const { runContextAdmin } = await import('./admin/shell.js');
+        const result = await runContextAdmin(seed, profiles);
+        if (result === undefined || result.edited.length === 0)
+            return {};
+        return { edited: result.edited };
+    },
+    render: (r) => {
+        const edited = r['edited'] ?? [];
+        if (edited.length === 0)
+            return 'Closed the context admin with nothing changed.';
+        return edited.map((name) => `- edited ${name}`).join('\n');
+    },
+});
+function optional(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/** The profile pinned to the nearest directory at or above `cwd`, or null. */
+function pinnedProfileFor(profiles, cwd) {
+    let best = null;
+    for (const profile of profiles) {
+        const dir = profile.default_dir;
+        if (dir == null)
+            continue;
+        if (cwd !== dir && !cwd.startsWith(dir.endsWith(sep) ? dir : `${dir}${sep}`))
+            continue;
+        if (best === null || dir.length > best.depth)
+            best = { id: profile.id, depth: dir.length };
+    }
+    return best?.id ?? null;
+}
+/** A `--node` id that no longer resolves seeds nothing rather than failing: the
+ *  page is useful without a live node, and the ids an agent has to hand are the
+ *  ones most likely to have been pruned. */
+async function fetchNodeOrNull(nodeId) {
+    try {
+        return await cliClient().getNode(nodeId);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return null;
+        throw err;
+    }
+}
+/** Hops from a node up to its root orchestrator, walked through the API so this
+ *  leaf never reaches the canvas db. A pruned ancestor ends the walk. */
+async function spineDepth(node) {
+    const seen = new Set([node.node_id]);
+    let parent = node.parent;
+    let hops = 0;
+    while (parent != null && !seen.has(parent)) {
+        seen.add(parent);
+        hops += 1;
+        const next = await fetchNodeOrNull(parent);
+        if (next === null)
+            break;
+        parent = next.parent;
+    }
+    return hops;
+}

package/dist/commands/sys/context/doc.d.ts

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

package/dist/commands/sys/context/doc.js

@@ -0,0 +1,126 @@
+// `crtr sys context doc` — the reverse question: for ONE document, every
+// delivery event it takes part in for one node (live or simulated) and why.
+// One dry run of `POST /v1/delivery/dry-run` per event, the same plan live
+// delivery uses.
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { PLANNED_EVENTS, SNAPSHOT_PARAMS, buildSnapshot, delivers, describeSubject, dryRun, exclusionReason, nodeLine, snapshotHead, gateText, optionalString, ruleText, subjectFor, subjectSummary, table, } from './resolve.js';
+export const docLeaf = defineLeaf({
+    name: 'doc',
+    description: 'show one document\u2019s delivery across every event for one node',
+    whenToUse: 'a document is reaching a node it should not, or failing to reach one it should — this says which event delivers it, at what level, and what excluded it everywhere else',
+    help: {
+        name: 'sys context doc',
+        summary: 'show where one document delivers to a node, at what level, and what excludes it elsewhere',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'The document as the node names it, exactly as `crtr canvas read` takes it: its bare name, or `<owner>/<name>` for a document another owner holds under the same name.' },
+            ...SNAPSHOT_PARAMS,
+            { kind: 'flag', name: 'event', type: 'enum', choices: [...PLANNED_EVENTS], required: false, constraint: 'Report only this rule `on` name instead of all of them.' },
+            { kind: 'flag', name: 'file', type: 'path', required: false, constraint: 'Payload for the file-read event: the file being read. Without it, no file-read rule matches.' },
+            { kind: 'flag', name: 'read-name', type: 'string', required: false, constraint: 'Payload for the document-read event: the document read, as `crtr canvas read` takes it. Without it, no document-read rule matches.' },
+            { kind: 'flag', name: 'command', type: 'string', required: false, constraint: 'Payload for the command and pre-command events: the command string.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'The document\u2019s name as the node sees it.' },
+            { name: 'kind', type: 'string', required: true, constraint: 'knowledge or preference.' },
+            { name: 'owner', type: 'string', required: true, constraint: 'The owner handle: a node id, or the space or profile name.' },
+            { name: 'ref', type: 'string', required: true, constraint: 'The document\u2019s object id.' },
+            { name: 'node', type: 'string', required: false, constraint: 'The node the dry runs ran for, or the node --cwd and --profile dialled away from. Absent when the node is simulated.' },
+            { name: 'cwd', type: 'string', required: false, constraint: 'The simulated node\u2019s directory. Present when the node is simulated.' },
+            { name: 'node_missing', type: 'boolean', required: false, constraint: 'Present when --node named a node that does not exist, so the node was simulated.' },
+            { name: 'subject', type: 'object', required: true, constraint: 'The node configuration every row was computed under.' },
+            { name: 'rules', type: 'array', required: true, constraint: 'The document\u2019s rules for the reported events: on, match, if, deliver.' },
+            { name: 'events', type: 'array', required: true, constraint: 'One row per event: event, delivers, authored_rung, limit, capped_rung, final_rung, gate, matched_rule, winner, shadowed_by, excluded.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only; the dry runs record nothing.'],
+    },
+    run: async (input) => {
+        const snapshot = await buildSnapshot(input);
+        const name = input['name'];
+        const events = optionalString(input['event']) === null ? [...PLANNED_EVENTS] : [input['event']];
+        const flags = { file: optionalString(input['file']), readName: optionalString(input['readName']), command: optionalString(input['command']) };
+        let found = null;
+        let subject = null;
+        const rules = [];
+        const perEvent = [];
+        for (const event of events) {
+            const { plan } = await dryRun(snapshot, event, subjectFor(event, flags));
+            subject ??= plan.subject;
+            const record = plan.docs.find((r) => found !== null ? r.doc.object.id === found.object.id : matchesName(r.doc, name)) ?? null;
+            if (record !== null) {
+                found ??= record.doc;
+                rules.push(...record.authoredRules.map((d) => d.rule));
+            }
+            perEvent.push({ event, record });
+        }
+        if (found === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no document ${name} with a delivery rule in ${snapshot.nodeId === null ? 'the simulated node' : `node ${snapshot.nodeId}`}\u2019s view for these events`,
+                field: 'name',
+                next: 'Check the name with `crtr sys context resolve --all-events --all`, which lists every document the node considers.',
+            });
+        }
+        return {
+            name: found.displayName,
+            kind: found.kind,
+            owner: found.ownerHandle,
+            ref: found.object.id,
+            ...snapshotHead(snapshot),
+            subject: subjectSummary(subject),
+            rules: rules.map(ruleRow),
+            events: perEvent.map(({ event, record }) => eventRow(event, record, subject)),
+        };
+    },
+    render: (result) => renderDoc(result),
+});
+function matchesName(doc, name) {
+    return doc.displayName === name || `${doc.ownerHandle}/${doc.name}` === name;
+}
+function ruleRow(rule) {
+    return { on: rule.on, match: rule.match === undefined ? null : rule.match.join(', '), if: rule.if !== undefined, deliver: rule.deliver };
+}
+function eventRow(event, record, subject) {
+    if (record === null) {
+        return {
+            event, delivers: false, authored_rung: 'none', limit: null, capped_rung: 'none', final_rung: 'none',
+            gate: null, matched_rule: null, winner: false, shadowed_by: null, excluded: 'no rule for this event',
+        };
+    }
+    return {
+        event,
+        delivers: delivers(record),
+        authored_rung: record.authoredRung,
+        limit: record.limit,
+        capped_rung: record.cappedRung,
+        final_rung: record.finalRung,
+        gate: gateText(record, subject),
+        matched_rule: ruleText(record.matchedRule),
+        winner: record.winner,
+        shadowed_by: record.shadowedBy === null ? null : `${record.shadowedBy.ownerHandle}/${record.shadowedBy.name}`,
+        excluded: delivers(record) ? null : exclusionReason(record, subject),
+    };
+}
+function renderDoc(result) {
+    return [
+        `# ${result.name}`,
+        '',
+        `- kind: ${result.kind}`,
+        `- owner: ${result.owner}`,
+        `- ref: ${result.ref}`,
+        '',
+        nodeLine(result),
+        `subject: ${describeSubject(result.subject)}`,
+        '',
+        '## Rules',
+        '',
+        result.rules.length === 0
+            ? 'None for these events.'
+            : table(['on', 'deliver', 'match', 'if'], result.rules.map((r) => [r.on, r.deliver, r.match ?? '—', r.if ? 'yes' : '—'])),
+        '',
+        '## Delivery per event',
+        '',
+        table(['event', 'delivers', 'authored', 'limit', 'final', 'matched', 'if', 'why not'], result.events.map((e) => [e.event, e.delivers ? 'yes' : 'no', e.authored_rung, e.limit ?? '—', e.final_rung, e.matched_rule ?? '—', e.gate ?? '—', e.excluded ?? '—'])),
+    ].join('\n');
+}

package/dist/commands/sys/context/expose.d.ts

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

package/dist/commands/sys/context/expose.js

@@ -0,0 +1,66 @@
+// `crtr sys context expose` — attach file-read documents to files a local
+// command has already decided to display. It deliberately owns neither source
+// rendering nor an alternate routing policy: crtrd delivers and records it.
+import { accessSync, constants as fsConstants, realpathSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { defineLeaf } from '../../../core/command.js';
+import { expandTilde } from '../../../core/fs-utils.js';
+import { cliClient } from '../../api-client.js';
+import { envExecutionId, envNodeId } from '../../../shared/env.js';
+function readableRegularFiles(paths) {
+    const files = [];
+    const seen = new Set();
+    for (const path of paths) {
+        try {
+            const realpath = realpathSync(resolvePath(expandTilde(path)));
+            accessSync(realpath, fsConstants.R_OK);
+            if (!statSync(realpath).isFile() || seen.has(realpath))
+                continue;
+            seen.add(realpath);
+            files.push(realpath);
+        }
+        catch {
+            // A command can display several files. An unavailable one contributes no
+            // delivered context but must not hide guidance for the rest.
+        }
+    }
+    return files;
+}
+export const exposeLeaf = defineLeaf({
+    name: 'expose',
+    description: 'deliver file-read documents for file content a local command displays',
+    whenToUse: 'a local command has successfully rendered file contents and must place the documents their file-read rules deliver in that same output',
+    help: {
+        name: 'sys context expose',
+        summary: 'deliver file-read documents for files displayed by a command',
+        params: [
+            { kind: 'flag', name: 'file', type: 'path', required: true, repeatable: true, constraint: 'Files whose contents the caller displays. Relative paths resolve against this process’s cwd; leading ~ expands as for Read. Symlinks resolve to their target. Missing, unreadable, and non-file paths contribute nothing.' },
+        ],
+        output: [
+            { name: 'content', type: 'string', required: false, constraint: 'The delivered <auto-loaded-context> blocks, one per displayed file with new matches. Absent when nothing new matches or the caller is not inside a node. Prose output is the blocks alone, without a field label or acknowledgement.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Delivers through the current node’s file-read activity: records its exposures, and a watch and read event for each document delivered at content. Inherits node identity from CRTR_NODE_ID. The caller must include the returned blocks in the same output as the displayed files; this is not a preview operation.',
+        ],
+    },
+    run: async (input) => {
+        const nodeId = envNodeId()?.trim();
+        if (nodeId === undefined || nodeId === '')
+            return {};
+        const files = readableRegularFiles(input['file']);
+        if (files.length === 0)
+            return {};
+        const executionId = envExecutionId();
+        if (executionId === undefined || executionId === '')
+            return {};
+        const content = [];
+        for (const file of files) {
+            const delivered = await cliClient().nodeDelivery(nodeId, { activity: 'file-read', subject: file, expected_execution_id: executionId });
+            if (delivered.content !== '')
+                content.push(delivered.content);
+        }
+        return content.length === 0 ? {} : { content: content.join('\n') };
+    },
+    render: (result) => result['content'] ?? '',
+});

package/dist/commands/sys/context/prompt-review.d.ts

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

package/dist/commands/sys/context/prompt-review.js

@@ -0,0 +1,244 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../../../core/command.js';
+import { InputError, readStdinRaw } from '../../../core/io.js';
+import { userScopeRoot } from '../../../core/scope.js';
+import { ApiError } from '../../../api/index.js';
+import { cliClient } from '../../api-client.js';
+import { envNodeId } from '../../../shared/env.js';
+import { readMergedLaunchConfig, subKindsAvailableTo } from '../../../core/config.js';
+import { LAUNCH_SYSTEM_PROMPT } from '../../../core/runtime/launch-prompt.js';
+function resolveLifecycle(mode, lifecycle) {
+    if (lifecycle !== undefined)
+        return lifecycle;
+    return mode === 'orchestrator' ? 'resident' : 'terminal';
+}
+function readJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new InputError({
+            error: 'invalid_json',
+            message: `stdin is not valid JSON: ${String(err)}`,
+            field: 'stdin',
+            next: 'Pass the comments deck JSON on stdin.',
+        });
+    }
+}
+function parseBool(value, field, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    if (value === true || value === false)
+        return value;
+    if (typeof value !== 'string') {
+        throw new InputError({ error: 'invalid_field', message: `${field} must be true or false`, field, next: `Use true or false for ${field}.` });
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    throw new InputError({ error: 'invalid_field', message: `${field} must be true or false`, field, next: `Use true or false for ${field}.` });
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : null;
+}
+function approxTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function topLevelKinds() {
+    const registry = readMergedLaunchConfig().kinds;
+    return Object.entries(registry)
+        .filter(([kind]) => !kind.includes('/'))
+        .map(([kind, cfg]) => ({ kind, whenToUse: cfg.whenToUse }))
+        .sort((a, b) => a.kind.localeCompare(b.kind));
+}
+function subKindsFor(kind) {
+    return subKindsAvailableTo(kind);
+}
+function reviewList() {
+    const kinds = topLevelKinds();
+    const subPersonas = {};
+    for (const { kind } of kinds)
+        subPersonas[kind] = subKindsFor(kind);
+    return { kinds, modes: ['base', 'orchestrator'], lifecycles: ['terminal', 'resident'], subPersonas };
+}
+/** Fetch a node's detail via the API, mapping the daemon's 404 to null so an
+ *  absent/pruned `--node` id degrades to the node-less prompt (no runtime
+ *  substrate layers) instead of throwing. */
+async function fetchNodeOrNull(nodeId) {
+    if (nodeId === null)
+        return null;
+    try {
+        return await cliClient().getNode(nodeId);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return null;
+        throw err;
+    }
+}
+async function dryRun(nodeId, activity, override) {
+    const res = await cliClient().nodeDelivery(nodeId, { dry_run: true, activity, subject_override: override });
+    return { content: res.content, docs: (res.plan?.docs) ?? [] };
+}
+function spliceIntoScaffold(scaffold, block) {
+    const anchor = '\n\nGuidelines:';
+    const idx = scaffold.indexOf(anchor);
+    if (idx === -1)
+        return `${scaffold}\n\n${block}`;
+    return `${scaffold.slice(0, idx)}\n\n${block}${scaffold.slice(idx)}`;
+}
+function promptReviewPath() {
+    const reviewsDir = join(userScopeRoot(), 'prompt-reviews');
+    mkdirSync(reviewsDir, { recursive: true });
+    return join(reviewsDir, `${new Date().toISOString()}.md`);
+}
+function renderExportDeck(deck) {
+    const lines = [];
+    lines.push(`# Prompt review — ${deck.config.kind}/${deck.config.mode}`);
+    lines.push('');
+    lines.push('## Config');
+    lines.push(`- timestamp: ${new Date().toISOString()}`);
+    lines.push(`- kind: ${deck.config.kind}`);
+    lines.push(`- mode: ${deck.config.mode}`);
+    lines.push(`- lifecycle: ${deck.config.lifecycle}`);
+    lines.push(`- hasManager: ${String(deck.config.hasManager)}`);
+    lines.push(`- node: ${deck.config.node ?? '(none)'}`);
+    lines.push('');
+    lines.push('## Comments');
+    if (deck.comments.length === 0) {
+        lines.push('- none');
+    }
+    else {
+        for (const comment of deck.comments) {
+            lines.push(`### ${comment.label} (${comment.layerId})`);
+            lines.push(`- source: \`${comment.sourcePath ?? '(generated)'}\` (${comment.scope})`);
+            if (comment.anchor !== null) {
+                lines.push('> ' + comment.anchor.split('\n').join('\n> '));
+            }
+            lines.push(comment.body);
+            lines.push('');
+        }
+        if (lines[lines.length - 1] === '')
+            lines.pop();
+    }
+    lines.push('');
+    lines.push('## Prompt sources (edit these documents)');
+    const seen = new Set();
+    for (const source of deck.sources) {
+        const key = `${source.scope}:${source.path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        lines.push(`- ${source.label} — \`${source.path}\` (${source.scope})`);
+    }
+    lines.push('');
+    lines.push('These are review comments on an assembled system prompt; edit the listed documents (ref and owner) with `crtr doc edit` to address them.');
+    return lines.join('\n') + '\n';
+}
+function exportReview(deck) {
+    const path = promptReviewPath();
+    writeFileSync(path, renderExportDeck(deck), 'utf8');
+    return { path };
+}
+async function resolveDeck(input) {
+    const kind = input['kind'];
+    const mode = input['mode'] ?? 'base';
+    const lifecycle = resolveLifecycle(mode, input['lifecycle']);
+    const hasManager = parseBool(input['hasManager'], 'hasManager', true);
+    const nodeId = optionalString(input['node']);
+    if (kind === undefined || kind.trim() === '') {
+        throw new InputError({ error: 'missing_parameter', message: 'kind is required', field: 'kind', next: 'Pass --kind <kind> or use --list.' });
+    }
+    const node = await fetchNodeOrNull(nodeId ?? envNodeId() ?? null);
+    if (node === null) {
+        throw new InputError({ error: 'missing_parameter', message: 'prompt-review needs an existing node whose view it renders', field: 'node', next: 'Pass --node <id> of a node that exists, or run from inside a node.' });
+    }
+    const override = { kind, mode, lifecycle, hasManager };
+    const block = (await dryRun(node.node_id, 'system-prompt', override)).content;
+    const boot = await dryRun(node.node_id, 'boot', override);
+    const preferenceDocs = boot.docs.filter((r) => r.winner && r.finalRung === 'content' && !r.doc.ownNode && r.doc.kind === 'preference');
+    const layers = [
+        {
+            id: 'launch-scaffold', label: 'Launch scaffold', group: 'generated',
+            source: 'generated: launch scaffold', sourcePath: null, scope: 'generated',
+            included: true, condition: null, text: LAUNCH_SYSTEM_PROMPT,
+            tokens: approxTokens(LAUNCH_SYSTEM_PROMPT), chars: LAUNCH_SYSTEM_PROMPT.length,
+        },
+    ];
+    if (block !== '') {
+        layers.push({
+            id: 'preferences', label: 'Preferences', group: 'substrate',
+            source: 'delivery: system-prompt', sourcePath: null, scope: 'generated',
+            included: true, condition: null, text: block, tokens: approxTokens(block), chars: block.length,
+        });
+    }
+    if (boot.content !== '') {
+        layers.push({
+            id: 'boot-context', label: 'Boot context — context message, not system prompt',
+            group: 'substrate', source: 'delivery: boot', sourcePath: null, scope: 'runtime',
+            included: false, condition: 'session_start context message, not the system prompt',
+            text: boot.content, tokens: approxTokens(boot.content), chars: boot.content.length,
+        });
+    }
+    const assembled = spliceIntoScaffold(LAUNCH_SYSTEM_PROMPT, block);
+    const sources = preferenceDocs.map((r) => ({ id: r.doc.displayName, label: r.doc.displayName, path: r.doc.object.id, scope: r.doc.ownerHandle }));
+    return {
+        config: { kind, mode, lifecycle, hasManager, node: node?.node_id ?? null },
+        layers,
+        assembled,
+        total: { tokens: approxTokens(assembled), chars: assembled.length },
+        sources,
+    };
+}
+export const promptReviewLeaf = defineLeaf({
+    name: 'prompt-review',
+    description: 'inspect an assembled prompt and export review notes',
+    whenToUse: 'you want to inspect a composed persona prompt for a kind/mode combo, compare the space around it, or export review notes back to source files',
+    help: {
+        name: 'sys context prompt-review',
+        summary: 'inspect an assembled prompt and export review notes',
+        params: [
+            { kind: 'positional', name: 'action', type: 'string', required: false, constraint: 'Optional subcommand: export. Omit for the assembled prompt contract.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind to inspect. Required unless --list or export.' },
+            { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. Default: base.' },
+            { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Lifecycle axis. Default: base -> terminal, orchestrator -> resident.' },
+            { kind: 'flag', name: 'has-manager', type: 'string', required: false, default: 'true', constraint: 'Whether the node reports to a manager. Use true or false. Default: true.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'The node whose view and profile limits render the prompt. Defaults to the calling node (CRTR_NODE_ID); the node must exist unless --list or export.' },
+            { kind: 'flag', name: 'list', type: 'bool', required: false, constraint: 'List the available kinds, modes, lifecycles, and sub-personas.' },
+        ],
+        output: [
+            { name: 'config', type: 'object', required: false, constraint: 'Resolved config: {kind, mode, lifecycle, hasManager, node}.' },
+            { name: 'layers', type: 'object[]', required: false, constraint: 'Ordered prompt layers, including excluded alternatives and provenance.' },
+            { name: 'assembled', type: 'string', required: false, constraint: 'The assembled prompt string.' },
+            { name: 'total', type: 'object', required: false, constraint: 'Approximate token/char totals for included layers.' },
+            { name: 'sources', type: 'object[]', required: false, constraint: 'The preference documents delivered into the prompt: {id, label, path (the document ref), scope (the owner)}.' },
+            { name: 'kinds', type: 'object[]', required: false, constraint: 'Available kinds for --list.' },
+            { name: 'modes', type: 'string[]', required: false, constraint: 'Mode choices for --list.' },
+            { name: 'lifecycles', type: 'string[]', required: false, constraint: 'Lifecycle choices for --list.' },
+            { name: 'subPersonas', type: 'object', required: false, constraint: 'Available sub-personas keyed by kind for --list.' },
+            { name: 'path', type: 'string', required: false, constraint: 'Written markdown path for export.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only inspection, or writes a review markdown file under `~/.crouter/prompt-reviews/`.'],
+    },
+    run: async (input) => {
+        const action = input['action'];
+        const isList = input['list'] === true;
+        const hasManager = parseBool(input['hasManager'], 'hasManager', true);
+        if (action !== undefined && action !== 'export') {
+            throw new InputError({ error: 'unknown_action', message: `unknown action: ${action}`, field: 'action', next: 'Use `export` or omit the positional action.' });
+        }
+        if (action === 'export') {
+            const raw = await readStdinRaw();
+            const deck = readJson(raw);
+            return exportReview(deck);
+        }
+        if (isList)
+            return reviewList();
+        const deck = await resolveDeck({ ...input, hasManager });
+        return deck;
+    },
+});