@crouton-kit/crouter 0.3.17 → 0.3.19

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.
  *

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

@@ -124,19 +124,133 @@ export function matchIndices(query, text) {
         out.clear(); // no full match → no highlight
     return out;
 }
+/** Chars of leading context kept before the match start when windowing. */
+const SNIPPET_LEAD = 12;
+/** 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 function highlightIndices(query, text) {
+    if (query === '')
+        return new Set();
+    const lower = text.toLowerCase();
+    const q = query.toLowerCase();
+    const sub = lower.indexOf(q);
+    if (sub >= 0) {
+        const out = new Set();
+        for (let i = sub; i < sub + q.length; i++)
+            out.add(i);
+        return out;
+    }
+    return matchIndices(query, text);
+}
+/** Greedy word-wrap of single-spaced `s` (caller normalizes whitespace) to `width`
+ *  cols × `maxLines` lines, returning each line's text AND its start offset in `s`.
+ *  Only the single space at each wrap break is dropped, so a highlight index maps
+ *  to a line column as `idx - line.start` with no drift across the wrap. */
+function wrapTracked(s, width, maxLines) {
+    const out = [];
+    if (width <= 0 || maxLines <= 0)
+        return out;
+    const n = s.length;
+    let i = 0;
+    while (i < n && out.length < maxLines) {
+        const lineStart = i;
+        let lineEnd = i; // exclusive end of committed words
+        let j = i;
+        while (j < n) {
+            let ws = j;
+            while (ws < n && s[ws] === ' ')
+                ws++;
+            let we = ws;
+            while (we < n && s[we] !== ' ')
+                we++;
+            if (ws === we)
+                break; // only trailing spaces remain
+            if (we - lineStart <= width || lineEnd === lineStart) {
+                lineEnd = we; // include this word (always take ≥1; a huge word is clipped below)
+                j = we;
+            }
+            else
+                break;
+        }
+        let text = s.slice(lineStart, lineEnd);
+        if (text.length > width)
+            text = text.slice(0, width);
+        out.push({ text, start: lineStart });
+        i = lineEnd;
+        if (i < n && s[i] === ' ')
+            i++; // drop the single break space
+    }
+    return out;
+}
+/**
+ * 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 function previewSnippet(query, text, width, maxLines) {
+    const norm = text.replace(/\s+/g, ' ').trim();
+    if (norm === '' || width <= 0 || maxLines <= 0)
+        return [];
+    // 1. Locate the match in the normalized text + choose a window start that keeps
+    //    a little leading context, snapped to a word boundary.
+    let matchStart = -1;
+    if (query !== '') {
+        const sub = norm.toLowerCase().indexOf(query.toLowerCase());
+        if (sub >= 0)
+            matchStart = sub;
+        else {
+            const ix = matchIndices(query, norm);
+            if (ix.size > 0)
+                matchStart = Math.min(...ix);
+        }
+    }
+    let windowStart = 0;
+    if (matchStart > SNIPPET_LEAD) {
+        let s = matchStart - SNIPPET_LEAD;
+        while (s < matchStart && norm[s] !== ' ')
+            s++; // forward to the next word boundary
+        windowStart = s < matchStart ? s + 1 : matchStart;
+    }
+    const snippet = (windowStart > 0 ? '… ' : '') + norm.slice(windowStart);
+    // 2. Recompute highlight indices on the FINAL snippet string (no drift), then
+    //    word-wrap with offset tracking and split the highlight into per-line cols.
+    const hi = highlightIndices(query, snippet);
+    return wrapTracked(snippet, width, maxLines).map(({ text: lt, start }) => {
+        const lhi = new Set();
+        for (const idx of hi)
+            if (idx >= start && idx < start + lt.length)
+                lhi.add(idx - start);
+        return { text: lt, hi: lhi };
+    });
+}
 function shortId(id) {
     return id.slice(0, 8);
 }
+/** 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 function promptText(row) {
+    return row.prompts ?? row.goal ?? '';
+}
 /** 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 function queryMatch(query, row) {
     if (query === '')
         return true;
+    const prompt = promptText(row);
     return (fuzzyMatch(query, row.name) ||
         fuzzyMatch(query, row.kind) ||
         fuzzyMatch(query, shortId(row.node_id)) ||
-        (row.goal !== undefined && fuzzyMatch(query, row.goal)));
+        (prompt !== '' && fuzzyMatch(query, prompt)));
 }
 // ---------------------------------------------------------------------------
 // Relevance scoring (super-search)
@@ -159,23 +273,30 @@ export function fieldScore(query, text) {
     }
     return fuzzyMatch(q, t) ? 0.2 : 0; // scattered subsequence
 }
-/** Per-field weights — name (handle + description) dominates, the spawn prompt
- *  is the long-tail super-search field. */
-const FIELD_WEIGHTS = { name: 4, kind: 2, id: 1, goal: 1.5 };
+/** Per-field weights — name (handle + description) dominates, the conversation
+ *  prompts are the long-tail super-search field. */
+const FIELD_WEIGHTS = { name: 4, kind: 2, id: 1, prompt: 1.5 };
 /** Weighted relevance of a row to the query across all searched fields. 0 means
  *  no field matched (excluded from relevance results, same as `queryMatch`). */
 export function scoreRow(query, row) {
     if (query === '')
         return 0;
+    const prompt = promptText(row);
     return (FIELD_WEIGHTS.name * fieldScore(query, row.name) +
         FIELD_WEIGHTS.kind * fieldScore(query, row.kind) +
         FIELD_WEIGHTS.id * fieldScore(query, shortId(row.node_id)) +
-        FIELD_WEIGHTS.goal * (row.goal !== undefined ? fieldScore(query, row.goal) : 0));
+        FIELD_WEIGHTS.prompt * (prompt !== '' ? fieldScore(query, prompt) : 0));
 }
 /** Is this row inside the active cwd scope? No scope (null/undefined) = All dirs. */
 export function cwdMatch(scope, row) {
     return scope === null || scope === undefined || row.cwd === scope;
 }
+/** 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 function lifecycleMatch(residentsOnly, row) {
+    return residentsOnly !== true || row.lifecycle !== 'terminal';
+}
 /**
  * Flatten the tree to the ordered list of currently-visible rows.
  *
@@ -189,11 +310,14 @@ export function cwdMatch(scope, row) {
  * always reachable.
  */
 export function flatten(tree, opts) {
-    const { collapsed, tab, query, cwdScope, sort = 'tree' } = opts;
-    // 1. Directly-matched nodes: tab predicate AND cwd scope AND query.
+    const { collapsed, tab, query, cwdScope, residentsOnly, sort = 'tree' } = opts;
+    // 1. Directly-matched nodes: tab predicate AND cwd scope AND lifecycle AND query.
     const matched = 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) &&
+            cwdMatch(cwdScope, node.row) &&
+            lifecycleMatch(residentsOnly, node.row) &&
+            queryMatch(query, node.row)) {
             matched.add(id);
         }
     }

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

@@ -1,19 +1,10 @@
 import type { Tab, Tree, VisibleRow, SortMode } from './model.js';
+import { detectColorCaps, type ColorCaps } from '../../tui/draw.js';
+export { detectColorCaps };
+export type { ColorCaps };
 export declare const PREVIEW_BODY = 5;
 export declare const PREVIEW_HEIGHT: number;
 export declare function headerHeight(search: boolean): number;
-export interface ColorCaps {
-    /** Any hue (fg/bg color) allowed. */
-    color: boolean;
-    /** 256-color bg allowed — drives the subtle cursor-row background. */
-    color256: boolean;
-}
-/** Detect color capability. Honors `NO_COLOR` and `TERM=dumb`, and only emits
- *  hue when stdout is a TTY. `color256` additionally requires a 256/truecolor
- *  terminal (for the cursor-row background; otherwise we fall back to reverse). */
-export declare function detectColorCaps(stream?: {
-    isTTY?: boolean;
-}, env?: NodeJS.ProcessEnv): ColorCaps;
 export interface RenderState {
     tree: Tree;
     visible: VisibleRow[];
@@ -29,6 +20,9 @@ export interface RenderState {
     sort: SortMode;
     /** Whether the bottom preview panel is drawn. */
     preview: boolean;
+    /** Lifecycle filter: when true, `terminal` (one-shot worker) nodes are hidden
+     *  — surfaced as a status-line cue. */
+    residentsOnly: boolean;
 }
 /**
  * Render the whole frame. Returns a single string that, written as-is, repaints

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

@@ -11,7 +11,12 @@
 // Every hue (fg / bg color) is gated on `caps.color`; structural SGR (bold/dim/
 // reverse) is allowed always. See detectColorCaps() for the gate, and the
 // canvas-browse color spec for the rationale + palette.
-import { TABS, matchIndices } from './model.js';
+import { TABS, matchIndices, promptText, previewSnippet } from './model.js';
+// Span/color primitives live in core/tui/draw.ts (one copy, shared with the
+// `crtr view` host). Re-export the color caps so browse's importers + tests keep
+// resolving them from this module.
+import { clip, assemble, detectColorCaps } from '../../tui/draw.js';
+export { detectColorCaps };
 // Fixed chrome heights, shared with app.ts so its viewport math never drifts
 // from what renderFrame actually draws.
 //   header = title + tab bar + status line + separator (+ search input when searching)
@@ -52,16 +57,6 @@ const STATUS_COLOR = {
     dead: FG_RED,
     canceled: FG_GRAY,
 };
-/** Detect color capability. Honors `NO_COLOR` and `TERM=dumb`, and only emits
- *  hue when stdout is a TTY. `color256` additionally requires a 256/truecolor
- *  terminal (for the cursor-row background; otherwise we fall back to reverse). */
-export function detectColorCaps(stream = process.stdout, env = process.env) {
-    const term = env['TERM'] ?? '';
-    const color = stream.isTTY === true && !env['NO_COLOR'] && term !== 'dumb';
-    const colorTerm = env['COLORTERM'] ?? '';
-    const color256 = color && (/256|direct/i.test(term) || /truecolor|24bit/i.test(colorTerm));
-    return { color, color256 };
-}
 function fmtCtx(tokens) {
     if (tokens <= 0)
         return '0k';
@@ -76,12 +71,6 @@ function ctxColorCode(tokens) {
         return FG_YELLOW;
     return undefined;
 }
-/** Truncate to `max` visible cols (plain text, no ANSI). */
-function clip(text, max) {
-    if (max <= 0)
-        return '';
-    return text.length <= max ? text : text.slice(0, Math.max(0, max - 1)) + '…';
-}
 /** Compact relative age, e.g. `45s` `12m` `3h` `5d` `2w` `4mo`. Empty on a bad
  *  timestamp. Drives the per-row recency cue + the preview meta line. */
 function relAge(created, now) {
@@ -110,74 +99,13 @@ function baseDir(cwd) {
     const parts = cwd.replace(/\/+$/, '').split('/');
     return parts[parts.length - 1] || cwd;
 }
-/** Greedy word-wrap to `width` cols, capped at `maxLines` (last line clipped). */
-function wrap(text, width, maxLines) {
-    if (width <= 0 || maxLines <= 0)
-        return [];
-    const words = text.replace(/\s+/g, ' ').trim().split(' ');
-    const out = [];
-    let cur = '';
-    for (const w of words) {
-        const next = cur === '' ? w : `${cur} ${w}`;
-        if (next.length <= width) {
-            cur = next;
-            continue;
-        }
-        if (cur !== '')
-            out.push(cur);
-        cur = w;
-        if (out.length >= maxLines)
-            break;
-    }
-    if (out.length < maxLines && cur !== '')
-        out.push(cur);
-    return out.slice(0, maxLines).map((l) => clip(l, width));
-}
-/** Style one span. Hue is gated on `color`; bold/dim are not. After the span we
- *  return to `lineBase` (not a bare reset) so a row-level background/dim persists
- *  across the span instead of bleeding or being cleared. */
-function styleSpan(text, span, color, lineBase) {
-    if (text === '')
-        return '';
-    let pre = '';
-    if (span.dim)
-        pre += DIM;
-    if (span.bold)
-        pre += BOLD;
-    if (color && span.fg)
-        pre += `${ESC}${span.fg}m`;
-    if (pre === '')
-        return text; // inherits lineBase / default
-    return `${pre}${text}${RESET}${lineBase}`;
-}
-/** Assemble styled spans into one line clipped to `width` visible cols. When
- *  `fill`, pad the remainder with spaces (under `lineBase`) so a cursor-row
- *  background spans the full width. Always RESET-terminated so no color bleeds
- *  into the next line. */
-function assemble(spans, width, color, lineBase, fill) {
-    let used = 0;
-    let body = '';
-    for (const span of spans) {
-        if (used >= width)
-            break;
-        if (span.text === '')
-            continue;
-        let t = span.text;
-        const remaining = width - used;
-        let cut = false;
-        if (t.length > remaining) {
-            t = t.slice(0, Math.max(0, remaining - 1)) + '…';
-            cut = true;
-        }
-        body += styleSpan(t, span, color, lineBase);
-        used += t.length;
-        if (cut)
-            break;
-    }
-    if (fill && used < width)
-        body += ' '.repeat(width - used);
-    return lineBase === '' ? body : `${lineBase}${body}${RESET}`;
-}
+// ── Styled spans ──────────────────────────────────────────────────────────────
+//
+// A row is built from styled spans, then assembled to a width-clipped line. This
+// lets each cell carry its own hue (status glyph, ctx tier, asks, match highlight)
+// while clipping by VISIBLE width — ANSI bytes don't count toward the column
+// budget. `fg` is hue (gated on `color`); `bold`/`dim` are structural (always).
+// Span / styleSpan / assemble now live in core/tui/draw.ts (imported above).
 /** Status tallies across the whole canvas, for the right-aligned header. Memoized
  *  per tree — the snapshot is immutable for a browse session, so counting is done
  *  once, not O(N) on every keystroke (the "massive canvas" target). */
@@ -213,7 +141,7 @@ const EMPTY_HI = new Set();
 function nameSpans(name, query, style) {
     const hi = query === '' ? EMPTY_HI : matchIndices(query, name);
     if (hi.size === 0)
-        return [{ text: name, dim: style.dim, bold: style.bold }];
+        return [{ text: name, style: { dim: style.dim, bold: style.bold } }];
     const out = [];
     let buf = '';
     let bufHi = false;
@@ -221,9 +149,9 @@ function nameSpans(name, query, style) {
         if (buf === '')
             return;
         if (bufHi)
-            out.push({ text: buf, fg: FG_BRIGHT_CYAN, bold: true });
+            out.push({ text: buf, style: { fg: FG_BRIGHT_CYAN, bold: true } });
         else
-            out.push({ text: buf, dim: style.dim, bold: style.bold });
+            out.push({ text: buf, style: { dim: style.dim, bold: style.bold } });
         buf = '';
     };
     for (let i = 0; i < name.length; i++) {
@@ -255,19 +183,19 @@ function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
     const nameStyle = { dim: !isCursor && terminal, bold: isCursor };
     const spans = [
         { text: `${indent}${collapse} ` },
-        { text: glyph, fg: STATUS_COLOR[r.status] }, // load-bearing status hue
+        { text: glyph, style: { fg: STATUS_COLOR[r.status] } }, // load-bearing status hue
         { text: ' ' },
         ...nameSpans(r.name, query, nameStyle),
-        { text: ` [${r.kind}/${r.mode}]`, fg: FG_GRAY }, // recedes
-        { text: ' ctx ', dim: true },
-        { text: ctxStr, fg: ctxFg, dim: ctxFg === undefined }, // tiered budget cue
+        { text: ` [${r.kind}/${r.mode}]`, style: { fg: FG_GRAY } }, // recedes
+        { text: ' ctx ', style: { dim: true } },
+        { text: ctxStr, style: { fg: ctxFg, dim: ctxFg === undefined } }, // tiered budget cue
     ];
     if (age !== '')
-        spans.push({ text: ` ${age}`, dim: true }); // recency cue
+        spans.push({ text: ` ${age}`, style: { dim: true } }); // recency cue
     if (showCwd)
-        spans.push({ text: ` ~${baseDir(r.cwd)}`, fg: FG_GRAY }); // project cue (All dirs)
+        spans.push({ text: ` ~${baseDir(r.cwd)}`, style: { fg: FG_GRAY } }); // project cue (All dirs)
     if (r.asks > 0)
-        spans.push({ text: ` ⚑${r.asks}`, fg: FG_BRIGHT_YELLOW, bold: true }); // attention
+        spans.push({ text: ` ⚑${r.asks}`, style: { fg: FG_BRIGHT_YELLOW, bold: true } }); // attention
     // Row base: cursor → subtle bg (256) or reverse fallback (also covers !color);
     // non-matched ancestor → whole-row dim for tree context (keep prior behavior).
     let lineBase = '';
@@ -288,15 +216,44 @@ function statusLine(state) {
     const dim = (s) => `${DIM}${s}${RESET}`;
     const scope = state.cwdScope === null ? 'all dirs' : baseDir(state.cwdScope);
     const segs = [`${dim('scope')} ${scope}`, `${dim('sort')} ${state.sort}`];
+    if (state.residentsOnly)
+        segs.push(`${dim('show')} residents`);
     if (!state.search && state.query !== '')
         segs.push(`${dim('filter')} ${state.query}`);
     return segs.join(dim('  ·  '));
 }
+/** One snippet line → a rendered string with the query-matched columns in bold
+ *  bright-cyan (mirrors the row name highlight). Unmatched text stays default. */
+function snippetLine(ln, width, caps) {
+    if (ln.hi.size === 0)
+        return assemble([{ text: ln.text }], width, caps.color, '', false);
+    const spans = [];
+    let buf = '';
+    let bufHi = false;
+    const flush = () => {
+        if (buf === '')
+            return;
+        spans.push(bufHi ? { text: buf, style: { fg: FG_BRIGHT_CYAN, bold: true } } : { text: buf });
+        buf = '';
+    };
+    for (let i = 0; i < ln.text.length; i++) {
+        const h = ln.hi.has(i);
+        if (h !== bufHi) {
+            flush();
+            bufHi = h;
+        }
+        buf += ln.text[i];
+    }
+    flush();
+    return assemble(spans, width, caps.color, '', false);
+}
 /** The bottom preview panel — exactly PREVIEW_HEIGHT lines: a separator, a meta
- *  line (status · kind/mode · project · age · ctx · asks), then the selected
- *  node's spawn prompt wrapped to PREVIEW_BODY lines. The "which one was this?"
+ *  line (status · kind/mode · project · age · ctx · asks), then the selected node's
+ *  prompt wrapped to PREVIEW_BODY lines. Under a live query the body is WINDOWED to
+ *  the matching prompt (anywhere in the conversation) with the match highlighted;
+ *  with no query it shows the spawn prompt from the start. The "which one was this?"
  *  answer — paired with super-search. Always full height so viewport math holds. */
-function previewPanel(r, width, caps, now) {
+function previewPanel(r, width, caps, now, query) {
     const out = [`${DIM}${'─'.repeat(width)}${RESET}`];
     if (r === undefined) {
         while (out.length < PREVIEW_HEIGHT)
@@ -311,10 +268,21 @@ function previewPanel(r, width, caps, now) {
         metaPieces.push(`⚑${r.asks}`);
     const metaText = clip(metaPieces.filter((p) => p !== '').join('  ·  '), Math.max(0, width - 2));
     out.push(caps.color ? `${glyph} ${DIM}${metaText}${RESET}` : `${glyph} ${metaText}`);
-    const goalText = (r.goal ?? '').trim();
-    const body = goalText === '' ? [`${DIM}(no spawn prompt)${RESET}`] : wrap(goalText, width, PREVIEW_BODY);
-    for (let i = 0; i < PREVIEW_BODY; i++)
-        out.push(body[i] ?? '');
+    // With a query, window+highlight the matching prompt from the WHOLE conversation;
+    // otherwise show the spawn prompt from the start.
+    const sourceText = query !== '' ? promptText(r) : (r.goal ?? '');
+    const snippet = previewSnippet(query, sourceText, width, PREVIEW_BODY);
+    if (snippet.length === 0) {
+        out.push(`${DIM}(no spawn prompt)${RESET}`);
+        for (let i = 1; i < PREVIEW_BODY; i++)
+            out.push('');
+    }
+    else {
+        for (let i = 0; i < PREVIEW_BODY; i++) {
+            const ln = snippet[i];
+            out.push(ln === undefined ? '' : snippetLine(ln, width, caps));
+        }
+    }
     return out;
 }
 /**
@@ -373,13 +341,13 @@ export function renderFrame(state, size, caps = { color: false, color256: false
     if (previewOn) {
         const sel = state.visible[state.cursor];
         const r = sel !== undefined ? state.tree.nodes.get(sel.id)?.row : undefined;
-        for (const l of previewPanel(r, width, caps, now))
+        for (const l of previewPanel(r, width, caps, now, state.query))
             lines.push(l);
     }
     // footer.
     const footer = state.search
         ? '⏎ commit  Esc cancel  ⌫ delete'
-        : '↑↓ move  →/← tree  ⏎ resume  Tab tabs  / search  s sort  c cwd  p preview  q quit';
+        : '↑↓ move  →/← tree  ⏎ resume  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit';
     lines.push(`${DIM}${clip(footer, width)}${RESET}`);
     // Assemble: home, each line cleared to EOL, then clear below.
     const body = lines.map((l) => `${l}${ESC}K`).join('\r\n');