@north-light/crouter 0.3.236 → 0.3.238

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

@@ -0,0 +1,428 @@
+// `crtr sys context resolve` — the forward question: given a configuration
+// snapshot and one surface event, what does the memory substrate deliver, at
+// which rung, and why. Reads the same plan the live renderers deliver from
+// (`planDelivery`, src/core/substrate/plan.ts), so a reported delivery can
+// never differ from an actual one.
+//
+// The snapshot builders and record formatters here are shared with
+// `sys context doc`, the reverse half of the same read surface.
+import { existsSync } from 'node:fs';
+import { resolve as resolvePath } 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, envProfileId } from '../../../shared/env.js';
+import { realpathOrSelf } from '../../../core/fs-utils.js';
+import { ambientMemoryTarget, resolveMemoryDocForTarget, } from '../../../core/memory-resolver.js';
+import { planDelivery, } from '../../../core/substrate/plan.js';
+import { emptyContextExposureState, exposureTarget } from '../../../core/substrate/injected-store.js';
+import { renderPreferencesForSubject, renderKnowledgeForSubject } from '../../../core/substrate/render.js';
+import { memoryReadDocBlocks, renderOnCommandDocsForSubject, renderOnReadDocsForSubject, renderPreCommandDocsForSubject, renderWorkspaceOpenDocsForSubject, } from '../../../core/substrate/on-read.js';
+import { clearSessionCache } from '../../../core/substrate/session-cache.js';
+import { rungAtLeast, SURFACE_EVENTS, } from '../../../core/substrate/schema.js';
+import { scopeForCwd, profileNameFor } from '../../../core/substrate/subject-fields.js';
+import { resetScopeCache } from '../../../core/scope.js';
+export const resolveLeaf = defineLeaf({
+    name: 'resolve',
+    description: 'resolve what a configuration snapshot loads for one surface event',
+    whenToUse: 'you are asking what a node (or a hypothetical configuration) actually receives — at boot, on opening a workspace, on reading a file, on a memory read, or around a command',
+    help: {
+        name: 'sys context resolve',
+        summary: 'resolve the documents a configuration snapshot loads for one surface event',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Resolve for this live node — derives kind, mode, lifecycle, has-manager, profile, and cwd from it. A node id that does not exist degrades to a synthetic subject and says so.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Node kind of the synthetic subject. Defaults to the --node value, else `general`.' },
+            { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Node mode of the synthetic subject. Defaults to `base`.' },
+            { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Node lifecycle of the synthetic subject. Defaults to `terminal` for base, `resident` for orchestrator.' },
+            { kind: 'flag', name: 'has-manager', type: 'enum', choices: ['true', 'false'], required: false, constraint: 'Treat the subject as having a manager (a subscriber above it). Defaults to the --node value, else true.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id whose memory store and project-memory caps apply. Defaults to the selected profile.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Directory the project stores resolve from. Defaults to the current directory.' },
+            { kind: 'flag', name: 'event', type: 'enum', choices: [...SURFACE_EVENTS], required: false, constraint: 'The surface event to resolve. Defaults to `boot`. Ignored when --all-events is set.' },
+            { kind: 'flag', name: 'all-events', type: 'bool', required: false, constraint: 'Resolve every surface event instead of one, and report each plan separately.' },
+            { kind: 'flag', name: 'file', type: 'path', required: false, constraint: 'Payload for `--event read`: the file that was read. Without it, no read entry matches.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Payload for `--event memory-read`: the exact canonical name the read resolved to.' },
+            { 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-rung counts; `docs` reports one row per document; `assembled` returns the real rendered text by calling the event\u2019s renderer. Defaults to `docs`. `--all` applies only at `docs` granularity; with `assembled` it is reported as ignored.' },
+            { kind: 'flag', name: 'all', type: 'bool', required: false, constraint: 'At `docs` granularity, include every considered document, not just the ones that deliver — shadowed, gated-out, and capped-to-none documents with the reason each was excluded. Ignored at `summary` and `assembled` granularity.' },
+        ],
+        output: [
+            { name: 'event', type: 'string', required: false, constraint: 'The resolved event. Absent with --all-events, where every entry in `plans` carries its own.' },
+            { name: 'subject', type: 'object', required: true, constraint: 'The configuration snapshot used: kind, mode, lifecycle, hasManager, profile, scope.' },
+            { name: 'target', type: 'object', required: true, constraint: 'Store resolution inputs: cwd, profileId, nodeId.' },
+            { name: 'docs', type: 'array', required: false, constraint: 'One entry per document, at `docs`/`all` granularity: name, kind, scope, store_path, authored_rung, project_memory_cap, capped_rung, final_rung, winner, shadowed_by, doc_gate, entry_gate, matched_entry, 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: 'all_ignored', type: 'boolean', required: false, constraint: 'Present only when --all is supplied with --granularity assembled; true means assembled text is unchanged because --all applies only to docs granularity.' },
+            { name: 'assembled', type: 'string', required: false, constraint: 'At `assembled` granularity: the exact text the node would receive for this event.' },
+            { name: 'plans', type: 'array', required: false, constraint: 'With --all-events: one plan result per surface event, each shaped as above.' },
+            { name: 'node_missing', type: 'boolean', required: false, constraint: 'Present when --node named a node that does not exist and a synthetic subject was used instead.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const snapshot = await buildSnapshot(input);
+        const granularity = input['granularity'] ?? 'docs';
+        const includeAll = input['all'] === true;
+        const events = input['allEvents'] === true
+            ? [...SURFACE_EVENTS]
+            : [input['event'] ?? 'boot'];
+        const flags = {
+            file: optionalString(input['file']),
+            readName: optionalString(input['name']),
+            command: optionalString(input['command']),
+        };
+        const sections = events.map((event) => planSection(snapshot, event, payloadFor(event, flags, snapshot.target), granularity, includeAll));
+        const head = {
+            subject: subjectSummary(snapshot.subject),
+            target: snapshot.target,
+            ...(snapshot.nodeMissing ? { node_missing: true } : {}),
+            ...(granularity === 'assembled' && includeAll ? { all_ignored: true } : {}),
+        };
+        return events.length === 1 ? { ...head, ...sections[0] } : { ...head, plans: sections };
+    },
+    render: (result) => renderResolve(result),
+});
+/** Build the subject and store target from `--node` and the axis flags. A flag
+ *  always wins over the value derived from the node, so a live node is a
+ *  starting point an engineer can dial away from. */
+export async function buildSnapshot(input) {
+    const nodeId = optionalString(input['node']);
+    const node = await fetchNodeOrNull(nodeId);
+    const derived = node === null ? null : await fetchSubjectOrNull(node.node_id);
+    const mode = input['mode'] ?? derived?.mode ?? 'base';
+    const lifecycle = input['lifecycle']
+        ?? derived?.lifecycle
+        ?? (mode === 'orchestrator' ? 'resident' : 'terminal');
+    const cwd = resolveCwd(optionalString(input['cwd']) ?? derived?.cwd ?? process.cwd());
+    const profileId = optionalString(input['profile']) ?? node?.profile_id ?? ambientMemoryTarget().profileId;
+    const hasManagerFlag = optionalString(input['hasManager']);
+    return {
+        subject: {
+            kind: optionalString(input['kind']) ?? derived?.kind ?? 'general',
+            mode,
+            lifecycle,
+            hasManager: hasManagerFlag === null ? derived?.hasManager ?? true : hasManagerFlag === 'true',
+            cwd,
+            scope: scopeForCwd(cwd),
+            orchestration: { depth: derived?.orchestration.depth ?? 0 },
+            profile: profileNameFor(profileId),
+        },
+        target: { cwd, profileId, nodeId: node?.node_id ?? null },
+        nodeMissing: nodeId !== null && node === null,
+    };
+}
+/** The event's match payload from the flags that carry it. An event invoked
+ *  without its payload matches nothing — the planner's own contract. */
+export function payloadFor(event, flags, target) {
+    if (event === 'read')
+        return flags.file === null ? {} : { absoluteFile: resolvePath(flags.file) };
+    if (event === 'memory-read') {
+        if (flags.readName === null)
+            return {};
+        return {
+            resolvedCanonicalName: flags.readName,
+            resolvedDocPath: resolvedDocRealpath(flags.readName, target),
+        };
+    }
+    if (event === 'command' || event === 'pre-command') {
+        return flags.command === null ? {} : { command: flags.command };
+    }
+    return {};
+}
+export function subjectSummary(subject) {
+    return {
+        kind: subject.kind,
+        mode: subject.mode,
+        lifecycle: subject.lifecycle,
+        hasManager: subject.hasManager,
+        scope: subject.scope,
+        profile: subject.profile,
+        depth: subject.orchestration.depth,
+    };
+}
+function resolveCwd(raw) {
+    const abs = resolvePath(raw);
+    if (!existsSync(abs)) {
+        throw new InputError({
+            error: 'invalid_field',
+            message: `cwd does not exist: ${abs}`,
+            field: 'cwd',
+            next: 'Pass --cwd a directory that exists, or omit it to use the current directory.',
+        });
+    }
+    return realpathOrSelf(abs);
+}
+export function optionalString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : null;
+}
+/** A 404 means the id names no node: `--node` degrades to a synthetic subject
+ *  rather than failing, the recovery `sys context prompt-review` also makes. */
+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;
+    }
+}
+/** The authoritative subject the daemon gates against, so an inspection never
+ *  re-derives axes the runtime already resolves. */
+async function fetchSubjectOrNull(nodeId) {
+    try {
+        return await cliClient().nodeSubject(nodeId);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return null;
+        throw err;
+    }
+}
+function planSection(snapshot, event, payload, granularity, includeAll) {
+    if (granularity === 'assembled') {
+        return { event, assembled: assembleEvent(snapshot, event, payload) };
+    }
+    const plan = planDelivery(snapshot.subject, snapshot.target, event, payload);
+    if (granularity === 'summary')
+        return { event, counts: countsOf(plan) };
+    const docs = plan.docs.filter((r) => includeAll || delivers(r)).map((r) => docRow(r, includeAll));
+    return { event, docs };
+}
+/** A document delivers when it won its canonical name AND resolved to a rung
+ *  above the no-delivery floor — boot keeps rung-`none` winners in the plan so
+ *  the catalog can still count them. */
+export function delivers(record) {
+    return record.winner && rungAtLeast(record.finalRung, 'name');
+}
+export function docRow(record, includeAll) {
+    const row = {
+        name: record.name,
+        kind: record.kind,
+        scope: record.scope,
+        store_path: record.storePath,
+        authored_rung: record.authoredRung,
+        project_memory_cap: record.projectMemoryCap,
+        capped_rung: record.cappedRung,
+        final_rung: record.finalRung,
+        winner: record.winner,
+        shadowed_by: record.shadowedBy === null ? null : `${record.shadowedBy.scope}:${record.shadowedBy.path}`,
+        doc_gate: gateText(record.docGate),
+        entry_gate: record.entryGate === null ? null : gateText(record.entryGate),
+        matched_entry: entryText(record.matchedEntry),
+    };
+    if (includeAll && !delivers(record))
+        row.excluded = exclusionReason(record);
+    return row;
+}
+export function gateText(gate) {
+    return gate.pass ? 'pass' : `fail: ${gate.reason}`;
+}
+export function entryText(entry) {
+    if (entry === null)
+        return null;
+    const parts = [`at=${entry.at}`];
+    if (entry.match !== undefined)
+        parts.push(`match=${entry.match.join(',')}`);
+    if (entry.matchFrontmatter !== undefined)
+        parts.push('match-frontmatter');
+    if (entry.gate !== undefined)
+        parts.push('gate');
+    return parts.join(' ');
+}
+/** Why a considered document delivers nothing, in the order the planner applies
+ *  its checks — the first failing one is the answer an engineer acts on. */
+export function exclusionReason(record) {
+    if (!record.docGate.pass)
+        return `document gate: ${record.docGate.reason}`;
+    if (record.shadowedBy !== null)
+        return `shadowed by ${record.shadowedBy.scope}:${record.shadowedBy.path}`;
+    if (record.authoredEntries.length === 0)
+        return 'no surface entry for this event';
+    if (record.matchedEntry === null) {
+        return record.entryGate !== null && !record.entryGate.pass
+            ? `entry gate: ${record.entryGate.reason}`
+            : 'no authored entry matched this event\u2019s payload';
+    }
+    if (record.cappedRung === 'none') {
+        return `capped to none by the profile\u2019s project-memory setting (authored ${record.authoredRung})`;
+    }
+    return `resolved to rung none (authored ${record.authoredRung})`;
+}
+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,
+    };
+}
+function exclusionBucket(record) {
+    if (!record.docGate.pass)
+        return 'document_gate';
+    if (record.shadowedBy !== null)
+        return 'shadowed';
+    if (record.authoredEntries.length === 0)
+        return 'no_entry';
+    if (record.matchedEntry === null) {
+        return record.entryGate !== null && !record.entryGate.pass ? 'entry_gate' : 'no_match';
+    }
+    return record.cappedRung === 'none' ? 'capped' : 'rung_none';
+}
+// Assembled granularity — the real renderers, so the highest-fidelity view is
+// byte-identical to what the node receives.
+/** Every renderer resolves its corpus from the AMBIENT process (cwd plus the
+ *  two env seams), not from a target argument, so a snapshot dialed away from
+ *  this process is only honored by standing in its place for the call. The
+ *  session parse cache is cleared on both sides so neither the emulated corpus
+ *  nor the real one is served from the other's scan. */
+function assembleEvent(snapshot, event, payload) {
+    const restore = {
+        cwd: process.cwd(),
+        profileId: envProfileId(),
+        nodeId: envNodeId(),
+    };
+    clearSessionCache();
+    resetScopeCache();
+    try {
+        process.chdir(snapshot.target.cwd);
+        setEnv('CRTR_PROFILE_ID', snapshot.target.profileId ?? undefined);
+        setEnv('CRTR_NODE_ID', snapshot.target.nodeId ?? undefined);
+        return renderEvent(snapshot, event, payload);
+    }
+    finally {
+        process.chdir(restore.cwd);
+        setEnv('CRTR_PROFILE_ID', restore.profileId);
+        setEnv('CRTR_NODE_ID', restore.nodeId);
+        clearSessionCache();
+        resetScopeCache();
+    }
+}
+function setEnv(name, value) {
+    if (value === undefined)
+        delete process.env[name];
+    else
+        process.env[name] = value;
+}
+function renderEvent(snapshot, event, payload) {
+    const { subject, target } = snapshot;
+    switch (event) {
+        case 'boot': {
+            const { block } = renderPreferencesForSubject(subject);
+            const knowledge = target.nodeId === null ? '' : renderKnowledgeForSubject(subject, target.nodeId);
+            return knowledge === '' ? block : `${block}\n\n${knowledge}`;
+        }
+        case 'workspace-open':
+            return renderWorkspaceOpenDocsForSubject(subject, target.cwd, target.profileId);
+        case 'read':
+            return payload.absoluteFile === undefined ? '' : renderOnReadDocsForSubject(subject, payload.absoluteFile);
+        case 'memory-read': {
+            const name = payload.resolvedCanonicalName;
+            if (name === undefined)
+                return '';
+            const blocks = memoryReadDocBlocks(subject, payload.resolvedDocPath ?? '', name, exposureTarget(emptyContextExposureState(), 'transcript'));
+            return blocks.length === 0 ? '' : `<auto-loaded-context>\n${blocks.join('\n')}\n</auto-loaded-context>`;
+        }
+        case 'command':
+            return payload.command === undefined ? '' : renderOnCommandDocsForSubject(subject, payload.command);
+        case 'pre-command':
+            return payload.command === undefined ? '' : renderPreCommandDocsForSubject(subject, payload.command);
+    }
+}
+/** The read document never delivers to itself, so the plan needs its physical
+ *  path. A name that resolves to nothing excludes nothing. */
+function resolvedDocRealpath(name, target) {
+    try {
+        return realpathOrSelf(resolveMemoryDocForTarget(name, target).path);
+    }
+    catch {
+        return '';
+    }
+}
+// Rendering — agent-ready markdown.
+function renderResolve(result) {
+    const lines = [];
+    if (result.node_missing === true) {
+        lines.push('The id passed to --node names no node; a synthetic subject was used instead.', '');
+    }
+    lines.push(`subject: ${describeSubject(result.subject)}`);
+    lines.push(`target: cwd=${result.target.cwd} profile=${result.target.profileId ?? '(none)'} node=${result.target.nodeId ?? '(none)'}`);
+    if (result.all_ignored === true) {
+        lines.push('Note: --all applies only at docs granularity and was ignored for assembled output.');
+    }
+    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');
+}
+export function describeSubject(subject) {
+    return ['kind', 'mode', 'lifecycle', 'hasManager', 'scope', 'profile', 'depth']
+        .map((k) => `${k}=${String(subject[k])}`)
+        .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', 'scope', 'kind', 'authored', 'cap', 'final', 'matched', 'gate', ...(showExcluded ? ['excluded'] : [])];
+    const rows = docs.map((d) => [
+        d.name,
+        d.scope,
+        d.kind,
+        d.authored_rung,
+        d.project_memory_cap ?? '—',
+        d.final_rung,
+        d.matched_entry ?? '—',
+        d.doc_gate,
+        ...(showExcluded ? [d.excluded ?? ''] : []),
+    ]);
+    return [
+        `${docs.length} document${docs.length === 1 ? '' : 's'}:`,
+        '',
+        `| ${cols.join(' | ')} |`,
+        `| ${cols.map(() => '---').join(' | ')} |`,
+        ...rows.map((r) => `| ${r.map(cell).join(' | ')} |`),
+    ].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, ' ');
+}

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

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

package/dist/commands/sys/{sysprompt.js → context/sysprompt.js}

@@ -1,20 +1,20 @@
-import { envNodeId } from '../../shared/env.js';
+import { envNodeId } from '../../../shared/env.js';
 import { existsSync, readFileSync, statSync, 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 { jobDir } from '../../core/canvas/paths.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';
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { jobDir } from '../../../core/canvas/paths.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 — the broker writes it to disk while live, and this command reads that artifact back as markdown.',
     help: {
-        name: 'sys sysprompt',
+        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).' },
@@ -54,7 +54,7 @@ export const sysSyspromptLeaf = defineLeaf({
                 error: 'not_found',
                 message: `system prompt not captured yet for ${nodeId}`,
                 field: 'node',
-                next: 'Focus or revive the node once while its broker is live, then rerun `crtr sys sysprompt <node>`.',
+                next: 'Focus or revive the node once while its broker is live, then rerun `crtr sys context sysprompt <node>`.',
             });
         }
         const prompt = readFileSync(path, 'utf8');
@@ -66,7 +66,7 @@ export const sysSyspromptLeaf = defineLeaf({
                     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 sysprompt --window ${nodeId}\`.`,
+                    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`);

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,20 @@
+// `crtr sys context` — inspect and shape the memory context surface: what a
+// node's configuration actually loads, 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';
+export const contextBranch = defineBranch({
+    name: 'context',
+    description: 'inspect and shape what a node\u2019s memory context surface delivers',
+    whenToUse: 'you are asking what a node loads, why a document does or does not reach it, or you want to change the surfaces and caps that decide it',
+    help: {
+        name: 'sys context',
+        summary: 'inspect and shape the memory context a node\u2019s configuration delivers',
+        model: 'A document reaches a node when one of its authored surface entries fires for an event (boot, workspace-open, read, memory-read, command, pre-command), its gates pass, and it wins its canonical name against nearer stores; the profile relationship caps the rung at boot and workspace-open only. resolve answers that forward — snapshot plus event to the delivered set. doc answers it in reverse — one document across every event. sysprompt and prompt-review read assembled prompts (a live node\u2019s captured one, and a hypothetical configuration\u2019s). admin is the interactive surface over all of it.',
+    },
+    children: [resolveLeaf, docLeaf, sysSyspromptLeaf, promptReviewLeaf, adminLeaf],
+});

package/dist/commands/sys.js

@@ -8,8 +8,7 @@ import { sysLogsLeaf } from './sys/logs.js';
 import { sysSettingsLeaf } from './sys/settings.js';
 import { sysSetupLeaf } from './sys/setup.js';
 import { supportBranch } from './sys/support.js';
-import { sysSyspromptLeaf } from './sys/sysprompt.js';
-import { promptReviewLeaf } from './sys/prompt-review.js';
+import { contextBranch } from './sys/context.js';
 import { sysSyncBranch } from './sys/sync.js';
 import { sysMigrateLeaf } from './sys/migrate.js';
 import { sysUpdateLeaf, sysVersionLeaf } from './sys/update.js';
@@ -18,7 +17,7 @@ export function registerSys() {
         name: 'sys',
         rootEntry: {
             concept: 'crtr configuration, diagnostics, and self-management',
-            desc: 'settings, config, setup, doctor, sysprompt, prompt-review, sync, migrate, update, version, feedback, logs, support, daemon',
+            desc: 'settings, config, setup, doctor, context, sync, migrate, update, version, feedback, logs, support, daemon',
             useWhen: 'managing the crtr installation, inspecting diagnostics, or operating the crtrd supervisor process',
         },
         help: {
@@ -26,6 +25,6 @@ export function registerSys() {
             summary: 'crtr system configuration, settings, diagnostics, and self-management',
             model: 'Configuration and settings own durable behavior; diagnostics and support observe it. Setup, migration, sync, and update change installed or generated state, while daemon control owns the supervisor lifecycle.',
         },
-        children: [sysSettingsLeaf, configBranch, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysFeedbackLeaf, sysLogsLeaf, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysMigrateLeaf, sysSyncBranch, daemonBranch],
+        children: [sysSettingsLeaf, configBranch, sysSetupLeaf, sysDoctorLeaf, contextBranch, sysFeedbackLeaf, sysLogsLeaf, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysMigrateLeaf, sysSyncBranch, daemonBranch],
     });
 }

package/dist/core/__tests__/child-death-wake.test.js

@@ -38,7 +38,9 @@ import { closeNode } from '../runtime/close.js';
 import { superviseTick } from '../../daemon/crtrd.js';
 import { bindTestFleet } from './helpers/fleet.js';
 import { resetFleetForTests } from '../runtime/fleet.js';
+import { headlessBrokerHost } from '../runtime/host.js';
 let home;
+let tf;
 function node(id, over = {}) {
     return {
         node_id: id,
@@ -96,9 +98,9 @@ const wakeFromChild = (parent, child) => readInboxSince(parent).find((e) => e.fr
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-child-death-wake-'));
     process.env['CRTR_HOME'] = home;
-    // superviseTick requires a bound fleet (D-2). Empty is the point: none of
-    // these fabricated rows has a live broker, so the tick must leave them alone.
-    bindTestFleet();
+    // superviseTick requires a bound fleet (D-2). It starts empty: none of these
+    // fabricated rows has a live broker.
+    tf = bindTestFleet();
 });
 beforeEach(() => {
     closeDb();
@@ -111,27 +113,41 @@ after(() => {
     resetFleetForTests();
 });
 // BROKER CUT — exit-event authority REPLACES daemon pane-gone reaping. A booted
-// child whose engine pid is dead (and whose viewer pane is gone) is REVIVABLE,
+// child whose engine pid is dead (and whose viewer pane is gone) is RECOVERED,
 // not reaped, and the daemon's tick fans NO wake to the dormant parent. This
 // single case subsumes the four deleted scenarios (crash / quiet-finalize /
-// awaiting a live grandchild / pending self-wake): with pane state ignored,
-// surfaceChildDeath gone, and the tick running no liveness pass at all (dead-
-// node recovery rides real exit events), the daemon treats them all identically
-// — no reap, no liveness wake — so the old CRUX (no spurious wake on healthy
-// dormancy) holds by construction.
-test('exit-event authority: a dead-engine booted child is revivable, NOT reaped, and the tick fans NO wake to its dormant parent', async () => {
-    inboxWaitingParent('PARENT');
-    deadEngineChild('CHILD');
-    subscribe('PARENT', 'CHILD', true); // the spawn-time spine edge
-    await superviseTick();
-    // The tick has no liveness pass: a stale recorded pid is metadata, not a
-    // death signal — the row stays revivable (recovery would ride a real exit
-    // event), never reaped to dead/done/idle.
-    assert.equal(getNode('CHILD').status, 'active', 'CHILD stays revivable, NOT reaped');
-    // surfaceChildDeath is deleted: the daemon raises no liveness wake. The
-    // doctrine wake now rides the child's own `push final` (or close.ts), so a
-    // purely-inbox-waiting parent is never spuriously woken on dormancy/crash.
-    assert.equal(readInboxSince('PARENT').length, 0, 'PARENT inbox EMPTY — no daemon liveness wake');
+// awaiting a live grandchild / pending self-wake): with pane state ignored and
+// surfaceChildDeath gone, the daemon treats them all identically — no reap, no
+// liveness wake — so the old CRUX (no spurious wake on healthy dormancy) holds
+// by construction. The node-lifecycle tick relaunches the row through the same
+// policy table its exit event would have used (D-12); that recovery is silent.
+test('exit-event authority: a dead-engine booted child is recovered, NOT reaped, and the tick fans NO wake to its dormant parent', async () => {
+    const originalLaunch = headlessBrokerHost.launch;
+    const launches = [];
+    headlessBrokerHost.launch = (nodeId) => {
+        launches.push(nodeId);
+        const handle = { pid: 424_242, exited: new Promise(() => { }) };
+        tf.fleet.register(nodeId, handle); // the real host contract: registration at the launch seam
+        return handle;
+    };
+    try {
+        inboxWaitingParent('PARENT');
+        deadEngineChild('CHILD', { cwd: home }); // a cwd that exists — reviveNode's preflight refuses a missing one
+        subscribe('PARENT', 'CHILD', true); // the spawn-time spine edge
+        await superviseTick();
+        // A stale recorded pid is metadata, not a verdict: the row is relaunched on
+        // its saved session, never reaped to dead/done/idle.
+        assert.deepEqual(launches, ['CHILD'], 'the tick recovers the dead engine through the policy table');
+        assert.equal(getNode('CHILD').status, 'active', 'CHILD is recovered, NOT reaped');
+        // surfaceChildDeath is deleted: the daemon raises no liveness wake. The
+        // doctrine wake now rides the child's own `push final` (or close.ts), so a
+        // purely-inbox-waiting parent is never spuriously woken on dormancy/crash.
+        assert.equal(readInboxSince('PARENT').length, 0, 'PARENT inbox EMPTY — no daemon liveness wake');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        tf.fleet.forget('CHILD');
+    }
 });
 test('node close of a child wakes its SURVIVING manager (the parent outside the closing set)', async () => {
     inboxWaitingParent('PARENT');