@crouton-kit/crouter 0.3.11 → 0.3.12

package/dist/core/canvas/types.js

@@ -0,0 +1,8 @@
+// The canvas vocabulary — the node + edge model the whole runtime hangs on.
+//
+// One global canvas (`~/.crtr/canvas.db`) holds the topology (nodes + edges);
+// each node's flesh lives on disk under `~/.crtr/nodes/<id>/`. A node's
+// `meta.json` is the source of truth for its own row; the db is a queryable
+// index over those metas, plus the authoritative store for the mutable
+// `subscribes_to` edges (which no single meta owns).
+export {};

package/dist/core/command.d.ts

@@ -23,6 +23,10 @@ export interface LeafDef {
     /** Opt into editor slash-command exposure (see SlashSpec). */
     slash?: SlashSpec;
     run: (input: Record<string, unknown>) => Promise<Record<string, unknown> | void>;
+    /** Optional bespoke renderer: turn the result into instruction-shaped
+     *  XML+markdown the agent acts on. Omit to fall back to the schema-driven
+     *  generic renderer. Ignored when `--json` is set. */
+    render?: (result: Record<string, unknown>) => string;
 }
 export interface BranchDef {
     kind: 'branch';
@@ -46,6 +50,7 @@ export declare function defineLeaf(opts: {
     help: LeafHelp;
     slash?: SlashSpec;
     run: (input: Record<string, unknown>) => Promise<Record<string, unknown> | void>;
+    render?: (result: Record<string, unknown>) => string;
 }): LeafDef;
 export declare function defineBranch(opts: {
     name: string;

package/dist/core/command.js

@@ -5,7 +5,8 @@
 // A plain array walk + a small flag parser is ~120 lines and has no surprising
 // edge cases.
 import { renderRoot, renderBranch, renderLeafArgv } from './help.js';
-import { readStdinRaw, emit, handle } from './io.js';
+import { readStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
+import { renderResult } from './render.js';
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
 import { readFileSync } from 'node:fs';
@@ -19,6 +20,7 @@ export function defineLeaf(opts) {
         help: opts.help,
         slash: opts.slash,
         run: opts.run,
+        render: opts.render,
     };
 }
 export function defineBranch(opts) {
@@ -263,7 +265,10 @@ export async function parseArgv(params, tokens) {
         if (positionalValue !== undefined) {
             throw parseArgvError('bad_invocation', `unexpected extra positional argument: ${token}`, tokens.join(' '), undefined, 'Use --flag for parameters; only one positional allowed.');
         }
-        if (positionalParam === undefined) {
+        // A bare positional is accepted when the leaf declares a positional param,
+        // OR when it declares a stdin param (the positional supplies the stdin
+        // value as an ergonomic alternative to piping). Otherwise it's an error.
+        if (positionalParam === undefined && stdinParam === undefined) {
             throw parseArgvError('bad_invocation', `this leaf takes no positional arguments: ${token}`, token, undefined, 'Use --flag for parameters. Run -h for the schema.');
         }
         positionalValue = token;
@@ -273,13 +278,20 @@ export async function parseArgv(params, tokens) {
     if (positionalValue !== undefined && positionalParam !== undefined) {
         result[flagNameToKey(positionalParam.name)] = positionalValue;
     }
-    // Read stdin if declared
+    // Resolve stdin if declared. A positional token (when there's no dedicated
+    // positional param to claim it) satisfies the stdin param directly, so
+    // `crtr node new "Say hi"` works as well as piping on stdin.
     if (stdinParam !== undefined) {
-        const raw = await readStdinRaw();
-        if (raw.trim() === '' && stdinParam.required) {
-            throw parseArgvError('missing_parameter', `stdin is required for this leaf`, '', stdinParam.name, 'Pipe the required content on stdin.');
+        if (positionalValue !== undefined && positionalParam === undefined) {
+            result[flagNameToKey(stdinParam.name)] = positionalValue;
+        }
+        else {
+            const raw = await readStdinRaw();
+            if (raw.trim() === '' && stdinParam.required) {
+                throw parseArgvError('missing_parameter', `stdin is required for this leaf`, '', stdinParam.name, 'Pipe the required content on stdin, or pass it as a positional argument.');
+            }
+            result[flagNameToKey(stdinParam.name)] = raw;
         }
-        result[flagNameToKey(stdinParam.name)] = raw;
     }
     // Validate required params
     for (const p of params) {
@@ -298,8 +310,15 @@ export async function parseArgv(params, tokens) {
     return result;
 }
 export async function runCli(root, argv) {
-    // argv is process.argv — strip node binary + script path
-    const tokens = argv.slice(2);
+    // argv is process.argv — strip node binary + script path. `--json` is a
+    // global: pull it out anywhere it appears so the rest of argv parses against
+    // the leaf schema unchanged, and switch stdout from rendered prose to raw
+    // JSON. It is intentionally undocumented — the default prose output is the
+    // agent contract; --json exists only for programmatic/tooling consumers.
+    const rawTokens = argv.slice(2);
+    const tokens = rawTokens.filter((t) => t !== '--json');
+    if (tokens.length !== rawTokens.length)
+        setJsonOutput(true);
     // Bare root invocation or -h at root
     if (tokens.length === 0 || (tokens.length === 1 && (tokens[0] === '-h' || tokens[0] === '--help'))) {
         process.stdout.write(renderRoot(root.help) + '\n');
@@ -325,7 +344,13 @@ export async function runCli(root, argv) {
         const input = await parseArgv(params, remaining);
         const result = await node.run(input);
         if (result !== undefined && result !== null) {
-            emit(result);
+            if (isJsonOutput()) {
+                emit(result);
+            }
+            else {
+                const text = node.render !== undefined ? node.render(result) : renderResult(result, node.help);
+                process.stdout.write(text + '\n');
+            }
         }
         // JSONL leaves call emitLine themselves and return void
     }

package/dist/core/feed/feed.d.ts

@@ -0,0 +1,43 @@
+export type PushKind = 'update' | 'urgent' | 'final';
+export interface PushOpts {
+    /** Semantic kind of this push. `final` also finalises the node. */
+    kind: PushKind;
+    /** Report body (markdown). Written verbatim after the YAML frontmatter. */
+    body: string;
+    /**
+     * Node id of the sender — recorded as `from` on each inbox entry.
+     * Defaults to `nodeId` (the publisher) when omitted.
+     */
+    from?: string;
+}
+export interface PushResult {
+    /** Absolute path of the written report file. */
+    reportPath: string;
+    /** Node ids that received an inbox pointer. */
+    deliveredTo: string[];
+}
+/**
+ * Push a report from `nodeId` and fan it out as inbox pointers to all
+ * current subscribers.
+ *
+ * Steps:
+ *   (a) Write nodes/<nodeId>/reports/<ts>-<kind>.md (YAML front + body).
+ *   (b) For each active/passive subscriber, append a pointer to their inbox.
+ *   (c) If kind === 'final', mark the node done.
+ */
+export declare function push(nodeId: string, opts: PushOpts): Promise<PushResult>;
+/** Emit a routine progress update from `nodeId`. */
+export declare function pushUpdate(nodeId: string, body: string, opts?: {
+    from?: string;
+}): Promise<PushResult>;
+/** Emit an urgent alert from `nodeId` (inbox tier: urgent). */
+export declare function pushUrgent(nodeId: string, body: string, opts?: {
+    from?: string;
+}): Promise<PushResult>;
+/**
+ * Emit the final report from `nodeId` (inbox tier: normal, kind: final).
+ * Also transitions the node to status=done / intent=done.
+ */
+export declare function pushFinal(nodeId: string, body: string, opts?: {
+    from?: string;
+}): Promise<PushResult>;

package/dist/core/feed/feed.js

@@ -0,0 +1,116 @@
+// Push engine for the pi-native canvas runtime.
+//
+// `push(nodeId, opts)` writes a report to the node's reports/ directory, then
+// fans out a lightweight inbox pointer to every subscriber. The inbox entry
+// carries the report path (ref), not the body — subscribers dereference on
+// demand.
+//
+// Compact timestamp format: 20260602T184512 (UTC, no separators) chosen for
+// file-system friendliness and lexicographic sort alignment.
+import { writeFileSync, renameSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { reportsDir, subscribersOf, setStatus, updateNode, } from '../canvas/index.js';
+import { appendInbox } from './inbox.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Format a Date as `YYYYMMDDTHHmmss` (UTC, no separators). */
+function compactTs(d = new Date()) {
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    return (String(d.getUTCFullYear()) +
+        pad(d.getUTCMonth() + 1) +
+        pad(d.getUTCDate()) +
+        'T' +
+        pad(d.getUTCHours()) +
+        pad(d.getUTCMinutes()) +
+        pad(d.getUTCSeconds()));
+}
+/**
+ * Write a report file atomically (tmp + rename).
+ * Returns the final absolute path.
+ */
+function writeReport(nodeId, kind, ts, body) {
+    const dir = reportsDir(nodeId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const fileName = `${ts}-${kind}.md`;
+    const finalPath = join(dir, fileName);
+    const tmpPath = `${finalPath}.tmp`;
+    const isoTs = new Date().toISOString();
+    // YAML frontmatter: minimal, machine-readable, no freeform content in it.
+    const frontmatter = `---\nnode: ${nodeId}\nkind: ${kind}\nts: ${isoTs}\n---\n`;
+    writeFileSync(tmpPath, frontmatter + body, 'utf8');
+    renameSync(tmpPath, finalPath);
+    return finalPath;
+}
+/**
+ * Extract the first line of a string and truncate to `maxLen` chars.
+ * Used to populate the inbox entry's `label` field (~80 chars).
+ */
+function firstLine(text, maxLen = 80) {
+    const line = text.split('\n')[0] ?? '';
+    return line.length > maxLen ? line.slice(0, maxLen - 1) + '…' : line;
+}
+/** Map a PushKind to the appropriate inbox delivery tier. */
+function tierFor(kind) {
+    return kind === 'urgent' ? 'urgent' : 'normal';
+}
+// ---------------------------------------------------------------------------
+// Core push
+// ---------------------------------------------------------------------------
+/**
+ * Push a report from `nodeId` and fan it out as inbox pointers to all
+ * current subscribers.
+ *
+ * Steps:
+ *   (a) Write nodes/<nodeId>/reports/<ts>-<kind>.md (YAML front + body).
+ *   (b) For each active/passive subscriber, append a pointer to their inbox.
+ *   (c) If kind === 'final', mark the node done.
+ */
+export async function push(nodeId, opts) {
+    const { kind, body } = opts;
+    const from = opts.from ?? nodeId;
+    const now = new Date();
+    const ts = compactTs(now);
+    // (a) Write the report.
+    const reportPath = writeReport(nodeId, kind, ts, body);
+    // (b) Fan out inbox pointers to every subscriber (active and passive both
+    //     receive the pointer; the daemon decides whether to wake active ones).
+    const subscribers = subscribersOf(nodeId);
+    const deliveredTo = [];
+    const label = firstLine(body);
+    for (const sub of subscribers) {
+        appendInbox(sub.node_id, {
+            from,
+            tier: tierFor(kind),
+            kind,
+            ref: reportPath,
+            label,
+        });
+        deliveredTo.push(sub.node_id);
+    }
+    // (c) Finalise node when kind === 'final'.
+    if (kind === 'final') {
+        setStatus(nodeId, 'done');
+        updateNode(nodeId, { intent: 'done' });
+    }
+    return { reportPath, deliveredTo };
+}
+// ---------------------------------------------------------------------------
+// Convenience wrappers
+// ---------------------------------------------------------------------------
+/** Emit a routine progress update from `nodeId`. */
+export async function pushUpdate(nodeId, body, opts) {
+    return push(nodeId, { kind: 'update', body, ...opts });
+}
+/** Emit an urgent alert from `nodeId` (inbox tier: urgent). */
+export async function pushUrgent(nodeId, body, opts) {
+    return push(nodeId, { kind: 'urgent', body, ...opts });
+}
+/**
+ * Emit the final report from `nodeId` (inbox tier: normal, kind: final).
+ * Also transitions the node to status=done / intent=done.
+ */
+export async function pushFinal(nodeId, body, opts) {
+    return push(nodeId, { kind: 'final', body, ...opts });
+}

package/dist/core/feed/inbox.d.ts

@@ -0,0 +1,50 @@
+export type InboxTier = 'critical' | 'urgent' | 'normal' | 'deferred';
+export type InboxKind = 'update' | 'urgent' | 'final' | 'message' | 'completed';
+/** A single inbox entry — a pointer, not a copy of the content. */
+export interface InboxEntry {
+    /** ISO 8601 timestamp of delivery. */
+    ts: string;
+    /** Node id of the sender, or null for system-generated entries. */
+    from: string | null;
+    /** Priority band for the receiver's attention. */
+    tier: InboxTier;
+    /** Semantic kind of the push event. */
+    kind: InboxKind;
+    /** Absolute path to the report file, when this entry is a push pointer. */
+    ref?: string;
+    /** First ~80 chars of the body's first line — enough to decide if it matters. */
+    label: string;
+    /** Arbitrary structured payload for non-push message entries. */
+    data?: Record<string, unknown>;
+}
+/**
+ * Atomically append one inbox entry to `nodes/<nodeId>/inbox.jsonl`.
+ * Fills `ts` (current ISO time). Returns the completed entry.
+ */
+export declare function appendInbox(nodeId: string, entry: Omit<InboxEntry, 'ts'>): InboxEntry;
+/**
+ * Return all inbox entries strictly after `cursorIso`.
+ * When `cursorIso` is undefined, returns every entry in the file.
+ */
+export declare function readInboxSince(nodeId: string, cursorIso?: string): InboxEntry[];
+/**
+ * Read the persisted cursor ISO for a node's inbox.
+ * Returns undefined if no cursor file exists yet.
+ */
+export declare function readCursor(nodeId: string): string | undefined;
+/**
+ * Persist a new cursor ISO for a node's inbox (atomic tmp+rename).
+ */
+export declare function writeCursor(nodeId: string, iso: string): void;
+/**
+ * Render many unread inbox pointers into one compact digest string.
+ *
+ * Format (per sender group):
+ *   From <sender> — <N> update(s):
+ *     [<kind>] <label>  (ref: <path>)
+ *     …
+ *
+ * A header line announces the total count and instructs the receiver to
+ * dereference only what matters.
+ */
+export declare function coalesce(entries: InboxEntry[]): string;

package/dist/core/feed/inbox.js

@@ -0,0 +1,124 @@
+// Per-node inbox.jsonl primitive for the pi-native canvas runtime.
+//
+// An inbox entry is a lightweight POINTER (~30 tokens), never content.
+// The report body lives in nodes/<id>/reports/; the inbox line carries only
+// enough to find it and decide whether to dereference.
+//
+// Layout:
+//   nodes/<id>/inbox.jsonl          — one JSON line per entry, append-only
+//   nodes/<id>/inbox.jsonl.cursor   — ISO 8601 of last-read entry (sidecar)
+import { appendFileSync, existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { inboxPath } from '../canvas/index.js';
+// ---------------------------------------------------------------------------
+// Cursor sidecar path
+// ---------------------------------------------------------------------------
+function cursorPath(nodeId) {
+    return `${inboxPath(nodeId)}.cursor`;
+}
+// ---------------------------------------------------------------------------
+// Append
+// ---------------------------------------------------------------------------
+/**
+ * Atomically append one inbox entry to `nodes/<nodeId>/inbox.jsonl`.
+ * Fills `ts` (current ISO time). Returns the completed entry.
+ */
+export function appendInbox(nodeId, entry) {
+    const full = { ts: new Date().toISOString(), ...entry };
+    const line = JSON.stringify(full) + '\n';
+    // Ensure the parent directory exists (inbox.jsonl lives directly under the
+    // node dir, which ensureNodeDirs creates — but guard anyway for callers that
+    // haven't yet scaffolded the node).
+    const dir = dirname(inboxPath(nodeId));
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // appendFileSync is atomic within a single process (a single write(2) call for
+    // a short line is atomic on POSIX). For multi-process safety we rely on the
+    // OS-level append guarantee (O_APPEND) which Node honours via 'a' flag.
+    appendFileSync(inboxPath(nodeId), line, { encoding: 'utf8', flag: 'a' });
+    return full;
+}
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+/**
+ * Return all inbox entries strictly after `cursorIso`.
+ * When `cursorIso` is undefined, returns every entry in the file.
+ */
+export function readInboxSince(nodeId, cursorIso) {
+    const p = inboxPath(nodeId);
+    if (!existsSync(p))
+        return [];
+    const raw = readFileSync(p, 'utf8');
+    const entries = raw
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => JSON.parse(l));
+    if (cursorIso === undefined)
+        return entries;
+    // Entries are appended in chronological order; filter to those strictly
+    // after the cursor. We compare ISO strings lexicographically (valid for UTC).
+    return entries.filter((e) => e.ts > cursorIso);
+}
+// ---------------------------------------------------------------------------
+// Cursor persistence
+// ---------------------------------------------------------------------------
+/**
+ * Read the persisted cursor ISO for a node's inbox.
+ * Returns undefined if no cursor file exists yet.
+ */
+export function readCursor(nodeId) {
+    const p = cursorPath(nodeId);
+    if (!existsSync(p))
+        return undefined;
+    const val = readFileSync(p, 'utf8').trim();
+    return val !== '' ? val : undefined;
+}
+/**
+ * Persist a new cursor ISO for a node's inbox (atomic tmp+rename).
+ */
+export function writeCursor(nodeId, iso) {
+    const p = cursorPath(nodeId);
+    const tmp = `${p}.tmp`;
+    const dir = dirname(p);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(tmp, iso, 'utf8');
+    renameSync(tmp, p);
+}
+// ---------------------------------------------------------------------------
+// Coalesce
+// ---------------------------------------------------------------------------
+/**
+ * Render many unread inbox pointers into one compact digest string.
+ *
+ * Format (per sender group):
+ *   From <sender> — <N> update(s):
+ *     [<kind>] <label>  (ref: <path>)
+ *     …
+ *
+ * A header line announces the total count and instructs the receiver to
+ * dereference only what matters.
+ */
+export function coalesce(entries) {
+    if (entries.length === 0)
+        return '(inbox empty)';
+    const header = `${entries.length} update${entries.length === 1 ? '' : 's'} since last read — dereference what matters.\n`;
+    // Group by `from` (null → 'system').
+    const groups = new Map();
+    for (const e of entries) {
+        const key = e.from ?? 'system';
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(e);
+    }
+    const sections = [];
+    for (const [sender, items] of groups) {
+        const lines = items.map((e) => {
+            const refPart = e.ref !== undefined ? `  (ref: ${e.ref})` : '';
+            return `  [${e.kind}] ${e.label}${refPart}`;
+        });
+        sections.push(`From ${sender} — ${items.length} update${items.length === 1 ? '' : 's'}:\n${lines.join('\n')}`);
+    }
+    return header + sections.join('\n\n');
+}

package/dist/core/help.js

@@ -45,7 +45,8 @@ function pad(s, width) {
 // ---------------------------------------------------------------------------
 // renderRoot
 // ---------------------------------------------------------------------------
-const IO_CONTRACT = 'I/O contract: flags and positional args on input, JSON on stdout (JSONL for streams).\n' +
+const IO_CONTRACT = 'I/O contract: flags and positional args on input; stdout is agent-ready markdown/XML you\n' +
+    'act on directly — read it as a continuation of your prompt, don\'t parse it as data.\n' +
     'Exit 0 on success, non-zero on failure. Schemas appear at leaf -h.';
 // Behavioral instruction (not a schema) — engrained in the appended system
 // prompt so the model treats unfamiliar capabilities as a cue to discover the
@@ -180,8 +181,9 @@ export function renderLeafArgv(h) {
         lines.push(h.inputNote !== undefined ? h.inputNote : 'No input parameters.');
     }
     lines.push('');
-    const outputLabel = h.outputKind === 'jsonl' ? 'Output (stdout, JSONL)' : 'Output (stdout, JSON)';
-    lines.push(outputLabel);
+    // The result is rendered as instruction-shaped XML+markdown; these fields are
+    // the information it carries, in order, not a literal JSON shape.
+    lines.push('Output (fields carried in the rendered result)');
     const outNameW = maxLen(h.output.map((f) => f.name));
     for (const f of h.output) {
         lines.push(`  ${pad(f.name, outNameW)}  ${f.type}. ${f.constraint}`);

package/dist/core/io.d.ts

@@ -1,5 +1,9 @@
 import { CrtrError } from './errors.js';
 import { type ExitCodeValue } from '../types.js';
+/** Set by the dispatcher when `--json` is present anywhere in argv. */
+export declare function setJsonOutput(v: boolean): void;
+/** True when the caller asked for raw JSON instead of rendered prose. */
+export declare function isJsonOutput(): boolean;
 /** Structured error payload. `error` is a stable code the agent branches on;
  *  `next` is the recovery road sign. */
 export interface ErrorPayload {
@@ -17,10 +21,20 @@ export declare class InputError extends CrtrError {
 /** Read raw stdin to EOF. Returns empty string when stdin is a TTY (no pipe).
  *  Called by the argv parser for leaves declaring a `stdin` parameter. */
 export declare function readStdinRaw(): Promise<string>;
-/** Single-shot response: one JSON object. The whole response is one value. */
+/** Raw-JSON mirror of a single-shot response (the `--json` escape hatch). The
+ *  default path renders the result as prose instead — see render.ts. */
 export declare function emit(obj: Record<string, unknown>): void;
 /** One JSONL record. Call per event in a stream; partial reads stay parseable. */
 export declare function emitLine(obj: Record<string, unknown>): void;
+/**
+ * Write to stdout and resolve true ONLY once the bytes are confirmed flushed to
+ * a connected reader. Resolves false if the consumer is gone (EPIPE) or the
+ * write fails. This is the reliable "the caller actually received it" signal:
+ * use it to gate side effects that must only happen on genuine delivery (e.g.
+ * acking a collected result). A killed process never resolves at all — also
+ * safe, since the gated side effect then never runs.
+ */
+export declare function writeStdout(s: string): Promise<boolean>;
 export declare function diag(message: string): void;
 /** Terminal error handler. Command-level failures (bad input, not-found,
  *  ambiguous) surface as the JSON response on stdout so the caller parses one

package/dist/core/io.js

@@ -1,9 +1,23 @@
-// The agent-facing I/O contract. Flags and positional args on input; one JSON
-// object on stdout (JSONL for streams); structured errors; stderr is
-// diagnostics only and never carries the result. The stdout value is the next
-// caller's stdin. See cli-design SKILL.md / reference.md.
+// The agent-facing I/O contract. Flags and positional args on input; stdout is
+// agent-ready markdown/XML the caller acts on directly (the result rendered FOR
+// the model, not data it parses); structured errors; stderr is diagnostics only
+// and never carries the result. The raw JSON object is available behind the
+// `--json` global for tooling. See cli-design SKILL.md / reference.md.
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
+import { renderError } from './render.js';
+// ---------------------------------------------------------------------------
+// output mode — prose (default) vs raw JSON (--json global, for tooling)
+// ---------------------------------------------------------------------------
+let jsonOutput = false;
+/** Set by the dispatcher when `--json` is present anywhere in argv. */
+export function setJsonOutput(v) {
+    jsonOutput = v;
+}
+/** True when the caller asked for raw JSON instead of rendered prose. */
+export function isJsonOutput() {
+    return jsonOutput;
+}
 /** A command-level failure: surfaces as the JSON response on stdout. */
 export class InputError extends CrtrError {
     payload;
@@ -29,7 +43,8 @@ export async function readStdinRaw() {
 // ---------------------------------------------------------------------------
 // stdout — the result, nothing else
 // ---------------------------------------------------------------------------
-/** Single-shot response: one JSON object. The whole response is one value. */
+/** Raw-JSON mirror of a single-shot response (the `--json` escape hatch). The
+ *  default path renders the result as prose instead — see render.ts. */
 export function emit(obj) {
     process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
 }
@@ -37,6 +52,37 @@ export function emit(obj) {
 export function emitLine(obj) {
     process.stdout.write(JSON.stringify(obj) + '\n');
 }
+/**
+ * Write to stdout and resolve true ONLY once the bytes are confirmed flushed to
+ * a connected reader. Resolves false if the consumer is gone (EPIPE) or the
+ * write fails. This is the reliable "the caller actually received it" signal:
+ * use it to gate side effects that must only happen on genuine delivery (e.g.
+ * acking a collected result). A killed process never resolves at all — also
+ * safe, since the gated side effect then never runs.
+ */
+export function writeStdout(s) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const onErr = (e) => {
+            if (e.code === 'EPIPE')
+                finish(false);
+        };
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            process.stdout.off('error', onErr);
+            resolve(ok);
+        };
+        process.stdout.on('error', onErr);
+        try {
+            process.stdout.write(s, (err) => finish(err === null || err === undefined));
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
 // ---------------------------------------------------------------------------
 // stderr — diagnostics the agent MAY capture, never the result
 // ---------------------------------------------------------------------------
@@ -67,7 +113,11 @@ function payloadOf(e) {
  *  raw traces never reach the agent. Exits non-zero either way. */
 export function handle(e) {
     if (e instanceof CrtrError) {
-        process.stdout.write(JSON.stringify(payloadOf(e), null, 2) + '\n');
+        const payload = payloadOf(e);
+        const out = jsonOutput
+            ? JSON.stringify(payload, null, 2)
+            : renderError(payload);
+        process.stdout.write(out + '\n');
         process.exit(e.exitCode);
     }
     const err = e;

package/dist/core/personas/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Persona composer public surface.
+ *
+ * Re-exports:
+ *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - resolve                    (high-level composer)
+ *   - ResolvedPersona            (return type of resolve)
+ */
+export { loadPersona, loadKernel, availableKinds } from './loader.js';
+export type { LoadedPersona } from './loader.js';
+export { resolve } from './resolve.js';
+export type { ResolvedPersona } from './resolve.js';

package/dist/core/personas/index.js

@@ -0,0 +1,10 @@
+/**
+ * Persona composer public surface.
+ *
+ * Re-exports:
+ *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - resolve                    (high-level composer)
+ *   - ResolvedPersona            (return type of resolve)
+ */
+export { loadPersona, loadKernel, availableKinds } from './loader.js';
+export { resolve } from './resolve.js';