@progen-labs/spectra 0.3.0 → 0.4.1

package/README.md

@@ -14,6 +14,8 @@ and per-component render/change-detection time; source files too, where the fram
 functions. A [Progen Labs](https://github.com/progen-labs) project — open source, non-profit, no
 telemetry, no account required.
 
+**Watch the two-minute demo:** [progen-labs.github.io/website/#spectra/demo](https://progen-labs.github.io/website/#spectra/demo).
+
 **Documentation:** the full guide, with annotated screenshots of every screen, is at
 [progen-labs.github.io/website](https://progen-labs.github.io/website/#spectra/docs/introduction).
 
@@ -210,6 +212,37 @@ Tools: `profile_page`, `verify_change` (re-profile and compare against a baselin
 `--allow-remote` to lift that), runs one browser at a time, and stops Chrome and any dev server it started when a
 call is cancelled. See the [MCP guide](https://progen-labs.github.io/website/#spectra/docs/mcp-server).
 
+## The AI fix harness
+
+`spectra fix` hands the costliest findings in your own code to a coding agent, one at a time, and keeps a change only
+when your checks still pass and Spectra measures the page faster beyond run-to-run noise. Kept changes arrive as
+commits on a new branch, `spectra/fix-<time>`, for you to review; everything else is undone.
+
+```bash
+npx spectra fix                       # Claude Code (signed in) fixes up to 3 findings
+npx spectra fix --check "npm run e2e" --max-fixes 5
+npx spectra fix --agent "./my-agent.sh"   # any agent: instructions on stdin
+```
+
+The harness, not the agent, makes every decision:
+
+- **Isolation.** It works in a git worktree of your last commit, with its own dev server. Your working tree is never
+  touched, and nothing is pushed or merged.
+- **Your checks first.** Your test, type-check and build scripts (or `--check`, which can test the running app at
+  `$SPECTRA_FIX_URL`) must pass before any change and after each one. A faster page that breaks is undone.
+- **Scope rules.** A change may not touch `package.json`, lockfiles, configuration, tests or CI, delete files, or
+  exceed 150 lines.
+- **Proof.** The change is kept only if `spectra compare` says *improved* with medium or high confidence and no new
+  critical finding; with low confidence it measures again.
+- **A record.** Each kept commit carries its evidence; `.spectra/fix/<time>/report.md` summarises the session, and a
+  history skips findings that failed before. A finding that an earlier kept fix already cleared is skipped too.
+
+By default the agent is Claude Code in headless mode, allowed only to read and edit files (no shell, no web, no MCP),
+with a spending cap per finding. A test bench (`npm run bench`) checks the harness's decisions in CI: a real fix is
+kept, a "faster" change that breaks the page is caught, a cosmetic change doesn't count, and an edit to
+`package.json` is refused. With Claude Code on the demo app, it kept two of three fixes and cut JavaScript CPU time
+from 1.51 s to 82.5 ms (−95%) for $0.44. See [the AI fix harness](https://progen-labs.github.io/website/#spectra/docs/harness).
+
 ## In VS Code
 
 The Spectra extension (`vscode/`) puts results where you work: every finding in the **Problems panel** at the file
@@ -219,13 +252,15 @@ baseline** after a change, golden paths, and the dashboard inside the editor. Re
 assistant writes to `.spectra/results` appear automatically, and on VS Code 1.101+ it offers Spectra's MCP server to
 agent mode. It runs your project's Spectra (0.2.0 or later) or `npx`.
 
-Until it is listed on the VS Code Marketplace and Open VSX, build and install it from this repository:
+Install **Spectra — frontend performance** from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=progen-labs.spectra-performance), or from a terminal:
 
 ```bash
-cd vscode && npx @vscode/vsce package --no-dependencies
-code --install-extension spectra-0.1.0.vsix
+code --install-extension progen-labs.spectra-performance
 ```
 
+For Cursor, Windsurf or VSCodium (Open VSX), until it is listed there: `cd vscode && npx @vscode/vsce package
+--no-dependencies`, then install `spectra-performance-0.1.0.vsix` with **Extensions: Install from VSIX…**.
+
 See the [VS Code guide](https://progen-labs.github.io/website/#spectra/docs/vscode).
 
 ## Safe by default

package/bin/spectra.js

@@ -6,6 +6,7 @@
  *   spectra compare <before> <after>                         before vs after, noise-aware
  *   spectra reports                                          list saved reports
  *   spectra mcp [--project <dir>]                            MCP server for AI tools (stdio)
+ *   spectra fix [options]                                    the AI fix harness: fix, check, verify
  *   spectra dashboard                                        open the dashboard UI
  *   spectra --help                                           show this help
  *   spectra --version                                        print the version
@@ -43,6 +44,10 @@ Usage:
   spectra mcp [--project <dir>] [--allow-remote]
                                   Run as an MCP server (stdio) for Claude Code,
                                   Cursor, VS Code and other AI tools
+  spectra fix [options]           The AI fix harness: an agent fixes the costliest
+                                  findings in a copy of your code; a change is kept
+                                  only if your checks pass and it measures faster
+                                  (spectra fix --help for its options)
   spectra dashboard               Open the Spectra dashboard UI
   spectra --help, -h              Show this help
   spectra --version, -v           Print the version
@@ -95,6 +100,7 @@ Examples:
   spectra performance --quick --runs 5 --out before.json
   spectra performance --quick --runs 5 --out after.json
   spectra compare before.json after.json           # did the change help?
+  spectra fix --max-fixes 3                        # let an agent fix them, verified
   spectra performance --json | jq .summary         # pipe it anywhere
 `;
 
@@ -300,6 +306,14 @@ switch (command) {
       });
     break;
   }
+  case 'fix':
+    // In-process, in the user's project: the harness manages its own copy,
+    // dev server and child processes (server/fix/cli.js).
+    import('../server/fix/cli.js').catch(err => {
+      console.error(`spectra: ${err.message}`);
+      process.exit(1);
+    });
+    break;
   case 'mcp':
     // In-process: stdin/stdout are the protocol channel, and the working
     // directory stays the user's (the project, unless --project or the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@progen-labs/spectra",
-  "version": "0.3.0",
-  "description": "Spectra — a Chrome DevTools Protocol profiler that identifies the files, functions and components causing frontend slowness, across React, Vue, Svelte, Angular and Next.js builds.",
+  "version": "0.4.1",
+  "description": "Spectra \u2014 a Chrome DevTools Protocol profiler that identifies the files, functions and components causing frontend slowness, across React, Vue, Svelte, Angular and Next.js builds.",
   "type": "module",
   "bin": {
     "spectra": "bin/spectra.js"
@@ -33,7 +33,8 @@
     "demo": "vite --config fixtures/demo-app/vite.config.js",
     "profile": "node server/cli.js",
     "test": "node --test \"server/**/test-*.js\" \"action/test-*.js\"",
-    "test:vscode": "npm --prefix vscode test"
+    "test:vscode": "npm --prefix vscode test",
+    "bench": "node bench/run.mjs"
   },
   "engines": {
     "node": ">=18"

package/server/fix/agent.js

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+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 });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', d => (out += d));
+    child.stderr.on('data', d => (err += d));
+    const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+    const abort = () => child.kill('SIGTERM');
+    signal?.addEventListener('abort', abort, { once: true });
+    child.on('error', e => {
+      clearTimeout(timer);
+      reject(e.code === 'ENOENT' ? new Error(`${cmd} was not found`) : e);
+    });
+    child.on('close', code => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      resolve({ code, out, err });
+    });
+    child.stdin.end(input ?? '');
+  });
+
+/** Claude Code, headless. */
+export function claudeAgent({ bin = process.env.SPECTRA_CLAUDE || 'claude', model, budgetUsd = 2, timeoutMs = 10 * 60_000 } = {}) {
+  return {
+    name: `Claude Code${model ? ` (${model})` : ''}`,
+    async run(prompt, { cwd, signal }) {
+      const args = [
+        '-p',
+        prompt,
+        '--output-format',
+        'json',
+        '--permission-mode',
+        'acceptEdits',
+        '--allowedTools',
+        'Read Edit Write Glob Grep',
+        '--disallowedTools',
+        'Bash WebFetch WebSearch',
+        '--strict-mcp-config',
+        '--no-session-persistence',
+        '--max-budget-usd',
+        String(budgetUsd),
+        ...(model ? ['--model', model] : []),
+      ];
+      let res;
+      try {
+        res = await run(bin, args, { cwd, signal, timeoutMs });
+      } catch (err) {
+        throw new Error(`could not start Claude Code (${err.message}). Install it (https://claude.com/claude-code), set SPECTRA_CLAUDE to its path, or pass --agent "<command>".`);
+      }
+      let parsed = null;
+      try {
+        parsed = JSON.parse(res.out.trim().split('\n').pop());
+      } catch {
+        /* not JSON */
+      }
+      if (res.code !== 0 && !parsed) throw new Error(`Claude Code exited with code ${res.code}: ${(res.err || res.out).trim().split('\n').slice(-3).join(' ')}`);
+      return {
+        summary: String(parsed?.result ?? res.out).trim().split('\n').filter(Boolean).pop()?.slice(0, 300) || '',
+        costUsd: parsed?.total_cost_usd ?? null,
+        turns: parsed?.num_turns ?? null,
+        error: parsed?.is_error ? String(parsed.result || 'agent error') : null,
+      };
+    },
+  };
+}
+
+/** Any agent, as a shell command run in the copy of the project. */
+export function commandAgent(command, { timeoutMs = 10 * 60_000 } = {}) {
+  return {
+    name: command,
+    async run(prompt, { cwd, signal, finding }) {
+      const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'spectra-fix-')), 'prompt.md');
+      fs.writeFileSync(file, prompt);
+      try {
+        const res = await run(command, [], { cwd, input: prompt, signal, timeoutMs, shell: true, env: { SPECTRA_FIX_PROMPT_FILE: file, SPECTRA_FIX_FINDING: JSON.stringify(finding) } });
+        if (res.code !== 0) throw new Error(`the agent exited with code ${res.code}: ${(res.err || res.out).trim().split('\n').slice(-2).join(' ')}`);
+        return { summary: res.out.trim().split('\n').filter(Boolean).pop()?.slice(0, 300) || '', costUsd: null, turns: null, error: null };
+      } finally {
+        fs.rmSync(path.dirname(file), { recursive: true, force: true });
+      }
+    },
+  };
+}

package/server/fix/checks.js

@@ -0,0 +1,53 @@
+/**
+ * The project's own checks: the tests, type check and build that must pass
+ * after every change, so a "faster" page is never a broken one. A check can
+ * test the live app at $SPECTRA_FIX_URL.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PLACEHOLDER = /no test specified/;
+
+/** Checks from package.json scripts: test, typecheck and build. */
+export function detectChecks(projectDir) {
+  let scripts = {};
+  try {
+    scripts = JSON.parse(fs.readFileSync(path.join(projectDir, 'package.json'), 'utf8')).scripts || {};
+  } catch {
+    /* no package.json */
+  }
+  const checks = [];
+  if (scripts.test && !PLACEHOLDER.test(scripts.test)) checks.push({ name: 'npm test', cmd: 'npm test' });
+  const typecheck = ['typecheck', 'type-check', 'check-types', 'tsc'].find(s => scripts[s]);
+  if (typecheck) checks.push({ name: `npm run ${typecheck}`, cmd: `npm run ${typecheck}` });
+  if (scripts.build) checks.push({ name: 'npm run build', cmd: 'npm run build' });
+  return checks;
+}
+
+/** Run checks in order, stopping at the first failure. */
+export async function runChecks(checks, { cwd, env = {}, signal, timeoutMs = 10 * 60_000 }) {
+  const results = [];
+  for (const check of checks) {
+    const t0 = Date.now();
+    const res = await new Promise(resolve => {
+      const child = spawn(check.cmd, { cwd, shell: true, env: { ...process.env, CI: '1', FORCE_COLOR: '0', ...env }, stdio: ['ignore', 'pipe', 'pipe'] });
+      let out = '';
+      child.stdout.on('data', d => (out = (out + d).slice(-4000)));
+      child.stderr.on('data', d => (out = (out + d).slice(-4000)));
+      const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+      const abort = () => child.kill('SIGTERM');
+      signal?.addEventListener('abort', abort, { once: true });
+      child.on('error', e => resolve({ code: 127, out: e.message }));
+      child.on('close', code => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+        resolve({ code, out });
+      });
+    });
+    const result = { name: check.name, ok: res.code === 0, ms: Date.now() - t0, tail: res.out.trim().split('\n').slice(-12).join('\n') };
+    results.push(result);
+    if (!result.ok) break;
+  }
+  return results;
+}

package/server/fix/cli.js

@@ -0,0 +1,237 @@
+/**
+ * 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.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+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 { 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 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, () => {
+    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*/, '')}`);
+    });
+    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}`);
+
+  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) && !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}`);
+}
+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 shortHead() {
+  return spawnSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: repo.root, encoding: 'utf8' }).stdout.trim();
+}

package/server/fix/harness.js

@@ -0,0 +1,147 @@
+/**
+ * The loop of `spectra fix`: measure, hand one finding to an agent, check its
+ * change, measure again, and keep the change only if it measurably helped.
+ * Everything it touches is passed in (profile, compare, agent, workspace,
+ * checks), so the loop itself is tested without a browser or a model.
+ */
+import { findingKey } from '../../shared/compare.js';
+import { fixPrompt, judge, rankFindings, scopeProblem } from './policy.js';
+
+// agent errors no other finding would get past: stop instead of trying them all
+const FATAL = /not logged in|\/login|authenticat|api key|credit balance|was not found|could not start/i;
+
+/**
+ * @param {object} o
+ * @param {(label: string) => Promise<{file: string, result: object}>} o.profile
+ * @param {(before: string[], after: string[]) => Promise<object>} o.compare   spectra compare's comparison
+ * @param {{name: string, run: Function}} o.agent
+ * @param {object} o.workspace   { projectDir, exists(file), changes(), diff(), commit(files, message), undo() }
+ * @param {() => Promise<{name: string, ok: boolean}[]>} o.runChecks
+ * @param {{name: string}[]} o.checks
+ * @returns {Promise<object>} the session: baseline, attempts, overall comparison
+ */
+export async function runFix(o) {
+  const { profile, compare, agent, workspace: ws, runChecks, checks = [], log = () => {}, maxFixes = 3, maxLines = 150, history = {}, retry = false, url, signal } = o;
+  const session = { agent: agent.name, checks: checks.map(c => c.name), attempts: [], skipped: [], baseline: null, final: null, kept: 0 };
+
+  if (checks.length) {
+    log(`running the checks before any change (${checks.map(c => c.name).join(', ')}) …`);
+    const before = await runChecks();
+    const failed = before.find(r => !r.ok);
+    if (failed) throw Object.assign(new Error(`"${failed.name}" fails before any change, so it cannot tell a good fix from a bad one. Fix it first, or choose checks with --check.`), { tail: failed.tail });
+  }
+
+  log('measuring the baseline …');
+  const baseline = await profile('baseline');
+  session.baseline = { file: baseline.file, summary: baseline.result.summary, url: baseline.result.url };
+  let current = [baseline.file];
+  let present = null; // finding keys the latest kept change still measures
+
+  const { candidates, skipped } = rankFindings(baseline.result.findings, { exists: ws.exists, history, retry, max: maxFixes });
+  session.skipped = skipped.map(s => ({ title: s.finding.title, reason: s.reason }));
+  if (!candidates.length) {
+    log('no findings in your own code to fix.');
+    return session;
+  }
+  log(`${candidates.length} finding${candidates.length === 1 ? '' : 's'} to attempt, most costly first.`);
+
+  for (const [i, f] of candidates.entries()) {
+    if (signal?.aborted) break;
+    const n = `${i + 1}/${candidates.length}`;
+    if (present && !present.has(f.key)) {
+      // one fix often clears several findings (a memoised row also stops its hot file)
+      session.skipped.push({ title: f.title, reason: 'already resolved by an earlier kept change' });
+      log(`[${n}] – ${f.title}: already resolved by an earlier kept change.`);
+      continue;
+    }
+    const attempt = { finding: { title: f.title, file: f.file, line: f.line, severity: f.severity, impactMs: f.impactMs, key: f.key }, outcome: null, reason: '', changes: [] };
+    session.attempts.push(attempt);
+    const discard = (outcome, reason) => {
+      ws.undo();
+      Object.assign(attempt, { outcome, reason });
+      log(`[${n}] ✗ ${reason} — change undone.`);
+    };
+
+    log(`[${n}] ${f.title} — ${f.file}${f.line ? `:${f.line}` : ''}`);
+    log(`[${n}] asking ${agent.name} for one focused change …`);
+    const t0 = Date.now();
+    try {
+      const res = await agent.run(fixPrompt(f, { url }), { cwd: ws.projectDir, signal, finding: attempt.finding });
+      Object.assign(attempt, { summary: res.summary, costUsd: res.costUsd, agentMs: Date.now() - t0 });
+      if (res.error) throw new Error(res.error);
+    } catch (err) {
+      discard('agent-error', `the agent failed: ${err.message}`);
+      if (FATAL.test(err.message)) throw Object.assign(new Error(`${agent.name} cannot work: ${err.message}`), { session });
+      continue;
+    }
+
+    const changes = ws.changes();
+    attempt.changes = changes;
+    if (!changes.length) {
+      Object.assign(attempt, { outcome: 'no-change', reason: 'the agent made no change' });
+      log(`[${n}] – the agent made no change.`);
+      continue;
+    }
+    attempt.diff = ws.diff();
+    log(`[${n}] changed ${changes.map(c => `${c.path} (+${c.added} −${c.removed})`).join(', ')}${attempt.summary ? `: ${attempt.summary}` : ''}`);
+    const problem = scopeProblem(changes, { maxLines });
+    if (problem) {
+      discard('out-of-scope', problem);
+      continue;
+    }
+
+    if (checks.length) {
+      log(`[${n}] running the checks …`);
+      const results = await runChecks();
+      attempt.checks = results.map(r => ({ name: r.name, ok: r.ok }));
+      const failed = results.find(r => !r.ok);
+      if (failed) {
+        attempt.checkTail = failed.tail;
+        discard('checks-failed', `"${failed.name}" failed`);
+        continue;
+      }
+    }
+
+    log(`[${n}] measuring the change …`);
+    const after = [await profile(`after ${i + 1}`)];
+    let comparison = await compare(current, after.map(a => a.file));
+    let verdict = judge(comparison);
+    if (verdict.decision === 'measure-again') {
+      log(`[${n}] improved with low confidence; measuring again …`);
+      after.push(await profile(`after ${i + 1}, more runs`));
+      comparison = await compare(current, after.map(a => a.file));
+      verdict = judge(comparison);
+      if (verdict.decision === 'measure-again') verdict = { decision: 'discard', outcome: 'unproven', reason: 'not proven: still low confidence after more runs' };
+    }
+    attempt.comparison = { verdict: comparison.verdict, confidence: comparison.confidence, headlines: comparison.headlines, resolved: comparison.findings.resolved.map(x => x.title), added: comparison.findings.added.map(x => x.title) };
+    if (verdict.decision !== 'keep') {
+      discard(verdict.outcome, verdict.reason);
+      continue;
+    }
+
+    const message = [
+      `perf: ${f.title.replace(/\s+/g, ' ').slice(0, 72)}`,
+      '',
+      ...(attempt.summary ? [attempt.summary, ''] : []),
+      `Verified by spectra fix: ${comparison.verdict} (confidence: ${comparison.confidence}).`,
+      ...verdict.headlines.map(h => `- ${h}`),
+      ...(attempt.checks?.length ? [`Checks passed: ${attempt.checks.map(c => c.name).join(', ')}.`] : []),
+      `Finding: ${f.file}${f.line ? `:${f.line}` : ''}`,
+    ].join('\n');
+    attempt.commit = ws.commit(
+      changes.map(c => c.path),
+      message,
+    );
+    Object.assign(attempt, { outcome: 'kept', reason: verdict.reason });
+    session.kept++;
+    current = after.map(a => a.file);
+    present = new Set(after.flatMap(a => a.result.findings || []).map(findingKey));
+    log(`[${n}] ✓ kept (${attempt.commit}): ${verdict.reason}`);
+  }
+
+  if (session.kept) {
+    const overall = await compare([baseline.file], current);
+    session.final = { verdict: overall.verdict, confidence: overall.confidence, headlines: overall.headlines, resolved: overall.findings.resolved.map(x => x.title) };
+  }
+  return session;
+}

package/server/fix/policy.js

@@ -0,0 +1,126 @@
+/**
+ * The rules of `spectra fix`: which findings to attempt, what an agent may
+ * change, and when a change has earned its place. Pure functions, so the
+ * rules are tested on their own (test-fix.js).
+ */
+import { findingKey } from '../../shared/compare.js';
+
+const SEVERITY = { critical: 0, warning: 1 };
+
+/** A finding's source file, when it points into the project (not a dependency or a URL). */
+export function ownFile(f) {
+  const file = f.file || f.culprits?.find(c => c.file)?.file || null;
+  if (!file || /^[a-z]+:\/\//i.test(file) || /(^|\/)node_modules\//.test(file) || file.startsWith('/@') || file.startsWith('..')) return null;
+  return file.replace(/^\.\//, '');
+}
+
+/**
+ * The findings worth an attempt, most costly first: critical or warning,
+ * pointing at a file in the project, one per place in the code, and not one
+ * that failed in an earlier session (unless retry).
+ *
+ * @param {object[]} findings   brief findings from a profile result
+ * @param {object} o
+ * @param {(file: string) => boolean} o.exists
+ * @param {Record<string, {outcome: string}>} [o.history]
+ * @returns {{ candidates: object[], skipped: {finding: object, reason: string}[] }}
+ */
+export function rankFindings(findings, { exists, history = {}, retry = false, max = 3 }) {
+  const candidates = [];
+  const skipped = [];
+  const taken = new Set();
+  const ordered = [...(findings || [])].sort(
+    (a, b) => (SEVERITY[a.severity] ?? 9) - (SEVERITY[b.severity] ?? 9) || (b.impactMs || 0) - (a.impactMs || 0),
+  );
+  for (const f of ordered) {
+    if (!(f.severity in SEVERITY)) continue;
+    const file = ownFile(f);
+    if (!file || !exists(file)) continue;
+    const key = findingKey(f);
+    const spot = `${file}:${f.line ?? ''}`;
+    if (taken.has(spot) || taken.has(key)) continue;
+    const past = history[key];
+    if (past && past.outcome !== 'kept' && !retry) {
+      skipped.push({ finding: f, reason: `an earlier attempt was ${past.outcome.replace(/-/g, ' ')} (use --retry to try again)` });
+      continue;
+    }
+    taken.add(spot);
+    taken.add(key);
+    candidates.push({ ...f, file, key });
+    if (candidates.length >= max) break;
+  }
+  return { candidates, skipped };
+}
+
+// files an agent must not touch: dependencies, tooling, tests and CI
+const OFF_LIMITS = [
+  /(^|\/)package\.json$/,
+  /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?)$/,
+  /(^|\/)[^/]*\.config\.[cm]?[jt]s$/,
+  /(^|\/)tsconfig[^/]*\.json$/,
+  /(^|\/)\.(eslintrc|prettierrc|babelrc)[^/]*$/,
+  /(^|\/)spectra\.config\.json$/,
+  /(^|\/)(__tests__|__snapshots__|tests?|e2e|cypress|playwright)\//,
+  /\.(test|spec)\.[cm]?[jt]sx?$/,
+  /(^|\/)\.github\//,
+  /(^|\/)\.spectra\//,
+];
+
+/**
+ * What is wrong with a proposed change, if anything.
+ * @param {{path: string, status: string, added: number, removed: number}[]} changes
+ */
+export function scopeProblem(changes, { maxLines = 150 } = {}) {
+  if (!changes.length) return null;
+  const deleted = changes.find(c => c.status === 'D');
+  if (deleted) return `deleted ${deleted.path}`;
+  const forbidden = changes.find(c => OFF_LIMITS.some(re => re.test(c.path)));
+  if (forbidden) return `changed ${forbidden.path}, which a fix may not touch (dependencies, configuration, tests and CI are off limits)`;
+  const lines = changes.reduce((n, c) => n + c.added + c.removed, 0);
+  if (lines > maxLines) return `${lines} changed lines, more than the ${maxLines} allowed for one focused fix`;
+  return null;
+}
+
+/**
+ * Keep, discard or measure again, from spectra compare's comparison of the
+ * code before the change with the code after it.
+ */
+export function judge(c) {
+  if (!c) return { decision: 'discard', outcome: 'not-measured', reason: 'nothing to compare' };
+  const worse = c.headlines.filter(h => h.kind === 'degraded').map(h => h.text);
+  const better = c.headlines.filter(h => h.kind === 'improved').map(h => h.text);
+  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');
+  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 };
+}
+
+/** The instructions an agent gets for one finding. */
+export function fixPrompt(f, { url } = {}) {
+  const culprits = (f.culprits || [])
+    .slice(0, 5)
+    .map(c => `  - ${c.fn || '(anonymous)'}${c.file ? ` in ${c.file}${c.line ? `:${c.line}` : ''}` : ''}${c.ms ? `: ${c.ms} ms` : ''}${c.note ? ` (${c.note})` : ''}`);
+  return [
+    'Fix one frontend performance problem that Spectra, a profiler, measured in this project.',
+    '',
+    `Finding: ${f.title}`,
+    `Where: ${f.file}${f.line ? `:${f.line}` : ''}`,
+    `Cost: about ${f.impactMs} ms${f.seenIn ? `, seen in ${f.seenIn} runs` : ''}`,
+    ...(f.detail ? [`Detail: ${f.detail}`] : []),
+    ...(culprits.length ? ['Where the time went:', ...culprits] : []),
+    ...(f.fix ? [`Suggested fix: ${f.fix}`] : []),
+    '',
+    'Make ONE focused change that removes or reduces this cost.',
+    'Rules:',
+    '- Keep the behaviour exactly the same: the same output, UI and data. Never delete features, skip work the page needs, or hide content to look faster.',
+    '- Edit only the source files involved. Do not edit package.json, lockfiles, configuration, tests or CI files, and do not delete files.',
+    '- Keep the change small: a few lines to a few dozen.',
+    "- Do not run commands. Spectra runs the project's checks and measures the change after you finish.",
+    ...(url ? [`- The app is served at ${url} while you work, if you want to read it.`] : []),
+    '',
+    'When you are done, reply with one sentence that describes the change.',
+  ].join('\n');
+}

package/server/fix/report.js

@@ -0,0 +1,38 @@
+/**
+ * The session report: a Markdown summary for people (and pull requests) and
+ * the JSON behind it.
+ */
+const OUTCOME = {
+  kept: '✅ kept',
+  'no-change': '➖ no change',
+  'out-of-scope': '⛔ out of scope',
+  'checks-failed': '❌ checks failed',
+  'no-gain': '➖ no measurable gain',
+  slower: '❌ slower',
+  mixed: '⚠️ mixed',
+  'new-problem': '❌ new problem',
+  unproven: '➖ not proven',
+  'agent-error': '⚠️ agent error',
+};
+
+export function reportMarkdown(s) {
+  const lines = [
+    `## ⚡ Spectra fix: ${s.kept} of ${s.attempts.length} finding${s.attempts.length === 1 ? '' : 's'} fixed`,
+    '',
+    `Agent: ${s.agent} · checks: ${s.checks.length ? s.checks.join(', ') : 'none'} · ${s.runs} page-load runs per measurement${s.branch && s.kept ? ` · branch \`${s.branch}\`` : ''}`,
+    '',
+  ];
+  if (s.final) {
+    lines.push(`**Overall, before → after all kept fixes:** ${s.final.verdict} (confidence: ${s.final.confidence})`, '', ...s.final.headlines.map(h => `- ${h.kind === 'improved' ? '✅' : '❌'} ${h.text}`), '');
+  }
+  if (s.attempts.length) {
+    lines.push('| Finding | Where | Outcome | Why |', '| --- | --- | --- | --- |');
+    for (const a of s.attempts)
+      lines.push(`| ${a.finding.title.replace(/\|/g, '\\|')} | \`${a.finding.file}${a.finding.line ? `:${a.finding.line}` : ''}\` | ${OUTCOME[a.outcome] || a.outcome}${a.commit ? ` (${a.commit})` : ''} | ${(a.reason || '').replace(/\|/g, '\\|')} |`);
+    lines.push('');
+  }
+  for (const a of s.attempts.filter(x => x.summary)) lines.push(`- **${a.finding.title}**: ${a.summary}`);
+  if (s.skipped.length) lines.push('', 'Skipped:', ...s.skipped.map(x => `- ${x.title}: ${x.reason}`));
+  lines.push('', '<sub>Every kept change passed the checks and measured faster beyond run-to-run noise. Review it like any other change.</sub>');
+  return `${lines.join('\n')}\n`;
+}

package/server/fix/test-fix.js

@@ -0,0 +1,227 @@
+// The AI fix harness without a browser or a model: its rules, its loop with
+// fake measurements and agents, and its git copy in a throwaway repository.
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+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 { detectChecks } from './checks.js';
+import { runFix } from './harness.js';
+import { fixPrompt, judge, rankFindings, scopeProblem } from './policy.js';
+import { reportMarkdown } from './report.js';
+import { changesIn, commitChange, commitsOn, createWorkspace, ignoreSpectra, removeWorkspace, repoOf, uncommitted, undoChanges } from './workspace.js';
+
+const finding = (id, extra = {}) => ({ id, severity: 'critical', title: `${id} is slow`, impactMs: 500, file: 'src/Row.jsx', line: 3, fix: 'memoize it', culprits: [{ fn: 'Row', file: 'src/Row.jsx', line: 3, ms: 500 }], ...extra });
+const comparison = (verdict, confidence = 'medium', extra = {}) => ({
+  verdict,
+  confidence,
+  headlines: verdict === 'improved' ? [{ kind: 'improved', text: 'JavaScript CPU time: 1.55 s → 107 ms (−93%)' }] : verdict === 'neutral' ? [] : [{ kind: 'degraded', text: 'Total blocking time: 0 ms → 300 ms' }],
+  findings: { added: [], resolved: [], persisting: [], ...extra },
+});
+
+test('ranks own-code findings, most costly first, one per place', () => {
+  const findings = [
+    finding('row-render', { impactMs: 1441 }),
+    finding('row-count', { impactMs: 1440, title: 'Row rendered 7200×' }), // same file and line
+    finding('heavy', { file: 'src/heavy.js', line: 2, impactMs: 1425, culprits: [{ fn: 'burn', file: 'src/heavy.js', line: 2 }] }),
+    finding('bundle', { file: 'node_modules/react-dom/index.js', impactMs: 600 }),
+    finding('note', { severity: 'info', file: 'src/App.jsx' }),
+    finding('gone', { file: 'src/Deleted.jsx' }),
+  ];
+  const exists = f => !f.includes('Deleted');
+  const { candidates } = rankFindings(findings, { exists, max: 5 });
+  assert.deepEqual(candidates.map(c => c.id), ['row-render', 'heavy']);
+  const again = rankFindings(findings, { exists, history: { 'row-render': { outcome: 'checks-failed' } } });
+  assert.deepEqual(again.candidates.map(c => c.id), ['row-count', 'heavy'], 'a failed finding is skipped, so the next one at that line gets its chance');
+  assert.match(again.skipped[0].reason, /checks failed/);
+  assert.deepEqual(rankFindings(findings, { exists, history: { 'row-render': { outcome: 'checks-failed' } }, retry: true }).candidates[0].id, 'row-render');
+});
+
+test('keeps changes inside the source, small, and without deleting files', () => {
+  const src = (p, added = 3, removed = 1, status = 'M') => ({ path: p, status, added, removed });
+  assert.equal(scopeProblem([src('src/Row.jsx')]), null);
+  assert.match(scopeProblem([src('package.json')]), /may not touch/);
+  assert.match(scopeProblem([src('pnpm-lock.yaml')]), /may not touch/);
+  assert.match(scopeProblem([src('src/Row.test.jsx')]), /may not touch/);
+  assert.match(scopeProblem([src('vite.config.js')]), /may not touch/);
+  assert.match(scopeProblem([src('src/Row.jsx', 0, 9, 'D')]), /deleted/);
+  assert.match(scopeProblem([src('src/Row.jsx', 200, 10)]), /more than the 150/);
+});
+
+test('judges a change from the comparison', () => {
+  assert.equal(judge(comparison('improved')).decision, 'keep');
+  assert.equal(judge(comparison('improved', 'high')).decision, 'keep');
+  assert.equal(judge(comparison('improved', 'low')).decision, 'measure-again');
+  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');
+});
+
+test('tells the agent the finding and the rules', () => {
+  const p = fixPrompt(finding('row'), { url: 'http://localhost:5199' });
+  assert.match(p, /row is slow/);
+  assert.match(p, /src\/Row\.jsx:3/);
+  assert.match(p, /Keep the behaviour exactly the same/);
+  assert.match(p, /Do not run commands/);
+  assert.match(p, /localhost:5199/);
+});
+
+// --- the loop, with fakes
+const bothFindings = () => [finding('row-render'), finding('heavy', { file: 'src/heavy.js', line: 2, culprits: [] })];
+function fakes({ agentChanges, checks = [true, true, true, true], verdicts, measured = bothFindings }) {
+  const calls = { commits: [], undos: 0, profiles: 0, compares: [] };
+  let pending = [];
+  let checkRun = 0;
+  let verdictRun = 0;
+  const workspace = {
+    projectDir: '/tmp/project',
+    exists: () => true,
+    changes: () => pending,
+    diff: () => 'diff',
+    commit: (files, message) => (calls.commits.push({ files, message }), (pending = []), 'abc1234'),
+    undo: () => ((pending = []), calls.undos++),
+  };
+  let agentRun = 0;
+  return {
+    calls,
+    options: {
+      agent: { name: 'fake', run: async () => ((pending = agentChanges[agentRun++] || []), { summary: 'memoized the work' }) },
+      workspace,
+      checks: [{ name: 'npm test' }],
+      runChecks: async () => [{ name: 'npm test', ok: checks[checkRun++] ?? true, tail: 'expected 120 rows' }],
+      profile: async label => ((calls.profiles++), { file: `${label}.json`, result: { url: 'http://localhost:5199', summary: {}, findings: measured(label) } }),
+      compare: async (before, after) => (calls.compares.push([before, after]), verdicts[verdictRun++] || comparison('neutral')),
+    },
+  };
+}
+const edit = [{ path: 'src/Row.jsx', status: 'M', added: 2, removed: 1 }];
+
+test('keeps a change that passes the checks and measures faster, and builds on it', async () => {
+  const { calls, options } = fakes({ agentChanges: [edit, edit], verdicts: [comparison('improved'), comparison('neutral'), comparison('improved')] });
+  const s = await runFix(options);
+  assert.deepEqual(s.attempts.map(a => a.outcome), ['kept', 'no-gain']);
+  assert.equal(s.kept, 1);
+  assert.equal(calls.commits.length, 1);
+  assert.match(calls.commits[0].message, /^perf: row-render is slow/);
+  assert.match(calls.commits[0].message, /Verified by spectra fix: improved \(confidence: medium\)/);
+  assert.deepEqual(calls.compares[1], [['after 1.json'], ['after 2.json']], 'the second fix is measured against the first');
+  assert.deepEqual(calls.compares[2], [['baseline.json'], ['after 1.json']], 'the overall comparison starts from the baseline');
+  assert.equal(s.final.verdict, 'improved');
+  assert.match(reportMarkdown({ ...s, runs: 3, branch: 'spectra/fix-x' }), /1 of 2 findings fixed/);
+});
+
+test('skips a finding that an earlier kept change already resolved', async () => {
+  // the memoised row also stops the hot file: after the first fix, neither is measured
+  const measured = label => (label === 'baseline' ? bothFindings() : []);
+  const { calls, options } = fakes({ agentChanges: [edit, edit], verdicts: [comparison('improved'), comparison('improved')], measured });
+  let asked = 0;
+  const run = options.agent.run;
+  options.agent.run = (...a) => (asked++, run(...a));
+  const s = await runFix(options);
+  assert.equal(asked, 1, 'the agent is not asked about the resolved finding');
+  assert.deepEqual(s.attempts.map(a => a.outcome), ['kept']);
+  assert.deepEqual(s.skipped, [{ title: 'heavy is slow', reason: 'already resolved by an earlier kept change' }]);
+  assert.equal(calls.profiles, 2, 'baseline and one measurement');
+  assert.match(reportMarkdown({ ...s, runs: 3, branch: 'spectra/fix-x' }), /heavy is slow: already resolved by an earlier kept change/);
+});
+
+test('undoes a change whose checks fail, without measuring it', async () => {
+  const { calls, options } = fakes({ agentChanges: [edit], checks: [true, false], verdicts: [] });
+  options.workspace.exists = f => f === 'src/Row.jsx';
+  const s = await runFix(options);
+  assert.equal(s.attempts[0].outcome, 'checks-failed');
+  assert.equal(calls.undos, 1);
+  assert.equal(calls.profiles, 1, 'only the baseline was measured');
+  assert.equal(calls.commits.length, 0);
+});
+
+test('refuses to start when a check fails before any change', async () => {
+  const { options } = fakes({ agentChanges: [], checks: [false], verdicts: [] });
+  await assert.rejects(runFix(options), /fails before any change/);
+});
+
+test('undoes out-of-scope and empty changes', async () => {
+  const { calls, options } = fakes({ agentChanges: [[{ path: 'package.json', status: 'M', added: 1, removed: 1 }], []], verdicts: [] });
+  const s = await runFix(options);
+  assert.deepEqual(s.attempts.map(a => a.outcome), ['out-of-scope', 'no-change']);
+  assert.equal(calls.undos, 1);
+});
+
+test('stops at once when the agent cannot work at all', async () => {
+  const { options } = fakes({ agentChanges: [], verdicts: [] });
+  let runs = 0;
+  options.agent = { name: 'Claude Code', run: async () => (runs++, { summary: '', error: 'Not logged in · Please run /login' }) };
+  await assert.rejects(runFix(options), /Claude Code cannot work: Not logged in/);
+  assert.equal(runs, 1, 'no other finding was tried');
+});
+
+test('measures again when the gain has low confidence', async () => {
+  const kept = fakes({ agentChanges: [edit], verdicts: [comparison('improved', 'low'), comparison('improved', 'medium'), comparison('improved')] });
+  kept.options.workspace.exists = f => f === 'src/Row.jsx';
+  const s = await runFix(kept.options);
+  assert.equal(s.attempts[0].outcome, 'kept');
+  assert.deepEqual(kept.calls.compares[1], [['baseline.json'], ['after 1.json', 'after 1, more runs.json']]);
+  const unproven = fakes({ agentChanges: [edit], verdicts: [comparison('improved', 'low'), comparison('improved', 'low')] });
+  unproven.options.workspace.exists = f => f === 'src/Row.jsx';
+  assert.equal((await runFix(unproven.options)).attempts[0].outcome, 'unproven');
+});
+
+// --- the git copy, in a throwaway repository
+const sh = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+function repo() {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'spectra-fix-test-')));
+  sh(dir, 'init', '-q', '-b', 'main');
+  fs.mkdirSync(path.join(dir, 'app/src'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'app/node_modules/dep'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'app/src/Row.jsx'), 'export const Row = () => null;\n');
+  fs.writeFileSync(path.join(dir, 'app/package.json'), JSON.stringify({ scripts: { test: 'echo "Error: no test specified" && exit 1', build: 'vite build', typecheck: 'tsc' } }));
+  fs.writeFileSync(path.join(dir, '.gitignore'), 'node_modules\n');
+  sh(dir, 'add', '-A');
+  sh(dir, '-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '-m', 'init');
+  return dir;
+}
+
+test('works in a git copy: links dependencies, commits kept changes, undoes the rest', () => {
+  const root = repo();
+  const { root: r, sub } = repoOf(path.join(root, 'app'));
+  assert.equal(r, root);
+  assert.equal(sub, 'app');
+  ignoreSpectra(root);
+  fs.mkdirSync(path.join(root, 'app/.spectra/fix'), { recursive: true });
+  assert.deepEqual(uncommitted(root), [], '.spectra is ignored');
+
+  const ws = createWorkspace({ root, sub, dir: path.join(root, 'app/.spectra/fix/s1/worktree'), branch: 'spectra/fix-test' });
+  assert.ok(fs.lstatSync(path.join(ws.projectDir, 'node_modules')).isSymbolicLink());
+
+  fs.writeFileSync(path.join(ws.projectDir, 'src/Row.jsx'), 'export const Row = () => null; // faster\n');
+  fs.writeFileSync(path.join(ws.projectDir, 'src/cache.js'), 'export const cache = new Map();\n');
+  const changes = changesIn(ws);
+  assert.deepEqual(changes.map(c => [c.path, c.status]).sort(), [['src/Row.jsx', 'M'], ['src/cache.js', 'A']]);
+  commitChange(ws, changes.map(c => c.path), 'perf: test');
+  assert.equal(commitsOn(root, 'spectra/fix-test'), 1);
+
+  fs.writeFileSync(path.join(ws.projectDir, 'src/Row.jsx'), 'broken');
+  fs.writeFileSync(path.join(ws.projectDir, 'src/junk.js'), 'junk');
+  undoChanges(ws);
+  assert.deepEqual(changesIn(ws), []);
+  assert.ok(fs.existsSync(path.join(ws.projectDir, 'node_modules')), 'the dependency link survives an undo');
+  assert.equal(fs.readFileSync(path.join(root, 'app/src/Row.jsx'), 'utf8'), 'export const Row = () => null;\n', 'the user\'s files never change');
+
+  removeWorkspace(root, ws, { keepBranch: true });
+  assert.ok(!fs.existsSync(ws.dir));
+  assert.equal(commitsOn(root, 'spectra/fix-test'), 1, 'the branch with the fix stays');
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test('finds checks in package.json and runs any agent command', async () => {
+  const root = repo();
+  assert.deepEqual(detectChecks(path.join(root, 'app')).map(c => c.cmd), ['npm run typecheck', 'npm run build'], 'the npm placeholder test is not a check');
+  const agent = commandAgent(`node -e "const fs=require('fs');const p=fs.readFileSync(process.env.SPECTRA_FIX_PROMPT_FILE,'utf8');fs.writeFileSync('src/Row.jsx','// '+p.split('\\n')[2]+'\\n');console.log('rewrote Row')"`);
+  const res = await agent.run('Fix it.\n\nFinding: Row is slow', { cwd: path.join(root, 'app'), finding: {} });
+  assert.equal(res.summary, 'rewrote Row');
+  assert.equal(fs.readFileSync(path.join(root, 'app/src/Row.jsx'), 'utf8'), '// Finding: Row is slow\n');
+  fs.rmSync(root, { recursive: true, force: true });
+});

package/server/fix/workspace.js

@@ -0,0 +1,130 @@
+/**
+ * The isolated copy `spectra fix` works in: a git worktree of the last commit
+ * on its own branch, inside .spectra/fix/<session>/ (which git is told to
+ * ignore). Every attempt is either committed on that branch or undone, so a
+ * failed attempt never reaches the user's working tree.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const gitRaw = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+const git = (cwd, args) => gitRaw(cwd, args).trim();
+const tryGit = (cwd, args) => {
+  try {
+    return git(cwd, args);
+  } catch {
+    return null;
+  }
+};
+
+/** The repository around `dir`, and where the project sits inside it. */
+export function repoOf(dir) {
+  const root = tryGit(dir, ['rev-parse', '--show-toplevel']);
+  if (!root) throw new Error('spectra fix needs a git repository: it works on a copy of your last commit.');
+  const real = fs.realpathSync(dir);
+  return { root: fs.realpathSync(root), sub: path.relative(fs.realpathSync(root), real) };
+}
+
+/** Uncommitted changes in the project (other than Spectra's own files). */
+export function uncommitted(root) {
+  return gitRaw(root, ['status', '--porcelain', '--untracked-files=normal'])
+    .split('\n')
+    .filter(Boolean)
+    .filter(l => !/(^|\/)\.spectra(\/|$)/.test(l.slice(3)));
+}
+
+/** Tell git, locally, to ignore .spectra/ so the session never shows up as a change. */
+export function ignoreSpectra(root) {
+  const file = path.resolve(root, git(root, ['rev-parse', '--git-path', 'info/exclude']));
+  const now = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  if (!now.split('\n').some(l => l.trim() === '.spectra/' || l.trim() === '.spectra')) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${now && !now.endsWith('\n') ? '\n' : ''}.spectra/\n`);
+  }
+}
+
+/**
+ * A worktree of HEAD on a new branch, with the project's dependencies linked
+ * in (or installed fresh, with install).
+ */
+export function createWorkspace({ root, sub, dir, branch, install = false, log = () => {} }) {
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  git(root, ['worktree', 'add', '-q', '-b', branch, dir, 'HEAD']);
+  const projectDir = path.join(dir, sub);
+  if (install) {
+    const lock = f => fs.existsSync(path.join(projectDir, f));
+    const [cmd, ...args] = lock('pnpm-lock.yaml') ? ['pnpm', 'install', '--frozen-lockfile'] : lock('yarn.lock') ? ['yarn', 'install', '--frozen-lockfile'] : lock('package-lock.json') ? ['npm', 'ci'] : ['npm', 'install'];
+    log(`installing dependencies in the copy (${cmd} ${args.join(' ')}) …`);
+    const r = spawnSync(cmd, args, { cwd: projectDir, stdio: 'ignore', shell: process.platform === 'win32' });
+    if (r.status !== 0) throw new Error(`${cmd} ${args.join(' ')} failed in the copy.`);
+  } else {
+    // node_modules of the project and of the repository root (hoisted workspaces)
+    for (const rel of new Set([sub, ''])) {
+      const from = path.join(root, rel, 'node_modules');
+      const to = path.join(dir, rel, 'node_modules');
+      if (fs.existsSync(from) && !fs.existsSync(to)) fs.symlinkSync(from, to, process.platform === 'win32' ? 'junction' : 'dir');
+    }
+  }
+  return { dir, projectDir, branch };
+}
+
+/** What the agent changed: [{ path, status, added, removed }], paths relative to the project. */
+export function changesIn(ws) {
+  const status = gitRaw(ws.projectDir, ['status', '--porcelain', '--untracked-files=all', '--', '.'])
+    .split('\n')
+    .filter(Boolean)
+    .map(l => ({ status: l.slice(0, 2).trim()[0] === '?' ? 'A' : l.slice(0, 2).trim()[0], file: l.slice(3).replace(/^"|"$/g, '') }))
+    .filter(c => !/(^|\/)node_modules$/.test(c.file));
+  const counts = new Map(
+    git(ws.projectDir, ['diff', '--numstat', 'HEAD', '--', '.'])
+      .split('\n')
+      .filter(Boolean)
+      .map(l => {
+        const [a, r, f] = l.split('\t');
+        return [f, { added: Number(a) || 0, removed: Number(r) || 0 }];
+      }),
+  );
+  const prefix = git(ws.projectDir, ['rev-parse', '--show-prefix']);
+  return status.map(c => {
+    const rel = c.file.startsWith(prefix) ? c.file.slice(prefix.length) : c.file;
+    const n = counts.get(c.file) || (c.status === 'A' ? { added: lineCount(path.join(ws.dir, c.file)), removed: 0 } : { added: 0, removed: 0 });
+    return { path: rel, status: c.status, ...n };
+  });
+}
+const lineCount = file => {
+  try {
+    return fs.readFileSync(file, 'utf8').split('\n').length;
+  } catch {
+    return 0;
+  }
+};
+
+/** The diff of the files a change touched, for the report. */
+export const diffOf = ws => git(ws.projectDir, ['diff', 'HEAD', '--', '.']);
+
+/** Commit exactly these files on the session branch. */
+export function commitChange(ws, files, message) {
+  git(ws.projectDir, ['add', '--', ...files]);
+  const named = tryGit(ws.dir, ['config', 'user.email']);
+  const who = named ? [] : ['-c', 'user.name=Spectra fix', '-c', 'user.email=spectra-fix@localhost'];
+  git(ws.dir, [...who, 'commit', '-q', '-m', message]);
+  undoChanges(ws); // anything the checks left behind
+  return git(ws.dir, ['rev-parse', '--short', 'HEAD']);
+}
+
+/** Undo everything since the last commit (the dependency link stays). */
+export function undoChanges(ws) {
+  git(ws.dir, ['reset', '-q', '--hard']);
+  git(ws.dir, ['clean', '-fdq', '-e', 'node_modules']);
+}
+
+/** Remove the copy; keep the branch only if it holds fixes. */
+export function removeWorkspace(root, ws, { keepBranch }) {
+  tryGit(root, ['worktree', 'remove', '--force', ws.dir]);
+  if (fs.existsSync(ws.dir)) fs.rmSync(ws.dir, { recursive: true, force: true });
+  tryGit(root, ['worktree', 'prune']);
+  if (!keepBranch) tryGit(root, ['branch', '-D', ws.branch]);
+}
+
+export const commitsOn = (root, branch) => Number(tryGit(root, ['rev-list', '--count', `HEAD..${branch}`]) || 0);