pi-fold 3.1.0 → 4.1.0

package/extensions/lib/editor-ui.ts

@@ -33,6 +33,14 @@ export interface FoldEditorBlock {
 	kind?: string;
 	origin?: string;
 	brief?: string;
+	/** Where this fold's brief came from: deterministic, supplied or augmented. Given the
+	 *  campaign verdict on agent-written briefs, which sentence is the runtime's and which
+	 *  is the model's is the fact a person auditing this window most needs. */
+	provenance?: string;
+	/** The fold is EXPANDED IN THE MODEL'S WINDOW: its raw bytes are in the projection
+	 *  right now, reclaimed at the next commit unless pinned. Distinct in every way from
+	 *  the view's own open/closed state, which the reader owns and the model never sees. */
+	expandedInContext?: boolean;
 	sourceCount?: number;
 	rolesSummary?: string;
 	/** Estimated tokens this staged mark frees at the next commit; proposed blocks only. */
@@ -50,6 +58,9 @@ export interface FoldEditorData {
 		budgetTokens: number;
 		commitOccupancy: number;
 		commitDue: boolean;
+		/** Automatic folding has stopped. The editor is the surface a person opens in order
+		 *  to ACT, and without this it priced a countdown to a commit that cannot fire. */
+		suspended?: boolean;
 	};
 	/** Top-level blocks only: raw gaps and ROOT folds, in window order. */
 	blocks: FoldEditorBlock[];
@@ -61,24 +72,57 @@ export interface FoldEditorData {
 		freedTokens: number;
 	};
 	pinned: string[];
+	/** Fold ids the AGENT has standing raw in its window (state.expanded), not the view's
+	 *  own open rows. Absent on a host that predates the field. */
+	expandedInContext?: string[];
 }
 
 const BAR_WIDTH = 24;
 const MAX_VISIBLE_ROWS = 24;
 const EXPANDED_ENTRY_CAP = 40;
+/** How many raw messages one stretch renders. Raw stretches open by default now, so this
+ *  is the bound on the DEFAULT view rather than on a gesture, and it is high because the
+ *  claim the view makes is that it shows the model's window. A stretch that reaches it
+ *  says so on its summary row rather than stopping quietly. */
+const RAW_ENTRY_CAP = 500;
 
 export function occupancyBar(usedTokens: number | null, budgetTokens: number): string {
 	const ratio = usedTokens !== null && budgetTokens > 0
 		? Math.max(0, Math.min(1, usedTokens / budgetTokens))
 		: 0;
 	const filled = Math.round(ratio * BAR_WIDTH);
-	return `${"█".repeat(filled)}${"·".repeat(BAR_WIDTH - filled)}`;
+	// THE SAME ALPHABET /fold-status USES. The editor drew its empty cells with the middle
+	// dot that also separates the fields on that very line, so the bar's tail and the
+	// line's punctuation were the same glyph doing two jobs.
+	return `${"▇".repeat(filled)}${"░".repeat(BAR_WIDTH - filled)}`;
 }
 
 function shortId(id: string): string {
 	return id.length > 12 ? id.slice(0, 12) : id;
 }
 
+/**
+ * MARK ORIGINS IN THE READER'S OWN WORDS. The state's names are for the state: "ladder"
+ * is this runtime's internal name for its own automatic marking pass, and a person
+ * reading a proposed row needs to know WHO proposed the fold, not which code path
+ * staged it. An unrecognized origin passes through rather than being hidden, because a
+ * name we do not have a word for is still better than a blank.
+ *
+ * ONE WORD FOR ONE THING (2026-08-28): the rows said PROPOSED while the header said
+ * staged, for the same marks on the same screen, which asks a reader to learn that two
+ * words mean one thing before they can read either line.
+ */
+const ORIGIN_WORDS: Record<string, string> = {
+	ladder: "automatic",
+	agent: "the model",
+	user: "you",
+};
+
+function originWord(origin: string | undefined): string {
+	if (!origin) return "staged";
+	return ORIGIN_WORDS[origin] ?? origin;
+}
+
 /**
  * Assemble the top-level window stream. Committed folds nest by containment (a fold
  * whose span sits inside another becomes a CHILD of the innermost container), so the
@@ -92,6 +136,7 @@ export function buildFoldEditorData(
 		foldRows: () => Array<{
 			id: string; kind: string; brief: string; sourceCount: number;
 			startPosition: number; endPosition: number;
+			provenance?: string; expandedInContext?: boolean;
 			entries: FoldEditorEntry[];
 		}>;
 		pendingMarkRefs: () => Array<{ id: string; origin: string; brief: string; entryIds: string[] }>;
@@ -109,6 +154,8 @@ export function buildFoldEditorData(
 			endPosition: row.endPosition,
 			kind: row.kind,
 			brief: row.brief,
+			provenance: row.provenance,
+			expandedInContext: row.expandedInContext,
 			sourceCount: row.sourceCount,
 			entries: row.entries,
 			children: [],
@@ -165,7 +212,9 @@ export function buildFoldEditorData(
 		if (block.type === "raw") {
 			const roles = new Map<string, number>();
 			for (const entry of block.entries) roles.set(entry.role, (roles.get(entry.role) ?? 0) + 1);
-			block.rolesSummary = [...roles.entries()].map(([role, count]) => `${role}×${count}`).join(" ");
+			// "user×2 assistant×3" put the count behind the same bare multiplication sign the
+			// fold rows just lost. Count first, noun second, like everything else here.
+			block.rolesSummary = [...roles.entries()].map(([role, count]) => `${count} ${role}`).join(", ");
 		}
 	}
 
@@ -220,11 +269,16 @@ function briefChunks(brief: string): string[] {
 	return chunks;
 }
 
-/** Detail rows: the full preview (to 480 chars) wrapped like a brief, under the
- *  entry's own row. One long truncated line plus a mid-word continuation hid the
- *  middle of the text; wrapping shows all of it in reading order. */
+/** Detail rows: the entry's text wrapped like a brief, under its own row. One long
+ *  truncated line plus a mid-word continuation hid the middle of the text; wrapping shows
+ *  all of it in reading order.
+ *
+ *  NO SECOND BOUND OF ITS OWN (2026-08-30). This sliced to 480 characters against a
+ *  preview the data layer had already cut to 300, so the deeper number could never bind
+ *  and the whole surface stopped at 300 characters of one text block. What arrives here is
+ *  now whatever the caller chose to hand over, and the caller states its own cut. */
 function detailChunks(preview: string): string[] {
-	return briefChunks(preview.slice(0, 480));
+	return briefChunks(preview);
 }
 
 interface RenderRow {
@@ -240,6 +294,16 @@ interface RenderRow {
 	entryId?: string;
 	/** A PROPOSED row: withdrawable with u. */
 	proposedMarkId?: string;
+	/** A RAW-STRETCH summary row. Its open state lives in the INVERTED set, because raw
+	 *  stretches open by default; sniffing the key prefix for this would put the two
+	 *  opposite defaults one typo apart. */
+	rawBlockId?: string;
+	/** A FOLD row: pinnable, expandable into the model's window, dissolvable. Carries the
+	 *  fold's own id, which is not the row key: the key is path-qualified so a nested fold
+	 *  renders once per ancestor chain, and the runtime only ever accepts the bare id. */
+	foldId?: string;
+	/** The fold is expanded IN THE MODEL'S WINDOW right now, which is what e toggles. */
+	foldExpandedInContext?: boolean;
 }
 
 /** What laying a mark over a span WOULD commit: the size the user sees before staging. */
@@ -248,16 +312,33 @@ export interface SpanCost {
 	tokens: number;
 }
 
+/** One page of an entry's exact text, with the cut STATED rather than silent. */
+export interface EntryDetailPage {
+	text: string;
+	offset: number;
+	total: number;
+	hasMore: boolean;
+}
+
 export interface FoldEditorActions {
 	/** Live would-be fold size for a span of mapped indices, any order. */
 	spanCost?: (from: number, to: number) => SpanCost;
+	/** One page of an entry's exact text. A PURE READ: it moves no bytes, writes no state
+	 *  and never touches the projection, so paging an entry to its end is invisible to the
+	 *  model. This is the reader's depth, and it is not the window's. */
+	entryDetail?: (entryId: string, offset?: number, chars?: number) => EntryDetailPage | null;
 	/** Stage a USER mark over two raw entry ids through the validated path. The
 	 *  brief is what the user typed; empty means the deterministic brief. */
 	onStageMark?: (fromId: string, toId: string, brief?: string) => Promise<void>;
 	/** Withdraw one staged mark by id (the tool's unmark path). */
 	onWithdrawMark?: (markId: string) => Promise<void>;
-	/** Pin or unpin one raw entry; the handler decides which from current state. */
+	/** Pin or unpin one raw entry or one fold; the handler decides which from current state. */
 	onTogglePin?: (entryId: string) => Promise<void>;
+	/** Put a fold's raw bytes back into the MODEL's window, or take them out again. The
+	 *  view's own open/close key is a different act and never reaches this. */
+	onSetExpanded?: (foldId: string, expand: boolean) => Promise<void>;
+	/** Return a fold to raw so its boundary can be re-marked (the tool's reboundary path). */
+	onDissolveFold?: (foldId: string) => Promise<void>;
 }
 
 type ThemeFn = (color: string, text: string) => string;
@@ -270,7 +351,34 @@ export class FoldEditorView {
 	private actions: FoldEditorActions;
 	private selectedKey: string;
 	private expanded: Set<string> = new Set();
+	/**
+	 * RAW STRETCHES THE READER HAS CLOSED, which is the exception rather than the rule.
+	 *
+	 * THE DEFAULT VIEW IS WHAT THE MODEL SEES (2026-08-30). Raw entries used to hide behind
+	 * a "raw · 14 entries" summary row that had to be opened one stretch at a time, so the
+	 * one surface built to show a person the model's window opened showing almost none of
+	 * it. The model sees every one of those messages in full; it sees a fold as ONE
+	 * placeholder. So the editor now opens the same way: a row per raw message, a row per
+	 * fold, and digging into a fold reveals what the model is NOT being shown. Shane,
+	 * 2026-08-30, on pi's /tree: "I basically want something similar but suited to our
+	 * extension's needs."
+	 *
+	 * The summary row stays as a group label and a collapse target, because a long raw
+	 * stretch a reader has finished with is worth folding away FOR THE READER, which is a
+	 * different act from folding it for the model and costs the model nothing.
+	 */
+	private collapsedRaw: Set<string> = new Set();
+	/** The search term, or null when the reader is not searching. Narrowing NEVER hides a
+	 *  row silently: the count of what it removed is stated in the footer. */
+	private filter: string | null = null;
+	private searchMode = false;
+	private rowCache: { data: FoldEditorData; signature: string; rows: RenderRow[] } | null = null;
 	private detailedEntry: string | null = null;
+	/** Where the open detail is being read from, in characters. THE READER'S POSITION AND
+	 *  NOTHING ELSE: paging it moves no bytes, writes no state and the model never learns
+	 *  it happened. Reset whenever the open entry changes, so a short entry cannot inherit
+	 *  a long one's offset and render blank. */
+	private detailOffset = 0;
 	private scroll = 0;
 	/** The anchored mark point: first boundary of a span the user is laying down. */
 	private anchor: { key: string; id: string; index: number } | null = null;
@@ -316,6 +424,76 @@ export class FoldEditorView {
 		return this.data.pinned.includes(entryId) ? " 📌" : "";
 	}
 
+	/**
+	 * A FOLD IS PINNED THROUGH ITS MEMBERS, so its badge is counted rather than looked up.
+	 *
+	 * `protectEvidence` takes a fold id and holds every ref underneath it, so the pinned set
+	 * only ever contains ENTRY ids and a fold id is never in it. Reading the fold's own id
+	 * against that set is how a fold pinned by this very view rendered unpinned.
+	 *
+	 * PARTIAL IS STATED, not rounded to either end. A fold whose entries were pinned
+	 * individually, or one that lost some of its hold to an unpin, is neither held nor free,
+	 * and a badge that showed nothing there would hide exactly the state a person opened
+	 * this surface to find.
+	 */
+	private foldPinBadge(block: FoldEditorBlock): string {
+		const entries = block.entries ?? [];
+		if (!entries.length) return "";
+		const held = entries.filter((entry) => this.data.pinned.includes(entry.id)).length;
+		if (!held) return "";
+		return held === entries.length ? " 📌" : ` 📌 ${held}/${entries.length}`;
+	}
+
+	/**
+	 * THE OPEN ENTRY'S TEXT, ONE PAGE AT A TIME, AND THE CUT IS STATED (2026-08-30).
+	 *
+	 * Three sites rendered detail rows and all three read `entry.preview`, which the data
+	 * layer had cut to 300 characters of the first text block; `detailChunks` then sliced
+	 * to 480, a bound the shorter one could never reach. So this is the whole depth the
+	 * editor had. It now asks the injected accessor, which reads the exact message and
+	 * hands back a page with `total` and `hasMore` beside it, and falls back to the row
+	 * preview on a host that supplies no accessor.
+	 *
+	 * PAGING HERE IS NOT EXPANDING. Nothing on this path touches the projection: the
+	 * reader walks the entry to its end and the model's window is byte-identical
+	 * afterwards. Putting a fold's bytes back in front of the model is `e`, a different
+	 * key on a different path with a different cost.
+	 */
+	private pushDetail(rows: RenderRow[], entryKey: string, entry: FoldEditorEntry, pad: string): void {
+		const page = this.actions.entryDetail?.(entry.id, this.detailOffset) ?? null;
+		const body = page ? page.text : entry.preview;
+		let ordinal = 0;
+		for (const chunk of detailChunks(body)) {
+			rows.push({
+				key: `${entryKey}:d${ordinal}`,
+				text: `${pad}      ${this.color("dim", chunk)}`,
+				toggleId: null,
+			});
+			ordinal += 1;
+		}
+		if (!page) return;
+		const shown = page.offset + page.text.length;
+		if (shown >= page.total && page.offset === 0) return;
+		// A LIST THAT STOPS EARLY AND SAYS NOTHING READS AS A COMPLETE LIST (gate 136's
+		// law, on a surface a person reads rather than a brief a model reads). The
+		// position is stated in characters because that is the unit the keys move in.
+		rows.push({
+			key: `${entryKey}:more`,
+			text: `${pad}      ${this.color("warning",
+				`characters ${page.offset.toLocaleString("en-US")}-${shown.toLocaleString("en-US")} ` +
+				`of ${page.total.toLocaleString("en-US")}` +
+				`${page.hasMore ? " · ]:more" : ""}${page.offset > 0 ? " · [:back" : ""}`)}`,
+			toggleId: null,
+		});
+	}
+
+	/** Open, close or re-target the detail rows under one entry row. The offset resets on
+	 *  every change of subject, so a short entry never inherits a long one's position. */
+	private toggleDetail(rowKey: string): void {
+		this.detailedEntry = this.detailedEntry === rowKey ? null : rowKey;
+		this.detailOffset = 0;
+	}
+
 	private renderFold(block: FoldEditorBlock, depth: number, rows: RenderRow[], keyPrefix: string): void {
 		// COLLAPSED = ONE ROW (Shane, 2026-08-22): "fold {id}" alone, no END bookend.
 		// Start/end bookends exist only in the EXPANDED state. ROW KEYS ARE UNIQUE PER
@@ -326,13 +504,41 @@ export class FoldEditorView {
 		const foldKey = `${keyPrefix}${block.id}`;
 		const isOpen = this.expanded.has(foldKey);
 		const pad = "  ".repeat(depth);
-		const kindLabel = `${block.kind} \u00d7${block.sourceCount}`;
+		// THE ROW SAYS WHAT WAS FOLDED (2026-08-28). It read "fold fold_a1b2c3 chapter ×9":
+		// the word "fold" twice (the ▸ glyph is already the word), thirteen columns of an
+		// id nothing in this view accepts as input, and the brief that says what the fold
+		// COVERS hidden behind Enter. Twelve roots differed only by hex, which recreates
+		// inside the editor the exact defect /fold-status was rewritten to remove.
+		//
+		// The id is dropped rather than trailed: it is unusable here, the expanded state
+		// still carries it on the end bookend, and a trailing id is what truncation eats
+		// first anyway. "×9" becomes a counted noun, because ×9 could be entries, nesting
+		// depth or generations and the reader has no way to tell which.
+		const kindLabel = `${block.kind} · ${block.sourceCount} ` +
+			`${block.sourceCount === 1 ? "entry" : "entries"}`;
 		const marker = isOpen ? "\u25bc" : "\u25b8";
 		const foldCursor = this.selectedKey === foldKey ? "\u276f" : " ";
+		const [foldHead] = briefChunks(block.brief ?? "");
+		// WHAT THE MODEL IS ACTUALLY HOLDING (2026-08-30). Two facts the row could not
+		// carry, and both are what a person opens this surface to learn. A fold the agent
+		// has EXPANDED is standing raw in its window and costing it, and rendered
+		// identically to a placeholder; and a brief the MODEL wrote is a different kind of
+		// claim from one the runtime derived, which is the fact the campaign verdict made
+		// load-bearing. Neither is stated with an id: the badge is the word.
+		const contextBadge = block.expandedInContext
+			? ` ${this.color("warning", "· raw in the model's window")}`
+			: "";
+		const provenanceBadge = block.provenance && block.provenance !== "deterministic"
+			? ` ${this.color("accent", `· brief ${block.provenance}`)}`
+			: "";
 		rows.push({
 			key: foldKey,
-			text: `${foldCursor}${this.color("success", `${pad}${marker} fold ${shortId(block.id)}`)} ${kindLabel}`,
+			text: `${foldCursor}${this.color("success", `${pad}${marker} ${kindLabel}`)}` +
+				`${this.foldPinBadge(block)}${contextBadge}${provenanceBadge}` +
+				`${foldHead ? ` · ${foldHead}` : ""}`,
 			toggleId: foldKey,
+			foldId: block.id,
+			foldExpandedInContext: Boolean(block.expandedInContext),
 		});
 		if (!isOpen) return;
 		let ordinal = 0;
@@ -353,23 +559,19 @@ export class FoldEditorView {
 				? this.color("dim", ` \u201c${entry.preview.slice(0, 48)}\u201d`)
 				: "";
 			const entryCursor = this.selectedKey === entryKey ? "\u276f" : " ";
+			// AN ENTRY IS AN ENTRY WHEREVER IT SITS (2026-08-30). These rows carried no id
+			// the view could act on, so `p` was inert on every row inside an expanded fold
+			// while working one row over in a raw gap, for no reason a reader could see.
+			// They are not mark points: their span is already inside a fold, and gate 112
+			// refuses that by name, so `markable` stays off and only the pin id travels.
 			rows.push({
 				key: entryKey,
 				text: `${entryCursor}${pad}    ${this.color("dim", `\u00b7 ${entry.role} ${shortId(entry.id)}${this.pinnedBadge(entry.id)}`)}${quoted}`,
 				toggleId: null,
 				entryPreview: entry.preview,
+				entryId: entry.id,
 			});
-			if (detailed) {
-				let detailOrdinal = 0;
-				for (const chunk of detailChunks(entry.preview)) {
-					rows.push({
-						key: `${entryKey}:d${detailOrdinal}`,
-						text: `${pad}      ${this.color("dim", chunk)}`,
-						toggleId: null,
-					});
-					detailOrdinal += 1;
-				}
-			}
+			if (detailed) this.pushDetail(rows, entryKey, entry, pad);
 		}
 		const endCursor = this.selectedKey === `${foldKey}:end` ? "\u276f" : " ";
 		rows.push({
@@ -379,22 +581,43 @@ export class FoldEditorView {
 		});
 	}
 
-	private visibleRows(): RenderRow[] {
+	/**
+	 * ONE PREDICATE FOR TWO OPPOSITE DEFAULTS, so they cannot drift apart.
+	 *
+	 * A FOLD IS CLOSED BY DEFAULT because that is what the model sees: one placeholder.
+	 * A RAW STRETCH IS OPEN BY DEFAULT for exactly the same reason: the model sees every
+	 * message in it. The editor's default view is the model's own window, and opening a
+	 * fold is the one gesture that shows the reader something the model is not being
+	 * shown. Inverting the raw default is what turned this from a map of blocks into a
+	 * map of the window.
+	 */
+	private blockIsOpen(block: FoldEditorBlock): boolean {
+		return block.type === "raw" ? !this.collapsedRaw.has(block.id) : this.expanded.has(block.id);
+	}
+
+	private allRows(): RenderRow[] {
 		const rows: RenderRow[] = [];
 		for (const block of this.data.blocks) {
 			if (block.type === "fold") {
 				this.renderFold(block, 0, rows, "");
 				continue;
 			}
-			const isOpen = this.expanded.has(block.id);
+			const isOpen = this.blockIsOpen(block);
 			const cursor = this.selectedKey === block.id ? "\u276f" : " ";
 			if (block.type === "proposed") {
 				const isLadder = block.origin === "ladder";
 				const color = isLadder ? "warning" : "accent";
-				const sizeNote = typeof block.tokens === "number" ? ` · ~${block.tokens.toLocaleString("en-US")} tok` : "";
+				const sizeNote = typeof block.tokens === "number"
+					? ` · frees ~${block.tokens.toLocaleString("en-US")} tokens` : "";
+				const [stagedHead] = briefChunks(block.brief ?? "");
 				rows.push({
 					key: block.id,
-					text: `${cursor}${this.color(color, `\u25c7 PROPOSED (${block.origin}) ${shortId(block.id)}`)} \u00d7${block.sourceCount}${sizeNote}${this.selectedKey === block.id ? " · u:withdraw" : ""}`,
+					// Same treatment as the fold row: no id, a counted noun, and the brief seated
+					// as the tail so it is what degrades if the terminal is narrow.
+					text: `${cursor}${this.color(color, `\u25c7 staged by ${originWord(block.origin)}`)}` +
+						` · ${block.sourceCount} ${block.sourceCount === 1 ? "entry" : "entries"}${sizeNote}` +
+						`${stagedHead ? ` · ${stagedHead}` : ""}` +
+						`${this.selectedKey === block.id ? " · u:withdraw" : ""}`,
 					toggleId: block.id,
 					proposedMarkId: block.id,
 				});
@@ -411,26 +634,38 @@ export class FoldEditorView {
 						// resolves them); an entry that fell off the map renders id-only.
 						const label = ["\u00b7", entry.role, `${shortId(entry.id)}${this.pinnedBadge(entry.id)}`]
 							.filter(Boolean).join(" ");
-						const quoted = entry.preview ? ` \u201c${entry.preview.slice(0, 48)}\u201d` : "";
+						const detailed = this.detailedEntry === entryKey;
+						const quoted = !detailed && entry.preview
+							? ` \u201c${entry.preview.slice(0, 48)}\u201d` : "";
 						rows.push({
 							key: entryKey,
 							text: `${this.selectedKey === entryKey ? "\u276f" : " "}    ${this.color("dim", `${label}${quoted}`)}`,
 							toggleId: null,
 							entryPreview: entry.preview,
+							entryId: entry.id,
 						});
+						if (detailed) this.pushDetail(rows, entryKey, entry, "");
 					}
 				}
 			} else {
-				const label = `\u00b7 raw \u00d7${block.sourceCount}` +
-					`${block.rolesSummary ? ` ${block.rolesSummary}` : ""}`;
+				// THE MARKER SAYS WHICH WAY THIS ROW GOES, because raw stretches now open by
+				// default and a reader meeting a closed one has to be able to tell it apart from
+				// a stretch that is simply empty. "hidden from this view only" is the whole
+				// distinction the surface rests on, said where it is easiest to get wrong.
+				const marker = isOpen ? "\u25bc" : "\u25b8";
+				const label = `${marker} raw · ${block.sourceCount} ` +
+					`${block.sourceCount === 1 ? "entry" : "entries"}` +
+					`${block.rolesSummary ? ` ${block.rolesSummary}` : ""}` +
+					`${isOpen ? "" : " · hidden from this view only"}`;
 				rows.push({
 					key: block.id,
 					text: `${cursor}${this.color("dim", label)}`,
 					toggleId: block.id,
+					rawBlockId: block.id,
 				});
 				if (isOpen) {
 					let ordinal = 0;
-					for (const entry of block.entries.slice(0, 60)) {
+					for (const entry of block.entries.slice(0, RAW_ENTRY_CAP)) {
 						const pinBadge = this.data.pinned.includes(entry.id) ? " \ud83d\udccc" : "";
 						const entryKey = `${block.id}:${entry.id}:r${ordinal}`;
 						ordinal += 1;
@@ -454,18 +689,11 @@ export class FoldEditorView {
 							text: `${cursor}    ${this.color("dim", `\u00b7 ${entry.role} ${shortId(entry.id)}${pinBadge}`)}${badge}${quoted}`,
 							toggleId: null,
 							entryPreview: entry.preview,
-							...(markable ? { markable: true, entryIndex: entry.index, entryId: entry.id } : {}),
+							entryId: entry.id,
+							...(markable ? { markable: true, entryIndex: entry.index } : {}),
 						});
 						if (detailed) {
-							let detailOrdinal = 0;
-							for (const chunk of detailChunks(entry.preview)) {
-								rows.push({
-									key: `${entryKey}:d${detailOrdinal}`,
-									text: `      ${this.color("dim", chunk)}`,
-									toggleId: null,
-								});
-								detailOrdinal += 1;
-							}
+							this.pushDetail(rows, entryKey, entry, "");
 						}
 					}
 				}
@@ -474,6 +702,65 @@ export class FoldEditorView {
 		return rows;
 	}
 
+	/**
+	 * WHAT THE READER IS LOOKING FOR, AND WHAT THAT HID.
+	 *
+	 * pi's /tree narrows by typing and the editor had no way to narrow at all, which is
+	 * survivable at a dozen blocks and useless at the density this view now opens with.
+	 * The term matches a row's rendered text, colour codes and all removed, so what is
+	 * searched is exactly what is on screen.
+	 *
+	 * A ROW KEEPS ITS PARENTS. A matching entry three levels inside a fold, shown alone,
+	 * is a line of text with no statement of where it came from, so every ancestor of a
+	 * match is kept: the reader sees the match seated in the structure that explains it.
+	 *
+	 * AND THE OMISSION IS COUNTED, never silent, which is gate 136's law on a surface a
+	 * person acts from. The footer states how many rows the term removed.
+	 */
+	private filterRows(rows: RenderRow[]): RenderRow[] {
+		const term = this.filter?.trim().toLowerCase();
+		if (!term) return rows;
+		const plain = (text: string): string => text.replace(/\[\/?[a-z]+\]/g, "").toLowerCase();
+		const keep = new Set<number>();
+		for (let index = 0; index < rows.length; index += 1) {
+			if (!plain(rows[index].text).includes(term)) continue;
+			keep.add(index);
+			// Walk back to the ancestors: a row's key is path-qualified, so any earlier row
+			// whose key is a prefix of this one is one of its parents.
+			for (let back = index - 1; back >= 0; back -= 1) {
+				if (rows[index].key.startsWith(rows[back].key)) keep.add(back);
+			}
+		}
+		return rows.filter((_row, index) => keep.has(index));
+	}
+
+	/**
+	 * THE ROW LIST, BUILT ONCE PER STATE. Every keystroke asks for it two or three times
+	 * (the move, the scroll clamp and the render), and the default view is now a row per
+	 * message rather than a row per block, so a session of a few thousand entries would
+	 * rebuild a few thousand strings three times for one arrow key. The signature is every
+	 * piece of view state a row's text reads; `data` is compared by IDENTITY, because
+	 * `refresh` always hands over a freshly built object and a mutated one would be a
+	 * defect one layer up.
+	 */
+	private visibleRows(): RenderRow[] {
+		const signature = [
+			this.selectedKey,
+			this.detailedEntry ?? "",
+			this.detailOffset,
+			this.filter ?? "",
+			this.anchor?.key ?? "",
+			[...this.expanded].sort().join(","),
+			[...this.collapsedRaw].sort().join(","),
+		].join("|");
+		if (this.rowCache && this.rowCache.data === this.data && this.rowCache.signature === signature) {
+			return this.rowCache.rows;
+		}
+		const rows = this.filterRows(this.allRows());
+		this.rowCache = { data: this.data, signature, rows };
+		return rows;
+	}
+
 	private move(delta: number): void {
 		const rows = this.visibleRows();
 		if (!rows.length) return;
@@ -499,6 +786,19 @@ export class FoldEditorView {
 			this.handleBriefInput(data);
 			return;
 		}
+		// SEARCH IS A MODE, NOT A KEY, because every letter here already means something.
+		// pi's /tree can narrow on any keystroke since it has no single-letter actions;
+		// this view has m, p, e, r and u, so typing has to be entered deliberately. `/`
+		// opens it, which is what a reader coming from less, vim or a browser will try.
+		if (this.searchMode) {
+			this.handleSearchInput(data);
+			return;
+		}
+		if (data === "/") {
+			this.searchMode = true;
+			this.filter = this.filter ?? "";
+			return;
+		}
 		if (data === "u") {
 			this.handleWithdrawKey();
 			return;
@@ -507,13 +807,34 @@ export class FoldEditorView {
 			this.handlePinKey();
 			return;
 		}
+		if (data === "e") {
+			this.handleExpandKey();
+			return;
+		}
+		if (data === "r") {
+			this.handleDissolveKey();
+			return;
+		}
+		if (data === "]" || data === "[") {
+			this.handlePageKey(data === "]" ? 1 : -1);
+			return;
+		}
 		if (data === "m") {
 			this.handleMarkKey();
 			return;
 		}
 		if (this.kb.matches(data, "tui.select.cancel")) {
-			// ESCAPE CANCELS WORK FIRST, STEPWISE: the brief line, then the anchor, and
-			// only then the editor. Nothing the user laid down is lost by one press.
+			// ESCAPE CANCELS WORK FIRST, STEPWISE: the search, then the brief line, then the
+			// anchor, and only then the editor. Nothing the user laid down is lost by one
+			// press, and a reader who narrowed the view and forgot gets the window back
+			// before they get the exit.
+			if (this.filter !== null) {
+				this.filter = null;
+				this.searchMode = false;
+				this.selectedKey = this.visibleRows()[0]?.key ?? "";
+				this.scrollToSelection();
+				return;
+			}
 			if (this.anchor !== null) {
 				this.anchor = null;
 				this.notice = null;
@@ -533,6 +854,21 @@ export class FoldEditorView {
 				this.expanded.delete(target);
 				this.selectedKey = target;
 				this.scrollToSelection();
+			} else {
+				// LEFT CLOSES AN OPEN RAW STRETCH for the same reason it collapses a fold:
+				// it is the key that means "less of this". Without it raw stretches could be
+				// closed only from their own summary row, which is off screen for a reader
+				// standing deep inside a long one.
+				const rows = this.visibleRows();
+				const at = rows.findIndex((candidate) => candidate.key === this.selectedKey);
+				for (let back = at; back >= 0; back -= 1) {
+					const owner = rows[back].rawBlockId;
+					if (!owner || !this.selectedKey.startsWith(owner)) continue;
+					this.collapsedRaw.add(owner);
+					this.selectedKey = owner;
+					this.scrollToSelection();
+					break;
+				}
 			}
 		}
 		else if (this.kb.matches(data, "tui.select.confirm") ||
@@ -540,17 +876,53 @@ export class FoldEditorView {
 			const row = this.visibleRows().find((candidate) => candidate.key === this.selectedKey);
 			if (!row) return;
 			if (row.toggleId) {
-				if (this.expanded.has(row.toggleId)) this.expanded.delete(row.toggleId);
-				else this.expanded.add(row.toggleId);
+				this.toggleBlock(row);
 				this.scrollToSelection();
 			} else if (row.entryPreview !== undefined) {
-				this.detailedEntry = this.detailedEntry === row.key ? null : row.key;
+				this.toggleDetail(row.key);
 				this.scrollToSelection();
 			}
 		}
 	}
 
 	/** The deepest expanded fold named in a row key (keys look like "a>b:c"). */
+	/** Typing while the search line is open. Enter leaves the line with the term standing,
+	 *  so the reader gets their action keys back without losing the narrowing; Escape
+	 *  drops the term as well, one press per thing given up. */
+	private handleSearchInput(data: string): void {
+		if (data === "\r" || data === "\n") {
+			this.searchMode = false;
+			return;
+		}
+		if (data === "\x7f" || data === "\b") {
+			this.filter = (this.filter ?? "").slice(0, -1);
+		} else if (data === "\x1b") {
+			this.filter = null;
+			this.searchMode = false;
+		} else if (!data.startsWith("\x1b") && data >= " ") {
+			this.filter = `${this.filter ?? ""}${data}`;
+		} else {
+			return;
+		}
+		const rows = this.visibleRows();
+		if (!rows.some((row) => row.key === this.selectedKey)) {
+			this.selectedKey = rows[0]?.key ?? "";
+		}
+		this.scroll = 0;
+	}
+
+	/** Open or close one block, in whichever sense that block's default runs. */
+	private toggleBlock(row: RenderRow): void {
+		if (row.rawBlockId) {
+			if (this.collapsedRaw.has(row.rawBlockId)) this.collapsedRaw.delete(row.rawBlockId);
+			else this.collapsedRaw.add(row.rawBlockId);
+			return;
+		}
+		const id = row.toggleId!;
+		if (this.expanded.has(id)) this.expanded.delete(id);
+		else this.expanded.add(id);
+	}
+
 	private innermostOpenFold(key: string): string | null {
 		const chain = key.split(":")[0].split(">");
 		for (let index = chain.length - 1; index >= 0; index -= 1) {
@@ -650,18 +1022,90 @@ export class FoldEditorView {
 			});
 	}
 
-	/** p ON A RAW ENTRY toggles its pin (the tool's pin/unpin path). */
+	/**
+	 * p TOGGLES A PIN, on any row that names something the runtime can hold.
+	 *
+	 * IT USED TO REQUIRE `markable` (2026-08-30). That flag means "this raw entry can be a
+	 * mark point", which is a fact about FOLDING a span, and it has nothing to do with
+	 * holding one. The effect was that `p` worked on a raw entry inside a raw gap, did
+	 * nothing at all on the identical entry inside an expanded fold, and did nothing on a
+	 * fold row, while the tool's own pin action has always taken either an entry id or a
+	 * fold id. The view was narrower than the path it is a skin over, for no reason a
+	 * reader could see.
+	 */
 	private handlePinKey(): void {
 		if (this.staging || this.briefMode) return;
 		const row = this.visibleRows().find((candidate) => candidate.key === this.selectedKey);
-		if (!row || !row.markable || !row.entryId) return;
+		const target = row?.entryId ?? row?.foldId;
+		if (!target) return;
 		if (!this.actions.onTogglePin) {
 			this.notice = "pinning is not wired in this view";
 			return;
 		}
+		this.runAction(this.actions.onTogglePin(target));
+	}
+
+	/**
+	 * e PUTS A FOLD'S BYTES BACK IN FRONT OF THE MODEL, or takes them out again.
+	 *
+	 * THE OTHER EXPANSION, and the distinction is the point (Shane, 2026-08-30: the reader
+	 * should be able to "page through/expand for their own viewing purposes" while
+	 * "setting an expanded fold is a different choice"). Enter and the arrow keys open a
+	 * fold FOR THE READER: they move a key in a Set this view owns, cost nothing and are
+	 * invisible to the model. This restores the fold's raw source to the PROJECTION, which
+	 * costs the window and is reclaimed at the next commit unless the fold is pinned. Two
+	 * acts, two keys, and the row says which state it is in.
+	 */
+	private handleExpandKey(): void {
+		if (this.staging || this.briefMode) return;
+		const row = this.visibleRows().find((candidate) => candidate.key === this.selectedKey);
+		if (!row?.foldId) return;
+		if (!this.actions.onSetExpanded) {
+			this.notice = "expanding into the window is not wired in this view";
+			return;
+		}
+		this.runAction(this.actions.onSetExpanded(row.foldId, !row.foldExpandedInContext));
+	}
+
+	/** r RETURNS A FOLD TO RAW so its boundary can be re-marked (the tool's reboundary
+	 *  path). Re-cutting is this plus `m` on the two entries the person meant, which the
+	 *  view already has, so this is the half that was missing. */
+	private handleDissolveKey(): void {
+		if (this.staging || this.briefMode) return;
+		const row = this.visibleRows().find((candidate) => candidate.key === this.selectedKey);
+		if (!row?.foldId) return;
+		if (!this.actions.onDissolveFold) {
+			this.notice = "re-cutting is not wired in this view";
+			return;
+		}
+		this.runAction(this.actions.onDissolveFold(row.foldId));
+	}
+
+	/** ] and [ page the OPEN DETAIL. A pure read: the offset is the reader's position and
+	 *  nothing on this path reaches the projection. */
+	private handlePageKey(direction: number): void {
+		if (this.staging || this.briefMode || !this.detailedEntry) return;
+		const row = this.visibleRows().find((candidate) => candidate.key === this.detailedEntry);
+		const entryId = row?.entryId;
+		if (!entryId || !this.actions.entryDetail) return;
+		const page = this.actions.entryDetail(entryId, this.detailOffset);
+		if (!page) return;
+		if (direction > 0) {
+			if (!page.hasMore) return;
+			this.detailOffset = page.offset + page.text.length;
+		} else {
+			if (page.offset === 0) return;
+			this.detailOffset = Math.max(0, page.offset - Math.max(1, page.text.length));
+		}
+		this.scrollToSelection();
+	}
+
+	/** One in-flight edit at a time, with the refusal shown rather than thrown: every
+	 *  action here is a skin over a validated path, and those refuse by name. */
+	private runAction(work: Promise<void>): void {
 		this.staging = true;
 		this.notice = null;
-		void this.actions.onTogglePin(row.entryId)
+		void work
 			.then(() => {
 				this.staging = false;
 			})
@@ -673,41 +1117,115 @@ export class FoldEditorView {
 
 	private headerLines(width: number): string[] {
 		const lines: string[] = [];
-		const { occupancy, pending } = this.data;
+		const { occupancy } = this.data;
 		lines.push(truncateToWidth(`── ${this.data.title} ──`, width));
-		const percent = occupancy.usedTokens !== null && occupancy.budgetTokens > 0
-			? ((occupancy.usedTokens / occupancy.budgetTokens) * 100).toFixed(1)
-			: "?";
-		const usedTokensText = occupancy.usedTokens !== null
-			? occupancy.usedTokens.toLocaleString("en-US")
-			: "?";
+		// UNMEASURED IS PROSE, NEVER A BAR. An empty bar beside "?%" reads to the eye as
+		// a window that is 0 percent full, which is a guess wearing the costume of a
+		// measurement: the exact failure the other three surfaces already refuse, on the
+		// one surface the rule was never checked against. Nothing here is estimated.
+		if (occupancy.usedTokens === null || !(occupancy.budgetTokens > 0)) {
+			lines.push(truncateToWidth(
+				"window not measured yet; the first model response will measure it", width));
+			for (const line of this.stagedLines()) lines.push(truncateToWidth(line, width));
+			return lines;
+		}
+		// A WHOLE PERCENT. The tenth was false precision on a figure that moves with every
+		// message, and it read as a measurement finer than the thing being measured. The
+		// other three human surfaces round, so this one does too. Past the guard above,
+		// both values are known, so neither can render as "?".
+		const percent = Math.round((occupancy.usedTokens / occupancy.budgetTokens) * 100);
+		const usedTokensText = occupancy.usedTokens.toLocaleString("en-US");
+		// The DISTANCE to the commit, not just the share it fires at. "commit at 80%" is
+		// a property of the configuration; "29,674 to go" is the answer to the question
+		// the reader actually has, and it is the same number /fold-status states.
+		const headroom = occupancy.usedTokens !== null && occupancy.budgetTokens > 0 && !occupancy.commitDue
+			? ` (${Math.round(occupancy.commitOccupancy * occupancy.budgetTokens - occupancy.usedTokens)
+				.toLocaleString("en-US")} to go)`
+			: "";
+		// Same ordering rule as the line below it: the raw token pair is the most
+		// expendable thing here, because the percentage in front of it already says what
+		// it says. At 80 columns the first draft cut the headroom instead.
+		// A STOPPED WINDOW IS TOLD SO, NOT GIVEN A COUNTDOWN. Every other surface reports
+		// the suspension and this one alone kept pricing the distance to a commit that
+		// will not happen, which is the one state here that can cost somebody a session.
+		const timing = occupancy.suspended
+			? " · FOLDING STOPPED"
+			: ` · commit at ${(occupancy.commitOccupancy * 100).toFixed(0)}%${headroom}` +
+				`${occupancy.commitDue ? " · COMMIT DUE" : ""}`;
 		lines.push(truncateToWidth(
 			`${occupancyBar(occupancy.usedTokens, occupancy.budgetTokens)} ` +
-			`${percent}% · ${usedTokensText}/${occupancy.budgetTokens.toLocaleString("en-US")} tokens · ` +
-			`commit at ${(occupancy.commitOccupancy * 100).toFixed(0)}%` +
-			`${occupancy.commitDue ? " · COMMIT DUE" : ""}`,
-			width,
-		));
-		lines.push(truncateToWidth(
-			`staged marks: ${pending.count} (${pending.agentMarks} agent, ${pending.ladderMarks} ladder` +
-			`${pending.userMarks > 0 ? `, ${pending.userMarks} you` : ""})` +
-			` · about ${pending.freedTokens.toLocaleString("en-US")} tokens freed when committed · ` +
-			`pinned: ${this.data.pinned.length}`,
+			`${percent}%${timing}` +
+			` · ${usedTokensText}/${occupancy.budgetTokens.toLocaleString("en-US")}`,
 			width,
 		));
+		for (const line of this.stagedLines()) lines.push(truncateToWidth(line, width));
 		return lines;
 	}
 
+	/**
+	 * ORDERED SO TRUNCATION COSTS THE LEAST. This line is cut to the terminal's width, and
+	 * at 100 columns the first draft lost the pin count off the end while spending its
+	 * width on who staged what. What the marks free and what is pinned are facts about the
+	 * window; the origin breakdown is colour, so it goes last.
+	 */
+	private stagedLines(): string[] {
+		const { pending } = this.data;
+		// The same vocabulary as ORIGIN_WORDS above, inflected for a count rather than a
+		// label: "1 automatic" and "2 by the model" read where "2 the model" does not.
+		// Only origins that actually staged something are listed, because a run of zeroes
+		// spends the line's width saying nothing happened three different ways.
+		const origins = [
+			pending.ladderMarks > 0 ? `${pending.ladderMarks} automatic` : "",
+			pending.agentMarks > 0 ? `${pending.agentMarks} by the model` : "",
+			pending.userMarks > 0 ? `${pending.userMarks} yours` : "",
+		].filter((part) => part !== "").join(", ");
+		// TWO LINES RATHER THAN ONE THAT RUNS OFF THE TERMINAL. At 97 characters the single
+		// line ended mid-phrase at "2 by the model" on any normal window; vertical space is
+		// cheaper than a sentence cut in half. The facts about the window come first and
+		// who staged what follows, so a narrow terminal still keeps the first line whole.
+		// "folds" not "marks": /fold-status and the always-on line both say folds, and one
+		// object carrying two nouns on adjacent surfaces is a thing to learn for nothing.
+		const staged = [`staged: ${pending.count} fold${pending.count === 1 ? "" : "s"}` +
+			` · frees ~${pending.freedTokens.toLocaleString("en-US")} tokens at commit` +
+			` · ${this.data.pinned.length} pinned` +
+			// EXPANDED IS A CLAIM ON THE WINDOW and belongs beside pinned, which is the
+			// other one. Both hold raw bytes in front of the model; only one of them is
+			// reclaimed automatically, and a reader cannot tell how much is being held
+			// without seeing both counts together.
+			`${this.data.expandedInContext?.length ? ` · ${this.data.expandedInContext.length} expanded` : ""}`];
+		if (origins) staged.push(`staged by: ${origins}`);
+		return staged;
+	}
+
 	render(width: number): string[] {
 		const header = this.headerLines(width);
 		const rows = this.visibleRows();
+		// WHAT THE SEARCH REMOVED IS COUNTED, never silently absent. A narrowed view that
+		// says nothing reads as the whole window, which is gate 136's law on the surface a
+		// person acts from: they would mark, pin or dissolve believing they had seen
+		// everything. The term is echoed because a filter left standing from three minutes
+		// ago is the other half of the same mistake.
+		if (this.filter !== null) {
+			const total = this.allRows().length;
+			const cursorMark = this.searchMode ? "\u2588" : "";
+			header.push(truncateToWidth(
+				`search: ${this.filter}${cursorMark} \u00b7 ${rows.length} of ${total} rows` +
+				`${this.searchMode ? " \u00b7 Enter:keep \u00b7 Esc:clear" : " \u00b7 Esc:clear"}`,
+				width));
+		}
 		if (!rows.length) {
-			return [...header, "", truncateToWidth("(empty window)", width)];
+			return [...header, "", truncateToWidth(this.filter
+				? `nothing matches "${this.filter}" \u00b7 Esc:clear`
+				: "(empty window)", width)];
 		}
 		this.scroll = Math.max(0, Math.min(this.scroll, Math.max(0, rows.length - MAX_VISIBLE_ROWS)));
 		const body = rows
 			.slice(this.scroll, this.scroll + MAX_VISIBLE_ROWS)
-			.map((row) => truncateToWidth(row.text, width, ""));
+			// THE PROJECT'S OWN BOUNDING LAW (gate 136): "..." means content continues in the
+			// source and never appears when nothing was cut. Header lines already take the
+			// default marker; body rows passed "" and were cut mid-word in silence, so the
+			// display layer contradicted the rule the briefs it displays all obey.
+			.map((row) => truncateToWidth(row.text, width));
 		// THE WOULD-BE FOLD SIZE (Shane, 2026-08-23): while a span is being laid down,
 		// the footer states what the second mark point would commit, in the runtime's
 		// own token arithmetic -- the same numbers the staged mark will answer with.
@@ -733,7 +1251,18 @@ export class FoldEditorView {
 			"",
 			...body,
 			...footers,
-			truncateToWidth("enter:expand/detail · arrows:navigate · m:mark raw span · esc:close", width, ""),
+			// EVERY KEY THAT CHANGES SOMETHING IS NAMED. p and u changed state and were named
+			// nowhere while the header printed a pin count on every render; e and r joined
+			// them on 2026-08-30. "raw span" stays: it is the word explaining why m does
+			// nothing on a fold row.
+			//
+			// ORDERED BY WHAT TRUNCATION SHOULD COST LEAST, and the ordering carries the
+			// distinction the surface is built on: enter opens a fold FOR THE READER and e
+			// opens it INTO THE MODEL'S WINDOW, so "open" and "show model" sit apart and are
+			// worded apart. A reader who learns only that enter opens things has learned the
+			// free one, which is the safe half to learn first.
+			truncateToWidth("enter:open · ]/[:page · arrows:move · m:mark raw span · p:pin · " +
+				"e:show model · r:re-cut · u:withdraw · esc:close", width),
 		];
 	}
 }