@north-light/crouter 0.3.239 → 0.3.241

package/dist/commands/node/bash.js

@@ -4,7 +4,9 @@ import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { displayMessage } from '../../core/runtime/tmux-chrome.js';
 import { contextDir } from '../../core/canvas/paths.js';
-import { activeBackgroundBashJobs, backgroundRunningBashJobs, bashJobCommandLine, bashJobPaths, formatBashElapsed, isSafeBashJobId, jobStartedAtMs, readJobPgid, stopBackgroundBashJob, tailJobLog } from '../../core/bash-jobs.js';
+import { existsSync } from 'node:fs';
+import { activeBackgroundBashJobs, backgroundRunningBashJobs, bashJobCommandLine, bashJobPaths, clearJobDeadline, formatBashElapsed, isSafeBashJobId, jobStartedAtMs, readJobPgid, stopBackgroundBashJob, tailJobLog, writeJobDeadlineMs } from '../../core/bash-jobs.js';
+import { parseDurationMs } from '../../core/wake.js';
 import { cliClient, getNodeOrNull } from '../api-client.js';
 import { nodeInPane } from '../surface/node/placement.js';
 function resolveBashTarget(input, missingMessage) {
@@ -77,7 +79,7 @@ const nodeBashList = defineLeaf({
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
-            { name: 'jobs', type: 'object[]', required: true, constraint: 'Oldest-first {job_id, command, purpose, started_at, elapsed_ms, log_path, pgid, log_tail} for every live background job; purpose is a human-readable label or null.' },
+            { name: 'jobs', type: 'object[]', required: true, constraint: 'Oldest-first {job_id, command, purpose, started_at, elapsed_ms, deadline_at, log_path, pgid, log_tail} for every live background job; purpose is a human-readable label or null; deadline_at is the auto-cancel time or null for a job that runs to completion.' },
         ],
         outputKind: 'object',
         effects: ['Reads the node context jobs directory. Changes nothing.'],
@@ -97,6 +99,7 @@ const nodeBashList = defineLeaf({
             purpose: job.purpose,
             started_at: new Date(job.startedAtMs).toISOString(),
             elapsed_ms: now - job.startedAtMs,
+            deadline_at: job.deadlineAtMs === null ? null : new Date(job.deadlineAtMs).toISOString(),
             log_path: job.logPath,
             pgid: readJobPgid(dir, job.jobId) ?? null,
             log_tail: tailJobLog(job.logPath, tail),
@@ -107,7 +110,7 @@ const nodeBashList = defineLeaf({
         const jobs = result['jobs'];
         if (jobs.length === 0)
             return `No background bash jobs for ${result['node_id']}.`;
-        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${bashJobCommandLine(job.command)}${job.purpose === null ? '' : `\n  purpose: ${job.purpose}`}\n  log: ${job.log_path}`).join('\n');
+        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${bashJobCommandLine(job.command)}${job.purpose === null ? '' : `\n  purpose: ${job.purpose}`}${job.deadline_at === null ? '' : `\n  cancels at: ${job.deadline_at}`}\n  log: ${job.log_path}`).join('\n');
     },
 });
 const nodeBashKill = defineLeaf({
@@ -171,14 +174,75 @@ const nodeBashKill = defineLeaf({
     },
     render: (result) => `Canceled a background bash job for ${result['node_id']}${result['signaled'] === true ? '' : ' (its process group was already gone)'}.`,
 });
+const nodeBashExtend = defineLeaf({
+    name: 'extend',
+    description: 'claim an auto-backgrounded bash job so the daemon does not cancel it at its deadline',
+    whenToUse: 'a command the valve auto-backgrounded is worth keeping past its cancel deadline — give it more time with --for, or let it run to completion with --keep',
+    tier: 'hidden',
+    help: {
+        name: 'node bash extend',
+        summary: 'move or clear the auto-cancel deadline on one of a node’s live background bash jobs',
+        params: [
+            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list or the auto-background notice.' },
+            { kind: 'flag', name: 'for', type: 'string', required: false, constraint: 'New window from now before the job is canceled, as a duration (e.g. 90s, 10m, 1h30m). Mutually exclusive with --keep; give exactly one.' },
+            { kind: 'flag', name: 'keep', type: 'bool', required: false, constraint: 'Remove the deadline entirely so the job runs to completion. Mutually exclusive with --for; give exactly one.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
+            { name: 'deadline_at', type: 'string', required: false, constraint: 'The job’s new auto-cancel time (ISO), or absent when --keep cleared the deadline so the job runs to completion.' },
+        ],
+        outputKind: 'object',
+        effects: ['Rewrites or removes the job’s deadline file. The daemon’s deadline lane reads it on its next scan. Signals nothing.'],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobId = input['job'];
+        if (!isSafeBashJobId(jobId)) {
+            throw new InputError({ error: 'invalid_job_id', message: `invalid background job id: ${jobId}`, next: 'Use a job id reported by `crtr node bash list`.' });
+        }
+        const forDuration = input['for'];
+        const keep = input['keep'] === true;
+        if (keep === (forDuration !== undefined && forDuration !== '')) {
+            throw new InputError({ error: 'invalid_args', message: 'give exactly one of --for <duration> or --keep', next: 'Extend by a window with --for 10m, or drop the deadline with --keep.' });
+        }
+        const dir = contextDir(node.node_id);
+        const paths = bashJobPaths(dir, jobId);
+        if (!existsSync(paths.dir)) {
+            throw new InputError({ error: 'not_found', message: `no background job ${jobId} for ${node.node_id}`, next: 'List live jobs with `crtr node bash list`.' });
+        }
+        if (!existsSync(paths.jobBg) || existsSync(paths.jobExit)) {
+            throw new InputError({ error: 'not_running', message: `background job ${jobId} for ${node.node_id} is no longer running`, next: `It finished or was stopped, so there is no deadline to change. Log: ${paths.jobLog}` });
+        }
+        if (keep) {
+            clearJobDeadline(paths);
+            return { node_id: node.node_id };
+        }
+        const durationMs = parseDurationMs(forDuration);
+        if (durationMs === null || durationMs <= 0) {
+            throw new InputError({ error: 'invalid_duration', message: `not a duration: ${forDuration}`, next: 'Use a value like 90s, 10m, or 1h30m.' });
+        }
+        const deadlineMs = Date.now() + durationMs;
+        writeJobDeadlineMs(paths, deadlineMs);
+        return { node_id: node.node_id, deadline_at: new Date(deadlineMs).toISOString() };
+    },
+    render: (result) => result['deadline_at'] === undefined
+        ? `Cleared the deadline — the background job will run to completion for ${result['node_id']}.`
+        : `Background job for ${result['node_id']} will be canceled at ${result['deadline_at']} unless extended again.`,
+});
 export const nodeBash = defineBranch({
     name: 'bash',
     description: 'control file-backed bash jobs owned by a node',
-    whenToUse: 'a running bash command must be handed off, listed, or stopped — the tmux prefix menu backgrounds, the Inspector’s jobs section lists and cancels',
+    whenToUse: 'a running bash command must be handed off, listed, stopped, or its auto-cancel deadline changed — the tmux prefix menu backgrounds, the Inspector’s jobs section lists and cancels',
     tier: 'hidden',
     help: {
         name: 'node bash',
         summary: 'control file-backed bash jobs owned by a node',
     },
-    children: [nodeBashBackground, nodeBashList, nodeBashKill],
+    children: [nodeBashBackground, nodeBashList, nodeBashKill, nodeBashExtend],
 });

package/dist/commands/node/inspect.js

@@ -3,7 +3,7 @@ import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { isPidAlive } from '../../core/canvas/pid.js';
 import { fullName } from '../../core/canvas/labels.js';
-import { fuzzyMatch } from '../../core/canvas/browse/model.js';
+import { fuzzyMatch } from '../../core/tui/fuzzy.js';
 import { resolveProfileOperand } from '../../core/profiles/manifest.js';
 import { profilesStateBlock } from '../../core/profiles/state-block.js';
 import { nodeSnapshotLeaf } from '../node-snapshot.js';

package/dist/commands/sys/context/admin/detail-panel.d.ts

@@ -47,6 +47,9 @@ export declare class ContextDetailPanel {
     move(delta: number): void;
     render(width: number, height: number, focused: boolean): string[];
     private verdict;
+    /** All three rungs, not just the current one, so "what would demoting this
+     *  save" is read rather than computed. */
+    private costs;
     private acrossEvents;
 }
 /** The editable rows for one document, in the order the panel draws them. */

package/dist/commands/sys/context/admin/detail-panel.js

@@ -1,10 +1,11 @@
 // The dossier: one document's editable configuration above the read-only
-// verdict that configuration produces. Every selectable row here is a field the
-// shell can write; everything below the rule is what the planner decided.
+// verdict that configuration produces, and below that the document's own
+// opening lines. Every selectable row here is a field the shell can write;
+// everything below the rule is what the planner decided.
 import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
 import { padAnsi, theme, wrapText } from '../../../../core/tui/panel.js';
 import { SURFACE_EVENTS } from '../../../../core/substrate/schema.js';
-import { EVENT_INITIALS, cellStateOf, describeSurfaceEntry, plural } from './model.js';
+import { EVENT_INITIALS, cellStateOf, describeSurfaceEntry, formatCost, plural, rungCostsOf } from './model.js';
 const STATE_WORD = {
     pending: 'planning…',
     delivers: 'delivers',
@@ -104,8 +105,14 @@ export class ContextDetailPanel {
         lines.push(theme.fg('dim', ` VERDICT · ${this.event}`));
         lines.push(...this.verdict(record, width));
         lines.push('');
+        lines.push(theme.fg('dim', ' COST IF DELIVERED · approximate'));
+        lines.push(...this.costs(record, width));
+        lines.push('');
         lines.push(theme.fg('dim', ' ACROSS EVENTS'));
         lines.push(...this.acrossEvents(row, width));
+        lines.push('');
+        lines.push(theme.fg('dim', ' BODY'));
+        lines.push(...bodyPreview(record.doc.body, width, height));
         const cursorLine = rowLines.get(this.index) ?? 0;
         const maxStart = Math.max(0, lines.length - height);
         let start = Math.min(Math.max(0, cursorLine - Math.floor(height / 3)), maxStart);
@@ -133,6 +140,16 @@ export class ContextDetailPanel {
         }
         return out;
     }
+    /** All three rungs, not just the current one, so "what would demoting this
+     *  save" is read rather than computed. */
+    costs(record, width) {
+        const costs = rungCostsOf(record);
+        const cells = ['content', 'preview', 'name'].map((rung) => {
+            const text = `${padAnsi(rung, 8)}${padAnsi(formatCost(costs[rung]) || '~0', 8)}`;
+            return rung === record.finalRung ? theme.fg('success', text) : theme.fg('dim', text);
+        });
+        return [truncateToWidth(`  ${cells.join(' ')}`, width)];
+    }
     acrossEvents(row, width) {
         return SURFACE_EVENTS.map((event) => {
             const record = row.records.get(event);
@@ -165,6 +182,18 @@ function bodyLines(body) {
     const trimmed = body.replace(/\n+$/, '');
     return trimmed === '' ? 0 : trimmed.split('\n').length;
 }
+/** The document's opening lines, filling the rows the dossier would otherwise
+ *  leave blank. Bounded by the pane height: past that the reader is scrolling,
+ *  and the body opens in $EDITOR. */
+function bodyPreview(body, width, height) {
+    const trimmed = body.trim();
+    if (trimmed === '')
+        return [theme.fg('dim', '  (empty)')];
+    return trimmed
+        .split('\n')
+        .slice(0, Math.max(1, height))
+        .map((line) => theme.fg('dim', truncateToWidth(`  ${line}`, width)));
+}
 const FIELD_WIDTH = 15;
 function field(label, value, width) {
     const room = Math.max(1, width - FIELD_WIDTH - 2);

package/dist/commands/sys/context/admin/docs-panel.d.ts

@@ -1,6 +1,7 @@
 import { type SurfaceEvent } from '../../../../core/substrate/schema.js';
 import type { DeliveryRecord } from '../../../../core/substrate/plan.js';
 import { PlanSet } from './model.js';
+import { type Filters } from './list-view.js';
 /** One physical document across every event. `records` is sparse: an event
  *  whose corpus never reaches this document has no record for it, and an event
  *  still being planned has none yet either. */
@@ -18,27 +19,36 @@ export interface DocRow {
 /** The union of every planned event's corpus, ordered by the focused event's
  *  precedence order with the documents only other events see appended. */
 export declare function buildRows(plans: PlanSet, event: SurfaceEvent): DocRow[];
-export declare function rowDelivers(row: DocRow): boolean;
 export declare class ContextDocsPanel {
     private readonly onChange;
     private rows;
+    private filters;
+    private event;
+    private lines;
     private index;
-    private filter;
-    private filtering;
-    /** Off by default: the surface is legible only when the silent documents are
-     *  visible beside the delivering ones. */
-    private deliveringOnly;
+    /** Groups the user opened. Empty means every group is collapsed, which is how
+     *  the page opens: ~25 rows that name the whole corpus. */
+    private readonly expanded;
     constructor(onChange: () => void);
+    /** The document the dossier describes: the focused row, or the first member
+     *  of the focused group so the dossier is never blank. */
     get selected(): DocRow | undefined;
-    get ownsKeyboard(): boolean;
-    get filteringDelivering(): boolean;
-    setRows(rows: DocRow[], selectedKey?: string): void;
+    /** Documents the current question selects — counted from the group rollups,
+     *  so a fully collapsed list still reports its size. */
+    get visibleCount(): number;
+    setRows(rows: DocRow[], event: SurfaceEvent, selectedKey?: string): void;
+    setFilters(filters: Filters): void;
     move(delta: number): void;
-    toggleDeliveringOnly(): void;
-    /** True only when a live filter consumed the input. */
-    handleInput(data: string): boolean;
-    private visible;
+    /** True when the focused line is a group, so the shell knows whether a
+     *  descend opens a group or the dossier. */
+    get onGroup(): boolean;
+    toggleGroup(): void;
+    /** Rebuild the drawn lines, keeping the cursor on the same document (or the
+     *  same group), and clamping when what it was on is gone. */
+    private relayout;
     render(width: number, height: number, focused: boolean, plans: PlanSet): string[];
+    private groupLine;
+    private docLine;
     /** Pad rather than trim: this column sets the length of the divider drawn
      *  beside it. */
     private fit;

package/dist/commands/sys/context/admin/docs-panel.js

@@ -1,10 +1,12 @@
-// The middle column: every document the snapshot can see, each carrying its own
-// six-event matrix. One row is one physical document, so two stores answering
-// to the same canonical name stay two rows and the shadowed one is visible.
-import { matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+// The middle column: every document the snapshot can see, grouped by the first
+// segment of its canonical name and each carrying its own six-event matrix. One
+// row is one physical document, so two stores answering to the same canonical
+// name stay two rows and the shadowed one is visible.
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
 import { padAnsi, theme, visibleRange } from '../../../../core/tui/panel.js';
 import { SURFACE_EVENTS } from '../../../../core/substrate/schema.js';
-import { EVENT_INITIALS, cellGlyph, cellStateOf, plural } from './model.js';
+import { EVENT_INITIALS, cellGlyph, cellStateOf, formatCost, plural } from './model.js';
+import { NO_FILTERS, buildListView, groupKeysOf } from './list-view.js';
 /** The union of every planned event's corpus, ordered by the focused event's
  *  precedence order with the documents only other events see appended. */
 export function buildRows(plans, event) {
@@ -41,133 +43,104 @@ export function buildRows(plans, event) {
             absorb(other);
     return order.map((key) => rows.get(key));
 }
-export function rowDelivers(row) {
-    for (const record of row.records.values())
-        if (record.finalRung !== 'none')
-            return true;
-    return false;
-}
 /** Cells and their width, so the shell's legend and the list agree. */
 const CELL_COUNT = SURFACE_EVENTS.length;
 const MATRIX_WIDTH = CELL_COUNT * 2 - 1;
+const COST_WIDTH = 6;
+/** The glyphs a group header counts its members with — the matrix vocabulary,
+ *  so a rung reads the same in both columns. */
+const RUNG_MARK = { content: '█', preview: '▄', name: '▁' };
 export class ContextDocsPanel {
     onChange;
     rows = [];
+    filters = NO_FILTERS;
+    event = 'boot';
+    lines = [];
     index = 0;
-    filter = '';
-    filtering = false;
-    /** Off by default: the surface is legible only when the silent documents are
-     *  visible beside the delivering ones. */
-    deliveringOnly = false;
+    /** Groups the user opened. Empty means every group is collapsed, which is how
+     *  the page opens: ~25 rows that name the whole corpus. */
+    expanded = new Set();
     constructor(onChange) {
         this.onChange = onChange;
     }
+    /** The document the dossier describes: the focused row, or the first member
+     *  of the focused group so the dossier is never blank. */
     get selected() {
-        const rows = this.visible();
-        this.index = Math.max(0, Math.min(this.index, rows.length - 1));
-        return rows[this.index];
-    }
-    get ownsKeyboard() {
-        return this.filtering;
+        const line = this.lines[this.index];
+        if (line === undefined)
+            return undefined;
+        return line.kind === 'doc' ? line.row : line.first;
     }
-    get filteringDelivering() {
-        return this.deliveringOnly;
+    /** Documents the current question selects — counted from the group rollups,
+     *  so a fully collapsed list still reports its size. */
+    get visibleCount() {
+        return this.lines.reduce((count, line) => count + (line.kind === 'group' ? line.docs : 0), 0);
     }
-    setRows(rows, selectedKey) {
+    setRows(rows, event, selectedKey) {
         this.rows = rows;
-        const visible = this.visible();
-        const found = selectedKey === undefined ? -1 : visible.findIndex((row) => row.key === selectedKey);
-        this.index = found >= 0 ? found : Math.min(this.index, Math.max(0, visible.length - 1));
+        this.event = event;
+        const live = groupKeysOf(rows);
+        for (const key of this.expanded)
+            if (!live.has(key))
+                this.expanded.delete(key);
+        this.relayout(selectedKey);
+    }
+    setFilters(filters) {
+        this.filters = filters;
+        this.relayout(this.selected?.key);
     }
     move(delta) {
-        const rows = this.visible();
-        if (rows.length === 0)
+        if (this.lines.length === 0)
             return;
-        this.index = Math.max(0, Math.min(rows.length - 1, this.index + delta));
+        this.index = Math.max(0, Math.min(this.lines.length - 1, this.index + delta));
         this.onChange();
     }
-    toggleDeliveringOnly() {
-        this.deliveringOnly = !this.deliveringOnly;
-        const held = this.selected?.key;
-        this.index = 0;
-        if (held !== undefined) {
-            const at = this.visible().findIndex((row) => row.key === held);
-            if (at >= 0)
-                this.index = at;
-        }
-        this.onChange();
+    /** True when the focused line is a group, so the shell knows whether a
+     *  descend opens a group or the dossier. */
+    get onGroup() {
+        return this.lines[this.index]?.kind === 'group';
     }
-    /** True only when a live filter consumed the input. */
-    handleInput(data) {
-        if (this.filtering) {
-            if (matchesKey(data, 'escape')) {
-                this.filter = '';
-                this.filtering = false;
-            }
-            else if (matchesKey(data, 'enter')) {
-                this.filtering = false;
-            }
-            else if (matchesKey(data, 'backspace')) {
-                this.filter = this.filter.slice(0, -1);
-                this.index = 0;
-            }
-            else if (data.length === 1 && data.charCodeAt(0) >= 32) {
-                this.filter += data;
-                this.index = 0;
-            }
-            this.onChange();
-            return true;
-        }
-        if (data === '/' || matchesKey(data, '/')) {
-            this.filtering = true;
-            this.onChange();
-            return true;
-        }
-        if (matchesKey(data, 'escape') && this.filter !== '') {
-            this.filter = '';
-            this.index = 0;
-            this.onChange();
-            return true;
-        }
-        return false;
+    toggleGroup() {
+        const line = this.lines[this.index];
+        if (line?.kind !== 'group')
+            return;
+        if (this.expanded.has(line.key))
+            this.expanded.delete(line.key);
+        else
+            this.expanded.add(line.key);
+        this.relayout(undefined, line.key);
+        this.onChange();
     }
-    visible() {
-        const needle = this.filter.trim().toLowerCase();
-        return this.rows.filter((row) => {
-            if (this.deliveringOnly && !rowDelivers(row))
-                return false;
-            if (needle === '')
-                return true;
-            return `${row.name}\n${row.anchor.scope}\n${row.anchor.storePath}`.toLowerCase().includes(needle);
-        });
+    /** Rebuild the drawn lines, keeping the cursor on the same document (or the
+     *  same group), and clamping when what it was on is gone. */
+    relayout(selectedKey, groupKey) {
+        const held = selectedKey ?? (this.lines[this.index]?.kind === 'doc' ? this.lines[this.index].key : undefined);
+        this.lines = buildListView(this.rows, this.filters, this.expanded, this.event);
+        const wanted = groupKey !== undefined
+            ? this.lines.findIndex((line) => line.kind === 'group' && line.key === groupKey)
+            : held === undefined
+                ? -1
+                : this.lines.findIndex((line) => line.kind === 'doc' && line.key === held);
+        this.index = wanted >= 0 ? wanted : Math.max(0, Math.min(this.index, this.lines.length - 1));
     }
     render(width, height, focused, plans) {
-        const rows = this.visible();
         const out = [];
-        const heading = this.filtering
-            ? `/${this.filter}`
-            : this.deliveringOnly
-                ? 'DELIVERING'
-                : 'DOCUMENTS';
-        const count = this.filter === '' ? plural(rows.length, 'doc', 'docs') : plural(rows.length, 'match', 'matches');
+        const nameRoom = Math.max(1, width - MATRIX_WIDTH - COST_WIDTH - 3);
+        const heading = this.filters.query === '' ? 'DOCUMENTS' : `/${this.filters.query}`;
+        const count = this.filters.query === ''
+            ? plural(this.visibleCount, 'doc', 'docs')
+            : plural(this.visibleCount, 'match', 'matches');
         const matrixHead = SURFACE_EVENTS.map((event) => EVENT_INITIALS[event]).join(' ');
-        const nameRoom = Math.max(1, width - MATRIX_WIDTH - 2);
-        out.push(truncateToWidth(` ${padAnsi(`${theme.fg('accent', theme.bold(heading))} ${theme.fg('dim', count)}`, nameRoom - 1)} ${theme.fg('dim', matrixHead)}`, width));
-        if (rows.length === 0) {
-            out.push('', theme.fg('dim', this.filter === '' ? ' No documents in this snapshot\u2019s corpus.' : ' Nothing matches that filter.'));
+        out.push(truncateToWidth(` ${padAnsi(`${theme.fg('accent', theme.bold(heading))} ${theme.fg('dim', count)}`, nameRoom + COST_WIDTH + 1)} ${theme.fg('dim', matrixHead)}`, width));
+        if (this.lines.length === 0) {
+            out.push('', theme.fg('dim', ' Nothing matches this question — cycle a facet back to "any".'));
             return this.fit(out, height);
         }
         const capacity = Math.max(1, height - out.length);
-        const range = visibleRange(rows.length, this.index, capacity);
+        const range = visibleRange(this.lines.length, this.index, capacity);
         for (let at = range.start; at < range.end; at += 1) {
-            const row = rows[at];
-            const matrix = SURFACE_EVENTS.map((event) => {
-                const state = plans.peek(event) === undefined ? 'pending' : cellStateOf(row.records.get(event));
-                return cellGlyph(row.records.get(event), state);
-            }).join(' ');
-            const scope = theme.fg('dim', ` ${row.anchor.scope}`);
-            const label = truncateToWidth(`${row.name}${scope}`, nameRoom - 1);
-            const body = ` ${padAnsi(label, nameRoom - 1)} ${matrix}`;
+            const line = this.lines[at];
+            const body = line.kind === 'group' ? this.groupLine(line, nameRoom) : this.docLine(line, nameRoom, plans);
             out.push(at === this.index && focused
                 ? theme.bg('selectedBg', padAnsi(body, width))
                 : at === this.index
@@ -176,6 +149,26 @@ export class ContextDocsPanel {
         }
         return this.fit(out, height);
     }
+    groupLine(line, nameRoom) {
+        const marker = line.expanded ? '▾' : '▸';
+        const label = `${marker} ${theme.bold(line.label)}`;
+        const marks = ['content', 'preview', 'name']
+            .filter((rung) => line.rungs[rung] > 0)
+            .map((rung) => `${line.rungs[rung]}${RUNG_MARK[rung]}`)
+            .join(' ');
+        const stats = theme.fg('dim', marks === '' ? plural(line.docs, 'doc', 'docs') : `${line.docs} · ${marks}`);
+        const room = Math.max(1, nameRoom - visibleWidth(stats) - 1);
+        const field = `${padAnsi(truncateToWidth(label, room), room)} ${stats}`;
+        return ` ${padAnsi(field, nameRoom)} ${cost(line.cost)} ${' '.repeat(MATRIX_WIDTH)}`;
+    }
+    docLine(line, nameRoom, plans) {
+        const matrix = SURFACE_EVENTS.map((event) => {
+            const state = plans.peek(event) === undefined ? 'pending' : cellStateOf(line.row.records.get(event));
+            return cellGlyph(line.row.records.get(event), state);
+        }).join(' ');
+        const label = truncateToWidth(`  ${line.label}`, nameRoom);
+        return ` ${padAnsi(label, nameRoom)} ${cost(line.cost)} ${matrix}`;
+    }
     /** Pad rather than trim: this column sets the length of the divider drawn
      *  beside it. */
     fit(lines, height) {
@@ -184,3 +177,8 @@ export class ContextDocsPanel {
         return lines.slice(0, height).map((line) => (visibleWidth(line) === 0 ? '' : line));
     }
 }
+/** Right-flushed into the cost column, dim because it is an estimate. */
+function cost(count) {
+    const text = formatCost(count);
+    return theme.fg('dim', ' '.repeat(Math.max(0, COST_WIDTH - text.length)) + text);
+}

package/dist/commands/sys/context/admin/list-view.d.ts

@@ -0,0 +1,53 @@
+import type { MemoryScope } from '../../../../core/memory-resolver.js';
+import type { DocKind, Rung, SurfaceEvent } from '../../../../core/substrate/schema.js';
+import type { DocRow } from './docs-panel.js';
+export type RungFacet = 'any' | Exclude<Rung, 'none'> | 'silent';
+export type OriginFacet = 'any' | MemoryScope;
+export type KindFacet = 'any' | DocKind;
+export type StateFacet = 'any' | 'delivering' | 'gated' | 'shadowed' | 'no-entry';
+/** The question the page is asking. Rung asks what arrives, state asks why it
+ *  does not, and the two compose. Every facet is "any" by default, so the page
+ *  opens on the whole corpus. */
+export interface Filters {
+    rung: RungFacet;
+    origin: OriginFacet;
+    kind: KindFacet;
+    state: StateFacet;
+    /** Fuzzy subsequence over the canonical name only. */
+    query: string;
+}
+export declare const NO_FILTERS: Filters;
+/** One drawn line. A group carries what its members add up to, so a collapsed
+ *  list still states where the corpus and its cost sit. */
+export type ListLine = {
+    kind: 'group';
+    key: string;
+    label: string;
+    docs: number;
+    rungs: Record<Exclude<Rung, 'none'>, number>;
+    cost: number;
+    expanded: boolean;
+    /** The first member, so the dossier has a document to describe while the
+     *  cursor rests on the header. */
+    first: DocRow;
+} | {
+    kind: 'doc';
+    key: string;
+    row: DocRow;
+    label: string;
+    cost: number;
+};
+export declare function groupKeyOf(name: string): string;
+/** Every group key the rows can produce, so collapse state can drop the keys a
+ *  re-plan removed instead of accumulating them. */
+export declare function groupKeysOf(rows: readonly DocRow[]): Set<string>;
+/** The lines to draw, in corpus order: the leading section, then each group in
+ *  order of first appearance. A live query force-expands every group holding a
+ *  match without touching `expanded`, so clearing it restores what the user
+ *  collapsed. */
+export declare function buildListView(rows: readonly DocRow[], filters: Filters, expanded: ReadonlySet<string>, event: SurfaceEvent): ListLine[];
+/** What the whole filtered set costs, split by the rung it arrives at. */
+export declare function costTotals(rows: readonly DocRow[], event: SurfaceEvent): {
+    total: number;
+    byRung: Record<Exclude<Rung, 'none'>, number>;
+};