@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,115 @@
+import type { InputParam } from '../../../core/help.js';
+import type { DeliveryActivity, HypotheticalNodeDTO } from '../../../api/dto/delivery.js';
+import type { NodeConfigSubject } from '../../../core/substrate/subject-fields.js';
+import { type Rung } from '../../../core/substrate/schema.js';
+/** The activities whose dry run carries a plan: each is a rule `on` name. */
+export declare const PLANNED_EVENTS: readonly ["boot", "workspace-open", "file-read", "document-read", "command", "pre-command", "slash-command"];
+export type PlannedEvent = (typeof PLANNED_EVENTS)[number];
+declare const SNAPSHOT_PARAMS: InputParam[];
+export { SNAPSHOT_PARAMS };
+export declare const resolveLeaf: import("../../../core/command.js").LeafDef;
+export interface ContextSnapshot {
+    /** A live node the dry run reads, or starts a simulation from. */
+    nodeId: string | null;
+    /** The simulated node; null when the dry run reads a live node as it is. */
+    hypothetical: HypotheticalNodeDTO | null;
+    override: Partial<NodeConfigSubject>;
+    /** --node named an id that does not exist; the node is simulated. */
+    nodeMissing: boolean;
+}
+/** A live node when one is named (or this runs inside one) and neither --cwd
+ *  nor --profile dials it; otherwise a simulated node, starting from the live
+ *  node when there is one. */
+export declare function buildSnapshot(input: Record<string, unknown>): Promise<ContextSnapshot>;
+/** The fields every result leads with: which node, or which simulated one. */
+export declare function snapshotHead(snapshot: ContextSnapshot): Record<string, unknown>;
+export interface PayloadFlags {
+    file: string | null;
+    /** `document-read`: the document read. */
+    readName: string | null;
+    command: string | null;
+}
+/** The activity's subject string from the flags that carry it. An activity
+ *  invoked without its payload matches nothing. */
+export declare function subjectFor(event: PlannedEvent, flags: PayloadFlags): string | undefined;
+export interface PlanRule {
+    on: string;
+    match?: string[];
+    matchFrontmatter?: Record<string, unknown>;
+    if?: unknown;
+    deliver: Rung;
+}
+export interface PlanDoc {
+    object: {
+        id: string;
+    };
+    ownerHandle: string;
+    kind: string;
+    name: string;
+    displayName: string;
+}
+export type GateOutcome = {
+    pass: true;
+} | {
+    pass: false;
+    reason: string;
+};
+export interface PlanRecord {
+    doc: PlanDoc;
+    authoredRules: Array<{
+        rule: PlanRule;
+        matched: boolean;
+        gate: GateOutcome;
+    }>;
+    matchedRule: PlanRule | null;
+    authoredRung: Rung;
+    limit: Rung | null;
+    cappedRung: Rung;
+    ruleGate: GateOutcome | null;
+    finalRung: Rung;
+    winner: boolean;
+    shadowedBy: PlanDoc | null;
+}
+export interface Plan {
+    on: string;
+    subject: NodeConfigSubject | null;
+    docs: PlanRecord[];
+}
+export declare function dryRun(snapshot: ContextSnapshot, activity: DeliveryActivity, subject?: string): Promise<{
+    plan: Plan;
+    content: string;
+}>;
+export declare function subjectSummary(subject: NodeConfigSubject | null): Record<string, unknown>;
+export declare function optionalString(value: unknown): string | null;
+export interface DocRow {
+    name: string;
+    kind: string;
+    owner: string;
+    ref: string;
+    authored_rung: Rung;
+    limit: Rung | null;
+    capped_rung: Rung;
+    final_rung: Rung;
+    winner: boolean;
+    shadowed_by: string | null;
+    gate: string | null;
+    matched_rule: string | null;
+    excluded?: string;
+}
+/** A document delivers when it holds its name and resolved to a level above none. */
+export declare function delivers(record: PlanRecord): boolean;
+export declare function docRow(record: PlanRecord, includeAll: boolean, subject: NodeConfigSubject | null): DocRow;
+/** The rule `if` verdict as one cell: `pass`, or `fail:` plus the failing clauses. */
+export declare function gateText(record: PlanRecord, subject: NodeConfigSubject | null): string | null;
+export declare function ruleText(rule: PlanRule | null): string | null;
+/** Why a considered document delivers nothing, in the order the planner applies its checks. */
+export declare function exclusionReason(record: PlanRecord, subject: NodeConfigSubject | null): string;
+/** Which node the result describes, live or simulated. */
+export declare function nodeLine(head: {
+    node?: string;
+    cwd?: string;
+    node_missing?: boolean;
+}): string;
+export declare function describeSubject(subject: Record<string, unknown>): string;
+export declare function cell(v: unknown): string;
+export declare function table(cols: string[], rows: string[][]): string;

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

@@ -0,0 +1,326 @@
+// `crtr sys context resolve` — the forward question: for one node and one
+// activity, what does delivery hand it, at which level, and why. Reads the
+// daemon's dry run (`POST /v1/delivery/dry-run`), the same plan and render the
+// live delivery uses, so a reported delivery can never differ from an actual
+// one. The node may be a live one, one that does not exist (described by
+// --cwd, --profile and the subject flags), or a live one dialled away from.
+// The dry run writes nothing.
+//
+// The snapshot builder and record formatters here are shared with
+// `sys context doc`, the reverse half of the same read surface.
+import { resolve as resolvePath } from 'node:path';
+import { defineLeaf } from '../../../core/command.js';
+import { ApiError } from '../../../api/index.js';
+import { cliClient } from '../../api-client.js';
+import { envNodeId } from '../../../shared/env.js';
+import { explainGate, formatClause } from '../../../core/substrate/gate-explain.js';
+import { rungAtLeast } from '../../../core/substrate/schema.js';
+/** The activities whose dry run carries a plan: each is a rule `on` name. */
+export const PLANNED_EVENTS = ['boot', 'workspace-open', 'file-read', 'document-read', 'command', 'pre-command', 'slash-command'];
+const SNAPSHOT_PARAMS = [
+    { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'The node whose view, owners, and profile limits apply. Defaults to the calling node (CRTR_NODE_ID). A node that does not exist is simulated from the other flags and reported as `node_missing`.' },
+    { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Simulate the node working in this directory: the repos enclosing it apply. Without --node and outside a node, the node simulated is one that does not exist, working in the current directory.' },
+    { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Simulate the node under this profile (id or name), whose delivery limits apply. Defaults to the node\u2019s profile, else the profile pinned to the directory.' },
+    { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Override the node kind that rule `if` conditions see. A simulated node defaults to `general`.' },
+    { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Override the node mode that rule `if` conditions see. A simulated node defaults to `base`.' },
+    { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Override the node lifecycle that rule `if` conditions see. A simulated node defaults to `terminal` for base, `resident` for orchestrator.' },
+    { kind: 'flag', name: 'has-manager', type: 'enum', choices: ['true', 'false'], required: false, constraint: 'Override whether rule `if` conditions see the node as having a manager. A simulated node defaults to true.' },
+];
+export { SNAPSHOT_PARAMS };
+export const resolveLeaf = defineLeaf({
+    name: 'resolve',
+    description: 'resolve what a node receives for one delivery activity',
+    whenToUse: 'you are asking what a node (or one that does not exist yet) actually receives — at boot, on opening a workspace, on reading a file or a document, around a command, or as slash commands — and why each document is in or out',
+    help: {
+        name: 'sys context resolve',
+        summary: 'resolve the documents a node receives for one delivery activity',
+        params: [
+            ...SNAPSHOT_PARAMS,
+            { kind: 'flag', name: 'event', type: 'enum', choices: [...PLANNED_EVENTS], required: false, constraint: 'The rule `on` name to resolve. Defaults to `boot`. Ignored when --all-events is set.' },
+            { kind: 'flag', name: 'all-events', type: 'bool', required: false, constraint: 'Resolve every event instead of one, and report each plan separately.' },
+            { kind: 'flag', name: 'file', type: 'path', required: false, constraint: 'Payload for `--event file-read`: the file that was read. Without it, no file-read rule matches.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Payload for `--event document-read`: 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 `--event command` / `--event pre-command`: the command string.' },
+            { kind: 'flag', name: 'granularity', type: 'enum', choices: ['summary', 'docs', 'assembled'], required: false, constraint: '`summary` folds to per-level counts; `docs` reports one row per document; `assembled` returns the rendered text (at boot, the system-prompt preferences followed by the boot context). Defaults to `docs`.' },
+            { kind: 'flag', name: 'all', type: 'bool', required: false, constraint: 'At `docs` granularity, include every considered document, not just the ones that deliver, with the reason each was excluded.' },
+        ],
+        output: [
+            { name: 'node', type: 'string', required: false, constraint: 'The node the dry run 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 rule `if` conditions were evaluated against, overrides applied.' },
+            { name: 'event', type: 'string', required: false, constraint: 'The resolved event. Absent with --all-events, where every entry in `plans` carries its own.' },
+            { name: 'docs', type: 'array', required: false, constraint: 'At `docs` granularity, one entry per document: name, kind, owner, ref, authored_rung, limit, capped_rung, final_rung, winner, shadowed_by, gate, matched_rule, and excluded when --all includes a non-delivering document.' },
+            { name: 'counts', type: 'object', required: false, constraint: 'At `summary` granularity: {considered, delivered: {content, preview, name}, delivered_total, excluded: {<reason>: count}}.' },
+            { name: 'assembled', type: 'string', required: false, constraint: 'At `assembled` granularity: the text the node would receive.' },
+            { name: 'plans', type: 'array', required: false, constraint: 'With --all-events: one result per event, each shaped as above.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only; the dry run records no watch, event, or exposure.'],
+    },
+    run: async (input) => {
+        const snapshot = await buildSnapshot(input);
+        const granularity = input['granularity'] ?? 'docs';
+        const includeAll = input['all'] === true;
+        const events = input['allEvents'] === true ? [...PLANNED_EVENTS] : [input['event'] ?? 'boot'];
+        const flags = { file: optionalString(input['file']), readName: optionalString(input['name']), command: optionalString(input['command']) };
+        const sections = [];
+        let subject = null;
+        for (const event of events) {
+            const { plan, content } = await dryRun(snapshot, event, subjectFor(event, flags));
+            subject ??= plan.subject;
+            sections.push(await planSection(snapshot, event, plan, content, granularity, includeAll));
+        }
+        const head = { ...snapshotHead(snapshot), subject: subjectSummary(subject) };
+        return events.length === 1 ? { ...head, ...sections[0] } : { ...head, plans: sections };
+    },
+    render: (result) => renderResolve(result),
+});
+/** A live node when one is named (or this runs inside one) and neither --cwd
+ *  nor --profile dials it; otherwise a simulated node, starting from the live
+ *  node when there is one. */
+export async function buildSnapshot(input) {
+    const named = optionalString(input['node']);
+    let nodeId = named ?? optionalString(envNodeId());
+    let nodeMissing = false;
+    if (nodeId !== null && !(await nodeExists(nodeId))) {
+        if (named === null)
+            nodeId = null; // a stale CRTR_NODE_ID: simulate instead
+        else {
+            nodeMissing = true;
+            nodeId = null;
+        }
+    }
+    const cwdFlag = optionalString(input['cwd']);
+    const profile = optionalString(input['profile']);
+    const override = {};
+    const kind = optionalString(input['kind']);
+    if (kind !== null)
+        override.kind = kind;
+    if (input['mode'] !== undefined)
+        override.mode = input['mode'];
+    if (input['lifecycle'] !== undefined)
+        override.lifecycle = input['lifecycle'];
+    const hasManager = optionalString(input['hasManager']);
+    if (hasManager !== null)
+        override.hasManager = hasManager === 'true';
+    if (nodeId !== null && cwdFlag === null && profile === null)
+        return { nodeId, hypothetical: null, override, nodeMissing };
+    const hypothetical = {
+        ...(cwdFlag !== null ? { cwd: resolvePath(cwdFlag) } : nodeId === null ? { cwd: process.cwd() } : {}),
+        ...(profile === null ? {} : { profile }),
+        ...(override.kind === undefined ? {} : { kind: override.kind }),
+        ...(override.mode === undefined ? {} : { mode: override.mode }),
+        ...(override.lifecycle === undefined ? {} : { lifecycle: override.lifecycle }),
+        ...(override.hasManager === undefined ? {} : { has_manager: override.hasManager }),
+    };
+    return { nodeId, hypothetical, override: {}, nodeMissing };
+}
+async function nodeExists(nodeId) {
+    try {
+        await cliClient().getNode(nodeId);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return false;
+        throw err;
+    }
+}
+/** The fields every result leads with: which node, or which simulated one. */
+export function snapshotHead(snapshot) {
+    return {
+        ...(snapshot.nodeId === null ? {} : { node: snapshot.nodeId }),
+        ...(snapshot.hypothetical?.cwd === undefined ? {} : { cwd: snapshot.hypothetical.cwd }),
+        ...(snapshot.nodeMissing ? { node_missing: true } : {}),
+    };
+}
+/** The activity's subject string from the flags that carry it. An activity
+ *  invoked without its payload matches nothing. */
+export function subjectFor(event, flags) {
+    if (event === 'file-read')
+        return flags.file === null ? undefined : resolvePath(flags.file);
+    if (event === 'document-read')
+        return flags.readName ?? undefined;
+    if (event === 'command' || event === 'pre-command')
+        return flags.command ?? undefined;
+    return undefined;
+}
+export async function dryRun(snapshot, activity, subject) {
+    // An activity invoked without its payload matches nothing; the route refuses it outright.
+    if (subject === undefined && (activity === 'file-read' || activity === 'document-read' || activity === 'command' || activity === 'pre-command')) {
+        return { plan: { on: activity, subject: null, docs: [] }, content: '' };
+    }
+    const request = {
+        activity,
+        ...(subject === undefined ? {} : { subject }),
+        ...(snapshot.nodeId === null ? {} : { node: snapshot.nodeId }),
+        ...(snapshot.hypothetical === null ? {} : { hypothetical: snapshot.hypothetical }),
+        ...(Object.keys(snapshot.override).length === 0 ? {} : { subject_override: snapshot.override }),
+    };
+    const res = await cliClient().deliveryDryRun(request);
+    const plan = (res.plan ?? { on: activity, subject: null, docs: [] });
+    return { plan, content: res.content };
+}
+export function subjectSummary(subject) {
+    if (subject === null)
+        return {};
+    return {
+        kind: subject.kind,
+        mode: subject.mode,
+        lifecycle: subject.lifecycle,
+        hasManager: subject.hasManager,
+        profile: subject.profile,
+        repo: subject.repo,
+        depth: subject.orchestration.depth,
+    };
+}
+export function optionalString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : null;
+}
+async function planSection(snapshot, event, plan, content, granularity, includeAll) {
+    if (granularity === 'assembled') {
+        if (event !== 'boot')
+            return { event, assembled: content };
+        const prefs = (await dryRun(snapshot, 'system-prompt')).content;
+        return { event, assembled: [prefs, content].filter((s) => s !== '').join('\n\n') };
+    }
+    if (granularity === 'summary')
+        return { event, counts: countsOf(plan) };
+    return { event, docs: plan.docs.filter((r) => includeAll || delivers(r)).map((r) => docRow(r, includeAll, plan.subject)) };
+}
+/** A document delivers when it holds its name and resolved to a level above none. */
+export function delivers(record) {
+    return record.winner && rungAtLeast(record.finalRung, 'name');
+}
+export function docRow(record, includeAll, subject) {
+    const row = {
+        name: record.doc.displayName,
+        kind: record.doc.kind,
+        owner: record.doc.ownerHandle,
+        ref: record.doc.object.id,
+        authored_rung: record.authoredRung,
+        limit: record.limit,
+        capped_rung: record.cappedRung,
+        final_rung: record.finalRung,
+        winner: record.winner,
+        shadowed_by: record.shadowedBy === null ? null : `${record.shadowedBy.ownerHandle}/${record.shadowedBy.name}`,
+        gate: gateText(record, subject),
+        matched_rule: ruleText(record.matchedRule),
+    };
+    if (includeAll && !delivers(record))
+        row.excluded = exclusionReason(record, subject);
+    return row;
+}
+/** The rule `if` verdict as one cell: `pass`, or `fail:` plus the failing clauses. */
+export function gateText(record, subject) {
+    const gate = record.ruleGate;
+    if (gate === null)
+        return null;
+    return gate.pass ? 'pass' : `fail: ${gateReason(record, subject, gate.reason)}`;
+}
+function gateReason(record, subject, fallback) {
+    const failing = record.authoredRules.find((d) => !d.gate.pass)?.rule.if;
+    const clauses = failing === undefined || subject === null ? [] : explainGate(failing, subject);
+    return clauses.length === 0 ? fallback : clauses.map(formatClause).join('; ');
+}
+export function ruleText(rule) {
+    if (rule === null)
+        return null;
+    const parts = [`deliver=${rule.deliver}`];
+    if (rule.match !== undefined)
+        parts.push(`match=${rule.match.join(',')}`);
+    if (rule.matchFrontmatter !== undefined)
+        parts.push('match-frontmatter');
+    if (rule.if !== undefined)
+        parts.push('if');
+    return parts.join(' ');
+}
+/** Why a considered document delivers nothing, in the order the planner applies its checks. */
+export function exclusionReason(record, subject) {
+    if (record.shadowedBy !== null)
+        return `shadowed by ${record.shadowedBy.ownerHandle}/${record.shadowedBy.name}`;
+    if (record.authoredRules.length === 0)
+        return 'no rule for this event';
+    if (record.matchedRule === null) {
+        return record.ruleGate !== null && !record.ruleGate.pass
+            ? `rule if: ${gateReason(record, subject, record.ruleGate.reason)}`
+            : 'no rule matched this event\u2019s payload';
+    }
+    if (record.cappedRung === 'none')
+        return `limited to none by the profile\u2019s delivery limit (authored ${record.authoredRung})`;
+    return `resolved to none (authored ${record.authoredRung})`;
+}
+function exclusionBucket(record) {
+    if (record.shadowedBy !== null)
+        return 'shadowed';
+    if (record.authoredRules.length === 0)
+        return 'no_rule';
+    if (record.matchedRule === null)
+        return record.ruleGate !== null && !record.ruleGate.pass ? 'rule_if' : 'no_match';
+    return record.cappedRung === 'none' ? 'limited' : 'none';
+}
+function countsOf(plan) {
+    const delivered = { content: 0, preview: 0, name: 0 };
+    const excluded = {};
+    for (const record of plan.docs) {
+        if (delivers(record)) {
+            delivered[record.finalRung] = (delivered[record.finalRung] ?? 0) + 1;
+            continue;
+        }
+        const bucket = exclusionBucket(record);
+        excluded[bucket] = (excluded[bucket] ?? 0) + 1;
+    }
+    return { considered: plan.docs.length, delivered, delivered_total: delivered['content'] + delivered['preview'] + delivered['name'], excluded };
+}
+// Rendering — agent-ready markdown.
+function renderResolve(result) {
+    const lines = [nodeLine(result), `subject: ${describeSubject(result.subject)}`];
+    const sections = result.plans ?? [{ event: result.event, docs: result.docs, counts: result.counts, assembled: result.assembled }];
+    for (const section of sections)
+        lines.push('', `## ${section.event}`, '', renderSection(section));
+    return lines.join('\n');
+}
+/** Which node the result describes, live or simulated. */
+export function nodeLine(head) {
+    if (head.cwd === undefined)
+        return `node: ${head.node ?? ''}`;
+    const base = head.node === undefined ? 'a node that does not exist' : `${head.node}, dialled`;
+    return `node: simulated (${base}; cwd ${head.cwd})${head.node_missing === true ? ' — the named node does not exist' : ''}`;
+}
+export function describeSubject(subject) {
+    return Object.entries(subject).map(([k, v]) => `${k}=${Array.isArray(v) ? v.join(',') || '(none)' : String(v)}`).join(' ');
+}
+function renderSection(section) {
+    if (section.assembled !== undefined) {
+        return section.assembled === '' ? 'Nothing is delivered for this event.' : ['```', section.assembled, '```'].join('\n');
+    }
+    if (section.counts !== undefined)
+        return renderCounts(section.counts);
+    const docs = section.docs ?? [];
+    if (docs.length === 0)
+        return 'No document delivers for this event.';
+    const showExcluded = docs.some((d) => d.excluded !== undefined);
+    const cols = ['document', 'owner', 'kind', 'authored', 'limit', 'final', 'matched', 'if', ...(showExcluded ? ['excluded'] : [])];
+    const rows = docs.map((d) => [
+        d.name, d.owner, d.kind, d.authored_rung, d.limit ?? '—', d.final_rung, d.matched_rule ?? '—', d.gate ?? '—',
+        ...(showExcluded ? [d.excluded ?? ''] : []),
+    ]);
+    return [`${docs.length} document${docs.length === 1 ? '' : 's'}:`, '', table(cols, rows)].join('\n');
+}
+function renderCounts(counts) {
+    const delivered = counts['delivered'];
+    const excluded = counts['excluded'];
+    const excludedText = Object.keys(excluded).length === 0 ? 'none' : Object.entries(excluded).map(([k, v]) => `${k}=${v}`).join(' ');
+    return [
+        `- considered: ${String(counts['considered'])}`,
+        `- delivered: ${String(counts['delivered_total'])} (content=${delivered['content']} preview=${delivered['preview']} name=${delivered['name']})`,
+        `- excluded: ${excludedText}`,
+    ].join('\n');
+}
+export function cell(v) {
+    return String(v).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+export function table(cols, rows) {
+    return [`| ${cols.join(' | ')} |`, `| ${cols.map(() => '---').join(' | ')} |`, ...rows.map((r) => `| ${r.map(cell).join(' | ')} |`)].join('\n');
+}

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

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

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

@@ -0,0 +1,95 @@
+import { envNodeId } from '../../../shared/env.js';
+import { writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { openNodeWindow } from '../../../core/runtime/placement-tmux.js';
+import { ApiError } from '../../../api/index.js';
+import { cliClient } from '../../api-client.js';
+import { shellQuote } from '../../../shared/shell-quote.js';
+export const sysSyspromptLeaf = defineLeaf({
+    name: 'sysprompt',
+    description: 'print a node\'s assembled system prompt',
+    whenToUse: 'you want to inspect a node\'s assembled system prompt headlessly, without paying conversation/context cost — this command prints the text from the node\'s latest launch recipe as markdown.',
+    help: {
+        name: 'sys context sysprompt',
+        summary: 'print a node\'s assembled system prompt',
+        params: [
+            { kind: 'positional', name: 'node', required: false, constraint: 'Node id. Defaults to the calling node (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'window', type: 'bool', required: false, constraint: 'Open the assembled prompt in a NEW tmux window in the session currently showing that node instead of printing to stdout.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node whose prompt was read.' },
+            { name: 'captured_at', type: 'string', required: true, constraint: 'Time of the read in ISO-8601 UTC.' },
+            { name: 'chars', type: 'number', required: true, constraint: 'Character count of the stored prompt.' },
+            { name: 'prompt', type: 'string', required: true, constraint: 'The system prompt text the latest launch recipe passes to pi.' },
+            { name: 'session', type: 'string', required: false, constraint: 'tmux session showing the node (only when --window is used).' },
+            { name: 'window', type: 'string', required: false, constraint: 'tmux window opened for the prompt (only when --window is used).' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads the system prompt from the node\'s latest launch recipe, or opens it in a tmux window.'],
+        // Giant prompt dump / machine payload for an agent to inspect deliberately,
+        // not to glance at inline — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
+    },
+    run: async (input) => {
+        const nodeId = input['node']?.trim() || envNodeId();
+        if (nodeId === undefined || nodeId === '') {
+            throw new InputError({ error: 'empty_node', message: 'a node id is required', field: 'node', next: 'Pass a node id or run from inside a node.' });
+        }
+        try {
+            await cliClient().getNode(nodeId);
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404) {
+                throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, field: 'node', next: 'List nodes with `crtr node inspect list`.' });
+            }
+            throw err;
+        }
+        const session = await cliClient().getSession(nodeId);
+        const prompt = session.system_prompt;
+        if (prompt === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `node ${nodeId} has no launch recipe yet`,
+                field: 'node',
+                next: 'Revive the node once, then rerun `crtr sys context sysprompt <node>`.',
+            });
+        }
+        const capturedAt = session.captured_at;
+        if (input['window'] === true) {
+            const focus = await cliClient().focusOf(nodeId);
+            if (focus === null || focus.session === null || focus.session === '') {
+                throw new InputError({
+                    error: 'not_focused',
+                    message: `node ${nodeId} is not currently shown in tmux`,
+                    field: 'node',
+                    next: `Focus the node first with \`crtr surface node focus ${nodeId}\`, then rerun \`crtr sys context sysprompt --window ${nodeId}\`.`,
+                });
+            }
+            const tmpPath = join(tmpdir(), `crtr-sysprompt-${nodeId}.md`);
+            writeFileSync(tmpPath, prompt, 'utf8');
+            const q = shellQuote(tmpPath);
+            // Syntax-highlight the prompt (markdown + its structural XML tags both stay visible).
+            // bat pages by default; markdown RENDERERS (termrender, glow) are wrong here — they
+            // silently swallow block-level XML tags, dropping most of the assembled prompt.
+            // Fall back to `less -R` when bat is not installed.
+            const command = `if command -v bat >/dev/null 2>&1; then bat --language=markdown --color=always --paging=always --style=plain ${q}; else less -R ${q}; fi`;
+            const opened = openNodeWindow({ session: focus.session, name: `sysprompt:${nodeId}`, cwd: process.cwd(), env: {}, command });
+            if (opened === null) {
+                throw new InputError({
+                    error: 'window_open_failed',
+                    message: `tmux could not open a window for node ${nodeId}`,
+                    field: 'node',
+                    next: 'Check the tmux server is reachable, then retry.',
+                });
+            }
+            return { node_id: nodeId, session: focus.session, window: opened.window };
+        }
+        return { node_id: nodeId, captured_at: capturedAt, chars: prompt.length, prompt };
+    },
+    render: (r) => ('window' in r)
+        ? `Opened system prompt for node ${r['node_id']} in tmux session ${r['session']} — window ${r['window']}.`
+        : `- node_id: ${r['node_id']}\n- captured_at: ${r['captured_at']}\n- chars: ${r['chars']}\n\n${r['prompt']}`,
+});

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

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

package/dist/commands/sys/context.js

@@ -0,0 +1,21 @@
+// `crtr sys context` — inspect delivery: what a
+// node actually receives, for which event, at which rung, and why.
+// The leaves are landed elsewhere; this file only assembles them.
+import { defineBranch } from '../../core/command.js';
+import { resolveLeaf } from './context/resolve.js';
+import { docLeaf } from './context/doc.js';
+import { sysSyspromptLeaf } from './context/sysprompt.js';
+import { promptReviewLeaf } from './context/prompt-review.js';
+import { adminLeaf } from './context/admin.js';
+import { exposeLeaf } from './context/expose.js';
+export const contextBranch = defineBranch({
+    name: 'context',
+    description: 'inspect what documents a node\u2019s delivery rules hand it',
+    whenToUse: 'you are asking what a node loads, why a document does or does not reach it, or what a prompt assembles to',
+    help: {
+        name: 'sys context',
+        summary: 'inspect the documents delivery hands a node, and assembled prompts',
+        model: 'A document reaches a node when one of its rules fires for an event (boot, file-read, command, pre-command, slash-command), the rule `if` holds for the node, and the document wins its bare name against owners earlier in the node\u2019s view; the profile\u2019s delivery limit for the owner caps the level at boot only. resolve answers that forward — node plus event to the delivered set; expose delivers the file-read documents for files a local command displays. doc answers it in reverse — one document across every event. Both read the daemon\u2019s dry run and record nothing. sysprompt and prompt-review read assembled prompts (a live node\u2019s captured one, and one rendered for a chosen kind and mode). admin is the interactive surface over all of it: dial a node, see what every activity delivers, and edit the rules that decide it.',
+    },
+    children: [resolveLeaf, exposeLeaf, docLeaf, sysSyspromptLeaf, promptReviewLeaf, adminLeaf],
+});

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

@@ -0,0 +1,4 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const daemonBranch: BranchDef;
+/** The daemon-only `sys` subtree used before scoped user state is available. */
+export declare function registerDaemonControlSys(): BranchDef;