@crouton-kit/crouter 0.3.13 → 0.3.14

package/dist/core/__tests__/passive-subscription.test.js

@@ -0,0 +1,141 @@
+// End-to-end tests for passive subscriptions:
+//   1. A passive subscriber's pushes land in passive.jsonl, NOT inbox.jsonl
+//      (so the inbox-watcher never wakes it); an active subscriber's land in
+//      inbox.jsonl as before.
+//   2. drainPassive reads + clears the accumulator (surfaces exactly once).
+//   3. canvas-passive-context formats drained entries as timestamped XML and
+//      transforms an `input` event into pre-text + the original message.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/passive-subscription.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, subscribe } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { inboxPath, passivePath } from '../canvas/paths.js';
+import { push } from '../feed/feed.js';
+import { appendPassive, readPassive, drainPassive } from '../feed/passive.js';
+import { readInboxSince } from '../feed/inbox.js';
+import registerCanvasPassiveContext, { formatPassive } from '../../pi-extensions/canvas-passive-context.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-passive-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    delete process.env['CRTR_NODE_ID'];
+});
+test('passive push accumulates in passive.jsonl, not inbox.jsonl', async () => {
+    createNode(node('pub'));
+    createNode(node('observer'));
+    subscribe('observer', 'pub', false); // PASSIVE
+    await push('pub', { kind: 'update', body: 'first observation\nmore detail' });
+    // No inbox entry → the inbox-watcher would never see it → no wake.
+    assert.equal(existsSync(inboxPath('observer')), false);
+    assert.equal(readInboxSince('observer').length, 0);
+    // It landed in the passive accumulator instead.
+    const acc = readPassive('observer');
+    assert.equal(acc.length, 1);
+    assert.equal(acc[0].from, 'pub');
+    assert.equal(acc[0].label, 'first observation');
+    assert.ok(acc[0].ref && acc[0].ref.endsWith('-update.md'));
+});
+test('active push still lands in inbox.jsonl (wakes)', async () => {
+    createNode(node('pub'));
+    createNode(node('worker-mgr'));
+    subscribe('worker-mgr', 'pub', true); // ACTIVE
+    await push('pub', { kind: 'update', body: 'active report' });
+    assert.equal(existsSync(passivePath('worker-mgr')), false);
+    const inbox = readInboxSince('worker-mgr');
+    assert.equal(inbox.length, 1);
+    assert.equal(inbox[0].from, 'pub');
+});
+test('mixed active + passive subscribers route to their own stores', async () => {
+    createNode(node('pub'));
+    createNode(node('active-sub'));
+    createNode(node('passive-sub'));
+    subscribe('active-sub', 'pub', true);
+    subscribe('passive-sub', 'pub', false);
+    const res = await push('pub', { kind: 'urgent', body: 'something happened' });
+    assert.deepEqual(new Set(res.deliveredTo), new Set(['active-sub', 'passive-sub']));
+    assert.equal(readInboxSince('active-sub').length, 1);
+    assert.equal(existsSync(passivePath('active-sub')), false);
+    assert.equal(readPassive('passive-sub').length, 1);
+    assert.equal(existsSync(inboxPath('passive-sub')), false);
+});
+test('drainPassive reads then clears (surfaces exactly once)', () => {
+    createNode(node('observer'));
+    appendPassive('observer', { from: 'a', tier: 'normal', kind: 'update', label: 'one' });
+    appendPassive('observer', { from: 'b', tier: 'normal', kind: 'update', label: 'two' });
+    const drained = drainPassive('observer');
+    assert.equal(drained.length, 2);
+    assert.deepEqual(drained.map((e) => e.label), ['one', 'two']); // oldest first
+    // Cleared — a second drain is empty.
+    assert.equal(drainPassive('observer').length, 0);
+    assert.equal(readPassive('observer').length, 0);
+});
+test('formatPassive renders timestamped XML update blocks', () => {
+    const entries = [
+        { ts: '2026-06-03T12:00:00.000Z', from: 'pub-a', tier: 'normal', kind: 'update', label: 'alpha happened' },
+        { ts: '2026-06-03T12:05:00.000Z', from: 'pub-b', tier: 'urgent', kind: 'final', label: 'beta done' },
+    ];
+    const xml = formatPassive(entries);
+    assert.match(xml, /<passive-subscription-backlog count="2"/);
+    assert.match(xml, /<update from="pub-a" kind="update" at="2026-06-03T12:00:00.000Z">/);
+    assert.match(xml, /alpha happened/);
+    assert.match(xml, /<update from="pub-b" kind="final" at="2026-06-03T12:05:00.000Z">/);
+    assert.match(xml, /<\/passive-subscription-backlog>/);
+});
+function makeFakePi() {
+    return { on(e, h) { if (e === 'input')
+            this.handler = h; } };
+}
+test('input handler injects drained backlog as pre-text, then clears it', async () => {
+    createNode(node('pub'));
+    createNode(node('observer'));
+    subscribe('observer', 'pub', false);
+    await push('pub', { kind: 'update', body: 'the body of the report\nsecond line' });
+    process.env['CRTR_NODE_ID'] = 'observer';
+    const pi = makeFakePi();
+    registerCanvasPassiveContext(pi);
+    assert.ok(pi.handler, 'input handler registered');
+    // First message → backlog drains in as pre-text before the user's text.
+    const out = pi.handler({ type: 'input', text: 'hey what happened', source: 'interactive' });
+    assert.equal(out.action, 'transform');
+    assert.match(out.text, /<passive-subscription-backlog/);
+    assert.match(out.text, /the body of the report/); // dereferenced report body
+    assert.match(out.text, /hey what happened$/); // original message preserved at the end
+    // Second message → nothing accumulated → left untouched.
+    const out2 = pi.handler({ type: 'input', text: 'still there?', source: 'interactive' });
+    assert.ok(out2 === undefined || out2.action === 'continue');
+});
+test('input handler is inert when nothing is accumulated', () => {
+    createNode(node('observer'));
+    process.env['CRTR_NODE_ID'] = 'observer';
+    const pi = makeFakePi();
+    registerCanvasPassiveContext(pi);
+    const out = pi.handler({ type: 'input', text: 'plain message', source: 'interactive' });
+    assert.ok(out === undefined || out.action === 'continue');
+});

package/dist/core/__tests__/subcommand-tier.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/subcommand-tier.test.js

@@ -0,0 +1,97 @@
+// Tests for the subcommand visibility tier (hidden | normal | common | important)
+// and the "[+N subcommands]" affordance.
+// Run with: node --import tsx/esm --test src/core/__tests__/subcommand-tier.test.ts
+//
+// Contract:
+//  - renderRoot promotes a subtree's `important` children (name + shortform
+//    desc) and `common` children (bare qualified path) into that command's
+//    block, then names how many other non-hidden subcommands stay behind
+//    `crtr <name> -h`.
+//  - `hidden` children never appear (not even in the subtree's own -h) and are
+//    not counted in any "[+N]" remainder.
+//  - renderBranch drops hidden children and flags branch children that own
+//    subcommands with "[+N subcommands]".
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { defineRoot, defineBranch, defineLeaf } from '../command.js';
+import { renderRoot, renderBranch } from '../help.js';
+const leaf = (name) => defineLeaf({
+    name,
+    help: { name, summary: name, output: [], outputKind: 'object', effects: ['None. Read-only.'] },
+    run: async () => ({}),
+});
+// A nested branch so we can assert the "[+N subcommands]" depth flag.
+const inspect = defineBranch({
+    name: 'inspect',
+    help: {
+        name: 'thing inspect',
+        summary: 'inspect',
+        children: [
+            { name: 'list', desc: 'list', useWhen: 'x' },
+            { name: 'show', desc: 'show', useWhen: 'x' },
+        ],
+    },
+    children: [leaf('list'), leaf('show')],
+});
+const thing = defineBranch({
+    name: 'thing',
+    rootEntry: { concept: 'a thing', desc: 'things', useWhen: 'doing things' },
+    help: {
+        name: 'thing',
+        summary: 'do things',
+        children: [
+            { name: 'make', desc: 'make a thing', useWhen: 'x', tier: 'important' },
+            { name: 'promote', desc: 'promote a thing', useWhen: 'x', tier: 'common' },
+            { name: 'inspect', desc: 'inspect things', useWhen: 'x' },
+            { name: 'secret', desc: 'secret op', useWhen: 'x', tier: 'hidden' },
+            { name: 'plain', desc: 'plain op', useWhen: 'x' },
+        ],
+    },
+    children: [leaf('make'), leaf('promote'), inspect, leaf('secret'), leaf('plain')],
+});
+const root = defineRoot({ tagline: 'test runtime', globals: [], subtrees: [thing] });
+describe('renderRoot: subcommand promotion', () => {
+    const out = renderRoot(root.help);
+    test('important child surfaces with its shortform desc', () => {
+        assert.match(out, /\n {2}thing make {2,}make a thing\n/);
+    });
+    test('common child surfaces as a bare qualified path (no desc)', () => {
+        assert.match(out, /\n {2}thing promote\n/);
+        assert.doesNotMatch(out, /thing promote {2,}promote a thing/);
+    });
+    test('hidden child is never promoted and not counted', () => {
+        assert.doesNotMatch(out, /secret/);
+        // 5 children, 1 hidden => 4 listable, 2 promoted => 2 remaining.
+        assert.match(out, /\[\+2 other subcommands — `crtr thing -h`\]/);
+    });
+});
+describe('renderRoot: commands with no promotions', () => {
+    test('still advertise their subcommand count', () => {
+        const bare = defineBranch({
+            name: 'bare',
+            rootEntry: { concept: 'bare', desc: 'bare', useWhen: 'x' },
+            help: { name: 'bare', summary: 'bare', children: [{ name: 'one', desc: 'one', useWhen: 'x' }] },
+            children: [leaf('one')],
+        });
+        const r = defineRoot({ tagline: 't', globals: [], subtrees: [bare] });
+        const out = renderRoot(r.help);
+        assert.match(out, /\[\+1 subcommand — `crtr bare -h`\]/); // singular, no "other"
+    });
+});
+describe('renderBranch: hidden filter + depth flag', () => {
+    const out = renderBranch(thing.help);
+    test('hidden child is dropped from the branch listing', () => {
+        assert.doesNotMatch(out, /secret/);
+    });
+    test('all non-hidden children are listed', () => {
+        for (const n of ['make', 'promote', 'inspect', 'plain']) {
+            assert.match(out, new RegExp(`\\n {2}${n} `));
+        }
+    });
+    test('a branch child flags how many subcommands it owns', () => {
+        assert.match(out, /inspect .* \[\+2 subcommands\]/);
+    });
+    test('leaf children carry no subcommand flag', () => {
+        assert.doesNotMatch(out, /make .* \[\+\d+ subcommands\]/);
+    });
+});

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

@@ -8,6 +8,10 @@ export declare function jobDir(nodeId: string): string;
 export declare function reportsDir(nodeId: string): string;
 export declare function nodeMetaPath(nodeId: string): string;
 export declare function inboxPath(nodeId: string): string;
+/** Passive-subscription accumulator. Pushes from publishers this node subscribes
+ *  to PASSIVELY land here instead of inbox.jsonl — the inbox-watcher never polls
+ *  it, so they never wake the node. Drained as XML pre-text on the next message. */
+export declare function passivePath(nodeId: string): string;
 export declare function transcriptPath(nodeId: string): string;
 export declare function sessionPtrPath(nodeId: string): string;
 /** Create the full directory skeleton for a node. Idempotent. */

package/dist/core/canvas/paths.js

@@ -44,6 +44,12 @@ export function nodeMetaPath(nodeId) {
 export function inboxPath(nodeId) {
     return join(nodeDir(nodeId), 'inbox.jsonl');
 }
+/** Passive-subscription accumulator. Pushes from publishers this node subscribes
+ *  to PASSIVELY land here instead of inbox.jsonl — the inbox-watcher never polls
+ *  it, so they never wake the node. Drained as XML pre-text on the next message. */
+export function passivePath(nodeId) {
+    return join(nodeDir(nodeId), 'passive.jsonl');
+}
 export function transcriptPath(nodeId) {
     return join(nodeDir(nodeId), 'transcript.jsonl');
 }

package/dist/core/command.js

@@ -23,7 +23,26 @@ export function defineLeaf(opts) {
         render: opts.render,
     };
 }
+/** Number of a node's own non-hidden subcommands (direct children). Leaves and
+ *  childless branches return 0. */
+function visibleSubCount(def) {
+    if (def.kind !== 'branch')
+        return 0;
+    return def.help.children.filter((c) => (c.tier ?? 'normal') !== 'hidden').length;
+}
 export function defineBranch(opts) {
+    // Enrich each help-child entry with the count of its own non-hidden
+    // subcommands so renderBranch can show "[+N subcommands]" when a branch child
+    // is listed without expanding it. Match help entries to child defs by name;
+    // entries without a matching def (or whose def has no subcommands) stay bare.
+    for (const hc of opts.help.children) {
+        const childDef = opts.children.find((c) => c.name === hc.name);
+        if (childDef !== undefined) {
+            const n = visibleSubCount(childDef);
+            if (n > 0)
+                hc.subCount = n;
+        }
+    }
     return {
         kind: 'branch',
         name: opts.name,
@@ -60,13 +79,27 @@ export function defineRoot(opts) {
     // 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,
-    }));
+        .map((s) => {
+        // Promote this subtree's common/important children into root, and count
+        // how many other (non-hidden) direct subcommands stay behind `<name> -h`.
+        const visible = s.help.children.filter((c) => (c.tier ?? 'normal') !== 'hidden');
+        const promoted = visible
+            .filter((c) => c.tier === 'common' || c.tier === 'important')
+            .map((c) => ({
+            path: `${s.name} ${c.name}`,
+            // important carries its shortform desc; common shows the bare path.
+            desc: c.tier === 'important' ? c.desc : undefined,
+        }));
+        return {
+            name: s.name,
+            concept: s.rootEntry.concept,
+            desc: s.rootEntry.desc,
+            useWhen: s.rootEntry.useWhen,
+            dynamicState: s.rootEntry.dynamicState,
+            subcommands: promoted.length > 0 ? promoted : undefined,
+            otherSubcommandCount: visible.length - promoted.length,
+        };
+    });
     const help = {
         tagline: opts.tagline,
         commands,

package/dist/core/feed/feed.js

@@ -11,6 +11,7 @@ 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';
+import { appendPassive } from './passive.js';
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -74,19 +75,20 @@ export async function push(nodeId, opts) {
     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).
+    // (b) Fan out a pointer to every subscriber. Active subscribers get it on
+    //     inbox.jsonl (the inbox-watcher polls that → a wake). Passive subscribers
+    //     get it on passive.jsonl instead — the watcher never polls that, so they
+    //     are NOT woken; the pointer accumulates until the node is next messaged,
+    //     when canvas-passive-context drains it as XML pre-text.
     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,
-        });
+        const entry = { from, tier: tierFor(kind), kind, ref: reportPath, label };
+        if (sub.active)
+            appendInbox(sub.node_id, entry);
+        else
+            appendPassive(sub.node_id, entry);
         deliveredTo.push(sub.node_id);
     }
     // (c) Finalise node when kind === 'final'.

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

@@ -0,0 +1,17 @@
+import type { InboxEntry } from './inbox.js';
+/**
+ * Atomically append one entry to `nodes/<nodeId>/passive.jsonl`.
+ * Fills `ts` (current ISO time). Returns the completed entry.
+ */
+export declare function appendPassive(nodeId: string, entry: Omit<InboxEntry, 'ts'>): InboxEntry;
+/** Return every accumulated passive entry (oldest first) without clearing. */
+export declare function readPassive(nodeId: string): InboxEntry[];
+/**
+ * Read AND clear the accumulator in one shot — the drain-on-message primitive.
+ *
+ * We rename the file aside before reading so a concurrent `appendPassive` (a
+ * publisher pushing at the same instant) starts a fresh file and is never lost
+ * to the truncate: at worst it lands in the next drain. The renamed snapshot is
+ * removed after a successful read. Returns the drained entries (oldest first).
+ */
+export declare function drainPassive(nodeId: string): InboxEntry[];

package/dist/core/feed/passive.js

@@ -0,0 +1,79 @@
+// Per-node passive-subscription accumulator for the pi-native canvas runtime.
+//
+// A PASSIVE subscription (the `active=false` flavor of a subscribes_to edge)
+// must never WAKE its subscriber. So when `push` fans out, a passive
+// subscriber's pointer is written here — to nodes/<id>/passive.jsonl — instead
+// of inbox.jsonl. The inbox-watcher polls only inbox.jsonl, so nothing here
+// triggers a turn.
+//
+// The accumulator is drained the moment the node is next MESSAGED: the
+// canvas-passive-context extension reads + clears this file on pi's `input`
+// event and injects every entry as timestamped XML pre-text before the message
+// reaches the LLM. Until then entries simply pile up, oldest first.
+//
+// Same entry shape as the inbox (InboxEntry) so the two stores stay symmetric
+// and a passive edge can be flipped active without reshaping data.
+import { appendFileSync, existsSync, readFileSync, renameSync, rmSync, mkdirSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { passivePath } from '../canvas/index.js';
+/**
+ * Atomically append one entry to `nodes/<nodeId>/passive.jsonl`.
+ * Fills `ts` (current ISO time). Returns the completed entry.
+ */
+export function appendPassive(nodeId, entry) {
+    const full = { ts: new Date().toISOString(), ...entry };
+    const line = JSON.stringify(full) + '\n';
+    const dir = dirname(passivePath(nodeId));
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    appendFileSync(passivePath(nodeId), line, { encoding: 'utf8', flag: 'a' });
+    return full;
+}
+/** Return every accumulated passive entry (oldest first) without clearing. */
+export function readPassive(nodeId) {
+    const p = passivePath(nodeId);
+    if (!existsSync(p))
+        return [];
+    return readFileSync(p, 'utf8')
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => JSON.parse(l));
+}
+/**
+ * Read AND clear the accumulator in one shot — the drain-on-message primitive.
+ *
+ * We rename the file aside before reading so a concurrent `appendPassive` (a
+ * publisher pushing at the same instant) starts a fresh file and is never lost
+ * to the truncate: at worst it lands in the next drain. The renamed snapshot is
+ * removed after a successful read. Returns the drained entries (oldest first).
+ */
+export function drainPassive(nodeId) {
+    const p = passivePath(nodeId);
+    if (!existsSync(p))
+        return [];
+    const snapshot = `${p}.draining`;
+    try {
+        renameSync(p, snapshot);
+    }
+    catch {
+        // Lost the race (file vanished) — nothing to drain.
+        return [];
+    }
+    let entries = [];
+    try {
+        entries = readFileSync(snapshot, 'utf8')
+            .split('\n')
+            .filter((l) => l.trim() !== '')
+            .map((l) => JSON.parse(l));
+    }
+    catch {
+        entries = [];
+    }
+    finally {
+        try {
+            rmSync(snapshot, { force: true });
+        }
+        catch { /* best-effort cleanup */ }
+    }
+    return entries;
+}

package/dist/core/help.d.ts

@@ -47,6 +47,29 @@ export interface ContextFileParam {
     shape?: string;
 }
 export type InputParam = PositionalParam | FlagParam | StdinParam | ContextFileParam;
+/** How prominently a subcommand surfaces in ancestor (parent / root) -h
+ *  listings. Set per child in the parent branch's `help.children`. Default
+ *  'normal'.
+ *   - hidden    — never listed anywhere, not even in this branch's own -h.
+ *                 You must already know it exists to invoke it.
+ *   - normal    — listed in this branch's own -h only (the default).
+ *   - common    — ALSO promoted into the parent's -h, as a bare qualified name.
+ *   - important — ALSO promoted into the parent's -h, name + shortform desc. */
+export type SubTier = 'hidden' | 'normal' | 'common' | 'important';
+/** One child entry in a branch's -h listing. `desc`/`useWhen` are the shortform
+ *  copy shown there; `tier` governs promotion into ancestor listings. */
+export interface BranchChild {
+    name: string;
+    desc: string;
+    useWhen: string;
+    /** Visibility tier in ancestor listings (see SubTier). Default 'normal'. */
+    tier?: SubTier;
+    /** Computed at define time (defineBranch): how many non-hidden subcommands
+     *  this child itself owns. Drives the "[+N subcommands]" affordance shown when
+     *  a branch child is listed without expanding its own subcommands. Absent for
+     *  leaves and childless branches. Do not author by hand. */
+    subCount?: number;
+}
 /** A subtree's self-description at the parent (root) level. Each subtree owns
  *  the content that represents it one level up: its vocabulary line, its
  *  selection rubric, and any bounded block it contributes to the parent's -h.
@@ -75,18 +98,32 @@ export interface RootHelp {
      *  root, carrying the subtree's concept, selection rubric, and any nested
      *  runtime-state block. Assembled from subtrees' RootEntry by defineRoot;
      *  root hardcodes none of it. */
-    commands: {
-        name: string;
-        concept: string;
-        desc: string;
-        useWhen: string;
-        dynamicState?: () => string | null;
-    }[];
+    commands: RootCommand[];
     globals: {
         name: string;
         desc: string;
     }[];
 }
+/** A single command block at root. Most fields come from the subtree's
+ *  RootEntry; `subcommands`/`otherSubcommandCount` are computed by defineRoot
+ *  from the subtree's children tiers. */
+export interface RootCommand {
+    name: string;
+    concept: string;
+    desc: string;
+    useWhen: string;
+    dynamicState?: () => string | null;
+    /** Promoted subcommands surfaced inline under this command at root, in
+     *  declaration order. `desc` is present only for 'important' tier; 'common'
+     *  tier carries the bare qualified path. */
+    subcommands?: {
+        path: string;
+        desc?: string;
+    }[];
+    /** How many of this command's other (non-hidden, not-promoted) direct
+     *  subcommands are not shown. Drives the "[+N (other) subcommands]" line. */
+    otherSubcommandCount?: number;
+}
 export interface BranchHelp {
     name: string;
     summary: string;
@@ -96,11 +133,7 @@ export interface BranchHelp {
      *  it with stateBlock), e.g. `<skills count="42">…</skills>`. Renderer
      *  soft-fails to omission if this returns null or throws. */
     dynamicState?: () => string | null;
-    children: {
-        name: string;
-        desc: string;
-        useWhen: string;
-    }[];
+    children: BranchChild[];
 }
 export interface LeafHelp {
     name: string;

package/dist/core/help.js

@@ -54,6 +54,31 @@ const IO_CONTRACT = 'I/O contract: flags and positional args on input; stdout is
 const CAPABILITY_DISCOVERY = "If the user mentions or implies a crtr capability you don't fully understand, " +
     'do not guess or assume it is unsupported — run `-h` on the relevant command ' +
     '(append it anywhere along the path) to read the contract before acting.';
+/** Lines for a command's subcommand affordance at root: any promoted
+ *  (common/important) subcommands, then a remainder line naming how many other
+ *  subcommands exist behind `crtr <name> -h`. Returns [] when the command has
+ *  no listable subcommands at all. */
+function rootSubcommandLines(c) {
+    const promoted = c.subcommands ?? [];
+    const other = c.otherSubcommandCount ?? 0;
+    if (promoted.length === 0 && other === 0)
+        return [];
+    const out = [];
+    if (promoted.length > 0) {
+        const labelW = maxLen(promoted.map((s) => s.path));
+        for (const s of promoted) {
+            // important → padded name + shortform desc; common → bare name.
+            out.push(s.desc !== undefined && s.desc !== ''
+                ? `  ${pad(s.path, labelW)}  ${s.desc}`
+                : `  ${s.path}`);
+        }
+    }
+    if (other > 0) {
+        const word = promoted.length > 0 ? 'other subcommand' : 'subcommand';
+        out.push(`  [+${other} ${word}${other === 1 ? '' : 's'} — \`crtr ${c.name} -h\`]`);
+    }
+    return out;
+}
 export function renderRoot(h) {
     const lines = [];
     lines.push(`${h.tagline}`);
@@ -71,6 +96,11 @@ export function renderRoot(h) {
         lines.push(`<command name="${c.name}">`);
         lines.push(c.concept);
         lines.push(`use when ${c.useWhen}`);
+        // The command's subcommand surface: promoted (common/important) children
+        // inline, plus a "[+N other subcommands]" pointer to its own -h. Sits
+        // between the selection rubric and any live state block.
+        for (const l of rootSubcommandLines(c))
+            lines.push(l);
         // dynamicState returns a complete self-named element (e.g.
         // <skills count="42">…</skills>) — emit it as-is, nested in the command.
         const state = evalDynamic(c.dynamicState);
@@ -113,10 +143,18 @@ export function renderBranch(h) {
     }
     lines.push('');
     lines.push('Branches');
-    const nameW = maxLen(h.children.map((c) => c.name));
-    const descW = maxLen(h.children.map((c) => c.desc));
-    for (const c of h.children) {
-        lines.push(`  ${pad(c.name, nameW)}  ${pad(c.desc, descW)}  | use when ${c.useWhen}`);
+    // 'hidden' children never appear in any listing — drop them here.
+    const visible = h.children.filter((c) => (c.tier ?? 'normal') !== 'hidden');
+    const nameW = maxLen(visible.map((c) => c.name));
+    const descW = maxLen(visible.map((c) => c.desc));
+    for (const c of visible) {
+        let line = `  ${pad(c.name, nameW)}  ${pad(c.desc, descW)}  | use when ${c.useWhen}`;
+        // A branch child is listed without its own subcommands expanded — flag how
+        // many it has so the agent knows there is more depth behind `<child> -h`.
+        if (c.subCount !== undefined && c.subCount > 0) {
+            line += `  [+${c.subCount} subcommand${c.subCount === 1 ? '' : 's'}]`;
+        }
+        lines.push(line);
     }
     return lines.join('\n');
 }

package/dist/core/runtime/demote.d.ts

@@ -0,0 +1,14 @@
+export interface DemoteResult {
+    /** True when the pane was recycled (a fresh root respawned in it). */
+    demoted: boolean;
+    /** True when a `final` report was pushed for the demoted node. */
+    finalized: boolean;
+    /** The fresh root node booted into the pane, or null on failure. */
+    newRoot: string | null;
+    /** Subscriber node ids that received the final report. */
+    delivered: string[];
+}
+/** Finish `nodeId` and recycle its pane into a fresh root. `callerPane` is the
+ *  tmux pane the agent occupies (the Alt+C menu passes it as `#{pane_id}`).
+ *  Best-effort; `demoted:false` when there is no pane to act on. */
+export declare function demoteNode(nodeId: string, callerPane?: string): Promise<DemoteResult>;