@crouton-kit/crouter 0.3.70 → 0.3.78

package/dist/core/__tests__/host-teardown-process-group.test.js

@@ -62,7 +62,7 @@
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createHarness } from './helpers/harness.js';
@@ -180,9 +180,20 @@ async function spawnBrokerWithSharedGroupDescendant(tag, descendantScript = 'sle
     if (leader.pid == null)
         throw new Error('failed to spawn fake broker leader');
     trackPid(leader.pid);
-    await h.waitFor(() => existsSync(pidFile), { label: `${tag}: descendant pid file written` });
-    const descendantPid = Number.parseInt(readFileSync(pidFile, 'utf8').trim(), 10);
-    assert.ok(Number.isInteger(descendantPid) && descendantPid > 0, `${tag}: parsed a real descendant pid`);
+    const descendantPid = await h.waitFor(() => {
+        try {
+            const record = readFileSync(pidFile, 'utf8');
+            if (!/^\d+\n$/.test(record))
+                return false;
+            const pid = Number(record.slice(0, -1));
+            return Number.isSafeInteger(pid) && pid > 0 ? pid : false;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }, { label: `${tag}: valid descendant pid written` });
     trackPid(descendantPid);
     await h.waitFor(() => isPidAlive(descendantPid), { label: `${tag}: descendant alive before teardown` });
     return { leaderPid: leader.pid, descendantPid };

package/dist/core/__tests__/stream-watchdog.test.d.ts

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

package/dist/core/__tests__/stream-watchdog.test.js

@@ -0,0 +1,70 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/stream-watchdog.test.ts
+//
+// Unit-level contract test for StreamWatchdog (see stream-watchdog.ts): a
+// single-timer dead-man's switch the broker pokes while a turn awaits the
+// provider (disarmed during tool execution) and clears at agent_end. This
+// locks the class's arm/clear/single-fire/token contract directly — no broker
+// or fake-engine harness needed (that integration surface is deliberately out
+// of scope; see
+// the roadmap's Fix 3 test-scope note).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { StreamWatchdog } from '../runtime/stream-watchdog.js';
+const MS = 30;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+test('poke() arms the watchdog, firing once after ms with no further poke', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    assert.equal(calls, 0, 'must not fire before ms elapses');
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'must fire exactly once after ms with no further poke');
+});
+test('repeated pokes rearm the deadline from the LAST poke, not the first', async () => {
+    // A cancel-without-reschedule bug (clear the old timer but never arm a new
+    // one) would also "never fire while poked", so proving no-fire mid-stream is
+    // not enough. Prove the deadline actually REARMS: no fire around the original
+    // deadline, then exactly one fire measured from the FINAL poke.
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    // Re-poke well inside the window, several times, always resetting the clock.
+    // The last poke lands at ~t=2.5*MS, so the original t=MS deadline must pass
+    // with no fire.
+    for (let i = 0; i < 5; i++) {
+        await sleep(MS / 2);
+        wd.poke(0);
+    }
+    assert.equal(calls, 0, 'no fire around the original deadline — each poke rearmed it');
+    // From the final poke the timer must still be armed and fire exactly once.
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'exactly one fire, measured from the final poke — proves rearming');
+});
+test('clear() after poke prevents firing', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    wd.clear();
+    await sleep(MS * 2);
+    assert.equal(calls, 0, 'a cleared watchdog must never fire');
+});
+test('fires exactly once even if left armed well past ms', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    await sleep(MS * 5);
+    assert.equal(calls, 1, 'must fire only once, not repeatedly, past the deadline');
+});
+test('onStall receives the token of the arm that fired (generation binding)', async () => {
+    // The broker stamps each poke with the current session generation and no-ops
+    // a stall whose token is stale. This pins that the token travels with the
+    // arm: a re-poke supersedes the prior token, so a fire after a rebind carries
+    // the NEW generation — and an old timer that somehow survived would deliver
+    // the OLD one, which the broker guard rejects.
+    const tokens = [];
+    const wd = new StreamWatchdog((token) => tokens.push(token), MS);
+    wd.poke(1);
+    wd.poke(2); // supersedes generation 1 before it can fire
+    await sleep(MS * 2);
+    assert.deepEqual(tokens, [2], 'exactly one fire, carrying the most-recent arm\'s token');
+});

package/dist/core/__tests__/tmux-surface.test.js

@@ -18,8 +18,11 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, basename } from 'node:path';
+import { installTmuxBindings } from '../runtime/tmux-chrome.js';
+import { resolveKeybindings } from '../keybindings/index.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SRC_ROOT = join(__dirname, '..', '..'); // .../src
 const TMUX_TS = join(SRC_ROOT, 'core', 'runtime', 'tmux.ts');
@@ -113,3 +116,72 @@ test('§5.1 lint: only placement.ts / tmux-chrome.ts import the tmux driver', ()
         .map((f) => f.slice(SRC_ROOT.length + 1));
     assert.deepEqual(offenders, [], `modules importing tmux.ts directly: ${offenders.join(', ')}`);
 });
+function isolatedTmux(socket, args) {
+    const result = spawnSync('tmux', ['-S', socket, ...args], { encoding: 'utf8' });
+    return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+function tmuxBinding(socket, table, key) {
+    const result = isolatedTmux(socket, ['list-keys', '-T', table]);
+    if (result.status !== 0)
+        return null;
+    return result.stdout.split('\n').find((line) => {
+        const match = line.match(/^bind-key\s+(?:-r\s+)?-T\s+\S+\s+(\S+)\s+/);
+        return match?.[1] === key;
+    }) ?? null;
+}
+test('tmux installer remaps owned pairs and preserves occupied user bindings', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-keybindings-${process.pid}-${Date.now()}`;
+    const boot = spawnSync('tmux', ['-L', name, 'new-session', '-d', '-s', 'test'], { encoding: 'utf8' });
+    assert.equal(boot.status, 0, boot.stderr);
+    const socketResult = spawnSync('tmux', ['-L', name, 'display-message', '-p', '#{socket_path}'], { encoding: 'utf8' });
+    const socket = socketResult.stdout.trim();
+    assert.notEqual(socket, '');
+    const priorTmux = process.env['TMUX'];
+    process.env['TMUX'] = `${socket},1,0`;
+    try {
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'M-]', 'run-shell', `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`]);
+        const first = installTmuxBindings(resolveKeybindings());
+        assert.equal(first.ok, true, JSON.stringify(first.diagnostics));
+        assert.ok(first.installed.some((pair) => pair.table === 'root' && pair.key === 'M-]'));
+        assert.match(tmuxBinding(socket, 'root', 'M-c') ?? '', /display-menu/);
+        assert.match(tmuxBinding(socket, 'root', 'M-v') ?? '', /switch-client/);
+        const remapped = installTmuxBindings(resolveKeybindings({
+            'crtr.tmux.menu.open': ['alt+shift+z'],
+            'crtr.tmux.menu.graph': ['shift+z'],
+            'crtr.tmux.node.next': [],
+            'crtr.tmux.view.next': ['alt+z > n'],
+            'crtr.tmux.view.previous': ['alt+z > p'],
+        }));
+        assert.equal(remapped.ok, true, JSON.stringify(remapped.diagnostics));
+        assert.equal(tmuxBinding(socket, 'root', 'M-c'), null);
+        assert.equal(tmuxBinding(socket, 'root', 'M-]'), null);
+        const menu = tmuxBinding(socket, 'root', 'M-Z') ?? '';
+        assert.match(menu, /graph view/);
+        assert.match(menu, /Z/);
+        const prefix = tmuxBinding(socket, 'root', 'M-z') ?? '';
+        assert.match(prefix, /switch-client/);
+        const again = installTmuxBindings(resolveKeybindings({
+            'crtr.tmux.menu.open': ['alt+shift+y'],
+            'crtr.tmux.node.next': [],
+            'crtr.tmux.view.next': ['alt+z > n'],
+            'crtr.tmux.view.previous': ['alt+z > p'],
+        }));
+        assert.equal(again.ok, true, JSON.stringify(again.diagnostics));
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'M-Z', 'display-message', 'user-owned']);
+        const occupied = installTmuxBindings(resolveKeybindings({ 'crtr.tmux.menu.open': ['alt+shift+z'] }));
+        assert.equal(occupied.ok, true);
+        assert.ok(occupied.diagnostics.some((diagnostic) => diagnostic.code === 'occupied' && diagnostic.bindingId === 'crtr.tmux.menu.open'));
+        assert.match(tmuxBinding(socket, 'root', 'M-Z') ?? '', /user-owned/);
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        isolatedTmux(socket, ['kill-server']);
+    }
+});

package/dist/core/canvas/browse/__tests__/model.test.js

@@ -108,20 +108,38 @@ test('pruneNode: absent id is a no-op', () => {
     assert.equal(t.nodes.size, before);
 });
 // ── tab predicates ───────────────────────────────────────────────────────────
-test('tabPredicate: All / Live / Dormant / Flagged', () => {
-    assert.deepEqual([...TABS], ['All', 'Live', 'Dormant', 'Flagged']);
+test('tabPredicate: All / Live / Dormant / Attention / Pinned', () => {
+    assert.deepEqual([...TABS], ['All', 'Live', 'Dormant', 'Attention', 'Pinned']);
     const active = ROWS[0]; // root1 active
     const idle = ROWS[1]; // child-a idle
     const done = ROWS[2]; // grand-x done
-    const flagged = ROWS[3]; // child-b active asks 2
+    const attention = ROWS[3]; // child-b active asks 2
     assert.equal(tabPredicate('All', done), true);
     assert.equal(tabPredicate('Live', active), true);
     assert.equal(tabPredicate('Live', idle), true);
     assert.equal(tabPredicate('Live', done), false);
     assert.equal(tabPredicate('Dormant', done), true);
     assert.equal(tabPredicate('Dormant', active), false);
-    assert.equal(tabPredicate('Flagged', flagged), true);
-    assert.equal(tabPredicate('Flagged', active), false);
+    // Attention = pending asks OR a fault.
+    assert.equal(tabPredicate('Attention', attention), true);
+    assert.equal(tabPredicate('Attention', active), false);
+    assert.equal(tabPredicate('Attention', { ...active, asks: 0, hanging: { kind: 'provider' } }), true);
+    // Pinned reads the isPinned arg, not the row.
+    assert.equal(tabPredicate('Pinned', active), false);
+    assert.equal(tabPredicate('Pinned', active, true), true);
+});
+// ── flatten: pins ────────────────────────────────────────────────────────────
+test('flatten: Pinned tab shows only pinned rows', () => {
+    const pinned = new Set(['child-c']);
+    const v = flatten(tree(), { collapsed: new Set(), tab: 'Pinned', query: '', pinned });
+    // child-c is directly matched; root2 rides along as its ancestor (context).
+    const matched = v.filter((r) => r.matched).map((r) => r.id);
+    assert.deepEqual(matched, ['child-c']);
+});
+test('flatten: pinned rows float to the top in a flat sort', () => {
+    const pinned = new Set(['lonely']); // an idle straggler that would otherwise sort late
+    const v = flatten(tree(), { collapsed: new Set(), tab: 'All', query: '', sort: 'recency', pinned });
+    assert.equal(v[0].id, 'lonely');
 });
 // ── flatten: collapse / expand ───────────────────────────────────────────────
 const allCollapsed = () => new Set(['root1', 'child-a', 'root2']); // every node with children

package/dist/core/canvas/browse/__tests__/render.test.js

@@ -37,6 +37,7 @@ function state(over = {}) {
         sort: 'tree',
         preview: false,
         residentsOnly: false,
+        pinned: new Set(),
         ...over,
     };
 }

package/dist/core/canvas/browse/app.js

@@ -15,6 +15,7 @@ import { RemoteCanvasSource } from '../remote-canvas-source.js';
 import { closeNode } from '../../runtime/close.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, pruneNode, TABS } from './model.js';
+import { loadPins, savePins } from './pins.js';
 import { createCoalescedRebuilder } from './rebuild-coalescer.js';
 // Sort cycle for the `s` key. Starts on the default `attention` ordering; one `s`
 // press restores the structural `tree` view, then relevance/recency, then back.
@@ -23,10 +24,10 @@ import { renderFrame, detectColorCaps, headerHeight, PREVIEW_HEIGHT } from './re
 /** Viewport (body) height = total rows minus the header renderFrame draws (see
  *  render.ts headerHeight), the footer, and the preview panel when shown. Kept
  *  in lockstep with render.ts via the shared headerHeight/PREVIEW_HEIGHT. */
-function viewportHeight(rowsTotal, search, previewOn) {
+function viewportHeight(rowsTotal, inputLine, previewOn) {
     const rows = Math.max(8, rowsTotal);
     const previewH = previewOn ? PREVIEW_HEIGHT : 0;
-    return Math.max(1, rows - headerHeight(search) - 1 /* footer */ - previewH);
+    return Math.max(1, rows - headerHeight(inputLine) - 1 /* footer */ - previewH);
 }
 /** Wires a RemoteEventStream's `nodes`/`inbox` events through the coalescer
  *  (`rebuild-coalescer.ts`) so a burst of SSE events collapses to ONE rebuild
@@ -103,6 +104,14 @@ export async function runBrowse(opts = {}) {
         preview: true, // default ON (decision)
         residentsOnly: true, // default ON: hide one-shot workers (decision)
         pendingClose: null,
+        pinned: loadPins(),
+        help: false,
+        rename: false,
+        renameBuf: '',
+        renameTarget: null,
+        message: false,
+        messageBuf: '',
+        messageTarget: null,
     };
     let visible = [];
     // The DashboardRow ref the tree holds for a visible id. Enrichment mutates this
@@ -193,6 +202,7 @@ export async function runBrowse(opts = {}) {
             cwdScope: state.cwdScope,
             residentsOnly: state.residentsOnly,
             sort: state.sort,
+            pinned: state.pinned,
         });
         if (keepId !== undefined) {
             const idx = visible.findIndex((v) => v.id === keepId);
@@ -207,7 +217,8 @@ export async function runBrowse(opts = {}) {
     const flush = async () => {
         const size = getTerminalSize();
         const previewOn = state.preview && visible.length > 0;
-        const viewport = viewportHeight(size.rows, state.search, previewOn);
+        const inputMode = state.search || state.rename || state.message;
+        const viewport = viewportHeight(size.rows, inputMode, previewOn);
         // Keep the cursor inside the viewport window.
         if (state.cursor < state.scrollOffset)
             state.scrollOffset = state.cursor;
@@ -238,6 +249,9 @@ export async function runBrowse(opts = {}) {
             query: state.query, search: state.search, totalNodes,
             cwdScope: state.cwdScope, sort: state.sort, preview: state.preview,
             residentsOnly: state.residentsOnly, pendingClose: state.pendingClose,
+            pinned: state.pinned, help: state.help,
+            rename: state.rename, renameBuf: state.renameBuf,
+            message: state.message, messageBuf: state.messageBuf,
             readOnly: isRemote,
         }, size, caps);
         process.stdout.write(frame);
@@ -419,6 +433,102 @@ export async function runBrowse(opts = {}) {
             scheduleSearchRepaint();
         }
     };
+    // Recenter the cursor on the launching node (CRTR_NODE_ID), expanding its
+    // ancestors so it is actually visible. No-op outside a node or when it's filtered
+    // out of the current tab/scope. Same move the boot performs, on demand (`.`).
+    const recenterOnSelf = () => {
+        const selfId = process.env['CRTR_NODE_ID'];
+        if (selfId === undefined || selfId === '' || !tree.nodes.has(selfId))
+            return;
+        for (let p = tree.nodes.get(selfId)?.parentId ?? null; p !== null; p = tree.nodes.get(p)?.parentId ?? null) {
+            state.collapsed.delete(p);
+        }
+        recompute(selfId);
+    };
+    // Toggle the pin on a node: mutate the in-memory set, persist best-effort, and
+    // recompute so it floats (flat sorts) / (dis)appears from the Pinned tab.
+    const togglePin = (id) => {
+        if (state.pinned.has(id))
+            state.pinned.delete(id);
+        else
+            state.pinned.add(id);
+        savePins(state.pinned);
+        recompute(id);
+    };
+    // Commit an inline rename: `crtr node config <id> --name <name>` (also renames a
+    // live viewer window), then reflect the new name into the snapshot in place.
+    const commitRename = () => {
+        const id = state.renameTarget;
+        const name = state.renameBuf.trim();
+        state.rename = false;
+        if (id !== null && name !== '') {
+            try {
+                execFileSync('crtr', ['node', 'config', id, '--name', name], { stdio: 'ignore' });
+            }
+            catch {
+                /* best-effort — a rename failure never wedges the picker */
+            }
+            const n = tree.nodes.get(id);
+            if (n !== undefined)
+                n.row.name = name;
+        }
+        recompute(state.renameTarget ?? undefined);
+        scheduleFlush();
+    };
+    // Commit an inline message: `crtr node msg --to <id> <body>` (immediate inbox
+    // delivery, best-effort revive if dormant). Fire-and-forget — browse stays put.
+    const commitMessage = () => {
+        const id = state.messageTarget;
+        const body = state.messageBuf.trim();
+        state.message = false;
+        if (id !== null && body !== '') {
+            try {
+                execFileSync('crtr', ['node', 'msg', '--to', id, body], { stdio: 'ignore' });
+            }
+            catch {
+                /* best-effort — delivery failure never wedges the picker */
+            }
+        }
+        scheduleFlush();
+    };
+    // Shared text-input keystroke handling for the rename/message sub-modes: Esc
+    // cancels, Enter commits, Backspace deletes, Ctrl+C quits, printable chars append.
+    const onKeyText = (input, key, get, set, commit, cancel) => {
+        if (key.escape) {
+            cancel();
+            return;
+        }
+        if (key.return) {
+            commit();
+            return;
+        }
+        if (key.backspace) {
+            set(get().slice(0, -1));
+            scheduleFlush();
+            return;
+        }
+        if (key.ctrl) {
+            if (input === 'c')
+                quit();
+            return;
+        }
+        const printable = [...input].filter((c) => c >= ' ').join('');
+        if (printable.length > 0) {
+            set(get() + printable);
+            scheduleFlush();
+        }
+    };
+    const onKeyRename = (input, key) => onKeyText(input, key, () => state.renameBuf, (s) => { state.renameBuf = s; }, commitRename, () => { state.rename = false; scheduleFlush(); });
+    const onKeyMessage = (input, key) => onKeyText(input, key, () => state.messageBuf, (s) => { state.messageBuf = s; }, commitMessage, () => { state.message = false; scheduleFlush(); });
+    // Help overlay: any key dismisses (Ctrl+C still quits outright).
+    const onKeyHelp = (input, key) => {
+        if (key.ctrl && input === 'c') {
+            quit();
+            return;
+        }
+        state.help = false;
+        scheduleFlush();
+    };
     const onKeyNav = (input, key) => {
         // Ctrl-combos first: only Ctrl+C is meaningful (quit); swallow the rest so
         // Ctrl+L / Ctrl+J / Ctrl+Q etc. don't masquerade as l/j/q commands.
@@ -519,7 +629,7 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        if (input >= '1' && input <= '4') {
+        if (input >= '1' && input <= '5') {
             const idx = Number(input) - 1;
             if (idx < TABS.length) {
                 state.tab = TABS[idx];
@@ -569,6 +679,49 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
+        // Help overlay.
+        if (input === '?') {
+            state.help = true;
+            scheduleFlush();
+            return;
+        }
+        // Pin / unpin (local, view-only — works against a remote canvas too).
+        if (input === 'f') {
+            if (row !== undefined)
+                togglePin(row.id);
+            scheduleFlush();
+            return;
+        }
+        // Recenter on the launching node.
+        if (input === '.') {
+            recenterOnSelf();
+            scheduleFlush();
+            return;
+        }
+        // Rename the node inline (mutation — no-op on a remote canvas).
+        if (input === 'R') {
+            if (isRemote)
+                return;
+            if (row !== undefined) {
+                state.rename = true;
+                state.renameTarget = row.id;
+                state.renameBuf = rowOf(row.id)?.name ?? '';
+            }
+            scheduleFlush();
+            return;
+        }
+        // Message the node without resuming it (mutation — no-op on a remote canvas).
+        if (input === 'm') {
+            if (isRemote)
+                return;
+            if (row !== undefined) {
+                state.message = true;
+                state.messageTarget = row.id;
+                state.messageBuf = '';
+            }
+            scheduleFlush();
+            return;
+        }
         // Search. Starting a search ranks by relevance (decision) so the best prompt/
         // name match floats to the top as you type.
         if (input === '/') {
@@ -664,8 +817,14 @@ export async function runBrowse(opts = {}) {
         const onData = (data) => {
             try {
                 const { input, key } = parseKeypress(data);
-                if (state.search)
+                if (state.help)
+                    onKeyHelp(input, key);
+                else if (state.search)
                     onKeySearch(input, key);
+                else if (state.rename)
+                    onKeyRename(input, key);
+                else if (state.message)
+                    onKeyMessage(input, key);
                 else
                     onKeyNav(input, key);
             }

package/dist/core/canvas/browse/model.d.ts

@@ -1,6 +1,6 @@
 import type { DashboardRow } from '../render.js';
 import type { NodeStatus } from '../types.js';
-export type Tab = 'All' | 'Live' | 'Dormant' | 'Flagged';
+export type Tab = 'All' | 'Live' | 'Dormant' | 'Attention' | 'Pinned';
 export declare const TABS: readonly Tab[];
 /** How the visible rows are ordered.
  *    tree      — spanning-tree order, ancestors shown for context (the default).
@@ -11,11 +11,12 @@ export declare const TABS: readonly Tab[];
 export type SortMode = 'tree' | 'attention' | 'relevance' | 'recency';
 export declare const SORTS: readonly SortMode[];
 /** Does a node belong to this tab's slice?
- *    All      — every node.
- *    Live     — active | idle.
- *    Dormant  — done | dead | canceled.
- *    Flagged  — has > 0 pending human asks. */
-export declare function tabPredicate(tab: Tab, row: DashboardRow): boolean;
+ *    All       — every node.
+ *    Live      — active | idle.
+ *    Dormant   — done | dead | canceled.
+ *    Attention — needs a human: has pending asks OR is parked on a fault.
+ *    Pinned    — user-starred (a local, view-only preference; `isPinned`). */
+export declare function tabPredicate(tab: Tab, row: DashboardRow, isPinned?: boolean): boolean;
 export interface TreeNode {
     row: DashboardRow;
     depth: number;
@@ -138,6 +139,9 @@ export interface FlattenOpts {
     /** Ordering. `tree` keeps the spanning tree + ancestor context; `relevance` /
      *  `recency` produce a FLAT ranked list of directly-matched rows. */
     sort?: SortMode;
+    /** User-starred node ids (local, view-only). Gates the Pinned tab, and floats
+     *  pinned rows to the top of every FLAT sort mode. undefined = none pinned. */
+    pinned?: Set<string>;
 }
 /** Is this row inside the active cwd scope? No scope (null/undefined) = All dirs. */
 export declare function cwdMatch(scope: string | null | undefined, row: DashboardRow): boolean;

package/dist/core/canvas/browse/model.js

@@ -4,19 +4,21 @@
 // it is exhaustively unit-testable. The app layer (app.ts) wires the canvas data
 // access (dashboardRowsAll / listNodes / subscriptionsOf) into buildTree, then
 // drives flatten() on each keystroke.
-export const TABS = ['All', 'Live', 'Dormant', 'Flagged'];
+export const TABS = ['All', 'Live', 'Dormant', 'Attention', 'Pinned'];
 export const SORTS = ['tree', 'attention', 'relevance', 'recency'];
 /** Does a node belong to this tab's slice?
- *    All      — every node.
- *    Live     — active | idle.
- *    Dormant  — done | dead | canceled.
- *    Flagged  — has > 0 pending human asks. */
-export function tabPredicate(tab, row) {
+ *    All       — every node.
+ *    Live      — active | idle.
+ *    Dormant   — done | dead | canceled.
+ *    Attention — needs a human: has pending asks OR is parked on a fault.
+ *    Pinned    — user-starred (a local, view-only preference; `isPinned`). */
+export function tabPredicate(tab, row, isPinned = false) {
     switch (tab) {
         case 'All': return true;
         case 'Live': return row.status === 'active' || row.status === 'idle';
         case 'Dormant': return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
-        case 'Flagged': return row.asks > 0;
+        case 'Attention': return row.asks > 0 || row.hanging != null;
+        case 'Pinned': return isPinned;
     }
 }
 /** Sort rank for roots/stragglers — live first (active, then idle), dormant
@@ -383,7 +385,8 @@ export function lifecycleMatch(residentsOnly, row) {
  * always reachable.
  */
 export function flatten(tree, opts) {
-    const { collapsed, tab, query, cwdScope, residentsOnly, sort = 'tree' } = opts;
+    const { collapsed, tab, query, cwdScope, residentsOnly, sort = 'tree', pinned } = opts;
+    const isPinned = (id) => pinned?.has(id) === true;
     // 1. Directly-matched nodes: tab predicate AND cwd scope AND lifecycle AND query.
     //    `matched` honors the residents-only filter (drives top-level rows, ancestor
     //    context, force-expand, and the flat search results below). `matchedAll` is
@@ -394,7 +397,7 @@ export function flatten(tree, opts) {
     const matched = new Set();
     const matchedAll = new Set();
     for (const [id, node] of tree.nodes) {
-        if (tabPredicate(tab, node.row) && cwdMatch(cwdScope, node.row) && queryMatch(query, node.row)) {
+        if (tabPredicate(tab, node.row, isPinned(id)) && cwdMatch(cwdScope, node.row) && queryMatch(query, node.row)) {
             matchedAll.add(id);
             if (lifecycleMatch(residentsOnly, node.row))
                 matched.add(id);
@@ -407,21 +410,26 @@ export function flatten(tree, opts) {
         const ids = [...matched];
         const createdOf = (id) => tree.nodes.get(id)?.row.created ?? '';
         const byRecency = (a, b) => createdOf(b).localeCompare(createdOf(a));
+        // Pinned rows float above everything in every flat mode — "keep this at the
+        // top of my list" is the whole point of a pin. Ordering WITHIN each pin tier
+        // still follows the active sort.
+        const pinRank = (id) => (isPinned(id) ? 0 : 1);
         if (sort === 'attention') {
             // Tiered (attached/streaming/live first), newest-message-first within tier.
             const rowOf = (id) => tree.nodes.get(id).row;
-            ids.sort((a, b) => (attentionTier(rowOf(a)) - attentionTier(rowOf(b))) ||
+            ids.sort((a, b) => (pinRank(a) - pinRank(b)) ||
+                (attentionTier(rowOf(a)) - attentionTier(rowOf(b))) ||
                 (attentionMtime(rowOf(b)) - attentionMtime(rowOf(a))) ||
                 byRecency(a, b));
         }
         else if (sort === 'recency' || query === '') {
-            ids.sort(byRecency);
+            ids.sort((a, b) => (pinRank(a) - pinRank(b)) || byRecency(a, b));
         }
         else {
             const score = new Map();
             for (const id of ids)
                 score.set(id, scoreRow(query, tree.nodes.get(id).row));
-            ids.sort((a, b) => (score.get(b) - score.get(a)) || byRecency(a, b));
+            ids.sort((a, b) => (pinRank(a) - pinRank(b)) || (score.get(b) - score.get(a)) || byRecency(a, b));
         }
         return ids.map((id) => ({ id, depth: 0, hasChildren: false, collapsed: false, matched: true }));
     }

package/dist/core/canvas/browse/pins.d.ts

@@ -0,0 +1,4 @@
+/** Load the pinned-id set. Missing/garbage file → empty set (never throws). */
+export declare function loadPins(): Set<string>;
+/** Persist the pinned-id set. Best-effort — a write failure never wedges the TUI. */
+export declare function savePins(pins: Set<string>): void;

package/dist/core/canvas/browse/pins.js

@@ -0,0 +1,29 @@
+// pins.ts — the durable per-user "pinned" set for the canvas browser.
+//
+// A pin is a LOCAL, view-only preference, NOT a canvas property: starring a node
+// keeps it at the top of YOUR navigator across sessions and machines, and it works
+// against a remote canvas too (you are pinning in your own view, mutating nothing
+// on the canvas). Stored as a flat id list at ~/.crouter/browse-pins.json so every
+// `canvas browse` invocation shares it regardless of cwd/scope. Read once at boot,
+// mutated in memory, written best-effort on each toggle.
+import { join } from 'node:path';
+import { userScopeRoot } from '../../scope.js';
+import { readJsonIfExists, atomicWriteJson } from '../../fs-utils.js';
+const PINS_FILE = 'browse-pins.json';
+function pinsPath() {
+    return join(userScopeRoot(), PINS_FILE);
+}
+/** Load the pinned-id set. Missing/garbage file → empty set (never throws). */
+export function loadPins() {
+    const raw = readJsonIfExists(pinsPath());
+    return new Set(Array.isArray(raw) ? raw.filter((x) => typeof x === 'string') : []);
+}
+/** Persist the pinned-id set. Best-effort — a write failure never wedges the TUI. */
+export function savePins(pins) {
+    try {
+        atomicWriteJson(pinsPath(), [...pins]);
+    }
+    catch {
+        /* best-effort: a pin that doesn't survive the session is a minor loss */
+    }
+}