modelrig 0.0.1 → 0.2.0

package/dist/cli.js

@@ -0,0 +1,590 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * modelrig CLI — Phase 3 plan §3 + Phase 4 plan §3:
+ *   modelrig bakeoff --route X --variants a,b,c --replay-last N
+ *     [--budget-usd usd] [--json] [--no-mirror]   (--envelope is a kept alias)
+ *   modelrig bakeoff --from-proposal <id> [--replay-last N] [--json]
+ *   modelrig watch run [--events fixtures.json] [--json]
+ *
+ * Bake-offs replay locally captured traffic, write the artifact JSON next
+ * to the telemetry db (.modelrig/bakeoffs/<id>.json), upsert the `bakeoffs`
+ * mirror when the Supabase sink is configured, and print the matrix.
+ * Captures never travel — only aggregate metrics. Watch cycles spend $0;
+ * --from-proposal runs draw from the monthly watch envelope and attach
+ * their evidence to the proposal (suggested → evidenced). Nothing here
+ * executes a swap — that is `modelrig swap execute --approve`, a separate,
+ * human command.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.main = main;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const init_cli_1 = require("./init/init-cli");
+const observe_cli_1 = require("./init/observe-cli");
+const failures_1 = require("./types/failures");
+const failures_teaching_1 = require("./types/failures-teaching");
+const config_1 = require("./config");
+const index_1 = require("./index");
+const status_1 = require("./status");
+const engine_1 = require("./bakeoff/engine");
+const samples_1 = require("./bakeoff/samples");
+const report_1 = require("./bakeoff/report");
+const cli_run_1 = require("./verify/cli-run");
+const loader_1 = require("./routes/loader");
+const validate_cli_1 = require("./validate-cli");
+const store_1 = require("./telemetry/store");
+const budget_1 = require("./watch/budget");
+const proposals_1 = require("./watch/proposals");
+const run_reported_1 = require("./watch/run-reported");
+const state_1 = require("./watch/state");
+const state_store_1 = require("./watch/state-store");
+const swaps_client_1 = require("./savings/swaps-client");
+const swap_execute_1 = require("./savings/swap-execute");
+const BARE_FLAGS = new Set([
+    "json",
+    "no-mirror",
+    "approve",
+    "keep-outputs",
+    "keep-outputs=all",
+    // modelrig init (Phase 5 WS2)
+    "dry-run",
+    "include-tests",
+    // modelrig observe / init --observe (T0/T1 scaffold)
+    "observe",
+]);
+function parseArgs(argv) {
+    const positional = [];
+    const named = new Map();
+    const bare = new Set();
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2);
+            if (BARE_FLAGS.has(name)) {
+                bare.add(name);
+                continue;
+            }
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error(`flag ${arg} needs a value`);
+            }
+            named.set(name, value);
+            i += 1;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, named, bare };
+}
+/** Control-plane client from config.export — the watch/proposal surfaces
+ * need it; a clear error beats a silent no-op. */
+function proposalsClientFrom(config) {
+    const exp = (0, config_1.directExportOf)(config, "this command");
+    return (0, proposals_1.createProposalsClient)({
+        supabaseUrl: exp.supabaseUrl,
+        serviceRoleKey: exp.serviceRoleKey,
+    });
+}
+/** A3: --keep-outputs (winner) | --keep-outputs=all | off. */
+function keepOutputsMode(flags) {
+    if (flags.bare.has("keep-outputs=all"))
+        return "all";
+    if (flags.bare.has("keep-outputs"))
+        return "winner";
+    return undefined;
+}
+async function runAndReportBakeoff(config, flags, route, variants, replayLastN, envelope) {
+    const keep = keepOutputsMode(flags);
+    if (keep !== undefined)
+        (0, config_1.directExportOf)(config, "--keep-outputs (bakeoff_samples lives there)");
+    const mirrorTarget = config.export?.mode === "direct" ? config.export : undefined;
+    const rig = (0, index_1.createRig)(config);
+    try {
+        const artifact = await rig.bakeoff(route, {
+            variants,
+            replayLastN,
+            ...(envelope !== undefined ? { envelopeUsdPerVariant: envelope } : {}),
+            ...(keep !== undefined ? { keepOutputs: keep } : {}),
+        });
+        const outDir = (0, node_path_1.join)((0, node_path_1.dirname)(config.telemetryDbPath), "bakeoffs");
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+        const artifactPath = (0, node_path_1.join)(outDir, `${artifact.id}.json`);
+        (0, node_fs_1.writeFileSync)(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`);
+        let mirrored = false;
+        if (mirrorTarget !== undefined && !flags.bare.has("no-mirror")) {
+            await (0, engine_1.mirrorBakeoff)(artifact, {
+                supabaseUrl: mirrorTarget.supabaseUrl,
+                serviceRoleKey: mirrorTarget.serviceRoleKey,
+                sourceId: mirrorTarget.sourceId ?? (0, node_os_1.hostname)(),
+            });
+            mirrored = true;
+        }
+        if (flags.bare.has("json")) {
+            console.log(JSON.stringify(artifact, null, 2));
+        }
+        else {
+            (0, report_1.printMatrix)(artifact);
+        }
+        console.log(`artifact → ${artifactPath}${mirrored ? " · mirrored to bakeoffs" : ""}` +
+            (keep !== undefined
+                ? ` · review samples kept (${keep}) → console /samples?bakeoff=${artifact.id}`
+                : ""));
+        return artifact;
+    }
+    finally {
+        // One-shot CLI: await the settled drain so the exporter's final batch is
+        // guaranteed to land before the process exits (H1).
+        await rig.close();
+    }
+}
+async function cmdBakeoff(flags) {
+    const config = (0, config_1.loadConfigFromEnv)();
+    const proposalId = flags.named.get("from-proposal");
+    if (proposalId !== undefined) {
+        // Evidence run for a watch proposal — budget-enveloped by the monthly
+        // watch cap, evidence attached on completion (suggested → evidenced).
+        const client = proposalsClientFrom(config);
+        const proposal = await client.get(proposalId);
+        if (proposal === null)
+            throw new Error(`no proposal "${proposalId}" on the control plane`);
+        if (proposal.status !== "suggested" && proposal.status !== "evidenced") {
+            throw new Error(`proposal ${proposalId} is ${proposal.status} — evidence runs apply to ` +
+                "suggested/evidenced proposals only");
+        }
+        const routes = (0, loader_1.loadRoutes)(config.routesDir);
+        const bundle = routes.get(proposal.route);
+        const variants = ["default", ...bundle.variants.map((v) => v.name)];
+        const lastRaw = flags.named.get("replay-last");
+        const replayLastN = lastRaw !== undefined ? Number(lastRaw) : 25;
+        if (!Number.isInteger(replayLastN) || replayLastN < 1) {
+            throw new Error("--replay-last must be a positive integer");
+        }
+        // Monthly watch budget: reserve headroom, split it across variants,
+        // accrue what the run actually spent afterwards.
+        const budgetStore = (0, store_1.openTelemetryStore)(config.telemetryDbPath);
+        try {
+            const monthlyUsd = config.watch?.monthlyUsd ?? budget_1.DEFAULT_WATCH_MONTHLY_USD;
+            const reservation = (0, budget_1.reserveWatchBudget)(budgetStore, monthlyUsd, new Date());
+            const perVariant = reservation.remainingUsd / variants.length;
+            console.log(`watch budget ${reservation.key}: $${reservation.remainingUsd.toFixed(2)} remaining → ` +
+                `$${perVariant.toFixed(2)}/variant cap`);
+            const artifact = await runAndReportBakeoff(config, flags, proposal.route, variants, replayLastN, perVariant);
+            const spentUsd = artifact.variants.reduce((a, m) => a + m.samples * m.meanCostUsd, 0);
+            budgetStore.accrue(reservation.key, spentUsd);
+            await client.attachEvidence(proposal.id, {
+                bakeoff_id: artifact.id,
+                replay_n: artifact.replayN,
+                ran_at: artifact.ranAt,
+                spent_usd: spentUsd,
+                proposal: artifact.proposal,
+                matrix: artifact.variants.map((m) => ({
+                    variant: m.variant,
+                    samples: m.samples,
+                    conform_rate: m.conformRate,
+                    conform_ci95: m.conformCi95,
+                    effective_usd_per_1k_conformant: Number.isFinite(m.effectiveUsdPer1kConformant)
+                        ? m.effectiveUsdPer1kConformant
+                        : null,
+                    pricing_missing: m.pricingMissing,
+                })),
+            });
+            console.log(`evidence attached → proposal ${proposal.id} is now evidenced ` +
+                `($${spentUsd.toFixed(2)} accrued to ${reservation.key}). ` +
+                "Approval stays human: modelrig swap execute <proposalId> --approve");
+            return 0;
+        }
+        finally {
+            budgetStore.close();
+        }
+    }
+    // Replay a task's promoted eval cases instead of the last-N captures (E4 chunk A).
+    const evalTask = flags.named.get("from-eval-cases");
+    if (evalTask !== undefined) {
+        const vRaw = flags.named.get("variants");
+        if (vRaw === undefined)
+            throw new Error("bakeoff --from-eval-cases <task> requires --variants a,b,c");
+        const vs = vRaw.split(",").map((v) => v.trim()).filter((v) => v !== "");
+        const envRaw = flags.named.get("budget-usd") ?? flags.named.get("envelope");
+        const env = envRaw !== undefined ? Number(envRaw) : undefined;
+        if (env !== undefined && (!Number.isFinite(env) || env <= 0))
+            throw new Error("--budget-usd must be positive");
+        return (0, report_1.runEvalCaseBakeoffCli)(config, evalTask, vs, env, keepOutputsMode(flags), flags.bare.has("json"));
+    }
+    const route = flags.named.get("route");
+    const variantsRaw = flags.named.get("variants");
+    const lastRaw = flags.named.get("replay-last");
+    if (route === undefined || variantsRaw === undefined || lastRaw === undefined) {
+        throw new Error("bakeoff requires --route, --variants a,b,c and --replay-last N (or --from-proposal <id>)");
+    }
+    const variants = variantsRaw.split(",").map((v) => v.trim()).filter((v) => v !== "");
+    const replayLastN = Number(lastRaw);
+    if (!Number.isInteger(replayLastN) || replayLastN < 1) {
+        throw new Error("--replay-last must be a positive integer");
+    }
+    // §4: --budget-usd is the named envelope knob; --envelope is kept as an alias.
+    const envelopeRaw = flags.named.get("budget-usd") ?? flags.named.get("envelope");
+    const envelope = envelopeRaw !== undefined ? Number(envelopeRaw) : undefined;
+    if (envelope !== undefined && (!Number.isFinite(envelope) || envelope <= 0)) {
+        throw new Error("--budget-usd must be a positive number of dollars (per replay variant)");
+    }
+    await runAndReportBakeoff(config, flags, route, variants, replayLastN, envelope);
+    return 0;
+}
+const DEFAULT_WATCH_THRESHOLD_PCT = 10;
+async function cmdWatch(flags) {
+    const sub = flags.positional[0];
+    if (sub !== "run") {
+        throw new Error("usage: modelrig watch run [--events fixtures.json] [--json]");
+    }
+    const config = (0, config_1.loadConfigFromEnv)();
+    const client = proposalsClientFrom(config);
+    const routes = (0, loader_1.loadRoutes)(config.routesDir);
+    const routeEconomics = routes.list().map((b) => ({
+        route: b.route,
+        candidates: b.candidates.map((c) => ({ provider: c.provider, model: c.model })),
+    }));
+    const providers = new Set(routeEconomics.flatMap((r) => r.candidates.map((c) => c.provider)));
+    const eventsPath = flags.named.get("events");
+    const injectedEvents = eventsPath !== undefined
+        ? JSON.parse((0, node_fs_1.readFileSync)(eventsPath, "utf8"))
+        : undefined;
+    // A4: on a cron container the pricing snapshot MUST outlive the process.
+    // A file-backed store there re-seeds every run and can never fire an event.
+    // Durable watch state needs the database itself, so api mode gets the local
+    // file (and the warning below) exactly as an unconfigured rig does.
+    const watchExport = config.export?.mode === "direct" ? config.export : undefined;
+    const store = (0, state_store_1.createWatchStateStore)({
+        filePath: (0, node_path_1.join)((0, node_path_1.dirname)(config.telemetryDbPath), "watch-state.json"),
+        export: watchExport,
+    });
+    if (watchExport === undefined) {
+        console.warn("[modelrig] watch state is local-file only — fine on your machine, but on an ephemeral " +
+            "container every cycle re-seeds and no price change can ever fire. Configure " +
+            "MODELRIG_SUPABASE_URL + MODELRIG_SUPABASE_SERVICE_ROLE_KEY for durable state.");
+    }
+    // The cycle reports its own outcome to the control plane. A4 gave this job
+    // durable state but no proof of life: `control_state` sat empty for a week
+    // and "never scheduled", "running and failing" and "running and finding
+    // nothing" were indistinguishable from outside, readable only through the
+    // hosting platform's log viewer. Now the job answers for itself.
+    const result = await (0, run_reported_1.runWatchCycleReported)({
+        routes: routeEconomics,
+        store,
+        universe: (0, state_1.buildPriceUniverse)(providers),
+        client,
+        thresholdPct: config.watch?.thresholdPct ?? DEFAULT_WATCH_THRESHOLD_PCT,
+        ...(injectedEvents !== undefined ? { injectedEvents } : {}),
+    }, {
+        supabaseUrl: watchExport?.supabaseUrl ?? "",
+        serviceRoleKey: watchExport?.serviceRoleKey ?? "",
+    });
+    if (flags.bare.has("json")) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else if (result.seeded) {
+        console.log("watch: seeded pricing state (first run watches silently — events fire from the next cycle)\n" +
+            `       state → ${store.description}`);
+    }
+    else {
+        console.log(`watch: ${result.events} event(s) → ${result.drafts} draft(s) → ` +
+            `${result.inserted} new proposal(s) (duplicates deduped; run \`modelrig bakeoff ` +
+            "--from-proposal <id>` to attach evidence — nothing executes automatically)");
+    }
+    return 0;
+}
+function swapsClientFrom(config) {
+    const exp = (0, config_1.directExportOf)(config, "this command");
+    return (0, swaps_client_1.createSwapsClient)({
+        supabaseUrl: exp.supabaseUrl,
+        serviceRoleKey: exp.serviceRoleKey,
+    });
+}
+async function cmdSwapExecute(flags) {
+    const proposalId = flags.positional[1];
+    if (proposalId === undefined) {
+        throw new Error("usage: modelrig swap execute <proposalId> --approve [--approved-by name]");
+    }
+    // THE gate (spec hard rule): no --approve, no execution — full stop,
+    // before any config or network access.
+    if (!flags.bare.has("approve")) {
+        throw new Error("swap execution requires explicit --approve — proposals never auto-execute. " +
+            `Re-run: modelrig swap execute ${proposalId} --approve`);
+    }
+    const config = (0, config_1.loadConfigFromEnv)();
+    const proposals = proposalsClientFrom(config);
+    const swaps = swapsClientFrom(config);
+    const routes = (0, loader_1.loadRoutes)(config.routesDir);
+    // The orchestration (guards, ordering, baseline snapshot) lives in the
+    // hermetically-tested executeSwap; the CLI only injects the real config
+    // deps and prints. The --approve gate is enforced here (fast-fail before
+    // config) AND inside executeSwap (defense in depth).
+    const result = await (0, swap_execute_1.executeSwap)({
+        proposalId,
+        approve: flags.bare.has("approve"),
+        approvedBy: flags.named.get("approved-by") ?? (0, node_os_1.userInfo)().username,
+        proposals,
+        swaps,
+        loadBundle: (route) => routes.get(route),
+        newId: () => (0, node_crypto_1.randomUUID)(),
+        now: () => new Date().toISOString(),
+    });
+    console.log(`swap ${result.swapId} recorded (approved by ${result.approvedBy}) — ` +
+        `${result.change.fromModel} → ${result.change.toModel}\n`);
+    console.log("APPLY THIS CHANGE (the executor never edits route files — git does):\n");
+    console.log(result.change.yaml);
+    console.log(`REVERT COMMAND (any time): modelrig swap revert ${result.swapId}\n` +
+        `The odometer starts measuring ${result.route} savings from the moment the change deploys.`);
+    return 0;
+}
+async function cmdSwapRevert(flags) {
+    const swapId = flags.positional[1];
+    if (swapId === undefined)
+        throw new Error("usage: modelrig swap revert <swapId>");
+    const config = (0, config_1.loadConfigFromEnv)();
+    const swaps = swapsClientFrom(config);
+    const swap = await swaps.get(swapId);
+    if (swap === null)
+        throw new Error(`no swap "${swapId}" on the control plane`);
+    if (swap.revertedAt !== null) {
+        console.log(`swap ${swapId} was already reverted at ${swap.revertedAt} — nothing to do`);
+        return 0;
+    }
+    const revertedAt = new Date().toISOString();
+    await swaps.markReverted(swapId, revertedAt);
+    const incumbents = swap.baseline.incumbent_candidates ?? [];
+    console.log(`swap ${swapId} marked reverted — the odometer stops accruing it at ${revertedAt}\n`);
+    console.log("APPLY THIS CHANGE (git is the actuator, as always):\n");
+    const routes = (0, loader_1.loadRoutes)(config.routesDir);
+    let version = null;
+    try {
+        version = routes.get(swap.route).version + 1;
+    }
+    catch {
+        // Route no longer loads locally — emit without the version line.
+    }
+    console.log([
+        `# revert swap ${swapId}: restore ${swap.route} to its pre-swap candidate order`,
+        `# apply to modelrig/routes/${swap.route}.yaml`,
+        ...(version !== null ? [`version: ${version}`] : ["# bump the version field by 1"]),
+        "candidates:",
+        ...incumbents.flatMap((c) => [`  - provider: ${c.provider}`, `    model: ${c.model}`]),
+        "",
+    ].join("\n"));
+    return 0;
+}
+async function cmdSwap(flags) {
+    const sub = flags.positional[0];
+    if (sub === "execute")
+        return cmdSwapExecute(flags);
+    if (sub === "revert")
+        return cmdSwapRevert(flags);
+    throw new Error("usage: modelrig swap execute <proposalId> --approve [--approved-by name] | modelrig swap revert <swapId>");
+}
+async function cmdSamples(flags) {
+    const sub = flags.positional[0];
+    if (sub !== "purge") {
+        throw new Error("usage: modelrig samples purge [--bakeoff <id>]");
+    }
+    const config = (0, config_1.loadConfigFromEnv)();
+    const samplesExport = (0, config_1.directExportOf)(config, "samples purge");
+    const client = (0, samples_1.createBakeoffSamplesClient)({
+        supabaseUrl: samplesExport.supabaseUrl,
+        serviceRoleKey: samplesExport.serviceRoleKey,
+    });
+    const bakeoffId = flags.named.get("bakeoff");
+    const deleted = await client.purge(bakeoffId !== undefined ? { bakeoffId } : { nowIso: new Date().toISOString() });
+    console.log(bakeoffId !== undefined
+        ? `purged ${deleted} review sample(s) for bakeoff ${bakeoffId}`
+        : `purged ${deleted} expired review sample(s)`);
+    return 0;
+}
+/**
+ * `modelrig verify-swap` — the autonomy-ladder Tier-2 verify step (Expansion
+ * §9). Replays a LOCAL capture fixture through the drafted SAME-MODEL route,
+ * diffs each output against the original, and emits the report the Tier-2 PR
+ * embeds. A plumbing proof; refuses uncapturable (streaming/dynamic) sites. */
+async function cmdVerifySwap(flags) {
+    const route = flags.named.get("route");
+    const fixturePath = flags.named.get("captures");
+    if (route === undefined || fixturePath === undefined) {
+        throw new Error("verify-swap requires --route <route> and --captures <fixture.json> " +
+            "(the local capture of the original call's inputs/outputs)");
+    }
+    const envRaw = flags.named.get("budget-usd") ?? flags.named.get("envelope");
+    const envelopeUsd = envRaw !== undefined ? Number(envRaw) : undefined;
+    if (envelopeUsd !== undefined && (!Number.isFinite(envelopeUsd) || envelopeUsd <= 0)) {
+        throw new Error("--budget-usd must be a positive number of dollars (the replay-pass envelope)");
+    }
+    const config = (0, config_1.loadConfigFromEnv)();
+    return (0, cli_run_1.runVerifySwapCli)(config, {
+        route,
+        fixturePath,
+        ...(envelopeUsd !== undefined ? { envelopeUsd } : {}),
+        ...(flags.bare.has("json") ? { asJson: true } : {}),
+        ...(flags.named.get("out") !== undefined ? { outPath: flags.named.get("out") } : {}),
+    });
+}
+/**
+ * `modelrig serve` — Phase 5 WS4's zero-config path. The HTTP surface lives
+ * in the separate `modelrig-server` package (it has its own auth and budget
+ * concerns); this is the one command name people will reach for, so it
+ * hands off rather than making them learn a second package name.
+ *
+ * The dependency stays one-way: the core package does not depend on the
+ * server, it just calls it when present and teaches when it isn't.
+ */
+async function cmdServe() {
+    let serverMain = null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require("modelrig-server");
+        serverMain = mod.main ?? null;
+    }
+    catch {
+        serverMain = null;
+    }
+    if (serverMain === null) {
+        console.error([
+            "`modelrig serve` needs the server package, which isn't installed here.",
+            "",
+            "  pnpm add modelrig-server        (or npm i / yarn add)",
+            "",
+            "It's a separate package because serving over HTTP brings its own concerns —",
+            "a bearer token and a daily spend cap — that a library shouldn't assume for you.",
+            "You do NOT need it to use ModelRig from your own code: `rig.run(...)` works",
+            "without any server at all. Docs: https://modelrig.dev/quickstart.html",
+        ].join("\n"));
+        return 1;
+    }
+    serverMain();
+    // The server owns the process from here (it holds the listener open).
+    return 0;
+}
+/** `modelrig status` — print the runtime posture (§2): export mode, artifact
+ * namespace on/off + WHY, content custody, OTLP. Reads config only (no rig, no
+ * routes dir), so it works anywhere the env is set. */
+function cmdStatus() {
+    console.log((0, status_1.formatStatusReport)((0, status_1.buildRigStatus)((0, config_1.loadConfigFromEnv)())));
+    return 0;
+}
+/** `modelrig judge <run>` — E5 V.4: explicitly ask the bounded model-judge to
+ * score a run. Goes through the API boundary (T12: the CLI never holds a DB
+ * client) — POST /v1/runs/:id/judge on the configured server, authed with a
+ * rig_sk key. The daily cap + metering are the SERVER's; this just triggers one. */
+async function cmdJudge(flags) {
+    const runId = flags.positional[0] ?? "";
+    // Config is the only env reader (package-invariants rule). The judge endpoint
+    // lives on the same server as the api-mode ingest sink, so the base is that
+    // URL's origin and the credential is the api key.
+    const exp = (0, config_1.loadConfigFromEnv)().export;
+    const api = exp !== undefined && exp.mode === "api" ? exp : undefined;
+    const base = api !== undefined ? new URL(api.ingestUrl).origin : "";
+    const key = api?.apiKey ?? "";
+    if (runId === "" || base === "" || key === "") {
+        console.error([
+            "usage: modelrig judge <runId>",
+            "",
+            "Needs api-mode telemetry configured (the judge is on the same server):",
+            "  MODELRIG_API_KEY    a rig_sk_ key with the `oracle-act` scope",
+            "  MODELRIG_INGEST_URL optional — the server base; defaults to the hosted API",
+            "",
+            "The judge is EXPLICIT-only and metered; scoring rides the gateway (a route),",
+            "so the org's daily cap and spend-stops apply. Nothing schedules it.",
+        ].join("\n"));
+        return 1;
+    }
+    const res = await fetch(`${base}/v1/runs/${encodeURIComponent(runId)}/judge`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+        body: "{}",
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        console.error(`judge ${res.status}: ${typeof body.error === "string" ? body.error : "failed"}`);
+        return 1;
+    }
+    console.log(JSON.stringify(body, null, 2));
+    return 0;
+}
+/** The one usage block, printed to stdout on `--help` (exit 0) and to stderr on
+ * an unknown command (exit 1). Kept as a const so the two paths can never
+ * drift. */
+const USAGE = [
+    "usage:",
+    "  modelrig init [path] [--scope glob,glob] [--out dir] [--dry-run] [--include-tests] [--json]",
+    "  modelrig observe [path] [--scope glob,glob] [--out dir] [--dry-run] [--json]   (T0/T1: see your runs first — no migration)",
+    "  modelrig validate                    (structurally check rig.yaml + every route bundle — no provider key needed)",
+    "  modelrig status                      (print export/artifact/otlp posture)",
+    "  modelrig serve                       (needs the modelrig-server package)",
+    "  modelrig bakeoff --route <route> --variants a,b,c --replay-last N [--budget-usd usd] [--keep-outputs[=all]] [--json] [--no-mirror]",
+    "  modelrig bakeoff --from-proposal <id> [--replay-last N] [--keep-outputs[=all]] [--json]",
+    "  modelrig watch run [--events fixtures.json] [--json]",
+    "  modelrig verify-swap --route <route> --captures <fixture.json> [--budget-usd usd] [--out report.md] [--json]",
+    "  modelrig swap execute <proposalId> --approve [--approved-by name]",
+    "  modelrig swap revert <swapId>",
+    "  modelrig judge <runId>               (E5: score a run with the bounded model-judge; explicit + metered)",
+    "  modelrig samples purge [--bakeoff <id>]",
+].join("\n");
+async function main(argv) {
+    const [command, ...rest] = argv;
+    // `--help`/`-h`/`help` is a success: print usage to stdout and exit 0. (An
+    // unknown command still prints usage to stderr and exits 1, below.) The
+    // clean-room tarball test asserts the shipped bin exits 0 on --help.
+    if (command === "--help" || command === "-h" || command === "help") {
+        console.log(USAGE);
+        return 0;
+    }
+    const flags = parseArgs(rest);
+    switch (command) {
+        case "status":
+            return cmdStatus();
+        case "validate":
+            return (0, validate_cli_1.runValidateCli)();
+        case "bakeoff":
+            return cmdBakeoff(flags);
+        case "watch":
+            return cmdWatch(flags);
+        case "swap":
+            return cmdSwap(flags);
+        case "samples":
+            return cmdSamples(flags);
+        case "init":
+            return (0, init_cli_1.cmdInit)(flags);
+        case "observe":
+            return (0, observe_cli_1.cmdObserve)(flags);
+        case "verify-swap":
+            return cmdVerifySwap(flags);
+        case "judge":
+            return cmdJudge(flags);
+        case "serve":
+            return cmdServe();
+        default:
+            console.error(USAGE);
+            return 1;
+    }
+}
+if (require.main === module) {
+    main(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((err) => {
+        // Errors that teach (WS3): a typed failure prints what happened, what
+        // to do, and where to read — from the one table, not from here.
+        if (err instanceof failures_1.RigFailureError) {
+            console.error((0, failures_teaching_1.renderFailureForTerminal)(err.failure));
+        }
+        else if ((0, failures_1.isRigFailure)(err)) {
+            console.error((0, failures_teaching_1.renderFailureForTerminal)(err));
+        }
+        else {
+            console.error(err instanceof Error ? err.message : String(err));
+        }
+        process.exitCode = 1;
+    });
+}