ultimate-pi 0.4.0 → 0.4.1

package/vendor/pi-vcc/scripts/audit-sessions.ts

@@ -0,0 +1,88 @@
+import { basename, dirname } from "node:path";
+import { compile } from "../src/core/summarize";
+import { normalize } from "../src/core/normalize";
+import { filterNoise } from "../src/core/filter-noise";
+import { renderMessage } from "../src/core/render-entries";
+import { prepareSessionSamples } from "../tests/support/real-sessions";
+import { loadSessionMessages } from "../tests/support/load-session";
+
+const SEP = "=".repeat(80);
+const samples = await prepareSessionSamples(10);
+
+for (const sample of samples) {
+  const loaded = loadSessionMessages(sample.copy);
+  const { messages } = loaded;
+
+  const rawBlocks = normalize(messages);
+  const filteredBlocks = filterNoise(rawBlocks);
+  const afterText = compile({ messages });
+
+  const rendered = messages.map((m, i) => renderMessage(m, i));
+  const beforeChars = rendered.reduce((s, e) => s + e.summary.length, 0);
+
+  const project = dirname(sample.source).split("--").filter(Boolean).pop() ?? "unknown";
+
+  const goalSection = afterText.match(/\[Session Goal\]\n([\s\S]*?)(?=\n\n\[|$)/)?.[1] ?? "(empty)";
+  const stateSection = afterText.match(/\[Current State\]\n([\s\S]*?)(?=\n\n\[|$)/)?.[1] ?? "(empty)";
+  const doneSection = afterText.match(/\[What Was Done\]\n([\s\S]*?)(?=\n\n\[|$)/)?.[1] ?? "(empty)";
+  const problemsSection = afterText.match(/\[Open Problems\]\n([\s\S]*?)(?=\n\n\[|$)/)?.[1] ?? "(empty)";
+  const nextSection = afterText.match(/\[Next Best Steps\]\n([\s\S]*?)(?=\n\n\[|$)/)?.[1] ?? "(empty)";
+
+  const doneLines = doneSection.split("\n").filter(l => l.trim());
+  const problemLines = problemsSection.split("\n").filter(l => l.trim());
+
+  // Detect issues
+  const issues: string[] = [];
+
+  // 1. Goal quality
+  const goalLines = goalSection.split("\n").map(l => l.replace(/^- /, "").trim()).filter(Boolean);
+  if (goalLines[0] && goalLines[0].length < 5) issues.push(`GOAL_TOO_SHORT: "${goalLines[0]}"`);
+  if (goalLines.length === 0) issues.push("GOAL_EMPTY");
+
+  // 2. Sensitive data in What Was Done
+  if (/sshpass|password|secret|token=|api[_-]?key/i.test(doneSection)) {
+    issues.push("SENSITIVE_DATA_IN_DONE");
+  }
+
+  // 3. Raw code/minified JS in summary
+  if (/\{[a-zA-Z$_]+:[a-zA-Z$_]+,[a-zA-Z$_]+:/.test(afterText) || /var [a-zA-Z]+=/.test(afterText)) {
+    issues.push("RAW_CODE_LEAK");
+  }
+
+  // 4. Open problems count
+  if (problemLines.length > 10) issues.push(`PROBLEMS_OVERCOUNT: ${problemLines.length}`);
+
+  // 5. Next steps empty
+  if (nextSection === "(empty)") issues.push("NEXT_STEPS_EMPTY");
+
+  // 6. What Was Done too verbose
+  if (doneLines.length > 15) issues.push(`DONE_TOO_VERBOSE: ${doneLines.length} lines`);
+
+  // 7. Summary too large (>10K chars)
+  if (afterText.length > 10000) issues.push(`SUMMARY_TOO_LARGE: ${afterText.length} chars`);
+
+  console.log(SEP);
+  console.log(`PROJECT: ${project}`);
+  console.log(`FILE: ${basename(sample.source)}`);
+  console.log(`Size: ${(sample.size / 1024).toFixed(0)}KB | Msgs: ${messages.length} | Blocks raw: ${rawBlocks.length} -> filtered: ${filteredBlocks.length}`);
+  console.log(`Before: ${beforeChars} chars | After: ${afterText.length} chars | Ratio: ${(beforeChars / afterText.length).toFixed(1)}x`);
+  console.log(`Issues: ${issues.length === 0 ? "NONE" : issues.join(", ")}`);
+  console.log("");
+  console.log("--- GOAL ---");
+  console.log(goalSection.slice(0, 300));
+  console.log("");
+  console.log("--- CURRENT STATE (first 300c) ---");
+  console.log(stateSection.slice(0, 300));
+  console.log("");
+  console.log("--- WHAT WAS DONE (first 5 lines) ---");
+  console.log(doneLines.slice(0, 5).join("\n"));
+  console.log(`... (${doneLines.length} total lines)`);
+  console.log("");
+  console.log("--- OPEN PROBLEMS (first 5 lines) ---");
+  console.log(problemLines.slice(0, 5).join("\n"));
+  console.log(`... (${problemLines.length} total lines)`);
+  console.log("");
+  console.log("--- NEXT STEPS ---");
+  console.log(nextSection.slice(0, 300));
+  console.log("");
+}

package/vendor/pi-vcc/scripts/benchmark-real-sessions.ts

@@ -0,0 +1,25 @@
+import { performance } from "node:perf_hooks";
+import { basename } from "node:path";
+import { buildCompactReport } from "../src/core/report";
+import { prepareSessionSamples } from "../tests/support/real-sessions";
+import { loadSessionMessages } from "../tests/support/load-session";
+
+const samples = await prepareSessionSamples(2);
+for (const sample of samples) {
+  const loaded = loadSessionMessages(sample.copy);
+  const start = performance.now();
+  const report = buildCompactReport({ messages: loaded.messages });
+  const elapsedMs = performance.now() - start;
+  console.log(JSON.stringify({
+    sourceFile: basename(sample.source),
+    sourceSizeBytes: sample.size,
+    copiedToTemp: true,
+    loadedMessages: loaded.messageCount,
+    skippedMessages: loaded.skippedCount,
+    compileMs: Number(elapsedMs.toFixed(2)),
+    before: report.before,
+    after: report.after,
+    compression: report.compression,
+    recall: report.recall,
+  }, null, 2));
+}

package/vendor/pi-vcc/scripts/compare-before-after.ts

@@ -0,0 +1,36 @@
+import { basename } from "node:path";
+import { compile } from "../src/core/summarize";
+import { renderMessage } from "../src/core/render-entries";
+import { clip } from "../src/core/content";
+import { prepareSessionSamples } from "../tests/support/real-sessions";
+import { loadSessionMessages } from "../tests/support/load-session";
+
+const SEP = "=".repeat(80);
+const samples = await prepareSessionSamples(2);
+
+for (const sample of samples) {
+  const loaded = loadSessionMessages(sample.copy);
+  const { messages } = loaded;
+
+  const rendered = messages.map((m, i) => renderMessage(m, i));
+  const beforeLines = rendered.map(
+    (e) => `#${e.index} [${e.role}] ${clip(e.summary, 300)}`,
+  );
+  const beforeText = beforeLines.join("\n");
+  const afterText = compile({ messages });
+
+  console.log(SEP);
+  console.log(`FILE: ${basename(sample.source)}`);
+  console.log(`Messages: ${messages.length} | Before chars: ${beforeText.length} | After chars: ${afterText.length}`);
+  console.log(`Compression: ${(beforeText.length / afterText.length).toFixed(1)}x`);
+  console.log(SEP);
+
+  console.log("\n--- BEFORE (raw context, first 40 + last 20 entries) ---\n");
+  for (const line of beforeLines.slice(0, 40)) console.log(line);
+  if (beforeLines.length > 60) console.log(`\n... (${beforeLines.length - 60} entries omitted) ...\n`);
+  for (const line of beforeLines.slice(-20)) console.log(line);
+
+  console.log("\n--- AFTER (pi-vcc compiled summary) ---\n");
+  console.log(afterText);
+  console.log("\n");
+}

package/vendor/pi-vcc/scripts/dump-branch-output.ts

@@ -0,0 +1,20 @@
+import { basename } from "node:path";
+import { compile } from "../src/core/summarize";
+import { prepareSessionSamples } from "../tests/support/real-sessions";
+import { loadSessionMessages } from "../tests/support/load-session";
+import { writeFileSync, mkdirSync } from "node:fs";
+
+const outDir = "/tmp/pi-vcc-compare";
+const branch = process.argv[2] || "unknown";
+mkdirSync(`${outDir}/${branch}`, { recursive: true });
+
+const samples = await prepareSessionSamples(5);
+for (const sample of samples) {
+  const name = basename(sample.source).slice(0, 30);
+  const loaded = loadSessionMessages(sample.copy);
+  const summary = compile({ messages: loaded.messages });
+  const outFile = `${outDir}/${branch}/${name}.txt`;
+  writeFileSync(outFile, summary);
+  console.log(`${name} (${loaded.messageCount} msgs) => ${summary.length} chars`);
+}
+console.log(`\nSaved to ${outDir}/${branch}/`);

package/vendor/pi-vcc/src/commands/pi-vcc.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { getLastCompactionStats, PI_VCC_COMPACT_INSTRUCTION } from "../hooks/before-compact";
+
+const formatTokens = (n: number): string => {
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(n);
+};
+
+export const registerPiVccCommand = (pi: ExtensionAPI) => {
+  pi.registerCommand("pi-vcc", {
+    description: "Compact conversation with pi-vcc structured summary",
+    handler: async (_args, ctx) => {
+      ctx.compact({
+        customInstructions: PI_VCC_COMPACT_INSTRUCTION,
+        onComplete: () => {
+          const stats = getLastCompactionStats();
+          if (stats) {
+            ctx.ui.notify(
+              `pi-vcc: ${stats.summarized} source entries processed; tail kept ${stats.kept} (~${formatTokens(stats.keptTokensEst)} tok).`,
+              "info",
+            );
+          } else {
+            ctx.ui.notify("Compacted with pi-vcc", "info");
+          }
+        },
+        onError: (err) => {
+          if (err.message === "Compaction cancelled" || err.message === "Already compacted") {
+            ctx.ui.notify("Nothing to compact", "warning");
+          } else {
+            ctx.ui.notify(`Compaction failed: ${err.message}`, "error");
+          }
+        },
+      });
+    },
+  });
+};

package/vendor/pi-vcc/src/commands/vcc-recall.ts

@@ -0,0 +1,65 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { loadAllMessages } from "../core/load-messages";
+import { searchEntries } from "../core/search-entries";
+import { formatRecallOutput } from "../core/format-recall";
+import { getActiveLineageEntryIds } from "../core/lineage";
+import { parseRecallScope } from "../core/recall-scope";
+
+const PAGE_SIZE = 5;
+const DEFAULT_RECENT = 25;
+
+export const registerVccRecallCommand = (pi: ExtensionAPI) => {
+  pi.registerCommand("pi-vcc-recall", {
+    description: "Search session history. Defaults to active lineage; add scope:all for off-lineage branches.",
+    handler: async (args: string, ctx) => {
+      const sessionFile = ctx.sessionManager.getSessionFile();
+      if (!sessionFile) {
+        ctx.ui.notify("No session file available.", "error");
+        return;
+      }
+
+      const raw = args.trim();
+      const parsed = parseRecallScope(raw);
+      const lineageEntryIds = parsed.scope === "lineage"
+        ? getActiveLineageEntryIds(ctx.sessionManager)
+        : undefined;
+      if (!parsed.text) {
+        // No query: show recent
+        const { rendered } = loadAllMessages(sessionFile, false, lineageEntryIds);
+        const recent = rendered.slice(-DEFAULT_RECENT);
+        const output = (parsed.scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(recent);
+        pi.sendMessage({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: true });
+        return;
+      }
+
+      // Parse page:N from args
+      const pageMatch = parsed.text.match(/\bpage:(\d+)\b/i);
+      const page = pageMatch ? Math.max(1, parseInt(pageMatch[1], 10)) : 1;
+      const query = parsed.text.replace(/\bpage:\d+\b/i, "").trim();
+
+      if (!query) {
+        const { rendered } = loadAllMessages(sessionFile, false, lineageEntryIds);
+        const recent = rendered.slice(-DEFAULT_RECENT);
+        const output = (parsed.scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(recent);
+        pi.sendMessage({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: true });
+        return;
+      }
+
+      const { rendered, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
+      const allResults = searchEntries(rendered, rawMessages, query);
+
+      const start = (page - 1) * PAGE_SIZE;
+      const pageResults = allResults.slice(start, start + PAGE_SIZE);
+      const totalPages = Math.ceil(allResults.length / PAGE_SIZE);
+      const scopeSuffix = parsed.scope === "all" ? " (scope: all)" : "";
+      const header = totalPages > 1
+        ? `Page ${page}/${totalPages} (${allResults.length} total matches${scopeSuffix})`
+        : `${allResults.length} matches${scopeSuffix}`;
+      const footer = page < totalPages
+        ? `\n--- /pi-vcc-recall ${query}${parsed.scope === "all" ? " scope:all" : ""} page:${page + 1} ---`
+        : "";
+      const output = formatRecallOutput(pageResults, query, header) + footer;
+      pi.sendMessage({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: true });
+    },
+  });
+};

package/vendor/pi-vcc/src/core/brief.ts

@@ -0,0 +1,381 @@
+import type { NormalizedBlock } from "../types";
+import { clip, firstLine } from "./content";
+import { extractPath } from "./tool-args";
+import { collapseSkillText } from "./skill-collapse";
+
+const TRUNCATE_USER = 256;
+const TRUNCATE_ASSISTANT = 200;
+
+// Strip common self-reflective assistant prefixes that carry no semantic info.
+// Conservative list: only removes the leading filler, preserves the actual content.
+const SELF_TALK_PREFIX_RE =
+  /^\s*(?:hmm|wait|actually|oh|okay|ok|well|so)[,.!\s-]+/i;
+
+// ── noise filtering ──
+
+const isNoiseUser = (text: string): boolean => {
+  return !text.trim();
+};
+
+// ── truncation ──
+
+// Unicode-aware word segmentation via Intl.Segmenter (built-in, zero dependency)
+const segmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+
+/** Check if segment is a word (Bun's isWordLike is unreliable for alphanumeric tokens) */
+const isWord = (seg: { segment: string; isWordLike: boolean }): boolean =>
+  seg.isWordLike || /[\p{L}\p{N}]/u.test(seg.segment);
+
+// Common stop words — don't count toward budget
+const STOP_WORDS = new Set([
+  "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+  "have", "has", "had", "do", "does", "did", "will", "would", "could",
+  "should", "may", "might", "shall", "can", "need", "must",
+  "to", "of", "in", "for", "on", "with", "at", "by", "from", "as",
+  "into", "through", "during", "before", "after", "above", "below",
+  "between", "under", "over",
+  "and", "but", "or", "nor", "not", "so", "yet", "both", "either",
+  "neither", "each", "every", "all", "any", "few", "more", "most",
+  "other", "some", "such", "no",
+  "that", "this", "these", "those", "it", "its",
+  "i", "me", "my", "we", "our", "you", "your", "he", "him", "his",
+  "she", "her", "they", "them", "their", "who", "which", "what",
+  "if", "then", "than", "when", "where", "how", "just", "also",
+]);
+
+const truncateTokens = (text: string, limit: number): string => {
+  const flat = text.replace(/\s+/g, " ").trim();
+  let count = 0;
+  let lastEnd = 0;
+  for (const seg of segmenter.segment(flat)) {
+    if (isWord(seg)) {
+      if (!STOP_WORDS.has(seg.segment.toLowerCase())) {
+        count++;
+        if (count > limit) {
+          return flat.slice(0, lastEnd).trimEnd() + "...(truncated)";
+        }
+      }
+    }
+    lastEnd = seg.index + seg.segment.length;
+  }
+  return flat;
+};
+
+// ── 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[^|]*)?$/;
+
+/** 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;
+  // 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++) {
+    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) + "...";
+  }
+  return cmd;
+};
+
+// ── tool summary ──
+
+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",
+  Glob: "pattern", Grep: "pattern",
+};
+
+const toolOneLiner = (name: string, args: Record<string, unknown>): string => {
+  const field = TOOL_SUMMARY_FIELDS[name];
+  if (field && typeof args[field] === "string") {
+    return `* ${name} "${args[field] as string}"`;
+  }
+  const path = extractPath(args);
+  if (path) return `* ${name} "${path}"`;
+  if (name === "bash" || name === "Bash") {
+    const raw = (args.command ?? args.description ?? "") as string;
+    const cmd = compressBash(raw);
+    return `* ${name} "${cmd}"`;
+  }
+  if (typeof args.query === "string") {
+    return `* ${name} "${clip(args.query as string, 60)}"`;
+  }
+  return `* ${name}`;
+};
+
+export interface BriefLine {
+  /** Section header like "[user]", "[assistant]", "[tool_error] bash" */
+  header: string;
+  /** Content lines for this section */
+  lines: string[];
+}
+
+/** Structured transcript entry for JSON output */
+export interface TranscriptEntry {
+  role: "user" | "assistant" | "tool_error";
+  text?: string;
+  tool?: string;
+  cmd?: string;
+  ref?: string;
+  /** Collapse count when identical tool calls are grouped */
+  count?: number;
+}
+
+/**
+ * Build BriefLine sections from NormalizedBlocks.
+ */
+export const buildBriefSections = (blocks: NormalizedBlock[]): BriefLine[] => {
+  const sections: BriefLine[] = [];
+  let lastHeader = "";
+
+  const push = (header: string, line: string) => {
+    if (header === lastHeader && sections.length > 0) {
+      sections[sections.length - 1].lines.push(line);
+      return;
+    }
+    sections.push({ header, lines: [line] });
+    lastHeader = header;
+  };
+
+  for (const b of blocks) {
+    switch (b.kind) {
+      case "user": {
+        if (isNoiseUser(b.text)) break;
+        const text = truncateTokens(collapseSkillText(b.text), TRUNCATE_USER);
+        if (text) {
+          const ref = b.sourceIndex != null ? ` (#${b.sourceIndex})` : "";
+          push("[user]", text + ref);
+        }
+        lastHeader = "[user]";
+        break;
+      }
+      case "assistant": {
+        let raw = b.text;
+        // Strip leading self-talk prefix (up to 2x; assistants sometimes chain "Hmm, actually, ...")
+        for (let i = 0; i < 2; i++) {
+          const stripped = raw.replace(SELF_TALK_PREFIX_RE, "");
+          if (stripped === raw) break;
+          raw = stripped;
+        }
+        const text = truncateTokens(raw, TRUNCATE_ASSISTANT);
+        if (text) {
+          const ref = b.sourceIndex != null ? ` (#${b.sourceIndex})` : "";
+          push("[assistant]", text + ref);
+        }
+        break;
+      }
+      case "tool_call": {
+        // Skip malformed tool calls from streaming providers (empty name / fragmented args).
+        if (!b.name || b.name.trim() === "") break;
+        const ref = b.sourceIndex != null ? ` (#${b.sourceIndex})` : "";
+        const summary = toolOneLiner(b.name, b.args) + ref;
+        push("[assistant]", summary);
+        break;
+      }
+      case "tool_result": {
+        if (b.isError) {
+          const body = firstLine(b.text, 150);
+          // Drop empty/placeholder error bodies — keep the line only if it carries info.
+          if (!body || body === "(no output)") break;
+          const ref = b.sourceIndex != null ? ` (#${b.sourceIndex})` : "";
+          const header = `[tool_error] ${b.name}${ref}`;
+          push(header, body);
+          lastHeader = header;
+        }
+        break;
+      }
+      case "thinking":
+        break;
+    }
+  }
+
+  // Collapse consecutive identical tool lines (same text, different #ref)
+  for (const sec of sections) {
+    if (sec.header !== "[assistant]") continue;
+    const out: string[] = [];
+    for (const line of sec.lines) {
+      if (!line.startsWith("* ")) { out.push(line); continue; }
+      const ref = line.match(/\(#(\d+)\)$/)?.[1] ?? "";
+      const base = ref ? line.slice(0, -(ref.length + 3)).trimEnd() : line;
+      const last = out.length > 0 ? out[out.length - 1] : "";
+      const m = last.match(/^(.*) \((#[\d, #]+)\) x(\d+)$/);
+      if (m && m[1] === base) {
+        out[out.length - 1] = `${base} (${m[2]}, #${ref}) x${parseInt(m[3]) + 1}`;
+      } else if (last.match(/\(#\d+\)$/) && last.replace(/\s*\(#\d+\)$/, "") === base) {
+        const prevRef = last.match(/\(#(\d+)\)$/)?.[1];
+        out[out.length - 1] = `${base} (#${prevRef}, #${ref}) x2`;
+      } else {
+        out.push(line);
+      }
+    }
+    sec.lines = out;
+  }
+
+  // Cap tool calls per [assistant] turn — keep tail (latest actions tend to
+  // be the deciding edits/writes; head is usually exploration noise).
+  const TOOL_CALLS_PER_TURN = 8;
+  for (const sec of sections) {
+    if (sec.header !== "[assistant]") continue;
+    const toolIdxs = sec.lines
+      .map((l, i) => (l.startsWith("* ") ? i : -1))
+      .filter((i) => i >= 0);
+    if (toolIdxs.length <= TOOL_CALLS_PER_TURN) continue;
+    const dropCount = toolIdxs.length - TOOL_CALLS_PER_TURN;
+    const dropSet = new Set(toolIdxs.slice(0, dropCount));
+    const firstKeptToolIdx = toolIdxs[dropCount];
+    const next: string[] = [];
+    let inserted = false;
+    for (let i = 0; i < sec.lines.length; i++) {
+      if (dropSet.has(i)) continue;
+      if (!inserted && i === firstKeptToolIdx) {
+        next.push(`* (${dropCount} earlier tool-call entries omitted)`);
+        inserted = true;
+      }
+      next.push(sec.lines[i]);
+    }
+    sec.lines = next;
+  }
+
+  // Collapse consecutive identical [tool_error] sections (same tool, same body).
+  // E.g. 20 back-to-back `[tool_error] bash (#N) ... Command aborted` become one
+  // `[tool_error] bash (#refs...) x20` entry.
+  const collapsedErrors: BriefLine[] = [];
+  for (const sec of sections) {
+    const m = sec.header.match(/^\[tool_error\]\s+(\S+?)(?:\s*\(#(\d+)\))?$/);
+    if (!m || sec.lines.length !== 1) {
+      collapsedErrors.push(sec);
+      continue;
+    }
+    const tool = m[1];
+    const ref = m[2];
+    const body = sec.lines[0];
+    const prev = collapsedErrors[collapsedErrors.length - 1];
+    const prevMatch = prev?.header.match(
+      /^\[tool_error\]\s+(\S+?)\s*\(((?:#\d+(?:,\s*)?)+)\)(?:\s*x(\d+))?$/,
+    );
+    if (prev && prevMatch && prevMatch[1] === tool && prev.lines.length === 1 && prev.lines[0] === body) {
+      const refs = prevMatch[2] + (ref ? `, #${ref}` : "");
+      const count = prevMatch[3] ? parseInt(prevMatch[3]) + 1 : 2;
+      prev.header = `[tool_error] ${tool} (${refs}) x${count}`;
+    } else {
+      collapsedErrors.push(sec);
+    }
+  }
+  sections.length = 0;
+  sections.push(...collapsedErrors);
+
+  return sections;
+};
+
+/**
+ * Stringify BriefLine sections into text format.
+ */
+export const stringifyBrief = (sections: BriefLine[]): string => {
+
+  // Emit sections -- suppress blank lines between consecutive tool 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)) {
+        out.push("");
+      }
+    }
+    out.push(sec.header);
+    for (const line of sec.lines) {
+      out.push(line);
+    }
+  }
+
+  return out.join("\n");
+};
+
+/** Parse a text line into a structured TranscriptEntry */
+const parseToolLine = (line: string): { tool: string; cmd?: string; ref?: string; count?: number } | null => {
+  // * bash "cmd" (#5)
+  // * bash "cmd" (#1, #3) x2
+  // * tilth "query" (#7)
+  const m = line.match(/^\* (\S+)\s*(?:"([^"]*)")?\s*(?:\((#[\d, #]+)\))?\s*(?:x(\d+))?$/);
+  if (!m) return null;
+  return {
+    tool: m[1],
+    cmd: m[2] || undefined,
+    ref: m[3] || undefined,
+    count: m[4] ? parseInt(m[4]) : undefined,
+  };
+};
+
+const extractRef = (text: string): { clean: string; ref?: string } => {
+  const m = text.match(/\s*\(#(\d+)\)$/);
+  if (!m) return { clean: text };
+  return { clean: text.slice(0, m.index).trimEnd(), ref: `#${m[1]}` };
+};
+
+/**
+ * Convert BriefLine sections to structured TranscriptEntry array for JSON output.
+ */
+export const sectionsToTranscript = (sections: BriefLine[]): TranscriptEntry[] => {
+  const entries: TranscriptEntry[] = [];
+
+  for (const sec of sections) {
+    if (sec.header === "[user]") {
+      for (const line of sec.lines) {
+        const { clean, ref } = extractRef(line);
+        entries.push({ role: "user", text: clean, ...(ref && { ref }) });
+      }
+    } else if (sec.header === "[assistant]") {
+      for (const line of sec.lines) {
+        if (line.startsWith("* ")) {
+          const parsed = parseToolLine(line);
+          if (parsed) {
+            entries.push({
+              role: "assistant",
+              tool: parsed.tool,
+              ...(parsed.cmd && { cmd: parsed.cmd }),
+              ...(parsed.ref && { ref: parsed.ref }),
+              ...(parsed.count && { count: parsed.count }),
+            });
+          } else {
+            // Fallback: unparseable tool line
+            const { clean, ref } = extractRef(line.slice(2));
+            entries.push({ role: "assistant", text: clean, ...(ref && { ref }) });
+          }
+        } else {
+          const { clean, ref } = extractRef(line);
+          entries.push({ role: "assistant", text: clean, ...(ref && { ref }) });
+        }
+      }
+    } else if (sec.header.startsWith("[tool_error]")) {
+      // [tool_error] bash (#5)
+      const headerMatch = sec.header.match(/^\[tool_error\]\s+(\S+)\s*(?:\(#(\d+)\))?/);
+      const tool = headerMatch?.[1] ?? "unknown";
+      const ref = headerMatch?.[2] ? `#${headerMatch[2]}` : undefined;
+      for (const line of sec.lines) {
+        entries.push({
+          role: "tool_error",
+          tool,
+          text: line,
+          ...(ref && { ref }),
+        });
+      }
+    }
+  }
+
+  return entries;
+};
+
+/** Convenience: build sections from blocks and stringify to text */
+export const compileBrief = (blocks: NormalizedBlock[]): string =>
+  stringifyBrief(buildBriefSections(blocks));