@progen-labs/spectra 0.5.0 → 0.7.0

package/server/fix/agent.js

@@ -1,18 +1,97 @@
 /**
- * The coding agent `spectra fix` hands one finding to. By default it is Claude
- * Code in headless mode, allowed only to read and edit files: no shell, no
- * web, no MCP servers. Any other agent works through --agent "<command>": it
- * gets the instructions on stdin (and in $SPECTRA_FIX_PROMPT_FILE) and runs in
- * the copy of the project.
+ * The coding agent `spectra improve` hands one finding to when it runs
+ * unattended. Spectra knows the common agent CLIs by name (AGENTS below) and
+ * finds one on the machine by itself; Claude Code runs allowed only to read
+ * and edit files: no shell, no web, no MCP servers. Any other agent works
+ * through --agent "<command>": it gets the instructions on stdin (and in
+ * $SPECTRA_FIX_PROMPT_FILE) and runs in the copy of the project.
  */
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+/**
+ * The agents Spectra can run by name: how each one takes a single prompt,
+ * edits files in the current directory without asking, and exits (the
+ * "print" mode every CLI agent has), and the signs that it is in use.
+ */
+export const AGENTS = {
+  claude: { name: 'Claude Code', bin: 'claude', project: ['CLAUDE.md', '.claude'], home: ['.claude', '.claude.json'], also: ['.local/bin/claude', '.claude/local/claude'] },
+  codex: { name: 'Codex CLI', bin: 'codex', args: p => ['exec', '--full-auto', p], project: ['.codex'], home: ['.codex'] },
+  gemini: { name: 'Gemini CLI', bin: 'gemini', args: p => ['-p', p, '--yolo'], project: ['GEMINI.md', '.gemini'], home: ['.gemini'] },
+  copilot: { name: 'GitHub Copilot CLI', bin: 'copilot', args: p => ['-p', p, '--allow-all-tools'], project: ['.github/copilot-instructions.md', '.github/instructions'], home: ['.copilot'] },
+  cursor: { name: 'Cursor CLI', bin: 'cursor-agent', args: p => ['-p', p, '--force'], project: ['.cursor', '.cursorrules'], home: ['.cursor'] },
+  opencode: { name: 'OpenCode', bin: 'opencode', args: p => ['run', p], project: ['opencode.json', '.opencode'], home: ['.config/opencode'] },
+  amp: { name: 'Amp', bin: 'amp', args: p => ['-x', p], project: [], home: ['.config/amp'] },
+};
+export const AGENT_IDS = Object.keys(AGENTS);
+
+const exists = p => {
+  try {
+    fs.statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Where an agent's executable is: on PATH, or in the places its installer uses. Null when it is not installed. */
+export function findExecutable(id, { env = process.env, home = os.homedir() } = {}) {
+  const a = AGENTS[id];
+  if (id === 'claude' && env.SPECTRA_CLAUDE) return env.SPECTRA_CLAUDE;
+  const names = process.platform === 'win32' ? [`${a.bin}.cmd`, `${a.bin}.exe`, a.bin] : [a.bin];
+  for (const dir of (env.PATH || '').split(path.delimiter).filter(Boolean))
+    for (const n of names) if (exists(path.join(dir, n))) return path.join(dir, n);
+  for (const rel of a.also || []) if (home && exists(path.join(home, rel))) return path.join(home, rel);
+  return null;
+}
+
+/**
+ * The agent to run unattended, when none was named: first one the project or
+ * the machine shows signs of (so it is the agent the user already works with),
+ * then any that is installed. Null when there is none.
+ */
+export function detectAgent({ root = process.cwd(), home = os.homedir(), env = process.env } = {}) {
+  const installed = AGENT_IDS.filter(id => findExecutable(id, { env, home }));
+  const inUse = id => (AGENTS[id].project || []).some(p => exists(path.join(root, p))) || (AGENTS[id].home || []).some(p => home && exists(path.join(home, p)));
+  const id = installed.find(inUse) || installed[0];
+  return id ? { id, ...AGENTS[id], bin: findExecutable(id, { env, home }) } : null;
+}
+
+/** The agent for --agent: a name from AGENTS, or any shell command. */
+export function agentFromOption(value, opts = {}) {
+  return AGENTS[value] ? namedAgent(value, opts) : commandAgent(String(value), opts);
+}
+
+/** One of AGENTS, ready to run. */
+export function namedAgent(id, { bin, model, budgetUsd, timeoutMs = 10 * 60_000, env, home } = {}) {
+  const a = AGENTS[id];
+  if (!a) throw new Error(`unknown agent "${id}"; the names are ${AGENT_IDS.join(', ')}, or pass a command.`);
+  const executable = bin || findExecutable(id, { env, home }) || a.bin;
+  if (id === 'claude') return claudeAgent({ bin: executable, model, budgetUsd, timeoutMs });
+  return {
+    id,
+    name: a.name,
+    async run(prompt, { cwd, signal }) {
+      let res;
+      try {
+        res = await run(executable, a.args(prompt), { cwd, signal, timeoutMs, env: { CI: '1' } });
+      } catch (err) {
+        throw new Error(`could not start ${a.name} (${err.message}). Install it, or pass --agent "<command>".`);
+      }
+      if (res.code !== 0) throw new Error(`${a.name} exited with code ${res.code}: ${(res.err || res.out).trim().split('\n').slice(-3).join(' ')}`);
+      return { summary: res.out.trim().split('\n').filter(Boolean).pop()?.slice(0, 300) || '', costUsd: null, turns: null, error: null };
+    },
+  };
+}
+
+// `input` goes to the agent's stdin; without it, stdin is closed from the start
+// (the prompt is in the arguments). An agent that exits before reading its
+// stdin makes the write fail with EPIPE, which must not take Spectra down.
 const run = (cmd, args, { cwd, input, env, signal, timeoutMs, shell = false }) =>
   new Promise((resolve, reject) => {
-    const child = spawn(cmd, args, { cwd, env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'pipe'], shell });
+    const child = spawn(cmd, args, { cwd, env: { ...process.env, ...env }, stdio: [input == null ? 'ignore' : 'pipe', 'pipe', 'pipe'], shell });
     let out = '';
     let err = '';
     child.stdout.on('data', d => (out += d));
@@ -29,12 +108,16 @@ const run = (cmd, args, { cwd, input, env, signal, timeoutMs, shell = false }) =
       signal?.removeEventListener('abort', abort);
       resolve({ code, out, err });
     });
-    child.stdin.end(input ?? '');
+    if (input != null) {
+      child.stdin.on('error', () => {}); // the agent closed its end first
+      child.stdin.end(input);
+    }
   });
 
 /** Claude Code, headless. */
 export function claudeAgent({ bin = process.env.SPECTRA_CLAUDE || 'claude', model, budgetUsd = 2, timeoutMs = 10 * 60_000 } = {}) {
   return {
+    id: 'claude',
     name: `Claude Code${model ? ` (${model})` : ''}`,
     async run(prompt, { cwd, signal }) {
       const args = [

package/server/fix/cli.js

@@ -1,9 +1,10 @@
 /**
- * spectra fix — the AI fix harness. It runs in the user's project: profiles a
- * copy of the last commit, hands the costliest findings in the project's own
- * code to a coding agent one at a time, and keeps a change only when the
- * project's checks pass and Spectra measures it faster beyond run-to-run
- * noise. Kept changes are commits on a new branch; nothing else is touched.
+ * The unattended mode of `spectra improve` (and `spectra fix`, its old name).
+ * It runs in the user's project: profiles a copy of the last commit, hands
+ * the costliest findings in the project's own code to a coding agent one at
+ * a time, and keeps a change only when the project's checks pass and Spectra
+ * measures it faster beyond run-to-run noise. Kept changes are commits on a
+ * new branch; nothing else is touched.
  */
 import { spawn, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
@@ -11,227 +12,198 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { intOption, parseArgs } from '../args.js';
 import { bootDevServer } from '../explore/boot.js';
-import { SPECTRA_VERSION } from '../output.js';
-import { claudeAgent, commandAgent } from './agent.js';
+import { EXIT, SPECTRA_VERSION } from '../output.js';
+import { agentFromOption, claudeAgent, detectAgent } from './agent.js';
 import { detectChecks, runChecks } from './checks.js';
 import { runFix } from './harness.js';
 import { reportMarkdown } from './report.js';
 import { changesIn, commitChange, commitsOn, createWorkspace, diffOf, ignoreSpectra, removeWorkspace, repoOf, uncommitted, undoChanges } from './workspace.js';
 
 const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/spectra.js');
-const argv = process.argv.slice(3);
-const { opt, flag } = parseArgs(argv, { values: ['runs', 'max-fixes', 'agent', 'model', 'max-budget-usd', 'check', 'command', 'boot-timeout', 'branch', 'out', 'max-lines'] });
-const log = line => console.error(`spectra: ${line}`);
-const json = flag('json');
-
-const HELP = `usage: spectra fix [options]
-
-The AI fix harness. In an isolated copy of your last commit, it hands the
-costliest findings in your own code to a coding agent one at a time, then
-keeps a change only if your checks pass and Spectra measures it faster
-beyond run-to-run noise. Kept changes are commits on a new branch.
-
-  --max-fixes <n>         Findings to attempt (default 3)
-  --runs <n>              Page loads per measurement (default 3)
-  --check "<cmd>"         A check that must pass after every change (repeat it
-                          for several). Default: your test, typecheck and
-                          build scripts. Checks can test the running app at
-                          $SPECTRA_FIX_URL.
-  --no-checks             Rely on measurements alone (not recommended)
-  --agent "<cmd>"         Your own agent: gets the instructions on stdin and in
-                          $SPECTRA_FIX_PROMPT_FILE, runs in the copy
-  --model <name>          Model for Claude Code, the default agent
-  --max-budget-usd <n>    Claude Code's spending cap per finding (default 2)
-  --command "<cmd>"       The dev-server command (default: your npm dev script)
-  --boot-timeout <s>      How long to wait for the dev server (default 60)
-  --install               Install dependencies in the copy instead of linking yours
-  --branch <name>         Branch for the fixes (default spectra/fix-<time>)
-  --max-lines <n>         Largest change accepted (default 150 lines)
-  --retry                 Try findings that failed in an earlier session
-  --keep-worktree         Keep the copy in .spectra/fix/ for inspection
-  --json, --out <file>    Machine-readable session report`;
-
-if (flag('help') || flag('h')) {
-  console.log(HELP);
-  process.exit(0);
-}
+const VALUES = ['runs', 'max-fixes', 'agent', 'model', 'max-budget-usd', 'check', 'command', 'boot-timeout', 'branch', 'out', 'max-lines', 'url'];
 
-const fail = (message, code = 1) => {
-  console.error(`spectra: ${message}`);
-  process.exit(code);
-};
-
-const checksFrom = () => {
-  const list = [];
-  for (let i = 0; i < argv.length; i++) if (argv[i] === '--check' && argv[i + 1]) list.push({ name: argv[i + 1], cmd: argv[++i] });
-  return list;
-};
-
-let runs;
-let maxFixes;
-let maxLines;
-try {
-  runs = intOption(opt('runs'), 'runs', { min: 1, max: 10, fallback: 3 });
-  maxFixes = intOption(opt('max-fixes'), 'max-fixes', { min: 1, max: 20, fallback: 3 });
-  maxLines = intOption(opt('max-lines'), 'max-lines', { min: 1, max: 5000, fallback: 150 });
-} catch (err) {
-  fail(err.message);
-}
-if (opt('url')) fail('spectra fix starts its own dev server in a copy of your project, so it does not take --url. Use --command if the dev server needs a special command.');
-
-const projectDir = process.cwd();
-let repo;
-try {
-  repo = repoOf(projectDir);
-} catch (err) {
-  fail(err.message);
-}
-const dirty = uncommitted(repo.root);
-if (dirty.length)
-  fail(`commit or stash your changes first: spectra fix works on a copy of your last commit, and these would not be in it:\n  ${dirty.slice(0, 6).join('\n  ')}${dirty.length > 6 ? '\n  …' : ''}`);
-
-let checks = checksFrom();
-if (!checks.length && !flag('no-checks')) checks = detectChecks(projectDir);
-if (!checks.length && !flag('no-checks'))
-  fail('no checks to run. A faster page must not be a broken one, so spectra fix needs at least one check that proves the app still works: add a test script, pass --check "<cmd>" (it can test the running app at $SPECTRA_FIX_URL), or pass --no-checks to rely on measurements alone.');
-if (flag('no-checks')) checks = [];
-
-const agent = opt('agent')
-  ? commandAgent(String(opt('agent')))
-  : claudeAgent({ model: opt('model') === true ? undefined : opt('model'), budgetUsd: Number(opt('max-budget-usd') ?? 2) });
-
-const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '-');
-const sessionRoot = path.join(projectDir, '.spectra', 'fix');
-const sessionDir = path.join(sessionRoot, stamp);
-const historyFile = path.join(sessionRoot, 'history.json');
-let branch = typeof opt('branch') === 'string' ? opt('branch') : `spectra/fix-${stamp}`;
-fs.mkdirSync(path.join(sessionDir, 'results'), { recursive: true });
-ignoreSpectra(repo.root);
-
-const controller = new AbortController();
-let ws = null;
-let server = null;
-let child = null;
-let session = null;
-
-async function cleanup() {
-  await server?.stop().catch(() => {});
-  if (ws && !flag('keep-worktree')) removeWorkspace(repo.root, ws, { keepBranch: commitsOn(repo.root, ws.branch) > 0 });
-}
-for (const signal of ['SIGINT', 'SIGTERM']) {
-  process.on(signal, () => {
+/**
+ * Runs a session. `agent` is the agent to use when the options name none;
+ * without it, the agent found on the machine, or Claude Code.
+ * @returns {Promise<number>} the exit code
+ */
+export async function runFixCli(argv, { agent: given = null } = {}) {
+  const { opt, flag } = parseArgs(argv, { values: VALUES });
+  const log = line => console.error(`spectra: ${line}`);
+  const json = flag('json');
+  const fail = message => {
+    throw Object.assign(new Error(message), { early: true });
+  };
+
+  const checksFrom = () => {
+    const list = [];
+    for (let i = 0; i < argv.length; i++) if (argv[i] === '--check' && argv[i + 1]) list.push({ name: argv[i + 1], cmd: argv[++i] });
+    return list;
+  };
+
+  const controller = new AbortController();
+  let ws = null;
+  let server = null;
+  let child = null;
+  let session = null;
+  let repo = null;
+  let branch = null;
+  let sessionDir = null;
+  const projectDir = process.cwd();
+
+  async function cleanup() {
+    await server?.stop().catch(() => {});
+    if (ws && !flag('keep-worktree')) removeWorkspace(repo.root, ws, { keepBranch: commitsOn(repo.root, ws.branch) > 0 });
+  }
+  const onSignal = signal => {
     controller.abort();
     child?.kill('SIGTERM');
     log('stopping …');
     cleanup().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
-  });
-}
-
-/** `spectra <args> --json` in the copy; resolves with the parsed result. */
-function spectra(args) {
-  return new Promise((resolve, reject) => {
-    child = spawn(process.execPath, [BIN, ...args, '--json'], {
-      cwd: ws.projectDir,
-      env: { ...process.env, PERF_FRONTEND_DIR: ws.projectDir, PERF_REPORTS_DIR: path.join(sessionDir, 'reports') },
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let out = '';
-    let err = '';
-    child.stdout.on('data', d => (out += d));
-    child.stderr.on('data', d => {
-      err += d;
-      for (const line of String(d).split('\n')) if (/^spectra: run \d+\/\d+/.test(line)) console.error(`           ${line.replace(/^spectra:\s*/, '')}`);
+  };
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, onSignal);
+
+  /** `spectra <args> --json` in the copy; resolves with the parsed result. */
+  function spectra(args) {
+    return new Promise((resolve, reject) => {
+      child = spawn(process.execPath, [BIN, ...args, '--json'], {
+        cwd: ws.projectDir,
+        env: { ...process.env, PERF_FRONTEND_DIR: ws.projectDir, PERF_REPORTS_DIR: path.join(sessionDir, 'reports') },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      let out = '';
+      let err = '';
+      child.stdout.on('data', d => (out += d));
+      child.stderr.on('data', d => {
+        err += d;
+        for (const line of String(d).split('\n')) if (/^spectra: run \d+\/\d+/.test(line)) console.error(`           ${line.replace(/^spectra:\s*/, '')}`);
+      });
+      child.on('error', reject);
+      child.on('close', code => {
+        if (code === 1) return reject(new Error(err.trim().split('\n').filter(l => l.startsWith('spectra:')).pop()?.replace(/^spectra:\s*/, '') || `spectra ${args[0]} failed`));
+        try {
+          resolve(JSON.parse(out));
+        } catch {
+          reject(new Error(`spectra ${args[0]} printed no result`));
+        }
+      });
     });
-    child.on('error', reject);
-    child.on('close', code => {
-      if (code === 1) return reject(new Error(err.trim().split('\n').filter(l => l.startsWith('spectra:')).pop()?.replace(/^spectra:\s*/, '') || `spectra ${args[0]} failed`));
-      try {
-        resolve(JSON.parse(out));
-      } catch {
-        reject(new Error(`spectra ${args[0]} printed no result`));
-      }
-    });
-  });
-}
-
-const slug = s => s.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').toLowerCase();
-
-try {
-  if (branchExists(branch)) throw new Error(`branch ${branch} already exists; pass --branch <name>.`);
-  log(`working in a copy of ${shortHead()} on branch ${branch} …`);
-  ws = createWorkspace({ root: repo.root, sub: repo.sub, dir: path.join(sessionDir, 'worktree'), branch, install: flag('install'), log });
-  ws.exists = file => fs.existsSync(path.join(ws.projectDir, file));
-  ws.changes = () => changesIn(ws);
-  ws.diff = () => diffOf(ws);
-  ws.commit = (files, message) => commitChange(ws, files, message);
-  ws.undo = () => undoChanges(ws);
-
-  const command = typeof opt('command') === 'string' ? opt('command') : undefined;
-  log(`starting the dev server in the copy${command ? ` (${command})` : ''} …`);
-  server = await bootDevServer({ root: ws.projectDir, command, timeoutMs: (Number(opt('boot-timeout')) || 60) * 1000 });
-  log(`dev server ready at ${server.url}`);
+  }
+  const slug = s => s.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').toLowerCase();
 
-  let history = {};
+  let agent = given;
   try {
-    history = JSON.parse(fs.readFileSync(historyFile, 'utf8'));
-  } catch {
-    /* first session */
+    const runs = intOption(opt('runs'), 'runs', { min: 1, max: 10, fallback: 3 });
+    const maxFixes = intOption(opt('max-fixes'), 'max-fixes', { min: 1, max: 20, fallback: 3 });
+    const maxLines = intOption(opt('max-lines'), 'max-lines', { min: 1, max: 5000, fallback: 150 });
+    if (opt('url')) fail('spectra improve starts its own dev server in a copy of your project, so it does not take --url. Use --command if the dev server needs a special command, or `spectra improve next` to work on a running page.');
+
+    repo = repoOf(projectDir);
+    const dirty = uncommitted(repo.root);
+    if (dirty.length)
+      fail(`commit or stash your changes first: spectra improve works on a copy of your last commit, and these would not be in it:\n  ${dirty.slice(0, 6).join('\n  ')}${dirty.length > 6 ? '\n  …' : ''}`);
+
+    let checks = checksFrom();
+    if (!checks.length && !flag('no-checks')) checks = detectChecks(projectDir);
+    if (!checks.length && !flag('no-checks'))
+      fail('no checks to run. A faster page must not be a broken one, so spectra improve needs at least one check that proves the app still works: add a test script, pass --check "<cmd>" (it can test the running app at $SPECTRA_FIX_URL), or pass --no-checks to rely on measurements alone.');
+    if (flag('no-checks')) checks = [];
+
+    if (!agent) {
+      const agentOpts = { model: opt('model') === true ? undefined : opt('model'), budgetUsd: Number(opt('max-budget-usd') ?? 2) };
+      const found = opt('agent') ? null : detectAgent();
+      agent = opt('agent') ? agentFromOption(String(opt('agent')), agentOpts) : found ? agentFromOption(found.id, { ...agentOpts, bin: found.bin }) : claudeAgent(agentOpts);
+    }
+
+    const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '-');
+    const sessionRoot = path.join(projectDir, '.spectra', 'improve');
+    sessionDir = path.join(sessionRoot, stamp);
+    const historyFile = path.join(sessionRoot, 'history.json');
+    branch = typeof opt('branch') === 'string' ? opt('branch') : `spectra/improve-${stamp}`;
+    fs.mkdirSync(path.join(sessionDir, 'results'), { recursive: true });
+    ignoreSpectra(repo.root);
+
+    if (branchExists(repo.root, branch)) fail(`branch ${branch} already exists; pass --branch <name>.`);
+    log(`working in a copy of ${shortHead(repo.root)} on branch ${branch}, with ${agent.name} …`);
+    ws = createWorkspace({ root: repo.root, sub: repo.sub, dir: path.join(sessionDir, 'worktree'), branch, install: flag('install'), log });
+    ws.exists = file => fs.existsSync(path.join(ws.projectDir, file));
+    ws.changes = () => changesIn(ws);
+    ws.diff = () => diffOf(ws);
+    ws.commit = (files, message) => commitChange(ws, files, message);
+    ws.undo = () => undoChanges(ws);
+
+    const command = typeof opt('command') === 'string' ? opt('command') : undefined;
+    log(`starting the dev server in the copy${command ? ` (${command})` : ''} …`);
+    server = await bootDevServer({ root: ws.projectDir, command, timeoutMs: (Number(opt('boot-timeout')) || 60) * 1000 });
+    log(`dev server ready at ${server.url}`);
+
+    let history = {};
+    try {
+      history = JSON.parse(fs.readFileSync(historyFile, 'utf8'));
+    } catch {
+      /* first session */
+    }
+
+    session = await runFix({
+      agent,
+      workspace: ws,
+      checks,
+      history,
+      retry: flag('retry'),
+      maxFixes,
+      maxLines,
+      url: server.url,
+      signal: controller.signal,
+      log,
+      runChecks: () => runChecks(checks, { cwd: ws.projectDir, env: { SPECTRA_FIX_URL: server.url }, signal: controller.signal }),
+      profile: async label => {
+        const file = path.join(sessionDir, 'results', `${slug(label)}.json`);
+        const result = await spectra(['performance', '--quick', '--runs', String(runs), '--url', server.url, '--out', file]);
+        return { file, result };
+      },
+      compare: async (before, after) => (await spectra(['compare', before.join(','), after.join(',')])).comparison,
+    });
+    Object.assign(session, { kind: 'fix', spectraVersion: SPECTRA_VERSION, project: projectDir, branch, runs, startedAt: stamp, sessionDir });
+
+    for (const a of session.attempts) history[a.finding.key] = { title: a.finding.title, outcome: a.outcome, at: new Date().toISOString() };
+    fs.writeFileSync(historyFile, `${JSON.stringify(history, null, 2)}\n`);
+  } catch (err) {
+    console.error(`spectra: ${err.message}`);
+    if (err.tail) console.error(err.tail.replace(/^/gm, '  | '));
+    if (/cannot work/.test(err.message) && agent?.id === 'claude' && !opt('agent'))
+      console.error('spectra: sign in to Claude Code first (run `claude` once), set SPECTRA_CLAUDE to its path, or pass --agent <name|"command">.');
+    await cleanup();
+    for (const signal of ['SIGINT', 'SIGTERM']) process.off(signal, onSignal);
+    return EXIT.ERROR;
   }
 
-  session = await runFix({
-    agent,
-    workspace: ws,
-    checks,
-    history,
-    retry: flag('retry'),
-    maxFixes,
-    maxLines,
-    url: server.url,
-    signal: controller.signal,
-    log,
-    runChecks: () => runChecks(checks, { cwd: ws.projectDir, env: { SPECTRA_FIX_URL: server.url }, signal: controller.signal }),
-    profile: async label => {
-      const file = path.join(sessionDir, 'results', `${slug(label)}.json`);
-      const result = await spectra(['performance', '--quick', '--runs', String(runs), '--url', server.url, '--out', file]);
-      return { file, result };
-    },
-    compare: async (before, after) => (await spectra(['compare', before.join(','), after.join(',')])).comparison,
-  });
-  Object.assign(session, { kind: 'fix', spectraVersion: SPECTRA_VERSION, project: projectDir, branch, runs, startedAt: stamp, sessionDir });
-
-  for (const a of session.attempts) history[a.finding.key] = { title: a.finding.title, outcome: a.outcome, at: new Date().toISOString() };
-  fs.writeFileSync(historyFile, `${JSON.stringify(history, null, 2)}\n`);
-} catch (err) {
-  console.error(`spectra: ${err.message}`);
-  if (err.tail) console.error(err.tail.replace(/^/gm, '  | '));
-  if (/cannot work/.test(err.message) && !opt('agent'))
-    console.error('spectra: sign in to Claude Code first (run `claude` once), set SPECTRA_CLAUDE to its path, or pass --agent "<command>".');
   await cleanup();
-  process.exit(1);
-}
-
-await cleanup();
-const md = reportMarkdown(session);
-fs.writeFileSync(path.join(sessionDir, 'report.md'), md);
-fs.writeFileSync(path.join(sessionDir, 'report.json'), `${JSON.stringify(session, null, 2)}\n`);
-if (opt('out') && typeof opt('out') === 'string') fs.writeFileSync(path.resolve(opt('out')), `${JSON.stringify(session, null, 2)}\n`);
-
-const rel = p => path.relative(projectDir, p) || '.';
-console.error('');
-console.error(`Spectra fix — ${session.kept} of ${session.attempts.length} finding${session.attempts.length === 1 ? '' : 's'} fixed`);
-for (const a of session.attempts) console.error(`  ${a.outcome === 'kept' ? '✓ kept    ' : '✗ undone  '} ${a.finding.title} (${a.finding.file}${a.finding.line ? `:${a.finding.line}` : ''})${a.outcome === 'kept' ? '' : ` — ${a.reason}`}`);
-if (session.final) {
-  console.error(`\nOverall: ${session.final.verdict.toUpperCase()} (confidence: ${session.final.confidence})`);
-  for (const h of session.final.headlines) console.error(`  ${h.kind === 'improved' ? '✓' : '✗'} ${h.text}`);
+  for (const signal of ['SIGINT', 'SIGTERM']) process.off(signal, onSignal);
+  const md = reportMarkdown(session);
+  fs.writeFileSync(path.join(sessionDir, 'report.md'), md);
+  fs.writeFileSync(path.join(sessionDir, 'report.json'), `${JSON.stringify(session, null, 2)}\n`);
+  if (opt('out') && typeof opt('out') === 'string') fs.writeFileSync(path.resolve(opt('out')), `${JSON.stringify(session, null, 2)}\n`);
+
+  const rel = p => path.relative(projectDir, p) || '.';
+  const n = session.attempts.length;
+  console.error('');
+  if (!n && !session.skipped.length) console.error("Spectra improve — nothing to fix: nothing in your own code crossed Spectra's thresholds.");
+  else console.error(`Spectra improve — ${session.kept} of ${n} problem${n === 1 ? '' : 's'} fixed`);
+  for (const a of session.attempts) console.error(`  ${a.outcome === 'kept' ? '✓ fixed   ' : '✗ undone  '} ${a.finding.title} (${a.finding.file}${a.finding.line ? `:${a.finding.line}` : ''})${a.outcome === 'kept' ? `: ${a.reason}` : ` — ${a.reason}`}`);
+  for (const s of session.skipped) console.error(`  – skipped  ${s.title} — ${s.reason}`);
+  if (session.final) {
+    console.error(`\nOverall, before → after: ${session.final.verdict.toUpperCase()} (confidence: ${session.final.confidence})`);
+    for (const h of session.final.headlines) console.error(`  ${h.kind === 'improved' ? '✓' : '✗'} ${h.text}`);
+  }
+  if (session.kept) console.error(`\nThe fixes are on branch ${branch}, one commit each, with the measurements in the commit messages.\nReview them with:  git log -p HEAD..${branch}\nthen merge the branch or open a pull request. Your own files were not touched.`);
+  console.error(`\nReport: ${rel(path.join(sessionDir, 'report.md'))}`);
+  if (json) process.stdout.write(`${JSON.stringify(session)}\n`);
+  return EXIT.OK;
 }
-if (session.kept) console.error(`\nThe fixes are on branch ${branch}. Review them with:\n  git log -p HEAD..${branch}\nthen merge the branch or open a pull request.`);
-console.error(`\nReport: ${rel(path.join(sessionDir, 'report.md'))}`);
-if (json) process.stdout.write(`${JSON.stringify(session)}\n`);
-process.exit(0);
 
-function branchExists(name) {
-  return spawnSync('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${name}`], { cwd: repo.root }).status === 0;
+function branchExists(root, name) {
+  return spawnSync('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${name}`], { cwd: root }).status === 0;
 }
-function shortHead() {
-  return spawnSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: repo.root, encoding: 'utf8' }).stdout.trim();
+function shortHead(root) {
+  return spawnSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout.trim();
 }

package/server/fix/policy.js

@@ -92,7 +92,9 @@ export function judge(c) {
   if (c.verdict === 'regressed') return { decision: 'discard', outcome: 'slower', reason: `slower: ${worse[0] || 'a key metric got worse'}` };
   if (c.verdict === 'mixed') return { decision: 'discard', outcome: 'mixed', reason: `mixed: ${worse[0] || 'something got worse'}` };
   if (c.verdict !== 'improved') return { decision: 'discard', outcome: 'no-gain', reason: 'no measurable improvement: every change was within run-to-run noise' };
-  const critical = c.findings.added.find(f => f.severity === 'critical');
+  // a new critical problem in the project's own code counts; one in a dependency or a network
+  // resource (a vendor chunk the dev server renamed between runs) is not something the change made
+  const critical = c.findings.added.find(f => f.severity === 'critical' && ownFile(f));
   if (critical) return { decision: 'discard', outcome: 'new-problem', reason: `introduced a critical finding: ${critical.title}` };
   if (c.confidence === 'low') return { decision: 'measure-again', outcome: 'unproven', reason: 'improved, but with low confidence' };
   return { decision: 'keep', outcome: 'kept', reason: better[0] || 'improved', headlines: better };

package/server/fix/test-fix.js

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { test } from 'node:test';
-import { commandAgent } from './agent.js';
+import { AGENTS, agentFromOption, commandAgent, detectAgent, findExecutable, namedAgent } from './agent.js';
 import { detectChecks } from './checks.js';
 import { runFix } from './harness.js';
 import { fixPrompt, judge, rankFindings, scopeProblem } from './policy.js';
@@ -57,7 +57,10 @@ test('judges a change from the comparison', () => {
   assert.equal(judge(comparison('neutral')).outcome, 'no-gain');
   assert.equal(judge(comparison('regressed')).outcome, 'slower');
   assert.equal(judge(comparison('mixed')).outcome, 'mixed');
-  assert.equal(judge(comparison('improved', 'high', { added: [{ severity: 'critical', title: 'Long task' }] })).outcome, 'new-problem');
+  assert.equal(judge(comparison('improved', 'high', { added: [{ severity: 'critical', title: 'Long task', file: 'src/App.jsx' }] })).outcome, 'new-problem');
+  // a new critical finding outside the project's code (a renamed vendor chunk, a request) is not the change's doing
+  assert.equal(judge(comparison('improved', 'high', { added: [{ severity: 'critical', title: 'react-dom-Zq1x.js is 2.47 MB over the wire', file: null, culprits: [] }] })).decision, 'keep');
+  assert.equal(judge(comparison('improved', 'high', { added: [{ severity: 'critical', title: 'big', file: 'node_modules/x/index.js' }] })).decision, 'keep');
 });
 
 test('tells the agent the finding and the rules', () => {
@@ -225,3 +228,41 @@ test('finds checks in package.json and runs any agent command', async () => {
   assert.equal(fs.readFileSync(path.join(root, 'app/src/Row.jsx'), 'utf8'), '// Finding: Row is slow\n');
   fs.rmSync(root, { recursive: true, force: true });
 });
+
+test('finds the coding agent on the machine: the one in use first, then any installed; runs it by name', async () => {
+  const bin = fs.mkdtempSync(path.join(os.tmpdir(), 'spectra-agents-bin-'));
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'spectra-agents-home-'));
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'spectra-agents-root-'));
+  const fake = (name, body = 'echo "done: $*"') => {
+    fs.writeFileSync(path.join(bin, name), `#!/bin/sh\n${body}\n`);
+    fs.chmodSync(path.join(bin, name), 0o755);
+  };
+  const env = { PATH: bin };
+  assert.equal(detectAgent({ root, home, env }), null, 'nothing installed');
+  fake('codex');
+  fake('gemini');
+  assert.equal(detectAgent({ root, home, env }).id, 'codex', 'the first installed one, in the order of AGENTS');
+  fs.mkdirSync(path.join(home, '.gemini'));
+  assert.equal(detectAgent({ root, home, env }).id, 'gemini', 'the one the machine shows signs of');
+  fs.mkdirSync(path.join(root, '.codex'));
+  assert.equal(detectAgent({ root, home, env }).id, 'codex', 'the one the project shows signs of');
+  assert.equal(findExecutable('gemini', { env, home }), path.join(bin, 'gemini'));
+  assert.equal(findExecutable('claude', { env: { PATH: bin, SPECTRA_CLAUDE: '/x/claude' }, home }), '/x/claude', 'SPECTRA_CLAUDE wins');
+  fs.mkdirSync(path.join(home, '.local/bin'), { recursive: true });
+  fs.writeFileSync(path.join(home, '.local/bin/claude'), '');
+  assert.equal(findExecutable('claude', { env, home }), path.join(home, '.local/bin/claude'), "the installer's folder, off PATH");
+
+  // a named agent gets the prompt the way its CLI takes it, and its last line is the summary
+  const gemini = namedAgent('gemini', { env, home });
+  assert.equal(gemini.name, 'Gemini CLI');
+  const res = await gemini.run('Fix one thing.', { cwd: root });
+  assert.equal(res.summary, 'done: -p Fix one thing. --yolo');
+  fake('codex', 'echo "boom" >&2; exit 3');
+  await assert.rejects(namedAgent('codex', { env, home }).run('x', { cwd: root }), /Codex CLI exited with code 3: boom/);
+  await assert.rejects(namedAgent('amp', { env, home }).run('x', { cwd: root }), /could not start Amp/);
+  assert.equal(agentFromOption('./my-agent.sh').name, './my-agent.sh', 'anything else is a command');
+  assert.equal(agentFromOption('claude', { env, home }).id, 'claude');
+  assert.throws(() => namedAgent('nope'), /unknown agent "nope"/);
+  assert.deepEqual(Object.keys(AGENTS).slice(0, 3), ['claude', 'codex', 'gemini']);
+  for (const d of [bin, home, root]) fs.rmSync(d, { recursive: true, force: true });
+});