@progen-labs/spectra 0.6.0 → 0.7.0

package/server/improve/cli.js

@@ -0,0 +1,304 @@
+/**
+ * spectra improve — make the app faster. Two ways, with the same rules:
+ *
+ *   spectra improve             unattended: a coding agent on this machine makes
+ *                               the changes in a copy of the project, and only
+ *                               what passes the checks and measures faster is
+ *                               kept, as commits on a new branch (../fix/)
+ *   spectra improve next        guided: Spectra measures and names the next
+ *   spectra improve check       problem; an AI agent (or you) changes the code in
+ *   spectra improve report      the working tree; Spectra measures the change and
+ *   spectra improve stop        says whether to keep it (./session.js)
+ *
+ * Without an agent on the machine, `spectra improve` starts a guided session.
+ */
+import { spawn } 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 { EXIT, SPECTRA_VERSION, exitAfterFlush } from '../output.js';
+import { AGENT_IDS, agentFromOption, detectAgent } from '../fix/agent.js';
+import { detectChecks, runChecks } from '../fix/checks.js';
+import { ignoreSpectra, repoOf } from '../fix/workspace.js';
+import { checkTask, checkText, nextTask, overall, reportMarkdown, reportText, startSession, taskText } from './session.js';
+import { RESULT_SCHEMA_VERSION } from '../../shared/result.js';
+
+const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/spectra.js');
+const STEPS = ['next', 'check', 'report', 'stop'];
+const VALUES = ['url', 'runs', 'max-fixes', 'check', 'command', 'boot-timeout', 'config', 'login-url', 'login-user', 'login', 'throttle', 'agent', 'model', 'max-budget-usd', 'branch', 'max-lines', 'out'];
+// options the profiling runs take as they are (how to reach the page, and how to sign in)
+const PASS_THROUGH = ['config', 'login-url', 'login-user', 'login', 'throttle'];
+
+export const HELP = `usage: spectra improve [options]
+       spectra improve next | check | report | stop [options]
+
+Makes the app faster: measures it, finds the problems in your own code, has
+each one fixed, measures again, and keeps only what measurably helped.
+
+Unattended (spectra improve): a coding agent on this machine makes the
+changes in a copy of your last commit. Kept fixes are commits on a new
+branch, for you to review. Spectra finds the agent by itself
+(${AGENT_IDS.join(', ')}), or take --agent.
+
+Guided (next, check, report, stop): for the AI agent you are talking to, or
+for you. "next" measures and names the next problem; after the change,
+"check" measures it and says whether to keep it, then names the next one;
+"report" sums up; "stop" ends the session.
+
+  --url <page>            The page to make faster (default: the dev server's home page,
+                          started and stopped by Spectra)
+  --max-fixes <n>         Problems to attempt (default 3 unattended, 5 guided)
+  --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)
+  --command "<cmd>"       The dev-server command (default: your npm dev script)
+  --boot-timeout <s>      How long to wait for the dev server (default 60)
+  --login-url, --login-user, --login <method>, --config <file>
+                          Sign in first, as for spectra performance
+  --json, --out <file>    Machine-readable output
+
+unattended only:
+  --agent <name|"cmd">    ${AGENT_IDS.join(', ')}, or your own
+                          command (it gets the instructions on stdin)
+  --model <name>          Model for Claude Code
+  --max-budget-usd <n>    Claude Code's spending cap per finding (default 2)
+  --install               Install dependencies in the copy instead of linking yours
+  --branch <name>         Branch for the fixes (default spectra/improve-<time>)
+  --max-lines <n>         Largest change accepted (default 150 lines)
+  --retry                 Try problems that failed in an earlier session
+  --keep-worktree         Keep the copy in .spectra/improve/ for inspection
+
+guided only:
+  --restart               End the current session and start over (with next)`;
+
+export async function runImproveCli(argv) {
+  const { opt, flag, positionals } = parseArgs(argv, { values: VALUES });
+  if (flag('help') || flag('h')) {
+    console.log(HELP);
+    return EXIT.OK;
+  }
+  const step = positionals.find(p => STEPS.includes(p));
+  if (positionals.length && !step) {
+    console.error(`spectra: improve takes one of ${STEPS.join(', ')} (got "${positionals[0]}"). See spectra improve --help.`);
+    return EXIT.ERROR;
+  }
+  if (step) return guided(step, argv, { opt, flag });
+
+  // unattended, with the agent named or found; without one, the guided mode's first step
+  const agentOpts = { model: opt('model') === true ? undefined : opt('model'), budgetUsd: Number(opt('max-budget-usd') ?? 2) };
+  let agent = null;
+  try {
+    agent = opt('agent') ? agentFromOption(String(opt('agent')), agentOpts) : (found => found && agentFromOption(found.id, { ...agentOpts, bin: found.bin }))(detectAgent());
+  } catch (err) {
+    console.error(`spectra: ${err.message}`);
+    return EXIT.ERROR;
+  }
+  if (agent) {
+    const { runFixCli } = await import('../fix/cli.js');
+    return runFixCli(argv, { agent });
+  }
+  console.error(`spectra: no coding agent found on this machine (${AGENT_IDS.join(', ')}), so Spectra cannot make the changes unattended.`);
+  console.error('spectra: starting a guided session instead: ask your AI agent to "improve the performance", or make each change yourself.\n');
+  return guided('next', argv, { opt, flag });
+}
+
+// ------------------------------------------------------------------ guided
+
+const stamp = () => new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '-');
+
+async function guided(step, argv, { opt, flag }) {
+  const json = flag('json');
+  const log = json ? console.error : console.log; // with --json, stdout carries only the result
+  const status = line => console.error(`spectra: ${line}`);
+  const projectDir = process.cwd();
+  const root = path.join(projectDir, '.spectra', 'improve');
+  const currentFile = path.join(root, 'current.json');
+  const historyFile = path.join(root, 'history.json');
+  const readJson = (file, fallback) => {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      return fallback;
+    }
+  };
+  const save = session => fs.writeFileSync(currentFile, `${JSON.stringify(session, null, 2)}\n`);
+  try {
+    ignoreSpectra(repoOf(projectDir).root);
+  } catch {
+    /* not a git repository: fine for the guided mode */
+  }
+
+  let runs;
+  let maxFixes;
+  try {
+    runs = intOption(opt('runs'), 'runs', { min: 1, max: 10, fallback: 3 });
+    maxFixes = intOption(opt('max-fixes'), 'max-fixes', { min: 1, max: 20, fallback: 5 });
+  } catch (err) {
+    console.error(`spectra: ${err.message}`);
+    return EXIT.ERROR;
+  }
+
+  let session = readJson(currentFile, null);
+  if (step === 'next' && flag('restart') && session) {
+    await finish(session, { archive: true });
+    session = null;
+  }
+
+  // the result for --json / --out, and the text for people and agents
+  const emit = (message, extra = {}) => {
+    log(message);
+    const result = { schemaVersion: RESULT_SCHEMA_VERSION, kind: 'improve', spectraVersion: SPECTRA_VERSION, createdAt: new Date().toISOString(), step, message, ...extra, session };
+    if (opt('out') && typeof opt('out') === 'string') fs.writeFileSync(path.resolve(opt('out')), `${JSON.stringify(result, null, 2)}\n`);
+    if (json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  };
+  const total = s => s.attempts.length + (s.task ? 1 : 0) + s.queue.length;
+
+  // ---- the dev server, for the commands that measure
+  const active = { server: null, child: null };
+  const stopServer = async () => {
+    const s = active.server;
+    active.server = null;
+    if (s) {
+      await s.stop().catch(() => {});
+      status('stopped the dev server.');
+    }
+  };
+  for (const signal of ['SIGINT', 'SIGTERM'])
+    process.on(signal, () => {
+      active.child?.kill('SIGTERM');
+      stopServer().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
+    });
+  const pageUrl = async s => {
+    if (s.fixedUrl) return s.fixedUrl;
+    if (!active.server) {
+      const command = s.command || (typeof opt('command') === 'string' ? opt('command') : undefined);
+      status(`starting the dev server in ${projectDir}${command ? ` (${command})` : ''} …`);
+      active.server = await bootDevServer({ root: projectDir, command, timeoutMs: (Number(s.bootTimeout || opt('boot-timeout')) || 60) * 1000 });
+      status(`dev server ready at ${active.server.url}`);
+    }
+    return active.server.url;
+  };
+
+  /** `spectra <args> --json`, in the project; resolves with the parsed result. */
+  const spectra = (args, dir) =>
+    new Promise((resolve, reject) => {
+      active.child = spawn(process.execPath, [BIN, ...args, '--json'], {
+        cwd: projectDir,
+        env: { ...process.env, PERF_FRONTEND_DIR: projectDir, PERF_REPORTS_DIR: path.join(dir, 'reports') },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      let out = '';
+      let err = '';
+      active.child.stdout.on('data', d => (out += d));
+      active.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*/, '')}`);
+      });
+      active.child.on('error', reject);
+      active.child.on('close', code => {
+        active.child = null;
+        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 passThrough = s => s.profileArgs || [];
+  const deps = s => ({
+    profile: async label => {
+      const url = await pageUrl(s);
+      const file = path.join(s.dir, 'results', `${label.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}-${Date.now()}.json`);
+      const result = await spectra(['performance', '--quick', '--runs', String(s.runs), '--url', url, ...passThrough(s), '--out', file], s.dir);
+      return { file, result };
+    },
+    compare: async (before, after) => (await spectra(['compare', before.join(','), after.join(',')], s.dir)).comparison,
+    runChecks: s.checkCommands?.length
+      ? async () => runChecks(s.checkCommands, { cwd: projectDir, env: { SPECTRA_FIX_URL: await pageUrl(s) } })
+      : null,
+    log: status,
+  });
+
+  async function finish(s, { archive }) {
+    const result = await overall(s, deps(s).compare).catch(() => null);
+    fs.writeFileSync(path.join(s.dir, 'report.md'), reportMarkdown(s, result));
+    fs.writeFileSync(path.join(s.dir, 'session.json'), `${JSON.stringify(s, null, 2)}\n`);
+    if (archive) fs.rmSync(currentFile, { force: true });
+    return result;
+  }
+  const remember = s => {
+    const history = readJson(historyFile, {});
+    for (const a of s.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`);
+  };
+
+  try {
+    if (step === 'next') {
+      if (!session) {
+        const dir = path.join(root, stamp());
+        fs.mkdirSync(path.join(dir, 'results'), { recursive: true });
+        // the checks: --check, or the project's own; none is allowed here, the measurements then decide alone
+        let checkCommands = [];
+        for (let i = 0; i < argv.length; i++) if (argv[i] === '--check' && argv[i + 1]) checkCommands.push({ name: argv[i + 1], cmd: argv[++i] });
+        if (!checkCommands.length && !flag('no-checks')) checkCommands = detectChecks(projectDir);
+        const meta = {
+          id: path.basename(dir),
+          dir,
+          runs,
+          fixedUrl: typeof opt('url') === 'string' ? opt('url') : null,
+          command: typeof opt('command') === 'string' ? opt('command') : null,
+          bootTimeout: Number(opt('boot-timeout')) || null,
+          profileArgs: PASS_THROUGH.flatMap(name => (typeof opt(name) === 'string' ? [`--${name}`, name === 'config' ? path.resolve(opt(name)) : opt(name)] : [])),
+          checkCommands,
+        };
+        status(`measuring the baseline (${runs} page loads) …`);
+        session = await startSession({ ...deps(meta), exists: f => fs.existsSync(path.join(projectDir, f)), history: readJson(historyFile, {}), retry: flag('retry'), maxFixes, checks: checkCommands, meta });
+        if (!checkCommands.length) status('no checks found (no test, typecheck or build script): the measurements decide alone.');
+      }
+      const task = nextTask(session);
+      save(session);
+      if (!task) {
+        const result = await finish(session, { archive: false });
+        emit(`${reportText(session, result)}\n\nNothing left to try in this session. Run:  npx spectra improve next --restart  to measure again from the start.`, { task: null, result });
+      } else emit(taskText(task, { total: total(session) }), { task });
+    } else if (step === 'check') {
+      if (!session) throw new Error('no session: run `npx spectra improve next` first.');
+      const { attempt, next } = await checkTask(session, deps(session));
+      save(session);
+      remember(session);
+      emit(checkText(attempt, next, { total: total(session) }), { attempt, task: next });
+    } else if (step === 'report') {
+      if (!session) throw new Error('no session: run `npx spectra improve next` first.');
+      const result = await finish(session, { archive: false });
+      emit(`${reportText(session, result)}\n\nReport: ${path.relative(projectDir, path.join(session.dir, 'report.md'))}`, { result });
+    } else {
+      if (!session) throw new Error('no session to stop.');
+      const result = await finish(session, { archive: true });
+      remember(session);
+      emit(`${reportText(session, result)}\n\nSession ended. Report: ${path.relative(projectDir, path.join(session.dir, 'report.md'))}`, { result });
+    }
+  } catch (err) {
+    console.error(`spectra: ${err.message}`);
+    await stopServer();
+    return EXIT.ERROR;
+  }
+  await stopServer();
+  return EXIT.OK;
+}
+
+/** Entry point for bin/spectra.js: runs, then exits once stdout is flushed. */
+export async function main(argv) {
+  let code = EXIT.ERROR;
+  try {
+    code = await runImproveCli(argv);
+  } catch (err) {
+    console.error(`spectra: ${err.message}`);
+  }
+  exitAfterFlush(code);
+}

package/server/improve/session.js

@@ -0,0 +1,188 @@
+/**
+ * The guided mode of `spectra improve`: Spectra measures and decides, and
+ * whoever is at the keyboard (an AI agent, or a person) edits the code in the
+ * working tree.
+ *
+ *   next     measure, when nothing is measured yet; then the next problem to fix
+ *   check    measure the change just made: kept, or to be undone; then the next problem
+ *   report   what has happened so far
+ *   stop     end the session
+ *
+ * The session is a JSON file, so each command is one short run and the state
+ * survives between them. Everything that measures, compares or runs checks is
+ * passed in, so the logic is tested without a browser (test-improve.js). The
+ * rules (which findings, when a change is kept) are the unattended mode's,
+ * from ../fix/policy.js, so both modes decide the same way.
+ */
+import { findingKey } from '../../shared/compare.js';
+import { judge, rankFindings } from '../fix/policy.js';
+
+export const SESSION_VERSION = 1;
+
+const where = f => `${f.file}${f.line ? `:${f.line}` : ''}`;
+const ms = v => (v == null ? '—' : v >= 1000 ? `${(v / 1000).toFixed(2)} s` : `${Math.round(v)} ms`);
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+/**
+ * Starts a session: measures the baseline and queues the problems worth a
+ * try. `o.profile(label)` resolves with { file, result }; `o.exists(file)`
+ * says whether a finding's file is in the project.
+ */
+export async function startSession(o) {
+  const { profile, exists, history = {}, retry = false, maxFixes = 5, checks = [], meta = {} } = o;
+  const baseline = await profile('baseline');
+  const { candidates, skipped } = rankFindings(baseline.result.findings, { exists, history, retry, max: maxFixes });
+  return {
+    version: SESSION_VERSION,
+    ...meta,
+    startedAt: new Date().toISOString(),
+    url: baseline.result.url,
+    checks: checks.map(c => c.name),
+    baseline: { file: baseline.file, summary: baseline.result.summary, findings: baseline.result.findings.length },
+    current: [baseline.file],
+    queue: candidates.map(f => ({ key: f.key, title: f.title, file: f.file, line: f.line, severity: f.severity, impactMs: f.impactMs, detail: f.detail, fix: f.fix, culprits: f.culprits, seenIn: f.seenIn })),
+    task: null,
+    attempts: [],
+    skipped: skipped.map(s => ({ title: s.finding.title, reason: s.reason })),
+    kept: 0,
+  };
+}
+
+/** The problem to work on: the one handed out already, or the next in the queue. Null when there is none left. */
+export function nextTask(session) {
+  if (!session.task && session.queue.length) session.task = { ...session.queue.shift(), number: session.attempts.length + 1 };
+  return session.task;
+}
+
+/**
+ * Measures the change made for the current task and decides: kept, or to be
+ * undone. The task is done either way; the next one is handed out. Resolves
+ * with the attempt (outcome, reason, headlines, checks) and the next task.
+ */
+export async function checkTask(session, o) {
+  const { profile, compare, runChecks, log = () => {} } = o;
+  const task = session.task;
+  if (!task) throw new Error('nothing to check: run `spectra improve next` first, make the change it describes, then check it.');
+  const attempt = { finding: { title: task.title, file: task.file, line: task.line, severity: task.severity, impactMs: task.impactMs, key: task.key }, outcome: null, reason: '', headlines: [], checks: [] };
+  const done = (outcome, reason, extra = {}) => {
+    Object.assign(attempt, { outcome, reason, ...extra });
+    session.attempts.push(attempt);
+    session.task = null;
+    return { attempt, next: nextTask(session) };
+  };
+
+  if (session.checks.length && runChecks) {
+    log(`running the checks (${session.checks.join(', ')}) …`);
+    const results = await runChecks();
+    attempt.checks = results.map(r => ({ name: r.name, ok: r.ok }));
+    const failed = results.find(r => !r.ok);
+    if (failed) return done('checks-failed', `"${failed.name}" failed`, { checkTail: failed.tail });
+  }
+
+  log('measuring the change …');
+  const after = [await profile(`after ${attempt.finding.key}`)];
+  let comparison = await compare(session.current, after.map(a => a.file));
+  let verdict = judge(comparison);
+  if (verdict.decision === 'measure-again') {
+    log('improved with low confidence; measuring again …');
+    after.push(await profile(`after ${attempt.finding.key}, more runs`));
+    comparison = await compare(session.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, resolved: comparison.findings.resolved.map(x => x.title), added: comparison.findings.added.map(x => x.title) };
+  if (verdict.decision !== 'keep') return done(verdict.outcome, verdict.reason);
+
+  session.current = after.map(a => a.file);
+  session.kept++;
+  // one fix often clears several problems: drop the queued ones the new measurement no longer shows
+  const present = new Set(after.flatMap(a => a.result.findings || []).map(findingKey));
+  const gone = session.queue.filter(f => !present.has(f.key));
+  session.queue = session.queue.filter(f => present.has(f.key));
+  for (const f of gone) session.skipped.push({ title: f.title, reason: 'already resolved by an earlier kept change' });
+  return done('kept', verdict.reason, { headlines: verdict.headlines });
+}
+
+/** The session's before → after, when something was kept; needs `compare` (no browser). */
+export async function overall(session, compare) {
+  if (!session.kept) return null;
+  const c = await compare([session.baseline.file], session.current);
+  return { verdict: c.verdict, confidence: c.confidence, headlines: c.headlines, resolved: c.findings.resolved.map(x => x.title) };
+}
+
+// ------------------------------------------------------------------ words
+
+/** The task, as instructions for whoever makes the change. */
+export function taskText(task, { total, command = 'npx spectra improve check' }) {
+  const culprits = (task.culprits || []).slice(0, 4).map(c => `    ${c.fn || '(anonymous)'}()${c.file ? ` in ${c.file}${c.line ? `:${c.line}` : ''}` : ''}${c.ms ? `: ${ms(c.ms)}` : ''}${c.note ? ` (${c.note})` : ''}`);
+  return [
+    `Problem ${task.number} of ${total}: ${task.title}`,
+    `  Where: ${where(task)}`,
+    `  Cost: about ${ms(task.impactMs)}${task.seenIn ? `, seen in ${task.seenIn} runs` : ''}`,
+    ...(task.detail ? [`  Detail: ${task.detail}`] : []),
+    ...(culprits.length ? ['  Where the time went:', ...culprits] : []),
+    ...(task.fix ? [`  Suggested fix: ${task.fix}`] : []),
+    '',
+    `Make ONE focused change in ${task.file} that removes or reduces this cost, keeping the behaviour exactly the same:`,
+    'the same output, UI and data. Edit only the source files involved (not package.json, lockfiles, configuration,',
+    'tests or CI), keep the change small, and do not delete features or hide content to look faster.',
+    `Then run:  ${command}`,
+  ].join('\n');
+}
+
+const OUTCOME = {
+  kept: 'fixed',
+  'checks-failed': 'undone: a check failed',
+  'no-gain': 'undone: no measurable gain',
+  slower: 'undone: slower',
+  mixed: 'undone: mixed',
+  'new-problem': 'undone: new problem',
+  unproven: 'undone: not proven',
+};
+
+/** What happened to the change just checked, and what to do now. */
+export function checkText(attempt, next, { total, command = 'npx spectra improve check', reportCommand = 'npx spectra improve report' }) {
+  const lines = [];
+  if (attempt.outcome === 'kept') {
+    lines.push(`✓ Kept: ${attempt.reason}`, ...attempt.headlines.slice(1).map(h => `  also ${h}`));
+    if (attempt.comparison?.resolved.length) lines.push(`  Resolved: ${attempt.comparison.resolved.slice(0, 3).join('; ')}`);
+    if (attempt.checks.length) lines.push(`  Checks passed: ${attempt.checks.map(c => c.name).join(', ')}.`);
+    lines.push('  Keep this change.');
+  } else {
+    lines.push(`✗ Undo this change: ${attempt.reason}.`);
+    if (attempt.outcome === 'checks-failed' && attempt.checkTail) lines.push(...attempt.checkTail.split('\n').slice(-6).map(l => `  | ${l}`));
+    lines.push('  Revert the files you changed for this problem (and only those), then continue.');
+  }
+  lines.push('');
+  if (next) lines.push(taskText(next, { total, command }));
+  else lines.push(`No more problems to try. Run:  ${reportCommand}`);
+  return lines.join('\n');
+}
+
+/** The session so far, in plain words. */
+export function reportText(session, result, { workingTree = true } = {}) {
+  const tried = session.attempts.length;
+  const lines = [`Spectra improve — ${session.kept} of ${plural(tried, 'problem')} fixed${session.task ? ` (one being worked on)` : ''}${session.queue.length ? `, ${session.queue.length} still to try` : ''}`];
+  for (const a of session.attempts) lines.push(`  ${a.outcome === 'kept' ? '✓' : '✗'} ${(OUTCOME[a.outcome] || a.outcome).padEnd(28)} ${a.finding.title} (${where(a.finding)})${a.outcome === 'kept' ? `: ${a.reason}` : a.reason ? ` — ${a.reason}` : ''}`);
+  if (session.task) lines.push(`  … in progress                ${session.task.title} (${where(session.task)})`);
+  if (result) {
+    lines.push('', `Overall, before → after: ${result.verdict.toUpperCase()} (confidence: ${result.confidence})`, ...result.headlines.map(h => `  ${h.kind === 'improved' ? '✓' : '✗'} ${h.text}`));
+  } else if (!tried) lines.push('', session.queue.length ? `${plural(session.queue.length, 'problem')} found in your own code. Run:  npx spectra improve next` : 'Nothing in your own code crossed Spectra\'s thresholds: nothing to fix.');
+  if (session.skipped.length) lines.push('', 'Not attempted:', ...session.skipped.slice(0, 6).map(s => `  – ${s.title}: ${s.reason}`));
+  if (session.kept && workingTree) lines.push('', 'The kept changes are in your working tree, uncommitted. Review them with `git diff`, then commit.');
+  return lines.join('\n');
+}
+
+/** The report as Markdown, for a pull request. */
+export function reportMarkdown(session, result) {
+  const lines = [`## ⚡ Spectra improve: ${session.kept} of ${plural(session.attempts.length, 'problem')} fixed`, '', `Page: ${session.url} · checks: ${session.checks.length ? session.checks.join(', ') : 'none'}`, ''];
+  if (result) lines.push(`**Overall, before → after:** ${result.verdict} (confidence: ${result.confidence})`, '', ...result.headlines.map(h => `- ${h.kind === 'improved' ? '✅' : '❌'} ${h.text}`), '');
+  if (session.attempts.length) {
+    lines.push('| Problem | Where | Outcome | Why |', '| --- | --- | --- | --- |');
+    for (const a of session.attempts) lines.push(`| ${a.finding.title.replace(/\|/g, '\\|')} | \`${where(a.finding)}\` | ${a.outcome === 'kept' ? '✅ fixed' : `❌ ${OUTCOME[a.outcome] || a.outcome}`} | ${(a.reason || '').replace(/\|/g, '\\|')} |`);
+    lines.push('');
+  }
+  if (session.skipped.length) lines.push('Not attempted:', ...session.skipped.map(s => `- ${s.title}: ${s.reason}`), '');
+  lines.push('<sub>Every kept change measured faster beyond run-to-run noise. Review it like any other change.</sub>');
+  return `${lines.join('\n')}\n`;
+}

package/server/improve/test-improve.js

@@ -0,0 +1,135 @@
+// The guided `spectra improve` session without a browser: measurements and
+// comparisons are fakes, so what is tested is what Spectra decides and says.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { checkTask, checkText, nextTask, overall, reportMarkdown, reportText, startSession, taskText } from './session.js';
+
+const finding = (title, file, extra = {}) => ({ id: `${title}-${file}`, severity: 'critical', title, impactMs: 500, file, line: 3, fix: 'memoize it', culprits: [{ fn: 'Row', file, line: 3, ms: 500 }], ...extra });
+const own = [finding('Row is slow to render', 'src/Row.jsx', { impactMs: 1400 }), finding('heavy.js spent 586ms', 'src/heavy.js', { impactMs: 586 }), finding('App rendered 60×', 'src/App.jsx', { impactMs: 90, severity: 'warning' })];
+const vendor = finding('react-dom is big', 'node_modules/react-dom/index.js');
+const result = (findings, file = 'r.json') => ({ file, result: { url: 'http://localhost:5190/', summary: { tbtMs: 10 }, findings } });
+const comparison = (verdict, confidence = 'medium', extra = {}) => ({
+  verdict,
+  confidence,
+  headlines: verdict === 'improved' ? [{ kind: 'improved', text: 'JavaScript CPU time: 1.55 s → 107 ms (−93%)' }, { kind: 'improved', text: 'Row — render time: 1.44 s → 8 ms' }] : verdict === 'neutral' ? [] : [{ kind: 'degraded', text: 'Total blocking time: 0 ms → 300 ms' }],
+  findings: { added: [], resolved: [], persisting: [], ...extra },
+});
+
+async function session(opts = {}) {
+  const calls = [];
+  const s = await startSession({
+    profile: async label => {
+      calls.push(label);
+      return result([...own, vendor], 'baseline.json');
+    },
+    exists: f => !f.includes('Deleted'),
+    checks: [{ name: 'npm test', cmd: 'npm test' }],
+    meta: { id: 's1', dir: '/tmp/s1', runs: 3 },
+    ...opts,
+  });
+  return { s, calls };
+}
+
+test('a session measures once, then queues the problems in the project\'s own code, costliest first', async () => {
+  const { s, calls } = await session();
+  assert.deepEqual(calls, ['baseline']);
+  assert.equal(s.baseline.file, 'baseline.json');
+  assert.deepEqual(s.current, ['baseline.json']);
+  assert.deepEqual(
+    s.queue.map(q => q.title),
+    ['Row is slow to render', 'heavy.js spent 586ms', 'App rendered 60×'],
+  );
+  assert.equal(s.task, null);
+  assert.equal(s.kept, 0);
+  assert.deepEqual(s.checks, ['npm test']);
+  // the same task until it is checked
+  const task = nextTask(s);
+  assert.equal(task.title, 'Row is slow to render');
+  assert.equal(task.number, 1);
+  assert.equal(nextTask(s), task);
+  assert.equal(s.queue.length, 2);
+  const text = taskText(task, { total: 3 });
+  assert.match(text, /^Problem 1 of 3: Row is slow to render/);
+  assert.match(text, /Where: src\/Row\.jsx:3/);
+  assert.match(text, /Suggested fix: memoize it/);
+  assert.match(text, /npx spectra improve check/);
+});
+
+test('a kept change moves the baseline on, and drops the queued problems it already solved', async () => {
+  const { s } = await session();
+  nextTask(s);
+  const log = [];
+  const { attempt, next } = await checkTask(s, {
+    profile: async label => result([own[2]], `${label}.json`), // the slow row and heavy.js are gone
+    compare: async (before, after) => {
+      log.push([before, after]);
+      return comparison('improved', 'high', { resolved: [{ title: 'Row is slow to render' }] });
+    },
+    runChecks: async () => [{ name: 'npm test', ok: true }],
+  });
+  assert.equal(attempt.outcome, 'kept');
+  assert.match(attempt.reason, /JavaScript CPU time/);
+  assert.deepEqual(attempt.checks, [{ name: 'npm test', ok: true }]);
+  assert.deepEqual(log, [[['baseline.json'], ['after Row is slow to render-src/Row.jsx.json']]]);
+  assert.equal(s.kept, 1);
+  assert.deepEqual(s.current, ['after Row is slow to render-src/Row.jsx.json']);
+  assert.equal(s.task, next);
+  assert.equal(next.title, 'App rendered 60×', 'heavy.js was resolved by the kept change, so it is skipped');
+  assert.equal(next.number, 2);
+  assert.match(s.skipped[0].reason, /already resolved/);
+  const text = checkText(attempt, next, { total: 3 });
+  assert.match(text, /^✓ Kept: JavaScript CPU time/);
+  assert.match(text, /also Row — render time/);
+  assert.match(text, /Keep this change\./);
+  assert.match(text, /Problem 2 of 3: App rendered 60×/);
+});
+
+test('a change that measures no better is to be undone; a failing check stops it before measuring', async () => {
+  const { s } = await session();
+  nextTask(s);
+  let profiled = 0;
+  const noGain = await checkTask(s, { profile: async () => (profiled++, result(own, 'a.json')), compare: async () => comparison('neutral'), runChecks: async () => [{ name: 'npm test', ok: true }] });
+  assert.equal(noGain.attempt.outcome, 'no-gain');
+  assert.equal(s.kept, 0);
+  assert.deepEqual(s.current, ['baseline.json'], 'the baseline stays where it was');
+  assert.equal(noGain.next.title, 'heavy.js spent 586ms');
+  assert.match(checkText(noGain.attempt, noGain.next, { total: 3 }), /^✗ Undo this change: no measurable improvement.*\n {2}Revert the files you changed/);
+
+  profiled = 0;
+  const broken = await checkTask(s, { profile: async () => (profiled++, result(own)), compare: async () => comparison('improved'), runChecks: async () => [{ name: 'npm test', ok: false, tail: 'Error: rows 0' }] });
+  assert.equal(broken.attempt.outcome, 'checks-failed');
+  assert.equal(profiled, 0, 'a broken page is not measured');
+  assert.match(checkText(broken.attempt, broken.next, { total: 3 }), /"npm test" failed[\s\S]*\| Error: rows 0/);
+  assert.equal(broken.next.title, 'App rendered 60×');
+
+  // low confidence measures again once, then gives up
+  let n = 0;
+  const unproven = await checkTask(s, { profile: async () => result(own, `p${n++}.json`), compare: async () => comparison('improved', 'low'), runChecks: async () => [{ name: 'npm test', ok: true }] });
+  assert.equal(n, 2);
+  assert.equal(unproven.attempt.outcome, 'unproven');
+  assert.equal(unproven.next, null);
+  assert.match(checkText(unproven.attempt, null, { total: 3 }), /No more problems to try\. Run: {2}npx spectra improve report/);
+  await assert.rejects(checkTask(s, {}), /nothing to check/);
+});
+
+test('the report says what happened, and the overall change compares the baseline with the latest kept state', async () => {
+  const { s } = await session();
+  assert.match(reportText(s, null), /3 problems found in your own code/);
+  nextTask(s);
+  await checkTask(s, { profile: async () => result(own.slice(1), 'k1.json'), compare: async () => comparison('improved', 'high'), runChecks: async () => [{ name: 'npm test', ok: true }] });
+  await checkTask(s, { profile: async () => result(own.slice(1), 'u1.json'), compare: async () => comparison('regressed'), runChecks: async () => [{ name: 'npm test', ok: true }] });
+  const seen = [];
+  const final = await overall(s, async (before, after) => (seen.push([before, after]), comparison('improved', 'high')));
+  assert.deepEqual(seen, [[['baseline.json'], ['k1.json']]]);
+  const text = reportText(s, final);
+  assert.match(text, /^Spectra improve — 1 of 2 problems fixed/);
+  assert.match(text, /✓ fixed .*Row is slow to render \(src\/Row\.jsx:3\): JavaScript CPU time/);
+  assert.match(text, /✗ undone: slower .*heavy\.js spent 586ms/);
+  assert.match(text, /Overall, before → after: IMPROVED \(confidence: high\)/);
+  assert.match(text, /in your working tree, uncommitted/);
+  const md = reportMarkdown(s, final);
+  assert.match(md, /^## ⚡ Spectra improve: 1 of 2 problems fixed/);
+  assert.match(md, /\| Row is slow to render \| `src\/Row\.jsx:3` \| ✅ fixed \|/);
+  assert.match(md, /❌ undone: slower/);
+  assert.equal(await overall({ kept: 0 }, async () => assert.fail('nothing kept, nothing to compare')), null);
+});