@autor3search/javascript 0.2.0

package/src/gitx.js

@@ -0,0 +1,115 @@
+/**
+ * The git commands autor3search-javascript needs.
+ *
+ * Stdout and stderr are captured separately so that stderr chatter on an
+ * otherwise successful command — git-lfs filter warnings, advice.* hints,
+ * locale warnings, a user's own hooks — is never parsed as part of the
+ * result. Stderr appears in the error message only when the command fails.
+ */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const exec = promisify(execFile)
+
+/** Runs a git subcommand in dir and returns its trimmed stdout. */
+async function git(dir, ...args) {
+  try {
+    const { stdout } = await exec('git', args, { cwd: dir, maxBuffer: 64 * 1024 * 1024 })
+    return stdout.trim()
+  } catch (err) {
+    const stderr = (err.stderr ?? '').trim()
+    throw new Error(`git ${args.join(' ')}: ${err.message}${stderr ? `\n${stderr}` : ''}`, { cause: err })
+  }
+}
+
+/** The repository root containing dir. */
+export const root = (dir) => git(dir, 'rev-parse', '--show-toplevel')
+
+/** The short hash of HEAD. */
+export const headCommit = (dir) => git(dir, 'rev-parse', '--short=7', 'HEAD')
+
+/**
+ * The first line of HEAD's commit message. `stop --force` prints this to
+ * identify the commit an abandoned experiment left behind, so only the
+ * subject is wanted — never the body or its trailers.
+ */
+export const headSubject = (dir) => git(dir, 'log', '-1', '--format=%s')
+
+/** The checked-out branch name. */
+export const currentBranch = (dir) => git(dir, 'rev-parse', '--abbrev-ref', 'HEAD')
+
+/** Creates and checks out a branch at HEAD. */
+export const createBranch = (dir, name) => git(dir, 'checkout', '-b', name).then(() => undefined)
+
+/** Switches the working tree to an existing branch or other ref. */
+export const checkout = (dir, ref) => git(dir, 'checkout', ref).then(() => undefined)
+
+/**
+ * Force-deletes a local branch. Used to undo a run branch left behind by a
+ * `baseline` attempt that failed partway through, so a retry under the same
+ * name is not permanently blocked.
+ */
+export const deleteBranch = (dir, name) => git(dir, 'branch', '-D', name).then(() => undefined)
+
+/** Checks commit out into a detached worktree at path. */
+export const addWorktree = (repoDir, path, commit) =>
+  git(repoDir, 'worktree', 'add', '--detach', path, commit).then(() => undefined)
+
+/**
+ * Moves an existing worktree to commit, detached. Used to advance the pinned
+ * baseline worktree after a KEEP: re-pointing an existing worktree with a
+ * plain checkout has less failure surface than removing and re-adding it,
+ * which would re-register it in the main repository's metadata rather than
+ * just moving HEAD. -f discards stray changes in the target — nothing should
+ * ever modify the pinned worktree, but checking out over a dirty tree without
+ * it would fail instead of re-pointing.
+ */
+export const checkoutDetached = (dir, commit) =>
+  git(dir, 'checkout', '-f', '--detach', commit).then(() => undefined)
+
+/**
+ * Deletes a worktree previously created by addWorktree.
+ *
+ * --force silently discards uncommitted and untracked changes in the target.
+ * git still refuses to remove the main working tree or an unregistered path,
+ * but callers must only ever point this at a worktree the harness itself
+ * created — never at a path a human might have unsaved work in.
+ */
+export const removeWorktree = (repoDir, path) =>
+  git(repoDir, 'worktree', 'remove', '--force', path).then(() => undefined)
+
+/** Reports whether a local branch exists. */
+export async function branchExists(dir, name) {
+  try {
+    await git(dir, 'show-ref', '--verify', '--quiet', `refs/heads/${name}`)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Reports whether the working tree has no changes. */
+export async function isClean(dir) {
+  return (await git(dir, 'status', '--porcelain')) === ''
+}
+
+/**
+ * Lists repo-relative paths modified since commit, including untracked files
+ * that are not gitignored, sorted and deduplicated.
+ *
+ * Both git calls use -z. Without it, git quotes and octal-escapes any path
+ * containing non-ASCII bytes, quotes or backslashes (e.g. "src/caf\303\251.js"),
+ * which would then fail scope matching and let an out-of-scope edit through.
+ * -z output is NUL-separated and not terminated, so it is split explicitly.
+ */
+export async function changedSince(dir, commit) {
+  const tracked = await git(dir, 'diff', '--name-only', '-z', commit)
+  const untracked = await git(dir, 'ls-files', '-z', '--others', '--exclude-standard')
+  const seen = new Set()
+  for (const block of [tracked, untracked]) {
+    for (const entry of block.split('\0')) {
+      if (entry !== '') seen.add(entry)
+    }
+  }
+  return [...seen].sort()
+}

package/src/measure.js

@@ -0,0 +1,127 @@
+/**
+ * Collects observations from a baseline and a candidate tree in INTERLEAVED
+ * order.
+ *
+ * This is the core measurement discipline. Comparing a candidate measured now
+ * against a baseline measured minutes ago attributes CPU thermal drift,
+ * frequency scaling and background load to the code change. Alternating the
+ * two sides within a single session cancels that, because both sides
+ * experience the same conditions.
+ */
+import { BenchSet } from './bench/set.js'
+import { getBenchRunner } from './adapters/bench/index.js'
+import { measureHeap } from './adapters/driver.js'
+
+/**
+ * Runs base and cand alternately for `rounds` measured rounds, accumulating
+ * their observations. With `warmup`, one extra leading round is run and
+ * discarded, absorbing first-touch effects such as cold caches and JIT
+ * tier-up.
+ *
+ * The two sides SWAP ORDER on every round — base,cand then cand,base — rather
+ * than always running base first. Alternating rounds alone cancels drift
+ * BETWEEN rounds, but a fixed order within each round leaves a systematic
+ * offset: the candidate would then always be measured one slot later than the
+ * baseline, so any drift monotonic across a round (a CPU still ramping toward
+ * its thermal steady state, a background job starting mid-run) lands on the
+ * candidate in the same direction every single time. Averaging over rounds
+ * does not remove it, because it is not noise — it is a constant bias, and it
+ * shifts the score the KEEP threshold is compared against.
+ *
+ * An odd number of measured rounds cannot be split evenly and leaves one
+ * round's worth of that offset behind; an even count cancels it exactly.
+ *
+ * @param {{rounds: number, warmup: boolean, base: (round: number) => Promise<BenchSet>, cand: (round: number) => Promise<BenchSet>, signal?: AbortSignal}} opts
+ * @returns {Promise<{baseSet: BenchSet, candSet: BenchSet}>}
+ */
+export async function interleave({ rounds, warmup, base, cand, signal }) {
+  if (rounds < 2) throw new Error(`need at least 2 measured rounds, got ${rounds}`)
+
+  const baseSet = new BenchSet()
+  const candSet = new BenchSet()
+  const total = warmup ? rounds + 1 : rounds
+
+  for (let i = 0; i < total; i++) {
+    signal?.throwIfAborted()
+    const baseFirst = i % 2 === 0
+    const [first, second] = baseFirst ? [base, cand] : [cand, base]
+    const [firstLabel, secondLabel] = baseFirst ? ['baseline', 'candidate'] : ['candidate', 'baseline']
+
+    const firstSet = await labelled(first, i, firstLabel)
+    signal?.throwIfAborted()
+    const secondSet = await labelled(second, i, secondLabel)
+
+    if (warmup && i === 0) continue
+    baseSet.add(baseFirst ? firstSet : secondSet)
+    candSet.add(baseFirst ? secondSet : firstSet)
+  }
+  return { baseSet, candSet }
+}
+
+/** Runs one side's round, naming which side and which round on failure. */
+async function labelled(fn, round, label) {
+  try {
+    return await fn(round)
+  } catch (err) {
+    throw new Error(`${label} round ${round}: ${err.message}`, { cause: err })
+  }
+}
+
+/**
+ * Measures two worktrees for real, wiring the configured bench runner and,
+ * when enabled, the heap-delta hint.
+ *
+ * The hint is folded into the SAME round as the timing so it gets the same
+ * number of observations and therefore a real p-value. It is still never
+ * scored — see src/pipeline.js.
+ *
+ * `benchmarks` selects by exact name, same as the bench adapter itself
+ * (src/adapters/bench/vitest.js): an empty array is the valid, ordinary
+ * "measure everything discovered" case, not an error. There is no regexp
+ * `pattern` here — Vitest's own benchmark name filter does not work, so
+ * selection happens after parsing, by exact name.
+ *
+ * @param {object} opts
+ * @returns {Promise<{baseSet: BenchSet, candSet: BenchSet}>}
+ */
+export async function measure(opts) {
+  if (!Array.isArray(opts.benchmarks)) {
+    throw new Error('measure: benchmarks must be an array (empty selects every discovered benchmark)')
+  }
+  const runner = getBenchRunner(opts.runner)
+
+  const roundFn = (dir) => async () => {
+    const set = await runner.run(dir, {
+      benchmarks: opts.benchmarks,
+      // The same file list both sides get, so neither is measured under a
+      // different workload than the other.
+      benchFiles: opts.benchFiles ?? [],
+      timeoutMs: opts.timeoutMs,
+      env: opts.env,
+      log: opts.log,
+      signal: opts.signal,
+    })
+    if (opts.heapHint) {
+      set.add(
+        await measureHeap(dir, {
+          benchFiles: opts.benchFiles ?? [],
+          benchmarks: opts.benchmarks,
+          iterations: opts.heapIterations ?? 1000,
+          timeoutMs: opts.timeoutMs,
+          env: opts.env,
+          log: opts.log,
+          signal: opts.signal,
+        }),
+      )
+    }
+    return set
+  }
+
+  return interleave({
+    rounds: opts.rounds,
+    warmup: opts.warmup ?? true,
+    base: roundFn(opts.baseDir),
+    cand: roundFn(opts.candDir),
+    signal: opts.signal,
+  })
+}

package/src/pipeline.js

@@ -0,0 +1,391 @@
+/**
+ * Runs one full evaluation: gate correctness, measure the candidate against
+ * the pinned baseline, score it.
+ *
+ * It lives here rather than in the command layer so it is testable without a
+ * process boundary — `eval` itself handles only flags, output formatting and
+ * the exit code.
+ *
+ * CONTRACT: evalOnce RETURNS a terminal verdict for every gate outcome and
+ * every completed measurement. A THROWN error means the harness itself
+ * malfunctioned (I/O, git, a malformed baseline), never that the candidate
+ * was rejected. Callers treat those two cases completely differently.
+ */
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { CONFIG_PATH } from './config.js'
+import { UNIT_BYTES, UNIT_TIME } from './bench/set.js'
+import { compareAll, geoMean } from './bench/stats.js'
+import { benchFilesFor, frozenFiles } from './discover.js'
+import * as freeze from './freeze.js'
+import * as gitx from './gitx.js'
+import { measure } from './measure.js'
+import { RESULTS_PATH } from './results.js'
+import { runGates } from './adapters/gates/index.js'
+import { createMatcher } from './scope.js'
+import { WORKTREE_NAME, BASELINE_FILE, linkNodeModules, saveBaseline } from './state/index.js'
+import { REASON, STATUS, decide, gate } from './verdict.js'
+import { parseDuration } from './duration.js'
+
+/**
+ * The harness-owned scratch log inside the repository root. Subprocess output
+ * that would otherwise flood an unattended agent's context is written here
+ * rather than to stdout. `init` gitignores it, and it is not part of the score.
+ */
+export const RUN_LOG_NAME = 'run.log'
+
+/**
+ * Files whose modification is rejected regardless of scope. Changing a
+ * dependency is a supply-chain decision a human makes, not something an
+ * unattended overnight loop decides — and a swapped dependency changes WHAT
+ * is measured, not just how fast it runs. The default scope matches root
+ * files, so this cannot be left to the scope patterns.
+ */
+export const DEPENDENCY_FILES = new Set([
+  'package.json',
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'bun.lock',
+  'bun.lockb',
+])
+
+/**
+ * Vitest/Vite config filenames whose modification is rejected regardless of
+ * scope, for a different reason than DEPENDENCY_FILES: these are loaded by
+ * the bench runner ITSELF (`vitest bench --run --root=<dir>`), so an
+ * ordinary, in-scope, committed config file can redirect what a frozen
+ * benchmark imports — or stub out the code path it measures entirely —
+ * without the frozen benchmark file itself changing by even one byte. The
+ * default scope (`["**"]`) admits a root config file exactly like any other
+ * source file, so this cannot be left to the scope patterns any more than a
+ * dependency file can.
+ *
+ * The name/extension list is exhaustive for Vitest 2.1.9, verified directly
+ * against its own resolution table
+ * (node_modules/vitest/dist/chunks/constants.*.js: CONFIG_NAMES,
+ * CONFIG_EXTENSIONS, WORKSPACES_NAMES, WORKSPACES_EXTENSIONS) rather than
+ * guessed from documentation:
+ *   - `vitest.config` / `vite.config` (Vitest loads Vite's own config too),
+ *     each with .js .mjs .cjs .ts .mts .cts
+ *   - `vitest.workspace` / `vitest.projects` — the latter is an alternate
+ *     workspace name Vitest accepts that is easy to miss because the two
+ *     names are documented as synonyms nowhere obvious — each with those six
+ *     extensions plus .json
+ */
+const CONFIG_NAMES = ['vitest.config', 'vite.config']
+const CONFIG_EXTS = ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts']
+const WORKSPACE_NAMES = ['vitest.workspace', 'vitest.projects']
+const WORKSPACE_EXTS = [...CONFIG_EXTS, '.json']
+
+export const TOOLCHAIN_CONFIG_FILES = new Set([
+  ...CONFIG_NAMES.flatMap((name) => CONFIG_EXTS.map((ext) => `${name}${ext}`)),
+  ...WORKSPACE_NAMES.flatMap((name) => WORKSPACE_EXTS.map((ext) => `${name}${ext}`)),
+])
+
+/** Which gate failure maps to which status and reason. */
+const GATE_VERDICT = {
+  typecheck: { status: STATUS.CRASH, reason: REASON.TYPECHECK },
+  lint: { status: STATUS.FAIL, reason: REASON.LINT },
+  test: { status: STATUS.FAIL, reason: REASON.TESTS },
+}
+
+/**
+ * @param {{root: string, stateDir: string, cfg: object, baseline: object, log?: object, signal?: AbortSignal}} o
+ * @returns {Promise<{result: object, measurements: {time: object[], bytes: object[]|null}|null}>}
+ */
+export async function evalOnce(o) {
+  const timeoutMs = parseDuration(o.cfg.timeout)
+
+  // ---- 1. Scope --------------------------------------------------------
+  // Checked before anything is restored or built, so an out-of-scope edit is
+  // reported as itself rather than as a build error.
+  //
+  // Deliberately diffs against baseline.commit — the FROZEN, never-advancing
+  // anchor — and NOT measureCommit, which moves after every KEEP. Anchoring
+  // here means the gate re-validates the FULL accumulated diff on every eval.
+  // Anchoring it to the advancing pointer instead would give an out-of-scope
+  // edit exactly one eval in which to be caught: past that single check it
+  // would become part of the "already accepted" state and never be looked at
+  // again.
+  const changed = await gitx.changedSince(o.root, o.baseline.commit)
+  const matcher = createMatcher(o.cfg.scope)
+  const frozenSet = new Set(await frozenFiles(o.root, o.cfg.unfreeze))
+
+  for (const rel of changed) {
+    if (DEPENDENCY_FILES.has(rel)) {
+      return terminal(
+        gate(
+          STATUS.FAIL,
+          REASON.SCOPE,
+          `${rel} may not be modified: dependency changes are a human decision, not an autonomous one`,
+        ),
+      )
+    }
+    if (TOOLCHAIN_CONFIG_FILES.has(rel)) {
+      return terminal(
+        gate(
+          STATUS.FAIL,
+          REASON.SCOPE,
+          `${rel} may not be modified: it is loaded by the bench runner itself and can redirect what a ` +
+            `benchmark measures without changing the frozen benchmark file at all`,
+        ),
+      )
+    }
+    // Harness output, plus the human-owned config, which is integrity-checked
+    // below rather than scope-checked.
+    if (rel === RESULTS_PATH || rel === RUN_LOG_NAME || rel === CONFIG_PATH) continue
+    // Frozen files are handled by restore, not by the scope gate.
+    if (frozenSet.has(rel)) continue
+    if (!matcher.match(rel)) {
+      return terminal(
+        gate(STATUS.FAIL, REASON.SCOPE, `${rel} is outside the allowed scope ${JSON.stringify(o.cfg.scope)}`),
+      )
+    }
+  }
+
+  // ---- 1b. Config integrity -------------------------------------------
+  // config.yaml lives in the repo because humans own it, which means the
+  // agent can reach it. Raising max_regress_pct or deleting entries from the
+  // benchmark set would defeat the guard, so the file is hashed at baseline
+  // and any change fails the run.
+  const configSha = await sha256File(join(o.root, CONFIG_PATH))
+  if (configSha !== o.baseline.configSha256) {
+    return terminal(
+      gate(
+        STATUS.FAIL,
+        REASON.CONFIG_CHANGED,
+        `${CONFIG_PATH} changed since baseline — scoring rules are fixed for a run; revert it, or start ` +
+          `a new run with 'autor3search-javascript baseline'`,
+      ),
+    )
+  }
+
+  // ---- 2. Restore frozen tests and benchmarks --------------------------
+  const manifest = await freeze.loadManifest(join(o.stateDir, freeze.MANIFEST_PATH))
+  let restored
+  try {
+    restored = await freeze.restore(o.root, join(o.stateDir, freeze.STORE_DIR), manifest)
+  } catch (err) {
+    // A frozen file replaced by a symlink or a hard link is TAMPERING, not a
+    // harness malfunction: report it as a verdict so the run gets a
+    // results.tsv row and an actionable message, rather than aborting with no
+    // signal at all.
+    if (err.code === freeze.ERR_HARD_LINK) {
+      return terminal(
+        gate(
+          STATUS.FAIL,
+          REASON.HARDLINK_SWAP,
+          `${err.message} — a frozen file must have exactly one name; a hard link would let a restore ` +
+            `write outside the repository`,
+        ),
+      )
+    }
+    if (err.code === freeze.ERR_SYMLINK) {
+      return terminal(
+        gate(
+          STATUS.FAIL,
+          REASON.SYMLINK_SWAP,
+          `${err.message} — a frozen file, and every directory on the way to it, must remain a regular ` +
+            `file and real directories; restore them and rerun`,
+        ),
+      )
+    }
+    // A golden copy that no longer matches its recorded hash means the store
+    // itself was rewritten. Unlike a symlink this cannot be undone by fixing
+    // the working tree, because the reference copy is the thing that was lost.
+    if (err.code === freeze.ERR_STORE_TAMPERED) {
+      return terminal(
+        gate(
+          STATUS.FAIL,
+          REASON.FROZEN_TAMPERED,
+          `${err.message} — the frozen copy this run scores against was modified, so its tests can no ` +
+            `longer be trusted. Start a fresh run with 'autor3search-javascript baseline'.`,
+        ),
+      )
+    }
+    throw err
+  }
+  if (restored.length > 0) {
+    o.log?.write(`restored ${restored.length} frozen file(s): ${restored.join(', ')}\n`)
+  }
+
+  // ---- 2b. Frozen-set integrity, in BOTH directions --------------------
+  // Restore only rewrites files it froze, and the scope gate skips every
+  // frozen path, so without this an agent could ADD a brand-new test or bench
+  // file — an easier benchmark, or one shadowing a frozen one — and neither
+  // gate would notice.
+  //
+  // The reverse direction matters just as much and is easier to miss: a file
+  // restore just rewrote should always be visible to the walker again, so a
+  // manifest entry MISSING from what is present means the walk could not
+  // reach it. A structural change to the tree can hide a frozen file from
+  // discovery while leaving it nominally restored, and the run would then
+  // score against a benchmark set that no longer runs.
+  const present = new Set(await frozenFiles(o.root, o.cfg.unfreeze))
+  const added = [...present].filter((rel) => !(rel in manifest.files)).sort()
+  if (added.length > 0) {
+    return terminal(
+      gate(
+        STATUS.FAIL,
+        REASON.NEW_TEST_FILE,
+        `test or benchmark files not present at baseline: ${added.join(', ')} — the benchmark set is ` +
+          `frozen; add them before running 'autor3search-javascript baseline', or list them in config unfreeze`,
+      ),
+    )
+  }
+  const missing = Object.keys(manifest.files).filter((rel) => !present.has(rel)).sort()
+  if (missing.length > 0) {
+    return terminal(
+      gate(
+        STATUS.FAIL,
+        REASON.MISSING_TEST_FILE,
+        `frozen files are no longer discoverable in the working tree: ${missing.join(', ')} — they were ` +
+          `restored, but the walk that finds them cannot reach them, so they would not run. Check for a ` +
+          `directory on their path that was replaced, renamed, or moved under a skipped name.`,
+      ),
+    )
+  }
+
+  // ---- 3-5. Correctness gates -----------------------------------------
+  const outcomes = await runGates(o.root, {
+    modes: o.cfg.gates,
+    scope: o.cfg.scope,
+    timeoutMs,
+    log: o.log,
+    signal: o.signal,
+  })
+  // An abort during the gate phase is an ABORT, not a gate failure. Without
+  // this the killed subprocess would look like a failing test, producing a
+  // FAIL verdict and a results.tsv row for an experiment nobody measured.
+  if (o.signal?.aborted) throw new Error('aborted during the correctness gates')
+  for (const outcome of outcomes) {
+    if (outcome.skipped) o.log?.write(`gate ${outcome.name} skipped: ${outcome.skipped}\n`)
+    if (outcome.ok) continue
+    if (outcome.timedOut) {
+      return terminal(gate(STATUS.CRASH, REASON.TIMEOUT, `${outcome.name} gate timed out after ${o.cfg.timeout}`))
+    }
+    const { status, reason } = GATE_VERDICT[outcome.name]
+    return terminal(gate(status, reason, outcome.detail))
+  }
+
+  // ---- 5b. Baseline worktree integrity --------------------------------
+  // An agent could edit the pinned baseline worktree in place to make the
+  // BASELINE slow, after which every candidate "improves" and every
+  // experiment returns KEEP without optimizing anything.
+  //
+  // Compares against measureCommit, not commit: the worktree is re-pointed
+  // after every KEEP, so comparing against the frozen anchor would fire
+  // spuriously on the very next eval after any KEEP.
+  //
+  // This is a DETECTION, and only a partial one. The state directory lives
+  // outside the repository, but the agent runs as the same OS user, so
+  // nothing stops it editing the worktree in place — this catches that only
+  // if HEAD itself moves. Treat it as catching accidental clobbering and a
+  // careless tamper, not as a guarantee.
+  const worktreeDir = join(o.stateDir, WORKTREE_NAME)
+  const worktreeHead = await gitx.headCommit(worktreeDir)
+  if (worktreeHead !== o.baseline.measureCommit) {
+    return terminal(
+      gate(
+        STATUS.FAIL,
+        REASON.BASELINE_TAMPERED,
+        `pinned baseline worktree HEAD is ${worktreeHead} but the recorded measurement commit is ` +
+          `${o.baseline.measureCommit} — the worktree no longer matches the baseline and this run's ` +
+          `measurements cannot be trusted. Start a fresh run with 'autor3search-javascript baseline'.`,
+      ),
+    )
+  }
+
+  // ---- 6. Measure ------------------------------------------------------
+  // Self-heals a worktree that lost its node_modules link — the target
+  // moved, someone deleted it — rather than failing every eval after the
+  // first. See linkNodeModules in src/state/index.js.
+  await linkNodeModules(o.root, worktreeDir)
+  let baseSet, candSet
+  try {
+    ;({ baseSet, candSet } = await measure({
+      runner: o.cfg.runner,
+      baseDir: worktreeDir,
+      candDir: o.root,
+      benchmarks: o.baseline.benchmarks,
+      rounds: o.cfg.count,
+      warmup: true,
+      timeoutMs,
+      heapHint: o.cfg.heapHint,
+      benchFiles: await benchFilesFor(o.root, o.baseline.benchmarks),
+      log: o.log,
+      signal: o.signal,
+    }))
+  } catch (err) {
+    // An ABORT is not a measurement failure. The bench adapter reports an
+    // aborted round as a timeout (both set `timedOut` on the runner result),
+    // so without this check a human pressing Ctrl+C or running `stop --force`
+    // would get CRASH/measurement_failed instead of ABORTED — and a
+    // results.tsv row would be written for an experiment that was never
+    // measured. Rethrow so the command layer's abort handler owns it.
+    if (o.signal?.aborted) throw err
+    return terminal(gate(STATUS.CRASH, REASON.MEASUREMENT, err.message))
+  }
+
+  // ---- 7. Score --------------------------------------------------------
+  // Time is the scored metric: any failure here — including a benchmark that
+  // vanished from the candidate — fails the whole call, per compareAll's
+  // contract.
+  const timeDeltas = compareAll(baseSet, candSet, UNIT_TIME)
+  const score = geoMean(timeDeltas)
+
+  // The bytes hint is informational ONLY. compareAll is strict about a
+  // benchmark disappearing from one side, which is right for the scored
+  // metric and wrong here: a hint that could not be measured must never fail
+  // a real, correctly-measured experiment.
+  let bytesDeltas = null
+  try {
+    bytesDeltas = compareAll(baseSet, candSet, UNIT_BYTES)
+  } catch (err) {
+    o.log?.write(`bytes/op comparison unavailable, continuing without it: ${err.message}\n`)
+  }
+
+  const result = decide({
+    deltas: timeDeltas,
+    score,
+    maxRegressPct: o.cfg.maxRegressPct,
+    minEffectPct: o.cfg.minEffectPct,
+  })
+
+  // ---- 8. Advance the measurement baseline on KEEP ---------------------
+  // Without this, every experiment after the first kept one is measured
+  // against the run's ORIGINAL commit forever, so a later no-op that merely
+  // fails to regress an EARLIER improvement still banks as KEEP.
+  if (result.status === STATUS.KEEP) {
+    await advanceMeasurementBaseline(o, worktreeDir)
+  }
+
+  return { result, measurements: { time: timeDeltas, bytes: bytesDeltas } }
+}
+
+/**
+ * Re-points the pinned baseline worktree at the candidate's own commit and
+ * persists it as the new measureCommit.
+ *
+ * A failure here is thrown, not folded into the verdict: continuing to run
+ * experiments against a worktree that no longer agrees with the recorded
+ * measurement commit would silently corrupt every subsequent measurement —
+ * exactly the class of bug this advance exists to fix. Should it fail after
+ * the worktree moved but before the new commit was persisted, the NEXT eval's
+ * worktree-integrity check catches the mismatch and fails loudly.
+ */
+async function advanceMeasurementBaseline(o, worktreeDir) {
+  const newCommit = await gitx.headCommit(o.root)
+  await gitx.checkoutDetached(worktreeDir, newCommit)
+  o.baseline.measureCommit = newCommit
+  await saveBaseline(join(o.stateDir, BASELINE_FILE), o.baseline)
+}
+
+const terminal = (result) => ({ result, measurements: null })
+
+async function sha256File(path) {
+  return createHash('sha256').update(await readFile(path)).digest('hex')
+}