@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/core/canvas/render.js

@@ -0,0 +1,186 @@
+// render.ts — ASCII tree rendering of the canvas subscription sub-DAG.
+//
+// `subscriptionsOf(nodeId)` returns the nodes a node subscribes to, which in
+// the crtr model are its *reports* / *children*: a parent auto-subscribes to
+// each child it spawns so it wakes on the child's output. Walking subscriptionsOf
+// recursively therefore walks DOWN the org chart.
+//
+// Telemetry is read directly from <crtrHome>/nodes/<id>/job/telemetry.json
+// (the node-local job dir written by canvas-stophook on every turn_end).
+// Missing or corrupt telemetry → ctx 0k (best-effort, never throws).
+//
+// Cycle guard: the subscription graph is declared acyclic (a node cannot
+// subscribe to its own ancestor), but we track visited ids defensively because
+// the db is mutable and bugs happen.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getNode, listNodes, subscriptionsOf, view } from './canvas.js';
+import { jobDir } from './paths.js';
+import { countAsks } from './attention.js';
+// ---------------------------------------------------------------------------
+// Glyphs
+// ---------------------------------------------------------------------------
+const STATUS_GLYPH = {
+    active: '●',
+    idle: '○',
+    done: '✓',
+    dead: '✗',
+};
+function readNodeTelemetry(nodeId) {
+    const path = join(jobDir(nodeId), 'telemetry.json');
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Format a token count as `Nk` (rounded down to nearest 1 k). */
+function fmtCtx(tokensIn) {
+    if (tokensIn === undefined || tokensIn === 0)
+        return '0k';
+    return `${Math.floor(tokensIn / 1000)}k`;
+}
+// ---------------------------------------------------------------------------
+// Tree builder
+// ---------------------------------------------------------------------------
+/** Build one line of the ASCII tree. */
+function nodeLine(nodeId, indent, connector) {
+    const node = getNode(nodeId);
+    if (node === null) {
+        // Node id is in the db but meta.json is gone — paranoid guard.
+        return `${indent}${connector}? <missing meta: ${nodeId}>`;
+    }
+    const glyph = STATUS_GLYPH[node.status] ?? '?';
+    const tel = readNodeTelemetry(nodeId);
+    const ctx = fmtCtx(tel.tokens_in);
+    const asks = countAsks(nodeId);
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    return `${indent}${connector}${glyph} ${node.name} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`;
+}
+/**
+ * Recursively walk the subscription sub-DAG rooted at `nodeId`, appending
+ * rendered lines to `out`. Cycle-safe via `visited`.
+ */
+function walkTree(nodeId, indent, isLast, visited, out) {
+    // Guard: if we have already rendered this node in this traversal, emit a
+    // back-ref marker instead of recursing (prevents infinite loops in graphs
+    // with cycles introduced by manual edge manipulation).
+    if (visited.has(nodeId)) {
+        // The line for this node was already emitted by the caller; just return.
+        return;
+    }
+    visited.add(nodeId);
+    const connector = isLast ? '└─ ' : '├─ ';
+    out.push(nodeLine(nodeId, indent, connector));
+    const children = subscriptionsOf(nodeId);
+    const childIndent = indent + (isLast ? '   ' : '│  ');
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const childIsLast = i === children.length - 1;
+        if (visited.has(child.node_id)) {
+            // Cycle reference — show the back-edge without recursing.
+            const cycleConnector = childIsLast ? '└─ ' : '├─ ';
+            out.push(`${childIndent}${cycleConnector}↺ <cycle: ${child.node_id}>`);
+            continue;
+        }
+        walkTree(child.node_id, childIndent, childIsLast, visited, out);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Render the subscription sub-DAG rooted at `rootId` as an ASCII tree.
+ * The root is the first line (no connector prefix); children are indented.
+ *
+ * Each line: `<glyph> <name> [<kind>/<mode>] ctx <Nk>[ ⚑<asks>]`
+ *
+ * Returns a multi-line string (no trailing newline).
+ */
+export function renderTree(rootId) {
+    const node = getNode(rootId);
+    if (node === null)
+        return `? <missing node: ${rootId}>`;
+    const tel = readNodeTelemetry(rootId);
+    const ctx = fmtCtx(tel.tokens_in);
+    const asks = countAsks(rootId);
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    const glyph = STATUS_GLYPH[node.status] ?? '?';
+    const out = [];
+    out.push(`${glyph} ${node.name} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`);
+    // visited starts with root already rendered (walkTree doesn't re-emit root).
+    const visited = new Set([rootId]);
+    const children = subscriptionsOf(rootId);
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const isLast = i === children.length - 1;
+        walkTree(child.node_id, '', isLast, visited, out);
+    }
+    return out.join('\n');
+}
+/**
+ * Render all canvas roots as a forest. A root is a node with no subscribers
+ * (no one subscribes to it = it has no managers in the org chart).
+ *
+ * If there are no roots on the canvas, returns a placeholder string.
+ */
+export function renderForest() {
+    const all = listNodes();
+    if (all.length === 0)
+        return '(canvas is empty)';
+    // A root has no subscribers (nobody is watching it). We discover this by
+    // looking for nodes whose node_id never appears as a "to" side of a
+    // subscribes_to edge — equivalently, nodes with parent === null are the
+    // authoritative roots per the spawn contract (spawn sets parent and records
+    // a spawned_by edge + subscribe). Fall back to parent===null because querying
+    // the full edge table would require opening the db here.
+    //
+    // Fine to use parent===null: roots are created by `node session` / `node new`
+    // without a parent; non-roots always have a parent.
+    const roots = all.filter((n) => n.parent === null);
+    // If for some reason we have no parent===null nodes (unusual: e.g., all nodes
+    // were created by hand with a parent), fall back to all nodes.
+    const renderRoots = roots.length > 0 ? roots : all;
+    const parts = [];
+    for (const r of renderRoots) {
+        parts.push(renderTree(r.node_id));
+    }
+    return parts.join('\n\n');
+}
+/** One row per node visible in the sub-DAG of `rootId` (including root). */
+export function dashboardRows(rootId) {
+    const ids = [rootId, ...view(rootId)];
+    return ids.flatMap((id) => {
+        const node = getNode(id);
+        if (node === null)
+            return [];
+        const tel = readNodeTelemetry(id);
+        return [{
+                node_id: id,
+                name: node.name,
+                status: node.status,
+                kind: node.kind,
+                mode: node.mode,
+                ctx_tokens: tel.tokens_in ?? 0,
+                asks: countAsks(id),
+            }];
+    });
+}
+/** One row per node across the entire canvas. */
+export function dashboardRowsAll() {
+    return listNodes().flatMap((row) => {
+        const tel = readNodeTelemetry(row.node_id);
+        return [{
+                node_id: row.node_id,
+                name: row.name,
+                status: row.status,
+                kind: row.kind,
+                mode: row.mode,
+                ctx_tokens: tel.tokens_in ?? 0,
+                asks: countAsks(row.node_id),
+            }];
+    });
+}

package/dist/core/canvas/types.d.ts

@@ -0,0 +1,87 @@
+/** What a node is doing right now. UI shows active+idle; `done` is hidden but
+ *  revivable; only `dead` is a fault. */
+export type NodeStatus = 'active' | 'idle' | 'done' | 'dead';
+/** Does stopping finalize the node? terminal = worker (finalizes on push --final);
+ *  resident = manager/orchestrator (stays dormant, woken by inbox). */
+export type Lifecycle = 'terminal' | 'resident';
+/** base = hands-on worker; orchestrator = delegating manager. Bespoke per kind. */
+export type Mode = 'base' | 'orchestrator';
+/** Why a node last stopped — drives the daemon's reap-vs-revive decision. */
+export type ExitIntent = 'done' | 'refresh' | 'idle-release' | null;
+/** The two structural edges. `subscribes_to` is the load-bearing spine (flow,
+ *  org chart, views, completion routing). `spawned_by` is audit only. */
+export type EdgeType = 'subscribes_to' | 'spawned_by';
+/** The pi launch recipe, persisted so the daemon can faithfully revive a node
+ *  as its *current* self. Rewritten on every polymorph (base→orchestrator). */
+export interface LaunchSpec {
+    /** Model id/pattern passed to pi `--model`. */
+    model?: string;
+    /** pi `--tools` allow-list. */
+    tools?: string[];
+    /** pi `-e` extension paths, loaded once; they self-gate on live {kind,mode}. */
+    extensions: string[];
+    /** Resolved system prompt text (passed via --append-system-prompt / --system-prompt). */
+    systemPrompt?: string;
+    /** Extra env injected into the pi process. */
+    env: Record<string, string>;
+}
+/** A node's `meta.json` — source of truth for its canvas row. Files for flesh,
+ *  sqlite for skeleton: the db indexes the queryable subset of these fields. */
+export interface NodeMeta {
+    node_id: string;
+    name: string;
+    created: string;
+    /** The dir this node is pinned to — its cwd (where pi runs, bash executes). */
+    cwd: string;
+    /** Role the node was born as: explore | developer | plan | review | general… */
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    status: NodeStatus;
+    /** spawned_by target — who created me. Audit only; null for user-opened roots. */
+    parent?: string | null;
+    /** New subscriptions this node opens default to passive when true. */
+    passive_default?: boolean;
+    /** Why the node last stopped (done | refresh). Drives reap-vs-revive. */
+    intent?: ExitIntent;
+    /** The pi session id for `--resume`. */
+    pi_session_id?: string | null;
+    /** Full pi launch recipe; rewritten on every polymorph. */
+    launch?: LaunchSpec;
+    /** Presence: the tmux session (its root's home) and window this node renders
+     *  in while active. Cleared when the node goes done/dead and its window closes.
+     *  (Phase 5 promotes this to a dedicated presence registry.) */
+    tmux_session?: string | null;
+    window?: string | null;
+}
+/** The queryable projection of a NodeMeta stored as a canvas.db row. */
+export interface NodeRow {
+    node_id: string;
+    name: string;
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    status: NodeStatus;
+    cwd: string;
+    parent: string | null;
+    created: string;
+}
+/** An edge as stored. For `subscribes_to`, `from` is the subscriber and `to`
+ *  is the publisher (A subscribes_to B ⇒ A receives B's output). For
+ *  `spawned_by`, `from` is the child and `to` is the parent. */
+export interface Edge {
+    type: EdgeType;
+    from: string;
+    to: string;
+    /** Only meaningful for subscribes_to: active = wake the subscriber on emit;
+     *  passive = accumulate pointers, no wake. */
+    active: boolean;
+    created: string;
+}
+/** A subscription as seen from one endpoint. */
+export interface SubscriptionRef {
+    /** The node id at the other end of the edge. */
+    node_id: string;
+    active: boolean;
+    created: string;
+}

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

@@ -1,14 +1,43 @@
-import type { RootHelp, BranchHelp, LeafHelp, InputParam } from './help.js';
+import type { RootHelp, RootEntry, BranchHelp, LeafHelp, InputParam } from './help.js';
+import { CrtrError } from './errors.js';
+/** Opt-in flag that surfaces a node as an editor slash command (a pi prompt
+ *  template / Claude Code command). When set, the bootstrap auto-writes a
+ *  markdown template named `<name>.md` to the host's command dirs on each crtr
+ *  run, so `/name` becomes available. The body is thin — it points the agent at
+ *  the live `crtr` workflow so the CLI stays the source of truth. */
+export interface SlashSpec {
+    /** Command name → `/<name>` and the template filename. */
+    name: string;
+    /** Frontmatter description shown in the autocomplete dropdown. */
+    description: string;
+    /** Optional autocomplete hint, e.g. `<url>` or `[topic]`. */
+    argumentHint?: string;
+    /** Markdown body (no frontmatter). Bootstrap wraps it with frontmatter + a
+     *  version marker. Use `$ARGUMENTS` for the invocation's free text. */
+    body: string;
+}
 export interface LeafDef {
     kind: 'leaf';
     name: string;
     help: LeafHelp;
+    /** 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';
     name: string;
     help: BranchHelp;
+    /** How this subtree represents itself one level up. Present on top-level
+     *  subtrees (assembled into root -h by defineRoot); omitted on nested
+     *  branches, whose parent representation is the branch's own children list. */
+    rootEntry?: RootEntry;
+    /** Opt into editor slash-command exposure (see SlashSpec). */
+    slash?: SlashSpec;
     children: (LeafDef | BranchDef)[];
 }
 export interface RootDef {
@@ -19,18 +48,50 @@ export interface RootDef {
 export declare function defineLeaf(opts: {
     name: string;
     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;
     help: BranchHelp;
+    rootEntry?: RootEntry;
+    slash?: SlashSpec;
     children: (LeafDef | BranchDef)[];
 }): BranchDef;
+/** Walk the whole tree and collect every node's SlashSpec (depth-first). Used
+ *  by the bootstrap to discover which commands opted into slash exposure. */
+export declare function collectSlashSpecs(root: RootDef): SlashSpec[];
+/** Assemble root -h from the subtrees themselves. Root owns only the tagline
+ *  and globals; every subtree's concept line, selection rubric, and dynamic
+ *  block come from its own RootEntry. A subtree without a rootEntry does not
+ *  appear in root -h — declaring the parent-level representation is how a
+ *  subtree opts into being listed. */
 export declare function defineRoot(opts: {
-    help: RootHelp;
+    tagline: string;
+    globals: {
+        name: string;
+        desc: string;
+    }[];
     subtrees: BranchDef[];
 }): RootDef;
+type AnyNode = RootDef | BranchDef | LeafDef;
+/** Walk argv tokens to the deepest matched node.
+ *  Returns { node, path, remaining } where path is the sequence of matched node
+ *  names from root (excluding root itself) and remaining are unconsumed tokens.
+ *  -h / --help tokens are NOT consumed here — the caller checks for them. */
+export declare function walk(root: RootDef, tokens: string[]): {
+    node: AnyNode;
+    path: string[];
+    remaining: string[];
+};
+/** Build a structured unknown-path error. Names valid children of the deepest
+ *  matched node and names the entry command per the spec. The entry command is
+ *  the full path to the matched node (not just its local name), so the recovery
+ *  hint is a command that actually exists. No fuzzy matching. */
+export declare function unknownPathError(node: AnyNode, path: string[], bad: string): CrtrError;
 /** Parse remaining argv tokens against the leaf's InputParam schema.
  *  Returns a plain object whose keys are camelCase parameter names. */
 export declare function parseArgv(params: InputParam[], tokens: string[]): Promise<Record<string, unknown>>;
 export declare function runCli(root: RootDef, argv: string[]): Promise<void>;
+export {};

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';
@@ -17,14 +18,61 @@ export function defineLeaf(opts) {
         kind: 'leaf',
         name: opts.name,
         help: opts.help,
+        slash: opts.slash,
         run: opts.run,
+        render: opts.render,
     };
 }
 export function defineBranch(opts) {
-    return { kind: 'branch', name: opts.name, help: opts.help, children: opts.children };
+    return {
+        kind: 'branch',
+        name: opts.name,
+        help: opts.help,
+        rootEntry: opts.rootEntry,
+        slash: opts.slash,
+        children: opts.children,
+    };
 }
+/** Walk the whole tree and collect every node's SlashSpec (depth-first). Used
+ *  by the bootstrap to discover which commands opted into slash exposure. */
+export function collectSlashSpecs(root) {
+    const out = [];
+    const visit = (node) => {
+        if (node.slash !== undefined)
+            out.push(node.slash);
+        if (node.kind === 'branch')
+            for (const c of node.children)
+                visit(c);
+    };
+    for (const s of root.subtrees)
+        visit(s);
+    return out;
+}
+/** Assemble root -h from the subtrees themselves. Root owns only the tagline
+ *  and globals; every subtree's concept line, selection rubric, and dynamic
+ *  block come from its own RootEntry. A subtree without a rootEntry does not
+ *  appear in root -h — declaring the parent-level representation is how a
+ *  subtree opts into being listed. */
 export function defineRoot(opts) {
-    return { kind: 'root', help: opts.help, subtrees: opts.subtrees };
+    // Each listed subtree becomes one <name> block at root, assembled straight
+    // from its RootEntry. Root composes nothing and hardcodes nothing: add a
+    // subtree with a rootEntry and it surfaces; its concept, rubric, state tag,
+    // and dynamic block all travel with it.
+    const commands = opts.subtrees
+        .filter((s) => s.rootEntry !== undefined)
+        .map((s) => ({
+        name: s.name,
+        concept: s.rootEntry.concept,
+        desc: s.rootEntry.desc,
+        useWhen: s.rootEntry.useWhen,
+        dynamicState: s.rootEntry.dynamicState,
+    }));
+    const help = {
+        tagline: opts.tagline,
+        commands,
+        globals: opts.globals,
+    };
+    return { kind: 'root', help, subtrees: opts.subtrees };
 }
 /** Validate and return child names for an unknown-path error. */
 function childNames(node) {
@@ -35,10 +83,12 @@ function childNames(node) {
     return [];
 }
 /** Walk argv tokens to the deepest matched node.
- *  Returns { node, remaining } where remaining are unconsumed tokens.
+ *  Returns { node, path, remaining } where path is the sequence of matched node
+ *  names from root (excluding root itself) and remaining are unconsumed tokens.
  *  -h / --help tokens are NOT consumed here — the caller checks for them. */
-function walk(root, tokens) {
+export function walk(root, tokens) {
     let current = root;
+    const path = [];
     let i = 0;
     while (i < tokens.length) {
         const token = tokens[i];
@@ -50,6 +100,7 @@ function walk(root, tokens) {
             if (nextNode === undefined)
                 break;
             current = nextNode;
+            path.push(nextNode.name);
             i++;
         }
         else if (current.kind === 'branch') {
@@ -57,6 +108,7 @@ function walk(root, tokens) {
             if (nextNode === undefined)
                 break;
             current = nextNode;
+            path.push(nextNode.name);
             i++;
         }
         else {
@@ -64,7 +116,7 @@ function walk(root, tokens) {
             break;
         }
     }
-    return { node: current, remaining: tokens.slice(i) };
+    return { node: current, path, remaining: tokens.slice(i) };
 }
 function renderNode(node) {
     if (node.kind === 'root')
@@ -77,15 +129,13 @@ function helpRequested(remaining) {
     return remaining.some((t) => t === '-h' || t === '--help');
 }
 /** Build a structured unknown-path error. Names valid children of the deepest
- *  matched node and names the entry command per the spec. No fuzzy matching. */
-function unknownPathError(node, bad) {
+ *  matched node and names the entry command per the spec. The entry command is
+ *  the full path to the matched node (not just its local name), so the recovery
+ *  hint is a command that actually exists. No fuzzy matching. */
+export function unknownPathError(node, path, bad) {
     const valid = childNames(node);
     const validStr = valid.length > 0 ? valid.join(', ') : '(none)';
-    const entryCmd = node.kind === 'root'
-        ? 'crtr -h'
-        : node.kind === 'branch'
-            ? `crtr ${node.name} -h`
-            : 'crtr -h';
+    const entryCmd = path.length > 0 ? `crtr ${path.join(' ')} -h` : 'crtr -h';
     return new CrtrError('unknown_path', `unknown subcommand: ${bad}`, ExitCode.USAGE, {
         received: bad,
         next: `Valid children: ${validStr}. Run \`${entryCmd}\` for the full list.`,
@@ -215,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;
@@ -225,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) {
@@ -250,14 +310,21 @@ 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');
         process.exit(ExitCode.SUCCESS);
     }
-    const { node, remaining } = walk(root, tokens);
+    const { node, path, remaining } = walk(root, tokens);
     try {
         // Help anywhere in remaining tokens → print node help and exit
         if (helpRequested(remaining)) {
@@ -267,7 +334,7 @@ export async function runCli(root, argv) {
         // Bare branch or bare root (no -h, but no leaf selected) → help surface
         if (node.kind === 'root' || node.kind === 'branch') {
             if (remaining.length > 0) {
-                throw unknownPathError(node, remaining[0]);
+                throw unknownPathError(node, path, remaining[0]);
             }
             process.stdout.write(renderNode(node) + '\n');
             process.exit(ExitCode.SUCCESS);
@@ -277,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>;