@north-light/crouter 0.3.154

package/dist/clients/attach/__tests__/titled-editor-preview.test.js

@@ -0,0 +1,271 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CURSOR_MARKER, visibleWidth } from '@earendil-works/pi-tui';
+import { RefAwareAutocompleteProvider } from '../input/ref-autocomplete.js';
+import { compactLoadedCommandPreview, TitledEditor } from '../input/titled-editor.js';
+const REF_STYLE_ON = '\x1b[4m\x1b[2m';
+const REF_STYLE_OFF = '\x1b[24m\x1b[22m';
+function stripAnsi(s) {
+    return s
+        .split(CURSOR_MARKER)
+        .join('')
+        .replace(/\x1b\[[0-9;]*m/g, '')
+        .replace(/\x1b\][^\x07]*\x07/g, '');
+}
+function makeEditor(rows = 24) {
+    const tui = { requestRender: () => { }, terminal: { rows } };
+    const theme = { borderColor: (s) => s, selectList: {} };
+    const keybindings = { matches: () => false };
+    return new TitledEditor(tui, theme, keybindings);
+}
+test('loaded command disclosure stays bounded and points to the full inspector', () => {
+    const lines = compactLoadedCommandPreview(Array.from({ length: 20 }, (_, i) => `instruction ${i}`).join('\n'), 32);
+    assert.equal(lines.length, 8);
+    assert.match(lines.at(-1), /truncated · inspect/);
+    assert.ok(lines.every((line) => visibleWidth(line) <= 32));
+});
+test('short loaded command disclosure is not decorated as truncated', () => {
+    assert.deepEqual(compactLoadedCommandPreview('one\ntwo', 32), ['one', 'two']);
+});
+test('inline disclosure strips hostile terminal controls while inspector text stays raw', () => {
+    const lines = compactLoadedCommandPreview('safe\x1b[2J\x1b]8;;https://evil.example\x07link\x1b]8;;\x07\u0000', 32);
+    const visible = lines.join('\n');
+    assert.match(visible, /safelink/);
+    assert.doesNotMatch(visible, /\x1b|\u0000|evil\.example/);
+});
+test('inline disclosure bounds huge work before wrapping and suppresses below usable inspect width', () => {
+    const lines = compactLoadedCommandPreview('x'.repeat(1_000_000), 32);
+    assert.equal(lines.length, 8);
+    assert.match(lines.at(-1), /inspect/);
+    assert.deepEqual(compactLoadedCommandPreview('ordinary prompt', 20), []);
+});
+test('down exhausts native editor movement and prompt history before yielding to the roster', { timeout: 1_000 }, () => {
+    const tui = { requestRender: () => { }, terminal: { rows: 24 } };
+    const theme = { borderColor: (s) => s, selectList: {} };
+    const keybindings = {
+        matches: (data, binding) => binding === 'tui.editor.cursorDown' && data === '\x1b[B',
+    };
+    const editor = new TitledEditor(tui, theme, keybindings);
+    const internals = editor;
+    let boundaryHits = 0;
+    editor.onCursorDownAtBottom = () => { boundaryHits++; };
+    editor.setText('this editor line is deliberately long enough to wrap several times');
+    editor.render(20);
+    internals.state.cursorLine = 0;
+    internals.state.cursorCol = 0;
+    editor.handleInput('\x1b[B');
+    assert.ok(editor.getCursor().col > 0, 'a wrapped visual line consumes ↓');
+    assert.equal(boundaryHits, 0);
+    editor.setText('short line');
+    editor.render(20);
+    internals.state.cursorCol = 2;
+    editor.handleInput('\x1b[B');
+    assert.equal(editor.getCursor().col, editor.getText().length, 'the last visual line first moves to its end');
+    assert.equal(boundaryHits, 0);
+    editor.handleInput('\x1b[B');
+    assert.equal(boundaryHits, 1, 'only the true editor bottom yields to the roster');
+    editor.addToHistory('previous prompt');
+    editor.setText('');
+    editor.render(20);
+    editor.handleInput('\x1b[A');
+    assert.equal(editor.getText(), 'previous prompt', '↑ opens the prior submitted prompt');
+    editor.handleInput('\x1b[B');
+    assert.equal(editor.getText(), '', '↓ returns from history to the draft');
+    assert.equal(boundaryHits, 1, 'history navigation consumes ↓ before the roster');
+});
+test('resolved-ref candidates are underlined; unknown or boundary-invalid strings are untouched', () => {
+    const editor = makeEditor();
+    editor.setResolvedRefNames(['dev', 'taste/foo']);
+    const text = 'check /dev. and /taste:foo and /nope and http://x and and/or';
+    editor.setText(`placeholder\n${text}`);
+    const internals = editor;
+    internals.state.cursorLine = 0;
+    internals.state.cursorCol = 0;
+    const lines = editor.render(80);
+    const body = lines[2]; // border(0) + placeholder(1) + the ref line(2)
+    assert.equal(stripAnsi(body).trimEnd(), text, 'decoration never alters the visible text');
+    assert.ok(body.includes(`${REF_STYLE_ON}/dev${REF_STYLE_OFF}`), 'trailing punctuation is trimmed from the highlighted span');
+    assert.ok(body.includes(`${REF_STYLE_ON}/taste:foo${REF_STYLE_OFF}`), 'nested taste/foo highlights as its colon surface form');
+    const onCount = body.split(REF_STYLE_ON).length - 1;
+    assert.equal(onCount, 2, 'unknown (/nope) and boundary-invalid (http://x, and/or) strings get no decoration at all');
+});
+test("decoration never changes a rendered line's visible width", () => {
+    const width = 40;
+    const texts = [
+        'ünïcödé prefix /dev then more text that wraps across the available width for sure',
+        'short /dev line',
+    ];
+    for (const text of texts) {
+        const plain = makeEditor();
+        const decorated = makeEditor();
+        decorated.setResolvedRefNames(['dev']);
+        plain.setText(text);
+        decorated.setText(text);
+        const linesPlain = plain.render(width);
+        const linesDecorated = decorated.render(width);
+        assert.equal(linesDecorated.length, linesPlain.length, `line count parity for: ${text}`);
+        for (let i = 0; i < linesPlain.length; i++) {
+            assert.equal(visibleWidth(linesDecorated[i]), visibleWidth(linesPlain[i]), `line ${i} width parity for: ${text}`);
+        }
+    }
+});
+test('cursor sweep across a resolved ref decorates outside the cursor cell and safely degrades inside it', () => {
+    const text = 'go /dev now';
+    // span for /dev is [3,7); decorated everywhere the cursor's own reverse-video
+    // cell doesn't touch or straddle it (see decorateRow's before/after-cursor math).
+    const decoratedCols = new Set([0, 1, 2, 7, 8, 9, 10, 11]);
+    for (const paneFocused of [true, false]) {
+        const editor = makeEditor();
+        editor.setResolvedRefNames(['dev']);
+        editor.focused = true; // component (TUI) focus controls CURSOR_MARKER emission
+        editor.paneFocused = paneFocused; // terminal-pane focus controls solid vs muted cursor styling
+        editor.setText(text);
+        const internals = editor;
+        for (let col = 0; col <= text.length; col++) {
+            internals.state.cursorLine = 0;
+            internals.state.cursorCol = col;
+            const lines = editor.render(60);
+            const body = lines[1];
+            assert.equal(stripAnsi(body).trimEnd(), text, `text intact at col ${col} paneFocused=${paneFocused}`);
+            const hasCursorMarkup = body.includes('\x1b[7m') || body.includes('\x1b[48;5;240m');
+            assert.ok(hasCursorMarkup, `cursor cell present at col ${col} paneFocused=${paneFocused}`);
+            const decorated = body.includes(REF_STYLE_ON);
+            assert.equal(decorated, decoratedCols.has(col), `decoration at col ${col} paneFocused=${paneFocused}`);
+        }
+    }
+});
+test('chrome (loaded-command disclosure, title/info border, mode/context badge) never carries ref decoration', () => {
+    const editorA = makeEditor();
+    const editorB = makeEditor();
+    for (const editor of [editorA, editorB]) {
+        editor.title = 'session';
+        editor.info = 'cwd-info';
+        editor.mode = 'plan';
+        editor.contextBadge = 'node-1';
+        editor.loadedCommand = { name: 'dev', content: 'do the thing', inspectHint: 'ctrl+i' };
+        editor.setText('please use /dev to continue');
+    }
+    editorB.setResolvedRefNames(['dev']);
+    const linesA = editorA.render(60);
+    const linesB = editorB.render(60);
+    assert.equal(linesA.length, linesB.length, 'decoration never adds or removes lines');
+    let diffCount = 0;
+    let diffIndex = -1;
+    for (let i = 0; i < linesA.length; i++) {
+        if (linesA[i] !== linesB[i]) {
+            diffCount++;
+            diffIndex = i;
+        }
+    }
+    assert.equal(diffCount, 1, 'decoration touches exactly the one content row carrying the ref, nothing else');
+    assert.ok(linesB[diffIndex].includes(REF_STYLE_ON), 'the differing row is in fact the decorated one');
+});
+test('terminal suppression combines a trimmed local-command rule and a separate untrimmed engine-command rule (Minor 10)', () => {
+    const editor = makeEditor();
+    editor.setResolvedRefNames(['dev']);
+    // The LOCAL viewer rule is checked against TRIMMED text (mirrors
+    // slash/dispatch.ts's own `text.trim()`-based dispatch parse) — leading
+    // whitespace is tolerated.
+    editor.setLocalCommandNames(['dev']);
+    editor.setText('  /dev something /dev');
+    assert.ok(!editor.render(60)[1].includes(REF_STYLE_ON), 'local-command rule suppresses even with leading whitespace (trimmed rule)');
+    // The SAME leading-whitespace text is NOT suppressed by the ENGINE rule —
+    // it mirrors the broker's own `isLeadingEngineCommand`, which requires the
+    // RAW text itself (no trim) to start with '/'.
+    editor.setLocalCommandNames([]);
+    editor.setEngineCommandNames(['dev']);
+    assert.ok(editor.render(60)[1].includes(REF_STYLE_ON), 'engine rule does not tolerate leading whitespace — decoration is not suppressed');
+    // Without leading whitespace the engine (untrimmed) rule suppresses too.
+    editor.setText('/dev something /dev');
+    assert.ok(!editor.render(60)[1].includes(REF_STYLE_ON), 'engine rule suppresses once the raw text itself starts with /');
+    editor.setEngineCommandNames([]);
+    assert.ok(editor.render(60)[1].includes(REF_STYLE_ON), 'decoration resumes once neither the local nor the engine rule matches');
+});
+test('Enter-confirming a non-leading ref completion accepts the token and returns to editing, never submits (Major 3)', async () => {
+    const editor = makeEditor();
+    editor.focused = true;
+    let submitted;
+    editor.onSubmit = (text) => {
+        submitted = text;
+    };
+    const refs = [{ name: 'dev', kind: 'knowledge', scope: 'user', shortForm: 'dev docs' }];
+    const delegate = {
+        async getSuggestions() {
+            return null;
+        },
+        applyCompletion(lines, cursorLine, cursorCol) {
+            return { lines, cursorLine, cursorCol };
+        },
+    };
+    editor.setAutocompleteProvider(new RefAwareAutocompleteProvider(refs, delegate));
+    editor.setText('hey check /d');
+    editor.handleInput('e'); // completes the typed prefix to '/de', triggering the non-leading bridge
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    assert.equal(editor.isShowingAutocomplete(), true, 'the ref suggestion popup is open');
+    editor.handleInput('\r'); // real Enter keystroke — tui.select.confirm
+    assert.equal(editor.isShowingAutocomplete(), false, 'Enter closes the popup');
+    assert.equal(editor.getText(), 'hey check /dev', 'the token was replaced in place, not submitted as typed');
+    assert.equal(submitted, undefined, 'Enter-confirming a ref completion must never submit the message');
+});
+test('a real Enter submission preserves raw leading/trailing whitespace end-to-end (Major 4)', () => {
+    const editor = makeEditor();
+    let submitted;
+    editor.onSubmit = (text) => {
+        submitted = text;
+    };
+    editor.setText('  hello world  ');
+    editor.handleInput('\r'); // real Enter keystroke — tui.input.submit
+    assert.equal(submitted, '  hello world  ', 'onSubmit receives the exact untrimmed text, not the base editor\'s trimmed copy');
+    assert.equal(editor.getText(), '', 'submitValue still resets editor state as usual');
+});
+test('a resolved ref wider than the editor renders plain, without corrupting width', () => {
+    const name = 'x'.repeat(40);
+    const width = 20;
+    const plain = makeEditor();
+    const decorated = makeEditor();
+    decorated.setResolvedRefNames([name]);
+    plain.setText(`/${name}`);
+    decorated.setText(`/${name}`);
+    const linesPlain = plain.render(width);
+    const linesDecorated = decorated.render(width);
+    assert.deepEqual(linesDecorated, linesPlain, 'a span that never fits inside one wrapped chunk is left entirely undecorated');
+});
+test('a non-leading ref-grammar character triggers autocomplete without an explicit Tab', async () => {
+    const editor = makeEditor();
+    editor.focused = true;
+    const calls = [];
+    const provider = {
+        async getSuggestions(_lines, cursorLine, cursorCol) {
+            calls.push({ cursorLine, cursorCol });
+            const item = { value: 'dev', label: '/dev' };
+            return { items: [item], prefix: '/' };
+        },
+        applyCompletion(lines, cursorLine, cursorCol) {
+            return { lines, cursorLine, cursorCol };
+        },
+    };
+    editor.setAutocompleteProvider(provider);
+    editor.setText('hey check ');
+    editor.handleInput('/');
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    assert.equal(calls.length, 1, 'the bridge triggers exactly one suggestion request');
+    assert.equal(calls[0].cursorCol, 'hey check /'.length);
+});
+test('a leading slash is unaffected by the trigger bridge (native path only, not doubled)', async () => {
+    const editor = makeEditor();
+    editor.focused = true;
+    const calls = [];
+    const provider = {
+        async getSuggestions() {
+            calls.push(1);
+            return null;
+        },
+        applyCompletion(lines, cursorLine, cursorCol) {
+            return { lines, cursorLine, cursorCol };
+        },
+    };
+    editor.setAutocompleteProvider(provider);
+    editor.handleInput('/');
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    assert.equal(calls.length, 1, 'exactly one trigger from the native leading path, not doubled by the bridge');
+});

package/dist/clients/attach/__tests__/visible-paths.test.d.ts

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

package/dist/clients/attach/__tests__/visible-paths.test.js

@@ -0,0 +1,19 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { checkReviewableFile, extractFilePaths } from '../visible-paths.js';
+test('extractFilePaths finds existing paths, strips positions, and deduplicates', () => {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-visible-paths-'));
+    const file = join(root, 'example.ts');
+    writeFileSync(file, 'export {};\n');
+    assert.deepEqual(extractFilePaths([`${file}:12:3 and again ${file}`], root), [file]);
+});
+test('checkReviewableFile rejects non-files and binary text', () => {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-reviewable-file-'));
+    const binary = join(root, 'binary.dat');
+    writeFileSync(binary, Buffer.from([0x61, 0, 0x62]));
+    assert.deepEqual(checkReviewableFile(root), { ok: false, reason: 'not a file' });
+    assert.deepEqual(checkReviewableFile(binary), { ok: false, reason: 'file is not UTF-8 text' });
+});

package/dist/clients/attach/chrome/bash-jobs.d.ts

@@ -0,0 +1,9 @@
+import { type BashJobStatus } from '../../../core/bash-jobs.js';
+/** Compact cockpit row: the running command (or job count) plus elapsed time.
+ *  `undefined` for an empty list — the caller omits the row entirely. */
+export declare function bashJobsWaitSummary(jobs: readonly BashJobStatus[], nowMs?: number): string | undefined;
+/** Readable drill-in document for the tmux detail surface. Watch-only — no
+ *  cancel line: the owning agent already received the exact `kill -- -<pgid>`
+ *  in its handoff notice, and persisting pgid to add a human stop affordance is
+ *  a separable future addition (measuring-stick restraint). */
+export declare function renderBashJobsDetails(jobs: readonly BashJobStatus[], nowMs?: number): string;

package/dist/clients/attach/chrome/bash-jobs.js

@@ -0,0 +1,43 @@
+// chrome/bash-jobs.ts — the attach-side formatter pair for live backgrounded bash
+// jobs (R3 of the Alt+C -> b bash handoff refinements design), mirroring
+// chrome/cron-wait.ts: a compact one-row cockpit summary and a read-only markdown
+// detail document. Pure — takes the already-scanned job list, never touches
+// disk itself (that's activeBackgroundBashJobs' job, in core/bash-jobs.ts).
+import { formatBashElapsed } from '../../../core/bash-jobs.js';
+const CMD_CELL_CAP = 26;
+/** First line of `command`, whitespace-collapsed and capped to ~26 chars. */
+function cmdCell(command) {
+    const oneLine = command.split('\n')[0].replace(/\s+/g, ' ').trim();
+    return oneLine.length > CMD_CELL_CAP ? `${oneLine.slice(0, CMD_CELL_CAP - 1)}…` : oneLine;
+}
+/** Compact cockpit row: the running command (or job count) plus elapsed time.
+ *  `undefined` for an empty list — the caller omits the row entirely. */
+export function bashJobsWaitSummary(jobs, nowMs = Date.now()) {
+    if (jobs.length === 0)
+        return undefined;
+    if (jobs.length === 1) {
+        const job = jobs[0];
+        return `${cmdCell(job.command)} · ${formatBashElapsed(nowMs - job.startedAtMs)}`;
+    }
+    const oldest = jobs[0]; // activeBackgroundBashJobs returns oldest-first
+    return `${jobs.length} bash jobs · oldest ${formatBashElapsed(nowMs - oldest.startedAtMs)}`;
+}
+/** Readable drill-in document for the tmux detail surface. Watch-only — no
+ *  cancel line: the owning agent already received the exact `kill -- -<pgid>`
+ *  in its handoff notice, and persisting pgid to add a human stop affordance is
+ *  a separable future addition (measuring-stick restraint). */
+export function renderBashJobsDetails(jobs, nowMs = Date.now()) {
+    const lines = [
+        '# Background bash jobs',
+        '',
+        `${jobs.length} bash job${jobs.length === 1 ? '' : 's'} running in the background.`,
+    ];
+    for (const job of jobs) {
+        lines.push('', `## ⚙ ${cmdCell(job.command)}`, '');
+        lines.push(`- **Elapsed:** ${formatBashElapsed(nowMs - job.startedAtMs)} · started ${new Date(job.startedAtMs).toISOString()}`);
+        lines.push(`- **Log:** \`${job.logPath}\``);
+        lines.push(`- **Watch:** \`tail -f ${job.logPath}\``);
+        lines.push('', '### Command', '', '```bash', job.command, '```');
+    }
+    return `${lines.join('\n')}\n`;
+}

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

@@ -0,0 +1,36 @@
+import type { CanvasSource } from '../../../core/canvas/source.js';
+import type { CronDTO } from '../../../api/dto/crons.js';
+import type { BashJobStatus } from '../../../core/bash-jobs.js';
+import type { AttachPalette } from '../config.js';
+export type CanvasPanelItem = {
+    key: string;
+    kind: 'node';
+    nodeId: string;
+    line: string;
+} | {
+    key: 'human';
+    kind: 'human';
+    line: string;
+} | {
+    key: 'bash';
+    kind: 'bash';
+    line: string;
+} | {
+    key: 'crons';
+    kind: 'crons';
+    line: string;
+};
+export interface CanvasPanelLines {
+    /** Below-editor relationship and wait rows, in render order. */
+    reports: string[];
+    /** Node ids backing relationship rows. Retained for graph/remote callers. */
+    reportIds: string[];
+    /** Actionable cockpit rows. Enter swaps nodes or opens the matching wait detail surface. */
+    items: CanvasPanelItem[];
+}
+/** Build the BASE panel line stacks for `nodeId`. `asks` is the per-node
+ *  pending human-ticket count map the caller polls (deck/review/notify); pass
+ *  `{}` to omit the ⚑ badges. `crons` are this node's armed schedules.
+ *  `palette`
+ *  drives the headers + dim cells; omit it and the panels render uncolored. */
+export declare function buildCanvasPanelLines(nodeId: string, asks: Record<string, number>, palette: AttachPalette | undefined, source: CanvasSource, crons?: readonly CronDTO[], jobs?: readonly BashJobStatus[]): Promise<CanvasPanelLines>;

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

@@ -0,0 +1,172 @@
+// chrome/canvas-panels.ts — the subscribed-node panel for `crtr surface attach` (Unit Q).
+//
+// Reads through the CanvasSource seam so the viewer chrome and graph overlay
+// share the same canvas read authority. Produces the line stacks the viewer paints
+// into Containers around the editor:
+//   reports   → BELOW the editor: this node's manager (↑), its live
+//               (↓, active|idle) reports, and trailing wait rows for human
+//               tickets, live background bash jobs, and armed crons. Backs
+//               inline scroll+open/swap.
+//
+// Pure: given a node id + the per-node ticket-count map it returns ANSI strings; the
+// caller owns the Containers and the refresh trigger. beginFrameTelem() clears the
+// nav-model telemetry cache for this one build pass so token/activity cells are
+// read fresh for every chrome frame.
+import { beginFrameTelem, navLabel, nodeGlyph, truncate, tokensCell, cycleBadge, askBadge, activityCell, YELLOW, RESET, DIM, GREEN, } from '../../../core/canvas/nav-render.js';
+import { RemoteCanvasSource } from '../../../core/canvas/remote-canvas-source.js';
+import { cronWaitSummary } from './cron-wait.js';
+import { bashJobsWaitSummary } from './bash-jobs.js';
+/** Column widths for the aligned panel rows (visible columns). name is sized to
+ *  the widest label across BOTH panels (capped); kind is wide enough for the
+ *  longest persona kind (`orchestrator` = 12) so real kinds never truncate;
+ *  tokens is fixed. Both panels share one grid. */
+const KIND_W = 12;
+const TOK_W = 6;
+const NAME_CAP = 22;
+/** Pad to `w`, or ellipsize with `…` when longer (plain text — callers pass
+ *  un-styled labels). */
+function nameCell(s, w) {
+    return s.length > w ? `${s.slice(0, w - 1)}…` : s + ' '.repeat(w - s.length);
+}
+function padStartVisible(s, w) {
+    return s.length >= w ? s.slice(0, w) : ' '.repeat(w - s.length) + s;
+}
+/** Build the BASE panel line stacks for `nodeId`. `asks` is the per-node
+ *  pending human-ticket count map the caller polls (deck/review/notify); pass
+ *  `{}` to omit the ⚑ badges. `crons` are this node's armed schedules.
+ *  `palette`
+ *  drives the headers + dim cells; omit it and the panels render uncolored. */
+export async function buildCanvasPanelLines(nodeId, asks, palette, source, crons = [], jobs = []) {
+    // A remote source provides only graph structure + node metadata; tokens/
+    // activity/status-glyph adornments are local disk reads (telemetry.json,
+    // fault state, pid liveness) and are suppressed to safe defaults below —
+    // never read for a remote id, which may collide with a local one.
+    const remote = source instanceof RemoteCanvasSource;
+    beginFrameTelem();
+    const nodes = new Map();
+    const children = new Map();
+    const managersOf = new Map();
+    const node = (id) => {
+        const hit = nodes.get(id);
+        if (hit !== undefined)
+            return hit;
+        const p = source.getNode(id).catch(() => null);
+        nodes.set(id, p);
+        return p;
+    };
+    const convoChildIds = (id) => {
+        const hit = children.get(id);
+        if (hit !== undefined)
+            return hit;
+        const p = (async () => {
+            const refs = await source.subscriptionsOf(id).catch(() => []);
+            const out = [];
+            for (const ref of refs) {
+                if ((await node(ref.node_id))?.kind !== 'human')
+                    out.push(ref.node_id);
+            }
+            return out;
+        })();
+        children.set(id, p);
+        return p;
+    };
+    const managerOf = (id) => {
+        const hit = managersOf.get(id);
+        if (hit !== undefined)
+            return hit;
+        const p = source.subscribersOf(id).then((refs) => refs[0]?.node_id).catch(() => undefined);
+        managersOf.set(id, p);
+        return p;
+    };
+    const liveReports = async (id) => {
+        const out = [];
+        for (const cid of await convoChildIds(id)) {
+            const st = (await node(cid))?.status;
+            if (st === 'active' || st === 'idle')
+                out.push(cid);
+        }
+        return out;
+    };
+    const climbRoot = async (self) => {
+        let cur = self;
+        const seen = new Set([cur]);
+        for (;;) {
+            const mgr = await managerOf(cur);
+            if (mgr === undefined || seen.has(mgr))
+                break;
+            seen.add(mgr);
+            cur = mgr;
+        }
+        return cur;
+    };
+    const activeBelow = new Map();
+    const computeActivity = async (root) => {
+        const seen = new Set();
+        const visit = async (id) => {
+            const selfActive = (await node(id))?.status === 'active';
+            if (seen.has(id))
+                return selfActive ? 1 : 0;
+            seen.add(id);
+            let below = 0;
+            for (const c of await convoChildIds(id))
+                below += await visit(c);
+            activeBelow.set(id, below);
+            return below + (selfActive ? 1 : 0);
+        };
+        await visit(root);
+    };
+    const childBadgeFor = async (n) => {
+        if (n === null || n.mode !== 'orchestrator')
+            return '';
+        const m = (await convoChildIds(n.node_id)).length;
+        return m > 0 ? ` ${DIM}⤳${m}${RESET}` : '';
+    };
+    const liveBelowBadgeFor = (n) => {
+        if (n === null || n.status === 'active')
+            return '';
+        const count = activeBelow.get(n.node_id) ?? 0;
+        return count > 0 ? ` ${GREEN}⇣${count}${RESET}` : '';
+    };
+    const muted = palette?.muted ?? ((s) => s);
+    const faint = palette?.faint ?? ((s) => s);
+    await computeActivity(await climbRoot(nodeId));
+    const mgr = await managerOf(nodeId);
+    const live = await liveReports(nodeId);
+    // The directional rows share column widths in their single roster.
+    const gridIds = [...(mgr !== undefined ? [mgr] : []), ...live];
+    const gridNodes = await Promise.all(gridIds.map((id) => node(id)));
+    const nameW = gridIds.length > 0
+        ? Math.min(NAME_CAP, Math.max(...gridIds.map((id, i) => navLabel(gridNodes[i] ?? null, id).length)))
+        : NAME_CAP;
+    const row = async (id, direction) => {
+        const n = await node(id);
+        const name = nameCell(navLabel(n, id), nameW);
+        const kind = faint(nameCell(n?.kind ?? '', KIND_W));
+        const tokens = muted(padStartVisible(tokensCell(id, remote), TOK_W));
+        const badges = `${cycleBadge(n)}${await childBadgeFor(n)}${liveBelowBadgeFor(n)}${askBadge(id, asks)}${activityCell(id, n, remote)}`;
+        const line = ` ${direction} ${nodeGlyph(n, remote)} ${name}  ${kind} ${tokens}${badges}`;
+        return truncate(line);
+    };
+    const reportIds = [...(mgr !== undefined ? [mgr] : []), ...live];
+    const items = [];
+    if (mgr !== undefined)
+        items.push({ key: `node:${mgr}`, kind: 'node', nodeId: mgr, line: await row(mgr, '↑') });
+    for (const id of live)
+        items.push({ key: `node:${id}`, kind: 'node', nodeId: id, line: await row(id, '↓') });
+    const selfAsks = asks[nodeId] ?? 0;
+    if (selfAsks > 0)
+        items.push({ key: 'human', kind: 'human', line: ` ${YELLOW}⚑ waiting on human · ${selfAsks} pending${RESET}` });
+    // Bash wait row: attention (human) -> active-now (running background work) ->
+    // scheduled-future (armed crons). The leading glyph distinguishes the row type.
+    const bashSummary = bashJobsWaitSummary(jobs);
+    if (bashSummary !== undefined) {
+        const gear = palette ? palette.info('⚙') : '⚙';
+        items.push({ key: 'bash', kind: 'bash', line: ` ${gear} ${muted(`${bashSummary} · ↵ details`)}${RESET}` });
+    }
+    const cronSummary = cronWaitSummary(crons);
+    if (cronSummary !== undefined) {
+        const clock = palette ? palette.info('◷') : '◷';
+        items.push({ key: 'crons', kind: 'crons', line: ` ${clock} ${muted(`${cronSummary} · ↵ details`)}${RESET}` });
+    }
+    return { reports: items.map((item) => item.line), reportIds, items };
+}

package/dist/clients/attach/chrome/completion-bell.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Ring the completion bell once, if enabled. Picks the best available signal
+ * for the host:
+ *   macOS  → afplay a system sound (guaranteed audible, ignores terminal bell prefs)
+ *   Linux  → paplay/aplay if CRTR_BELL_SOUND is set, else the terminal BEL
+ *   other  → terminal BEL (0x07) — the terminal's own bell / tmux bell indicator
+ *
+ * Gated on the `completion_bell` config setting (default true).
+ */
+export declare function ringCompletionBell(): void;

package/dist/clients/attach/chrome/completion-bell.js

@@ -0,0 +1,89 @@
+// chrome/completion-bell.ts — the "your agent finished" dopamine ding.
+//
+// A port of the Claude Code Stop-hook bell into the crtr attach viewer. Rings
+// once when the node you are watching stops its turn and hands control back
+// (chat-view's `agent_end`). Scoped to the viewer on purpose: the bell is for
+// the human at the terminal, so it fires ONLY inside a live viewer pane. A
+// headless/background node with no viewer attached never constructs a ChatView
+// and is therefore always silent — there is no code path that rings for it.
+//
+// Best-effort and non-blocking: spawns a detached sound process (unref'd) and
+// swallows every error. A missing player just means silence — never a crash and
+// never a blocked render.
+//
+// Controlled by the `completion_bell` config setting (default true):
+//   crtr sys config set completion_bell --value false   # mute
+//   crtr sys config set completion_bell --value true    # unmute
+// Override the macOS sound with the CRTR_BELL_SOUND env var (an absolute path to
+// any afplay-able file, or a bare name from /System/Library/Sounds, e.g. `Ping`).
+import { spawn } from 'node:child_process';
+import { readConfig } from '../../../core/config.js';
+/** Default macOS system sound — a short, pleasant "done" chime. */
+const DEFAULT_MAC_SOUND = '/System/Library/Sounds/Glass.aiff';
+function macSoundPath() {
+    const override = process.env['CRTR_BELL_SOUND'];
+    if (override === undefined || override.trim() === '')
+        return DEFAULT_MAC_SOUND;
+    const v = override.trim();
+    // Absolute path → use as-is; bare name → resolve against the system sounds dir.
+    if (v.startsWith('/'))
+        return v;
+    return `/System/Library/Sounds/${v.replace(/\.aiff$/i, '')}.aiff`;
+}
+/** True when the completion bell is enabled. Read live from the user-scope
+ *  config each time (a single small JSON read on an infrequent turn-completion
+ *  boundary) so `sys config set completion_bell` takes effect without
+ *  restarting the viewer. Any read failure defaults to the built-in `true`. */
+function bellEnabled() {
+    try {
+        return readConfig('user').completion_bell;
+    }
+    catch {
+        return true;
+    }
+}
+/** Fire a detached, best-effort audio process. Never throws, never blocks. */
+function playDetached(command, args) {
+    try {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ring the completion bell once, if enabled. Picks the best available signal
+ * for the host:
+ *   macOS  → afplay a system sound (guaranteed audible, ignores terminal bell prefs)
+ *   Linux  → paplay/aplay if CRTR_BELL_SOUND is set, else the terminal BEL
+ *   other  → terminal BEL (0x07) — the terminal's own bell / tmux bell indicator
+ *
+ * Gated on the `completion_bell` config setting (default true).
+ */
+export function ringCompletionBell() {
+    if (!bellEnabled())
+        return;
+    try {
+        if (process.platform === 'darwin') {
+            if (playDetached('afplay', [macSoundPath()]))
+                return;
+        }
+        else if (process.platform === 'linux') {
+            const override = process.env['CRTR_BELL_SOUND'];
+            if (override !== undefined && override.trim() !== '') {
+                if (playDetached('paplay', [override.trim()]) || playDetached('aplay', [override.trim()]))
+                    return;
+            }
+        }
+        // Fallback everywhere: the terminal BEL. Non-printing control char — the
+        // terminal (and tmux) interpret it without moving the cursor or disturbing
+        // the TUI render.
+        process.stdout.write('\x07');
+    }
+    catch {
+        /* the bell is pure delight; never let it break a turn */
+    }
+}

package/dist/clients/attach/chrome/cron-wait.d.ts

@@ -0,0 +1,3 @@
+import type { CronDTO } from '../../../api/dto/crons.js';
+/** Compact cockpit row: state first; the native Inspector owns details. */
+export declare function cronWaitSummary(crons: readonly CronDTO[], nowMs?: number): string | undefined;