pi-blackhole 0.3.4 → 0.3.7

package/README.md

@@ -160,6 +160,11 @@ Root cause is a missing token refresh...
 
 ---
 
+---
+The conversation before this point has been compacted into the summary above.
+Details not captured here — exact code, error messages, file paths — are only recoverable via `recall`.
+Use `recall` to search the session history. Do not redo work already completed.
+
 ## Reflections
 [c3d4e5f6a1b2] User is building Acme Dashboard on Next.js 15 with Supabase auth.
 
@@ -168,20 +173,14 @@ Root cause is a missing token refresh...
 [b2c3d4e5f6a1] 2026-05-23 [medium] GraphQL migration completed; user confirmed working.
 
 ----
-Use `recall` to search for prior work, decisions, and context from before this summary. Do not redo work already completed.
-
-These are condensed memories from earlier in this session.
-
-- Reflections: stable, long-lived facts about the user, project, decisions, and constraints.
-- Observations: timestamped events from the conversation history, in chronological order.
-
-Treat these as past records. When entries conflict, the most recent observation reflects the latest known state. Work that prior observations describe as completed should not be redone unless the user explicitly asks to revisit it.
-
-When exact source context is needed for precision or traceability, use the `recall` tool with the relevant observation or reflection id.
+Bracketed ids in reflections and observations connect to their source session entries. These are condensed memories from earlier in this session.
+When entries conflict, the most recent observation reflects the latest known state.
+Use `recall` with an id to retrieve original context, or `#N:path` drill-down to explore file content from referenced entries.
+When exact source context is needed for precision or traceability, use the `recall` tool with the relevant observation or reflection id. This is especially useful when a reflection materially affects a decision or is too compressed to continue confidently.
 ----
 ```
 
-> **Note:** The OM injection format uses `## Reflections` and `## Observations` Markdown headers with a preamble and footer. Each observation and reflection has a 12-char hex identifier you can use with the `recall` tool to recover source evidence, as well as the agent can search based on them and get relevant context back.
+> **Note:** The OM injection format uses `## Reflections` and `## Observations` Markdown headers followed by a brief footer. Each observation and reflection has a 12-char hex identifier you can use with the `recall` tool to recover source evidence, as well as the agent can search based on them and get relevant context back. When no observations or reflections exist, only a short recall-guidance footer is appended.
 
 ---
 
@@ -245,7 +244,6 @@ The agent gets a unified `recall` tool that handles three types of input:
 | `#N:path` | Drill-down into file content from a tool call (e.g. `#42:auth.ts` shows first 30 lines; `#42:auth.ts:30` shows next 30; `#42:auth.ts:full` shows everything) |
 | Free text | BM25-ranked OR search across transcript and/or file content. Rare terms weighted higher. |
 | `mode:file` | Search only write/edit file content |
-| `mode:transcript` | Search only conversation text |
 | `mode:touched` | Aggregate all files written/edited, grouped by path with entry indices |
 | Regex | Pattern search (e.g. `fork.*pi-vcc`, `hook|inject`) |
 | `scope:all` | Search across all session lineages, not just the active one |
@@ -254,7 +252,7 @@ The agent gets a unified `recall` tool that handles three types of input:
 
 ## Configuration
 
-All settings in a single JSON file: **`~/.pi/agent/pi-blackhole/pi-blackhole-config.json`** — auto-created with defaults on first startup. See [`CONFIG.md`](CONFIG.md) for the full reference with detailed explanations for every knob. An annotated example config with the new config surface is at [`example-config-v2.json`](example-config-v2.json). The legacy example is at [`example-config.json`](example-config.json).
+All settings in a single JSON file: **`~/.pi/agent/pi-blackhole/pi-blackhole-config.json`** — auto-created with defaults on first startup. See [`CONFIG.md`](CONFIG.md) for the full reference with detailed explanations for every knob. An annotated example config is at [`example-config.json`](example-config.json).
 
 Quick start — just set custom models (if you want):
 
@@ -274,12 +272,13 @@ Everything else has sensible defaults.
 |---|---|---|
 | `compaction` | `"auto"` | When compaction triggers: `"auto"` (blackhole auto-fires), `"manual"` (only `/blackhole`), `"off"` (Pi handles auto + `/compact`, `/blackhole` still works) |
 | `compactionEngine` | `"blackhole"` | Which engine handles auto-compaction: `"blackhole"` or `"pi-default"`. Only meaningful when `compaction: "auto"` — for `"manual"`/`"off"` the hook lets Pi handle everything except `/blackhole` |
-| `tailBehavior` | `"minimal"` | How much of the transcript stays visible after compaction: `"minimal"` (last user message only, default) or `"pi-default"` (gentle, ~20k tokens) |
+| `tailBehavior` | `"minimal"` | How much stays visible after compaction: `"minimal"` (last user message only, default) or `"pi-default"` (gentle, ~20k tokens). Both `/blackhole` and auto-triggered default to `"minimal"`; set explicitly to opt into gentler cut |
 | `memory` | `true` | `false` = OM workers off + no memory injection (compaction still runs) |
 | `model` | — | Base fallback model for all workers (last resort before session model) |
 | `observerModel` / `observerFallbackModels` | — / `[]` | Primary + fallback models for observer (extracts facts) |
 | `reflectorModel` / `reflectorFallbackModels` | — / `[]` | Primary + fallback models for reflector (synthesizes reflections) |
 | `dropperModel` / `dropperFallbackModels` | — / `[]` | Primary + fallback models for dropper (prunes observations) |
+| `sessionFallback` | `true` | When false, skip session model fallback when all OM model candidates are exhausted. Default true for backward compatibility. |
 | *(per model)* `thinking` | `"low"` | Thinking/reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
 | *(per model)* `cooldownHours` | `1` | How long to skip this model after a retryable error |
 | *(per model)* `contextWindow` | *(inherited from Pi)* | Override context window for this model. If unset, inherits from Pi's model registry. When set, the OM pipeline checks if the estimated input fits before calling the model — if not, the next fallback is tried. |
@@ -453,7 +452,6 @@ The agent gets one unified tool that searches session history, expands entries,
 | `#N:path` | Drill-down into file content from a tool call (e.g. `#42:auth.ts` shows first 30 lines; `#42:auth.ts:30` shows next 30; `#42:auth.ts:full` shows everything) |
 | Free text | BM25-ranked OR search across transcript + file indicators. Rare terms weighted higher. |
 | `mode:file` | Search only write/edit file content |
-| `mode:transcript` | Search only conversation text |
 | `mode:touched` | Aggregate all files written/edited across the session, grouped by path with entry indices |
 | Regex | Pattern search (e.g. `fork.*pi-vcc`, `hook\|inject`) |
 | `scope:all` | Search across all session lineages (default: active lineage only) |
@@ -470,7 +468,6 @@ Results are shown as a collapsible message and auto-fed to the agent as context.
 /blackhole-recall hook|inject                       # regex
 /blackhole-recall fail.*build scope:all             # regex across all lineages
 /blackhole-recall mode:file                         # search only write/edit file content
-/blackhole-recall mode:transcript                   # search only conversation
 /blackhole-recall mode:touched                      # aggregate view of all files touched
 /blackhole-recall                                   # recent 25 entries
 ```

package/example-config.json

@@ -1,10 +1,12 @@
 {
-  "_comment": "blackhole unified configuration — ~/.pi/agent/pi-blackhole/pi-blackhole-config.json",
+  "_comment": "blackhole unified configuration v2 — ~/.pi/agent/pi-blackhole/pi-blackhole-config.json",
   "_all_settings_in_one_file": true,
+  "_new_keys": "compaction, compactionEngine, tailBehavior, sessionFallback — new config surface",
+  "_renamed": "was example-config-v2.json; old example-config.json → example-config-old.json",
 
-  "overrideDefaultCompaction": false,
-  "noAutoCompact": false,
-  "debug": false,
+  "compaction": "auto",
+  "compactionEngine": "blackhole",
+  "tailBehavior": "minimal",
 
   "model": {
     "_comment": "Base model (last fallback before session model).",
@@ -98,33 +100,23 @@
   "agentMaxTurns": 16,
 
   "memory": true,
-  "passive": false,
-  "noAutoCompact": false,
+  "sessionFallback": true,
+  "debug": false,
   "debugLog": false,
 
   "_notes": [
-    "Model fallback chains per worker:",
-    "  Observer: qwen3-next-80b → gemma4:31b-cloud → google/gemma-4-31b-it:free → base model → session",
-    "  Reflector: gpt-oss-120b (cerebras) → glm-4.7 (z.ai) → openai/gpt-oss-120b:free → base model → session",
-    "  Dropper:  gpt-oss-120b (cerebras) → glm-4.7 (z.ai) → openai/gpt-oss-120b:free → base model → session",
-    "",
-    "On retryable error (429, 5xx, timeout), the model is cooled down for cooldownHours.",
-    "Cooled-down models are skipped on subsequent consolidation attempts until cooldown expires.",
-    "After all candidates exhausted, the stage aborts. 30s retry gate prevents spam.",
-    "Cooldowns persist in ~/.pi/agent/pi-blackhole/pi-blackhole-cooldown.json (survives pi restarts).",
-    "Valid thinking values: off, minimal, low, medium, high, xhigh.",
-    "Env override for passive mode: PI_BLACKHOLE_PASSIVE=true.",
+    "v2 config surface:",
+    "  compaction (auto|manual|off) — how compaction triggers",
+    "  compactionEngine (blackhole|pi-default) — who handles it",
+    "  tailBehavior (pi-default|minimal) — how much stays visible",
+    "  sessionFallback (true|false) — if false, skip session model as last-resort fallback",
     "",
-    "noAutoCompact mode accumulates observationBatches/reflectionBatches in",
-    "<sessionId>-pending.json (per-session) across pipeline runs.",
-    "On /blackhole flush, all accumulated batches are written to the branch and the file is cleared.",
-    "The observer preamble (CURRENT OBSERVATIONS)",
-    "is capped to observerPreambleMaxTokens (default 0 = auto 30% of observerChunkMaxTokens).",
-    "This is a soft safety valve — it only trims when accumulated observations exceed",
-    "the budget. High-relevance observations are always kept. Reflections are never trimmed.",
+    "Backward compat: old keys (overrideDefaultCompaction, noAutoCompact, passive)",
+    "are migrated to new keys at load time.",
     "",
-    "agentMaxTurns controls how many agent-loop turns each worker gets per chunk.",
-    "Lower-context models can reduce this (e.g., 8) so the observer doesn't waste",
-    "turns trying to extract more than it can reliably handle per run."
+    "Env overrides:",
+    "  PI_BLACKHOLE_PASSIVE=1  → compaction:off + memory:false",
+    "  PI_BLACKHOLE_COMPACTION  → override compaction setting",
+    "  PI_BLACKHOLE_COMPACTION_ENGINE → override compactionEngine setting"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-blackhole",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "packageManager": "pnpm@11.2.2",
   "description": "Unified compaction + observational memory extension for Pi — compresses conversation context while preserving durable observations and reflections",
   "license": "MIT",

package/src/commands/memory.ts

@@ -36,7 +36,7 @@ function firstArg(args: unknown): string | undefined {
 }
 
 function pct(current: number, total: number): number {
-	return total > 0 ? Math.min(100, Math.round((current / total) * 100)) : 0;
+	return total > 0 ? Math.round((current / total) * 100) : 0;
 }
 
 function tokenSum(items: { tokenCount: number }[]): number {

package/src/commands/pi-vcc.ts

@@ -24,14 +24,8 @@ const formatTokens = (n: number): string => {
 };
 
 export const registerPiVccCommand = (pi: ExtensionAPI, runtime: Runtime) => {
-	const fuzzyMatch = (value: string, prefix: string): boolean => {
-		const q = prefix.toLowerCase();
-		let qi = 0;
-		for (const ch of value) {
-			if (qi < q.length && ch === q[qi]) qi++;
-			if (qi === q.length) return true;
-		}
-		return false;
+	const prefixMatch = (value: string, prefix: string): boolean => {
+		return value.toLowerCase().startsWith(prefix.toLowerCase());
 	};
 
 	pi.registerCommand("blackhole", {
@@ -46,7 +40,7 @@ export const registerPiVccCommand = (pi: ExtensionAPI, runtime: Runtime) => {
 				{ value: "om-on", label: "Enable observational memory [om-on]" },
 			];
 			if (!prefix) return subcommands;
-			return subcommands.filter((s) => fuzzyMatch(s.value, prefix));
+			return subcommands.filter((s) => prefixMatch(s.value, prefix));
 		},
 		handler: async (args, ctx) => {
 			const sessionId = ctx.sessionManager.getSessionId();

package/src/commands/vcc-recall.ts

@@ -6,8 +6,8 @@
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadAllMessages } from "../core/load-messages.js";
-import { searchEntries } from "../core/search-entries.js";
-import { formatRecallOutput } from "../core/format-recall.js";
+import { searchEntries, getTouchedFiles } from "../core/search-entries.js";
+import { formatRecallOutput, formatTouchedOutput } from "../core/format-recall.js";
 import { getActiveLineageEntryIds } from "../core/lineage.js";
 import { parseRecallScope } from "../core/recall-scope.js";
 import {
@@ -41,7 +41,7 @@ async function augmentWithObservations(
 export const registerVccRecallCommand = (pi: ExtensionAPI) => {
 	pi.registerCommand("blackhole-recall", {
 		description:
-			"Search session history. Defaults to active lineage. Usage: /blackhole-recall <query> [page:N] [scope:all] [mode:file|transcript]",
+			"Search session history. Defaults to active lineage. Usage: /blackhole-recall <query> [page:N] [scope:all] [mode:file|touched]",
 		handler: async (args: string, ctx) => {
 			const sessionFile = ctx.sessionManager.getSessionFile();
 			if (!sessionFile) {
@@ -57,6 +57,19 @@ export const registerVccRecallCommand = (pi: ExtensionAPI) => {
 					: undefined;
 			const mode = parsed.mode;
 
+			if (mode === "touched") {
+				const pageMatch = raw.match(/\bpage:(\d+)\b/i);
+				const page = pageMatch ? Math.max(1, parseInt(pageMatch[1], 10)) : 1;
+				const { rendered, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
+				const touched = getTouchedFiles(rawMessages, rendered);
+				const text = formatTouchedOutput(touched, page);
+				pi.sendMessage(
+					{ customType: "blackhole-recall", content: text, display: true },
+					{ triggerTurn: true },
+				);
+				return;
+			}
+
 			if (!parsed.text) {
 				// No query: show recent entries
 				const { rendered } = loadAllMessages(sessionFile, false, lineageEntryIds);

package/src/core/brief.ts

@@ -94,22 +94,27 @@ const truncateTokens = (text: string, limit: number): string => {
 // ── bash command compression ──
 
 const BASH_CAP = 120;
-const PIPE_TAIL_RE = /\s*\|\s*(?:head|tail|sort|wc|column|tr|cut|awk|uniq|python3|node|bun)(?:\s[^|]*)?$/;
+// Only strip pure-formatting pipe tails (head/tail for truncation, sort/wc/column for display).
+// awk/python3/node/bun are data-processing commands — their output carries semantic meaning.
+const PIPE_TAIL_RE = /\s*\|\s*(?:head|tail|sort|wc|column|tr|cut|uniq)(?:\s[^|]*)?$/;
 
 /** Semantic compression: strip cd prefix, pipe tail formatting, cap length */
 const compressBash = (raw: string): string => {
-  // Flatten multi-line: take first meaningful line
-  let cmd = raw.split("\n").map(l => l.trim()).filter(Boolean)[0] ?? raw;
+  // Flatten multi-line: join lines with semicolons
+  let cmd = raw.split("\n").map(l => l.trim()).filter(Boolean).join("; ");
   // Strip cd <path> && prefix
   cmd = cmd.replace(/^cd\s+\S+\s*&&\s*/, "");
-  // Strip pipe tail formatting commands (up to 3 times)
-  for (let i = 0; i < 3; i++) {
+  // Strip pipe tail formatting commands (up to 10 iterations, stop when stable)
+  for (let i = 0; i < 10; i++) {
     const stripped = cmd.replace(PIPE_TAIL_RE, "");
     if (stripped === cmd) break;
     cmd = stripped;
   }
   if (cmd.length > BASH_CAP) {
-    return cmd.slice(0, BASH_CAP - 3) + "...";
+    // Cut at word boundary to avoid mid-word truncation
+    const cut = cmd.lastIndexOf(" ", BASH_CAP - 2);
+    const end = cut > BASH_CAP * 0.6 ? cut : BASH_CAP - 3;
+    return cmd.slice(0, end).trimEnd() + "...";
   }
   return cmd;
 };
@@ -118,7 +123,7 @@ const compressBash = (raw: string): string => {
 
 const TOOL_SUMMARY_FIELDS: Record<string, string> = {
   Read: "file_path", Edit: "file_path", Write: "file_path",
-  read: "file_path", edit: "file_path", write: "file_path",
+  read: "path", edit: "path", write: "path",
   Glob: "pattern", Grep: "pattern",
 };
 
@@ -318,17 +323,17 @@ export const buildBriefSections = (blocks: NormalizedBlock[]): BriefLine[] => {
  */
 export const stringifyBrief = (sections: BriefLine[]): string => {
 
-  // Emit sections -- suppress blank lines between consecutive tool summaries
+  // Emit sections -- suppress blank lines between consecutive tool/error summaries
   const out: string[] = [];
   for (let i = 0; i < sections.length; i++) {
     const sec = sections[i];
     if (i > 0) {
       const prev = sections[i - 1];
-      const prevIsTools = prev.header === "[assistant]" &&
-        prev.lines.every((l) => l.startsWith("* "));
-      const curIsTools = sec.header === "[assistant]" &&
-        sec.lines.every((l) => l.startsWith("* "));
-      if (!(prevIsTools && curIsTools)) {
+      const prevIsToolLike = (prev.header === "[assistant]" && prev.lines.every((l) => l.startsWith("* "))) ||
+        prev.header.startsWith("[tool_error]");
+      const curIsToolLike = (sec.header === "[assistant]" && sec.lines.every((l) => l.startsWith("* "))) ||
+        sec.header.startsWith("[tool_error]");
+      if (!(prevIsToolLike && curIsToolLike)) {
         out.push("");
       }
     }

package/src/core/build-sections.ts

@@ -11,7 +11,7 @@ import { extractGoals } from "../extract/goals";
 import { extractFiles } from "../extract/files";
 import { extractPreferences, dedupPreferencesAgainstGoals } from "../extract/preferences";
 import { extractCommits, formatCommits } from "../extract/commits";
-import { buildBriefSections, sectionsToTranscript, stringifyBrief } from "./brief";
+import { buildBriefSections, stringifyBrief } from "./brief";
 
 export interface BuildSectionsInput {
   blocks: NormalizedBlock[];
@@ -80,6 +80,5 @@ export const buildSections = (input: BuildSectionsInput): SectionData => {
     commits: formatCommits(extractCommits(blocks)),
     userPreferences,
     briefTranscript: stringifyBrief(briefSections),
-    transcriptEntries: sectionsToTranscript(briefSections),
   };
 };

package/src/core/content.ts

@@ -1,4 +1,5 @@
 import type { Message } from "@earendil-works/pi-ai";
+import { PATH_KEYS } from "./tool-args.js";
 
 export const clip = (text: string, max = 200): string => {
   if (text.length <= max) return text;
@@ -57,14 +58,16 @@ export const textOf = (content: Message["content"]): string =>
  */
 export const isContentBearing = (args: Record<string, unknown>): boolean => {
   if (!args || typeof args !== "object") return false;
-  // Must have a path in one of the known keys
-  const hasPath = ["path", "filePath", "file_path", "file"].some((k) => typeof args[k] === "string");
+  // Must have a path in one of the known keys (from tool-args.ts)
+  const hasPath = PATH_KEYS.some((k) => typeof args[k] === "string");
   if (!hasPath) return false;
   // Must have at least one content-bearing field
   if (typeof args.content === "string" && args.content.length > 0) return true;
-  if (Array.isArray(args.edits) && args.edits.length > 0) return true;
-  if (typeof args.oldText === "string" && args.oldText.length > 0 && !Array.isArray(args.edits)) return true;
-  if (typeof args.newText === "string" && args.newText.length > 0 && !Array.isArray(args.edits)) return true;
+  // edits must be a non-empty array of objects (each with oldText/newText)
+  if (Array.isArray(args.edits) && args.edits.length > 0 && args.edits.every((e) => typeof e === "object" && e !== null)) return true;
+  // oldText/newText without edits are content-bearing
+  if (typeof args.oldText === "string" && args.oldText.length > 0 && args.edits === undefined) return true;
+  if (typeof args.newText === "string" && args.newText.length > 0 && args.edits === undefined) return true;
   return false;
 };
 

package/src/core/drill-down.ts

@@ -13,6 +13,7 @@
  *   requires the entire query to be the drill-down pattern.
  */
 import { isContentBearing } from "./content.js";
+import { extractPath } from "./tool-args.js";
 import { loadAllMessages } from "./load-messages.js";
 
 // ── Types ─────────────────────────────────────────────────────────────────
@@ -28,14 +29,6 @@ interface ContentBearingCall {
 
 // ── Helpers ───────────────────────────────────────────────────────────────
 
-/** Extract the file path from tool call args, checking all known keys. */
-function extractPathFromArgs(args: Record<string, unknown>): string | null {
-  for (const key of ["path", "filePath", "file_path", "file"]) {
-    if (typeof args[key] === "string") return args[key] as string;
-  }
-  return null;
-}
-
 /**
  * Find content-bearing tool calls that have a `path` argument and at least
  * one content field (content, edits, oldText, newText).
@@ -48,7 +41,7 @@ function findContentBearingCalls(content: unknown[]): ContentBearingCall[] {
     if (!part || (part as any).type !== "toolCall") continue;
     const args = (part as any).arguments ?? {};
     if (!isContentBearing(args)) continue;
-    const path = extractPathFromArgs(args);
+    const path = extractPath(args);
     if (!path) continue;
     const entry: ContentBearingCall = { name: (part as any).name ?? "", path };
     if (typeof args.content === "string") entry.content = args.content;

package/src/core/filter-noise.ts

@@ -13,16 +13,14 @@ const NOISE_STRINGS = [
 
 const XML_WRAPPER_RE = /<(system-reminder|ide_opened_file|command-message|context-window-usage)[^>]*>[\s\S]*?<\/\1>/g;
 
-const isNoiseUserBlock = (text: string): boolean => {
+/** Return cleaned user text, or null if the block is noise. Cleans once. */
+const cleanOrNull = (text: string): string | null => {
   const trimmed = text.trim();
-  if (NOISE_STRINGS.some((s) => trimmed.includes(s))) return true;
-  const stripped = trimmed.replace(XML_WRAPPER_RE, "").trim();
-  return stripped.length === 0;
+  if (NOISE_STRINGS.some((s) => trimmed.includes(s))) return null;
+  const cleaned = trimmed.replace(XML_WRAPPER_RE, "").trim();
+  return cleaned.length > 0 ? cleaned : null;
 };
 
-const cleanUserText = (text: string): string =>
-  text.replace(XML_WRAPPER_RE, "").trim();
-
 export const filterNoise = (blocks: NormalizedBlock[]): NormalizedBlock[] => {
   const out: NormalizedBlock[] = [];
   for (const b of blocks) {
@@ -30,10 +28,9 @@ export const filterNoise = (blocks: NormalizedBlock[]): NormalizedBlock[] => {
     if (b.kind === "tool_call" && NOISE_TOOLS.has(b.name)) continue;
     if (b.kind === "tool_result" && NOISE_TOOLS.has(b.name)) continue;
     if (b.kind === "user") {
-      if (isNoiseUserBlock(b.text)) continue;
-      const cleaned = cleanUserText(b.text);
+      const cleaned = cleanOrNull(b.text);
       if (!cleaned) continue;
-      out.push({ kind: "user", text: cleaned });
+      out.push({ ...b, text: cleaned }); // preserve sourceIndex and any future fields
       continue;
     }
     out.push(b);

package/src/core/format.ts

@@ -1,4 +1,5 @@
 import type { SectionData } from "../sections";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 
 const section = (title: string, items: string[]): string => {
   if (items.length === 0) return "";
@@ -9,31 +10,23 @@ const section = (title: string, items: string[]): string => {
 const BRIEF_MAX_LINES = 120;
 const TUI_SAFE_LINE_CHARS = 120;
 
-const wrapLine = (line: string, maxChars: number): string[] => {
-  if (line.length <= maxChars) return [line];
-
+/**
+ * Wrap a single line of text, preserving list-item continuation indent.
+ * Detects leading bullets (-, *, N.) and indents continuation lines
+ * to match, so wrapped list items remain visually grouped.
+ */
+function wrapLineWithContinuation(line: string, maxChars: number): string[] {
   const indent = line.match(/^\s*(?:[-*]\s+|\d+\.\s+)?/)?.[0] ?? "";
   const continuationIndent = indent ? " ".repeat(Math.min(indent.length, 8)) : "";
-  const wrapped: string[] = [];
-  let remaining = line;
-  let prefix = "";
-
-  while (prefix.length + remaining.length > maxChars) {
-    const available = Math.max(20, maxChars - prefix.length);
-    let splitAt = remaining.lastIndexOf(" ", available);
-    if (splitAt < Math.floor(available * 0.5)) splitAt = available;
-
-    wrapped.push(prefix + remaining.slice(0, splitAt).trimEnd());
-    remaining = remaining.slice(splitAt).trimStart();
-    prefix = continuationIndent;
-  }
-
-  if (remaining) wrapped.push(prefix + remaining);
-  return wrapped;
-};
+  // Wrap at reduced width so prepending continuationIndent doesn't exceed maxChars
+  const safeMaxChars = continuationIndent ? maxChars - continuationIndent.length : maxChars;
+  const wrapped = wrapTextWithAnsi(line, safeMaxChars);
+  if (wrapped.length <= 1 || !continuationIndent) return wrapped;
+  return [wrapped[0], ...wrapped.slice(1).map((l) => continuationIndent + l)];
+}
 
 export const wrapLongLines = (text: string, maxChars = TUI_SAFE_LINE_CHARS): string =>
-  text.split("\n").flatMap((line) => wrapLine(line, maxChars)).join("\n");
+  text.split("\n").flatMap((line) => wrapLineWithContinuation(line, maxChars)).join("\n");
 
 export const capBrief = (text: string): string => {
   const lines = text.split("\n");
@@ -41,14 +34,21 @@ export const capBrief = (text: string): string => {
   const omitted = lines.length - BRIEF_MAX_LINES;
   const kept = lines.slice(-BRIEF_MAX_LINES);
   // Find first section header to avoid cutting mid-section
-  const firstHeader = kept.findIndex((l) => /^\[.+\]/.test(l));
+  let firstHeader = kept.findIndex((l) => /^\[.+\]/.test(l));
+  if (firstHeader < 0) {
+    // No header in the kept window — scan for any bracket-delimited anchor
+    // (e.g., tool name, inline reference) to avoid starting mid-paragraph.
+    const anyAnchor = kept.findIndex((l) => /^\[[^\]]+\]/.test(l));
+    if (anyAnchor > 0) firstHeader = anyAnchor;
+  }
   const clean = firstHeader > 0 ? kept.slice(firstHeader) : kept;
   return `...(${omitted} earlier lines omitted)\n\n${clean.join("\n")}`;
 };
 
 export const RECALL_NOTE =
-  "Use `recall` to search for prior work, decisions, and context from before this summary. " +
-  "Do not redo work already completed.";
+  "The conversation before this point has been compacted into the summary above. " +
+  "Details not captured here — exact code, error messages, file paths — are only recoverable via `recall`. " +
+  "Use `recall` to search the session history. Do not redo work already completed.";
 
 export const formatSummary = (data: SectionData): string => {
   const headerParts = [
@@ -69,7 +69,7 @@ export const formatSummary = (data: SectionData): string => {
 
   if (parts.length === 0) return "";
 
-  // NOTE: RECALL_NOTE is intentionally NOT appended here.
+  // NOTE: RECALL_NOTE is appended by compile(), not here.
   // It is appended once by `compile()` at the very end, after merge-with-previous,
   // to avoid the note compounding inside the brief transcript across compactions.
   return wrapLongLines(parts.join("\n\n---\n\n"));

package/src/core/load-messages.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "fs";
+import { readFileSync, statSync } from "fs";
 import type { Message } from "@earendil-works/pi-ai";
 import { renderMessage, type RenderedEntry } from "./render-entries";
 
@@ -8,11 +8,78 @@ export interface LoadedMessages {
   entryIds: string[];
 }
 
+// ── Session-file cache (LRU, invalidated by mtime) ─────────────────────────
+
+interface CacheEntry {
+  result: LoadedMessages;
+  mtimeMs: number;
+  timestamp: number;
+}
+
+const MAX_CACHE_SIZE = 3;
+const CACHE_TTL_MS = 2_000;
+const cache = new Map<string, CacheEntry>();
+
+function cacheKey(sessionFile: string, full: boolean, allowedEntryIds: Set<string> | undefined): string {
+  let hash = `${sessionFile}::${full}`;
+  if (allowedEntryIds && allowedEntryIds.size > 0) {
+    // Include the full set as sorted JSON for collision-free caching
+    hash += `::${JSON.stringify([...allowedEntryIds].sort())}`;
+  }
+  return hash;
+}
+
+function getCached(sessionFile: string, full: boolean, allowedEntryIds?: Set<string>): LoadedMessages | undefined {
+  const key = cacheKey(sessionFile, full, allowedEntryIds);
+  const entry = cache.get(key);
+  if (!entry) return undefined;
+
+  // Check TTL (mtime-based invalidation)
+  if (Date.now() - entry.timestamp > CACHE_TTL_MS) {
+    cache.delete(key);
+    return undefined;
+  }
+
+  // Verify file mtime hasn't changed
+  try {
+    const mtimeMs = statSync(sessionFile).mtimeMs;
+    if (mtimeMs !== entry.mtimeMs) {
+      cache.delete(key);
+      return undefined;
+    }
+  } catch {
+    cache.delete(key);
+    return undefined;
+  }
+
+  return entry.result;
+}
+
+function setCache(sessionFile: string, full: boolean, allowedEntryIds: Set<string> | undefined, result: LoadedMessages): void {
+  // Evict oldest if at capacity
+  if (cache.size >= MAX_CACHE_SIZE) {
+    const oldest = cache.entries().next();
+    if (!oldest.done) cache.delete(oldest.value[0]);
+  }
+
+  try {
+    const mtimeMs = statSync(sessionFile).mtimeMs;
+    const key = cacheKey(sessionFile, full, allowedEntryIds);
+    cache.set(key, { result, mtimeMs, timestamp: Date.now() });
+  } catch {
+    // Can't stat the file — don't cache
+  }
+}
+
 export const loadAllMessages = (
   sessionFile: string,
   full: boolean,
   allowedEntryIds?: Set<string>,
 ): LoadedMessages => {
+  // Check cache first (same sessionFile + full flag + lineage size — approximate)
+  const cached = getCached(sessionFile, full, allowedEntryIds);
+  if (cached) return cached;
+
   const content = readFileSync(sessionFile, "utf-8");
   const entries: any[] = [];
   let parseErrors = 0;
@@ -42,5 +109,7 @@ export const loadAllMessages = (
     messageIndex++;
   }
 
-  return { rendered, rawMessages, entryIds };
+  const result: LoadedMessages = { rendered, rawMessages, entryIds };
+  setCache(sessionFile, full, allowedEntryIds, result);
+  return result;
 };

package/src/core/normalize.ts

@@ -9,6 +9,14 @@ import type { NormalizedBlock } from "../types";
 import { textOf } from "./content";
 import { sanitize } from "./sanitize";
 
+// Mirrors @earendil-works/pi-coding-agent's BashExecutionMessage (not re-exported from index)
+interface LocalBashMessage {
+  role: "bashExecution";
+  command: string;
+  output: string;
+  exitCode: number | undefined;
+}
+
 const normalizeOne = (msg: Message, msgIndex: number): NormalizedBlock[] => {
   if (msg.role === "user") {
     const blocks: NormalizedBlock[] = [];
@@ -25,10 +33,8 @@ const normalizeOne = (msg: Message, msgIndex: number): NormalizedBlock[] => {
   }
 
   if ((msg as any).role === "bashExecution") {
-    const cmd = (msg as any).command ?? "";
-    const out = (msg as any).output ?? "";
-    const exit = (msg as any).exitCode;
-    return [{ kind: "bash", command: cmd, output: out, exitCode: exit, sourceIndex: msgIndex }];
+    const bashMsg = msg as unknown as LocalBashMessage;
+    return [{ kind: "bash", command: bashMsg.command ?? "", output: bashMsg.output ?? "", exitCode: bashMsg.exitCode, sourceIndex: msgIndex }];
   }
 
   if (msg.role === "toolResult") {

package/src/core/recall-scope.ts

@@ -1,10 +1,10 @@
 export type RecallScope = "lineage" | "all";
-export type RecallMode = "hybrid" | "file" | "transcript" | "touched";
+export type RecallMode = "hybrid" | "file" | "touched";
 
 const SCOPE_RE = /\bscope:(lineage|all)\b/i;
-const MODE_RE = /\bmode:(hybrid|file|transcript|touched)\b/i;
+const MODE_RE = /\bmode:(hybrid|file|touched)\b/i;
 
-const VALID_MODES = new Set(["hybrid", "file", "transcript", "touched"]);
+const VALID_MODES = new Set(["hybrid", "file", "touched"]);
 
 export const normalizeRecallScope = (scope?: unknown): RecallScope =>
   typeof scope === "string" && scope.toLowerCase() === "all" ? "all" : "lineage";