@crouton-kit/crouter 0.3.26 → 0.3.28

package/dist/builtin-memory/internal/INDEX.md

@@ -16,6 +16,6 @@ Open this dir whenever a task turns on understanding the runtime itself. Content
 - **storage-tiers** — where every kind of state lives: the three tiers (scope root, per-cwd crouter root, canvas home) and their durability/ownership contracts.
 - **examples/** — worked compositions of the primitives into complete systems (the analogue of pi's `examples/` dir), e.g. the iMessage assistant node.
 
-Adjacent, outside this dir: authoring memory documents (frontmatter, rungs, gates, the asked-to-remember workflow) is owned by the builtin **memory-authoring** skill; making a persona (a custom `--kind`) is owned by the builtin **crouter-development/personas** skills.
+Adjacent, outside this dir: authoring memory documents (kind, rungs, gates, routing line, the asked-to-remember workflow) is owned by `crtr memory write -h` — the authoring guide lives on the help-gate so it surfaces exactly when you write; making a persona (a custom `--kind`) is owned by the builtin **crouter-development/personas** skills.
 
 The individual files surface at `name` (their titles route; open the one the situation calls for); this index surfaces at `preview` so the dir announces when to come looking.

package/dist/builtin-personas/runtime-base.md

@@ -15,6 +15,9 @@ Don't stall and don't guess at a decision a person should make:
 
     crtr human ask "<question>"
 
+## When crtr itself misbehaves
+A `crtr` command that errors unexpectedly, hangs, churns, double-spawns, or contradicts its own `-h` is a harness bug — don't silently work around it. Run `crtr sys feedback` to report it (`-h` for how), then continue.
+
 ## When your task is too big for one context window
 If you discover the job is far larger than one node can hold — many phases, or work that won't fit before you run low on context — **promote yourself** instead of grinding it out:
 

package/dist/clients/attach/__tests__/reconnect-giveup.test.d.ts

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

package/dist/clients/attach/__tests__/reconnect-giveup.test.js

@@ -0,0 +1,30 @@
+// Regression: the `crtr attach` viewer used to ALWAYS teardown ("broker gone")
+// on a socket close, so a resident broker node's yield→revive cycle dropped the
+// viewer to a shell. The fix holds the pane and re-dials the SAME view.sock
+// while the node is still alive, giving up only when it is genuinely gone. This
+// locks the give-up/keep-reconnecting decision (the bug-prone core) without a
+// socket or tmux. See src/clients/attach/{view-socket,attach-cmd}.ts.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { reconnectShouldGiveUp } from '../view-socket.js';
+const rowWith = (status) => ({
+    node_id: 'n',
+    status,
+    host_kind: 'broker',
+    intent: null,
+    pi_pid: null,
+});
+test('keeps reconnecting while the node is still alive (active = mid yield/revive)', () => {
+    // A yield leaves status='active' (intent='refresh') — must NOT give up.
+    assert.equal(reconnectShouldGiveUp(rowWith('active')), false);
+    // idle-release revives on the next inbox wake — keep trying (bounded by the
+    // supervisor's own ~30s deadline), do not give up.
+    assert.equal(reconnectShouldGiveUp(rowWith('idle')), false);
+});
+test('gives up the instant the node is genuinely gone', () => {
+    assert.equal(reconnectShouldGiveUp(rowWith('done')), true);
+    assert.equal(reconnectShouldGiveUp(rowWith('dead')), true);
+    assert.equal(reconnectShouldGiveUp(rowWith('canceled')), true);
+    // A reaped row (null) → give up.
+    assert.equal(reconnectShouldGiveUp(null), true);
+});

package/dist/clients/attach/attach-cmd.js

@@ -15,18 +15,40 @@
 // `crtr attach <node>` form is not expressible without a framework change. attach
 // is therefore a BRANCH wrapping a single leaf: `crtr attach to <node>`.
 import { randomUUID } from 'node:crypto';
-import { Container, ProcessTerminal, Text, TUI, matchesKey, } from '@earendil-works/pi-tui';
+import { execFile } from 'node:child_process';
+import { CombinedAutocompleteProvider, Container, ProcessTerminal, Text, TUI, matchesKey, } from '@earendil-works/pi-tui';
 import { CustomEditor, getSelectListTheme, } from '@earendil-works/pi-coding-agent';
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
-import { getNode } from '../../core/canvas/index.js';
+import { getNode, getRow } from '../../core/canvas/index.js';
 // tmux driver verbs only through placement (the §5.1 model-over-driver seam) —
 // never `core/runtime/tmux.js` directly.
 import { setPaneOption, currentTmux } from '../../core/runtime/placement.js';
+import { climbRoot } from '../../core/canvas/nav-model.js';
 import { ChatView } from './chat-view.js';
 import { InputController } from './input-controller.js';
+import { buildCanvasPanelLines } from './canvas-panels.js';
+import { GraphOverlay } from './graph-overlay.js';
+import { slashCommandList } from './slash-commands.js';
 import { applyTheme, createKeybindingsManager } from './config-load.js';
-import { BrokerUnavailableError, ViewSocketClient } from './view-socket.js';
+import { BrokerUnavailableError, ViewSocketClient, reconnectShouldGiveUp } from './view-socket.js';
+/** Async per-node ask-map fetch (NON-blocking — the viewer must never block its
+ *  input pump on a shell-out, unlike canvas-nav's execFileSync). Buckets a whole
+ *  sub-DAG's pending asks in one `crtr` process; on any error the callback is not
+ *  invoked, so the caller keeps its last good map. */
+function fetchAsksAsync(rootId, cb) {
+    execFile('crtr', ['canvas', 'attention', 'map', '--view', rootId, '--json'], { timeout: 2_500, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+        if (err)
+            return;
+        try {
+            const parsed = JSON.parse(stdout.trim());
+            cb(parsed.counts ?? {});
+        }
+        catch {
+            /* malformed — keep last map */
+        }
+    });
+}
 /** Run the interactive attach session against `nodeId`. Resolves when the
  *  viewer detaches (ctrl+c/ctrl+d), the broker goes away, or a signal lands —
  *  always restoring the terminal first. */
@@ -101,12 +123,27 @@ async function runAttach(nodeId, observer) {
     //    otherwise (T5 contract). One KeybindingsManager feeds BOTH editor + input.
     applyTheme({ cwd: meta.cwd });
     const km = createKeybindingsManager();
-    // 2. TUI + chat container + editor.
+    // 2. TUI + layout containers + editor. Top-to-bottom render order (set at
+    //    step 8): chat · badge · managers (↑ subscriber) · editor · reports
+    //    (↓ subscriptions) · footer. The badge sits in the BOTTOM-anchored chrome
+    //    stack (directly above managers), NOT as the topmost child: pi-tui anchors
+    //    the viewport to the cursor at the bottom, so a topmost badge scrolls off
+    //    into scrollback the instant the chat exceeds one screen. The badge + the
+    //    two canvas panels reproduce the pi-extension chrome natively (Unit Q).
     const tui = new TUI(new ProcessTerminal());
+    const badge = new Container();
     const chatContainer = new Container();
+    const managers = new Container();
+    const reports = new Container();
     const footer = new Container();
     const editorTheme = { borderColor: (s) => s, selectList: getSelectListTheme() };
     const editor = new CustomEditor(tui, editorTheme, km, { paddingX: 1 });
+    // Slash-command autocomplete: builtins + native canvas commands now; enriched
+    // with the broker's engine/extension/skill commands on the get_commands ack.
+    const setCommands = (commands) => {
+        editor.setAutocompleteProvider(new CombinedAutocompleteProvider(slashCommandList(commands), meta.cwd));
+    };
+    setCommands();
     // 3. Render layer (T5). ChatView owns the chat scroll + activity spinner; the
     //    footer/status line below is ours, so onFooterEvent is left unset (footer
     //    updates flow through handleBrokerFrame's single update path instead).
@@ -122,8 +159,6 @@ async function runAttach(nodeId, observer) {
             bits.push(liveState.model);
         if (liveState?.isStreaming)
             bits.push('streaming');
-        if (liveState?.sessionName)
-            bits.push(liveState.sessionName);
         if (liveState && liveState.pendingMessageCount > 0)
             bits.push(`queued ${liveState.pendingMessageCount}`);
         let line = `\x1b[2m${bits.join(' · ')}\x1b[22m`;
@@ -137,11 +172,47 @@ async function runAttach(nodeId, observer) {
         notice = msg;
         renderFooter();
     };
-    // 5. Input layer (T6). onCommand/onDialogResponse → socket; onNotice → footer.
+    // Name badge — the session name (= the canvas editor label `kind (mode)
+    // name`), relayed over the socket and patched live (Feature 1). Rendered just
+    // above the managers line in the bottom chrome so it stays in-viewport.
+    const renderBadge = () => {
+        badge.clear();
+        if (liveState?.sessionName)
+            badge.addChild(new Text(`\x1b[1m${liveState.sessionName}\x1b[22m`, 1, 0));
+        tui.requestRender();
+    };
+    // Subscribed-node panel — manager line above the editor, live reports below,
+    // read straight from canvas.db via nav-model (Feature 2). asksMap is refreshed
+    // by the low-rate poll below; beginFrame() inside buildCanvasPanelLines memoizes
+    // the db reads for each rebuild.
+    let asksMap = {};
+    const renderPanels = () => {
+        const { managers: mLines, reports: rLines } = buildCanvasPanelLines(nodeId, asksMap);
+        managers.clear();
+        for (const l of mLines)
+            managers.addChild(new Text(l, 1, 0));
+        reports.clear();
+        for (const l of rLines)
+            reports.addChild(new Text(l, 1, 0));
+        tui.requestRender();
+    };
+    // The alt+g GRAPH overlay (Feature 3) — a full-screen navigator over the same
+    // nav-model graph, reading the live asksMap.
+    const graphOverlay = new GraphOverlay(tui, nodeId, () => asksMap);
+    // Refresh all canvas chrome (panels + overlay if open) from canvas.db.
+    const refreshChrome = () => {
+        renderPanels();
+        graphOverlay.refresh();
+    };
+    // 5. Input layer (T6). onCommand/onDialogResponse → socket; onNotice → footer;
+    //    nodeId/onGraph feed the slash context (/promote targets this node, /graph
+    //    toggles the overlay).
     const input = new InputController(tui, editor, km, {
         onCommand: (frame) => socket.send(frame),
         onDialogResponse: (resp) => socket.send(resp),
         onNotice: (msg) => setNotice(msg),
+        nodeId,
+        onGraph: () => graphOverlay.toggle(),
     });
     // Feed fresh state into the input controller AND the footer. Steer-vs-prompt
     // routing (T6) reads `state.isStreaming`, so this must stay current — the
@@ -151,6 +222,11 @@ async function runAttach(nodeId, observer) {
         liveState = state;
         input.setState(state);
         renderFooter();
+        renderBadge();
+        // Panel liveness rides the relayed event stream (agent_start/agent_end/
+        // queue_update/session_info_changed all patch state through here) plus the
+        // low-rate poll below for changes that emit no event (child status flips).
+        refreshChrome();
     };
     const patchState = (patch) => {
         if (liveState === undefined)
@@ -164,6 +240,9 @@ async function runAttach(nodeId, observer) {
                 role = frame.role;
                 chatView.applySnapshot(frame.snapshot);
                 setLiveState(frame.snapshot.state);
+                // Ask the broker for its merged command list (engine/extension/skill
+                // commands) to enrich slash autocomplete beyond the builtins+canvas set.
+                socket.send({ type: 'get_commands' });
                 if (frame.pending_dialog != null)
                     input.attachDialog(frame.pending_dialog);
                 break;
@@ -185,10 +264,19 @@ async function runAttach(nodeId, observer) {
                 break;
             }
             case 'ack': {
-                // Dynamic-command autocomplete (feeding get_commands into T6's palette)
-                // is DEFERRED for Phase 4 (would require editing T6's input-controller —
-                // out of my 3-file scope; the fall-through-to-prompt path already makes
-                // extension commands functional). Surface only command failures here.
+                // get_commands replies with the broker's merged command list as JSON in
+                // `detail` — rebuild the autocomplete provider with it (slashCommandList
+                // re-appends the native canvas commands, deduped).
+                if (frame.for === 'get_commands' && frame.ok && frame.detail) {
+                    try {
+                        const list = JSON.parse(frame.detail);
+                        setCommands(list);
+                    }
+                    catch {
+                        /* malformed — keep the current provider */
+                    }
+                    break;
+                }
                 if (!frame.ok) {
                     setNotice(`command failed: ${frame.for}${frame.detail ? ` — ${frame.detail}` : ''}`);
                 }
@@ -239,10 +327,14 @@ async function runAttach(nodeId, observer) {
     const done = new Promise((r) => {
         resolveDone = r;
     });
+    let asksTimer;
     const teardown = (reason) => {
         if (tornDown)
             return;
         tornDown = true;
+        if (asksTimer !== undefined)
+            clearInterval(asksTimer);
+        graphOverlay.close();
         clearPaneTag();
         removeKeyListener();
         // A clean detach tells the broker to drop this viewer (the engine runs on);
@@ -264,6 +356,53 @@ async function runAttach(nodeId, observer) {
         }
         resolveDone();
     };
+    // The handshake the viewer sends on connect AND on every successful redial.
+    const sendHello = () => {
+        socket.send({
+            type: 'hello',
+            role: observer ? 'observer' : 'controller',
+            client_id: clientId,
+            term: { cols: process.stdout.columns ?? 80, rows: process.stdout.rows ?? 24 },
+        });
+    };
+    // Reconnect supervisor. A resident broker node that yields EXITS its broker
+    // (socket close) and is revived FRESH by the daemon on the SAME `view.sock`
+    // path within a few seconds. So on close we HOLD the pane and re-dial while
+    // the canvas-db row says the node is still alive (status active/idle), giving
+    // up only when it is genuinely terminal (done/dead/canceled or row gone) or a
+    // bounded ~30s of failed redials elapses (stale-row safety). A successful
+    // redial re-sends `hello`; the new broker's `welcome` runs applySnapshot,
+    // which resetChat()s the pane and rebuilds from the persisted .jsonl — a clean
+    // "clear + continuation" for free.
+    const RECONNECT_GIVEUP_MS = 30_000;
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    let reconnecting = false;
+    const attemptReconnect = async () => {
+        reconnecting = true;
+        setNotice('↻ node refreshing — reconnecting…');
+        const deadline = Date.now() + RECONNECT_GIVEUP_MS;
+        let delay = 200;
+        while (!tornDown && Date.now() < deadline) {
+            if (reconnectShouldGiveUp(getRow(nodeId))) {
+                break; // genuinely gone → fall through to broker-gone
+            }
+            try {
+                await socket.redial();
+                reconnecting = false;
+                sendHello();
+                setNotice('');
+                return; // reconnected; the welcome snapshot clears + continues the pane
+            }
+            catch {
+                // ENOENT (socket not recreated yet) / ECONNREFUSED (listen not ready) → retry.
+                await sleep(Math.min(delay, 1000));
+                delay *= 2;
+            }
+        }
+        reconnecting = false;
+        if (!tornDown)
+            teardown('broker-gone');
+    };
     // Permanent socket wiring (the connect-race listeners are gone).
     socket.on('frame', handleBrokerFrame);
     socket.on('error', (err) => {
@@ -271,7 +410,13 @@ async function runAttach(nodeId, observer) {
         // broker-gone message prefers this over the generic text.
         lastSocketError = err.message;
     });
-    socket.on('close', () => teardown('broker-gone'));
+    socket.on('close', () => {
+        if (tornDown)
+            return; // a real detach/signal already won
+        if (reconnecting)
+            return; // the dead socket's own close during the redial loop
+        void attemptReconnect();
+    });
     // ctrl+c / ctrl+d → detach (T6 left these unwired; lifecycle is ours). A
     // global TUI input listener fires BEFORE the focused component (and before any
     // dialog overlay), so detach is unconditional and consistent.
@@ -280,6 +425,13 @@ async function runAttach(nodeId, observer) {
             teardown('detach');
             return { consume: true };
         }
+        // alt+g toggles the GRAPH overlay. The global listener fires BEFORE the
+        // focused component, so this works whether the editor or the overlay holds
+        // focus (closing it from inside the overlay too).
+        if (matchesKey(data, 'alt+g')) {
+            graphOverlay.toggle();
+            return { consume: true };
+        }
         return undefined;
     });
     // Pane kill / daemon teardown arrives as a signal (raw mode swallows ctrl+c as
@@ -291,17 +443,33 @@ async function runAttach(nodeId, observer) {
     // 8. Lay out, focus the editor, start, then handshake. Starting before the
     //    handshake means the welcome's applySnapshot renders into a live TUI.
     tui.addChild(chatContainer);
-    tui.addChild(footer);
+    tui.addChild(badge);
+    tui.addChild(managers);
     tui.addChild(editor);
+    tui.addChild(reports);
+    tui.addChild(footer);
     tui.setFocus(editor);
     renderFooter();
+    renderBadge();
+    renderPanels();
     tui.start();
-    socket.send({
-        type: 'hello',
-        role: observer ? 'observer' : 'controller',
-        client_id: clientId,
-        term: { cols: process.stdout.columns ?? 80, rows: process.stdout.rows ?? 24 },
-    });
+    sendHello();
+    // Low-rate canvas-chrome refresh: repaint panels/overlay from canvas.db (child
+    // status flips emit no broker event) and re-poll the ask map asynchronously.
+    const ASKS_POLL_MS = 5_000;
+    const pollChrome = () => {
+        refreshChrome();
+        fetchAsksAsync(climbRoot(nodeId), (counts) => {
+            if (JSON.stringify(counts) !== JSON.stringify(asksMap)) {
+                asksMap = counts;
+                refreshChrome();
+            }
+        });
+    };
+    pollChrome();
+    asksTimer = setInterval(pollChrome, ASKS_POLL_MS);
+    if (typeof asksTimer.unref === 'function')
+        asksTimer.unref();
     await done;
 }
 // ---------------------------------------------------------------------------

package/dist/clients/attach/canvas-panels.d.ts

@@ -0,0 +1,10 @@
+export interface CanvasPanelLines {
+    /** Above-editor manager line(s) — empty for a root node (no manager). */
+    managers: string[];
+    /** Below-editor report row(s) + self's trailing ⚑ asks line — empty when none. */
+    reports: string[];
+}
+/** Build the BASE panel line stacks for `nodeId` from canvas.db (ported verbatim
+ *  from canvas-nav.ts renderBase). `asks` is the per-node pending-ask map the
+ *  caller polls; pass `{}` to omit the ⚑ badges. */
+export declare function buildCanvasPanelLines(nodeId: string, asks: Record<string, number>): CanvasPanelLines;

package/dist/clients/attach/canvas-panels.js

@@ -0,0 +1,50 @@
+// canvas-panels.ts — the subscribed-node panel for `crtr attach` (Unit Q).
+//
+// Native reimplementation of canvas-nav.ts's BASE chrome (renderBase), reading
+// the subscription graph DIRECTLY from canvas.db via the shared nav-model layer
+// (no pi extension host, no broker frame). Produces the two line stacks the
+// viewer paints into Containers around the editor:
+//   managers  → ABOVE the editor: this node's manager (its first subscriber).
+//   reports   → BELOW the editor: this node's live reports (active|idle
+//               subscriptions), plus a trailing ⚑ line for self's own asks.
+//
+// Pure: given a node id + the per-node ask map it returns ANSI strings; the
+// caller owns the Containers and the refresh trigger. beginFrame() memoizes the
+// canvas.db reads for this one build pass (mirrors canvas-nav's per-frame cache),
+// so a whole panel rebuild is a single fan-out of disk/db reads.
+import { beginFrame, cNode, managerOf, liveReports, climbRoot, computeSubtreeActivity, navLabel, coloredGlyph, truncate, tokensCell, cycleBadge, childBadge, liveBelowBadge, askBadge, activityCell, DIM, RESET, YELLOW, } from '../../core/canvas/nav-model.js';
+/** Build the BASE panel line stacks for `nodeId` from canvas.db (ported verbatim
+ *  from canvas-nav.ts renderBase). `asks` is the per-node pending-ask map the
+ *  caller polls; pass `{}` to omit the ⚑ badges. */
+export function buildCanvasPanelLines(nodeId, asks) {
+    // Fresh snapshot: drop the previous build's memoized reads so this pass sees
+    // current disk+db state, then read-once within it.
+    beginFrame();
+    // One subtree-activity pass (rooted at the ancestry root) feeds the ⇣N
+    // live-work-below badge on both the manager line and every report row.
+    const activity = computeSubtreeActivity(climbRoot(nodeId), nodeId);
+    const managers = [];
+    const mgr = managerOf(nodeId);
+    if (mgr !== undefined) {
+        const mn = cNode(mgr);
+        const name = navLabel(mn, mgr);
+        managers.push(truncate(`↑ ${name} ${coloredGlyph(mn)} ${DIM}${mn?.kind ?? ''}${RESET} ${DIM}${tokensCell(mgr)}${RESET}${cycleBadge(mn)}${childBadge(mn)}${liveBelowBadge(mn, activity.activeBelow)}${askBadge(mgr, asks)}${activityCell(mgr, mn)}`));
+    }
+    const reports = [];
+    const live = liveReports(nodeId);
+    if (live.length > 0) {
+        const nameW = Math.min(20, Math.max(...live.map((id) => navLabel(cNode(id), id).length)));
+        for (const id of live) {
+            const n = cNode(id);
+            const name = navLabel(n, id).padEnd(nameW);
+            const kind = `${DIM}${(n?.kind ?? '').padEnd(6)}${RESET}`;
+            const tokens = `${DIM}${tokensCell(id).padStart(5)}${RESET}`;
+            reports.push(truncate(`  ${coloredGlyph(n)} ${name} ${kind} ${tokens}${cycleBadge(n)}${childBadge(n)}${liveBelowBadge(n, activity.activeBelow)}${askBadge(id, asks)}${activityCell(id, n)}`));
+        }
+    }
+    // Self's own pending asks (no self row in BASE) → a trailing inline line.
+    const selfAsks = asks[nodeId] ?? 0;
+    if (selfAsks > 0)
+        reports.push(`${YELLOW}⚑${selfAsks}${RESET}`);
+    return { managers, reports };
+}

package/dist/clients/attach/graph-overlay.d.ts

@@ -0,0 +1,34 @@
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+export declare class GraphOverlay implements Component {
+    private readonly tui;
+    private readonly self;
+    private readonly getAsks;
+    private handle;
+    /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
+     *  both override the default activity-driven policy and survive open/close. */
+    private readonly userExpanded;
+    private readonly userCollapsed;
+    private readonly folds;
+    /** Cursor as a node id (indices shift as topology changes). */
+    private cursorId;
+    /** Viewport scroll offset (row index of the top visible tree row). */
+    private scrollTop;
+    /** Transient y/n confirm gate (kill). */
+    private pendingConfirm;
+    constructor(tui: TUI, self: string, getAsks: () => Record<string, number>);
+    isOpen(): boolean;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    /** Repaint if shown (the low-rate ask poll calls this). */
+    refresh(): void;
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    private dispatch;
+    /** Swap `id` into THIS viewer's tmux pane (mirrors canvas browse's return-pane
+     *  shell). Default --pane is the caller TMUX_PANE; we pass it explicitly when
+     *  set so the focus lands here even if env resolution differs. */
+    private focusTarget;
+    private shellCrtr;
+}