@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/core/__tests__/review-render-pane-regression.test.js

@@ -0,0 +1,133 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/review-render-pane-regression.test.ts
+//
+// BUG REGRESSION: `crtr human review` showed the human RAW markdown — literal
+// `:::callout{...}` / `#` / `**bold**` source — instead of the termrender-
+// rendered document the leaf help promises ("directive-flavored markdown
+// rendered by termrender (panels, columns, trees, callouts, mermaid)").
+//
+// Root cause: the review surface was ONLY the read-only nvim buffer. nvim must
+// show the raw source (anchored comments hang off source line/col numbers), and
+// `-u NONE` treesitter/render-markdown styling never interprets ::: directives —
+// so nothing anywhere rendered the doc. There was no termrender invocation in
+// the entire review path (crouter `_run` review branch + humanloop
+// launchReview): the managed venv binary was healthy and never asked.
+//
+// THE FIX (src/commands/human/queue.ts, `_run` review branch): open a live
+// termrender watch pane via humanloop `display()` BESIDE the editor, record its
+// pane id as `render_pane_id` on run.json (so `human cancel` can clear it), and
+// kill it in a `finally` when the editor exits. The editor keeps the raw
+// source; the human reads the rendered pane.
+//
+// This test drives the REAL `crtr human _run` worker (review mode) in a REAL
+// but isolated tmux session — no mocks — and asserts:
+//   (a) a second pane appears beside the editor running termrender on the file,
+//   (b) that pane's content is RENDERED ANSI (box-drawing panels), not raw `:::`,
+//   (c) run.json carries render_pane_id for the cancel path,
+//   (d) the render pane is torn down when the editor exits.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { hasTmux } from './helpers/harness.js';
+const CROUTER = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const CLI_SRC = join(CROUTER, 'src', 'cli.ts');
+const TSX_ESM = createRequire(import.meta.url).resolve('tsx/esm');
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    return { code: r.status ?? -1, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
+}
+function sessionPanes(session) {
+    const r = tmux(['list-panes', '-s', '-t', session, '-F', '#{pane_id}\t#{pane_current_command}']);
+    if (r.code !== 0)
+        return [];
+    return r.out
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => {
+        const [id, cmd] = l.split('\t');
+        return { id: id ?? '', cmd: cmd ?? '' };
+    });
+}
+function paneContent(paneId) {
+    return tmux(['capture-pane', '-p', '-t', paneId]).out;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function waitFor(fn, timeoutMs, label) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const v = fn();
+        if (v !== undefined)
+            return v;
+        if (Date.now() > deadline)
+            throw new Error(`timeout waiting for ${label}`);
+        await sleep(300);
+    }
+}
+const SKIP = !hasTmux();
+test('review-render-pane regression: `human _run` (review) opens a live termrender pane showing RENDERED panels, not raw ::: source', { skip: SKIP ? 'tmux unavailable' : false, timeout: 90_000 }, async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-review-render-'));
+    const session = `crtr-revrender-${process.pid}-${Date.now().toString(36)}`;
+    const mdPath = join(dir, 'doc.md');
+    // A directive doc: rendered output has box-drawing panels; raw output has `:::`.
+    writeFileSync(mdPath, '# Render check\n\n:::callout{type="info"}\nRENDER-MARKER body\n:::\n');
+    writeFileSync(join(dir, 'run.json'), JSON.stringify({ mode: 'review', job_id: '', file: mdPath, output: join(dir, 'feedback.json') }));
+    try {
+        // The worker runs the real `crtr human _run` from src via tsx, exactly the
+        // command shape detachHumanTui bakes into the spawned pane. job_id is ''
+        // so pushFinal is skipped (no canvas home needed) — the surface under
+        // test is the panes, not the report fan-out.
+        const workerCmd = `CRTR_HUMAN_DIR='${dir}' '${process.execPath}' --import '${TSX_ESM}' '${CLI_SRC}' human _run; sleep 120`;
+        const created = tmux(['new-session', '-d', '-s', session, '-x', '200', '-y', '50', workerCmd]);
+        assert.equal(created.code, 0, `create isolated session failed: ${created.err}`);
+        // (a) a SECOND pane appears: the termrender watch pane beside the editor.
+        const renderPane = await waitFor(() => {
+            const panes = sessionPanes(session);
+            if (panes.length < 2)
+                return undefined;
+            // The render pane is the one NOT hosting the editor/worker shell.
+            const candidates = panes.filter((p) => !/zsh|bash|sh|node|nvim|vim/i.test(p.cmd));
+            return candidates[0]?.id;
+        }, 30_000, 'termrender render pane to open');
+        // (b) its content is RENDERED: panel box-drawing present, raw ::: absent.
+        const rendered = await waitFor(() => {
+            const c = paneContent(renderPane);
+            return c.includes('RENDER-MARKER') ? c : undefined;
+        }, 30_000, 'rendered body to paint');
+        assert.ok(/[┌│└]/.test(rendered), `render pane draws panels (box chars): ${rendered.slice(0, 200)}`);
+        assert.ok(!rendered.includes(':::'), 'render pane does NOT show raw ::: directive source');
+        // (c) run.json carries render_pane_id so `human cancel` can clear the pane.
+        const rc = JSON.parse(readFileSync(join(dir, 'run.json'), 'utf8'));
+        assert.equal(rc.render_pane_id, renderPane, 'run.json records the render pane id');
+        // (d) editor exit (any quit submits) tears the render pane down. The
+        // editor pane is the OTHER pane (nvim runs as a child of the worker, so
+        // #{pane_current_command} may report node/zsh — match on its content:
+        // the read-only buffer shows the RAW ::: source).
+        const editorPane = await waitFor(() => {
+            const other = sessionPanes(session).find((p) => p.id !== renderPane);
+            if (other === undefined)
+                return undefined;
+            return paneContent(other.id).includes(':::') ? other.id : undefined;
+        }, 30_000, 'editor pane showing the raw source buffer');
+        tmux(['send-keys', '-t', editorPane, 'Space', 's']);
+        await waitFor(() => (existsSync(join(dir, 'feedback.json')) ? true : undefined), 30_000, 'feedback.json after submit');
+        await waitFor(() => (sessionPanes(session).some((p) => p.id === renderPane) ? undefined : true), 15_000, 'render pane to be killed after editor exit');
+    }
+    finally {
+        tmux(['kill-session', '-t', session]);
+        // The worker may still be flushing job files as it exits; retry the rm
+        // briefly so a write racing the first attempt can't fail the test.
+        for (let i = 0; i < 10; i++) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+                break;
+            }
+            catch {
+                await sleep(300);
+            }
+        }
+    }
+});

package/dist/core/__tests__/spawn-root.test.js

@@ -10,6 +10,7 @@ import { createNode, getNode, getRow, subscribersOf } from '../canvas/canvas.js'
 import { closeDb } from '../canvas/db.js';
 import { nodeDir } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
+import { resolveSpawner } from '../runtime/spawn.js';
 let home;
 function spawner(id) {
     return {
@@ -62,6 +63,15 @@ test('independent root: provenance only, no parent, no subscription', () => {
     assert.equal(meta.lifecycle, 'resident', 'a root is resident');
     assert.equal(subscribersOf(root.node_id).length, 0, 'nobody is subscribed to an independent root — the spawner is not woken by it');
 });
+test('resolveSpawner: a --root spawn needs no caller; a managed child does (regression)', () => {
+    // Bug-regression: `crtr node new --root` from a human shell (no CRTR_NODE_ID,
+    // no --parent) threw "spawnChild requires a calling node" even though a root
+    // has no spine parent and the spawner id is provenance only.
+    assert.equal(resolveSpawner(undefined, null, true), null, 'human root spawn: no caller is fine');
+    assert.equal(resolveSpawner(undefined, 'A', true), 'A', 'node root spawn: provenance recorded');
+    assert.equal(resolveSpawner('A', null, false), 'A', 'explicit parent satisfies a child spawn');
+    assert.throws(() => resolveSpawner(undefined, null, false), /requires a calling node/, 'a managed child with no caller still throws');
+});
 test('unknown parent: spawnNode throws and mints NO node dir / row (validate before create)', () => {
     // Pre-allocate the would-be id so we can prove nothing was scaffolded for it.
     const orphanId = 'orphan-under-ghost';

package/dist/core/__tests__/spike-harness.test.js

@@ -46,6 +46,7 @@ const CANVAS_ENV_KEYS = [
     'CRTR_NODE_ID',
     'CRTR_HOME',
     'CRTR_ROOT_SESSION',
+    'CRTR_SUBTREE',
     'CRTR_NODE_SESSION',
     'CRTR_PARENT_NODE_ID',
     'CRTR_FRONT_DOOR',

package/dist/core/__tests__/wake-bearings.test.d.ts

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

package/dist/core/__tests__/wake-bearings.test.js

@@ -0,0 +1,156 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/wake-bearings.test.ts
+//
+// Wake-origin self-knowledge (the <crtr-wake> provenance block). Regression
+// guard for the observed gap: a node woken or BORN by a scheduled TIMER could
+// not tell it came from a timer — a scheduled wake arrived indistinguishable
+// from an ordinary refresh/message (the Invariant B/D anti-goal). These lock:
+//   • buildWakeBearings renders the right decision-first block per wake kind /
+//     cadence, and never crashes when the armer was reaped (no resolved name);
+//   • the bare-wake revive kickoff carries that block (so a scheduled alarm is
+//     distinguishable from a generic context-refresh), placed AFTER the kickoff
+//     sentinel (goal-capture keys on it) and BEFORE the roadmap/disk bearings;
+//   • an ordinary fresh revive (no wakeReason) carries NO block.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { buildWakeBearings } from '../runtime/bearings.js';
+import { buildReviveKickoff, drainBearings, REVIVE_KICKOFF_SENTINEL, } from '../runtime/kickoff.js';
+let home;
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+const ARMED = '2026-06-08T13:30:00.000Z';
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-wake-bearings-'));
+    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'];
+});
+// --- buildWakeBearings: one per kind / cadence variant ----------------------
+test('spawn one-shot: names a deferred birth + the armer, and says it does not recur', () => {
+    const o = {
+        kind: 'spawn',
+        ownerId: 'arm-1',
+        ownerName: 'release-orch',
+        armedAt: ARMED,
+        recur: null,
+    };
+    const b = buildWakeBearings(o);
+    assert.ok(b.startsWith('<crtr-wake>') && b.endsWith('</crtr-wake>'));
+    assert.match(b, /BORN by a scheduled wake/);
+    assert.match(b, /deferred birth/);
+    // Armer named ROLE-explicitly so the newborn never reads the id as its own.
+    assert.match(b, /armed by node arm-1 \("release-orch"\)/);
+    assert.match(b, /only run, not a recurring job/);
+    assert.match(b, /Your task follows\./);
+});
+test('spawn cron: surfaces the cadence + frames it as one run of a standing job', () => {
+    const o = {
+        kind: 'spawn',
+        ownerId: 'arm-1',
+        ownerName: 'nightly',
+        armedAt: ARMED,
+        recur: JSON.stringify({ cron: '0 9 * * *', tz: 'America/New_York' }),
+    };
+    const b = buildWakeBearings(o);
+    assert.match(b, /recurring spawn-cron armed by node arm-1 \("nightly"\)/);
+    // The cadence renders via the shared cadenceDisplay (matches `wake list`).
+    assert.match(b, /firing cron `0 9 \* \* \*` \(America\/New_York\)/);
+    assert.match(b, /one run of a standing job, not a one-off/);
+    assert.match(b, /inherit nothing from prior runs but this task/);
+});
+test('spawn interval cron: renders the every-N cadence', () => {
+    const o = {
+        kind: 'spawn',
+        ownerId: 'arm-1',
+        ownerName: 'poller',
+        armedAt: ARMED,
+        recur: JSON.stringify({ every: '6h' }),
+    };
+    assert.match(buildWakeBearings(o), /firing every 6h/);
+});
+test('spawn with a reaped armer: renders the bare id, no name, never crashes', () => {
+    const o = {
+        kind: 'spawn',
+        ownerId: 'gone-9',
+        ownerName: undefined, // armer no longer exists → no resolved name
+        armedAt: ARMED,
+        recur: JSON.stringify({ every: '12h' }),
+    };
+    const b = buildWakeBearings(o);
+    assert.match(b, /armed by node gone-9 \(now gone\)/); // bare id, flagged reaped
+    assert.doesNotMatch(b, /\("/); // never an empty/dangling name
+});
+test('bare one-shot: frames a timed re-check, NOT a new request', () => {
+    const o = { kind: 'bare', ownerId: 'n1', ownerName: 'n1', armedAt: ARMED, recur: null };
+    const b = buildWakeBearings(o);
+    assert.match(b, /a scheduled alarm fired/);
+    assert.match(b, /a timer, NOT a new message or request/);
+    assert.match(b, /timed re-check, not a new task/);
+    assert.match(b, /re-read your roadmap/);
+    // No armer attribution on bare (could be `--node`-armed by another), no ISO.
+    assert.doesNotMatch(b, /you set/);
+    assert.doesNotMatch(b, new RegExp(ARMED));
+});
+test('bare recurring: frames one tick of a standing re-check + the cadence', () => {
+    const o = {
+        kind: 'bare',
+        ownerId: 'n1',
+        ownerName: 'n1',
+        armedAt: ARMED,
+        recur: JSON.stringify({ every: '6h' }),
+    };
+    const b = buildWakeBearings(o);
+    assert.match(b, /recurring scheduled alarm fired \(every 6h\)/);
+    assert.match(b, /one tick of a standing re-check/);
+});
+// --- the bare-wake revive seam (Seam 2) -------------------------------------
+test('a bare scheduled wake makes the fresh-revive kickoff distinguishable from a refresh', () => {
+    const id = 'b1';
+    const meta = createNode(node(id));
+    const wakeReason = {
+        kind: 'bare',
+        ownerId: id,
+        ownerName: id,
+        armedAt: ARMED,
+        recur: null,
+    };
+    const msg = buildReviveKickoff(meta, drainBearings(meta), wakeReason);
+    // The block is present, and the kickoff STILL starts with the sentinel that
+    // goal-capture keys on (so the prompt is never mistaken for a user mandate).
+    assert.ok(msg.startsWith(REVIVE_KICKOFF_SENTINEL), 'kickoff still leads with the sentinel');
+    assert.match(msg, /<crtr-wake>/);
+    assert.match(msg, /a scheduled alarm fired/);
+    // Placement: sentinel < <crtr-wake> < <roadmap> — "why you woke" precedes
+    // "what to rebuild from".
+    const iSentinel = msg.indexOf(REVIVE_KICKOFF_SENTINEL);
+    const iWake = msg.indexOf('<crtr-wake>');
+    const iRoadmap = msg.indexOf('<roadmap');
+    assert.ok(iSentinel === 0 && iSentinel < iWake && iWake < iRoadmap, 'block sits after sentinel, before roadmap');
+});
+test('an ordinary fresh revive (no wakeReason) carries NO wake block', () => {
+    const id = 'b2';
+    const meta = createNode(node(id));
+    const msg = buildReviveKickoff(meta, drainBearings(meta));
+    assert.doesNotMatch(msg, /<crtr-wake>/);
+});

package/dist/core/__tests__/wake-origin.test.d.ts

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

package/dist/core/__tests__/wake-origin.test.js

@@ -0,0 +1,110 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/wake-origin.test.ts
+//
+// Wake-origin self-knowledge at the DAEMON FIRING seams (the other half of the
+// regression — wake-bearings.test.ts covers the pure block + the bare-revive
+// kickoff). The observed gap: a scheduled wake arrived indistinguishable from an
+// ordinary message/spawn (Invariant D). These lock the daemon's third pass:
+//   • noted  — the delivered inbox label carries the ⏰ scheduled-wake marker, so
+//     a timed note is distinguishable from a plain `node msg` (no tmux needed).
+//   • spawn  — a node BORN by a spawn wake gets the <crtr-wake> block prepended
+//     to its kickoff prompt (naming the armer + cadence); an ordinary `node new`
+//     spawn does NOT. The headline. (tmux-gated integration via the harness.)
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createNode } from '../canvas/canvas.js';
+import { armWake } from '../canvas/wakeups.js';
+import { closeDb } from '../canvas/db.js';
+import { readInboxSince } from '../feed/inbox.js';
+import { superviseTick } from '../../daemon/crtrd.js';
+import { hasTmux, createHarness } from './helpers/harness.js';
+const CROUTER = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent: null,
+    };
+}
+// --- noted seam (no tmux) ---------------------------------------------------
+let home;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-wake-origin-'));
+    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'];
+});
+test('a noted scheduled wake delivers a ⏰-marked inbox label, distinct from a plain message', async () => {
+    const armer = createNode(node('armer'));
+    const target = createNode(node('tgt')); // no tmux placement → pass 1 skips it
+    armWake({
+        wakeup_id: 'wk-noted-1',
+        node_id: target.node_id,
+        owner_id: armer.node_id,
+        fire_at: new Date(Date.now() - 1000).toISOString(),
+        kind: 'noted',
+        recur: null,
+        payload: { body: 'CI should be green by now — check it', label: 'check CI' },
+    });
+    closeDb();
+    await superviseTick(Date.now());
+    closeDb();
+    const entries = readInboxSince(target.node_id);
+    assert.equal(entries.length, 1, 'the noted wake delivered exactly one inbox entry');
+    // Invariant D: the timer signal rides the VISIBLE label (digests never surface
+    // arbitrary data keys), so this is distinguishable from a plain `node msg`.
+    assert.equal(entries[0].label, '⏰ scheduled wake — check CI');
+    assert.notEqual(entries[0].label, 'check CI', 'a plain message would carry the bare label');
+});
+// --- spawn seam (the headline; tmux-gated integration) ----------------------
+test('a spawn scheduled wake births a node whose kickoff carries <crtr-wake>; node new does NOT', { skip: hasTmux() ? false : 'tmux unavailable' }, async () => {
+    const h = await createHarness();
+    try {
+        const armer = h.spawnRoot('armer');
+        // Contrast: an ordinary `node new` spawn — its kickoff has NO wake block.
+        const plainChild = await h.spawnChild(armer, 'plain task');
+        const plainBoot = await h.awaitBoot(plainChild);
+        assert.doesNotMatch(plainBoot.prompt ?? '', /<crtr-wake>/, 'node new carries no wake block');
+        // Arm a recurring spawn-cron (detached), fire one tick, inspect the BORN
+        // node's kickoff prompt (the message it actually wakes on).
+        const before = new Set(readdirSync(join(h.home, 'nodes')));
+        armWake({
+            wakeup_id: 'wk-spawn-1',
+            node_id: null, // canvas-detached deferred birth
+            owner_id: armer,
+            fire_at: new Date(Date.now() - 1000).toISOString(),
+            kind: 'spawn',
+            recur: JSON.stringify({ every: '6h' }),
+            payload: { kind: 'general', cwd: CROUTER, prompt: 'do the recurring job', parent: armer },
+        });
+        await h.tick(Date.now());
+        const born = readdirSync(join(h.home, 'nodes')).filter((d) => !before.has(d));
+        assert.equal(born.length, 1, 'exactly one node born from the spawn wake');
+        const bornBoot = await h.awaitBoot(born[0]);
+        const prompt = bornBoot.prompt ?? '';
+        assert.match(prompt, /<crtr-wake>/, 'the born node learns a timer birthed it');
+        assert.match(prompt, /recurring spawn-cron armed by node /, 'names the armer role-explicitly');
+        assert.match(prompt, /firing every 6h/, 'surfaces the cadence');
+        assert.match(prompt, new RegExp(armer), 'the still-alive armer is named');
+        assert.match(prompt, /do the recurring job/, 'the real task follows the block');
+    }
+    finally {
+        await h.dispose();
+    }
+});

package/dist/core/bootstrap.js

@@ -30,7 +30,7 @@ const BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
 function bootSkillBody() {
     return `---
 name: crtr-skills
-description: Capture, list, search, and load skills via the crtr CLI. Skills are durable agent memory — markdown future LLM sessions load on demand. Use when the user wants to remember/save knowledge, build a context primer, or recall a previously saved skill. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".
+description: 'Capture, list, search, and load skills via the crtr CLI. Skills are durable agent memory — markdown future LLM sessions load on demand. Use when the user wants to remember/save knowledge, build a context primer, or recall a previously saved skill. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".'
 argument-hint: [topic or verb]
 ---
 

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

@@ -36,6 +36,7 @@ function state(over = {}) {
         cwdScope: null,
         sort: 'tree',
         preview: false,
+        residentsOnly: false,
         ...over,
     };
 }

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

@@ -11,7 +11,7 @@ import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { dashboardRowsAll, renderForest } from '../render.js';
 import { listNodes, subscriptionsOf } from '../canvas.js';
-import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from './terminal.js';
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, TABS, SORTS } from './model.js';
 import { renderFrame, detectColorCaps, headerHeight, PREVIEW_HEIGHT } from './render.js';
 /** Viewport (body) height = total rows minus the header renderFrame draws (see
@@ -52,6 +52,7 @@ export async function runBrowse(opts = {}) {
         cwdScope: launchCwd, // default: this dir
         sort: 'tree',
         preview: true, // default ON (decision)
+        residentsOnly: true, // default ON: hide one-shot workers (decision)
     };
     let visible = [];
     // Color capability is fixed for the session (it's a property of the tty/env).
@@ -89,6 +90,7 @@ export async function runBrowse(opts = {}) {
             tab: state.tab,
             query: state.query,
             cwdScope: state.cwdScope,
+            residentsOnly: state.residentsOnly,
             sort: state.sort,
         });
         if (keepId !== undefined) {
@@ -116,6 +118,7 @@ export async function runBrowse(opts = {}) {
             tree, visible, tab: state.tab, cursor: state.cursor, scrollOffset: state.scrollOffset,
             query: state.query, search: state.search, totalNodes,
             cwdScope: state.cwdScope, sort: state.sort, preview: state.preview,
+            residentsOnly: state.residentsOnly,
         }, size, caps);
         process.stdout.write(frame);
     };
@@ -146,6 +149,13 @@ export async function runBrowse(opts = {}) {
         state.cwdScope = state.cwdScope === null ? launchCwd : null;
         recompute(keep);
     };
+    // Toggle the resident-only lifecycle filter (hide/show one-shot worker nodes),
+    // keeping the selected node put when it survives the toggle.
+    const toggleResidents = () => {
+        const keep = curRow()?.id;
+        state.residentsOnly = !state.residentsOnly;
+        recompute(keep);
+    };
     const onKeySearch = (input, key) => {
         if (key.escape) {
             // Cancel the search: drop the query AND the relevance ranking it switched
@@ -284,7 +294,7 @@ export async function runBrowse(opts = {}) {
             flush();
             return;
         }
-        // Sort / scope / preview.
+        // Sort / scope / residents / preview.
         if (input === 's') {
             cycleSort();
             flush();
@@ -295,6 +305,11 @@ export async function runBrowse(opts = {}) {
             flush();
             return;
         }
+        if (input === 'r') {
+            toggleResidents();
+            flush();
+            return;
+        }
         if (input === 'p') {
             state.preview = !state.preview;
             flush();
@@ -322,6 +337,13 @@ export async function runBrowse(opts = {}) {
     // Boot. If the launch dir holds NO nodes, the default this-dir scope would show
     // a blank canvas — fall back to All dirs so browse is never empty on open.
     recompute();
+    // Relax the resident-only filter first (you're in this dir for a reason), then
+    // the cwd scope — so browse is never blank on open even if the launch dir holds
+    // only one-shot workers, or only nodes from other dirs.
+    if (visible.length === 0 && state.residentsOnly) {
+        state.residentsOnly = false;
+        recompute();
+    }
     if (visible.length === 0 && state.cwdScope !== null) {
         state.cwdScope = null;
         recompute();

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

@@ -50,9 +50,36 @@ export declare function fuzzyMatch(query: string, text: string): boolean;
  *  the renderer can highlight them. Empty set when `query` is empty OR does not
  *  fully match (no partial highlights). */
 export declare function matchIndices(query: string, text: string): Set<number>;
+/** One word-wrapped preview line: its text + the column indices WITHIN that text
+ *  to highlight (the query match). */
+export interface SnippetLine {
+    text: string;
+    hi: Set<number>;
+}
+/** Highlight indices for the preview: the literal case-insensitive SUBSTRING span
+ *  when present (so "where does this text appear?" is answered exactly), else the
+ *  scattered subsequence indices, else empty (empty query). This is a different,
+ *  stricter model than the subsequence super-search on purpose — a contiguous span
+ *  is what reads as a highlight. */
+export declare function highlightIndices(query: string, text: string): Set<number>;
+/**
+ * Build the preview snippet for `text` under the live `query`: up to `maxLines`
+ * word-wrapped lines (each ≤ `width` cols), WINDOWED so the best match is visible
+ * (long conversations: the match can be thousands of chars in), with the matched
+ * columns flagged for highlight. Empty query (or empty text) → a plain wrap from
+ * the start with no highlight. The snippet string itself is what carries the
+ * highlight indices, so they never drift across the windowing.
+ */
+export declare function previewSnippet(query: string, text: string, width: number, maxLines: number): SnippetLine[];
+/** The searchable conversation text for a row: EVERY user prompt across the pi
+ *  session (`prompts`) when present, else the spawn prompt (`goal`) for a
+ *  never-revived node that has no session yet. Searched by super-search and
+ *  windowed in the preview, so search matches a prompt from ANYWHERE in the
+ *  conversation, not just the first one. */
+export declare function promptText(row: DashboardRow): string;
 /** Does this row match the live query? Super-search spans name (which already
- *  folds in the pi-generated description), kind, short-id, AND the spawn prompt
- *  (`row.goal`). Empty query matches everything. */
+ *  folds in the pi-generated description), kind, short-id, AND every user prompt
+ *  in the conversation (`promptText`). Empty query matches everything. */
 export declare function queryMatch(query: string, row: DashboardRow): boolean;
 /** Score how well `query` matches one field, 0 (no match) → 1 (exact). Tiers:
  *  exact > prefix > word-boundary substring > interior substring > subsequence.
@@ -76,12 +103,21 @@ export interface FlattenOpts {
      *  undefined = All dirs (no cwd filter). Like the tab predicate, it gates the
      *  matched set — ancestors from other dirs still render dimmed for tree context. */
     cwdScope?: string | null;
+    /** Lifecycle filter: when true, hide `terminal` (one-shot worker) nodes so only
+     *  the persistent `resident` agents you come back to show. The resume picker
+     *  defaults this ON. Undefined/false = every lifecycle. Gates the matched set
+     *  like the tab + cwd predicates (ancestors of a match still render for context). */
+    residentsOnly?: boolean;
     /** Ordering. `tree` keeps the spanning tree + ancestor context; `relevance` /
      *  `recency` produce a FLAT ranked list of directly-matched rows. */
     sort?: SortMode;
 }
 /** 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;
+/** Is this row inside the active lifecycle filter? `residentsOnly` hides `terminal`
+ *  nodes; off (false/undefined) = every lifecycle. A row with an unknown lifecycle
+ *  (older snapshot field absent) is treated as resident so it is never hidden. */
+export declare function lifecycleMatch(residentsOnly: boolean | undefined, row: DashboardRow): boolean;
 /**
  * Flatten the tree to the ordered list of currently-visible rows.
  *