@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,176 @@
+import type { DashboardRow } from '../render-source.js';
+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).
+ *    attention — FLAT list, tiered by where your attention belongs (attached/
+ *                streaming/live), newest-message-first within each tier.
+ *    relevance — FLAT list, best query match first (super-search).
+ *    recency   — FLAT list, newest `created` first. */
+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      — what you can pick up right now: active | idle, PLUS a resident
+ *                agent that stopped without finishing (Enter opens its saved
+ *                conversation; submitted input wakes it — see `isFinishedWork`).
+ *                Finished work never appears here.
+ *    Dormant   — done | dead | canceled: literally "no engine running". A stopped
+ *                resident agent is deliberately on BOTH tabs — it is openable
+ *                (Live) and it is not running (Dormant); both are true and each
+ *                tab is the one a different search starts from.
+ *    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;
+    parentId: string | null;
+    childIds: string[];
+}
+export interface Tree {
+    /** Ordered root ids (live-first, then stragglers). */
+    roots: string[];
+    nodes: Map<string, TreeNode>;
+}
+/**
+ * Build a spanning tree of the whole canvas.
+ *   - `rows`       — one DashboardRow per node (display text + status/asks).
+ *   - `rootIds`    — node ids whose `parent === null` (raw, unsorted).
+ *   - `childIdsOf` — a node's children = the nodes it subscribes to (its
+ *                    reports), in edge order. (= subscriptionsOf(id) node ids.)
+ *
+ * Roots are sorted live-first. The graph is walked DFS-preorder; the FIRST
+ * parent to reach a node owns it (cycle-/multi-parent-safe via `visited`). Any
+ * node never reached from a root (orphaned by a missing subscription edge) is
+ * appended as a depth-0 straggler so "All" is genuinely the whole canvas.
+ */
+export declare function buildTree(rows: DashboardRow[], rootIds: string[], childIdsOf: (id: string) => string[]): Tree;
+/** Splice a node out of an already-built tree in place (mutates `tree`). Used when
+ *  a close REAPED an empty node (row + dir hard-deleted) rather than parking it:
+ *  the node is gone from the db, so it must vanish from the in-memory tree too or
+ *  its stale row lingers on screen (the "press x, nothing happens" bug — an empty
+ *  active husk reaped by closeNode but never dropped from `tree.nodes`, so the
+ *  attention/flat view kept painting it). Surviving children are re-homed to the
+ *  reaped node's parent so a non-leaf reap never orphans them out of view. No-op
+ *  if the id is absent. */
+export declare function pruneNode(tree: Tree, id: string): void;
+/** 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>;
+}
+/** The literal case-insensitive substring span in a conversation preview.
+ *  Scattered letters are not a message match and never receive 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? Empty query matches everything; a
+ *  non-empty query uses the same fields and match tiers as relevance ranking. */
+export declare function queryMatch(query: string, row: DashboardRow, contentHits?: ReadonlyMap<string, string>): boolean;
+export type MatchTier = 0 | 1 | 2 | 3;
+export interface FieldMatch {
+    /** 3 = bounded word/phrase, 2 = contiguous partial, 1 = subsequence. */
+    tier: MatchTier;
+    /** Tie-break quality within one tier. */
+    quality: number;
+}
+export interface RelevanceScore {
+    tier: MatchTier;
+    strength: number;
+}
+/** One field's best match. Match class is deliberately separate from quality:
+ *  a bounded literal always outranks a contiguous partial, which always outranks
+ *  a scattered subsequence, regardless of field weights. */
+export declare function fieldMatch(query: string, text: string): FieldMatch;
+/** Rank a row by its strongest match class, then by weighted evidence only from
+ *  that class. Weaker classes cannot add up to beat one stronger literal match. */
+export declare function scoreRow(query: string, row: DashboardRow): RelevanceScore;
+/** The "most recent message" signal for the attention sort: the pi session-file
+ *  mtime (ms) the snapshot stamps on each row, falling back to the `created`
+ *  birth timestamp when no session file exists. Larger = more recent.
+ *
+ *  NOTE (phase-3 reconcile): phase 1 owns the field name on DashboardRow. We read
+ *  `mtimeMs` here as the most likely name; if phase 1 lands a different name,
+ *  update this single accessor. `created` is ISO 8601, so its epoch-ms is a
+ *  monotonic stand-in within the same tier. */
+export declare function attentionMtime(row: DashboardRow): number;
+/** Up to a 10% relevance lift for recent conversation activity, halving after a
+ *  week. Match tier remains separate, so freshness never promotes fuzzy over literal. */
+export declare function relevanceFreshness(row: DashboardRow, now: number): number;
+/** Attention tier (lower = higher priority, shown first):
+ *    T0 — attached AND streaming (`viewed && streaming`)
+ *    T1 — attached, not streaming (`viewed`)
+ *    T2 — streaming, not attached
+ *    T3 — live but neither (`status active|idle`)
+ *    T4 — everything else (dormant: done/dead/canceled). */
+export declare function attentionTier(row: DashboardRow): number;
+export interface VisibleRow {
+    id: string;
+    depth: number;
+    hasChildren: boolean;
+    collapsed: boolean;
+    matched: boolean;
+}
+export interface FlattenOpts {
+    collapsed: Set<string>;
+    tab: Tab;
+    query: string;
+    /** cwd-scope filter: only rows pinned to this dir are directly-matched. null /
+     *  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;
+    /** Profile-scope filter: only rows belonging to this profile are directly-matched.
+     *  undefined = All profiles. It gates matches before ancestor context is added. */
+    profileScope?: string | undefined;
+    /** Lifecycle filter: when true, `terminal` (one-shot worker) nodes are kept out
+     *  of the TOP-LEVEL rows and the flat search results — but, in tree mode, still
+     *  appear when you manually expand their parent fold (drilling into a resident).
+     *  The resume picker defaults this ON. Undefined/false = every lifecycle. */
+    residentsOnly?: boolean;
+    /** 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>;
+    /** Conversation-content search hits for the live query: node id → matching
+     *  snippet. A row in this map matches the query even when its name and prompts
+     *  do not; such a row scores tier 0, so it ranks below every name/prompt match. */
+    contentHits?: ReadonlyMap<string, 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;
+/** Is this row inside the active profile scope? Undefined = All profiles. */
+export declare function profileMatch(scope: string | 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.
+ *
+ * Inclusion: a node is shown when it directly matches (tab predicate AND query)
+ * — flagged `matched:true` — OR it is an ANCESTOR of a directly-matched node
+ * (shown for tree context, `matched:false`, dimmed by the renderer).
+ *
+ * Collapse: children are emitted only under an EXPANDED node. A node is expanded
+ * when it is not in `collapsed` — except under a non-empty query, where every
+ * ancestor-of-a-match is force-expanded regardless of `collapsed` so matches are
+ * always reachable.
+ */
+export declare function flatten(tree: Tree, opts: FlattenOpts): VisibleRow[];

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

@@ -0,0 +1,477 @@
+// model.ts — pure, TTY-free logic for the canvas browser.
+//
+// Everything here is a pure function of its inputs (no db, no stdin, no ANSI) so
+// 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.
+import { isFinishedWork, isLiveStatus, statusRank } from '../node-order.js';
+import { matchIndices } from '../../tui/fuzzy.js';
+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      — what you can pick up right now: active | idle, PLUS a resident
+ *                agent that stopped without finishing (Enter opens its saved
+ *                conversation; submitted input wakes it — see `isFinishedWork`).
+ *                Finished work never appears here.
+ *    Dormant   — done | dead | canceled: literally "no engine running". A stopped
+ *                resident agent is deliberately on BOTH tabs — it is openable
+ *                (Live) and it is not running (Dormant); both are true and each
+ *                tab is the one a different search starts from.
+ *    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 isLiveStatus(row.status)
+            || !isFinishedWork({ lifecycle: row.lifecycle, finalized: row.finalized === true });
+        case 'Dormant': return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
+        case 'Attention': return row.asks > 0 || row.hanging != null;
+        case 'Pinned': return isPinned;
+    }
+}
+/**
+ * Build a spanning tree of the whole canvas.
+ *   - `rows`       — one DashboardRow per node (display text + status/asks).
+ *   - `rootIds`    — node ids whose `parent === null` (raw, unsorted).
+ *   - `childIdsOf` — a node's children = the nodes it subscribes to (its
+ *                    reports), in edge order. (= subscriptionsOf(id) node ids.)
+ *
+ * Roots are sorted live-first. The graph is walked DFS-preorder; the FIRST
+ * parent to reach a node owns it (cycle-/multi-parent-safe via `visited`). Any
+ * node never reached from a root (orphaned by a missing subscription edge) is
+ * appended as a depth-0 straggler so "All" is genuinely the whole canvas.
+ */
+export function buildTree(rows, rootIds, childIdsOf) {
+    const rowMap = new Map(rows.map((r) => [r.node_id, r]));
+    const nodes = new Map();
+    const orderedRoots = [];
+    const visited = new Set();
+    const rankOf = (id) => {
+        const r = rowMap.get(id);
+        return r !== undefined ? statusRank(r.status) : 99;
+    };
+    const walk = (id, depth, parentId) => {
+        if (visited.has(id))
+            return; // cycle, or already claimed by an earlier parent
+        const row = rowMap.get(id);
+        if (row === undefined)
+            return; // id in the graph but no row (missing meta)
+        visited.add(id);
+        const childIds = childIdsOf(id).filter((c) => rowMap.has(c) && !visited.has(c));
+        nodes.set(id, { row, depth, parentId, childIds });
+        for (const c of childIds)
+            walk(c, depth + 1, id);
+    };
+    const sortedRoots = [...rootIds].filter((id) => rowMap.has(id)).sort((a, b) => rankOf(a) - rankOf(b));
+    for (const r of sortedRoots) {
+        if (visited.has(r))
+            continue;
+        orderedRoots.push(r);
+        walk(r, 0, null);
+    }
+    // Stragglers: any row never reached from a declared root. Attach live-first as
+    // depth-0 pseudo-roots so the whole canvas stays reachable.
+    const stragglers = rows
+        .map((r) => r.node_id)
+        .filter((id) => !visited.has(id))
+        .sort((a, b) => rankOf(a) - rankOf(b));
+    for (const s of stragglers) {
+        if (visited.has(s))
+            continue;
+        orderedRoots.push(s);
+        walk(s, 0, null);
+    }
+    return { roots: orderedRoots, nodes };
+}
+/** Splice a node out of an already-built tree in place (mutates `tree`). Used when
+ *  a close REAPED an empty node (row + dir hard-deleted) rather than parking it:
+ *  the node is gone from the db, so it must vanish from the in-memory tree too or
+ *  its stale row lingers on screen (the "press x, nothing happens" bug — an empty
+ *  active husk reaped by closeNode but never dropped from `tree.nodes`, so the
+ *  attention/flat view kept painting it). Surviving children are re-homed to the
+ *  reaped node's parent so a non-leaf reap never orphans them out of view. No-op
+ *  if the id is absent. */
+export function pruneNode(tree, id) {
+    const node = tree.nodes.get(id);
+    if (node === undefined)
+        return;
+    const parentId = node.parentId;
+    // Children still present (their own reap, if any, already removed them) lift up
+    // to this node's parent, taking its slot in the child order.
+    const survivingKids = node.childIds.filter((c) => tree.nodes.has(c));
+    for (const c of survivingKids) {
+        const kid = tree.nodes.get(c);
+        if (kid !== undefined)
+            kid.parentId = parentId;
+    }
+    if (parentId !== null) {
+        const p = tree.nodes.get(parentId);
+        if (p !== undefined) {
+            const i = p.childIds.indexOf(id);
+            if (i >= 0)
+                p.childIds.splice(i, 1, ...survivingKids);
+        }
+    }
+    else {
+        const i = tree.roots.indexOf(id);
+        if (i >= 0)
+            tree.roots.splice(i, 1, ...survivingKids);
+    }
+    tree.nodes.delete(id);
+}
+/** Chars of leading context kept before the match start when windowing. */
+const SNIPPET_LEAD = 12;
+/** The literal case-insensitive substring span in a conversation preview.
+ *  Scattered letters are not a message match and never receive a highlight. */
+export function highlightIndices(query, text) {
+    if (query === '')
+        return new Set();
+    const sub = text.toLowerCase().indexOf(query.toLowerCase());
+    if (sub < 0)
+        return new Set();
+    const out = new Set();
+    for (let i = sub; i < sub + query.length; i++)
+        out.add(i);
+    return out;
+}
+/** 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.
+    const matchStart = query === '' ? -1 : norm.toLowerCase().indexOf(query.toLowerCase());
+    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);
+    const wrapped = wrapTracked(snippet, width, maxLines);
+    const lines = wrapped.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 };
+    });
+    // 3. Mark a truncation. Without this the last line reads as the end of the text,
+    //    which is exactly the wrong impression for "where did this node leave off?".
+    const last = wrapped[wrapped.length - 1];
+    const lastLine = lines[lines.length - 1];
+    if (last !== undefined && lastLine !== undefined && last.start + last.text.length < snippet.length) {
+        const keep = Math.max(0, Math.min(lastLine.text.length, width - 1));
+        const text = lastLine.text.slice(0, keep);
+        const lhi = new Set();
+        for (const idx of lastLine.hi)
+            if (idx < keep)
+                lhi.add(idx);
+        lines[lines.length - 1] = { text: `${text}…`, hi: lhi };
+    }
+    return lines;
+}
+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? Empty query matches everything; a
+ *  non-empty query uses the same fields and match tiers as relevance ranking. */
+export function queryMatch(query, row, contentHits) {
+    return query === '' || scoreRow(query, row).tier > 0 || contentHits?.has(row.node_id) === true;
+}
+const NO_MATCH = { tier: 0, quality: 0 };
+const WORD_CHAR = /[\p{L}\p{N}]/u;
+function isWordChar(char) {
+    return char !== undefined && WORD_CHAR.test(char);
+}
+/** One field's best match. Match class is deliberately separate from quality:
+ *  a bounded literal always outranks a contiguous partial, which always outranks
+ *  a scattered subsequence, regardless of field weights. */
+export function fieldMatch(query, text) {
+    if (query === '' || text === '')
+        return NO_MATCH;
+    const q = query.toLowerCase();
+    const t = text.toLowerCase();
+    const firstIdx = t.indexOf(q);
+    if (firstIdx >= 0) {
+        for (let idx = firstIdx; idx >= 0; idx = t.indexOf(q, idx + 1)) {
+            const end = idx + q.length;
+            const leftBounded = !isWordChar(q[0]) || !isWordChar(t[idx - 1]);
+            const rightBounded = !isWordChar(q[q.length - 1]) || !isWordChar(t[end]);
+            if (leftBounded && rightBounded)
+                return { tier: 3, quality: t === q ? 1 : 0.95 };
+        }
+        const position = Math.min(0.2, firstIdx / 400);
+        return { tier: 2, quality: (firstIdx === 0 ? 1 : 0.8) - position };
+    }
+    const indices = [...matchIndices(q, t)];
+    if (indices.length === 0)
+        return NO_MATCH;
+    const span = indices[indices.length - 1] - indices[0] + 1;
+    return { tier: 1, quality: q.length / span };
+}
+/** Explicit handles and user prompts are primary. The generated description is
+ *  searchable but lower-weight; assistant replies are preview-only. */
+const FIELD_WEIGHTS = { handle: 4, prompt: 4, kind: 2, description: 1.5, id: 1 };
+function explicitHandle(row) {
+    const handle = row.handle ?? row.name;
+    return handle === row.kind ? '' : handle;
+}
+/** Rank a row by its strongest match class, then by weighted evidence only from
+ *  that class. Weaker classes cannot add up to beat one stronger literal match. */
+export function scoreRow(query, row) {
+    if (query === '')
+        return { tier: 0, strength: 0 };
+    const fields = [
+        { text: explicitHandle(row), weight: FIELD_WEIGHTS.handle, minimumTier: 1 },
+        // Scattered subsequences in long messages are random noise, not matches.
+        { text: promptText(row), weight: FIELD_WEIGHTS.prompt, minimumTier: 2 },
+        { text: row.kind, weight: FIELD_WEIGHTS.kind, minimumTier: 1 },
+        { text: row.description ?? '', weight: FIELD_WEIGHTS.description, minimumTier: 1 },
+        { text: shortId(row.node_id), weight: FIELD_WEIGHTS.id, minimumTier: 1 },
+    ];
+    const matches = fields.map(({ text, weight, minimumTier }) => {
+        const match = fieldMatch(query, text);
+        return { match: match.tier >= minimumTier ? match : NO_MATCH, weight };
+    });
+    const tier = Math.max(...matches.map(({ match }) => match.tier));
+    const strength = matches.reduce((sum, { match, weight }) => sum + (match.tier === tier ? match.quality * weight : 0), 0);
+    return { tier, strength };
+}
+// Attention tiering (default sort)
+/** The "most recent message" signal for the attention sort: the pi session-file
+ *  mtime (ms) the snapshot stamps on each row, falling back to the `created`
+ *  birth timestamp when no session file exists. Larger = more recent.
+ *
+ *  NOTE (phase-3 reconcile): phase 1 owns the field name on DashboardRow. We read
+ *  `mtimeMs` here as the most likely name; if phase 1 lands a different name,
+ *  update this single accessor. `created` is ISO 8601, so its epoch-ms is a
+ *  monotonic stand-in within the same tier. */
+export function attentionMtime(row) {
+    const m = row.mtimeMs;
+    if (typeof m === 'number' && Number.isFinite(m))
+        return m;
+    const t = Date.parse(row.created);
+    return Number.isFinite(t) ? t : 0;
+}
+const RELEVANCE_RECENCY_MAX_BOOST = 0.1;
+const RELEVANCE_RECENCY_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Up to a 10% relevance lift for recent conversation activity, halving after a
+ *  week. Match tier remains separate, so freshness never promotes fuzzy over literal. */
+export function relevanceFreshness(row, now) {
+    const age = Math.max(0, now - attentionMtime(row));
+    return 1 + RELEVANCE_RECENCY_MAX_BOOST / (1 + age / RELEVANCE_RECENCY_HALF_LIFE_MS);
+}
+/** Attention tier (lower = higher priority, shown first):
+ *    T0 — attached AND streaming (`viewed && streaming`)
+ *    T1 — attached, not streaming (`viewed`)
+ *    T2 — streaming, not attached
+ *    T3 — live but neither (`status active|idle`)
+ *    T4 — everything else (dormant: done/dead/canceled). */
+export function attentionTier(row) {
+    const viewed = row.viewed === true;
+    const streaming = row.streaming === true;
+    if (viewed && streaming)
+        return 0;
+    if (viewed)
+        return 1;
+    if (streaming)
+        return 2;
+    if (row.status === 'active' || row.status === 'idle')
+        return 3;
+    return 4;
+}
+/** 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 profile scope? Undefined = All profiles. */
+export function profileMatch(scope, row) {
+    return scope === undefined || row.profile_id === 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.
+ *
+ * Inclusion: a node is shown when it directly matches (tab predicate AND query)
+ * — flagged `matched:true` — OR it is an ANCESTOR of a directly-matched node
+ * (shown for tree context, `matched:false`, dimmed by the renderer).
+ *
+ * Collapse: children are emitted only under an EXPANDED node. A node is expanded
+ * when it is not in `collapsed` — except under a non-empty query, where every
+ * ancestor-of-a-match is force-expanded regardless of `collapsed` so matches are
+ * always reachable.
+ */
+export function flatten(tree, opts) {
+    const { collapsed, tab, query, cwdScope, profileScope, residentsOnly, sort = 'tree', pinned, contentHits } = opts;
+    const isPinned = (id) => pinned?.has(id) === true;
+    // 1. Directly-matched nodes: tab predicate AND profile/cwd scopes 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
+    //    the same set WITHOUT the lifecycle gate — it's how a terminal node becomes
+    //    visible once you expand the resident parent that owns it (the fold-reveal
+    //    below), so residents-only de-clutters the top level + search yet still lets
+    //    you drill into a fold and see everything under it.
+    const matched = new Set();
+    const matchedAll = new Set();
+    for (const [id, node] of tree.nodes) {
+        if (tabPredicate(tab, node.row, isPinned(id)) && profileMatch(profileScope, node.row) && cwdMatch(cwdScope, node.row) && queryMatch(query, node.row, contentHits)) {
+            matchedAll.add(id);
+            if (lifecycleMatch(residentsOnly, node.row))
+                matched.add(id);
+        }
+    }
+    // FLAT ranked modes (relevance / recency): no tree, no ancestors — just the
+    // directly-matched rows in ranked order. Relevance falls back to recency when
+    // the query is empty (every score would be 0).
+    if (sort !== 'tree') {
+        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) => (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((a, b) => (pinRank(a) - pinRank(b)) || byRecency(a, b));
+        }
+        else {
+            const score = new Map();
+            const rowOf = (id) => tree.nodes.get(id).row;
+            const now = Date.now();
+            for (const id of ids)
+                score.set(id, scoreRow(query, rowOf(id)));
+            ids.sort((a, b) => {
+                const aScore = score.get(a);
+                const bScore = score.get(b);
+                const aStrength = aScore.strength * relevanceFreshness(rowOf(a), now);
+                const bStrength = bScore.strength * relevanceFreshness(rowOf(b), now);
+                return (pinRank(a) - pinRank(b))
+                    || (bScore.tier - aScore.tier)
+                    || (bStrength - aStrength)
+                    || (attentionMtime(rowOf(b)) - attentionMtime(rowOf(a)))
+                    || byRecency(a, b);
+            });
+        }
+        return ids.map((id) => ({ id, depth: 0, hasChildren: false, collapsed: false, matched: true }));
+    }
+    // 2. Ancestors of matches (for tree context + force-expand under query).
+    const ancestors = new Set();
+    for (const id of matched) {
+        let p = tree.nodes.get(id)?.parentId ?? null;
+        while (p !== null && !ancestors.has(p)) {
+            ancestors.add(p);
+            p = tree.nodes.get(p)?.parentId ?? null;
+        }
+    }
+    const included = (id) => matched.has(id) || ancestors.has(id);
+    const isExpanded = (id) => {
+        if (query !== '' && ancestors.has(id))
+            return true; // force-expand to reveal matches
+        return !collapsed.has(id);
+    };
+    // 3. Walk the tree in order, emitting shown nodes and descending only into
+    //    expanded ones. A node is shown when it is `included` (matched or ancestor),
+    //    OR — under residents-only — when its already-shown parent is expanded and the
+    //    node matches everything but the lifecycle gate (`matchedAll`). That is the
+    //    fold-reveal: a terminal worker hidden from the top level reappears the moment
+    //    you open the resident fold that owns it. `parentShown` threads that down.
+    const out = [];
+    const walk = (id, parentShown) => {
+        const node = tree.nodes.get(id);
+        if (node === undefined)
+            return;
+        const show = included(id) || (residentsOnly === true && parentShown && matchedAll.has(id));
+        if (show) {
+            const hasChildren = node.childIds.length > 0;
+            out.push({
+                id,
+                depth: node.depth,
+                hasChildren,
+                collapsed: hasChildren && !isExpanded(id),
+                matched: matched.has(id),
+            });
+        }
+        if (isExpanded(id)) {
+            for (const c of node.childIds)
+                walk(c, show);
+        }
+    };
+    for (const r of tree.roots)
+        walk(r, false);
+    return out;
+}

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;