@ngockhoale/ukit 1.1.6

package/src/core/output/index.js

@@ -0,0 +1,1309 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { recordCompaction } from '../compact/index.js';
+import { buildRuntimePaths } from '../runtimePaths.js';
+import {
+  buildCompactMachineKey,
+  compressLine,
+  compressMarkdownLines,
+  estimateTokenCount,
+  readPromptCacheEntry,
+  writePromptCacheEntry,
+} from '../token/index.js';
+
+export const DEFAULT_OUTPUT_HISTORY_MAX_ENTRIES = 25;
+const ANSI_RE = /\u001b\[[0-9;]*m/g;
+const FRESH_OUTPUT_WINDOW_MS = 30 * 60 * 1000;
+const RAW_OUTPUT_SAVE_MIN_TOKENS = 600;
+const RAW_OUTPUT_SAVE_MIN_SAVED_TOKENS = 250;
+const GENERIC_NOISE_PATTERNS = [
+  /^[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]/,
+  /^\[[=\-#>\s]{6,}\]/,
+  /^progress[:\s]/i,
+  /^download(ed|ing)?\b/i,
+  /^debug\b/i,
+  /^[.+-]{16,}$/,
+  /^[╭╰│─└┌┬┴├┤┼\s]+$/u,
+  /^\.+$/,
+];
+const GENERIC_IMPORTANT_PATTERNS = [
+  /\b(error|fail(?:ed)?|warning|assertionerror|exception|fatal)\b/i,
+  /(^|\s)(tests?|specs?)\//i,
+  /(^|\s)(src|app|lib|docs|ukit|\.claude|\.codex)\//i,
+  /(^|\s)at\s+.*:\d+:\d+/i,
+  /\b(Test Files|Tests|Duration|Start at|Summary|Ran all)\b/i,
+  /^stderr\s*\|/i,
+  /^stdout\s*\|/i,
+  /^\s*[✓✗×❯]/,
+  /^\s*FAIL(?:ED)?\s+/i,
+  /^\s*E\s+/,
+];
+const GENERIC_ANCHOR_PATTERNS = [
+  /\b(error|fail(?:ed)?|assertionerror|exception|fatal)\b/i,
+  /(^|\s)(tests?|specs?)\//i,
+  /(^|\s)(src|app|lib|docs|ukit|\.claude|\.codex)\//i,
+  /(^|\s)at\s+.*:\d+:\d+/i,
+  /\b(Test Files|Tests|Duration|Start at|Summary|Ran all)\b/i,
+  /^stderr\s*\|/i,
+  /^\s*[✗×❯]/,
+  /^\s*FAIL(?:ED)?\s+/i,
+  /^\s*AssertionError:/i,
+];
+const GENERIC_TAIL_PATTERNS = [
+  /^\s*(Test Files|Tests|Duration|Start at)\b/i,
+  /^\s*=+ .* in [0-9.]+s =+\s*$/i,
+  /^\s*short test summary info\b/i,
+];
+const OUTPUT_PROFILES = [
+  {
+    id: 'paths',
+    commandPatterns: [
+      /\brg\s+--files\b/i,
+      /\bgit\s+ls-files\b/i,
+      /(?:^|\s)(?:find|fd)\b/i,
+      /(?:^|\s)tree\b/i,
+      /\bls\b[^\n]*\s-R(?:\s|$)/i,
+    ],
+    importantPatterns: [],
+    anchorPatterns: [],
+    tailPatterns: [],
+    noisePatterns: [],
+  },
+  {
+    id: 'search',
+    commandPatterns: [
+      /(?:^|\s)(?:rg|ripgrep)\b/i,
+      /(?:^|\s)grep\b/i,
+      /\bgit\s+grep\b/i,
+    ],
+    importantPatterns: [],
+    anchorPatterns: [],
+    tailPatterns: [],
+    noisePatterns: [],
+  },
+  {
+    id: 'package-install',
+    commandPatterns: [
+      /\b(?:npm|pnpm|yarn|bun)\b.*\b(?:install|add|ci|update)\b/i,
+    ],
+    importantPatterns: [
+      /\b(?:deprecated|unmet peer|peer dependenc(?:y|ies)|ignored build scripts|approve-builds)\b/i,
+      /\b(?:vulnerab(?:ility|ilities)|audited \d+ packages|added \d+ packages|removed \d+ packages|changed \d+ packages)\b/i,
+      /\b(?:npm ERR!|ERR_PNPM|ELIFECYCLE|ERESOLVE|ENOENT|EACCES)\b/i,
+      /^Packages:\s*[+~-]?\d+/i,
+      /^Done in\b/i,
+    ],
+    anchorPatterns: [
+      /\b(?:deprecated|unmet peer|peer dependenc(?:y|ies)|ignored build scripts)\b/i,
+      /\b(?:vulnerab(?:ility|ilities)|npm ERR!|ERR_PNPM|ELIFECYCLE|ERESOLVE|ENOENT|EACCES)\b/i,
+      /^Packages:\s*[+~-]?\d+/i,
+      /^Done in\b/i,
+    ],
+    tailPatterns: [
+      /^Done in\b/i,
+    ],
+    noisePatterns: [
+      /^Progress:\s/i,
+      /^\+\+\++$/,
+      /^\s*(?:dependencies|devDependencies|optionalDependencies):\s*$/i,
+      /^[+]\s+\S+/,
+    ],
+  },
+  {
+    id: 'test-runner',
+    commandPatterns: [
+      /\b(?:vitest|jest|mocha|ava|pytest|py\.test)\b/i,
+      /\b(?:npm|pnpm|yarn|bun)\s+test\b/i,
+    ],
+    importantPatterns: [
+      /^\s*FAIL(?:ED)?\b/i,
+      /^\s*PASS\b/i,
+      /^\s*AssertionError:/i,
+      /^\s*short test summary info\b/i,
+    ],
+    anchorPatterns: [
+      /^\s*FAIL(?:ED)?\b/i,
+      /^\s*AssertionError:/i,
+      /^\s*short test summary info\b/i,
+    ],
+    tailPatterns: [
+      /^\s*short test summary info\b/i,
+      /^\s*=+ .* in [0-9.]+s =+\s*$/i,
+    ],
+    noisePatterns: [
+      /^\s*collected \d+ items?\s*$/i,
+    ],
+  },
+  {
+    id: 'git',
+    commandPatterns: [
+      /\bgit\s+status\b/i,
+      /\bgit\s+diff\b/i,
+    ],
+    importantPatterns: [
+      /^(?:M|A|D|R|C|UU|\?\?)\s+/,
+      /\bfiles? changed\b/i,
+      /\binsertions?\(\+\)/i,
+      /\bdeletions?\(-\)/i,
+      /^diff --git\b/i,
+    ],
+    anchorPatterns: [
+      /^(?:M|A|D|R|C|UU|\?\?)\s+/,
+      /\bfiles? changed\b/i,
+      /\binsertions?\(\+\)/i,
+      /\bdeletions?\(-\)/i,
+    ],
+    tailPatterns: [
+      /\bfiles? changed\b/i,
+      /\binsertions?\(\+\)/i,
+      /\bdeletions?\(-\)/i,
+    ],
+    noisePatterns: [],
+  },
+  {
+    id: 'docker-logs',
+    commandPatterns: [
+      /\bdocker(?:\s+compose)?\s+logs\b/i,
+    ],
+    importantPatterns: [
+      /\b(error|exception|warn|fatal|traceback|exited with code)\b/i,
+      /^[a-z0-9_.-]+(?:-\d+)?\s+\|/i,
+    ],
+    anchorPatterns: [
+      /\b(error|exception|fatal|traceback|exited with code)\b/i,
+      /^[a-z0-9_.-]+(?:-\d+)?\s+\|.*\b(error|exception|fatal|traceback)\b/i,
+    ],
+    tailPatterns: [],
+    noisePatterns: [
+      /^Attaching to\b/i,
+    ],
+  },
+];
+
+function stripAnsi(value) {
+  return String(value ?? '').replace(ANSI_RE, '');
+}
+
+function splitLines(value) {
+  return stripAnsi(value)
+    .split(/\r?\n/)
+    .map((line) => line.replace(/\s+$/g, ''));
+}
+
+function normalizeLineForDedupe(line) {
+  return String(line ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+function matchesAnyPattern(line, patterns = []) {
+  return patterns.some((pattern) => pattern.test(line));
+}
+
+function detectOutputProfile(command) {
+  const commandText = String(command ?? '').trim();
+  return OUTPUT_PROFILES.find((profile) => matchesAnyPattern(commandText, profile.commandPatterns)) ?? null;
+}
+
+function escapeRegExp(value) {
+  return String(value ?? '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function buildProjectRootVariants(projectRoot) {
+  const trimmed = String(projectRoot ?? '').trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  const resolved = path.resolve(trimmed).replace(/[\\/]+$/g, '');
+  return [...new Set([
+    resolved,
+    resolved.replace(/\\/g, '/'),
+    resolved.replace(/\//g, '\\'),
+  ].filter(Boolean))];
+}
+
+function shortenProjectRootSegments(value, projectRoot) {
+  let next = String(value ?? '');
+  if (!next.trim()) {
+    return next;
+  }
+
+  for (const variant of buildProjectRootVariants(projectRoot)) {
+    const escaped = escapeRegExp(variant);
+    next = next
+      .replace(new RegExp(`${escaped}(?:[\\\\/])`, 'g'), '')
+      .replace(new RegExp(`${escaped}(?=$|[\\s)'":])`, 'g'), '.');
+  }
+
+  return next;
+}
+
+function normalizeRuntimeRelativePath(filePath) {
+  return String(filePath ?? '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '');
+}
+
+function buildRawOutputRecoveryReason({ exitCode = null, tokensBefore = 0, savedTokens = 0 } = {}) {
+  if (Number.isFinite(Number(exitCode)) && Number(exitCode) !== 0) {
+    return 'failure';
+  }
+  if (Number(tokensBefore) >= RAW_OUTPUT_SAVE_MIN_TOKENS) {
+    return 'large-output';
+  }
+  if (Number(savedTokens) >= RAW_OUTPUT_SAVE_MIN_SAVED_TOKENS) {
+    return 'high-savings';
+  }
+  return null;
+}
+
+function sanitizeFileComponent(value, { fallback = 'output', maxLength = 48 } = {}) {
+  const normalized = String(value ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, maxLength);
+  return normalized || fallback;
+}
+
+function buildRecoveryFileName({
+  command = '',
+  summary = '',
+  profile = 'generic',
+  exitCode = null,
+} = {}) {
+  const slug = sanitizeFileComponent(String(command).split(/\s+/).slice(0, 3).join('-'), {
+    fallback: sanitizeFileComponent(profile, { fallback: 'output', maxLength: 16 }),
+    maxLength: 24,
+  });
+  const fingerprint = buildCompactMachineKey('tool-output-recovery-v1', {
+    command: String(command ?? '').trim(),
+    summary: String(summary ?? '').trim(),
+    profile: String(profile ?? 'generic').trim(),
+    exitCode: Number.isFinite(Number(exitCode)) ? Number(exitCode) : null,
+  }).split(':').at(-1)?.replace(/[^a-z0-9_-]/gi, '-').slice(0, 16) || 'recovery';
+  return `${slug}-${fingerprint}.log`;
+}
+
+function buildRawOutputText({ command = '', stdout = '', stderr = '', exitCode = null } = {}) {
+  const sections = [
+    `Command: ${String(command ?? '').trim() || 'unknown command'}`,
+  ];
+
+  if (Number.isFinite(Number(exitCode))) {
+    sections.push(`Exit code: ${Number(exitCode)}`);
+  }
+
+  sections.push('');
+
+  if (String(stdout ?? '').length > 0) {
+    sections.push('--- stdout ---');
+    sections.push(String(stdout));
+    sections.push('');
+  }
+
+  if (String(stderr ?? '').length > 0) {
+    sections.push('--- stderr ---');
+    sections.push(String(stderr));
+    sections.push('');
+  }
+
+  return `${sections.join('\n').trimEnd()}\n`;
+}
+
+function buildRecoveryHintSummary(summary, rawPath, { tokensBefore = 0 } = {}) {
+  const recoveryLine = `- Full output: ${rawPath}`;
+  const summaryLines = String(summary ?? '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (summaryLines.length === 0) {
+    return null;
+  }
+
+  const directCandidate = [...summaryLines, recoveryLine].join('\n');
+  if (estimateTokenCount(directCandidate) < tokensBefore) {
+    return directCandidate;
+  }
+
+  const removalPatterns = [
+    /^-\s*stderr\s*\|/i,
+    /^-\s*FAIL(?:ED)?\b/i,
+    /^-\s*PASS\b/i,
+    /^-\s*(?:Test Files|Tests|Duration|Start at)\b/i,
+  ];
+
+  for (const pattern of removalPatterns) {
+    const index = summaryLines.findIndex((line, lineIndex) => lineIndex > 0 && pattern.test(line));
+    if (index < 0) continue;
+    const candidate = [...summaryLines.slice(0, index), ...summaryLines.slice(index + 1), recoveryLine].join('\n');
+    if (estimateTokenCount(candidate) < tokensBefore) {
+      return candidate;
+    }
+  }
+
+  for (let index = summaryLines.length - 1; index >= 1; index -= 1) {
+    const candidate = [...summaryLines.slice(0, index), ...summaryLines.slice(index + 1), recoveryLine].join('\n');
+    if (estimateTokenCount(candidate) < tokensBefore) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+async function persistRawOutput(projectRoot, {
+  command = '',
+  summary = '',
+  profile = 'generic',
+  stdout = '',
+  stderr = '',
+  exitCode = null,
+} = {}) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const teeCacheDir = runtimePaths.teeCacheDir ?? path.join(runtimePaths.cacheRoot, 'tee');
+  const fileName = buildRecoveryFileName({
+    command,
+    summary,
+    profile,
+    exitCode,
+  });
+  const absolutePath = path.join(teeCacheDir, fileName);
+  const rawOutputText = buildRawOutputText({
+    command,
+    stdout,
+    stderr,
+    exitCode,
+  });
+
+  await fs.mkdir(teeCacheDir, { recursive: true });
+  await fs.writeFile(absolutePath, rawOutputText, 'utf8');
+
+  return {
+    rawSaved: true,
+    rawPath: normalizeRuntimeRelativePath(path.relative(projectRoot, absolutePath)),
+    rawBytes: Buffer.byteLength(rawOutputText, 'utf8'),
+  };
+}
+
+function isProgressNoise(line, profile = null) {
+  const normalized = String(line ?? '').trim();
+  if (!normalized) return true;
+  return matchesAnyPattern(normalized, [
+    ...GENERIC_NOISE_PATTERNS,
+    ...(profile?.noisePatterns ?? []),
+  ]);
+}
+
+function isImportantLine(line, profile = null) {
+  const normalized = String(line ?? '').trim();
+  if (!normalized) return false;
+  return matchesAnyPattern(normalized, [
+    ...GENERIC_IMPORTANT_PATTERNS,
+    ...(profile?.importantPatterns ?? []),
+  ]);
+}
+
+function isAnchorLine(line, profile = null) {
+  const normalized = String(line ?? '').trim();
+  if (!normalized) return false;
+  return matchesAnyPattern(normalized, [
+    ...GENERIC_ANCHOR_PATTERNS,
+    ...(profile?.anchorPatterns ?? []),
+  ]);
+}
+
+function isTailSummaryLine(line, profile = null) {
+  const normalized = String(line ?? '').trim();
+  if (!normalized) return false;
+  return matchesAnyPattern(normalized, [
+    ...GENERIC_TAIL_PATTERNS,
+    ...(profile?.tailPatterns ?? []),
+  ]);
+}
+
+function buildCompactedSummaryLines(lines, { maxTokens = 180, maxLines = 10, forceFirstCount = 1 } = {}) {
+  const sourceLines = Array.isArray(lines) ? lines : [];
+  const selected = [];
+  const seen = new Set();
+  let usedTokens = 0;
+  let nonEmptyCount = 0;
+
+  for (const line of sourceLines) {
+    const compressed = compressLine(line);
+    if (!compressed) continue;
+
+    const dedupeKey = compressed.toLowerCase();
+    if (seen.has(dedupeKey)) continue;
+
+    const tokens = estimateTokenCount(compressed);
+    const forceLine = nonEmptyCount < forceFirstCount;
+    const wouldOverflow = selected.length > 0 && (usedTokens + tokens) > maxTokens;
+    const wouldExceedLines = nonEmptyCount >= maxLines;
+
+    if (!forceLine && (wouldOverflow || wouldExceedLines)) {
+      break;
+    }
+    if (forceLine && wouldExceedLines) {
+      break;
+    }
+
+    selected.push(compressed);
+    seen.add(dedupeKey);
+    usedTokens += tokens;
+    nonEmptyCount += 1;
+  }
+
+  if (selected.length === 0 && sourceLines.length > 0) {
+    return compressMarkdownLines(sourceLines, { maxTokens, maxLines, preserveFirstLine: true });
+  }
+
+  return selected;
+}
+
+function findMissingAnchors(summary, anchorLines) {
+  const summaryText = String(summary ?? '').toLowerCase();
+  return anchorLines.filter((line) => {
+    const compressed = compressLine(line).toLowerCase();
+    return compressed && !summaryText.includes(compressed);
+  });
+}
+
+function uniqueLines(lines) {
+  const seen = new Set();
+  const unique = [];
+  for (const line of lines) {
+    const normalized = normalizeLineForDedupe(line);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    unique.push(String(line ?? '').trim());
+  }
+  return unique;
+}
+
+function looksLikeSearchPath(filePath) {
+  const normalized = String(filePath ?? '').trim();
+  if (!normalized) return false;
+  return /[\\/]/.test(normalized) || normalized.startsWith('.') || /\.(?:[a-z0-9]{1,10})(?:$|:)/i.test(normalized);
+}
+
+function parseSearchMatchLine(line) {
+  const trimmed = String(line ?? '').trim().replace(/^stderr:\s*/i, '');
+  if (!trimmed) return null;
+
+  let match = trimmed.match(/^(.+?):(\d+):(\d+):(.*)$/);
+  if (match && looksLikeSearchPath(match[1])) {
+    return {
+      rawLine: trimmed,
+      filePath: match[1],
+      anchor: `${match[1]}:${match[2]}:${match[3]}`,
+    };
+  }
+
+  match = trimmed.match(/^(.+?):(\d+):(.*)$/);
+  if (match && looksLikeSearchPath(match[1])) {
+    return {
+      rawLine: trimmed,
+      filePath: match[1],
+      anchor: `${match[1]}:${match[2]}`,
+    };
+  }
+
+  match = trimmed.match(/^(.+?):(.*)$/);
+  if (match && looksLikeSearchPath(match[1])) {
+    return {
+      rawLine: trimmed,
+      filePath: match[1],
+      anchor: match[1],
+    };
+  }
+
+  return null;
+}
+
+function buildSearchResultSelection(lines) {
+  const matches = [];
+  const extras = [];
+  const seenRaw = new Set();
+  for (const line of lines) {
+    const trimmed = String(line ?? '').trim();
+    if (!trimmed) continue;
+    const parsed = parseSearchMatchLine(trimmed);
+    if (parsed) {
+      const key = normalizeLineForDedupe(parsed.rawLine);
+      if (!seenRaw.has(key)) {
+        seenRaw.add(key);
+        matches.push(parsed);
+      }
+      continue;
+    }
+
+    if (/^Binary file .* matches$/i.test(trimmed) || /^\d+\s+matches?$/i.test(trimmed)) {
+      extras.push(trimmed);
+    }
+  }
+  if (matches.length === 0) {
+    return null;
+  }
+  const detailedMatches = [];
+  const usedDetailedKeys = new Set();
+  const seenDetailedFiles = new Set();
+  for (const match of matches) {
+    if (detailedMatches.length >= 2) break;
+    if (seenDetailedFiles.has(match.filePath)) continue;
+    detailedMatches.push(match);
+    usedDetailedKeys.add(normalizeLineForDedupe(match.rawLine));
+    seenDetailedFiles.add(match.filePath);
+  }
+
+  for (const match of matches) {
+    if (detailedMatches.length >= 2) break;
+    const key = normalizeLineForDedupe(match.rawLine);
+    if (usedDetailedKeys.has(key)) continue;
+    detailedMatches.push(match);
+    usedDetailedKeys.add(key);
+  }
+  const remainingAnchors = uniqueLines(
+    matches
+      .filter((match) => !usedDetailedKeys.has(normalizeLineForDedupe(match.rawLine)))
+      .map((match) => match.anchor),
+  );
+  const shownAnchors = remainingAnchors.slice(0, 3);
+  const remainingAnchorCount = Math.max(0, remainingAnchors.length - shownAnchors.length);
+
+  return {
+    anchorLines: uniqueLines([
+      ...detailedMatches.map((match) => match.rawLine),
+      ...remainingAnchors.slice(0, 6),
+    ]),
+    candidateLines: uniqueLines([
+      ...detailedMatches.map((match) => match.rawLine),
+      shownAnchors.length > 0
+        ? `Match anchors: ${shownAnchors.join(', ')}${remainingAnchorCount > 0 ? `, +${remainingAnchorCount} more` : ''}`
+        : null,
+      ...extras.slice(0, 1),
+    ].filter(Boolean)),
+  };
+}
+
+function parsePathListLine(line) {
+  const trimmed = String(line ?? '').trim().replace(/^stderr:\s*/i, '');
+  if (!trimmed || /[:*?"<>|]$/.test(trimmed) || /\s{2,}/.test(trimmed)) return null;
+  if (!(/[\\/]/.test(trimmed) || trimmed.startsWith('.') || /\.[a-z0-9]{1,10}$/i.test(trimmed))) return null;
+  return trimmed;
+}
+
+function cleanStructuredPathSegment(value) {
+  return String(value ?? '')
+    .trim()
+    .replace(/^['"]|['"]$/g, '')
+    .replace(/[\\/]+$/g, '');
+}
+
+function normalizeStructuredPath(parts) {
+  return (Array.isArray(parts) ? parts : [parts])
+    .flatMap((part) => String(part ?? '').split(/[\\/]/))
+    .map((segment) => segment.trim())
+    .filter(Boolean)
+    .join('/');
+}
+
+function filterLeafStructuredPaths(paths) {
+  const uniquePaths = uniqueLines(paths);
+  const parentPaths = new Set();
+
+  for (const filePath of uniquePaths) {
+    const parts = String(filePath ?? '').split('/').filter(Boolean);
+    while (parts.length > 1) {
+      parts.pop();
+      parentPaths.add(parts.join('/'));
+    }
+  }
+
+  const leafPaths = uniquePaths.filter((filePath) => !parentPaths.has(filePath));
+  return leafPaths.length > 0 ? leafPaths : uniquePaths;
+}
+
+function buildTreePathList(lines) {
+  const paths = [];
+  const stack = [];
+  let rootOffset = 0;
+
+  for (const line of lines) {
+    const raw = String(line ?? '')
+      .replace(/^stderr:\s*/i, '')
+      .replace(/\s+$/g, '');
+    const trimmed = raw.trim();
+    if (!trimmed || /^\d+\s+directories?,\s+\d+\s+files?$/i.test(trimmed)) continue;
+
+    if (trimmed === '.' || trimmed === './') {
+      stack.length = 0;
+      rootOffset = 0;
+      continue;
+    }
+
+    const branchMatch = raw.match(/^((?:[│ ]{4})*)(?:[├└]── )(.+)$/u);
+    if (branchMatch) {
+      const depth = Math.floor(branchMatch[1].length / 4) + rootOffset;
+      const name = cleanStructuredPathSegment(branchMatch[2]);
+      if (!name || name === '.' || name === '..') continue;
+      stack[depth] = name;
+      stack.length = depth + 1;
+      const filePath = normalizeStructuredPath(stack);
+      if (filePath) paths.push(filePath);
+      continue;
+    }
+
+    if (/^[│├└]/u.test(trimmed) || /:$/.test(trimmed) || /^total\s+\d+/i.test(trimmed)) {
+      continue;
+    }
+
+    const name = cleanStructuredPathSegment(trimmed);
+    if (!name || name === '.' || name === '..') continue;
+    stack[0] = name;
+    stack.length = 1;
+    rootOffset = 1;
+    const filePath = normalizeStructuredPath(stack);
+    if (filePath) paths.push(filePath);
+  }
+
+  return filterLeafStructuredPaths(paths);
+}
+
+function buildRecursiveListingPathList(lines) {
+  const sectionDirs = new Set();
+  const paths = [];
+  let currentDir = null;
+
+  for (const line of lines) {
+    const trimmed = String(line ?? '')
+      .trim()
+      .replace(/^stderr:\s*/i, '');
+    if (!trimmed || /^total\s+\d+/i.test(trimmed)) continue;
+
+    const sectionMatch = trimmed.match(/^(.+):$/);
+    if (sectionMatch) {
+      const sectionPath = cleanStructuredPathSegment(sectionMatch[1]);
+      if (!sectionPath) continue;
+      currentDir = sectionPath === '.'
+        ? '.'
+        : normalizeStructuredPath(sectionPath);
+      if (currentDir && currentDir !== '.') {
+        sectionDirs.add(currentDir);
+      }
+      continue;
+    }
+
+    if (!currentDir || trimmed === '.' || trimmed === '..') continue;
+
+    const entryName = cleanStructuredPathSegment(trimmed);
+    if (!entryName) continue;
+
+    const filePath = currentDir === '.'
+      ? normalizeStructuredPath([entryName])
+      : normalizeStructuredPath([currentDir, entryName]);
+    if (filePath) {
+      paths.push(filePath);
+    }
+  }
+
+  const leafPaths = uniqueLines(paths.filter((filePath) => !sectionDirs.has(filePath)));
+  return leafPaths.length > 0 ? leafPaths : uniqueLines(paths);
+}
+
+function extractPathCandidates(lines) {
+  const treePaths = buildTreePathList(lines);
+  const recursivePaths = buildRecursiveListingPathList(lines);
+  const directPaths = uniqueLines(lines.map((line) => parsePathListLine(line)).filter(Boolean));
+  const hasRecursiveSections = lines.some((line) => /^.+:\s*$/.test(String(line ?? '').trim().replace(/^stderr:\s*/i, '')));
+
+  if (hasRecursiveSections && recursivePaths.length > 0) {
+    return recursivePaths;
+  }
+  if (treePaths.length > 0 && treePaths.length >= recursivePaths.length && treePaths.length >= directPaths.length) {
+    return treePaths;
+  }
+  if (recursivePaths.length > 0 && recursivePaths.length >= directPaths.length) {
+    return recursivePaths;
+  }
+  return directPaths;
+}
+
+function getPathAreaKey(filePath) {
+  const parts = String(filePath ?? '').split(/[\\/]/).filter(Boolean);
+  if (parts[0] === '.') parts.shift();
+  if (parts.length === 0) return String(filePath ?? '');
+  if (parts[0] === 'docs') return 'docs';
+  if (parts.length >= 2 && ['src', 'tests', 'test', 'app', 'lib'].includes(parts[0])) return `${parts[0]}/${parts[1]}`;
+  return parts[0];
+}
+
+function getPathTopLevelKey(filePath) {
+  const parts = String(filePath ?? '').split(/[\\/]/).filter(Boolean);
+  if (parts[0] === '.') parts.shift();
+  return parts[0] || String(filePath ?? '');
+}
+
+function buildPathListSelection(lines) {
+  const paths = extractPathCandidates(lines);
+  if (paths.length === 0) return null;
+  if (paths.length <= 6) return { anchorLines: paths, candidateLines: paths };
+
+  const detailedPaths = [];
+  const usedAreas = new Set();
+  for (const filePath of paths) {
+    const areaKey = getPathAreaKey(filePath);
+    if (usedAreas.has(areaKey)) continue;
+    detailedPaths.push(filePath);
+    usedAreas.add(areaKey);
+    if (detailedPaths.length >= 4) break;
+  }
+  for (const filePath of paths) {
+    if (detailedPaths.length >= 4) break;
+    if (detailedPaths.includes(filePath)) continue;
+    detailedPaths.push(filePath);
+  }
+
+  const remainingPaths = paths.filter((filePath) => !detailedPaths.includes(filePath));
+  const shownAnchors = [];
+  const shownAnchorTopLevels = new Set();
+  for (const filePath of remainingPaths) {
+    const topLevelKey = getPathTopLevelKey(filePath);
+    if (shownAnchorTopLevels.has(topLevelKey)) continue;
+    shownAnchors.push(filePath);
+    shownAnchorTopLevels.add(topLevelKey);
+    if (shownAnchors.length >= 2) break;
+  }
+  for (const filePath of remainingPaths) {
+    if (shownAnchors.length >= 2) break;
+    if (shownAnchors.includes(filePath)) continue;
+    shownAnchors.push(filePath);
+  }
+
+  return {
+    anchorLines: uniqueLines([...detailedPaths, ...shownAnchors]),
+    candidateLines: uniqueLines([
+      ...detailedPaths,
+      shownAnchors.length > 0
+        ? `Path anchors: ${shownAnchors.join(', ')}${remainingPaths.length > shownAnchors.length ? `, +${remainingPaths.length - shownAnchors.length} more` : ''}`
+        : null,
+    ].filter(Boolean)),
+  };
+}
+
+function parseGitChangeLine(line) {
+  const trimmed = String(line ?? '').trim().replace(/^stderr:\s*/i, '');
+  if (!trimmed) return null;
+
+  const statusMatch = trimmed.match(/^([ MADRCU?]{1,2})\s+(.+)$/);
+  if (statusMatch && looksLikeSearchPath(statusMatch[2].split(' -> ').at(-1))) {
+    const status = statusMatch[1].replace(/\s+/g, ' ').trim() || '?';
+    const filePath = statusMatch[2].split(' -> ').at(-1);
+    return { rawLine: trimmed, anchor: `${status} ${filePath}`, filePath, kind: 'status' };
+  }
+
+  const statMatch = trimmed.match(/^(.+?)\s+\|\s+\d+\s+[+\-]+$/);
+  if (statMatch && looksLikeSearchPath(statMatch[1].trim())) {
+    const filePath = statMatch[1].trim();
+    return { rawLine: trimmed, anchor: filePath, filePath, kind: 'stat' };
+  }
+
+  const filePath = parsePathListLine(trimmed);
+  return filePath ? { rawLine: filePath, anchor: filePath, filePath, kind: 'path' } : null;
+}
+
+function buildGitSelection(lines) {
+  const summaryLines = uniqueLines(lines.filter((line) => /\bfiles? changed\b|\binsertions?\(\+\)|\bdeletions?\(-\)/i.test(String(line ?? '').trim())));
+  const entries = [];
+  const seen = new Set();
+  for (const line of lines) {
+    const entry = parseGitChangeLine(line);
+    if (!entry) continue;
+    const key = normalizeLineForDedupe(entry.rawLine);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    entries.push(entry);
+  }
+  if (entries.length === 0 || (entries.length <= 4 && summaryLines.length <= 1)) return null;
+
+  const detailed = [];
+  const addDetailed = (predicate) => {
+    const entry = entries.find((item) => !detailed.includes(item) && predicate(item));
+    if (entry) detailed.push(entry);
+  };
+  addDetailed((item) => /^(?:src|app|lib)\//.test(item.filePath));
+  if (summaryLines.length > 0) addDetailed((item) => /^(?:src|app|lib)\//.test(item.filePath));
+  addDetailed((item) => /^(?:tests?|specs?)\//.test(item.filePath));
+  if (summaryLines.length === 0) addDetailed((item) => /^docs\//.test(item.filePath));
+  while (detailed.length < 3) {
+    const entry = entries.find((item) => !detailed.includes(item));
+    if (!entry) break;
+    detailed.push(entry);
+  }
+
+  const remaining = entries.filter((item) => !detailed.includes(item));
+  const shownAnchor = remaining.find((item) => /^docs\//.test(item.filePath)) || remaining[0] || null;
+  return {
+    anchorLines: uniqueLines([...detailed.map((item) => item.rawLine), ...(shownAnchor ? [shownAnchor.anchor] : []), ...summaryLines]),
+    candidateLines: uniqueLines([
+      ...detailed.map((item) => item.rawLine),
+      shownAnchor ? `Changed paths: ${shownAnchor.anchor}${remaining.length > 1 ? `, +${remaining.length - 1} more` : ''}` : null,
+      ...summaryLines,
+    ].filter(Boolean)),
+  };
+}
+
+function selectCandidateLines(lines, profile = null) {
+  if (profile?.id === 'git') {
+    const gitSelection = buildGitSelection(lines);
+    if (gitSelection) return gitSelection;
+  }
+  if (profile?.id === 'paths') {
+    const pathSelection = buildPathListSelection(lines);
+    if (pathSelection) return pathSelection;
+  }
+  if (profile?.id === 'search') {
+    const searchSelection = buildSearchResultSelection(lines);
+    if (searchSelection) {
+      return searchSelection;
+    }
+  }
+
+  const important = [];
+  const anchors = [];
+  const fallback = [];
+  const tail = [];
+  const seen = new Set();
+  const hasFailureSignal = lines.some((line) => /\b(error|fail(?:ed)?|assertionerror|exception|fatal)\b/i.test(String(line ?? '')));
+
+  for (const line of lines) {
+    const trimmed = String(line ?? '').trim();
+    const normalized = normalizeLineForDedupe(trimmed);
+    if (!normalized || seen.has(normalized)) continue;
+
+    const progressNoise = isProgressNoise(trimmed, profile);
+    const importantLine = isImportantLine(trimmed, profile);
+    const anchorLine = isAnchorLine(trimmed, profile);
+    const shouldDropOnFailure = hasFailureSignal && (/^\s*RUN\b/i.test(trimmed) || /^\s*✓\s+/i.test(trimmed) || /^stdout\s*\|/i.test(trimmed));
+
+    if (anchorLine && !shouldDropOnFailure) {
+      anchors.push(trimmed);
+      important.push(trimmed);
+      seen.add(normalized);
+      continue;
+    }
+
+    if (importantLine && !shouldDropOnFailure) {
+      important.push(trimmed);
+      seen.add(normalized);
+      continue;
+    }
+
+    if (!progressNoise && !shouldDropOnFailure && fallback.length < 3) {
+      fallback.push(trimmed);
+      seen.add(normalized);
+    }
+  }
+
+  for (const line of [...lines].reverse()) {
+    const trimmed = String(line ?? '').trim();
+    const normalized = normalizeLineForDedupe(trimmed);
+    if (!normalized || seen.has(normalized) || isProgressNoise(trimmed, profile)) continue;
+
+    if (isTailSummaryLine(trimmed, profile)) {
+      tail.unshift(trimmed);
+      seen.add(normalized);
+    }
+    if (tail.length >= 4) break;
+  }
+
+  return {
+    anchorLines: uniqueLines([...anchors, ...tail]).slice(0, 6),
+    candidateLines: uniqueLines([...important, ...tail, ...fallback]),
+  };
+}
+
+export function compressToolOutput({
+  command = '',
+  stdout = '',
+  stderr = '',
+  exitCode = null,
+  maxTokens = 180,
+  projectRoot = null,
+} = {}) {
+  const commandText = String(command ?? '').trim();
+  const displayCommand = shortenProjectRootSegments(commandText, projectRoot).trim() || commandText;
+  const profile = detectOutputProfile(displayCommand);
+  const stdoutLines = splitLines(stdout).map((line) => shortenProjectRootSegments(line, projectRoot));
+  const stderrLines = splitLines(stderr).map((line) => shortenProjectRootSegments(line, projectRoot));
+  const allLines = [
+    ...stdoutLines,
+    ...stderrLines.map((line) => (line.trim() ? `stderr: ${line}` : line)),
+  ];
+  const rawText = [commandText, stdout, stderr].filter(Boolean).join('\n');
+  const { candidateLines, anchorLines } = selectCandidateLines(allLines, profile);
+  const headerLine = `- Recent command: ${displayCommand || 'unknown command'}${exitCode === null || exitCode === undefined ? '' : ` (exit ${exitCode})`}`;
+  const compactedLines = buildCompactedSummaryLines([headerLine, ...candidateLines.map((line) => `- ${line}`)], {
+    maxTokens,
+    maxLines: 10,
+  });
+  let summary = compactedLines.join('\n').trim();
+  let validationMode = 'default';
+  const missingAnchors = findMissingAnchors(summary, anchorLines);
+
+  if (missingAnchors.length > 0) {
+    const anchorFirstLines = buildCompactedSummaryLines([
+      headerLine,
+      ...anchorLines.map((line) => `- ${line}`),
+      ...candidateLines.map((line) => `- ${line}`),
+    ], {
+      maxTokens,
+      maxLines: 10,
+      forceFirstCount: Math.min(1 + anchorLines.length, 5),
+    });
+    const anchorFirstSummary = anchorFirstLines.join('\n').trim();
+
+    if (findMissingAnchors(anchorFirstSummary, anchorLines).length === 0) {
+      summary = anchorFirstSummary;
+      validationMode = 'anchor-first';
+    } else {
+      const compactHeaderLine = `- Cmd: ${displayCommand || 'unknown'}${exitCode === null || exitCode === undefined ? '' : ` (exit ${exitCode})`}`;
+      summary = buildCompactedSummaryLines([
+        compactHeaderLine,
+        ...anchorLines.map((line) => `- ${line}`),
+      ], {
+        maxTokens,
+        maxLines: 10,
+        forceFirstCount: Math.min(1 + anchorLines.length, 5),
+      }).join('\n').trim();
+      validationMode = 'forced-anchors';
+    }
+  }
+
+  const tokensBefore = estimateTokenCount(rawText);
+  const tokensAfter = estimateTokenCount(summary);
+
+  return {
+    summary,
+    tokensBefore,
+    tokensAfter,
+    savedTokens: Math.max(0, tokensBefore - tokensAfter),
+    rawLineCount: allLines.filter((line) => line.trim()).length,
+    keptLineCount: summary.split(/\r?\n/).filter((line) => line.trim()).length,
+    command: displayCommand,
+    exitCode,
+    profile: profile?.id ?? 'generic',
+    validationMode,
+  };
+}
+
+function normalizeOutputHistoryEntry(entry) {
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+
+  const timestamp = Number(entry.timestamp);
+  const tokensBefore = Number(entry.tokensBefore);
+  const tokensAfter = Number(entry.tokensAfter);
+  const savedTokens = Number(entry.savedTokens);
+  const command = typeof entry.command === 'string' ? entry.command.trim() : '';
+  const summary = typeof entry.summary === 'string' ? entry.summary : '';
+  const rawPath = typeof entry.rawPath === 'string' ? normalizeRuntimeRelativePath(entry.rawPath) : '';
+  const rawBytes = Number(entry.rawBytes);
+  const recoveryReason = typeof entry.recoveryReason === 'string' ? entry.recoveryReason.trim() : '';
+  const truncated = typeof entry.truncated === 'boolean' ? entry.truncated : false;
+
+  return {
+    ...entry,
+    command,
+    summary,
+    timestamp: Number.isFinite(timestamp) ? timestamp : Date.now(),
+    tokensBefore: Number.isFinite(tokensBefore) ? tokensBefore : 0,
+    tokensAfter: Number.isFinite(tokensAfter) ? tokensAfter : 0,
+    savedTokens: Number.isFinite(savedTokens) ? savedTokens : 0,
+    rawSaved: Boolean(entry.rawSaved),
+    rawPath,
+    rawBytes: Number.isFinite(rawBytes) ? rawBytes : 0,
+    recoveryReason: recoveryReason || null,
+    truncated,
+  };
+}
+
+function normalizeOutputSummaryForDedupe(summary) {
+  return String(summary ?? '')
+    .split(/\r?\n/)
+    .map((line) => String(line ?? '').trim())
+    .filter((line) => line && !/^- Full output:\s+/i.test(line))
+    .join('\n');
+}
+
+function buildOutputHistoryDedupeKey(entry) {
+  return [
+    String(entry?.command ?? '').trim(),
+    normalizeOutputSummaryForDedupe(entry?.summary),
+  ].join('\n').trim().toLowerCase();
+}
+
+function normalizeOutputHistoryDocument(raw, { maxEntries = DEFAULT_OUTPUT_HISTORY_MAX_ENTRIES } = {}) {
+  const candidates = Array.isArray(raw?.entries)
+    ? raw.entries
+    : Array.isArray(raw)
+      ? raw
+      : [];
+
+  return {
+    entries: candidates
+      .map((entry) => normalizeOutputHistoryEntry(entry))
+      .filter(Boolean)
+      .sort((left, right) => (right.timestamp ?? 0) - (left.timestamp ?? 0))
+      .slice(0, maxEntries),
+  };
+}
+
+export async function readOutputHistory(projectRoot, options = {}) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const raw = await readJsonIfExists(runtimePaths.outputHistoryPath);
+  return normalizeOutputHistoryDocument(raw, options);
+}
+
+export async function appendOutputHistory(projectRoot, entry, options = {}) {
+  const normalizedEntry = normalizeOutputHistoryEntry(entry);
+  if (!normalizedEntry || !normalizedEntry.command || !normalizedEntry.summary) {
+    return readOutputHistory(projectRoot, options);
+  }
+
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const history = await readOutputHistory(projectRoot, options);
+  const normalizedKey = buildOutputHistoryDedupeKey(normalizedEntry);
+  const dedupedExistingEntries = history.entries.filter((candidate) => !(
+    buildOutputHistoryDedupeKey(candidate) === normalizedKey
+  ));
+  const nextDocument = normalizeOutputHistoryDocument({
+    entries: [normalizedEntry, ...dedupedExistingEntries],
+  }, options);
+  await writeJson(runtimePaths.outputHistoryPath, nextDocument);
+  return nextDocument;
+}
+
+export function summarizeOutputHistory(rawHistory) {
+  const history = normalizeOutputHistoryDocument(rawHistory);
+  if (history.entries.length === 0) {
+    return {
+      lastCompressedAt: 'never',
+      savingsLabel: 'n/a',
+      entryCount: 0,
+      recoveryCount: 0,
+      byProfile: [],
+    };
+  }
+
+  const totalBefore = history.entries.reduce((sum, entry) => sum + (entry.tokensBefore ?? 0), 0);
+  const totalSaved = history.entries.reduce((sum, entry) => sum + (entry.savedTokens ?? 0), 0);
+  const recoveryCount = history.entries.reduce((sum, entry) => sum + (entry.rawSaved ? 1 : 0), 0);
+  const latest = history.entries[0];
+  const percentage = totalBefore > 0 ? Math.trunc((totalSaved / totalBefore) * 100) : 0;
+  const byProfileMap = new Map();
+
+  for (const entry of history.entries) {
+    const profile = typeof entry.profile === 'string' && entry.profile.trim()
+      ? entry.profile.trim()
+      : (detectOutputProfile(String(entry.command ?? ''))?.id ?? 'generic');
+    const bucket = byProfileMap.get(profile) ?? {
+      profile,
+      entryCount: 0,
+      totalBefore: 0,
+      totalSaved: 0,
+      recoveryCount: 0,
+    };
+    bucket.entryCount += 1;
+    bucket.totalBefore += Number(entry.tokensBefore ?? 0);
+    bucket.totalSaved += Number(entry.savedTokens ?? 0);
+    bucket.recoveryCount += entry.rawSaved ? 1 : 0;
+    byProfileMap.set(profile, bucket);
+  }
+
+  const byProfile = [...byProfileMap.values()]
+    .map((bucket) => ({
+      ...bucket,
+      savingsLabel: bucket.entryCount > 0 && bucket.totalBefore > 0
+        ? `${Math.trunc((bucket.totalSaved / bucket.totalBefore) * 100)}% avg`
+        : 'n/a',
+    }))
+    .sort((left, right) => (
+      right.totalSaved - left.totalSaved
+      || right.entryCount - left.entryCount
+      || left.profile.localeCompare(right.profile)
+    ));
+
+  return {
+    lastCompressedAt: latest.timestamp ? new Date(latest.timestamp).toISOString() : 'unknown',
+    savingsLabel: `${percentage}% avg`,
+    entryCount: history.entries.length,
+    recoveryCount,
+    byProfile,
+  };
+}
+
+export async function captureCompressedToolOutput(
+  projectRoot,
+  {
+    command = '',
+    stdout = '',
+    stderr = '',
+    exitCode = null,
+    promptCache = true,
+    maxTokens = 180,
+  } = {},
+) {
+  const requestKey = buildCompactMachineKey('tool-output-v1', {
+    command: String(command ?? '').trim(),
+    stdoutHash: buildCompactMachineKey('stdout', stripAnsi(stdout)),
+    stderrHash: buildCompactMachineKey('stderr', stripAnsi(stderr)),
+    exitCode,
+    maxTokens,
+  });
+
+  if (promptCache) {
+    const cached = await readPromptCacheEntry(projectRoot, requestKey, { touch: true });
+    if (cached?.content) {
+      const cachedCommand = String(cached.metadata?.command ?? command ?? '').trim();
+      const cachedDisplayCommand = shortenProjectRootSegments(cachedCommand, projectRoot).trim() || cachedCommand;
+      const cachedProfile = typeof cached.metadata?.profile === 'string' && cached.metadata.profile.trim()
+        ? cached.metadata.profile.trim()
+        : (detectOutputProfile(cachedDisplayCommand)?.id ?? 'generic');
+      await appendOutputHistory(projectRoot, {
+        timestamp: Date.now(),
+        command: cachedCommand,
+        profile: cachedProfile,
+        summary: String(cached.content),
+        tokensBefore: cached.tokensBefore ?? 0,
+        tokensAfter: cached.tokensAfter ?? 0,
+        savedTokens: cached.savedTokens ?? 0,
+        exitCode,
+        rawSaved: Boolean(cached.metadata?.rawSaved),
+        rawPath: cached.metadata?.rawPath ?? '',
+        rawBytes: cached.metadata?.rawBytes ?? 0,
+        recoveryReason: cached.metadata?.recoveryReason ?? null,
+        truncated: Boolean(cached.metadata?.truncated),
+      });
+      return {
+        requestKey,
+        summary: cached.content,
+        tokensBefore: cached.tokensBefore ?? 0,
+        tokensAfter: cached.tokensAfter ?? 0,
+        savedTokens: cached.savedTokens ?? 0,
+        command: String(command ?? '').trim(),
+        exitCode,
+        rawSaved: Boolean(cached.metadata?.rawSaved),
+        rawPath: cached.metadata?.rawPath ?? '',
+        rawBytes: cached.metadata?.rawBytes ?? 0,
+        recoveryReason: cached.metadata?.recoveryReason ?? null,
+        fromCache: true,
+      };
+    }
+  }
+
+  const result = compressToolOutput({
+    command,
+    stdout,
+    stderr,
+    exitCode,
+    maxTokens,
+    projectRoot,
+  });
+  const recoveryReason = buildRawOutputRecoveryReason({
+    exitCode,
+    tokensBefore: result.tokensBefore,
+    savedTokens: result.savedTokens,
+  });
+  let rawOutputMetadata = {
+    rawSaved: false,
+    rawPath: '',
+    rawBytes: 0,
+    recoveryReason: null,
+    truncated: false,
+  };
+
+  if (recoveryReason) {
+    rawOutputMetadata = {
+      ...rawOutputMetadata,
+      ...(await persistRawOutput(projectRoot, {
+        command,
+        summary: result.summary,
+        profile: result.profile,
+        stdout,
+        stderr,
+        exitCode,
+      })),
+      recoveryReason,
+    };
+    const summaryWithRecoveryHint = buildRecoveryHintSummary(result.summary, rawOutputMetadata.rawPath, {
+      tokensBefore: result.tokensBefore,
+    });
+    if (summaryWithRecoveryHint) {
+      result.summary = summaryWithRecoveryHint;
+      result.tokensAfter = estimateTokenCount(result.summary);
+      result.savedTokens = Math.max(0, result.tokensBefore - result.tokensAfter);
+      result.keptLineCount = result.summary.split(/\r?\n/).filter((line) => line.trim()).length;
+    }
+  }
+  await appendOutputHistory(projectRoot, {
+    timestamp: Date.now(),
+    command: result.command,
+    profile: result.profile,
+    summary: result.summary,
+    tokensBefore: result.tokensBefore,
+    tokensAfter: result.tokensAfter,
+    savedTokens: result.savedTokens,
+    exitCode,
+    ...rawOutputMetadata,
+  });
+
+  await recordCompaction(projectRoot, {
+    source: 'tool-output',
+    beforeText: [command, stdout, stderr].filter(Boolean).join('\n'),
+    afterText: result.summary,
+    metadata: {
+      command: result.command,
+      exitCode,
+    },
+  });
+
+  if (promptCache) {
+    await writePromptCacheEntry(projectRoot, {
+      requestKey,
+      kind: 'tool-output',
+      updatedAt: Date.now(),
+      tokensBefore: result.tokensBefore,
+      tokensAfter: result.tokensAfter,
+      savedTokens: result.savedTokens,
+      content: result.summary,
+      metadata: {
+        command: result.command,
+        exitCode,
+        profile: result.profile,
+        rawSaved: rawOutputMetadata.rawSaved,
+        rawPath: rawOutputMetadata.rawPath,
+        rawBytes: rawOutputMetadata.rawBytes,
+        recoveryReason: rawOutputMetadata.recoveryReason,
+        truncated: rawOutputMetadata.truncated,
+      },
+    });
+  }
+
+  return {
+    requestKey,
+    ...result,
+    ...rawOutputMetadata,
+    fromCache: false,
+  };
+}
+
+export function selectFreshOutputEntries(rawHistory, { now = Date.now(), limit = 1 } = {}) {
+  const history = normalizeOutputHistoryDocument(rawHistory);
+  return history.entries
+    .filter((entry) => typeof entry.timestamp === 'number' && (now - entry.timestamp) <= FRESH_OUTPUT_WINDOW_MS)
+    .slice(0, limit);
+}