@north-light/crouter 0.3.154

package/dist/commands/sys/feedback.js

@@ -0,0 +1,174 @@
+// `crtr sys feedback` — file a GitHub issue against the crtr repo when the
+// harness itself misbehaves (a command errors unexpectedly, hangs, churns, or
+// acts contrary to its documented contract). The agent supplies one prose
+// description; everything else (version, node identity, recent activity) is
+// auto-collected and templated into the issue body. gh-less / unauthed hosts
+// fall back to a durable local file so the report is never lost.
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { userScopeRoot } from '../../core/scope.js';
+import { readTelemetry } from '../../core/canvas/telemetry.js';
+import { ApiError } from '../../api/index.js';
+import { cliClient } from '../api-client.js';
+import { projectTier1Event, readLogSnapshot } from '../../core/events/read.js';
+import { readPackageVersion } from './shared.js';
+/** Canonical repo for crtr harness feedback — feedback is always about the
+ *  tool, regardless of which project the reporting agent is working in. */
+const FEEDBACK_REPO = 'crouton-labs/crouter';
+async function collectContext() {
+    const env = process.env;
+    const nodeId = env['CRTR_NODE_ID'] ?? null;
+    let cycle = null;
+    let logTail = [];
+    if (nodeId !== null) {
+        const meta = await fetchNodeOrNull(nodeId);
+        if (meta !== null && typeof meta.cycles === 'number')
+            cycle = meta.cycles;
+        logTail = readRecentActivity(nodeId);
+    }
+    const contextTokens = nodeId !== null ? readTelemetry(nodeId).context_tokens ?? null : null;
+    return {
+        version: readPackageVersion(),
+        platform: `${os.platform()} ${os.release()} (${os.arch()})`,
+        nodeId,
+        kind: env['CRTR_KIND'] ?? null,
+        mode: env['CRTR_MODE'] ?? null,
+        lifecycle: env['CRTR_LIFECYCLE'] ?? null,
+        cwd: env['CRTR_NODE_CWD'] ?? process.cwd(),
+        cycle,
+        contextTokens,
+        logTail,
+    };
+}
+/** Fetch a node's detail via the API, mapping the daemon's 404 (and any other
+ *  failure) to null so feedback context collection never fails because the node
+ *  is absent or the daemon is momentarily unreachable — the report must survive. */
+async function fetchNodeOrNull(nodeId) {
+    try {
+        return await cliClient().getNode(nodeId);
+    }
+    catch (err) {
+        if (err instanceof ApiError)
+            return null;
+        throw err;
+    }
+}
+/** Recent canonical broker events — best-effort, never throws. */
+function readRecentActivity(nodeId) {
+    try {
+        return readLogSnapshot({ nodeId, component: 'broker' }, false).items
+            .filter((item) => item.kind === 'event')
+            .slice(-15)
+            .map((item) => JSON.stringify(projectTier1Event(item.envelope)));
+    }
+    catch {
+        return [];
+    }
+}
+function deriveTitle(raw, message) {
+    const explicit = raw !== undefined && raw.trim() !== '' ? raw.trim() : undefined;
+    const base = explicit ?? message.split('\n')[0].trim();
+    const trimmed = base.length > 80 ? base.slice(0, 79) + '…' : base;
+    return `[feedback] ${trimmed}`;
+}
+function buildBody(message, ctx) {
+    const rows = [
+        `| crtr version | \`${ctx.version}\` |`,
+        `| platform | ${ctx.platform} |`,
+    ];
+    if (ctx.nodeId !== null) {
+        rows.push(`| node id | \`${ctx.nodeId}\` |`);
+        rows.push(`| kind / mode / lifecycle | ${ctx.kind ?? '?'} / ${ctx.mode ?? '?'} / ${ctx.lifecycle ?? '?'} |`);
+        if (ctx.cycle !== null)
+            rows.push(`| cycle | ${ctx.cycle} |`);
+        if (ctx.contextTokens !== null)
+            rows.push(`| context tokens | ${ctx.contextTokens.toLocaleString('en-US')} |`);
+    }
+    if (ctx.cwd !== null)
+        rows.push(`| working dir | \`${ctx.cwd}\` |`);
+    const parts = [
+        message.trim(),
+        '',
+        '---',
+        '_Filed via `crtr sys feedback` — context below auto-attached by the harness._',
+        '',
+        '### Environment',
+        '| | |',
+        '|---|---|',
+        ...rows,
+    ];
+    if (ctx.logTail.length > 0) {
+        parts.push('', `### Recent node activity (last ${ctx.logTail.length} log events)`, '```jsonl', ...ctx.logTail, '```');
+    }
+    return parts.join('\n') + '\n';
+}
+/** Persist a report locally when gh can't file it, so nothing is lost. Returns
+ *  the absolute path written. */
+function saveLocally(title, body) {
+    const dir = join(userScopeRoot(), 'feedback');
+    mkdirSync(dir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const path = join(dir, `${ts}.md`);
+    writeFileSync(path, `# ${title}\n\n${body}`, 'utf8');
+    return path;
+}
+export const sysFeedbackLeaf = defineLeaf({
+    name: 'feedback',
+    description: 'report a crtr harness bug as a GitHub issue',
+    whenToUse: 'a crtr command itself misbehaves — it errors unexpectedly, hangs, churns, double-spawns, or acts contrary to its documented contract. NOT for your task work or decisions a human should make (that is `crtr human ask`); this reports the TOOL, filing an issue against the crtr repo with your node context auto-attached.',
+    help: {
+        name: 'sys feedback',
+        summary: 'file a GitHub issue describing a crtr harness bug, with node context auto-attached',
+        params: [
+            {
+                kind: 'positional',
+                name: 'message',
+                required: true,
+                constraint: 'What broke, in your own words: the command you ran, what you expected, what happened instead. Be concrete — this is the only part a human writes; everything else is auto-collected.',
+            },
+            {
+                kind: 'flag',
+                name: 'title',
+                type: 'string',
+                required: false,
+                constraint: 'Issue title. Default: first line of the message, truncated.',
+            },
+        ],
+        output: [
+            { name: 'status', type: 'string', required: true, constraint: 'filed | saved-locally.' },
+            { name: 'url', type: 'string', required: false, constraint: 'Issue URL when status is filed.' },
+            { name: 'path', type: 'string', required: false, constraint: 'Local report path when status is saved-locally (gh unavailable).' },
+            { name: 'error', type: 'string', required: false, constraint: 'Why filing fell back to local save.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            `Opens a public GitHub issue on ${FEEDBACK_REPO} via gh.`,
+            'On gh failure (missing / unauthenticated), writes the report to ~/.crouter/feedback/ instead — never lost.',
+        ],
+    },
+    run: async (input) => {
+        const message = input['message']?.trim();
+        if (message === undefined || message === '') {
+            throw usage('feedback message is required: describe what broke. Run `crtr sys feedback -h`.');
+        }
+        const ctx = await collectContext();
+        const title = deriveTitle(input['title'], message);
+        const body = buildBody(message, ctx);
+        const res = spawnSync('gh', ['issue', 'create', '--repo', FEEDBACK_REPO, '--title', title, '--body-file', '-'], { input: body, encoding: 'utf8' });
+        if (res.error === undefined && res.status === 0) {
+            const url = res.stdout.trim().split('\n').filter((l) => l.startsWith('http')).pop() ?? res.stdout.trim();
+            return { status: 'filed', url };
+        }
+        // gh missing, unauthenticated, or the API call failed — persist locally so
+        // the report survives, and tell the agent how to escalate.
+        const reason = res.error !== undefined
+            ? `gh not available: ${res.error.message}`
+            : (res.stderr?.trim() || `gh exited ${res.status}`);
+        const path = saveLocally(title, body);
+        return { status: 'saved-locally', path, error: reason };
+    },
+});

package/dist/commands/sys/logs.d.ts

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

package/dist/commands/sys/logs.js

@@ -0,0 +1,127 @@
+import { defineLeaf } from '../../core/command.js';
+import { isSafeNodeId } from '../../core/canvas/paths.js';
+import { usage } from '../../core/errors.js';
+import { validateOperationId } from '../../core/events/operation-id.js';
+import { readLogSnapshot } from '../../core/events/read.js';
+import { emitLine, isJsonOutput } from '../../core/io.js';
+const ISO_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/u;
+const MAX_PATTERN_BYTES = 4_096;
+function invalidFlag(flag, received, expected) {
+    throw usage(`--${flag} ${expected}; received ${JSON.stringify(received)}.`, {
+        received,
+        field: flag,
+        next: `Retry with a value that ${expected}.`,
+    });
+}
+function parseTimestamp(flag, raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = raw.trim();
+    const match = ISO_TIMESTAMP.exec(value);
+    const parsed = Date.parse(value);
+    if (match === null || !Number.isFinite(parsed)) {
+        invalidFlag(flag, raw, 'must be a valid ISO 8601 timestamp with a timezone');
+    }
+    const calendar = new Date(Date.parse(`${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}Z`));
+    if (calendar.getUTCFullYear() !== Number(match[1])
+        || calendar.getUTCMonth() + 1 !== Number(match[2])
+        || calendar.getUTCDate() !== Number(match[3])
+        || calendar.getUTCHours() !== Number(match[4])
+        || calendar.getUTCMinutes() !== Number(match[5])
+        || calendar.getUTCSeconds() !== Number(match[6])) {
+        invalidFlag(flag, raw, 'must be a valid ISO 8601 timestamp with a timezone');
+    }
+    return parsed;
+}
+function parseNodeId(raw) {
+    if (raw === undefined)
+        return undefined;
+    const nodeId = raw.trim();
+    if (!isSafeNodeId(nodeId)) {
+        invalidFlag('node', raw, 'must be one non-empty path segment of at most 128 UTF-8 bytes');
+    }
+    return nodeId;
+}
+function parseOperationId(raw) {
+    if (raw === undefined)
+        return undefined;
+    const operationId = raw.trim();
+    try {
+        return validateOperationId(operationId);
+    }
+    catch {
+        invalidFlag('operation', raw, 'must be 32 lowercase non-zero hexadecimal characters');
+    }
+}
+function parsePattern(raw) {
+    if (raw === undefined)
+        return undefined;
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    if (bytes === 0 || bytes > MAX_PATTERN_BYTES) {
+        invalidFlag('pattern', raw, `must be a non-empty literal of at most ${MAX_PATTERN_BYTES.toLocaleString('en-US')} UTF-8 bytes`);
+    }
+    return raw;
+}
+function renderEvent(envelope) {
+    const { v: _version, ts, level, event, component, operation_id: operationId, ...optional } = envelope;
+    const suffix = Object.keys(optional).length === 0 ? '' : ` ${JSON.stringify(optional)}`;
+    return `${ts} ${level.toUpperCase()} ${component} ${event} op=${operationId}${suffix}`;
+}
+export const sysLogsLeaf = defineLeaf({
+    name: 'logs',
+    description: 'inspect recent local runtime events',
+    whenToUse: 'you need a bounded local diagnostic snapshot, especially to correlate a node with an operation ID.',
+    help: {
+        name: 'sys logs',
+        summary: 'show the latest 200 matching local event and raw-residue records, oldest first',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Safe node ID; the node need not still be active.' },
+            { kind: 'flag', name: 'component', type: 'enum', choices: ['daemon', 'broker', 'web'], required: false, constraint: 'Owning runtime component.' },
+            { kind: 'flag', name: 'operation', type: 'string', required: false, constraint: 'Exact 32-character lowercase non-zero hexadecimal operation ID.' },
+            { kind: 'flag', name: 'since', type: 'string', required: false, constraint: 'Inclusive ISO 8601 lower bound with a timezone.' },
+            { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Inclusive ISO 8601 upper bound with a timezone; cannot precede --since.' },
+            { kind: 'flag', name: 'level', type: 'enum', choices: ['debug', 'info', 'warn', 'error'], required: false, constraint: 'Minimum severity.' },
+            { kind: 'flag', name: 'pattern', type: 'string', required: false, constraint: 'Case-insensitive literal, non-empty and at most 4,096 UTF-8 bytes.' },
+        ],
+        output: [
+            { name: 'record', type: 'EventEnvelope | RAW line', required: false, constraint: 'At most 200 matches, oldest to newest. Default canonical summaries occupy one line; unstructured daemon/broker residue is visibly prefixed RAW. Machine JSON output is canonical EventEnvelope JSONL only.' },
+        ],
+        outputKind: 'jsonl',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nodeId = parseNodeId(input.node);
+        const operationId = parseOperationId(input.operation);
+        const sinceMs = parseTimestamp('since', input.since);
+        const untilMs = parseTimestamp('until', input.until);
+        if (sinceMs !== undefined && untilMs !== undefined && sinceMs > untilMs) {
+            throw usage('--since cannot be later than --until.', {
+                received: { since: input.since, until: input.until },
+                field: 'since/until',
+                next: 'Retry with an inclusive range whose lower bound does not exceed its upper bound.',
+            });
+        }
+        const query = {
+            nodeId,
+            component: input.component,
+            operationId,
+            sinceMs,
+            untilMs,
+            minimumLevel: input.level,
+            pattern: parsePattern(input.pattern),
+        };
+        const json = isJsonOutput();
+        const snapshot = readLogSnapshot(query, !json);
+        for (const item of snapshot.items) {
+            if (item.kind === 'event') {
+                if (json)
+                    emitLine({ ...item.envelope });
+                else
+                    process.stdout.write(`${renderEvent(item.envelope)}\n`);
+            }
+            else if (!json) {
+                process.stdout.write(`RAW ${item.source} ${new Date(item.effectiveTsMs).toISOString()} ${JSON.stringify(item.content)}\n`);
+            }
+        }
+    },
+});

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

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

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

@@ -0,0 +1,291 @@
+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 { readMergedLaunchConfig, subKindsAvailableTo } from '../../core/config.js';
+import { LAUNCH_SYSTEM_PROMPT } from '../../core/runtime/launch-prompt.js';
+// De-barreled imports: substrate/index.js re-exports subject.js (canvas-db), so
+// this CLI leaf imports the PURE render fns from render.js and the pure subject
+// fields from subject-fields.js/schema.js directly, never the barrel. Spine
+// depth is computed via the API (spineDepthViaApi), not subject.js's spineDepth.
+import { renderPreferencesForSubject, renderKnowledgeForSubject } from '../../core/substrate/render.js';
+import { scopeForCwd, profileNameFor } from '../../core/substrate/subject-fields.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;
+    }
+}
+/** Spine distance from `nodeId` up to its root orchestrator, computed via the
+ *  API (crtrd) parent-walk rather than a direct canvas-db read: count hops up
+ *  the parent chain until a node with no parent (the root, depth 0). Cycle-
+ *  guarded; a 404 mid-walk (a pruned ancestor) stops the walk. Mirrors
+ *  subject.ts's `spineDepth` but keeps this CLI leaf off the canvas-db. */
+async function spineDepthViaApi(nodeId) {
+    let cur = nodeId;
+    const seen = new Set();
+    let hops = 0;
+    while (cur !== null) {
+        if (seen.has(cur))
+            break;
+        seen.add(cur);
+        const node = await fetchNodeOrNull(cur);
+        if (node === null || node.parent == null)
+            break;
+        cur = node.parent;
+        hops++;
+    }
+    return hops;
+}
+async function buildReviewSubject(kind, mode, lifecycle, hasManager, node) {
+    const cwd = node?.cwd ?? process.cwd();
+    return {
+        kind,
+        mode,
+        lifecycle,
+        hasManager,
+        cwd,
+        scope: scopeForCwd(cwd),
+        orchestration: { depth: node !== null ? await spineDepthViaApi(node.node_id) : 0 },
+        profile: profileNameFor(node?.profile_id),
+    };
+}
+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)');
+    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 source files 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);
+    const subject = await buildReviewSubject(kind, mode, lifecycle, hasManager, node);
+    const { block, contentDocs, tree } = renderPreferencesForSubject(subject);
+    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,
+        },
+        ...contentDocs.map((d) => ({
+            id: d.name, label: d.name, group: 'substrate',
+            source: `memory: ${d.name}`, sourcePath: d.path, scope: d.scope,
+            included: true, condition: null, text: d.body,
+            tokens: approxTokens(d.body), chars: d.body.length,
+        })),
+    ];
+    if (tree !== '') {
+        layers.push({
+            id: 'preference-catalog', label: 'Preference catalog (routing entries)', group: 'substrate',
+            source: 'generated: preference catalog', sourcePath: null, scope: 'generated',
+            included: true, condition: null, text: tree, tokens: approxTokens(tree), chars: tree.length,
+        });
+    }
+    if (node !== null) {
+        const knowledge = renderKnowledgeForSubject(subject, node.node_id);
+        if (knowledge !== '') {
+            layers.push({
+                id: 'memory-knowledge', label: 'Memory (knowledge) — context message, not system prompt',
+                group: 'substrate', source: 'runtime-spliced', sourcePath: null, scope: 'runtime',
+                included: false, condition: 'session_start context message, not the system prompt',
+                text: knowledge, tokens: approxTokens(knowledge), chars: knowledge.length,
+            });
+        }
+    }
+    const assembled = spliceIntoScaffold(LAUNCH_SYSTEM_PROMPT, block);
+    const sources = [];
+    const seen = new Set();
+    for (const d of contentDocs) {
+        const key = `${d.scope}:${d.path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        sources.push({ id: d.name, label: d.name, path: d.path, scope: d.scope });
+    }
+    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 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: 'Optional node id. When the node exists, runtime substrate layers are appended.' },
+            { 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: 'De-duplicated source files referenced by the prompt.' },
+            { 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;
+    },
+});

package/dist/commands/sys/promptstudio.d.ts

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

package/dist/commands/sys/promptstudio.js

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+import { defineLeaf } from '../../core/command.js';
+import { startWebServer } from '../../clients/web/server.js';
+const DEFAULT_PORT = 7878;
+const PROMPT_STUDIO_PATH = '/views/prompt-review';
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => {
+            /* the printed URL is enough when no browser opener is available */
+        });
+        child.unref();
+    }
+    catch {
+        /* the printed URL is enough when no browser opener is available */
+    }
+}
+export const sysPromptStudioLeaf = defineLeaf({
+    name: 'promptstudio',
+    description: 'open Prompt Studio in the browser',
+    whenToUse: 'you want the Prompt Studio browser UI — a prompt review surface for toggling crouter persona/mode/lifecycle configs, inspecting the assembled system prompt, comparing configurations, and exporting review comments with source-file pointers.',
+    help: {
+        name: 'sys promptstudio',
+        summary: 'start the crouter web server and open Prompt Studio directly',
+        params: [
+            { kind: 'flag', name: 'port', type: 'int', required: false, default: DEFAULT_PORT, constraint: `TCP port to bind on 127.0.0.1. Default ${DEFAULT_PORT}.` },
+            { kind: 'flag', name: 'dev', type: 'bool', required: false, default: false, constraint: 'Serve the web shell through Vite middleware/HMR while iterating on Prompt Studio or the web client.' },
+        ],
+        output: [
+            { name: 'url', type: 'string', required: true, constraint: 'Prompt Studio URL opened in the browser.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Binds the same long-running local web server as the surface web serve leaf, opens `/views/prompt-review` in the default browser, and keeps serving until ctrl+c/SIGTERM.',
+            'The server is a crtrd `/v1/*` reverse-proxy shell (identical to `surface web serve`) hosting the Prompt Studio SPA; it opens no canvas.db, so crtrd must be running.',
+        ],
+    },
+    run: async (input) => {
+        const port = input['port'] ?? DEFAULT_PORT;
+        const dev = input['dev'] ?? false;
+        const server = await startWebServer({ port, dev });
+        const url = `${server.url}${PROMPT_STUDIO_PATH}`;
+        process.stdout.write(`Prompt Studio serving at ${url}${dev ? ' (--dev: Vite middleware)' : ''}\n` +
+            `  api proxy:    ${server.url}/v1/* → crtrd\n` +
+            `  events (SSE): GET  ${server.url}/__crtr/events\n` +
+            `  shell assets: ${dev ? 'Vite middleware (HMR)' : server.clientDir}\n` +
+            `  (ctrl+c to stop)\n`);
+        openBrowser(url);
+        await new Promise((resolveShutdown) => {
+            const shutdown = () => {
+                void server.close().then(() => resolveShutdown());
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+            process.once('SIGHUP', shutdown);
+        });
+        return { url };
+    },
+    render: () => '',
+});