@autor3search/javascript 0.2.0

package/src/cli/cmd-eval.js

@@ -0,0 +1,231 @@
+/**
+ * Runs one experiment and returns a verdict.
+ *
+ * With --json this prints ONE JSON object to stdout and nothing else. That is
+ * a contract program.md's loop depends on: the agent parses stdout directly,
+ * so a stray line of progress output would break every run. The subprocess
+ * transcript goes to run.log instead, opened by this command itself so the
+ * agent never has to redirect stdout (doing so would open a second
+ * descriptor on the same path and clobber whichever writes second).
+ */
+import { createWriteStream } from 'node:fs'
+import { join } from 'node:path'
+import { parseArgs } from 'node:util'
+import { headCommit } from '../gitx.js'
+import { RUN_LOG_NAME, evalOnce } from '../pipeline.js'
+import { RESULTS_PATH, appendRow, loadRows } from '../results.js'
+import { BASELINE_FILE, WORKTREE_NAME, loadBaseline } from '../state/index.js'
+import { claimEval } from '../state/lock.js'
+import { stopRequested } from '../state/stop.js'
+import { REASON, STATUS, exitCode } from '../verdict.js'
+import { expandSingleDashFlags, loadRepoConfig, resolveRun } from './context.js'
+
+/**
+ * @param {string[]} args
+ * @param {{out: {write(s: string): void}, err: {write(s: string): void}}} io
+ * @returns {Promise<number>}
+ */
+export async function runEval(args, io) {
+  const { values } = parseArgs({
+    args: expandSingleDashFlags(args, ['desc']),
+    options: {
+      C: { type: 'string', default: '.' },
+      json: { type: 'boolean', default: false },
+      desc: { type: 'string', default: '' },
+      'no-log': { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  })
+
+  // --json's whole contract is that stdout carries nothing but the verdict.
+  // --no-log sends the transcript to stdout instead of run.log. Combining
+  // them would interleave subprocess chatter with the JSON object, breaking
+  // the one contract this command exists to keep — refuse before anything
+  // is claimed or touched.
+  if (values.json && values['no-log']) {
+    io.err.write('--json and --no-log cannot be combined: --json requires stdout to carry only the verdict\n')
+    return 2
+  }
+
+  const run = await resolveRun(values.C)
+  const cfg = await loadRepoConfig(run.root)
+  const baseline = await loadBaseline(join(run.stateDir, BASELINE_FILE))
+
+  // An interrupt must not leave Vitest workers running: the runner kills its
+  // process groups, and this abort signal is what tells evalOnce's measure
+  // phase to do it.
+  //
+  // Installed BEFORE the claim, and that order is load-bearing. claimEval
+  // creates the lock DIRECTORY first and writes its pid and heartbeat files
+  // afterwards, so a handler installed after it would leave a window in which
+  // the run already owns on-disk state while SIGINT still has Node's default
+  // action: the process dies outright, the `finally` below never runs, and the
+  // claim sits stranded until it goes stale ~30s later, refusing every eval in
+  // between. That window is also observable from outside — evalRunning reports
+  // `running` as soon as the directory exists — so anything waiting for the run
+  // to start could deliver the signal squarely into it.
+  //
+  // An interrupt arriving before there is anything to abort is harmless: the
+  // controller simply starts out aborted, and evalOnce stops at its first
+  // checkpoint without measuring anything.
+  const controller = new AbortController()
+  const onSignal = () => controller.abort()
+  process.on('SIGINT', onSignal)
+  process.on('SIGTERM', onSignal)
+  const offSignals = () => {
+    process.off('SIGINT', onSignal)
+    process.off('SIGTERM', onSignal)
+  }
+
+  let claim
+  try {
+    claim = await claimEval(run.stateDir)
+  } catch (err) {
+    // dispatch() also runs in-process under test, so a leaked listener here
+    // would accumulate across runs rather than dying with the process.
+    offSignals()
+    io.err.write(`${err.message}\n`)
+    return 2
+  }
+
+  // The transcript goes to run.log by default; --no-log streams it to stdout
+  // for a human watching interactively instead (never combined with --json,
+  // refused above).
+  const logStream = values['no-log'] ? null : createWriteStream(join(run.root, RUN_LOG_NAME), { flags: 'a' })
+  // A stream error (e.g. the directory vanishing mid-run) must not crash the
+  // process via an unhandled 'error' event; it surfaces as a missing
+  // transcript instead, which run.log's absence already makes visible.
+  logStream?.on('error', () => {})
+  const log = values['no-log'] ? io.out : logStream
+
+  try {
+    const { result, measurements } = await evalOnce({
+      root: run.root,
+      stateDir: run.stateDir,
+      cfg,
+      baseline,
+      log,
+      signal: controller.signal,
+    })
+
+    const experiment = (await loadRows(join(run.root, RESULTS_PATH))).length + 1
+    await appendRow(join(run.root, RESULTS_PATH), {
+      commit: await headCommit(run.root).catch(() => 'unknown'),
+      score: result.score,
+      bestBenchDelta: bestDelta(measurements?.time),
+      bytesDelta: bestDelta(measurements?.bytes),
+      status: result.status.toLowerCase(),
+      description: values.desc,
+    })
+
+    const stopped = await stopRequested(run.stateDir)
+    const context = buildContext(run, baseline, experiment)
+
+    if (values.json) writeJson(io, result, measurements, stopped, context)
+    else writeHuman(io, result, measurements, stopped, context)
+    return exitCode(result)
+  } catch (err) {
+    if (controller.signal.aborted) {
+      // ABORTED is not a verdict: nothing was measured, so NO results.tsv row
+      // is written. The agent treats it as it would a FAIL.
+      const aborted = {
+        status: STATUS.ABORTED,
+        reason: REASON.STOP_FORCED,
+        score: 0,
+        message: 'the experiment was interrupted before it could be measured',
+        regressions: [],
+        warnings: [],
+      }
+      // Still report whatever is actually pending — an interrupt is not
+      // itself evidence that a graceful stop was also requested.
+      const stopped = await stopRequested(run.stateDir).catch(() => false)
+      const context = buildContext(run, baseline)
+      if (values.json) writeJson(io, aborted, null, stopped, context)
+      else {
+        io.err.write(`ABORTED: ${aborted.message}\n`)
+        if (stopped) io.err.write('STOP REQUESTED: end the loop after applying this verdict\n')
+      }
+      return exitCode(aborted)
+    }
+    throw err
+  } finally {
+    offSignals()
+    await closeLog(logStream)
+    await claim.release()
+  }
+}
+
+/** The run context reported alongside a verdict; experiment is omitted when none was recorded. */
+function buildContext(run, baseline, experiment) {
+  return {
+    tag: run.tag,
+    branch: run.branch,
+    baseline_commit: baseline.commit,
+    measure_commit: baseline.measureCommit,
+    worktree: join(run.stateDir, WORKTREE_NAME),
+    ...(experiment !== undefined ? { experiment } : {}),
+  }
+}
+
+/** Flushes and closes the transcript stream, if one was opened. */
+async function closeLog(stream) {
+  if (!stream) return
+  await new Promise((resolve) => stream.end(resolve))
+}
+
+function writeJson(io, result, measurements, stopped, run) {
+  io.out.write(
+    `${JSON.stringify({
+      status: result.status,
+      reason: result.reason,
+      score: result.score,
+      message: result.message,
+      regressions: result.regressions ?? [],
+      warnings: result.warnings ?? [],
+      deltas: (measurements?.time ?? []).map(publicDelta),
+      bytes: (measurements?.bytes ?? []).map(publicDelta),
+      stop_requested: stopped,
+      run,
+    })}\n`,
+  )
+}
+
+function writeHuman(io, result, measurements, stopped, run) {
+  for (const delta of measurements?.time ?? []) {
+    io.out.write(
+      `${delta.name}  ${(delta.baseCenter * 1e9).toFixed(0)} -> ${(delta.candCenter * 1e9).toFixed(0)} ns/op  ` +
+        `${delta.pctChange >= 0 ? '+' : ''}${delta.pctChange.toFixed(2)}%  p=${delta.p.toFixed(5)}` +
+        `${delta.significant ? '' : '  (not significant)'}\n`,
+    )
+  }
+  for (const delta of measurements?.bytes ?? []) {
+    io.out.write(
+      `${delta.name}  ${delta.baseCenter.toFixed(0)} -> ${delta.candCenter.toFixed(0)} bytes/op  ` +
+        `${delta.pctChange >= 0 ? '+' : ''}${delta.pctChange.toFixed(2)}%  (approximate hint, never scored)\n`,
+    )
+  }
+  // Warnings go ABOVE the verdict: they qualify how far it can be read, and a
+  // reader who stops at the verdict line must not miss them.
+  for (const warning of result.warnings ?? []) io.out.write(`WARNING: ${warning}\n`)
+  io.out.write(`VERDICT: ${result.status} (${result.reason}) — ${result.message}\n`)
+  if (stopped) io.out.write('STOP REQUESTED: end the loop after applying this verdict\n')
+  if (run?.experiment) io.out.write(`experiment ${run.experiment} on ${run.branch}\n`)
+}
+
+/** The delta fields the agent and a human need, without internal detail. */
+const publicDelta = (d) => ({
+  name: d.name,
+  unit: d.unit,
+  base: d.baseCenter,
+  candidate: d.candCenter,
+  ratio: d.ratio,
+  pct_change: d.pctChange,
+  p: d.p,
+  significant: d.significant,
+})
+
+/** The largest single-benchmark improvement, in percent; 0 when unmeasured. */
+function bestDelta(deltas) {
+  if (!deltas || deltas.length === 0) return 0
+  return Math.min(...deltas.map((d) => d.pctChange))
+}

package/src/cli/cmd-init.js

@@ -0,0 +1,136 @@
+/**
+ * Scans the repository, discovers benchmarks, and writes the run
+ * configuration and the agent's instruction set.
+ *
+ * It writes files and commits NOTHING. `baseline` refuses an uncommitted
+ * tree, so the human commits what init produced — deliberately, because a
+ * baseline pinned against what is on disk rather than what is in git would
+ * not be reproducible.
+ */
+import { copyFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { CONFIG_PATH, defaultConfig } from '../config.js'
+import { baseNames, benchmarks } from '../discover.js'
+import { resolveRepo } from './context.js'
+
+const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates', 'program.md')
+
+/** Entries init adds to .gitignore, in order. */
+const IGNORE_ENTRIES = ['results.tsv', 'run.log', '.autor3search/*', '!.autor3search/config.yaml']
+
+export async function runInit(args, io) {
+  const { values } = parseArgs({
+    args,
+    options: { C: { type: 'string', default: '.' }, force: { type: 'boolean', default: false } },
+    allowPositionals: false,
+  })
+  const root = await resolveRepo(values.C)
+
+  const found = await benchmarks(root)
+  if (found.length === 0) {
+    // Refusing is deliberate. The verdict is entirely a function of the
+    // declared benchmarks' timings, so with none there is no signal to gate
+    // on — every candidate would be accepted or rejected for no reason.
+    io.err.write(
+      `no benchmarks found in ${root}.\n\n` +
+        `autor3search-javascript optimizes what it can measure, and refuses to guess. Write at least one\n` +
+        `Vitest benchmark covering the code you want made faster, in a *.bench.js file:\n\n` +
+        `    import { bench } from 'vitest'\n` +
+        `    import { thing } from './thing.js'\n\n` +
+        `    bench('thing', () => { thing() })\n\n` +
+        `Benchmark the path that actually dominates your workload — one that exercises a cold path or a\n` +
+        `trivial helper produces numbers that are entirely real and entirely useless. Then run init again.\n`,
+    )
+    return 2
+  }
+
+  const configPath = join(root, CONFIG_PATH)
+  const exists = await stat(configPath).then(
+    () => true,
+    () => false,
+  )
+  if (exists && !values.force) {
+    io.err.write(`${CONFIG_PATH} already exists; pass --force to overwrite it\n`)
+    return 2
+  }
+
+  await mkdir(dirname(configPath), { recursive: true })
+  await writeFile(configPath, renderConfig(baseNames(found)))
+  await copyFile(TEMPLATE, join(root, 'program.md'))
+  await addIgnoreEntries(join(root, '.gitignore'))
+
+  io.out.write(`discovered ${found.length} benchmark(s):\n`)
+  for (const b of found) io.out.write(`  ${b.path.padEnd(40)} ${b.file}\n`)
+  io.out.write(`\nwrote ${CONFIG_PATH}, program.md and .gitignore entries.\n`)
+  io.out.write(`next: git add -A && git commit -m "autor3search-javascript init"\n`)
+  io.out.write(`then: autor3search-javascript doctor && autor3search-javascript baseline -tag <tag>\n`)
+  return 0
+}
+
+/**
+ * Renders the config as commented YAML rather than serialising the defaults
+ * object: the comments are the documentation a human reads when deciding
+ * what to change, and they are the reason this file lives in the repository
+ * at all.
+ */
+function renderConfig(names) {
+  const d = defaultConfig()
+  return `# autor3search-javascript run configuration.
+#
+# This file is HUMAN-OWNED and version-controlled. Its hash is recorded at
+# baseline time, so any change during a run fails the run rather than
+# silently moving the goalposts.
+
+# The declared benchmark set. An empty list means every discovered benchmark.
+benchmarks:
+${names.map((n) => `  - ${JSON.stringify(n)}`).join('\n')}
+
+# Glob patterns the agent may edit. Everything else is rejected before an
+# experiment is even measured.
+scope:
+  - "**"
+
+# Measured rounds per side. Below 4 the significance test can never report
+# p < 0.05 however large the improvement, so every experiment would discard.
+# Capped at 1000: timeout bounds each measurement process, not the run, so a
+# stray zero here does not fail — it runs for days.
+count: ${d.count}
+
+# The largest tolerated significant regression, in percent.
+max_regress_pct: ${d.maxRegressPct}
+
+# The smallest geomean improvement a KEEP will accept, in percent.
+min_effect_pct: ${d.minEffectPct}
+
+# Bound on each subprocess phase.
+timeout: ${d.timeout}
+
+# Test or bench files deliberately exempt from freezing.
+unfreeze: []
+
+# The bench adapter. Only "vitest" is registered in this version.
+runner: ${d.runner}
+
+# Sample approximate bytes/op alongside the timings. Never scored.
+heap_hint: ${d.heapHint}
+
+# auto runs each gate when the repository is set up for it, on requires it,
+# off never runs it.
+gates:
+  typecheck: ${d.gates.typecheck}
+  lint: ${d.gates.lint}
+  test: ${d.gates.test}
+`
+}
+
+/** Appends any missing ignore entries, leaving existing content untouched. */
+async function addIgnoreEntries(path) {
+  const existing = await readFile(path, 'utf8').catch(() => '')
+  const lines = new Set(existing.split('\n').map((l) => l.trim()))
+  const missing = IGNORE_ENTRIES.filter((entry) => !lines.has(entry))
+  if (missing.length === 0) return
+  const prefix = existing === '' || existing.endsWith('\n') ? '' : '\n'
+  await writeFile(path, `${existing}${prefix}\n# autor3search-javascript\n${missing.join('\n')}\n`)
+}

package/src/cli/cmd-profile.js

@@ -0,0 +1,38 @@
+/** Profiles the declared benchmarks and prints where the time actually goes. */
+import { parseArgs } from 'node:util'
+import { profile } from '../profile.js'
+import { loadRepoConfig, resolveRepo } from './context.js'
+
+export async function runProfile(args, io) {
+  const { values } = parseArgs({
+    args,
+    options: { C: { type: 'string', default: '.' }, top: { type: 'string', default: '15' } },
+    allowPositionals: false,
+  })
+
+  const root = await resolveRepo(values.C)
+  const cfg = await loadRepoConfig(root)
+  const reports = await profile(root, cfg, { top: Number(values.top) })
+
+  for (const report of reports) {
+    io.out.write(`\n${report.file}\n`)
+    if (report.top.length === 0) {
+      io.out.write('  (no samples attributable to benchmarked code)\n')
+      continue
+    }
+    io.out.write(`${'self ms'.padStart(9)}  ${'%'.padStart(6)}  function\n`)
+    for (const entry of report.top) {
+      io.out.write(
+        `${entry.selfMs.toFixed(1).padStart(9)}  ${entry.pct.toFixed(1).padStart(6)}  ` +
+          `${entry.name}${entry.file ? `  (${entry.file})` : ''}\n`,
+      )
+    }
+    io.out.write(`\n  cpu   ${report.cpuProfile}\n`)
+    io.out.write(`  heap  ${report.heapProfile}\n`)
+  }
+  io.out.write(
+    '\nopen a .cpuprofile or .heapprofile in Chrome DevTools (Performance > Load profile) or at\n' +
+      'https://speedscope.app for a flame graph.\n',
+  )
+  return 0
+}

package/src/cli/cmd-report.js

@@ -0,0 +1,96 @@
+/**
+ * Summarizes results.tsv: what ran, what was kept, and how much faster.
+ *
+ * Cumulative speedup is the PRODUCT of every kept score, never the latest
+ * score and never an average. The harness re-points its measurement baseline
+ * at the commit just kept after every KEEP, so each kept `score` measures
+ * only that experiment's own incremental contribution — "did this change
+ * help, compared to the last thing we kept" — never "is the tree better than
+ * when the run started". Successive improvements compound the way
+ * percentage changes do, so multiplying is the only way to recover total
+ * progress; averaging or taking the last score would both understate a good
+ * night, in different ways.
+ *
+ * A DISCARD's score is real (it was measured) but was rejected, so it is
+ * excluded from the product — folding it in would invent progress that was
+ * explicitly not banked.
+ */
+import { join } from 'node:path'
+import { parseArgs } from 'node:util'
+import { RESULTS_PATH, loadRows } from '../results.js'
+import { resolveRepo } from './context.js'
+
+/** How many of the largest wins to list. */
+const TOP_N = 5
+
+/** Every status appendRow may write, in the order counted and printed. */
+const STATUSES = ['keep', 'discard', 'fail', 'crash']
+
+/**
+ * @param {string[]} args
+ * @param {{out: {write(s: string): void}, err: {write(s: string): void}}} io
+ * @returns {Promise<number>}
+ */
+export async function runReport(args, io) {
+  const { values } = parseArgs({
+    args,
+    options: { C: { type: 'string', default: '.' } },
+    allowPositionals: false,
+  })
+  const root = await resolveRepo(values.C)
+  const rows = await loadRows(join(root, RESULTS_PATH))
+
+  if (rows.length === 0) {
+    io.out.write(`no experiments recorded in ${RESULTS_PATH} yet — nothing to report\n`)
+    return 0
+  }
+
+  const counts = Object.fromEntries(STATUSES.map((s) => [s, 0]))
+  let other = 0
+  for (const row of rows) {
+    if (Object.hasOwn(counts, row.status)) counts[row.status]++
+    else other++
+  }
+
+  io.out.write('experiments\n')
+  for (const status of STATUSES) io.out.write(`  ${status.padEnd(10)} ${counts[status]}\n`)
+  if (other > 0) io.out.write(`  ${'other'.padEnd(10)} ${other}  (unrecognised status)\n`)
+  io.out.write(`  ${'total'.padEnd(10)} ${rows.length}\n\n`)
+
+  const kept = rows.filter((r) => r.status === 'keep')
+  if (kept.length === 0) {
+    io.out.write('nothing was kept — no measured improvement cleared the bar.\n')
+    return 0
+  }
+
+  // The PRODUCT of every kept score — see file header for why.
+  const cumulative = kept.reduce((acc, r) => acc * r.score, 1)
+  io.out.write(`cumulative speedup   ${cumulative.toFixed(4)}  (${formatMultiplier(cumulative)}, `)
+  io.out.write(`${formatPercent(cumulative)})\n`)
+  io.out.write(`  the product of all ${kept.length} kept score(s); discards do not contribute\n\n`)
+
+  io.out.write('largest individual wins\n')
+  for (const row of [...kept].sort((a, b) => a.score - b.score).slice(0, TOP_N)) {
+    io.out.write(
+      `  ${row.commit.padEnd(9)} ${row.score.toFixed(4)}  ` +
+        `${row.bestBenchDelta >= 0 ? '+' : ''}${row.bestBenchDelta.toFixed(1)}%  ${row.description}\n`,
+    )
+  }
+  return 0
+}
+
+/**
+ * The cumulative ratio as a human-readable "Nx faster". A ratio of exactly
+ * zero (a kept experiment measured at effectively zero cost) has no finite
+ * reciprocal — report that plainly instead of printing "Infinityx".
+ */
+function formatMultiplier(cumulative) {
+  if (cumulative <= 0) return 'immeasurably faster (measured cost of zero)'
+  return `${(1 / cumulative).toFixed(2)}x faster`
+}
+
+/** The cumulative ratio as a signed percent change, e.g. "-75.00%". */
+function formatPercent(cumulative) {
+  const pct = (cumulative - 1) * 100
+  return `${pct >= 0 ? '+' : ''}${pct.toFixed(2)}%`
+}

package/src/cli/cmd-status.js

@@ -0,0 +1,68 @@
+/**
+ * Prints where a run is. READ-ONLY: checking on a run must never change it,
+ * which is why nothing here writes, claims, or clears anything.
+ */
+import { join } from 'node:path'
+import { parseArgs } from 'node:util'
+import * as gitx from '../gitx.js'
+import { RESULTS_PATH, loadRows } from '../results.js'
+import { BASELINE_FILE, WORKTREE_NAME, loadBaseline } from '../state/index.js'
+import { evalRunning } from '../state/lock.js'
+import { stopRequested } from '../state/stop.js'
+import { expandSingleDashFlags, resolveRun } from './context.js'
+
+/**
+ * @param {string[]} args
+ * @param {{out: {write(s: string): void}, err: {write(s: string): void}}} io
+ * @returns {Promise<number>}
+ */
+export async function runStatus(args, io) {
+  const { values } = parseArgs({
+    args: expandSingleDashFlags(args, ['tag']),
+    options: { C: { type: 'string', default: '.' }, tag: { type: 'string' } },
+    allowPositionals: false,
+  })
+
+  const run = await resolveRun(values.C, values.tag)
+  const baseline = await loadBaseline(join(run.stateDir, BASELINE_FILE))
+  const current = await gitx.currentBranch(run.root)
+  const rows = await loadRows(join(run.root, RESULTS_PATH))
+  const counts = { keep: 0, discard: 0, fail: 0, crash: 0 }
+  for (const row of rows) if (row.status in counts) counts[row.status]++
+
+  // A corrupt pid file is an error `evalRunning` deliberately throws rather
+  // than guessing at — but a human reaching for `status` to see the REST of
+  // the run must never be stopped cold by that. Report the eval line as
+  // unreadable and keep going with everything else.
+  let evalLine
+  try {
+    const { pid, running } = await evalRunning(run.stateDir)
+    evalLine = running ? `running (pid ${pid}) — an experiment is being measured` : 'idle'
+  } catch (err) {
+    evalLine = `unknown (${err.message})`
+  }
+  const stopped = await stopRequested(run.stateDir)
+
+  const field = (name, value) => io.out.write(`${name.padEnd(14)} ${value}\n`)
+  field('run tag', run.tag)
+  field('branch', `${run.branch}  ${current === run.branch ? '(checked out)' : `(not checked out; on ${current})`}`)
+  field('baseline', `${baseline.commit}  (run started here)`)
+  field(
+    'measuring vs',
+    baseline.measureCommit === baseline.commit
+      ? `${baseline.measureCommit}  (unchanged — nothing kept yet)`
+      : `${baseline.measureCommit}  (advanced past the baseline by earlier KEEPs)`,
+  )
+  field('worktree', join(run.stateDir, WORKTREE_NAME))
+  field(
+    'experiments',
+    `${rows.length} run  (${counts.keep} keep, ${counts.discard} discard, ${counts.fail} fail, ` +
+      `${counts.crash} crash)  — next is #${rows.length + 1}`,
+  )
+  field('eval', evalLine)
+  field('stop', stopped ? 'requested — the agent will end the run after the current experiment' : 'not requested')
+
+  io.out.write('\nto stop after the current experiment:  autor3search-javascript stop\n')
+  io.out.write('to stop now, abandoning it:            autor3search-javascript stop --force\n')
+  return 0
+}

package/src/cli/cmd-stop.js

@@ -0,0 +1,98 @@
+/**
+ * Asks the agent to end the run.
+ *
+ * Plain `stop` is the one to use: it writes a request `eval` reports back, so
+ * the experiment under way finishes and is scored, its verdict is applied,
+ * and only then does the loop exit. Nothing is thrown away.
+ *
+ * `--force` is for when a long benchmark cannot be waited out. It writes the
+ * same request, then signals the running eval to abandon the experiment. It
+ * REPORTS what state that leaves the repository in; it does not drop anything
+ * for you, because deciding what to do with a half-finished experiment is the
+ * human's call.
+ */
+import { parseArgs } from 'node:util'
+import * as gitx from '../gitx.js'
+import { evalRunning } from '../state/lock.js'
+import { clearStop, requestStop } from '../state/stop.js'
+import { expandSingleDashFlags, resolveRun } from './context.js'
+
+/**
+ * @param {string[]} args
+ * @param {{out: {write(s: string): void}, err: {write(s: string): void}}} io
+ * @returns {Promise<number>}
+ */
+export async function runStop(args, io) {
+  const { values } = parseArgs({
+    args: expandSingleDashFlags(args, ['tag']),
+    options: {
+      C: { type: 'string', default: '.' },
+      tag: { type: 'string' },
+      clear: { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  })
+
+  if (values.clear && values.force) {
+    io.err.write('--clear and --force ask for opposite things; pass one or the other\n')
+    return 2
+  }
+
+  const run = await resolveRun(values.C, values.tag)
+
+  if (values.clear) {
+    await clearStop(run.stateDir)
+    io.out.write(`stop request for ${run.tag} cancelled — the loop may continue\n`)
+    return 0
+  }
+
+  await requestStop(run.stateDir)
+  io.out.write(`stop requested for ${run.tag}: the agent will end the run after the current experiment\n`)
+  if (!values.force) {
+    io.out.write('the experiment under way will still be measured, scored and applied\n')
+    io.out.write(`to cancel: autor3search-javascript stop -tag ${run.tag} --clear\n`)
+    return 0
+  }
+
+  // A corrupt pid file must not crash `stop --force` — it is refused by
+  // evalRunning rather than guessed at, but the request above already stands
+  // regardless, so fall back to "nothing known to signal" and keep going.
+  let pid = null
+  let running = false
+  try {
+    ;({ pid, running } = await evalRunning(run.stateDir))
+  } catch (err) {
+    io.err.write(`could not read the eval lock (${err.message}); assuming there is nothing to signal\n`)
+  }
+
+  if (running) {
+    // SIGTERM, not SIGKILL: eval installs a handler that tears down its child
+    // process groups. Killing it outright would leave Vitest workers running,
+    // burning CPU and corrupting every later measurement on this machine.
+    try {
+      process.kill(pid, 'SIGTERM')
+      io.out.write(`signalled eval (pid ${pid}) to abandon the current experiment\n`)
+    } catch (err) {
+      io.err.write(`could not signal eval (pid ${pid}): ${err.message}\n`)
+    }
+  } else {
+    io.out.write('no eval is running, so there was nothing to interrupt — the request stands\n')
+  }
+
+  // Report, do not act — whether or not anything was actually interrupted,
+  // this is what the repository looks like right now. The commit an
+  // abandoned experiment made, if any, is still on the branch and nothing
+  // scored it; dropping it is the human's call, not this command's.
+  const branch = await gitx.currentBranch(run.root).catch(() => 'unknown')
+  const head = await gitx.headCommit(run.root).catch(() => 'unknown')
+  const subject = await gitx.headSubject(run.root).catch(() => '')
+  io.out.write('\nwhat this leaves you with:\n')
+  io.out.write(`  branch    ${branch}\n`)
+  io.out.write(`  HEAD      ${head}  ${subject}\n`)
+  io.out.write('  no results.tsv row is written for an experiment interrupted this way\n')
+  io.out.write('\nHEAD may be the commit for an experiment nothing scored. If it is, drop it yourself:\n')
+  io.out.write('  git reset --hard HEAD~1\n')
+  io.out.write('Every commit kept before it is untouched.\n')
+  return 0
+}