diffsplain 0.7.0 → 0.8.2

package/README.md

@@ -13,10 +13,12 @@ npx diffsplain
 
 The command opens a local page and compares the checkout with its default
 branch. It starts at port `2299` and uses the next free port when needed. You
-need Node.js 22.13 or newer and a signed-in Codex, Claude, Copilot, or OpenCode
-CLI. Diffsplain tries them in that order. Pull requests also need a signed-in
-GitHub CLI. Cursor reviews stay disabled because Cursor Agent has no supported
-read-only, no-network, no-tool mode.
+need Node.js 22.13 or newer and a signed-in Codex, Claude, Copilot, Cursor, or
+OpenCode CLI. Diffsplain tries them in that order. Cursor Agent must be version
+2026.08.11 or newer. It uses the signed-in Cursor CLI in the user's home and
+still contacts the Cursor service. Pull requests also need a signed-in GitHub
+CLI. Once Diffsplain chooses an agent, a failed check or run ends the command;
+it does not switch agents.
 
 Common targets:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffsplain",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "Review Git diffs one file at a time with coding agent notes beside each patch.",
   "keywords": [
     "codex",

package/scripts/build-diff-data.mjs

@@ -143,11 +143,42 @@ const excludedPaths = new Set(
 function command(commandName, commandArgs, options = {}) {
   return execFileSync(commandName, commandArgs, {
     cwd: options.cwd,
+    env: options.env,
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
   });
 }
 
+function githubHttpsRemote(url) {
+  if (typeof url !== 'string' || !url) return false;
+  try {
+    const parsed = new URL(url);
+    return (
+      parsed.protocol === 'https:' &&
+      (parsed.hostname === 'github.com' || parsed.hostname === 'www.github.com')
+    );
+  } catch {
+    return false;
+  }
+}
+
+function runGit(gitArgs, { gitDir, remoteUrl } = {}) {
+  const githubHttps = githubHttpsRemote(remoteUrl);
+  return command(
+    'git',
+    [
+      ...(gitDir ? ['--git-dir', gitDir] : ['-C', repo]),
+      ...(githubHttps
+        ? ['-c', 'credential.helper=!gh auth git-credential']
+        : []),
+      ...gitArgs,
+    ],
+    githubHttps
+      ? { env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } }
+      : {},
+  );
+}
+
 const runRepo = (gitArgs) => command('git', ['-C', repo, ...gitArgs]);
 const tryRepo = (gitArgs) => {
   try {
@@ -383,16 +414,19 @@ function bareCache(remoteUrl) {
 
 function fetchInto(cache, remoteUrl, refspecs) {
   try {
-    cache.run([
-      'fetch',
-      '--quiet',
-      '--no-tags',
-      '--no-write-fetch-head',
-      '--no-auto-maintenance',
-      '--force',
-      remoteUrl,
-      ...refspecs,
-    ]);
+    runGit(
+      [
+        'fetch',
+        '--quiet',
+        '--no-tags',
+        '--no-write-fetch-head',
+        '--no-auto-maintenance',
+        '--force',
+        remoteUrl,
+        ...refspecs,
+      ],
+      { gitDir: cache.path, remoteUrl },
+    );
   } catch (error) {
     const detail = error?.stderr?.toString().trim();
     throw new Error(
@@ -422,7 +456,7 @@ function uniqueMergeBase(runGit, base, head) {
 function remoteDefaultBranchInfo(remoteUrl) {
   let raw;
   try {
-    raw = runRepo(['ls-remote', '--symref', remoteUrl, 'HEAD']);
+    raw = runGit(['ls-remote', '--symref', remoteUrl, 'HEAD'], { remoteUrl });
   } catch {
     throw new Error('Could not read the remote default branch');
   }
@@ -441,7 +475,7 @@ function remoteDefaultBranch(remoteUrl) {
 function remoteContainsCommits(remoteUrl, commits) {
   let raw;
   try {
-    raw = runRepo(['ls-remote', remoteUrl]);
+    raw = runGit(['ls-remote', remoteUrl], { remoteUrl });
   } catch {
     return false;
   }

package/scripts/cli-args.mjs

@@ -86,7 +86,7 @@ Targets:
 Options:
   --repo PATH|URL|OWNER/NAME
                       Repo to review (default: current repo)
-  --agent NAME        Use codex, claude, copilot, or opencode
+  --agent NAME        Use codex, claude, copilot, cursor, or opencode
   --no-agent          Do not write agent notes
   --model NAME        Model for agent notes
   --reasoning LEVEL   Agent reasoning effort when supported
@@ -107,12 +107,12 @@ Options:
   -h, --help          Show this help
   -v, --version       Show the installed version
 
-Agent fallback:
-  codex, claude, copilot, opencode
+Automatic agent selection:
+  codex, claude, copilot, cursor, opencode
 
 Cursor:
-  Disabled because Cursor Agent has no supported read-only, no-network,
-  no-tool mode
+  Requires Cursor Agent 2026.08.11 or newer. Uses the signed-in CLI in the
+  user's home. Cursor still contacts its service.
 
 Examples:
   diffsplain

package/scripts/coding-agents.mjs

@@ -1,6 +1,8 @@
 import { constants } from 'node:fs';
 import { access } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
 import {
+  basename,
   delimiter,
   dirname,
   isAbsolute,
@@ -60,17 +62,103 @@ export function summaryAgentEnvironment(env = process.env) {
   );
 }
 
-const cursorDisabledReason =
-  'Cursor review is disabled: Cursor Agent has no supported read-only, no-network, no-tool mode.';
+const minimumCursorVersion = [2026, 8, 11];
+const cursorRequirementSummary =
+  'Cursor needs version 2026.08.11 or newer with Ask mode, --sandbox, --trust, and --workspace.';
 
-export function agentDisabledReason(agent) {
-  if (agent === 'cursor') return cursorDisabledReason;
-  return undefined;
+export const enabledCodingAgents = codingAgents;
+
+function firstLine(value) {
+  return value
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .split('\n')
+    .map((line) => line.trim())
+    .find(Boolean);
+}
+
+function cursorVersionParts(version) {
+  const match = version?.match(/^(\d{4})\.(\d{1,2})\.(\d{1,2})(?:-|$)/);
+  return match?.slice(1).map(Number);
 }
 
-export const enabledCodingAgents = codingAgents.filter(
-  (agent) => !agentDisabledReason(agent),
-);
+function versionAtLeast(current, minimum) {
+  for (const [index, part] of current.entries()) {
+    if (part !== minimum[index]) return part > minimum[index];
+  }
+  return true;
+}
+
+function cursorCompatibilityError(detail) {
+  return `Cursor Agent is incompatible: ${detail} ${cursorRequirementSummary} Upgrade Cursor Agent.`;
+}
+
+export function inspectCursorCompatibility(
+  command,
+  {
+    env = process.env,
+    timeout = 5_000,
+  } = {},
+) {
+  const run = (args) => spawnSync(command, args, {
+    encoding: 'utf8',
+    env,
+    timeout,
+    windowsHide: true,
+  });
+  const versionResult = run(['--version']);
+  const version = firstLine(
+    `${versionResult.stdout || ''}\n${versionResult.stderr || ''}`,
+  );
+  if (versionResult.error || versionResult.status !== 0 || !version) {
+    return {
+      compatible: false,
+      version,
+      reason: cursorCompatibilityError('The version check failed.'),
+    };
+  }
+  const parts = cursorVersionParts(version);
+  if (!parts || !versionAtLeast(parts, minimumCursorVersion)) {
+    return {
+      compatible: false,
+      version,
+      reason: cursorCompatibilityError(
+        `Found ${version}; version 2026.08.11 or newer is required.`,
+      ),
+    };
+  }
+  const helpResult = run(['--help']);
+  const help = `${helpResult.stdout || ''}\n${helpResult.stderr || ''}`;
+  if (helpResult.error || helpResult.status !== 0) {
+    return {
+      compatible: false,
+      version,
+      reason: cursorCompatibilityError('The CLI help check failed.'),
+    };
+  }
+  const requiredHelp = [
+    ['--mode <mode>', 'Ask mode'],
+    ['"ask"', 'Ask mode'],
+    ['--sandbox <mode>', 'sandbox control'],
+    ['"enabled"', 'sandbox control'],
+    ['--workspace <path-or-name>', 'workspace selection'],
+    ['--output-format <format>', 'structured output'],
+    ['--model <model>', 'model selection'],
+    ['--trust', 'workspace trust control'],
+  ];
+  const missing = requiredHelp
+    .filter(([text]) => !help.includes(text))
+    .map(([, label]) => label);
+  if (missing.length) {
+    return {
+      compatible: false,
+      version,
+      reason: cursorCompatibilityError(
+        `The CLI lacks ${[...new Set(missing)].join(', ')}.`,
+      ),
+    };
+  }
+  return { compatible: true, version };
+}
 
 async function executable(path) {
   try {
@@ -123,7 +211,30 @@ export async function commandAvailable(command, options) {
   return Boolean(await findCommand(command, options));
 }
 
-// fallow-ignore-next-line complexity -- validation and fallback share one public selector.
+export async function codingAgentAvailability(
+  agent,
+  {
+    binary = codingAgentBinary(agent),
+    env = process.env,
+    platform = process.platform,
+  } = {},
+) {
+  const path = await findCommand(binary, { env, platform });
+  if (!path) return { available: false, installed: false };
+  if (agent !== 'cursor') {
+    return { available: true, installed: true, path };
+  }
+  const inspection = inspectCursorCompatibility(path, { env });
+  return {
+    available: inspection.compatible,
+    installed: true,
+    path,
+    version: inspection.version,
+    reason: inspection.reason,
+  };
+}
+
+// fallow-ignore-next-line complexity -- validation and discovery share one public selector.
 export async function selectCodingAgent(
   requested,
   available = commandAvailable,
@@ -134,19 +245,32 @@ export async function selectCodingAgent(
         `Unsupported agent "${requested}". Choose ${enabledCodingAgents.join(', ')}.`,
       );
     }
-    const disabled = agentDisabledReason(requested);
-    if (disabled) throw new Error(disabled);
-    if (!(await available(requested))) {
+    const result = await available(requested);
+    const availableResult = typeof result === 'object'
+      ? result.available
+      : result;
+    if (!availableResult) {
+      if (typeof result === 'object' && result.reason) {
+        throw new Error(result.reason);
+      }
       throw new Error(`Coding agent "${requested}" is not available.`);
     }
     return requested;
   }
 
+  let cursorReason;
   for (const agent of enabledCodingAgents) {
-    if (await available(agent)) return agent;
+    const result = await available(agent);
+    const availableResult = typeof result === 'object'
+      ? result.available
+      : result;
+    if (availableResult) return agent;
+    if (agent === 'cursor' && typeof result === 'object') {
+      cursorReason = result.reason;
+    }
   }
   throw new Error(
-    `No coding agent is available. Install one of: ${enabledCodingAgents.join(', ')}. ${cursorDisabledReason}`,
+    `No coding agent is available. Install one of: ${enabledCodingAgents.join(', ')}.${cursorReason ? ` ${cursorReason}` : ''}`,
   );
 }
 
@@ -169,12 +293,29 @@ export function codingAgentBinary(
   );
 }
 
+function extractJsonValue(text) {
+  const start = text.search(/[{[]/);
+  if (start === -1) return undefined;
+  const opening = text[start];
+  const closing = opening === '{' ? '}' : ']';
+  const end = text.lastIndexOf(closing);
+  if (end <= start) return undefined;
+  try {
+    return JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return undefined;
+  }
+}
+
 function parseJsonText(text, agent) {
   const trimmed = text.trim();
   const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  const candidate = fenced ? fenced[1] : trimmed;
   try {
-    return JSON.parse(fenced ? fenced[1] : trimmed);
+    return JSON.parse(candidate);
   } catch {
+    const extracted = extractJsonValue(candidate);
+    if (extracted !== undefined) return extracted;
     throw new Error(`${agent} did not return valid summary JSON`);
   }
 }
@@ -207,8 +348,35 @@ function parseOpenCodeResponse(stdout) {
   return parseJsonText(parts.join(''), 'OpenCode');
 }
 
+export function parseCursorStreamResponse(stdout) {
+  const trimmed = stdout.trim();
+  const lines = trimmed.split('\n').filter(Boolean);
+  const events = lines.map(parseEvent);
+  if (!lines.length || !events.every(Boolean)) {
+    throw new Error('Cursor did not return a valid event stream');
+  }
+  const envelope = [...events]
+    .reverse()
+    .find((event) => event.type === 'result');
+  if (!envelope || envelope.subtype !== 'success' || envelope.is_error) {
+    throw new Error('Cursor did not return a successful result');
+  }
+  if (typeof envelope.result !== 'string') {
+    throw new Error('Cursor did not return summary JSON');
+  }
+  return {
+    events,
+    response: parseJsonText(envelope.result, 'Cursor'),
+  };
+}
+
 function parseCursorResponse(stdout) {
-  const envelope = parseJsonText(stdout, 'Cursor');
+  const trimmed = stdout.trim();
+  const lines = trimmed.split('\n').filter(Boolean);
+  if (lines.length > 1) {
+    return parseCursorStreamResponse(trimmed).response;
+  }
+  const envelope = parseJsonText(trimmed, 'Cursor');
   if (typeof envelope?.result === 'string') {
     return parseJsonText(envelope.result, 'Cursor');
   }
@@ -380,6 +548,53 @@ function openCodeCommand({
   };
 }
 
+function cursorCommand({
+  binary,
+  inputPath,
+  model,
+  prompt,
+  schema,
+  summaryDirectory,
+  summaryEnv,
+  sourceEnv,
+}) {
+  const args = [
+    '--print',
+    '--output-format',
+    'stream-json',
+    '--mode',
+    'ask',
+    '--sandbox',
+    'enabled',
+    '--trust',
+    '--workspace',
+    summaryDirectory,
+  ];
+  if (model) args.push('--model', model);
+  args.push(
+    `${prompt}\n\nRead the snapshot JSON from ${basename(inputPath)} in this workspace. Return JSON that matches this schema:\n${JSON.stringify(schema)}`,
+  );
+  return {
+    command: binary,
+    args,
+    input: 'stdin',
+    cwd: summaryDirectory,
+    env: {
+      ...summaryEnv,
+      ...(sourceEnv.XDG_CONFIG_HOME
+        ? { XDG_CONFIG_HOME: sourceEnv.XDG_CONFIG_HOME }
+        : {}),
+      ...(sourceEnv.APPDATA ? { APPDATA: sourceEnv.APPDATA } : {}),
+      ...(sourceEnv.CURSOR_API_KEY
+        ? { CURSOR_API_KEY: sourceEnv.CURSOR_API_KEY }
+        : {}),
+      ...(sourceEnv.CURSOR_AUTH_TOKEN
+        ? { CURSOR_AUTH_TOKEN: sourceEnv.CURSOR_AUTH_TOKEN }
+        : {}),
+    },
+  };
+}
+
 export function agentCommand({
   agent,
   binary = agent,
@@ -391,8 +606,6 @@ export function agentCommand({
   inputPath,
   env = process.env,
 }) {
-  const disabled = agentDisabledReason(agent);
-  if (disabled) throw new Error(disabled);
   const options = {
     binary,
     inputPath,
@@ -403,9 +616,11 @@ export function agentCommand({
     schemaPath,
     summaryDirectory: dirname(inputPath),
     summaryEnv: summaryAgentEnvironment(env),
+    sourceEnv: env,
   };
   if (agent === 'codex') return codexCommand(options);
   if (agent === 'claude') return claudeCommand(options);
   if (agent === 'copilot') return copilotCommand(options);
+  if (agent === 'cursor') return cursorCommand(options);
   return openCodeCommand(options);
 }

package/scripts/doctor.mjs

@@ -1,9 +1,9 @@
 import { spawnSync } from 'node:child_process';
 import {
-  agentDisabledReason,
   codingAgentBinary,
   codingAgents,
   findCommand,
+  inspectCursorCompatibility,
 } from './coding-agents.mjs';
 
 const agentLabels = {
@@ -76,6 +76,28 @@ async function inspectDependency(label, command, { env, platform }) {
   };
 }
 
+async function inspectAgent(agent, { env, platform }) {
+  const label = agentLabels[agent];
+  const command = codingAgentBinary(agent, { env });
+  if (agent !== 'cursor') {
+    return inspectDependency(label, command, { env, platform });
+  }
+  const path = await findCommand(command, { env, platform });
+  if (!path) {
+    return { label, command, installed: false, compatible: 'not-checked' };
+  }
+  const inspection = inspectCursorCompatibility(path, { env });
+  return {
+    label,
+    command,
+    installed: true,
+    path,
+    version: inspection.version,
+    compatible: inspection.compatible ? 'yes' : 'no',
+    ...(inspection.reason ? { boundaryError: inspection.reason } : {}),
+  };
+}
+
 function dependencyLine(dependency) {
   const label = dependency.label.padEnd(9);
   if (dependency.disabled) {
@@ -84,6 +106,9 @@ function dependencyLine(dependency) {
   if (!dependency.installed) {
     return `  ✗ ${label} not found (${dependency.command})`;
   }
+  if (dependency.boundaryError) {
+    return `  ! ${label} ${dependency.version || 'version unavailable'} (${dependency.path}; ${dependency.boundaryError})`;
+  }
   const mark = dependency.version ? '✓' : '!';
   return `  ${mark} ${label} ${dependency.version || 'version unavailable'} (${dependency.path})`;
 }
@@ -132,23 +157,7 @@ async function inspectDependencies(env, platform) {
   const [git, gh, ...agents] = await Promise.all([
     inspectDependency('Git', 'git', { env, platform }),
     inspectDependency('gh', 'gh', { env, platform }),
-    ...codingAgents.map((agent) => {
-      const disabled = agentDisabledReason(agent);
-      if (disabled) {
-        return Promise.resolve({
-          label: agentLabels[agent],
-          command: codingAgentBinary(agent, { env }),
-          installed: false,
-          compatible: 'no',
-          disabled,
-        });
-      }
-      return inspectDependency(
-        agentLabels[agent],
-        codingAgentBinary(agent, { env }),
-        { env, platform },
-      );
-    }),
+    ...codingAgents.map((agent) => inspectAgent(agent, { env, platform })),
   ]);
   return { git, gh, agents };
 }

package/scripts/generate-summaries.mjs

@@ -15,8 +15,8 @@ import { fileURLToPath } from 'node:url';
 import {
   agentCommand,
   assertReasoningSupported,
+  codingAgentAvailability,
   codingAgentBinary,
-  commandAvailable,
   parseAgentResponse,
   selectCodingAgent,
 } from './coding-agents.mjs';
@@ -104,8 +104,8 @@ 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, or opencode
-                      Cursor is disabled because it cannot meet the review boundary
+  --agent NAME        Use codex, claude, copilot, cursor, or opencode
+                      Cursor needs version 2026.08.11 or newer
   --codex-bin FILE    Codex CLI path (default: codex)
   --model NAME        Model passed to the coding agent
   --reasoning LEVEL   Agent reasoning effort when supported
@@ -173,6 +173,7 @@ const proseCodePointLimit = 1_200;
 const detailItemLimit = 4;
 const riskItemLimit = 3;
 const listItemCodePointLimit = 500;
+const fileNoteAttemptLimit = 3;
 const jobsValue = option('--jobs') || '3';
 if (!/^[1-9]\d*$/.test(jobsValue) || Number(jobsValue) > 8) {
   fail('--jobs must be a number from 1 to 8');
@@ -930,7 +931,9 @@ async function selectAgentForNotes() {
   try {
     selectedAgent = await selectCodingAgent(
       requestedAgent,
-      (agent) => commandAvailable(codingAgentBinary(agent, { codexBin })),
+      (agent) => codingAgentAvailability(agent, {
+        binary: codingAgentBinary(agent, { codexBin }),
+      }),
     );
     assertReasoningSupported(selectedAgent, reasoning);
     agentBinary = codingAgentBinary(selectedAgent, { codexBin });
@@ -973,7 +976,7 @@ function failureReason(error) {
     'Agent note generation failed.';
 }
 
-function runAgent(invocation, input) {
+function runAgent(invocation, input, { timeoutMs } = {}) {
   return new Promise((resolvePromise, rejectPromise) => {
     const child = spawn(invocation.command, invocation.args, {
       cwd: invocation.cwd || root,
@@ -981,6 +984,15 @@ function runAgent(invocation, input) {
       stdio: ['pipe', 'pipe', 'pipe'],
     });
     activeAgentProcesses.add(child);
+    const timeout = timeoutMs
+      ? setTimeout(() => {
+        child.kill('SIGTERM');
+        rejectPromise(
+          new Error(`${selectedAgent} timed out`),
+        );
+      }, timeoutMs)
+      : undefined;
+    timeout?.unref();
     const stdout = [];
     const stderr = [];
     let outputBytes = 0;
@@ -1001,10 +1013,12 @@ function runAgent(invocation, input) {
       if (error.code !== 'EPIPE') rejectPromise(error);
     });
     child.once('error', (error) => {
+      if (timeout) clearTimeout(timeout);
       activeAgentProcesses.delete(child);
       rejectPromise(error);
     });
     child.once('close', (status, signal) => {
+      if (timeout) clearTimeout(timeout);
       activeAgentProcesses.delete(child);
       if (interrupted) {
         rejectPromise(new Error('Agent note generation was interrupted'));
@@ -1013,7 +1027,7 @@ function runAgent(invocation, input) {
       const stdoutText = Buffer.concat(stdout).toString('utf8');
       const stderrText = Buffer.concat(stderr).toString('utf8');
       if (status !== 0 || signal) {
-        const detail = stderrText
+        const detail = `${stdoutText}\n${stderrText}`
           .split('\n')
           .map((line) =>
             line.replace(
@@ -1120,6 +1134,10 @@ const temporaryDirectory = mkdtempSync(
 let workingSummaries;
 let workingSnapshot;
 
+function agentTemporaryPath(name) {
+  return resolve(temporaryDirectory, name);
+}
+
 try {
   recordSyncStage('cache', acquireOwnership);
   const { rawSnapshot, snapshot } = recordSyncStage('snapshot', () => {
@@ -1269,10 +1287,9 @@ try {
     }
     if (batch.length) batches.push(batch);
     let nextBatch = 0;
-    const requestBatch = async (index, batchPaths) => {
-      const schemaPath = resolve(
-        temporaryDirectory,
-        `summary-schema-${index + 1}.json`,
+    const requestBatch = async (index, batchPaths, attempt) => {
+      const schemaPath = agentTemporaryPath(
+        `summary-schema-${index + 1}-${attempt}.json`,
       );
       writeFileSync(
         schemaPath,
@@ -1289,9 +1306,8 @@ try {
         batchPaths,
         workingSummaries.files,
       );
-      const inputPath = resolve(
-        temporaryDirectory,
-        `summary-input-${index + 1}.json`,
+      const inputPath = agentTemporaryPath(
+        `summary-input-${index + 1}-${attempt}.json`,
       );
       writeFileSync(inputPath, input);
       const invocation = agentCommand({
@@ -1307,7 +1323,7 @@ try {
       });
 
       console.error(
-        `Asking ${selectedAgent} for batch ${index + 1} of ${batches.length} (${batchPaths.length} changed files)...`,
+        `Asking ${selectedAgent} for batch ${index + 1} of ${batches.length} (${batchPaths.length} changed files, attempt ${attempt} of ${fileNoteAttemptLimit})...`,
       );
       return requestAgent(
         invocation,
@@ -1321,45 +1337,73 @@ try {
     };
     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),
+      let pendingPaths = batchPaths;
+      for (
+        let attempt = 1;
+        attempt <= fileNoteAttemptLimit && pendingPaths.length;
+        attempt += 1
+      ) {
+        let outcome;
+        let requestFailed = false;
+        try {
+          outcome = await requestBatch(index, pendingPaths, attempt);
+        } catch (error) {
+          if (interrupted) throw error;
+          requestFailed = true;
+          const reason = failureReason(error);
+          console.error(
+            error instanceof Error ? error.message : String(error),
+          );
+          outcome = {
+            files: {},
+            failedFiles: pendingPaths.map((path) => ({ path, reason })),
+            errors: [],
+          };
+        }
+        const requestedPaths = new Set(pendingPaths);
+        const retryableFailures = requestFailed
+          ? []
+          : outcome.failedFiles.filter(
+              (failure) => requestedPaths.has(failure.path),
+            );
+        const finalAttempt =
+          requestFailed || attempt === fileNoteAttemptLimit;
+        const keptFailures = outcome.failedFiles.filter(
+          (failure) =>
+            requestedPaths.has(failure.path)
+              ? finalAttempt
+              : !completeFileNote(workingSummaries.files[failure.path]),
         );
-        outcome = {
-          files: {},
-          failedFiles: batchPaths.map((path) => ({ path, reason })),
-          errors: [],
+        workingSummaries = {
+          ...(workingSummaries.change
+            ? { change: workingSummaries.change }
+            : {}),
+          files: {
+            ...workingSummaries.files,
+            ...outcome.files,
+          },
+          meta: {
+            ...workingSummaries.meta,
+            status: 'generating',
+            generatedAt: new Date().toISOString(),
+          },
         };
-      }
-      workingSummaries = {
-        ...(workingSummaries.change
-          ? { change: workingSummaries.change }
-          : {}),
-        files: {
-          ...workingSummaries.files,
-          ...outcome.files,
-        },
-        meta: {
-          ...workingSummaries.meta,
-          status: 'generating',
-          generatedAt: new Date().toISOString(),
-        },
-      };
-      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}`,
+        workingSummaries = addFailures(
+          workingSummaries,
+          keptFailures,
+          finalAttempt || retryableFailures.length === 0
+            ? outcome.errors
+            : [],
         );
+        storeProgress(rawSnapshot, workingSummaries);
+        if (pendingPaths.length) {
+          console.log(
+            `Wrote ${Object.keys(workingSummaries.files).length} of ${paths.length} agent notes to ${summariesPath}`,
+          );
+        }
+        pendingPaths = [...new Set(
+          retryableFailures.map((failure) => failure.path),
+        )];
       }
     };
     const workers = Array.from(
@@ -1375,10 +1419,7 @@ try {
     await Promise.all(workers);
     if (changeNeedsRefresh) {
       try {
-        const schemaPath = resolve(
-          temporaryDirectory,
-          'change-summary-schema.json',
-        );
+        const schemaPath = agentTemporaryPath('change-summary-schema.json');
         const schema = outputSchema([]);
         writeFileSync(
           schemaPath,
@@ -1390,10 +1431,7 @@ try {
           [],
           workingSummaries.files,
         );
-        const inputPath = resolve(
-          temporaryDirectory,
-          'change-summary-input.json',
-        );
+        const inputPath = agentTemporaryPath('change-summary-input.json');
         writeFileSync(inputPath, input);
         const invocation = agentCommand({
           agent: selectedAgent,

package/scripts/present.mjs

@@ -18,8 +18,8 @@ import { fileURLToPath } from 'node:url';
 import { helpText, parseCliArgs } from './cli-args.mjs';
 import {
   assertReasoningSupported,
+  codingAgentAvailability,
   codingAgentBinary,
-  commandAvailable,
   selectCodingAgent,
 } from './coding-agents.mjs';
 import { doctorReport } from './doctor.mjs';
@@ -189,9 +189,9 @@ if (agentEnabled) {
     selectedAgent = await selectCodingAgent(
       cli.agent,
       (agent) =>
-        commandAvailable(
-          codingAgentBinary(agent, { codexBin: cli.codexBin }),
-        ),
+        codingAgentAvailability(agent, {
+          binary: codingAgentBinary(agent, { codexBin: cli.codexBin }),
+        }),
     );
     assertReasoningSupported(selectedAgent, cli.reasoning);
     const agentBinary = codingAgentBinary(selectedAgent, {