diffsplain 0.5.0 → 0.6.0

package/scripts/generate-summaries.mjs

@@ -3,10 +3,9 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import {
-  mkdirSync,
+  existsSync,
   mkdtempSync,
   readFileSync,
-  renameSync,
   rmSync,
   writeFileSync,
 } from 'node:fs';
@@ -15,12 +14,25 @@ import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   agentCommand,
+  assertReasoningSupported,
   codingAgentBinary,
   commandAvailable,
   parseAgentResponse,
   selectCodingAgent,
 } from './coding-agents.mjs';
 import { summaryPath } from './summary-path.mjs';
+import {
+  acquireLease,
+  publishLeaseFile,
+  refreshLease,
+  releaseLease,
+} from './cache.mjs';
+import {
+  createSupportRecorder,
+  formatSupportRecord,
+  safeCommandVersion,
+  writeSupportRecord,
+} from './support-record.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const callerDirectory = process.cwd();
@@ -43,8 +55,14 @@ const valueFlags = new Set([
   '--batch-size',
   '--jobs',
   '--snapshot',
+  '--support-record-file',
+]);
+const booleanFlags = new Set([
+  '--checkout',
+  '--force',
+  '--support-record',
+  '--worktree',
 ]);
-const booleanFlags = new Set(['--checkout', '--force', '--worktree']);
 
 function fail(message) {
   console.error(message);
@@ -86,12 +104,16 @@ Options:
   --summaries FILE    Agent note file
   --output FILE       Rebuilt Diffsplain JSON
   --cache-dir PATH    Bare cache for fetched Git objects
-  --agent NAME        Use codex, claude, copilot, cursor, or opencode
+  --agent NAME        Use codex, claude, copilot, or opencode
+                      Cursor is disabled because it cannot meet the review boundary
   --codex-bin FILE    Codex CLI path (default: codex)
   --model NAME        Model passed to the coding agent
   --reasoning LEVEL   Agent reasoning effort when supported
   --batch-size COUNT  Maximum files per agent pass (default: 12)
   --jobs COUNT        Agent passes to run at once (default: 3)
+  --support-record    Print a safe record if this run fails
+  --support-record-file FILE
+                      Write a safe record if this run fails
   --force             Regenerate all notes instead of using cached notes`);
   process.exit(0);
 }
@@ -101,18 +123,22 @@ const outputPath = resolve(
   callerDirectory,
   option('--output') || resolve(root, '.cache/diff-data.json'),
 );
+const printSupportRecord = rawArgs.includes('--support-record');
+const supportRecordFile = option('--support-record-file');
+if (printSupportRecord && supportRecordFile) {
+  fail('Pass either --support-record or --support-record-file, not both');
+}
+const supportRecordPath = supportRecordFile
+  ? resolve(callerDirectory, supportRecordFile)
+  : undefined;
 const codexBin = option('--codex-bin') || process.env.CODEX_BIN;
+const requestedAgent = option('--agent');
+const supportRecorder =
+  printSupportRecord || supportRecordPath
+    ? createSupportRecorder()
+    : undefined;
 let selectedAgent;
-try {
-  selectedAgent = await selectCodingAgent(
-    option('--agent'),
-    (agent) =>
-      commandAvailable(codingAgentBinary(agent, { codexBin })),
-  );
-} catch (error) {
-  fail(error.message);
-}
-const agentBinary = codingAgentBinary(selectedAgent, { codexBin });
+let agentBinary;
 const model = option('--model');
 const reasoning = option('--reasoning');
 const batchSizeValue = option('--batch-size') || '12';
@@ -126,11 +152,27 @@ const reasoningLevels = new Set([
 if (reasoning && !reasoningLevels.has(reasoning)) {
   fail('--reasoning must be minimal, low, medium, high, or xhigh');
 }
+if (requestedAgent) {
+  try {
+    await selectCodingAgent(requestedAgent, async () => true);
+    assertReasoningSupported(requestedAgent, reasoning);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
 if (!/^[1-9]\d*$/.test(batchSizeValue) || Number(batchSizeValue) > 50) {
   fail('--batch-size must be a number from 1 to 50');
 }
 const batchSize = Number(batchSizeValue);
 const batchByteLimit = 180_000;
+const softFileByteLimit = 180_000;
+const hardInputByteLimit = 2_000_000;
+const priorNoteByteLimit = 250_000;
+const titleCodePointLimit = 160;
+const proseCodePointLimit = 1_200;
+const detailItemLimit = 4;
+const riskItemLimit = 3;
+const listItemCodePointLimit = 500;
 const jobsValue = option('--jobs') || '3';
 if (!/^[1-9]\d*$/.test(jobsValue) || Number(jobsValue) > 8) {
   fail('--jobs must be a number from 1 to 8');
@@ -148,10 +190,37 @@ const snapshotPath = option('--snapshot');
 const activeAgentProcesses = new Set();
 let interrupted = false;
 
-process.once('SIGTERM', () => {
+function recordSyncStage(name, action) {
+  const finishStage = supportRecorder?.startStage(name);
+  try {
+    const result = action();
+    finishStage?.();
+    return result;
+  } catch (error) {
+    finishStage?.('failed');
+    throw error;
+  }
+}
+
+async function recordAsyncStage(name, action) {
+  const finishStage = supportRecorder?.startStage(name);
+  try {
+    const result = await action();
+    finishStage?.();
+    return result;
+  } catch (error) {
+    finishStage?.('failed');
+    throw error;
+  }
+}
+
+function interrupt() {
   interrupted = true;
   for (const child of activeAgentProcesses) child.kill('SIGTERM');
-});
+}
+
+process.once('SIGINT', interrupt);
+process.once('SIGTERM', interrupt);
 
 if (range && (base || head)) {
   fail('--range cannot be used with --base or --head');
@@ -192,8 +261,21 @@ const summariesPath = summaryPath({
   head: selectedHead,
   remote,
 });
+const ownershipPath = `${summariesPath}.lock`;
+let ownership;
+let ownershipHeartbeat;
+function acquireOwnership() {
+  ownership = acquireLease(ownershipPath);
+  ownershipHeartbeat = setInterval(() => {
+    try { refreshLease(ownership); } catch { clearInterval(ownershipHeartbeat); }
+  }, 30_000);
+  ownershipHeartbeat.unref();
+}
 if (selectedBase) targetArgs.push('--base', selectedBase);
 if (selectedHead) targetArgs.push('--head', selectedHead);
+if (supportRecordPath) {
+  targetArgs.push('--exclude-output', supportRecordPath);
+}
 const cacheDirectory = option('--cache-dir');
 if (cacheDirectory) {
   targetArgs.push('--cache-dir', resolve(callerDirectory, cacheDirectory));
@@ -233,15 +315,17 @@ function pathInsideRepo(file) {
 }
 
 function cleanSnapshot(snapshot) {
+  const summaryFile = pathInsideRepo(summariesPath);
   const excluded = new Set(
-    [pathInsideRepo(summariesPath), pathInsideRepo(outputPath)].filter(Boolean),
+    [summaryFile, summaryFile && `${summaryFile}.lock`, pathInsideRepo(outputPath)].filter(Boolean),
   );
   const files = snapshot.files
     .filter((file) => !excluded.has(file.path))
     .map((file) => {
       const fullPatch = typeof file.patch === 'string' ? file.patch : '';
-      const useSnippet = fullPatch.length > 180_000;
-      return {
+      const useSnippet =
+        Buffer.byteLength(fullPatch) > softFileByteLimit;
+      const summaryFile = {
         path: file.path,
         ...(file.oldPath ? { oldPath: file.oldPath } : {}),
         status: file.status,
@@ -251,6 +335,16 @@ function cleanSnapshot(snapshot) {
         patch: useSnippet ? file.snippet : fullPatch,
         patchIsExcerpt: useSnippet,
       };
+      const inputBytes = Buffer.byteLength(JSON.stringify(summaryFile));
+      return {
+        ...summaryFile,
+        ...(inputBytes > hardInputByteLimit
+          ? {
+              summaryFailure:
+                `The file input is ${inputBytes} bytes after using its patch excerpt; the hard limit is ${hardInputByteLimit} bytes.`,
+            }
+          : {}),
+      };
     });
 
   return {
@@ -273,11 +367,35 @@ function cleanSnapshot(snapshot) {
   };
 }
 
+// fallow-ignore-next-line complexity
+function compactExistingFileNotes(snapshot, existingFiles, selected, baseBytes) {
+  const existingFileNotes = {};
+  const propertyBytes = Buffer.byteLength(',"existingFileNotes":');
+  const maximumBytes = Math.min(
+    priorNoteByteLimit,
+    hardInputByteLimit - baseBytes - propertyBytes,
+  );
+  let contextBytes = Buffer.byteLength('{}');
+  let hasEntries = false;
+  for (const file of snapshot.files) {
+    const path = file.path;
+    const note = existingFiles[path];
+    if (selected.has(path) || !note) continue;
+    const compactNote = { title: note.title, what: note.what, risks: note.risks };
+    const entryBytes = Buffer.byteLength(
+      `${hasEntries ? ',' : ''}${JSON.stringify(path)}:${JSON.stringify(compactNote)}`,
+    );
+    if (contextBytes + entryBytes <= maximumBytes) {
+      existingFileNotes[path] = compactNote;
+      contextBytes += entryBytes;
+      hasEntries = true;
+    }
+  }
+  return existingFileNotes;
+}
+
 function batchInput(snapshot, rawSnapshot, paths, existingFiles) {
   const selected = new Set(paths);
-  const existingFileNotes = Object.fromEntries(
-    Object.entries(existingFiles).filter(([path]) => !selected.has(path)),
-  );
   const result = {
     repo: snapshot.repo,
     change: snapshot.change,
@@ -291,37 +409,59 @@ function batchInput(snapshot, rawSnapshot, paths, existingFiles) {
     })),
     files: snapshot.files
       .filter((file) => selected.has(file.path))
-      .map((file) => ({ ...file })),
-    ...(Object.keys(existingFileNotes).length ? { existingFileNotes } : {}),
+      .map(({ summaryFailure: _summaryFailure, ...file }) => file),
   };
 
-  let encoded = JSON.stringify(result);
-  if (Buffer.byteLength(encoded) > 2_000_000) {
+  let baseInput = JSON.stringify(result);
+  if (Buffer.byteLength(baseInput) > hardInputByteLimit) {
     for (const file of result.files) {
       const source = rawSnapshot.files.find((item) => item.path === file.path);
       file.patch = source?.snippet || '';
       file.patchIsExcerpt = true;
     }
-    encoded = JSON.stringify(result);
+    baseInput = JSON.stringify(result);
   }
-  if (Buffer.byteLength(encoded) > 2_000_000) {
+  const baseBytes = Buffer.byteLength(baseInput);
+  if (baseBytes > hardInputByteLimit) {
     throw new Error(
-      `The batch containing ${paths.join(', ')} is too large to summarize`,
+      `The agent input containing ${paths.join(', ')} is larger than the ${hardInputByteLimit}-byte hard limit`,
     );
   }
-  return encoded;
+  const existingFileNotes = compactExistingFileNotes(
+    snapshot,
+    existingFiles,
+    selected,
+    baseBytes,
+  );
+  return Object.keys(existingFileNotes).length
+    ? `${baseInput.slice(0, -1)},"existingFileNotes":${JSON.stringify(existingFileNotes)}}`
+    : baseInput;
 }
 
-const text = { type: 'string' };
-const list = { type: 'array', items: text };
+function textSchema(maxLength) {
+  return { type: 'string', minLength: 1, maxLength };
+}
+
+function listSchema(maxItems) {
+  return {
+    type: 'array',
+    maxItems,
+    items: textSchema(listItemCodePointLimit),
+  };
+}
+
+const title = textSchema(titleCodePointLimit);
+const prose = textSchema(proseCodePointLimit);
+const details = listSchema(detailItemLimit);
+const risks = listSchema(riskItemLimit);
 const fileNote = {
   type: 'object',
   properties: {
-    title: text,
-    what: text,
-    why: text,
-    details: list,
-    risks: list,
+    title,
+    what: prose,
+    why: prose,
+    details,
+    risks,
   },
   required: ['title', 'what', 'why', 'details', 'risks'],
   additionalProperties: false,
@@ -333,11 +473,11 @@ function outputSchema(paths, { includeChange = true } = {}) {
     properties.change = {
       type: 'object',
       properties: {
-        title: text,
-        summary: text,
-        why: text,
-        highlights: list,
-        risks: list,
+        title,
+        summary: prose,
+        why: prose,
+        highlights: details,
+        risks,
       },
       required: ['title', 'summary', 'why', 'highlights', 'risks'],
       additionalProperties: false,
@@ -392,18 +532,34 @@ risks to at most three concrete items. Use an empty list when there is no useful
 detail or risk. For binary files, describe only the change shown by the metadata.`;
 }
 
-function normalizedText(value, field) {
+function normalizedText(value, field, limit) {
   if (typeof value !== 'string' || !value.trim()) {
     throw new Error(`${field} must be a non-empty string`);
   }
-  return value.trim();
+  const text = value.trim();
+  if (Array.from(text).length > limit) {
+    throw new Error(`${field} must be at most ${limit} Unicode code points`);
+  }
+  return text;
 }
 
-function normalizedList(value, field) {
+// fallow-ignore-next-line complexity
+function normalizedList(value, field, maxItems) {
   if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
     throw new Error(`${field} must be a list of strings`);
   }
-  return value.map((item) => item.trim()).filter(Boolean);
+  if (value.length > maxItems) {
+    throw new Error(`${field} must contain at most ${maxItems} items`);
+  }
+  const list = value.map((item) => item.trim()).filter(Boolean);
+  for (const item of list) {
+    if (Array.from(item).length > listItemCodePointLimit) {
+      throw new Error(
+        `${field} items must be at most ${listItemCodePointLimit} Unicode code points`,
+      );
+    }
+  }
+  return list;
 }
 
 function exactFields(value, fields, label) {
@@ -425,104 +581,229 @@ function exactFields(value, fields, label) {
   }
 }
 
-function normalizeResponse(
-  value,
-  paths,
-  { includeChange = true } = {},
-) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+function isObject(value) {
+  return Boolean(value) &&
+    typeof value === 'object' &&
+    !Array.isArray(value);
+}
+
+function responseObject(value) {
+  if (!isObject(value)) {
     throw new Error('Agent response must be an object');
   }
-  const allowed = new Set(['change', 'files']);
-  if (Object.keys(value).some((field) => !allowed.has(field))) {
+  return value;
+}
+
+function unsupportedResponseFields(value) {
+  return Object.keys(value).filter(
+    (field) => !['change', 'files'].includes(field),
+  );
+}
+
+function normalizeChangeResponse(value) {
+  const response = responseObject(value);
+  if (unsupportedResponseFields(response).length) {
     throw new Error('Agent response has unsupported fields');
   }
-  if (includeChange) {
-    exactFields(
-      value.change,
-      ['title', 'summary', 'why', 'highlights', 'risks'],
-      'Change note',
-    );
+  exactFields(
+    response.change,
+    ['title', 'summary', 'why', 'highlights', 'risks'],
+    'Change note',
+  );
+  return {
+    title: normalizedText(response.change.title, 'change.title', titleCodePointLimit),
+    summary: normalizedText(response.change.summary, 'change.summary', proseCodePointLimit),
+    why: normalizedText(response.change.why, 'change.why', proseCodePointLimit),
+    highlights: normalizedList(
+      response.change.highlights,
+      'change.highlights', detailItemLimit,
+    ),
+    risks: normalizedList(response.change.risks, 'change.risks', riskItemLimit),
+  };
+}
+
+function arrayFileEntry(note) {
+  if (!isObject(note)) {
+    return { error: 'Agent response has a malformed file note' };
+  }
+  const path = typeof note.path === 'string' ? note.path.trim() : '';
+  return path
+    ? { entry: { path, note, arrayForm: true } }
+    : { error: 'Agent response has a file note without a path' };
+}
+
+function arrayFileEntries(notes) {
+  const result = { entries: [], errors: [] };
+  for (const note of notes) {
+    const item = arrayFileEntry(note);
+    if (item.entry) result.entries.push(item.entry);
+    if (item.error) result.errors.push(item.error);
   }
-  let fileValues = {};
-  if (!paths.length) {
+  return result;
+}
+
+function fileResponseEntries(value) {
+  const response = responseObject(value);
+  const errors = unsupportedResponseFields(response).map(
+    (field) => `Agent response has unsupported field: ${field}`,
+  );
+  if (Array.isArray(response.files)) {
+    const arrayResult = arrayFileEntries(response.files);
     return {
-      ...(includeChange
-        ? {
-            change: {
-              title: normalizedText(value.change.title, 'change.title'),
-              summary: normalizedText(
-                value.change.summary,
-                'change.summary',
-              ),
-              why: normalizedText(value.change.why, 'change.why'),
-              highlights: normalizedList(
-                value.change.highlights,
-                'change.highlights',
-              ),
-              risks: normalizedList(value.change.risks, 'change.risks'),
-            },
-          }
-        : {}),
-      files: {},
+      entries: arrayResult.entries,
+      errors: [...errors, ...arrayResult.errors],
     };
   }
-  if (Array.isArray(value.files)) {
-    fileValues = {};
-    for (const note of value.files) {
-      exactFields(
-        note,
-        ['path', 'title', 'what', 'why', 'details', 'risks'],
-        'File note',
-      );
-      const path = normalizedText(note.path, 'files.path');
-      if (fileValues[path]) throw new Error(`Duplicate file note: ${path}`);
-      fileValues[path] = note;
+  if (!isObject(response.files)) {
+    throw new Error('Agent response has no file notes object');
+  }
+  return {
+    entries: Object.entries(response.files).map(([path, note]) => ({
+      path,
+      note,
+      arrayForm: false,
+    })),
+    errors,
+  };
+}
+
+function normalizeFileNote(note, path, arrayForm) {
+  exactFields(
+    note,
+    [
+      ...(arrayForm ? ['path'] : []),
+      'title',
+      'what',
+      'why',
+      'details',
+      'risks',
+    ],
+    path,
+  );
+  return {
+    title: normalizedText(note.title, `${path}.title`, titleCodePointLimit),
+    what: normalizedText(note.what, `${path}.what`, proseCodePointLimit),
+    why: normalizedText(note.why, `${path}.why`, proseCodePointLimit),
+    details: normalizedList(note.details, `${path}.details`, detailItemLimit),
+    risks: normalizedList(note.risks, `${path}.risks`, riskItemLimit),
+  };
+}
+
+function indexFileEntries(entries, expected) {
+  const byPath = new Map();
+  const failedFiles = [];
+  for (const entry of entries) {
+    if (!expected.has(entry.path)) {
+      failedFiles.push({
+        path: entry.path,
+        reason: 'Agent output included a file outside this batch.',
+      });
+      continue;
     }
-  } else {
-    fileValues = value.files;
+    const values = byPath.get(entry.path) || [];
+    byPath.set(entry.path, [...values, entry]);
+  }
+  return { byPath, failedFiles };
+}
+
+function normalizeFileEntry(path, values) {
+  if (values.length !== 1) {
+    return {
+      failure: {
+        path,
+        reason: values.length
+          ? 'Agent output repeated this file.'
+          : 'Agent output omitted this file.',
+      },
+    };
+  }
+  try {
+    return {
+      note: normalizeFileNote(
+        values[0].note,
+        path,
+        values[0].arrayForm,
+      ),
+    };
+  } catch (error) {
+    return {
+      failure: {
+        path,
+        reason: error instanceof Error ? error.message : String(error),
+      },
+    };
   }
-  exactFields(fileValues, paths, 'File notes');
+}
 
+function normalizeFileResponse(value, paths) {
+  const expected = new Set(paths);
   const files = {};
+  const { entries, errors } = fileResponseEntries(value);
+  const indexed = indexFileEntries(entries, expected);
   for (const path of paths) {
-    const note = fileValues[path];
-    if (!Array.isArray(value.files)) {
-      exactFields(note, ['title', 'what', 'why', 'details', 'risks'], path);
-    }
-    files[path] = {
-      title: normalizedText(note.title, `${path}.title`),
-      what: normalizedText(note.what, `${path}.what`),
-      why: normalizedText(note.why, `${path}.why`),
-      details: normalizedList(note.details, `${path}.details`),
-      risks: normalizedList(note.risks, `${path}.risks`),
-    };
+    const result = normalizeFileEntry(
+      path,
+      indexed.byPath.get(path) || [],
+    );
+    if (result.note) files[path] = result.note;
+    if (result.failure) indexed.failedFiles.push(result.failure);
   }
+  return { files, failedFiles: indexed.failedFiles, errors };
+}
+
+function writeJsonAtomic(file, value, options) {
+  publishLeaseFile(
+    ownership,
+    file,
+    `${JSON.stringify(value, null, 2)}\n`,
+    options,
+  );
+}
 
+function metadataList(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function summaryFailureState(snapshot, summaries) {
+  const failedFiles = metadataList(summaries.meta?.failedFiles);
+  const errors = metadataList(summaries.meta?.errors);
+  const emptyReviewComplete =
+    snapshot.files.length === 0 &&
+    summaries.meta?.status === 'complete' &&
+    summaries.meta?.reviewFingerprint ===
+      snapshot.notes?.reviewFingerprint;
+  const complete = [
+    failedFiles.length === 0,
+    errors.length === 0,
+    emptyReviewComplete ||
+      (completeChangeNote(summaries.change) &&
+        snapshot.files.every((file) =>
+          completeFileNote(summaries.files?.[file.path]),
+        )),
+  ].every(Boolean);
+  return { failedFiles, errors, complete };
+}
+
+function snapshotFileWithNote(file, summaries, failureByPath) {
+  const nextFile = { ...file };
+  delete nextFile.noteFailure;
+  const note = summaries.files?.[file.path];
+  if (completeFileNote(note)) {
+    return { ...nextFile, summary: note, noteReady: true };
+  }
+  const failure = failureByPath.get(file.path);
   return {
-    ...(includeChange
-      ? {
-          change: {
-            title: normalizedText(value.change.title, 'change.title'),
-            summary: normalizedText(value.change.summary, 'change.summary'),
-            why: normalizedText(value.change.why, 'change.why'),
-            highlights: normalizedList(
-              value.change.highlights,
-              'change.highlights',
-            ),
-            risks: normalizedList(value.change.risks, 'change.risks'),
-          },
-        }
-      : {}),
-    files,
+    ...nextFile,
+    noteReady: false,
+    ...(failure ? { noteFailure: failure } : {}),
   };
 }
 
-function writeJsonAtomic(file, value) {
-  mkdirSync(dirname(file), { recursive: true });
-  const temporary = `${file}.${process.pid}.tmp`;
-  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
-  renameSync(temporary, file);
+function notesWithoutFailures(notes = {}) {
+  const nextNotes = { ...notes };
+  delete nextNotes.failedFiles;
+  delete nextNotes.errors;
+  return nextNotes;
 }
 
 function publishSnapshot(snapshot, summaries) {
@@ -536,17 +817,18 @@ function publishSnapshot(snapshot, summaries) {
     throw new Error('The diff changed while agent notes were being written');
   }
 
-  const complete =
-    completeChangeNote(summaries.change) &&
-    snapshot.files.every((file) =>
-      completeFileNote(summaries.files?.[file.path]),
-    );
-  const files = snapshot.files.map((file) => {
-    const note = summaries.files?.[file.path];
-    return completeFileNote(note)
-      ? { ...file, summary: note, noteReady: true }
-      : { ...file, noteReady: false };
-  });
+  const lockPath = pathInsideRepo(summariesPath);
+  const publishedFiles = snapshot.files.filter(
+    (file) => file.path !== `${lockPath}.lock`,
+  );
+  const publishedSnapshot = { ...snapshot, files: publishedFiles };
+  const state = summaryFailureState(publishedSnapshot, summaries);
+  const failureByPath = new Map(
+    state.failedFiles.map((failure) => [failure.path, failure.reason]),
+  );
+  const files = publishedFiles.map((file) =>
+    snapshotFileWithNote(file, summaries, failureByPath),
+  );
   const content = {
     ...snapshot,
     ...(completeChangeNote(summaries.change)
@@ -554,15 +836,20 @@ function publishSnapshot(snapshot, summaries) {
       : {}),
     files,
     notes: {
-      ...snapshot.notes,
+      ...notesWithoutFailures(snapshot.notes),
+      agent: selectedAgent,
       generatedFor: reviewFingerprint,
       fresh: true,
-      complete,
-      status: complete
+      complete: state.complete,
+      status: state.complete
         ? 'complete'
         : summaries.meta?.status || 'generating',
       completedFiles: files.filter((file) => file.noteReady).length,
       totalFiles: files.length,
+      ...(state.failedFiles.length
+        ? { failedFiles: state.failedFiles }
+        : {}),
+      ...(state.errors.length ? { errors: state.errors } : {}),
       ...(model ? { model } : {}),
       ...(reasoning ? { reasoning } : {}),
     },
@@ -573,11 +860,15 @@ function publishSnapshot(snapshot, summaries) {
     .update(JSON.stringify(content))
     .digest('hex')
     .slice(0, 12);
-  writeJsonAtomic(outputPath, {
-    version,
-    generatedAt: new Date().toISOString(),
-    ...content,
-  });
+  writeJsonAtomic(
+    outputPath,
+    {
+      version,
+      generatedAt: new Date().toISOString(),
+      ...content,
+    },
+    { privateFile: false },
+  );
 }
 
 function publish(snapshot, summaries) {
@@ -588,6 +879,30 @@ function publish(snapshot, summaries) {
   }
 }
 
+function storeProgress(snapshot, summaries) {
+  recordSyncStage('publish', () => {
+    writeJsonAtomic(summariesPath, summaries);
+    publish(snapshot, summaries);
+  });
+}
+
+function emitFailedSupportRecord(code = 1) {
+  if (!supportRecorder) return;
+  const record = supportRecorder.failure(code);
+  try {
+    if (supportRecordPath) {
+      writeSupportRecord(supportRecordPath, record);
+      console.error(`Wrote support record to ${supportRecordPath}`);
+    } else {
+      process.stderr.write(
+        `Diffsplain support record:\n${formatSupportRecord(record)}`,
+      );
+    }
+  } catch {
+    console.error('Could not write the support record.');
+  }
+}
+
 function readJson(file, fallback) {
   try {
     return JSON.parse(readFileSync(file, 'utf8'));
@@ -596,14 +911,73 @@ function readJson(file, fallback) {
   }
 }
 
+function readSummaryState(file) {
+  try {
+    const value = JSON.parse(readFileSync(file, 'utf8'));
+    const valid =
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value);
+    return valid
+      ? { value, damaged: false }
+      : { value: {}, damaged: true };
+  } catch {
+    return { value: {}, damaged: existsSync(file) };
+  }
+}
+
+async function selectAgentForNotes() {
+  try {
+    selectedAgent = await selectCodingAgent(
+      requestedAgent,
+      (agent) => commandAvailable(codingAgentBinary(agent, { codexBin })),
+    );
+    assertReasoningSupported(selectedAgent, reasoning);
+    agentBinary = codingAgentBinary(selectedAgent, { codexBin });
+    supportRecorder?.setProvider(
+      selectedAgent,
+      safeCommandVersion(selectedAgent, agentBinary),
+    );
+  } catch (error) {
+    supportRecorder?.setProvider(requestedAgent || 'unknown');
+    if (error instanceof Error) error.exitCode = 2;
+    throw error;
+  }
+}
+
+function addFailures(summaries, failedFiles = [], errors = []) {
+  const priorFailedFiles = metadataList(summaries.meta?.failedFiles);
+  const priorErrors = metadataList(summaries.meta?.errors);
+  const uniqueFailures = new Map(
+    [...priorFailedFiles, ...failedFiles].map((failure) => [
+      `${failure.path}\0${failure.reason}`,
+      failure,
+    ]),
+  );
+  const nextErrors = [...new Set([...priorErrors, ...errors])];
+  return {
+    ...summaries,
+    meta: {
+      ...summaries.meta,
+      ...(uniqueFailures.size
+        ? { failedFiles: [...uniqueFailures.values()] }
+        : {}),
+      ...(nextErrors.length ? { errors: nextErrors } : {}),
+    },
+  };
+}
+
+function failureReason(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.split('\n').find((line) => line.trim())?.trim() ||
+    'Agent note generation failed.';
+}
+
 function runAgent(invocation, input) {
   return new Promise((resolvePromise, rejectPromise) => {
     const child = spawn(invocation.command, invocation.args, {
       cwd: invocation.cwd || root,
-      env: {
-        ...process.env,
-        ...invocation.env,
-      },
+      env: invocation.env || process.env,
       stdio: ['pipe', 'pipe', 'pipe'],
     });
     activeAgentProcesses.add(child);
@@ -613,6 +987,7 @@ function runAgent(invocation, input) {
     const maxBuffer = 10 * 1024 * 1024;
     const collect = (chunks, chunk) => {
       outputBytes += chunk.length;
+      supportRecorder?.addBytes('agentOutput', chunk.length);
       if (outputBytes > maxBuffer) {
         child.kill('SIGTERM');
         rejectPromise(new Error(`${selectedAgent} returned too much output`));
@@ -622,6 +997,9 @@ function runAgent(invocation, input) {
     };
     child.stdout.on('data', (chunk) => collect(stdout, chunk));
     child.stderr.on('data', (chunk) => collect(stderr, chunk));
+    child.stdin.on('error', (error) => {
+      if (error.code !== 'EPIPE') rejectPromise(error);
+    });
     child.once('error', (error) => {
       activeAgentProcesses.delete(child);
       rejectPromise(error);
@@ -653,13 +1031,26 @@ function runAgent(invocation, input) {
         );
         return;
       }
-      resolvePromise(stdoutText);
+      resolvePromise({ stdout: stdoutText, stderr: stderrText });
     });
     if (invocation.input === 'stdin') child.stdin.end(input);
     else child.stdin.end();
   });
 }
 
+async function requestAgent(invocation, input, normalize) {
+  supportRecorder?.addBytes('agentInput', Buffer.byteLength(input));
+  return recordAsyncStage('agent', async () => {
+    const result = await runAgent(invocation, input);
+    if (result.stderr.trim()) {
+      console.error(
+        `${selectedAgent} wrote diagnostic output:\n${result.stderr.trim()}`,
+      );
+    }
+    return normalize(result.stdout);
+  });
+}
+
 function completeText(value) {
   return typeof value === 'string' && Boolean(value.trim());
 }
@@ -711,6 +1102,18 @@ function fileFingerprint(file) {
     .digest('hex');
 }
 
+function generationSettingsMatch(meta, generationSettings) {
+  if (!meta || typeof meta !== 'object' || typeof meta.agent !== 'string') {
+    return false;
+  }
+  const previousSettings = {
+    agent: meta.agent,
+    model: Object.hasOwn(meta, 'model') ? meta.model : null,
+    reasoning: Object.hasOwn(meta, 'reasoning') ? meta.reasoning : null,
+  };
+  return JSON.stringify(previousSettings) === JSON.stringify(generationSettings);
+}
+
 const temporaryDirectory = mkdtempSync(
   resolve(tmpdir(), 'diffsplain-agent-'),
 );
@@ -718,22 +1121,36 @@ let workingSummaries;
 let workingSnapshot;
 
 try {
-  const rawSnapshotPath = resolve(temporaryDirectory, 'diff-data.json');
-  if (!snapshotPath) runBuilder(rawSnapshotPath, true);
-  const rawSnapshot = JSON.parse(
-    readFileSync(snapshotPath || rawSnapshotPath, 'utf8'),
-  );
-  const snapshot = cleanSnapshot(rawSnapshot);
+  recordSyncStage('cache', acquireOwnership);
+  const { rawSnapshot, snapshot } = recordSyncStage('snapshot', () => {
+    const rawSnapshotPath = resolve(temporaryDirectory, 'diff-data.json');
+    if (!snapshotPath) runBuilder(rawSnapshotPath, true);
+    const rawSnapshotText = readFileSync(
+      snapshotPath || rawSnapshotPath,
+      'utf8',
+    );
+    supportRecorder?.addBytes(
+      'snapshot',
+      Buffer.byteLength(rawSnapshotText),
+    );
+    const value = JSON.parse(rawSnapshotText);
+    return { rawSnapshot: value, snapshot: cleanSnapshot(value) };
+  });
   const paths = snapshot.files.map((file) => file.path);
-  const previousSummaries = readJson(summariesPath, {});
+  const previousState = readSummaryState(summariesPath);
+  const previousSummaries = previousState.value;
+  if (previousState.damaged) {
+    console.error(
+      `Saved notes at ${summariesPath} are damaged. Rebuilding them from the current review.`,
+    );
+  }
   if (paths.length === 0) {
+    if (requestedAgent) await selectAgentForNotes();
     workingSnapshot = rawSnapshot;
     workingSummaries = {
-      ...(completeChangeNote(previousSummaries.change)
-        ? { change: previousSummaries.change }
-        : {}),
       files: {},
       meta: {
+        agent: selectedAgent,
         reviewFingerprint: rawSnapshot.notes.reviewFingerprint,
         fileFingerprints: {},
         status: 'complete',
@@ -742,10 +1159,15 @@ try {
         ...(reasoning ? { reasoning } : {}),
       },
     };
-    writeJsonAtomic(summariesPath, workingSummaries);
-    publish(rawSnapshot, workingSummaries);
+    storeProgress(rawSnapshot, workingSummaries);
     console.log('No changed files to summarize.');
   } else {
+    await selectAgentForNotes();
+    const generationSettings = {
+      agent: selectedAgent,
+      model: model || null,
+      reasoning: reasoning || null,
+    };
     const startedAt = new Date().toISOString();
     const previousFiles =
       previousSummaries.files &&
@@ -765,45 +1187,67 @@ try {
     const fileFingerprints = Object.fromEntries(
       paths.map((path) => [path, fileFingerprint(rawFiles.get(path))]),
     );
+    const settingsMatch = generationSettingsMatch(
+      previousSummaries.meta,
+      generationSettings,
+    );
+    const summaryFiles = new Map(
+      snapshot.files.map((file) => [file.path, file]),
+    );
     const reusableFiles = {};
     const changedPaths = [];
+    const inputFailures = [];
     for (const path of paths) {
       if (
         !force &&
+        settingsMatch &&
         previousFingerprints[path] === fileFingerprints[path] &&
         completeFileNote(previousFiles[path])
       ) {
         reusableFiles[path] = previousFiles[path];
+      } else if (summaryFiles.get(path)?.summaryFailure) {
+        inputFailures.push({
+          path,
+          reason: summaryFiles.get(path).summaryFailure,
+        });
       } else {
         changedPaths.push(path);
       }
     }
     const changeNeedsRefresh =
       force ||
+      !settingsMatch ||
       previousSummaries.meta?.reviewFingerprint !==
         rawSnapshot.notes.reviewFingerprint ||
       !completeChangeNote(previousSummaries.change);
     const needsGeneration = changedPaths.length > 0 || changeNeedsRefresh;
 
     workingSnapshot = rawSnapshot;
-    workingSummaries = {
-      ...(!changeNeedsRefresh ? { change: previousSummaries.change } : {}),
-      files: reusableFiles,
-      meta: {
-        reviewFingerprint: rawSnapshot.notes.reviewFingerprint,
-        fileFingerprints,
-        ...(needsGeneration
-          ? { startedAt }
-          : previousSummaries.meta?.generatedAt
-            ? { generatedAt: previousSummaries.meta.generatedAt }
-            : {}),
-        status: needsGeneration ? 'generating' : 'complete',
-        ...(model ? { model } : {}),
-        ...(reasoning ? { reasoning } : {}),
+    workingSummaries = addFailures(
+      {
+        ...(!changeNeedsRefresh ? { change: previousSummaries.change } : {}),
+        files: reusableFiles,
+        meta: {
+          agent: selectedAgent,
+          reviewFingerprint: rawSnapshot.notes.reviewFingerprint,
+          fileFingerprints,
+          ...(needsGeneration
+            ? { startedAt }
+            : previousSummaries.meta?.generatedAt
+              ? { generatedAt: previousSummaries.meta.generatedAt }
+              : {}),
+          status: needsGeneration
+            ? 'generating'
+            : inputFailures.length
+              ? 'failed'
+              : 'complete',
+          ...(model ? { model } : {}),
+          ...(reasoning ? { reasoning } : {}),
+        },
       },
-    };
-    writeJsonAtomic(summariesPath, workingSummaries);
-    publish(rawSnapshot, workingSummaries);
+      inputFailures,
+    );
+    storeProgress(rawSnapshot, workingSummaries);
 
     const batches = [];
     let batch = [];
@@ -825,8 +1269,7 @@ try {
     }
     if (batch.length) batches.push(batch);
     let nextBatch = 0;
-    const runBatch = async (index) => {
-      const batchPaths = batches[index];
+    const requestBatch = async (index, batchPaths) => {
       const schemaPath = resolve(
         temporaryDirectory,
         `summary-schema-${index + 1}.json`,
@@ -866,18 +1309,40 @@ try {
       console.error(
         `Asking ${selectedAgent} for batch ${index + 1} of ${batches.length} (${batchPaths.length} changed files)...`,
       );
-      const stdout = await runAgent(invocation, input);
-      const response = parseAgentResponse(selectedAgent, stdout);
-      const normalized = normalizeResponse(response, batchPaths, {
-        includeChange: false,
-      });
+      return requestAgent(
+        invocation,
+        input,
+        (stdout) =>
+          normalizeFileResponse(
+            parseAgentResponse(selectedAgent, stdout),
+            batchPaths,
+          ),
+      );
+    };
+    const runBatch = async (index) => {
+      const batchPaths = batches[index];
+      let outcome;
+      try {
+        outcome = await requestBatch(index, batchPaths);
+      } catch (error) {
+        if (interrupted) throw error;
+        const reason = failureReason(error);
+        console.error(
+          error instanceof Error ? error.message : String(error),
+        );
+        outcome = {
+          files: {},
+          failedFiles: batchPaths.map((path) => ({ path, reason })),
+          errors: [],
+        };
+      }
       workingSummaries = {
         ...(workingSummaries.change
           ? { change: workingSummaries.change }
           : {}),
         files: {
           ...workingSummaries.files,
-          ...normalized.files,
+          ...outcome.files,
         },
         meta: {
           ...workingSummaries.meta,
@@ -885,8 +1350,12 @@ try {
           generatedAt: new Date().toISOString(),
         },
       };
-      writeJsonAtomic(summariesPath, workingSummaries);
-      publish(rawSnapshot, workingSummaries);
+      workingSummaries = addFailures(
+        workingSummaries,
+        outcome.failedFiles,
+        outcome.errors,
+      );
+      storeProgress(rawSnapshot, workingSummaries);
       if (batchPaths.length) {
         console.log(
           `Wrote ${Object.keys(workingSummaries.files).length} of ${paths.length} agent notes to ${summariesPath}`,
@@ -896,7 +1365,7 @@ try {
     const workers = Array.from(
       { length: Math.min(jobs, batches.length) },
       async () => {
-        while (nextBatch < batches.length) {
+        while (!interrupted && nextBatch < batches.length) {
           const index = nextBatch;
           nextBatch += 1;
           await runBatch(index);
@@ -905,91 +1374,122 @@ try {
     );
     await Promise.all(workers);
     if (changeNeedsRefresh) {
-      const schemaPath = resolve(
-        temporaryDirectory,
-        'change-summary-schema.json',
-      );
-      const schema = outputSchema([]);
-      writeFileSync(
-        schemaPath,
-        `${JSON.stringify(schema, null, 2)}\n`,
-      );
-      const input = batchInput(
-        snapshot,
-        rawSnapshot,
-        [],
-        workingSummaries.files,
-      );
-      const inputPath = resolve(
-        temporaryDirectory,
-        'change-summary-input.json',
-      );
-      writeFileSync(inputPath, input);
-      const invocation = agentCommand({
-        agent: selectedAgent,
-        binary: agentBinary,
-        model,
-        reasoning,
-        prompt: promptFor([]),
-        schema,
-        schemaPath,
-        inputPath,
-        workingDirectory: root,
-      });
-      console.error(`Asking ${selectedAgent} for the change note...`);
-      const stdout = await runAgent(invocation, input);
-      const normalized = normalizeResponse(
-        parseAgentResponse(selectedAgent, stdout),
-        [],
-      );
-      workingSummaries = {
-        change: normalized.change,
-        files: workingSummaries.files,
-        meta: {
-          ...workingSummaries.meta,
-          status: 'complete',
-          generatedAt: new Date().toISOString(),
-        },
-      };
-      writeJsonAtomic(summariesPath, workingSummaries);
-      publish(rawSnapshot, workingSummaries);
-      console.log(`Updated the change note in ${summariesPath}`);
-    } else if (batches.length) {
-      workingSummaries = {
-        ...workingSummaries,
-        meta: {
-          ...workingSummaries.meta,
-          status: 'complete',
-          generatedAt: new Date().toISOString(),
-        },
-      };
-      writeJsonAtomic(summariesPath, workingSummaries);
-      publish(rawSnapshot, workingSummaries);
+      try {
+        const schemaPath = resolve(
+          temporaryDirectory,
+          'change-summary-schema.json',
+        );
+        const schema = outputSchema([]);
+        writeFileSync(
+          schemaPath,
+          `${JSON.stringify(schema, null, 2)}\n`,
+        );
+        const input = batchInput(
+          snapshot,
+          rawSnapshot,
+          [],
+          workingSummaries.files,
+        );
+        const inputPath = resolve(
+          temporaryDirectory,
+          'change-summary-input.json',
+        );
+        writeFileSync(inputPath, input);
+        const invocation = agentCommand({
+          agent: selectedAgent,
+          binary: agentBinary,
+          model,
+          reasoning,
+          prompt: promptFor([]),
+          schema,
+          schemaPath,
+          inputPath,
+          workingDirectory: root,
+        });
+        console.error(`Asking ${selectedAgent} for the change note...`);
+        const normalized = await requestAgent(
+          invocation,
+          input,
+          (stdout) =>
+            normalizeChangeResponse(
+              parseAgentResponse(selectedAgent, stdout),
+            ),
+        );
+        workingSummaries = {
+          change: normalized,
+          files: workingSummaries.files,
+          meta: workingSummaries.meta,
+        };
+        console.log(`Updated the change note in ${summariesPath}`);
+      } catch (error) {
+        if (interrupted) throw error;
+        console.error(
+          error instanceof Error ? error.message : String(error),
+        );
+        workingSummaries = addFailures(
+          workingSummaries,
+          [],
+          [`Change note: ${failureReason(error)}`],
+        );
+      }
     }
-    if (batches.length === 0) {
+    const failedFiles = workingSummaries.meta.failedFiles || [];
+    const generationErrors = workingSummaries.meta.errors || [];
+    const complete =
+      failedFiles.length === 0 &&
+      generationErrors.length === 0 &&
+      completeChangeNote(workingSummaries.change) &&
+      paths.every((path) =>
+        completeFileNote(workingSummaries.files[path]),
+      );
+    workingSummaries = {
+      ...workingSummaries,
+      meta: {
+        ...workingSummaries.meta,
+        status: complete ? 'complete' : 'failed',
+        generatedAt: new Date().toISOString(),
+      },
+    };
+    storeProgress(rawSnapshot, workingSummaries);
+    if (batches.length === 0 && inputFailures.length === 0) {
       console.log('No file summaries changed.');
     }
+    for (const failure of failedFiles) {
+      console.error(`${failure.path}: ${failure.reason}`);
+    }
+    for (const error of generationErrors) console.error(error);
+    if (!complete) {
+      process.exitCode = 1;
+      emitFailedSupportRecord(1);
+    }
     console.log(`Rebuilt ${outputPath}`);
   }
 } catch (error) {
   if (!interrupted && workingSummaries && workingSnapshot) {
     try {
-      workingSummaries = {
-        ...workingSummaries,
-        meta: {
-          ...workingSummaries.meta,
-          status: 'failed',
-          generatedAt: new Date().toISOString(),
+      workingSummaries = addFailures(
+        {
+          ...workingSummaries,
+          meta: {
+            ...workingSummaries.meta,
+            status: 'failed',
+            generatedAt: new Date().toISOString(),
+          },
         },
-      };
-      writeJsonAtomic(summariesPath, workingSummaries);
-      publish(workingSnapshot, workingSummaries);
+        [],
+        [failureReason(error)],
+      );
+      storeProgress(workingSnapshot, workingSummaries);
     } catch {}
   }
   if (!interrupted) {
     console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
+    process.exitCode =
+      error instanceof Error && error.exitCode === 2 ? 2 : 1;
+    emitFailedSupportRecord(process.exitCode);
   }
 } finally {
+  if (ownershipHeartbeat) clearInterval(ownershipHeartbeat);
+  if (ownership) { try { releaseLease(ownership); } catch {} }
   rmSync(temporaryDirectory, { recursive: true, force: true });
 }