akm-cli 0.7.0-rc1 → 0.7.0

package/dist/tests/bench/cleanup.js

@@ -31,6 +31,37 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { warn } from "../../src/core/warn";
 import { benchTmpRoot } from "./tmp";
+/**
+ * Register a process-group kill for a spawned opencode PID.
+ *
+ * On SIGINT/SIGTERM the bench driver must kill the entire opencode process
+ * group (not just the node wrapper) so .opencode children don't become orphans
+ * that keep pipes open and block subsequent runs.
+ *
+ * Call this immediately after spawning opencode. Returns a deregister thunk
+ * that should be called once the process has exited (in the run's finally
+ * block).
+ *
+ * The SIGKILL is sent to the process group (`-pid`) if available, falling back
+ * to the individual PID for environments where group-kill is unavailable.
+ */
+export function registerProcessGroupCleanup(pid) {
+    const fn = () => {
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            // Process group may not exist (process already exited or pid unavailable).
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    };
+    return registerCleanup(fn);
+}
 const registry = {
     fns: new Set(),
     installed: false,

package/dist/tests/bench/cli.js

@@ -7,6 +7,7 @@
  *   • `compare`    — diff two report JSON files; refuses on hash/model mismatch.
  *   • `attribute`  — per-asset marginal contribution via leave-one-out masking.
  *   • `evolve`     — longitudinal evolution loop (Track B). Stub.
+ *   • `kill`       — send SIGTERM to a running bench process (reads bench.pid).
  *
  * Implementation status and validity rules live in `tests/bench/BENCH.md`.
  *
@@ -15,31 +16,56 @@
  * hand-rolled parser keeps the dependency graph tight.
  */
 import fs from "node:fs";
+import path from "node:path";
 import process from "node:process";
+import { getCacheDir } from "../../src/core/paths";
 import { listTasks } from "./corpus";
 import { runEvolve } from "./evolve";
 import { compareReports, rehydrateRunFromSerialized, runMaskedCorpus, } from "./metrics";
+import { BenchConfigError, loadOpencodeProviders } from "./opencode-config";
 import { renderAttributionTable, renderCompareMarkdown, renderEvolveReport, renderUtilityReport, } from "./report";
+import { loadBenchRunConfig } from "./run-config";
 import { runUtility } from "./runner";
+import { isPidRunning, readBenchPid, writeBenchPid } from "./tmp";
 const HELP = `akm-bench — agent-plus-akm evaluation framework
 
 Usage:
+  bun run tests/bench/cli.ts <config.json> [--json] [--seeds N] [--parallel N] [--tasks <list>]
   bun run tests/bench/cli.ts <subcommand> [...flags]
 
-Subcommands:
+Config-file mode (recommended):
+  Pass a path to a tests/bench/configs/*.json file as the first argument.
+  See tests/bench/BENCH.md for the run-config schema and provider
+  discovery chain (BENCH_OPENCODE_CONFIG → providers/providersRef →
+  ~/.config/akm/bench-providers.json).
+
+Subcommands (legacy; still supported):
   utility       Track A: paired noakm vs akm utility benchmark.
   evolve        Track B: longitudinal feedback → distill → propose loop.
   compare       Diff two report JSON files (refuses cross-model diffs).
   attribute     Per-asset marginal pass-rate contribution.
+  kill          Send SIGTERM to a running bench process (reads bench.pid).
+  clean         Remove all bench tmp dirs under \${AKM_CACHE_DIR}/bench/.
 
 utility flags:
   --tasks <slice>          train | eval | all  (default: all)
   --seeds <N>              seeds per arm  (default: 5)
   --budget-tokens <N>      per-run token cap (default: 30000)
   --budget-wall-ms <N>     per-run wallclock cap in ms (default: 120000)
+  --parallel <N>           number of (task, arm, seed) triples to run concurrently
+                           (default: 1 — sequential). Clamped to [1, 8]. Values > 4
+                           print a warning unless --force-parallel is also set.
+  --force-parallel         suppress the high-parallelism warning when --parallel > 4.
+  --no-noakm               exclude the noakm baseline arm (default: included). The noakm arm is
+                           the control condition — pass_rate(akm) − pass_rate(noakm) is the
+                           primary utility metric. Omit only when you are measuring workflow
+                           compliance rather than marginal utility.
   --include-synthetic      add a third 'synthetic' arm where the model writes/uses its own
                            scratch notes (no AKM stash). Reports akm_over_synthetic_lift so
                            operators can see whether AKM beats a self-notes baseline.
+  --opencode-config <path> path to a bench opencode providers JSON file. Auto-discovered
+                           from BENCH_OPENCODE_CONFIG env var or the fixture defaults when
+                           omitted. See BENCH.md for the discovery order.
   --json                   suppress the markdown summary on stderr (machine-readable only).
                            Without --json, JSON still goes to stdout and the markdown
                            summary is also written to stderr for human-friendly reads.
@@ -50,8 +76,11 @@ evolve flags:
   --seeds <N>              seeds per arm (default: 5)
   --budget-tokens <N>      per-run token cap (default: 30000)
   --budget-wall-ms <N>     per-run wallclock cap in ms (default: 120000)
+  --parallel <N>           same as utility --parallel (default: 1).
+  --force-parallel         suppress the high-parallelism warning when --parallel > 4.
   --negative-threshold-count <N>  absolute negative-feedback count to evolve (default: 2)
   --negative-threshold-ratio <R>  ratio of negatives to total feedback (default: 0.5)
+  --opencode-config <path> path to a bench opencode providers JSON file (same as utility).
   --json                   suppress the markdown summary on stderr.
 
 compare flags:
@@ -71,10 +100,26 @@ compare flags:
 attribute flags:
   --base <path>            path to a §13.3 utility run JSON (required).
   --top <N>                number of top-loaded assets to mask (default: 5; clamped).
+  --opencode-config <path> path to a bench opencode providers JSON file (same as utility).
   --json                   suppress the markdown summary on stderr.
 
+kill flags:
+  (none)        Reads \${AKM_CACHE_DIR}/bench/bench.pid and sends SIGTERM.
+                Prints "no bench running" and exits 0 when the PID file is absent.
+                Run again (or press Ctrl-C) to escalate to SIGKILL.
+
 Environment:
-  BENCH_OPENCODE_MODEL   model id stamped into every RunResult. REQUIRED for utility.
+  BENCH_OPENCODE_MODEL      model id stamped into every RunResult. REQUIRED for utility/evolve
+                            unless the loaded providers file supplies a defaultModel.
+  BENCH_OPENCODE_CONFIG     path to the bench opencode providers JSON file. Overrides the
+                            default fixture; overridden by --opencode-config flag.
+
+Auto-discovery order for --opencode-config (first existing file wins):
+  1. --opencode-config <path>  flag value
+  2. BENCH_OPENCODE_CONFIG     env var
+  3. tests/fixtures/bench/opencode-providers.local.json  (gitignored operator overlay)
+  4. tests/fixtures/bench/opencode-providers.json        (committed fixture)
+  5. None found → empty isolated dir, opencode uses cloud-provider defaults.
 
 See tests/bench/BENCH.md for the operator guide.
 `;
@@ -114,6 +159,58 @@ function parseArgs(argv) {
     }
     return { subcommand, flags, bool, positional };
 }
+/**
+ * Absolute path to the committed default bench opencode providers fixture.
+ * Used as the final fallback in the auto-discovery chain.
+ */
+const DEFAULT_PROVIDERS_PATH = path.resolve(__dirname, "..", "fixtures", "bench", "opencode-providers.json");
+/**
+ * Absolute path to the gitignored operator overlay. Takes precedence over
+ * the committed fixture when it exists.
+ */
+const LOCAL_PROVIDERS_PATH = path.resolve(__dirname, "..", "fixtures", "bench", "opencode-providers.local.json");
+/**
+ * Auto-discover and load the bench opencode providers file.
+ *
+ * Discovery order (first existing file wins):
+ *   1. `flagPath`  — `--opencode-config` flag value (already resolved by caller).
+ *   2. `BENCH_OPENCODE_CONFIG` env var.
+ *   3. `tests/fixtures/bench/opencode-providers.local.json` (gitignored overlay).
+ *   4. `tests/fixtures/bench/opencode-providers.json` (committed fixture).
+ *   5. None found → returns `undefined` (empty isolated dir, cloud-provider fallback).
+ *
+ * When a file is found but fails to load, the BenchConfigError is re-thrown
+ * so the caller can map it to the correct exit code.
+ */
+export function discoverOpencodeProviders(flagPath) {
+    const candidates = [
+        flagPath,
+        getEnv("BENCH_OPENCODE_CONFIG"),
+        LOCAL_PROVIDERS_PATH,
+        DEFAULT_PROVIDERS_PATH,
+    ];
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        const absPath = path.isAbsolute(candidate) ? candidate : path.resolve(candidate);
+        if (fs.existsSync(absPath)) {
+            // Throws BenchConfigError on validation failure; callers propagate it.
+            return loadOpencodeProviders(absPath);
+        }
+        // When a flag or env-var path was given explicitly but doesn't exist,
+        // treat it as a usage error rather than silently skipping to the next
+        // candidate. Only the auto-discovered defaults (local + committed) are
+        // silently skipped when absent.
+        if (candidate === flagPath && flagPath) {
+            // This throws with isUsageError: true (file not found).
+            return loadOpencodeProviders(absPath);
+        }
+        if (candidate === getEnv("BENCH_OPENCODE_CONFIG") && candidate) {
+            return loadOpencodeProviders(absPath);
+        }
+    }
+    return undefined;
+}
 /**
  * `utility` subcommand. Walks the corpus, runs K seeds per arm per task,
  * and produces the §13.3 report.
@@ -124,9 +221,13 @@ function parseArgs(argv) {
 export async function runUtilityCli(options) {
     const sliceFilter = options.slice === "all" ? undefined : options.slice;
     const tasks = listTasks(sliceFilter ? { slice: sliceFilter } : {});
+    // noakm arm is included by default: it is the control condition for the
+    // primary utility metric (pass_rate(akm) − pass_rate(noakm), spec §4).
+    // Pass --no-noakm (options.includeNoakm === false) to exclude it.
+    const arms = options.includeNoakm === false ? ["akm"] : ["noakm", "akm"];
     const report = await runUtility({
         tasks,
-        arms: ["noakm", "akm"],
+        arms,
         model: options.model,
         seedsPerArm: options.seedsPerArm,
         budgetTokens: options.budgetTokens,
@@ -135,9 +236,12 @@ export async function runUtilityCli(options) {
         // #261: thread the synthetic-arm gate. Default off — the envelope shape
         // is byte-identical to the pre-#261 output unless the operator opts in.
         ...(options.includeSynthetic ? { includeSynthetic: true } : {}),
+        ...(options.parallel !== undefined ? { parallel: options.parallel } : {}),
+        ...(options.forceParallel ? { forceParallel: true } : {}),
         ...(options.branch !== undefined ? { branch: options.branch } : {}),
         ...(options.commit !== undefined ? { commit: options.commit } : {}),
         ...(options.timestamp !== undefined ? { timestamp: options.timestamp } : {}),
+        ...(options.opencodeProviders ? { opencodeProviders: options.opencodeProviders } : {}),
     });
     const { json, markdown } = renderUtilityReport(report);
     const jsonText = `${JSON.stringify(json, null, 2)}\n`;
@@ -413,6 +517,7 @@ function extractCorpusMetrics(envelope, key) {
     return {
         passRate: typeof node.pass_rate === "number" ? node.pass_rate : 0,
         tokensPerPass: node.tokens_per_pass === null ? null : typeof node.tokens_per_pass === "number" ? node.tokens_per_pass : null,
+        tokensPerRun: node.tokens_per_run === null ? null : typeof node.tokens_per_run === "number" ? node.tokens_per_run : null,
         wallclockMs: typeof node.wallclock_ms === "number" ? node.wallclock_ms : 0,
     };
 }
@@ -536,6 +641,101 @@ function parseFloatArg(text, fallback) {
         return fallback;
     return n;
 }
+/**
+ * Set of obsolete-flag names that have already emitted their stderr
+ * warning during this process. Used by `warnObsolete` to dedupe.
+ *
+ * Exported as a test seam so unit tests can clear the cache between
+ * cases without restarting the process.
+ */
+export const obsoleteFlagWarned = new Set();
+/**
+ * Emit a one-line `[obsolete] ...` warning on stderr the FIRST time the
+ * named flag is used in this process. Subsequent calls with the same
+ * `name` are silent so a single invocation never emits the same warning
+ * twice. Internal: wired into the existing utility/evolve dispatch
+ * branches; the new config-file path never triggers these.
+ */
+function warnObsolete(name, replacement) {
+    if (obsoleteFlagWarned.has(name))
+        return;
+    obsoleteFlagWarned.add(name);
+    process.stderr.write(`[obsolete] ${name} → ${replacement}\n`);
+}
+/**
+ * Detect whether the user supplied any of the flags marked obsolete in
+ * BENCH.md §G and emit one warning per used flag. The flags continue to
+ * function — the warning is the only behavior change.
+ */
+function warnIfObsoleteFlagsUsed(parsed) {
+    if (parsed.bool.has("no-noakm")) {
+        warnObsolete("--no-noakm", 'use `arms: ["akm"]` in a run config');
+    }
+    if (parsed.bool.has("include-synthetic")) {
+        warnObsolete("--include-synthetic", 'use `arms: [..., "synthetic"]` in a run config');
+    }
+    if (parsed.flags.has("opencode-config")) {
+        warnObsolete("--opencode-config", "use `providersRef` in a run config, BENCH_OPENCODE_CONFIG, or ~/.config/akm/bench-providers.json");
+    }
+    if (parsed.flags.has("budget-tokens")) {
+        warnObsolete("--budget-tokens", "use `budgetTokens` in a run config");
+    }
+    if (parsed.flags.has("budget-wall-ms")) {
+        warnObsolete("--budget-wall-ms", "use `budgetWallMs` in a run config");
+    }
+}
+/**
+ * `<config.json>` dispatch — load a bench run config, resolve providers
+ * and tasks, invoke `runUtility`, and emit the §13.3 envelope on stdout.
+ *
+ * Behaves identically to `runUtilityCli` from a stdout/stderr/exit-code
+ * standpoint: JSON on stdout, optional markdown summary on stderr,
+ * returns 0/2/78 mirroring the existing semantics.
+ */
+export async function runConfigCli(options) {
+    let resolved;
+    try {
+        const overrides = {};
+        if (options.tasksList)
+            overrides.tasksList = options.tasksList;
+        if (options.seedsPerArm !== undefined)
+            overrides.seedsPerArm = options.seedsPerArm;
+        if (options.parallel !== undefined)
+            overrides.parallel = options.parallel;
+        resolved = loadBenchRunConfig(options.configPath, overrides);
+    }
+    catch (err) {
+        const exitCode = err instanceof BenchConfigError && err.isUsageError ? 2 : 78;
+        return {
+            exitCode,
+            stdout: "",
+            stderr: `bench: ${err instanceof Error ? err.message : String(err)}\n`,
+        };
+    }
+    const report = await runUtility({
+        tasks: resolved.tasks,
+        arms: resolved.arms,
+        model: resolved.model,
+        slice: resolved.slice,
+        ...(resolved.seedsPerArm !== undefined ? { seedsPerArm: resolved.seedsPerArm } : {}),
+        ...(resolved.budgetTokens !== undefined ? { budgetTokens: resolved.budgetTokens } : {}),
+        ...(resolved.budgetWallMs !== undefined ? { budgetWallMs: resolved.budgetWallMs } : {}),
+        ...(resolved.parallel !== undefined ? { parallel: resolved.parallel } : {}),
+        ...(resolved.forceParallel ? { forceParallel: true } : {}),
+        ...(resolved.baselineByTaskId ? { baselineByTaskId: resolved.baselineByTaskId } : {}),
+        ...(options.timestamp !== undefined ? { timestamp: options.timestamp } : {}),
+        ...(options.branch !== undefined ? { branch: options.branch } : {}),
+        ...(options.commit !== undefined ? { commit: options.commit } : {}),
+        opencodeProviders: resolved.providers,
+        // Synthetic arm follows from `arms` containing "synthetic".
+        ...(resolved.arms.includes("synthetic") ? { includeSynthetic: true } : {}),
+    });
+    const { json, markdown } = renderUtilityReport(report);
+    const stdout = `${JSON.stringify(json, null, 2)}\n`;
+    let stderr = options.json ? "" : `${markdown}\n`;
+    stderr += `bench: config=${resolved.name} tasks=${resolved.tasks.length} arms=${resolved.arms.join(",")} model=${resolved.model}\n`;
+    return { exitCode: 0, stdout, stderr };
+}
 /**
  * `evolve` subcommand. Filters the corpus to one domain (or `all`), then
  * dispatches `runEvolve` and renders the §6.3+§6.4 envelope.
@@ -574,6 +774,43 @@ async function main(argv) {
         process.stdout.write(HELP);
         return parsed.subcommand === "" ? 2 : 0;
     }
+    // Config-file dispatch: when argv[0] looks like a JSON path that exists,
+    // route to `runConfigCli`. This is the new common-case entry point —
+    // existing subcommand-style invocations are untouched.
+    if (parsed.subcommand.endsWith(".json") && fs.existsSync(parsed.subcommand)) {
+        const tasksRaw = parsed.flags.get("tasks");
+        const tasksList = tasksRaw
+            ? tasksRaw
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0)
+            : undefined;
+        const seedsRaw = parsed.flags.get("seeds");
+        const parallelRaw = parsed.flags.get("parallel");
+        const removePid = writeBenchPid();
+        let result;
+        try {
+            result = await runConfigCli({
+                configPath: parsed.subcommand,
+                json: parsed.bool.has("json"),
+                ...(tasksList ? { tasksList } : {}),
+                ...(seedsRaw !== undefined ? { seedsPerArm: parseInt32(seedsRaw, 5) } : {}),
+                ...(parallelRaw !== undefined ? { parallel: parseInt32(parallelRaw, 1) } : {}),
+            });
+        }
+        finally {
+            removePid();
+        }
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        return result.exitCode;
+    }
+    // Emit obsolete-flag warnings for the legacy subcommand path. The new
+    // config-file path above never reaches this code so config-mode runs
+    // never spuriously warn.
+    warnIfObsoleteFlagsUsed(parsed);
     switch (parsed.subcommand) {
         case "utility": {
             const sliceRaw = parsed.flags.get("tasks") ?? "all";
@@ -582,20 +819,43 @@ async function main(argv) {
                 return 2;
             }
             const slice = sliceRaw;
-            const model = getEnv("BENCH_OPENCODE_MODEL");
+            // Load provider config at CLI startup (before any runs).
+            let opencodeProviders;
+            try {
+                opencodeProviders = discoverOpencodeProviders(parsed.flags.get("opencode-config"));
+            }
+            catch (err) {
+                const exitCode = err instanceof BenchConfigError && err.isUsageError ? 2 : 78;
+                process.stderr.write(`bench utility: ${err instanceof Error ? err.message : String(err)}\n`);
+                return exitCode;
+            }
+            // BENCH_OPENCODE_MODEL: flag → env var → loaded.defaultModel → error exit 2.
+            const model = getEnv("BENCH_OPENCODE_MODEL") ?? opencodeProviders?.defaultModel;
             if (!model) {
                 process.stderr.write("bench utility: BENCH_OPENCODE_MODEL environment variable is required.\n");
                 return 2;
             }
-            const result = await runUtilityCli({
-                slice,
-                json: parsed.bool.has("json"),
-                seedsPerArm: parseInt32(parsed.flags.get("seeds"), 5),
-                budgetTokens: parseInt32(parsed.flags.get("budget-tokens"), 30000),
-                budgetWallMs: parseInt32(parsed.flags.get("budget-wall-ms"), 120000),
-                model,
-                ...(parsed.bool.has("include-synthetic") ? { includeSynthetic: true } : {}),
-            });
+            // Write PID file so `bench kill` can terminate this run.
+            const removePid = writeBenchPid();
+            let result;
+            try {
+                result = await runUtilityCli({
+                    slice,
+                    json: parsed.bool.has("json"),
+                    seedsPerArm: parseInt32(parsed.flags.get("seeds"), 5),
+                    budgetTokens: parseInt32(parsed.flags.get("budget-tokens"), 30000),
+                    budgetWallMs: parseInt32(parsed.flags.get("budget-wall-ms"), 120000),
+                    model,
+                    parallel: parseInt32(parsed.flags.get("parallel"), 1),
+                    ...(parsed.bool.has("force-parallel") ? { forceParallel: true } : {}),
+                    ...(parsed.bool.has("include-synthetic") ? { includeSynthetic: true } : {}),
+                    ...(parsed.bool.has("no-noakm") ? { includeNoakm: false } : {}),
+                    ...(opencodeProviders ? { opencodeProviders } : {}),
+                });
+            }
+            finally {
+                removePid();
+            }
             if (result.stdout)
                 process.stdout.write(result.stdout);
             if (result.stderr)
@@ -608,28 +868,49 @@ async function main(argv) {
                 process.stderr.write("bench evolve: --tasks <domain> is required (use --tasks all to run the full corpus).\n");
                 return 2;
             }
-            const model = getEnv("BENCH_OPENCODE_MODEL");
+            // Load provider config at CLI startup (before any runs).
+            let opencodeProvidersEvolve;
+            try {
+                opencodeProvidersEvolve = discoverOpencodeProviders(parsed.flags.get("opencode-config"));
+            }
+            catch (err) {
+                const exitCode = err instanceof BenchConfigError && err.isUsageError ? 2 : 78;
+                process.stderr.write(`bench evolve: ${err instanceof Error ? err.message : String(err)}\n`);
+                return exitCode;
+            }
+            const model = getEnv("BENCH_OPENCODE_MODEL") ?? opencodeProvidersEvolve?.defaultModel;
             if (!model) {
                 process.stderr.write("bench evolve: BENCH_OPENCODE_MODEL environment variable is required.\n");
                 return 2;
             }
-            const result = await runEvolveCli({
-                domain,
-                json: parsed.bool.has("json"),
-                seedsPerArm: parseInt32(parsed.flags.get("seeds"), 5),
-                budgetTokens: parseInt32(parsed.flags.get("budget-tokens"), 30000),
-                budgetWallMs: parseInt32(parsed.flags.get("budget-wall-ms"), 120000),
-                model,
-                negativeThreshold: {
-                    absoluteCount: parseInt32(parsed.flags.get("negative-threshold-count"), 2),
-                    ratio: parseFloatArg(parsed.flags.get("negative-threshold-ratio"), 0.5),
-                },
-            });
-            if (result.stdout)
-                process.stdout.write(result.stdout);
-            if (result.stderr)
-                process.stderr.write(result.stderr);
-            return result.exitCode;
+            // Write PID file so `bench kill` can terminate this run.
+            const removePidEvolve = writeBenchPid();
+            let resultEvolve;
+            try {
+                resultEvolve = await runEvolveCli({
+                    domain,
+                    json: parsed.bool.has("json"),
+                    seedsPerArm: parseInt32(parsed.flags.get("seeds"), 5),
+                    budgetTokens: parseInt32(parsed.flags.get("budget-tokens"), 30000),
+                    budgetWallMs: parseInt32(parsed.flags.get("budget-wall-ms"), 120000),
+                    model,
+                    parallel: parseInt32(parsed.flags.get("parallel"), 1),
+                    ...(parsed.bool.has("force-parallel") ? { forceParallel: true } : {}),
+                    negativeThreshold: {
+                        absoluteCount: parseInt32(parsed.flags.get("negative-threshold-count"), 2),
+                        ratio: parseFloatArg(parsed.flags.get("negative-threshold-ratio"), 0.5),
+                    },
+                    ...(opencodeProvidersEvolve ? { opencodeProviders: opencodeProvidersEvolve } : {}),
+                });
+            }
+            finally {
+                removePidEvolve();
+            }
+            if (resultEvolve.stdout)
+                process.stdout.write(resultEvolve.stdout);
+            if (resultEvolve.stderr)
+                process.stderr.write(resultEvolve.stderr);
+            return resultEvolve.exitCode;
         }
         case "compare": {
             const basePath = parsed.flags.get("base");
@@ -657,6 +938,19 @@ async function main(argv) {
                 process.stderr.write("bench attribute: --base <path> is required.\n");
                 return 2;
             }
+            // Load provider config for parity (attribute re-runs use the same model + provider).
+            let opencodeProvidersAttr;
+            try {
+                opencodeProvidersAttr = discoverOpencodeProviders(parsed.flags.get("opencode-config"));
+            }
+            catch (err) {
+                const exitCode = err instanceof BenchConfigError && err.isUsageError ? 2 : 78;
+                process.stderr.write(`bench attribute: ${err instanceof Error ? err.message : String(err)}\n`);
+                return exitCode;
+            }
+            // Suppress unused variable warning — opencodeProvidersAttr is exposed for
+            // future wiring when runMaskedCorpus accepts it. For now it only validates.
+            void opencodeProvidersAttr;
             const topN = parseInt32(parsed.flags.get("top"), 5);
             const result = await runAttributeCli({
                 basePath,
@@ -669,6 +963,47 @@ async function main(argv) {
                 process.stderr.write(result.stderr);
             return result.exitCode;
         }
+        case "kill": {
+            const pid = readBenchPid();
+            if (pid === undefined) {
+                process.stdout.write("no bench running\n");
+                return 0;
+            }
+            if (!isPidRunning(pid)) {
+                process.stdout.write(`no bench running (stale PID file for PID ${pid} — cleaning up)\n`);
+                try {
+                    const { benchPidPath } = await import("./tmp");
+                    const { default: nodeFs } = await import("node:fs");
+                    nodeFs.rmSync(benchPidPath(), { force: true });
+                }
+                catch {
+                    /* best-effort */
+                }
+                return 0;
+            }
+            try {
+                process.kill(pid, "SIGTERM");
+                process.stdout.write(`sent SIGTERM to bench process ${pid}\n`);
+                process.stdout.write("run `bench kill` again to escalate to SIGKILL if the process does not exit.\n");
+            }
+            catch (err) {
+                process.stderr.write(`bench kill: failed to signal PID ${pid}: ${err instanceof Error ? err.message : String(err)}\n`);
+                return 1;
+            }
+            return 0;
+        }
+        case "clean": {
+            const benchRoot = path.join(getCacheDir(), "bench");
+            try {
+                fs.rmSync(benchRoot, { recursive: true, force: true });
+                process.stderr.write(`bench clean: removed ${benchRoot}\n`);
+            }
+            catch (err) {
+                process.stderr.write(`bench clean: failed to remove ${benchRoot}: ${err.message}\n`);
+                return 1;
+            }
+            return 0;
+        }
         default:
             process.stderr.write(`unknown subcommand: ${parsed.subcommand}\n`);
             process.stderr.write(HELP);