@north-light/crouter 0.3.240 → 0.3.242

package/dist/commands/node/create.js

@@ -75,7 +75,7 @@ function nodeNewParams() {
     return [
         { kind: 'stdin', name: 'prompt', required: false, constraint: 'First user message.' },
         { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: "Persona kind. Defaults to the profile's default kind; `general` when the profile has none. The <kinds> list below names every top-level installable kind." },
-        { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for hands-on work; orchestrator when the unit itself needs decomposition across children.' },
+        { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for one hands-on unit; orchestrator when the unit itself needs decomposition across children. When you hold several parallel units of one kind, spawn ONE orchestrator child of that kind to own the fan-out rather than spawning the units yourself — unless you are already an orchestrator of that kind, whose job is exactly that fan-out.' },
         { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Pin the node to this directory. Defaults to the spawner\u2019s directory for a managed child, and to the directory this command runs in for a root.' },
         { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name.' },
         { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node.' },
@@ -147,6 +147,7 @@ function nodeNewOutput() {
     return [
         { name: 'node_id', type: 'string', required: true, constraint: 'New node id.' },
         { name: 'name', type: 'string', required: true, constraint: 'Display name.' },
+        { name: 'frozen_at', type: 'string', required: false, constraint: 'Present when a managed child exists but capacity deferred its broker start.' },
         ...(inTmux()
             ? [
                 { name: 'window', type: 'string', required: false, constraint: 'tmux window id when a viewer opens.' },
@@ -242,23 +243,27 @@ async function runNodeCreation(input) {
         placement = openSpawnViewer(detail.node_id, detail.cwd, detail.name);
     if (root)
         mark('node_new.viewer_window_opened');
+    const frozen = !root && detail.frozen_at !== null;
     const result = {
         node_id: detail.node_id,
         name: detail.name,
+        ...(frozen ? { frozen_at: detail.frozen_at } : {}),
         window: placement.window,
         session: placement.session,
         follow_up: root
             ? (noKickoff
                 ? 'Independent root spawned idle. No kickoff turn ran; hand it off or attach and prompt it. No report wakes you.'
                 : 'Independent root spawned. You are not subscribed, so its finish does not wake you; hand it off and move on.')
-            : await childFollowUp(parentId),
+            : (frozen
+                ? 'Child row exists, but no broker started because capacity is full. It is frozen and will launch when a broker slot frees; its final report wakes you then.'
+                : await childFollowUp(parentId)),
     };
     return result;
 }
 export const nodeNew = defineLeaf({
     name: 'new',
     description: 'create and start a node immediately',
-    whenToUse: 'a unit of work is genuinely separable from what you are doing: a bounded subtask you would otherwise grind out inline, several independent units worth running in parallel, a scouting pass over unfamiliar code, a change that wants its own git worktree, or an answer you need in a fixed shape rather than as prose',
+    whenToUse: 'a unit of work is genuinely separable from what you are doing: a bounded subtask you would otherwise grind out inline, several independent units worth running in parallel (usually via one orchestrator child of the matching kind rather than a flat fan-out from you), a scouting pass over unfamiliar code, a change that wants its own git worktree, or an answer you need in a fixed shape rather than as prose',
     tier: 'important',
     help: {
         name: 'node new',

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>;
+};

package/dist/commands/sys/context/admin/list-view.js

@@ -0,0 +1,125 @@
+// The list's view model: which documents a question selects, how they group,
+// and what each group costs. Pure — no terminal, no colour, no width — so the
+// rail's counts and the list's rows are computed from the same call.
+import { fuzzyMatch } from '../../../../core/tui/fuzzy.js';
+import { deliveredCost, rungCostsOf } from './model.js';
+export const NO_FILTERS = { rung: 'any', origin: 'any', kind: 'any', state: 'any', query: '' };
+/** Documents whose canonical name carries no `/` share one leading section
+ *  rather than becoming a crowd of one-member groups. */
+const LEADING_KEY = '';
+const LEADING_LABEL = 'top level';
+export function groupKeyOf(name) {
+    const cut = name.indexOf('/');
+    return cut < 0 ? LEADING_KEY : name.slice(0, cut);
+}
+/** Every group key the rows can produce, so collapse state can drop the keys a
+ *  re-plan removed instead of accumulating them. */
+export function groupKeysOf(rows) {
+    return new Set(rows.map((row) => groupKeyOf(row.name)));
+}
+/** 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 function buildListView(rows, filters, expanded, event) {
+    const groups = new Map();
+    const order = [];
+    for (const row of rows) {
+        if (!passes(row, row.records.get(event), filters))
+            continue;
+        const key = groupKeyOf(row.name);
+        const held = groups.get(key);
+        if (held === undefined) {
+            groups.set(key, [row]);
+            order.push(key);
+        }
+        else
+            held.push(row);
+    }
+    if (groups.has(LEADING_KEY)) {
+        order.splice(order.indexOf(LEADING_KEY), 1);
+        order.unshift(LEADING_KEY);
+    }
+    const lines = [];
+    for (const key of order) {
+        const members = groups.get(key);
+        const rungs = { name: 0, preview: 0, content: 0 };
+        let cost = 0;
+        for (const row of members) {
+            const record = row.records.get(event);
+            if (record !== undefined && record.finalRung !== 'none')
+                rungs[record.finalRung] += 1;
+            cost += deliveredCost(record);
+        }
+        const open = filters.query !== '' || expanded.has(key);
+        lines.push({
+            kind: 'group',
+            key,
+            label: key === LEADING_KEY ? LEADING_LABEL : `${key}/`,
+            docs: members.length,
+            rungs,
+            cost,
+            expanded: open,
+            first: members[0],
+        });
+        if (!open)
+            continue;
+        for (const row of members) {
+            lines.push({
+                kind: 'doc',
+                key: row.key,
+                row,
+                label: key === LEADING_KEY ? row.name : row.name.slice(key.length + 1),
+                cost: deliveredCost(row.records.get(event)),
+            });
+        }
+    }
+    return lines;
+}
+/** What the whole filtered set costs, split by the rung it arrives at. */
+export function costTotals(rows, event) {
+    const byRung = { name: 0, preview: 0, content: 0 };
+    let total = 0;
+    for (const row of rows) {
+        const record = row.records.get(event);
+        if (record === undefined || record.finalRung === 'none')
+            continue;
+        const spend = rungCostsOf(record)[record.finalRung];
+        byRung[record.finalRung] += spend;
+        total += spend;
+    }
+    return { total, byRung };
+}
+function passes(row, record, filters) {
+    if (filters.rung !== 'any') {
+        const rung = record?.finalRung ?? 'none';
+        if (filters.rung === 'silent' ? rung !== 'none' : rung !== filters.rung)
+            return false;
+    }
+    if (filters.origin !== 'any' && row.anchor.scope !== filters.origin)
+        return false;
+    if (filters.kind !== 'any' && row.anchor.kind !== filters.kind)
+        return false;
+    if (filters.state !== 'any' && !inState(record, filters.state))
+        return false;
+    if (filters.query !== '' && !fuzzyMatch(filters.query, row.name))
+        return false;
+    return true;
+}
+/** `gated` is the document's own gate — the one predicate that can silence a
+ *  document in every event. An entry gate failure belongs to a single entry and
+ *  reads in the dossier's verdict, not here. */
+function inState(record, state) {
+    if (record === undefined)
+        return state === 'no-entry';
+    switch (state) {
+        case 'delivering':
+            return record.finalRung !== 'none';
+        case 'gated':
+            return !record.docGate.pass;
+        case 'shadowed':
+            return record.shadowedBy !== null;
+        case 'no-entry':
+            return record.authoredEntries.length === 0;
+    }
+}

package/dist/commands/sys/context/admin/model.d.ts

@@ -73,3 +73,14 @@ export declare function surfaceEntryToFlag(entry: SurfaceEntry): string;
 /** One authored entry as a single readable row. */
 export declare function describeSurfaceEntry(entry: SurfaceEntry): string;
 export declare function plural(count: number, one: string, many: string): string;
+/** What one document would cost at each rung, in approximate tokens. The
+ *  renderers decide the payload: `content` emits the body, `preview` emits the
+ *  catalog entry plus the routing line, `name` emits the entry alone. The
+ *  estimate is characters ÷ 4 — it ranks documents correctly and totals
+ *  approximately, and every place it renders says so. */
+export type RungCosts = Record<Rung, number>;
+export declare function rungCostsOf(record: DeliveryRecord): RungCosts;
+/** What this document actually spends in the event the record belongs to. */
+export declare function deliveredCost(record: DeliveryRecord | undefined): number;
+/** Approximate tokens in at most six columns, always marked as an estimate. */
+export declare function formatCost(count: number): string;