@north-light/crouter 0.3.243 → 0.3.245

package/dist/commands/sys/context/admin/shell.js

@@ -1,7 +1,7 @@
-// The `crtr sys context admin` page: a rail, the document matrix, and the
-// dossier that edits one document's routing. The rail decides WHAT is being
-// planned and WHICH slice of it is shown, the matrix shows WHERE every document
-// lands, and the dossier is the only place a write starts.
+// The `crtr sys context admin` page: a rail, the document list, and the dossier
+// that edits one document's routing. The rail decides WHAT is being planned and
+// WHICH slice of it is shown, the list states what each document does on the
+// dialled event, and the dossier is the only place a write starts.
 import { Input, matchesKey, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
 import { formatGesture, matchesPiTuiInput, } from '../../../../core/keybindings/index.js';
 import { runTuiPage } from '../../../../core/tui/page-host.js';
@@ -10,7 +10,7 @@ import { RUNGS, SURFACE_EVENTS, SURFACE_RUNGS, } from '../../../../core/substrat
 import { profileNameFor } from '../../../../core/substrate/subject-fields.js';
 import { editBufferInEditor } from '../../../../clients/inbox/review/roundtrip.js';
 import { capOwnerFor, moveDoc, readBody, readOnlyReason, toggleFlag, writeBody, writeCap, writeGate, writeRoutingLine, writeShortForm, writeSurfaces, } from './actions.js';
-import { axesOf, cycleAxis, cycleFacet, facetsOf, renderRail, setTypedAxis, typedAxisValue, } from './rail-panel.js';
+import { axesOf, cycleAxis, cycleFacet, facetsOf, payloadRowOf, railEnter, railRowKey, railRowsOf, renderRail, setTypedAxis, typedAxisValue, } from './rail-panel.js';
 import { ContextDetailPanel } from './detail-panel.js';
 import { ContextDocsPanel, buildRows } from './docs-panel.js';
 import { NO_FILTERS, costTotals } from './list-view.js';
@@ -20,8 +20,8 @@ const RAIL_MIN_TOTAL_WIDTH = 86;
 const THREE_COLUMN_MIN_WIDTH = 112;
 /** Columns the two dividers between the three zones spend. */
 const DIVIDER_WIDTH = 6;
-/** Below the floor a row cannot hold a name beside the matrix; above the
- *  ceiling extra width stops buying legibility and the dossier wants it. */
+/** Below the floor a row cannot hold a name beside its state; above the ceiling
+ *  extra width stops buying legibility and the dossier wants it. */
 const DOCS_MIN_WIDTH = 48;
 const DOCS_MAX_WIDTH = 100;
 const DOCS_SHARE = 0.45;
@@ -78,14 +78,14 @@ export class ContextAdminShell {
     // planning
     /** Recompute the focused event's plan, refresh the panels from it, and let
      *  the remaining events fill in behind it. */
-    rebuild(selectedKey) {
+    rebuild() {
         this.plans.plan(this.snapshot.event);
         this.rows = buildRows(this.plans, this.snapshot.event);
-        this.docs.setRows(this.rows, this.snapshot.event, selectedKey ?? this.docs.selected?.key);
+        this.docs.setRows(this.rows, this.snapshot.event);
         this.syncDetail();
         this.plans.warm(() => {
             this.rows = buildRows(this.plans, this.snapshot.event);
-            this.docs.setRows(this.rows, this.snapshot.event, this.docs.selected?.key);
+            this.docs.setRows(this.rows, this.snapshot.event);
             this.syncDetail();
             this.tui.requestRender();
         });
@@ -101,13 +101,29 @@ export class ContextAdminShell {
         const row = this.docs.selected;
         const capOwner = row === undefined ? null : capOwnerFor(row.anchor, this.snapshot.profileId);
         const readOnly = row === undefined ? null : readOnlyReason(row.anchor, this.snapshot.profileId);
-        this.detail.setContext(row, this.snapshot.event, capOwner, readOnly);
+        // The plan's own subject, not a re-derived one: what a failed gate is
+        // explained against must be exactly what it was judged against.
+        this.detail.setContext(row, this.snapshot.event, capOwner, readOnly, this.plans.plan(this.snapshot.event).subject);
     }
     setSnapshot(next) {
+        const held = this.railRows()[this.railIndex];
         this.snapshot = next;
         this.plans.setSnapshot(next);
         this.notice = undefined;
         this.rebuild();
+        this.holdRail(held);
+    }
+    /** Put the rail cursor back on the row it was on, since dialling a different
+     *  event moves the payload row and every offset below it. The payload belongs
+     *  to the dialled event, so when the new event reads none the cursor falls to
+     *  that event's own row rather than to whatever slid into the offset. */
+    holdRail(held) {
+        if (held === undefined)
+            return;
+        const rows = this.railRows();
+        const key = railRowKey(held);
+        const at = rows.findIndex((row) => railRowKey(row) === key);
+        this.railIndex = Math.max(0, at >= 0 ? at : rows.findIndex((row) => row.kind === 'event' && row.event.dialled));
     }
     // input
     matches(id, data) {
@@ -158,7 +174,10 @@ export class ContextAdminShell {
             this.setSnapshot(cycleAxis(this.snapshot, 'event', step));
             return;
         }
-        if (matchesKey(data, 'q') || this.matches('crtr.setup.cancel', data)) {
+        // `crtr.setup.cancel` also claims ctrl+d, so the read face's half-pane
+        // gesture has to outrank it or paging a body would close the page instead.
+        const pagesBody = this.zone === 'detail' && !this.detail.editing && matchesKey(data, 'ctrl+d');
+        if (!pagesBody && (matchesKey(data, 'q') || this.matches('crtr.setup.cancel', data))) {
             this.close();
             return;
         }
@@ -169,31 +188,47 @@ export class ContextAdminShell {
         else
             this.handleDetail(data);
     }
-    /** The rail's rows are the snapshot axes followed by the filter facets, so
-     *  one cursor and one gesture drive both sections. */
+    /** Every surface event with what it delivers, which is what the rail states
+     *  instead of the list drawing a cell per event on every row. An event whose
+     *  plan has not warmed yet has no count to state. */
+    eventRows() {
+        return SURFACE_EVENTS.map((event) => {
+            const plan = this.plans.peek(event);
+            return {
+                event,
+                delivers: plan === undefined ? undefined : plan.docs.filter((record) => record.finalRung !== 'none').length,
+                dialled: event === this.snapshot.event,
+            };
+        });
+    }
+    /** The rail's rows: the events, then the snapshot axes, then the filter
+     *  facets, so one cursor and one gesture drive all three sections. */
+    railRows() {
+        return railRowsOf(this.eventRows(), payloadRowOf(this.snapshot), axesOf(this.snapshot, profileNameFor(this.snapshot.profileId) ?? 'none'), facetsOf(this.filters));
+    }
     handleRail(data) {
-        const axes = axesOf(this.snapshot, profileNameFor(this.snapshot.profileId) ?? 'none');
-        const facets = facetsOf(this.filters);
-        const total = axes.length + facets.length;
-        this.railIndex = Math.max(0, Math.min(this.railIndex, total - 1));
-        const axis = axes[this.railIndex];
-        const facet = facets[this.railIndex - axes.length];
+        const rows = this.railRows();
+        this.railIndex = Math.max(0, Math.min(this.railIndex, rows.length - 1));
+        const row = rows[this.railIndex];
         const change = (delta) => {
-            if (axis !== undefined) {
-                if (axis.typed)
-                    this.openAxisField(axis.id, axis.label);
+            if (row === undefined)
+                return;
+            if (row.kind === 'event')
+                this.setSnapshot({ ...this.snapshot, event: row.event.event });
+            else if (row.kind === 'axis') {
+                if (row.axis.typed)
+                    this.openAxisField(row.axis.id, row.axis.label);
                 else
-                    this.setSnapshot(cycleAxis(this.snapshot, axis.id, delta));
-            }
-            else if (facet !== undefined) {
-                if (facet.typed)
-                    this.openSearch();
-                else
-                    this.setFilters(cycleFacet(this.filters, facet.id, delta));
+                    this.setSnapshot(cycleAxis(this.snapshot, row.axis.id, delta));
             }
+            else if (row.facet.typed)
+                this.openSearch();
+            else
+                this.setFilters(cycleFacet(this.filters, row.facet.id, delta));
         };
+        const onEnter = railEnter(row);
         if (this.isDown(data)) {
-            this.railIndex = Math.min(total - 1, this.railIndex + 1);
+            this.railIndex = Math.min(rows.length - 1, this.railIndex + 1);
         }
         else if (this.isUp(data)) {
             this.railIndex = Math.max(0, this.railIndex - 1);
@@ -202,7 +237,7 @@ export class ContextAdminShell {
             change(1);
         }
         else if (this.isDescend(data)) {
-            if (matchesKey(data, 'enter') && (axis?.typed === true || facet?.typed === true))
+            if (matchesKey(data, 'enter') && onEnter !== 'documents')
                 change(1);
             else
                 this.zone = 'docs';
@@ -228,9 +263,8 @@ export class ContextAdminShell {
             this.syncDetail();
         }
         else if (this.isDescend(data)) {
-            // A directory that is also a document keeps both gestures: space opens it,
-            // and descending goes to its dossier like any other document.
-            if (this.docs.onGroup && !this.docs.onDocument) {
+            // One gesture per row: a header expands, a document opens its dossier.
+            if (this.docs.onGroup) {
                 this.docs.toggleGroup();
                 this.syncDetail();
             }
@@ -268,35 +302,101 @@ export class ContextAdminShell {
         this.tui.requestRender();
     }
     handleDetail(data) {
+        if (this.detail.editing)
+            this.handleEdit(data);
+        else
+            this.handleRead(data);
+    }
+    /** The resting face: reading, and the two gestures that leave it. */
+    handleRead(data) {
         if (this.isDown(data))
             this.detail.move(1);
         else if (this.isUp(data))
             this.detail.move(-1);
-        else if (this.isAscend(data) || matchesKey(data, 'escape'))
-            this.zone = 'docs';
-        else if (matchesKey(data, 'enter') || matchesKey(data, 'space') || this.matches('crtr.setup.toggle', data)) {
-            this.activate();
-        }
-        else if (matchesKey(data, 'b'))
-            this.editBody();
-        else if (matchesKey(data, 'x'))
-            this.removeEntry();
-        else if (matchesKey(data, 'e'))
-            this.composeEntry();
-        else if (matchesKey(data, 'g'))
-            this.editGate();
-        else if (matchesKey(data, 'u'))
-            this.flip('unlisted');
-        else if (matchesKey(data, 's'))
-            this.flip('slash');
-        else if (matchesKey(data, 'm'))
-            this.editCap();
-        else if (matchesKey(data, 'r'))
-            this.editMove();
-        else if (matchesKey(data, 'w'))
-            this.editRouting();
-        else if (matchesKey(data, 'f'))
-            this.editShortForm();
+        else if (matchesKey(data, 'ctrl+d'))
+            this.detail.page(1);
+        else if (matchesKey(data, 'ctrl+u'))
+            this.detail.page(-1);
+        else if (data === 'G' || matchesKey(data, 'shift+g'))
+            this.detail.jump('bottom');
+        else if (data === 'g' || matchesKey(data, 'g'))
+            this.detail.jump('top');
+        else if (data === 'e' || matchesKey(data, 'e'))
+            this.detail.edit();
+        else if (this.isDescend(data))
+            this.detail.openBody();
+        else if (this.isAscend(data) || matchesKey(data, 'escape')) {
+            if (!this.detail.back())
+                this.zone = 'docs';
+        }
+    }
+    /** The field list. Every write gesture is resolved before it is started, so a
+     *  read-only document refuses at the keypress rather than after a modal. */
+    handleEdit(data) {
+        if (this.isDown(data)) {
+            this.detail.move(1);
+            return;
+        }
+        if (this.isUp(data)) {
+            this.detail.move(-1);
+            return;
+        }
+        if (this.isAscend(data) || matchesKey(data, 'escape')) {
+            this.detail.back();
+            return;
+        }
+        const gesture = this.writeGesture(data);
+        if (gesture === undefined)
+            return;
+        if (gesture.document && this.refusesWrite())
+            return;
+        gesture.start();
+    }
+    /** The write one edit-face key starts, or undefined when the key writes
+     *  nothing. `document` marks the writes a read-only document refuses — the
+     *  profile ceiling is not one of them; it lives in the profile manifest. */
+    writeGesture(data) {
+        const doc = (start) => ({ start, document: true });
+        if (matchesKey(data, 'enter') || matchesKey(data, 'space') || this.matches('crtr.setup.toggle', data)) {
+            const row = this.detail.selected;
+            if (row === undefined)
+                return undefined;
+            return row.kind === 'cap' ? { start: () => this.editCap(), document: false } : doc(() => this.activate());
+        }
+        if (matchesKey(data, 'm'))
+            return { start: () => this.editCap(), document: false };
+        if (matchesKey(data, 'b'))
+            return doc(() => this.editBody());
+        if (matchesKey(data, 'x'))
+            return doc(() => this.removeEntry());
+        if (matchesKey(data, 'e'))
+            return doc(() => this.composeEntry());
+        if (matchesKey(data, 'g'))
+            return doc(() => this.editGate());
+        if (matchesKey(data, 'u'))
+            return doc(() => this.flip('unlisted'));
+        if (matchesKey(data, 's'))
+            return doc(() => this.flip('slash'));
+        if (matchesKey(data, 'r'))
+            return doc(() => this.editMove());
+        if (matchesKey(data, 'w'))
+            return doc(() => this.editRouting());
+        if (matchesKey(data, 'f'))
+            return doc(() => this.editShortForm());
+        return undefined;
+    }
+    /** The refusal a read-only document owes the write just attempted, carried by
+     *  the same footer channel every other write outcome uses. */
+    refusesWrite() {
+        const record = this.record;
+        if (record === undefined)
+            return false;
+        const refusal = readOnlyReason(record, this.snapshot.profileId);
+        if (refusal === null)
+            return false;
+        this.notice = { text: refusal, ok: false };
+        this.tui.requestRender();
+        return true;
     }
     /** What the focused dossier row does when opened — the same write its letter
      *  key starts, so a user who never learns the letters can still edit. */
@@ -472,13 +572,6 @@ export class ContextAdminShell {
         const record = this.record;
         if (record === undefined)
             return;
-        // Checked before the terminal leaves for $EDITOR, so a read-only record
-        // refuses in place rather than after a whole editing session.
-        const refusal = readOnlyReason(record, this.snapshot.profileId);
-        if (refusal !== null) {
-            this.notice = { text: refusal, ok: false };
-            return;
-        }
         let before;
         try {
             before = readBody(record);
@@ -633,7 +726,7 @@ export class ContextAdminShell {
         return out.slice(0, height);
     }
     // rendering
-    footer(width) {
+    footer(width, railRow) {
         if (this.busy !== undefined)
             return theme.fg('warning', this.busy);
         if (this.modal?.kind === 'choice')
@@ -648,33 +741,33 @@ export class ContextAdminShell {
             return theme.fg(this.notice.ok ? 'success' : 'warning', truncateToWidth(this.notice.text, width));
         const move = `${this.label('crtr.setup.list-down', 'j')}/${this.label('crtr.setup.list-up', 'k')}`;
         const left = this.zone === 'rail'
-            ? `${move} row · space change · enter documents`
+            ? `${move} row · ${railGesture(railRow)}`
             : this.zone === 'docs'
                 ? `${move} row · ${this.docsGesture()} · / search`
-                : `${move} field · enter edit · e add · x remove · g gate · b body · u unlisted · s slash · m cap · r rename`;
+                : this.detail.editing
+                    ? `${move} field · enter edit · e add · x remove · g gate · b body · u unlisted · s slash · m cap · r rename · esc read`
+                    : this.detail.bodyOpen
+                        ? `${move} scroll · ctrl-d/u page · g/G ends · esc collapse`
+                        : `${move} scroll · enter body · e edit · esc list`;
         const right = `${this.label('crtr.setup.tab-next', 'tab')} event · ${this.label('crtr.setup.cancel', 'q')} close`;
         const gap = width - visibleWidth(left) - visibleWidth(right);
         return gap >= 2
             ? `${theme.fg('dim', left)}${' '.repeat(gap)}${theme.fg('dim', right)}`
             : theme.fg('dim', truncateToWidth(`${left} · ${this.label('crtr.setup.cancel', 'q')} close`, width));
     }
-    /** What the focused row does when opened. A directory answers to space, a
-     *  document to enter, and a directory that is also a document to both. */
+    /** What the focused row does when opened. A directory expands; a document
+     *  opens its dossier. */
     docsGesture() {
-        if (!this.docs.onGroup)
-            return 'enter dossier';
-        return this.docs.onDocument ? 'space open · enter dossier' : 'space/enter open';
+        return this.docs.onGroup ? 'space/enter open' : 'enter dossier';
     }
     render(width) {
         const height = this.terminalRows();
         const bodyHeight = Math.max(1, height - PAGE_CHROME_ROWS);
         const railVisible = width >= RAIL_MIN_TOTAL_WIDTH;
-        const axes = axesOf(this.snapshot, profileNameFor(this.snapshot.profileId) ?? 'none');
-        const facets = facetsOf(this.filters);
-        this.railIndex = Math.max(0, Math.min(this.railIndex, axes.length + facets.length - 1));
+        const rows = this.railRows();
+        this.railIndex = Math.max(0, Math.min(this.railIndex, rows.length - 1));
         const rail = (railWidth) => renderRail({
-            axes,
-            facets,
+            rows,
             index: this.railIndex,
             width: railWidth,
             height: bodyHeight,
@@ -686,7 +779,7 @@ export class ContextAdminShell {
         if (width >= THREE_COLUMN_MIN_WIDTH) {
             const docsWidth = docsWidthFor(width);
             const detailWidth = Math.max(1, width - RAIL_WIDTH - docsWidth - DIVIDER_WIDTH);
-            const middle = columns(this.docs.render(docsWidth, bodyHeight, this.zone === 'docs', this.plans), docsWidth, this.modal === undefined
+            const middle = columns(this.docs.render(docsWidth, bodyHeight, this.zone === 'docs'), docsWidth, this.modal === undefined
                 ? this.detail.render(detailWidth, bodyHeight, this.zone === 'detail')
                 : this.renderModal(detailWidth, bodyHeight), detailWidth);
             body = columns(rail(RAIL_WIDTH), RAIL_WIDTH, middle, width - RAIL_WIDTH - 3);
@@ -697,7 +790,7 @@ export class ContextAdminShell {
                 ? this.renderModal(panelWidth, bodyHeight)
                 : this.zone === 'detail'
                     ? this.detail.render(panelWidth, bodyHeight, true)
-                    : this.docs.render(panelWidth, bodyHeight, this.zone === 'docs', this.plans);
+                    : this.docs.render(panelWidth, bodyHeight, this.zone === 'docs');
             body = columns(rail(RAIL_WIDTH), RAIL_WIDTH, panel, panelWidth);
         }
         else if (this.modal !== undefined) {
@@ -710,7 +803,7 @@ export class ContextAdminShell {
             body = this.detail.render(width, bodyHeight, true);
         }
         else {
-            body = this.docs.render(width, bodyHeight, true, this.plans);
+            body = this.docs.render(width, bodyHeight, true);
         }
         const pending = SURFACE_EVENTS.filter((event) => this.plans.peek(event) === undefined).length;
         const meta = [
@@ -721,7 +814,14 @@ export class ContextAdminShell {
         ]
             .filter((part) => part !== '')
             .join(' · ');
-        return pageFrame({ width, height, title: 'crouter context', meta, body, footer: this.footer(width) });
+        return pageFrame({
+            width,
+            height,
+            title: 'crouter context',
+            meta,
+            body,
+            footer: this.footer(width, rows[this.railIndex]),
+        });
     }
     /** What the delivering documents spend on this event. An estimate, and a
      *  floor on the rendered prompt: boot wraps these documents in its own intro
@@ -737,6 +837,19 @@ export class ContextAdminShell {
         return `docs load ${formatCost(total)} — ${split}`;
     }
 }
+/** What the focused rail row does, which differs by row: an event dials, a
+ *  typed row opens its field, and an enum cycles in place with enter left free
+ *  to move zones. */
+function railGesture(row) {
+    switch (railEnter(row)) {
+        case 'dial':
+            return 'space/enter dial · l documents';
+        case 'edit':
+            return 'space/enter edit · l documents';
+        default:
+            return 'space change · enter documents';
+    }
+}
 /** Every field here is an edit-or-accept, never a blank to retype, so the
  *  cursor lands at the end (`\x05`) — `setValue` alone leaves it at 0, where
  *  typing prepends and backspace does nothing. */

package/dist/commands/sys/context/doc.js

@@ -7,6 +7,7 @@ import { realpathOrSelf } from '../../../core/fs-utils.js';
 import { resolveMemoryDocForTarget } from '../../../core/memory-resolver.js';
 import { InputError } from '../../../core/io.js';
 import { planDelivery } from '../../../core/substrate/plan.js';
+import { explainRecordGate } from '../../../core/substrate/gate-explain.js';
 import { parseSubstrateDoc, SURFACE_EVENTS } from '../../../core/substrate/schema.js';
 import { buildSnapshot, cell, delivers, describeSubject, entryText, exclusionReason, gateText, optionalString, payloadFor, subjectSummary, } from './resolve.js';
 export const docLeaf = defineLeaf({
@@ -58,7 +59,7 @@ export const docLeaf = defineLeaf({
         const recordPathCache = new Map();
         const rows = events.map((event) => {
             const plan = planDelivery(snapshot.subject, snapshot.target, event, payloadFor(event, flags, snapshot.target));
-            return eventRow(event, findRecord(plan.docs, targetPath, recordPathCache));
+            return eventRow(event, findRecord(plan.docs, targetPath, recordPathCache), plan.subject);
         });
         return {
             name: doc.name,
@@ -111,7 +112,7 @@ function surfaceRow(entry) {
         at: entry.at,
     };
 }
-function eventRow(event, record) {
+function eventRow(event, record, subject) {
     if (record === null) {
         return {
             event,
@@ -133,12 +134,12 @@ function eventRow(event, record) {
         authored_rung: record.authoredRung,
         capped_rung: record.cappedRung,
         final_rung: record.finalRung,
-        doc_gate: gateText(record.docGate),
-        entry_gate: record.entryGate === null ? null : gateText(record.entryGate),
+        doc_gate: gateText(record.docGate, explainRecordGate(record, 'doc', subject)),
+        entry_gate: record.entryGate === null ? null : gateText(record.entryGate, explainRecordGate(record, 'entry', subject)),
         matched_entry: entryText(record.matchedEntry),
         winner: record.winner,
         shadowed_by: record.shadowedBy === null ? null : `${record.shadowedBy.scope}:${record.shadowedBy.path}`,
-        excluded: delivers(record) ? null : exclusionReason(record),
+        excluded: delivers(record) ? null : exclusionReason(record, subject),
     };
 }
 function corpusNote(event) {

package/dist/commands/sys/context/resolve.d.ts

@@ -1,5 +1,6 @@
 import { type MemoryTarget } from '../../../core/memory-resolver.js';
 import { type DeliveryPayload, type DeliveryRecord, type GateOutcome } from '../../../core/substrate/plan.js';
+import { type GateClause } from '../../../core/substrate/gate-explain.js';
 import { type Rung, type SurfaceEntry, type SurfaceEvent } from '../../../core/substrate/schema.js';
 import { type NodeConfigSubject } from '../../../core/substrate/subject-fields.js';
 export declare const resolveLeaf: import("../../../core/command.js").LeafDef;
@@ -45,11 +46,14 @@ export interface DocRow {
  *  above the no-delivery floor — boot keeps rung-`none` winners in the plan so
  *  the catalog can still count them. */
 export declare function delivers(record: DeliveryRecord): boolean;
-export declare function docRow(record: DeliveryRecord, includeAll: boolean): DocRow;
-export declare function gateText(gate: GateOutcome): string;
+export declare function docRow(record: DeliveryRecord, includeAll: boolean, subject: NodeConfigSubject | null): DocRow;
+/** A gate verdict as one cell: `pass`, or `fail:` plus the clauses that failed
+ *  — the planner's generic sentence only when the explainer cannot decompose
+ *  the predicate. */
+export declare function gateText(gate: GateOutcome, clauses: readonly GateClause[]): string;
 export declare function entryText(entry: SurfaceEntry | null): string | null;
 /** Why a considered document delivers nothing, in the order the planner applies
  *  its checks — the first failing one is the answer an engineer acts on. */
-export declare function exclusionReason(record: DeliveryRecord): string;
+export declare function exclusionReason(record: DeliveryRecord, subject: NodeConfigSubject | null): string;
 export declare function describeSubject(subject: Record<string, unknown>): string;
 export declare function cell(v: unknown): string;

package/dist/commands/sys/context/resolve.js

@@ -16,6 +16,7 @@ import { envNodeId, envProfileId } from '../../../shared/env.js';
 import { realpathOrSelf } from '../../../core/fs-utils.js';
 import { ambientMemoryTarget, resolveMemoryDocForTarget, } from '../../../core/memory-resolver.js';
 import { planDelivery, } from '../../../core/substrate/plan.js';
+import { explainRecordGate, formatClause } from '../../../core/substrate/gate-explain.js';
 import { emptyContextExposureState, exposureTarget } from '../../../core/substrate/injected-store.js';
 import { renderPreferencesForSubject, renderKnowledgeForSubject } from '../../../core/substrate/render.js';
 import { memoryReadDocBlocks, renderOnCommandDocsForSubject, renderOnReadDocsForSubject, renderPreCommandDocsForSubject, renderWorkspaceOpenDocsForSubject, } from '../../../core/substrate/on-read.js';
@@ -193,7 +194,7 @@ function planSection(snapshot, event, payload, granularity, includeAll) {
     const plan = planDelivery(snapshot.subject, snapshot.target, event, payload);
     if (granularity === 'summary')
         return { event, counts: countsOf(plan) };
-    const docs = plan.docs.filter((r) => includeAll || delivers(r)).map((r) => docRow(r, includeAll));
+    const docs = plan.docs.filter((r) => includeAll || delivers(r)).map((r) => docRow(r, includeAll, plan.subject));
     return { event, docs };
 }
 /** A document delivers when it won its canonical name AND resolved to a rung
@@ -202,7 +203,7 @@ function planSection(snapshot, event, payload, granularity, includeAll) {
 export function delivers(record) {
     return record.winner && rungAtLeast(record.finalRung, 'name');
 }
-export function docRow(record, includeAll) {
+export function docRow(record, includeAll, subject) {
     const row = {
         name: record.name,
         kind: record.kind,
@@ -214,16 +215,22 @@ export function docRow(record, includeAll) {
         final_rung: record.finalRung,
         winner: record.winner,
         shadowed_by: record.shadowedBy === null ? null : `${record.shadowedBy.scope}:${record.shadowedBy.path}`,
-        doc_gate: gateText(record.docGate),
-        entry_gate: record.entryGate === null ? null : gateText(record.entryGate),
+        doc_gate: gateText(record.docGate, explainRecordGate(record, 'doc', subject)),
+        entry_gate: record.entryGate === null ? null : gateText(record.entryGate, explainRecordGate(record, 'entry', subject)),
         matched_entry: entryText(record.matchedEntry),
     };
     if (includeAll && !delivers(record))
-        row.excluded = exclusionReason(record);
+        row.excluded = exclusionReason(record, subject);
     return row;
 }
-export function gateText(gate) {
-    return gate.pass ? 'pass' : `fail: ${gate.reason}`;
+/** A gate verdict as one cell: `pass`, or `fail:` plus the clauses that failed
+ *  — the planner's generic sentence only when the explainer cannot decompose
+ *  the predicate. */
+export function gateText(gate, clauses) {
+    return gate.pass ? 'pass' : `fail: ${gateReason(gate.reason, clauses)}`;
+}
+function gateReason(fallback, clauses) {
+    return clauses.length === 0 ? fallback : clauses.map(formatClause).join('; ');
 }
 export function entryText(entry) {
     if (entry === null)
@@ -239,16 +246,17 @@ export function entryText(entry) {
 }
 /** Why a considered document delivers nothing, in the order the planner applies
  *  its checks — the first failing one is the answer an engineer acts on. */
-export function exclusionReason(record) {
-    if (!record.docGate.pass)
-        return `document gate: ${record.docGate.reason}`;
+export function exclusionReason(record, subject) {
+    if (!record.docGate.pass) {
+        return `document gate: ${gateReason(record.docGate.reason, explainRecordGate(record, 'doc', subject))}`;
+    }
     if (record.shadowedBy !== null)
         return `shadowed by ${record.shadowedBy.scope}:${record.shadowedBy.path}`;
     if (record.authoredEntries.length === 0)
         return 'no surface entry for this event';
     if (record.matchedEntry === null) {
         return record.entryGate !== null && !record.entryGate.pass
-            ? `entry gate: ${record.entryGate.reason}`
+            ? `entry gate: ${gateReason(record.entryGate.reason, explainRecordGate(record, 'entry', subject))}`
             : 'no authored entry matched this event\u2019s payload';
     }
     if (record.cappedRung === 'none') {

package/dist/commands/sys/panels/profiles-panel.js

@@ -18,7 +18,8 @@ import { PROFILE_PROJECT_MEMORY_VALUES } from '../../../api/dto/profiles.js';
 import { cliClient } from '../../api-client.js';
 import { clearDefaultProfile, defaultProfileDirs, getDefaultProfileId, setDefaultProfileId, } from '../../../core/profiles/default-binding.js';
 import { ROOT_PROFILE_ID, addProfileProject, createProfile, listProfiles, pauseProfile, removeProfileProject, renameProfile, resumeProfile, } from '../../../core/profiles/manifest.js';
-import { profileCoversCwd, tildify } from '../../../core/profiles/select.js';
+import { tildify } from '../../../core/fs-utils.js';
+import { profileCoversCwd } from '../../../core/profiles/select.js';
 import { padAnsi, theme, visibleRange, wrapText, } from '../../../core/tui/panel.js';
 /** Coarse "used ..." for telling otherwise-alike profiles apart. */
 function relativeUsed(iso) {

package/dist/core/fs-utils.d.ts

@@ -3,6 +3,9 @@ export declare function realpathOrSelf(p: string): string;
 /** Expand a leading `~` against `homeDir` (pi's own convention). Other forms
  *  — absolute, relative, `~user` — pass through as pi leaves them. */
 export declare function expandTilde(p: string, homeDir?: string): string;
+/** Collapse the home prefix to `~` so a path reads short. The inverse of
+ *  `expandTilde`, and the ONE collapse every surface prints paths through. */
+export declare function tildify(p: string, homeDir?: string): string;
 export declare function ensureDir(dir: string): void;
 export declare function writeJson(path: string, data: unknown): void;
 export interface AtomicWriteOptions {

package/dist/core/fs-utils.js

@@ -1,5 +1,5 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, realpathSync, } from 'node:fs';
-import { dirname, join, relative } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 import { homedir, platform } from 'node:os';
 /** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved. */
 export function realpathOrSelf(p) {
@@ -19,6 +19,15 @@ export function expandTilde(p, homeDir = homedir()) {
         return join(homeDir, p.slice(2));
     return p;
 }
+/** Collapse the home prefix to `~` so a path reads short. The inverse of
+ *  `expandTilde`, and the ONE collapse every surface prints paths through. */
+export function tildify(p, homeDir = homedir()) {
+    if (p === homeDir)
+        return '~';
+    if (p.startsWith(homeDir + sep))
+        return '~' + p.slice(homeDir.length);
+    return p;
+}
 export function ensureDir(dir) {
     mkdirSync(dir, { recursive: true });
 }

package/dist/core/profiles/select.d.ts

@@ -11,9 +11,6 @@ export declare function resolveProfileSearchAction(bindings: BindingResolution<B
 export declare function profileCoversCwd(entry: ProfileEntry, cwd: string): boolean;
 /** Resolve the headless selector against existing state without changing it. */
 export declare function selectProfileForCwdReadOnly(cwd: string): string;
-/** Collapse the home prefix to `~` so project paths read short. Exported so the
- *  Profiles settings panel prints a project dir exactly as this menu does. */
-export declare function tildify(p: string): string;
 /** Select the profile a node about to boot at `cwd` should run under.
  *
  *  1. `explicitProfile` present → resolve it as a user-typed operand (exact id,