@crouton-kit/crouter 0.3.12 → 0.3.14

package/dist/commands/node.js

@@ -11,10 +11,11 @@ import { promote, requestYield } from '../core/runtime/promote.js';
 import { writeYieldMessage } from '../core/runtime/kickoff.js';
 import { reviveNode } from '../core/runtime/revive.js';
 import { focusNodeInPlace } from '../core/runtime/presence.js';
-import { windowAlive } from '../core/runtime/tmux.js';
+import { demoteNode } from '../core/runtime/demote.js';
+import { windowAlive, windowOfPane, currentTmux } from '../core/runtime/tmux.js';
 import { appendInbox } from '../core/feed/inbox.js';
 import { availableKinds } from '../core/personas/index.js';
-import { getNode, listNodes, subscriptionsOf, subscribersOf, } from '../core/canvas/index.js';
+import { getNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, } from '../core/canvas/index.js';
 /** Validate a `--kind` against the installed personas; throws a listing InputError. */
 function assertKind(kind) {
     const kinds = availableKinds();
@@ -42,9 +43,9 @@ const nodeNew = defineLeaf({
             { name: 'node_id', type: 'string', required: true, constraint: 'The new node id.' },
             { name: 'name', type: 'string', required: true, constraint: 'Display name.' },
             { name: 'window', type: 'string', required: false, constraint: 'tmux window id of the background window.' },
-            { name: 'session', type: 'string', required: true, constraint: 'Root tmux session the node was placed in.' },
+            { name: 'session', type: 'string', required: true, constraint: 'The shared crtr tmux session the node was placed in.' },
             { name: 'status', type: 'string', required: true, constraint: 'Always "active" on spawn.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'A notification to the caller about the spawn: the child runs independently and its finish wakes you automatically, so treat it as fire-and-forget. Read it, then act.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign for the caller: the child runs independently and its finish wakes you on its own, so never wait or poll on it — either pick up other work now or end your turn. Read it, then act.' },
         ],
         outputKind: 'object',
         effects: [
@@ -70,7 +71,7 @@ const nodeNew = defineLeaf({
             window: res.window ?? undefined,
             session: res.session,
             status: res.node.status,
-            follow_up: "Notification only — you're auto-subscribed, so the child's finish wakes you automatically; treat it as fire-and-forget. Carry on with other independent work now, or stop and end your turn. On wake: `crtr feed read`.",
+            follow_up: "Do not wait or poll on this child — there is no result to await and stopping will not strand you. You're auto-subscribed, so its finish wakes you on its own. Two moves only: pick up other independent work right now, or stop and end your turn — the wake brings you back. Sitting idle to watch it is wasted; pick one and act.",
         };
     },
     render: (r) => `<spawned name="${r['name']}" id="${r['node_id']}" status="${r['status']}">\n${r['follow_up']}\n</spawned>`,
@@ -182,13 +183,159 @@ const nodeFocus = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
+// node demote — detach the agent in your pane to the background session
+// ---------------------------------------------------------------------------
+/** First live node whose window id is `win` (each node owns one window). The
+ *  queryable row projection omits `window`, so resolve full meta per candidate. */
+function nodeByWindow(win) {
+    for (const row of listNodes({ status: ['active', 'idle'] })) {
+        if (getNode(row.node_id)?.window === win)
+            return row.node_id;
+    }
+    return undefined;
+}
+/** The live node occupying a tmux pane (pane → window → node), or undefined.
+ *  Defaults to $TMUX_PANE / the caller's current pane when `pane` is omitted —
+ *  shared by `node demote` and `node cycle`, both of which act on "the agent in
+ *  front of you". */
+function nodeInPane(pane) {
+    const resolvePane = pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    const win = resolvePane !== undefined && resolvePane !== '' ? windowOfPane(resolvePane) : null;
+    return win !== null ? nodeByWindow(win) : undefined;
+}
+const nodeDemote = defineLeaf({
+    name: 'demote',
+    help: {
+        name: 'node demote',
+        summary: 'finish the agent in your current pane and recycle the pane — push its last message as a final report to everyone waiting on it, mark it done, then boot a fresh crtr root in the same pane',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to finish. Defaults to the node occupying --pane (or your current pane).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to recycle. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you.' },
+        ],
+        output: [
+            { name: 'demoted', type: 'boolean', required: true, constraint: 'True when the pane was recycled into a fresh root.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The finished node.' },
+            { name: 'finalized', type: 'boolean', required: false, constraint: 'True when a final report was pushed to its subscribers.' },
+            { name: 'delivered', type: 'number', required: false, constraint: 'How many subscribers/managers received the final report.' },
+            { name: 'new_root', type: 'string', required: false, constraint: 'The fresh root node booted into the pane.' },
+        ],
+        outputKind: 'object',
+        effects: ['Pushes a final report from the node (fans out to all subscribers) and marks it done.', 'Kills the agent\'s pi and respawns a fresh resident root in the same tmux pane.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        let id = input['node'];
+        if (id === undefined || id === '') {
+            // Derive the node from the pane: which node's window holds it?
+            id = nodeInPane(pane);
+        }
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node found in this pane to finish', next: 'Pass --node <id>, or run from inside the agent\'s pane.' });
+        }
+        if (getNode(id) === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const res = await demoteNode(id, pane);
+        return { demoted: res.demoted, node_id: id, finalized: res.finalized, delivered: res.delivered.length, new_root: res.newRoot ?? undefined };
+    },
+    render: (r) => r['demoted'] === true
+        ? `<demoted id="${r['node_id']}" finalized="${r['finalized']}" delivered="${r['delivered']}" new_root="${r['new_root'] ?? ''}"/>`
+        : `<demote-failed id="${r['node_id'] ?? ''}">not in tmux, or no agent in this pane</demote-failed>`,
+});
+// ---------------------------------------------------------------------------
+// node cycle — DFS-walk the canvas one window at a time (Alt+] / Alt+[)
+// ---------------------------------------------------------------------------
+/** Every live node in DFS pre-order across the whole forest. The spawn tree is
+ *  the `parent` field; children inherit their parent's row order (created), so
+ *  the walk descends into a node's children before moving to its siblings —
+ *  exactly "next in pre-order is your first child". Roots are live nodes with no
+ *  live parent (a done/dead parent orphans its live children up to the top).
+ *  Cycle-safe: a final pass appends any node a cycle kept from being reached. */
+function liveDfsOrder() {
+    const rows = listNodes({ status: ['active', 'idle'] }); // ORDER BY created
+    const liveIds = new Set(rows.map((r) => r.node_id));
+    const childrenOf = new Map();
+    for (const r of rows) {
+        const p = r.parent;
+        if (p != null && liveIds.has(p)) {
+            const arr = childrenOf.get(p) ?? [];
+            arr.push(r.node_id);
+            childrenOf.set(p, arr);
+        }
+    }
+    const out = [];
+    const seen = new Set();
+    const visit = (id) => {
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        out.push(id);
+        for (const c of childrenOf.get(id) ?? [])
+            visit(c);
+    };
+    for (const r of rows)
+        if (r.parent == null || !liveIds.has(r.parent))
+            visit(r.node_id);
+    for (const r of rows)
+        visit(r.node_id); // stragglers (parent cycles)
+    return out;
+}
+const nodeCycle = defineLeaf({
+    name: 'cycle',
+    help: {
+        name: 'node cycle',
+        summary: 'focus the next/previous live node in DFS pre-order — the canvas walked one window at a time, descending into a node\'s children before its siblings (bound to Alt+] forward / Alt+[ back)',
+        params: [
+            { kind: 'flag', name: 'dir', type: 'enum', choices: ['next', 'prev'], required: false, default: 'next', constraint: 'Direction along the pre-order: next (Alt+], rightward/deeper into children) or prev (Alt+[, back). Wraps at the ends.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane to cycle FROM. Defaults to $TMUX_PANE / your current pane. The Alt+] / Alt+[ bindings pass this for you.' },
+        ],
+        output: [
+            { name: 'focused', type: 'boolean', required: true, constraint: 'True when the neighbor was brought into view.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The node now in front of you.' },
+            { name: 'name', type: 'string', required: false, constraint: 'Its display name.' },
+            { name: 'from', type: 'string', required: false, constraint: 'The node you cycled away from.' },
+        ],
+        outputKind: 'object',
+        effects: ['Swaps the neighbor\'s pane into the caller pane (like `node focus`); the node you were viewing drops to the background.', 'Revives the neighbor first if its window was released.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane ?? undefined;
+        const dir = (input['dir'] ?? 'next');
+        const fromId = nodeInPane(pane);
+        if (fromId === undefined)
+            return { focused: false };
+        const order = liveDfsOrder();
+        const i = order.indexOf(fromId);
+        if (i === -1 || order.length < 2)
+            return { focused: false, node_id: fromId, from: fromId };
+        const step = dir === 'next' ? 1 : -1;
+        const targetId = order[(i + step + order.length) % order.length];
+        const target = getNode(targetId);
+        if (target === null)
+            return { focused: false, from: fromId };
+        // A live node may have had its window released — revive (resume) so there is
+        // a window to swap in, mirroring `node focus`.
+        if (!windowAlive(target.tmux_session, target.window)) {
+            try {
+                reviveNode(targetId, { resume: true });
+            }
+            catch { /* fall through */ }
+        }
+        const res = focusNodeInPlace(targetId, pane, fromId);
+        return { focused: res.focused, node_id: targetId, name: target.name, from: fromId };
+    },
+    render: (r) => r['focused'] === true
+        ? `<cycled to="${r['node_id']}" name="${r['name'] ?? ''}" from="${r['from'] ?? ''}"/>`
+        : `<cycle-noop>no other live node to focus</cycle-noop>`,
+});
+// ---------------------------------------------------------------------------
 // node session — boot a NEW root in its own tmux session (the explicit form)
 // ---------------------------------------------------------------------------
 const nodeSession = defineLeaf({
     name: 'session',
     help: {
         name: 'node session',
-        summary: 'start a fresh root node in its own tmux session and switch to it (use from inside a node to start a new root without taking your pane)',
+        summary: 'start a fresh root node as its own window in the shared crtr session (use from inside a node to start a new root without taking your pane)',
         params: [
             { kind: 'stdin', name: 'prompt', required: false, constraint: 'Optional starter prompt; a root needs none.' },
             { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind for the root.' },
@@ -197,11 +344,11 @@ const nodeSession = defineLeaf({
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The root node id.' },
-            { name: 'session', type: 'string', required: true, constraint: 'The dedicated tmux session created for this root.' },
+            { name: 'session', type: 'string', required: true, constraint: 'The shared crtr tmux session this root\'s window was placed in.' },
             { name: 'window', type: 'string', required: false, constraint: 'The root node\'s window id.' },
         ],
         outputKind: 'object',
-        effects: ['Creates a detached tmux session and runs pi in it as a resident root node.'],
+        effects: ['Opens a detached window in the shared crtr session and runs pi in it as a resident root node.'],
     },
     run: async (input) => {
         const prompt = input['prompt'];
@@ -258,15 +405,86 @@ const nodeMsg = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
+// node subscribe / unsubscribe — wire the subscribes_to spine between any pair
+// ---------------------------------------------------------------------------
+/** Resolve the subscriber: explicit --subscriber wins, else the calling node. */
+function resolveSubscriber(input) {
+    const sub = input['subscriber'] ?? process.env['CRTR_NODE_ID'];
+    if (sub === undefined || sub === '') {
+        throw new InputError({ error: 'no_subscriber', message: 'no subscriber (set CRTR_NODE_ID or pass --subscriber)', field: 'subscriber', next: 'Run from inside a node, or pass --subscriber <id>.' });
+    }
+    return sub;
+}
+const nodeSubscribe = defineLeaf({
+    name: 'subscribe',
+    help: {
+        name: 'node subscribe',
+        summary: 'wire a subscribes_to edge so one node receives another\'s pushes — the subscriber can be you (default) or, with --subscriber, ANY node, to ANY publisher. Re-running flips an existing edge\'s active/passive mode.',
+        params: [
+            { kind: 'positional', name: 'publisher', required: true, constraint: 'The node to subscribe TO — whose pushes get delivered to the subscriber.' },
+            { kind: 'flag', name: 'subscriber', type: 'string', required: false, constraint: 'Who receives the pushes. Defaults to the calling node (CRTR_NODE_ID). Pass any node id to wire a third party.' },
+            { kind: 'flag', name: 'passive', type: 'bool', required: false, constraint: 'Passive subscription: pushes ACCUMULATE without waking the subscriber, then auto-inject as timestamped XML pre-text on its next message. Omit for an active (wake-on-push) subscription.' },
+        ],
+        output: [
+            { name: 'subscribed', type: 'boolean', required: true, constraint: 'True when the edge was created/updated.' },
+            { name: 'subscriber', type: 'string', required: true, constraint: 'The receiving node.' },
+            { name: 'publisher', type: 'string', required: true, constraint: 'The node being subscribed to.' },
+            { name: 'mode', type: 'string', required: true, constraint: '"active" (wakes on push) or "passive" (accumulates, no wake).' },
+        ],
+        outputKind: 'object',
+        effects: ['Upserts a subscribes_to edge in canvas.db (active flag set from --passive).', 'Passive edges never wake the subscriber and do not hold it alive (excluded from the stop-guard).'],
+    },
+    run: async (input) => {
+        const publisher = input['publisher'];
+        const subscriber = resolveSubscriber(input);
+        const passive = input['passive'] === true;
+        if (subscriber === publisher) {
+            throw new InputError({ error: 'self_subscribe', message: 'a node cannot subscribe to itself', next: 'Pick a different publisher.' });
+        }
+        if (getNode(subscriber) === null)
+            throw new InputError({ error: 'not_found', message: `no node: ${subscriber}`, field: 'subscriber', next: 'List nodes with `crtr node inspect list`.' });
+        if (getNode(publisher) === null)
+            throw new InputError({ error: 'not_found', message: `no node: ${publisher}`, field: 'publisher', next: 'List nodes with `crtr node inspect list`.' });
+        subscribe(subscriber, publisher, !passive);
+        return { subscribed: true, subscriber, publisher, mode: passive ? 'passive' : 'active' };
+    },
+    render: (r) => `<subscribed subscriber="${r['subscriber']}" publisher="${r['publisher']}" mode="${r['mode']}"/>`,
+});
+const nodeUnsubscribe = defineLeaf({
+    name: 'unsubscribe',
+    help: {
+        name: 'node unsubscribe',
+        summary: 'drop a subscribes_to edge — the subscriber (you by default, or any node via --subscriber) stops receiving the publisher\'s pushes.',
+        params: [
+            { kind: 'positional', name: 'publisher', required: true, constraint: 'The node to stop subscribing to.' },
+            { kind: 'flag', name: 'subscriber', type: 'string', required: false, constraint: 'Who to detach. Defaults to the calling node (CRTR_NODE_ID).' },
+        ],
+        output: [
+            { name: 'unsubscribed', type: 'boolean', required: true, constraint: 'True when the edge was removed (idempotent — also true if none existed).' },
+            { name: 'subscriber', type: 'string', required: true, constraint: 'The detached node.' },
+            { name: 'publisher', type: 'string', required: true, constraint: 'The node it stopped subscribing to.' },
+        ],
+        outputKind: 'object',
+        effects: ['Deletes the subscribes_to edge from canvas.db.'],
+    },
+    run: async (input) => {
+        const publisher = input['publisher'];
+        const subscriber = resolveSubscriber(input);
+        unsubscribe(subscriber, publisher);
+        return { unsubscribed: true, subscriber, publisher };
+    },
+    render: (r) => `<unsubscribed subscriber="${r['subscriber']}" publisher="${r['publisher']}"/>`,
+});
+// ---------------------------------------------------------------------------
 // node promote — become a resident orchestrator (terminal → resident polymorph)
 // ---------------------------------------------------------------------------
 const nodePromote = defineLeaf({
     name: 'promote',
     help: {
         name: 'node promote',
-        summary: 'promote yourself to a resident orchestrator of a chosen kind — flips to that kind\'s orchestrator persona on next revive, dumps its orchestration + roadmap-shaping guidance now, and seeds a roadmap scaffold for you to author',
+        summary: 'promote yourself to a resident orchestrator — do this when your task outgrows one context window (many phases to delegate and persist across refreshes); not for work that fits one window, and not merely because you spawned a child',
         params: [
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator: developer (own feature delivery), review, spec, design, plan, explore, general. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it picks the orchestrator persona you revive into and the roadmap-shaping skill dumped now.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator: developer (own feature delivery), review, spec, design, plan, explore, general. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
         ],
         output: [
@@ -274,7 +492,9 @@ const nodePromote = defineLeaf({
             { name: 'kind', type: 'string', required: true, constraint: 'The kind it now orchestrates as.' },
             { name: 'mode', type: 'string', required: true, constraint: 'Now "orchestrator".' },
             { name: 'roadmap_written', type: 'boolean', required: true, constraint: 'True if a roadmap scaffold was seeded by this call.' },
-            { name: 'guidance', type: 'string', required: true, constraint: 'Kind-specific orchestration + roadmap-shaping guidance and your roadmap scaffold — read it, then AUTHOR your roadmap (goal, exit criteria, phases) this turn before delegating.' },
+            { name: 'roadmap_path', type: 'string', required: true, constraint: 'Absolute path to your roadmap doc (context/roadmap.md) — edit it to author your plan.' },
+            { name: 'goal_path', type: 'string', required: true, constraint: 'Absolute path to your goal doc (context/initial-prompt.md) — the mandate you were spawned with.' },
+            { name: 'guidance', type: 'string', required: true, constraint: 'Instructions for your new role — read and act on them this turn.' },
         ],
         outputKind: 'object',
         effects: ['Flips lifecycle→resident, mode→orchestrator, kind→chosen; rewrites the launch spec to that kind\'s orchestrator persona; seeds context/roadmap.md scaffold if absent.'],
@@ -287,7 +507,7 @@ const nodePromote = defineLeaf({
         if (kind !== undefined)
             assertKind(kind);
         const res = promote(id, kind !== undefined ? { kind } : {});
-        return { node_id: res.meta.node_id, kind: res.meta.kind, mode: res.meta.mode, roadmap_written: res.roadmapWritten, guidance: res.guidance };
+        return { node_id: res.meta.node_id, kind: res.meta.kind, mode: res.meta.mode, roadmap_written: res.roadmapWritten, roadmap_path: res.roadmapPath, goal_path: res.goalPath, guidance: res.guidance };
     },
 });
 // ---------------------------------------------------------------------------
@@ -340,15 +560,19 @@ export function registerNode() {
                 'HOW: `crtr node new "<task>" --kind <kind>` returns a node id immediately and runs the worker in a background window. Match the kind to the work (see `node new -h`). You are woken when a child finishes; absorb what your children reported with `crtr feed read` (coalesced pointers — dereference the report paths that matter, don\'t act on a one-line summary). Integrate, then either delegate the next units or finish.\n\n' +
                 'FINISH: a worker ends its own work with `crtr push final "<result>"` (writes the canonical result, marks done, closes the window) — stopping without it is not finishing. For a job too big for one context window, `node promote` to a resident orchestrator (holds a roadmap, delegates phases); when context fills, `node yield` to refresh against that roadmap.',
             children: [
-                { name: 'new', desc: 'spawn a terminal worker as a background window', useWhen: 'delegating a self-contained unit of work' },
+                { name: 'new', desc: 'spawn a terminal worker as a background window', useWhen: 'delegating a self-contained unit of work', tier: 'important' },
                 { name: 'inspect', desc: 'read the graph (list nodes / show one)', useWhen: 'surveying the canvas or inspecting a node' },
                 { name: 'focus', desc: 'bring a node window forefront', useWhen: 'jumping to a node to watch or steer it' },
+                { name: 'cycle', desc: 'DFS-walk to the next/prev live node in place', useWhen: 'sweeping the canvas one window at a time (Alt+] forward / Alt+[ back)' },
+                { name: 'demote', desc: 'finish the agent in your pane + recycle it into a fresh root', useWhen: 'wrapping up the agent in front of you and starting fresh (Alt+C → d)' },
                 { name: 'session', desc: 'open a fresh root in its own tmux session', useWhen: 'starting a new top-level session from inside a node' },
                 { name: 'msg', desc: 'direct-message any node at a wake tier', useWhen: 'steering or pinging a specific node (wakes it)' },
-                { name: 'promote', desc: 'become a resident orchestrator of a chosen kind', useWhen: 'your task is bigger than one context window and you must delegate + persist' },
+                { name: 'subscribe', desc: 'wire a subscribes_to edge between any pair (active or --passive)', useWhen: 'making a node (you or another) receive another node\'s pushes' },
+                { name: 'unsubscribe', desc: 'drop a subscribes_to edge', useWhen: 'detaching a subscriber from a publisher' },
+                { name: 'promote', desc: 'become a resident orchestrator of a chosen kind', useWhen: 'your task is bigger than one context window and you must delegate + persist', tier: 'important' },
                 { name: 'yield', desc: 'refresh your context against your roadmap', useWhen: 'your context window is filling up' },
             ],
         },
-        children: [nodeNew, nodeInspect, nodeFocus, nodeSession, nodeMsg, nodePromote, nodeYield],
+        children: [nodeNew, nodeInspect, nodeFocus, nodeCycle, nodeDemote, nodeSession, nodeMsg, nodeSubscribe, nodeUnsubscribe, nodePromote, nodeYield],
     });
 }

package/dist/core/__tests__/passive-subscription.test.d.ts

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

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');
 }