@jevitate/cli 0.1.0 → 0.3.0

package/dist/program.js

@@ -1,1938 +1,140 @@
-import { readFile, writeFile, mkdir, mkdtemp, rm } from "node:fs/promises";
-import { dirname } from "node:path";
-import { tmpdir, userInfo } from "node:os";
-import { join } from "node:path";
 import { Command } from "commander";
-import * as clack from "@clack/prompts";
-import { SitePolicySchema, simulateTiming } from "@jevitate/domain";
-import { openDatabase, migrateToLatest, SqliteSitePolicyRepository } from "@jevitate/storage-sqlite";
-import { RecordingSchema, AuthoringTakeSchema, PostdocDecisionsSchema, promoteToVariable, diffTakes, applyPostdoc, flattenBaseFillSteps, fitInteractionPolicy, } from "@jevitate/recording";
-import { FsJourneyStore, JourneyRegistry, ParamValidationError } from "@jevitate/journey";
-import { envCredentialStore, requireKeys, MissingCredentialError, FakeGenerationGateway, OpenRouterGenerationGateway, JevJudgmentGateway, } from "@jevitate/ai-core";
-import { UnauthorizedExploreTargetError } from "@jevitate/explore";
-import { PlaywrightBrowserPort } from "@jevitate/playwright";
-import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
-import { safeRunPolicy } from "@jevitate/domain";
-import { makeExploreSelfHealer } from "./self-heal-adapter.js";
-import { ok, fail } from "./envelope.js";
-import { runJourneyProgrammatically, UnknownJourneyError } from "./journey-api.js";
-import { runJourneyLoadTest, UnknownLoadJourneyError } from "./load-api.js";
-import { runRegressionCapture } from "./regression-api.js";
-import { addMissionTarget, listMissionTargets, promoteMissionTarget, missionTargetContext, UnknownMissionTargetError, } from "./mission-api.js";
-import { startMcpServer } from "./mcp-api.js";
-import { startUiServer } from "./ui-api.js";
-import { registerAiCommands, realSecureIO } from "./ai-cli.js";
-import { collectAllMissingKeys } from "./init-keys.js";
-import { readCliVersion } from "./version.js";
-import { detectRuntimes, resolveInstallTargetPaths, installSkills, } from "./init-skills.js";
-import { registerMcp, resolveMcpTargetPaths, renderPrintConfig, } from "./init-mcp.js";
-import { loadManifest } from "@jevitate/skills";
-import { runExploration, runAuthorJourney, runCoverageMission, runAdversarialCliMission, runFeatureCliMission, parseAssertionSpec, resolveExploreAllowlist, } from "./explore-api.js";
-import { runUsabilityMission, runUxReview, UxAnalysisFailedError } from "./ux-api.js";
-import { resolveDataDir } from "./data-dir.js";
-import { runRecording, resolveRecordAllowlist, } from "./record-api.js";
-import { addSource, listSources, pullSource, updateSource, removeSource, trustJourney, publishJourneyToSource, realGhPort, NotPromotedError, NoDeclaredOriginsError, } from "./source-api.js";
-import { runSourceJourney, realResolvedJourneyRunner, } from "./source-run-api.js";
-import { FsTrustStore, FsAckStore, UnknownSourceError, EmbeddedSecretError, UndeclaredOriginError, UndeclaredTouError, HashMismatchError, UntrustedRiskyJourneyError, SourceValidationError, DEFAULT_LOCK_PATH, } from "@jevitate/sources";
-// `~/.jevitate/*` is the product's runtime-data convention (product = Jevitate).
-// See data-dir.ts.
-const DEFAULT_DB_PATH = resolveDataDir(["db.sqlite"]);
-const DEFAULT_JOURNEYS_DIR = resolveDataDir(["journeys"]);
-const DEFAULT_REGRESSIONS_DIR = resolveDataDir(["regressions"]);
-const DEFAULT_MISSION_TARGETS_DIR = resolveDataDir(["missions", "targets"]);
-const DEFAULT_INBOX_DIR = resolveDataDir(["inbox"]);
-function resolveDbPath(deps, flag) {
-    return flag ?? deps.dbPath ?? DEFAULT_DB_PATH;
-}
-/**
- * Mirrors `resolveDbPath`'s flag > deps > home-dir-default convention: a
- * per-invocation `--dir` flag wins, then a `CliDeps.journeysDir` wired in by
- * the host, then `~/.jevitate/journeys`.
- */
-function resolveJourneysDir(deps, flag) {
-    return flag ?? deps.journeysDir ?? DEFAULT_JOURNEYS_DIR;
-}
-/** Same flag > home-dir-default convention as `resolveJourneysDir`, for the
- *  committed-regressions directory `regression capture` writes into. */
-function resolveRegressionsDir(flag) {
-    return flag ?? DEFAULT_REGRESSIONS_DIR;
-}
-/** Same flag > deps > home-dir-default convention as `resolveJourneysDir`, for
- *  the mission-targets store `mission target ...` reads/writes. */
-function resolveMissionTargetsDir(deps, flag) {
-    return flag ?? deps.missionTargetsDir ?? DEFAULT_MISSION_TARGETS_DIR;
-}
-/** Same flag > deps > home-dir-default convention as `resolveJourneysDir`, for
- *  the inbox store `jevitate mcp`'s inbox tools AND `jevitate ui` both read
- *  from — the SAME resolved directory, so the two commands agree on where
- *  approvals/handbacks/reviews live. */
-function resolveInboxDir(deps, flag) {
-    return flag ?? deps.inboxDir ?? DEFAULT_INBOX_DIR;
-}
-/**
- * Assembles the injected `SourceApiDeps` for the distributed-sources commands
- * from `CliDeps.sources` (test-injected ports) or the real production
- * defaults: `~/.jevitate/sources` clones, `<cwd>/jevitate.lock`, and the
- * local, per-user `FsTrustStore`/`FsAckStore` under `~/.jevitate/trust`.
- * Trust/ack stores are LOCAL by design (§14.1) — never the team-shared lock.
- */
-function resolveSourceApiDeps(deps) {
-    const s = deps.sources ?? {};
-    return {
-        sourcesDir: s.sourcesDir ?? resolveDataDir(["sources"]),
-        lockPath: s.lockPath ?? DEFAULT_LOCK_PATH(),
-        trust: new FsTrustStore(s.trustDir ?? resolveDataDir(["trust"])),
-        ack: new FsAckStore(s.ackDir ?? resolveDataDir(["trust", "acks"])),
-        git: s.git,
-        now: s.now,
-    };
-}
-/** The identity recorded in a `TrustRecord`/`TouAck` — an injected value, else
- *  the OS username, else `"local"`. Never a secret/credential. */
-function resolveApprovedBy(deps) {
-    if (deps.sources?.approvedBy)
-        return deps.sources.approvedBy;
-    try {
-        return userInfo().username || "local";
-    }
-    catch {
-        return "local";
-    }
-}
-/**
- * Builds a fresh, real Playwright-backed `Actor` (its own temp profile dir +
- * browser context, per `journey-api.ts`'s `runJourneyProgrammatically`
- * pattern) and returns it alongside a `close()` to tear the session down.
- * `@jevitate/regression`'s `makeActor: () => Promise<Actor>` contract calls
- * this once per reproduce/minimize attempt — a Playwright session cannot be
- * reused after a run — so callers must close each one it hands back.
- */
-async function makeRealBrowserActor(site) {
-    const profileDir = await mkdtemp(join(tmpdir(), "jevitate-regression-"));
-    const port = new PlaywrightBrowserPort();
-    const session = await port.open({ profileDir, headless: true, allowedOrigins: [site], baseUrl: site });
-    const actor = CastActor.named("regression-capture").whoCan(new BrowseTheWeb(session, [site]));
-    return {
-        actor,
-        close: async () => {
-            await session.close();
-            await rm(profileDir, { recursive: true, force: true });
-        },
-    };
-}
-/**
- * Parses repeated `--param key=value` flags into a `Record<string,string>`.
- * `previous` starts as the option's default (`{}`) and this is called once
- * per occurrence, commander's standard "collect" pattern.
- */
-function collectParam(value, previous) {
-    const idx = value.indexOf("=");
-    const key = idx === -1 ? value : value.slice(0, idx);
-    const val = idx === -1 ? "" : value.slice(idx + 1);
-    return { ...previous, [key]: val };
-}
-function makeClock() {
-    return {
-        nowIso: () => new Date().toISOString(),
-        monotonicMs: () => Date.now(),
-    };
-}
-async function withSitePolicyRepository(dbPath, fn) {
-    await mkdir(dirname(dbPath), { recursive: true });
-    const db = openDatabase(dbPath);
-    try {
-        await migrateToLatest(db);
-        const repository = new SqliteSitePolicyRepository(db, makeClock());
-        return await fn(repository);
-    }
-    finally {
-        await db.destroy();
-    }
-}
-function isPlannedStep(value) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    const record = value;
-    if (typeof record.label !== "string")
-        return false;
-    switch (record.kind) {
-        case "type":
-            return typeof record.text === "string";
-        case "click":
-        case "navigate":
-            return true;
-        case "read":
-            return typeof record.chars === "number";
-        default:
-            return false;
-    }
-}
-function parsePlannedScript(raw) {
-    const parsed = JSON.parse(raw);
-    if (!Array.isArray(parsed) || !parsed.every(isPlannedStep)) {
-        throw new Error("script must be a JSON array of planned steps ({kind, label, ...})");
-    }
-    return parsed;
-}
+import { registerDoctorCommand } from "./resource-preflight.js";
+import { fail } from "./envelope.js";
+import { registerLedgerCommands } from "./ledger-cli.js";
+import { registerAiCommands } from "./ai-cli.js";
+import { registerCheckCommand } from "./check-cli.js";
+import { registerReportCommands } from "./report-cli.js";
+import { registerInvariantsCommands } from "./invariants-validate.js";
+import { currentEngineInfo } from "./engine.js";
+import { EXIT_CODES } from "./exit-codes.js";
+import { commandPath, trackActionCommand } from "./cli-refusal.js";
+import { resolveDbPath, resolveJourneysDir, resolveMissionTargetsDir, withBrowserLaunchFlags, browserLaunchFromFlags, buildExploreGateways, } from "./cli-shared.js";
+import { registerInitCommands } from "./init-cli.js";
+import { registerProfileCommands } from "./profile-cli.js";
+import { registerSiteCommands } from "./site-cli.js";
+import { registerRecordingCommands } from "./recording-cli.js";
+import { registerJourneyCommands } from "./journey-cli.js";
+import { registerSourceCommands } from "./source-cli.js";
+import { registerLoadCommands } from "./load-cli.js";
+import { registerExploreCommands } from "./explore-cli.js";
+import { registerCampaignCommands } from "./campaign-cli.js";
+import { registerVerifyFixCommands } from "./verify-fix-cli.js";
+import { registerAuthorJourneyCommands } from "./author-journey-cli.js";
+import { registerDemoCommands } from "./demo-aspect-cli.js";
+import { registerRecordCommands } from "./record-cli.js";
+import { registerRegressionCommands } from "./regression-cli.js";
+import { registerMissionCommands } from "./mission-cli.js";
+import { registerServeCommands } from "./serve-cli.js";
+import { registerUxCommands } from "./ux-cli.js";
+import { registerLogsCommands } from "./logs-cli.js";
+import { registerInboxCommands } from "./inbox-cli.js";
+export { fakeDoneJudge } from "./cli-shared.js";
 /**
- * Writes a JSON envelope using the program's CURRENTLY-CONFIGURED output
- * writer (read at call time via `configureOutput()`), so tests that call
- * `program.configureOutput({ writeOut })` after `buildProgram()` still see
- * output routed to their writer. Also sets `process.exitCode` (0 for `ok`,
- * 1 for `fail`) instead of hard-exiting, so `exitOverride()` in tests works.
+ * `--version`'s display string: the published semver alone once that alone identifies the
+ * build (a real npm install), plus commit/builtAt whenever the build could determine them (a
+ * dev checkout / `npm link`ed working tree) — issue #83, "`jevitate --version` stays `0.1.0`
+ * across 3 rebuilds in one hour ... nothing says which commit produced a result." `"unknown"`
+ * (never shown here at all — omitted instead) rather than a fabricated commit/time.
  */
-function emitJson(program, envelope) {
-    const writeOut = program.configureOutput().writeOut;
-    writeOut?.(`${JSON.stringify(envelope)}\n`);
-    process.exitCode = envelope.ok ? 0 : 1;
+function versionString() {
+    const engine = currentEngineInfo();
+    if (engine.commit === "unknown" && engine.builtAt === "unknown")
+        return engine.version;
+    return `${engine.version} (commit ${engine.commit}, built ${engine.builtAt})`;
 }
 export function buildProgram(deps) {
     const program = new Command();
-    program.name("jevitate").description("Local browser automation platform").version(readCliVersion());
-    program
-        .command("init")
-        .option("--json", "emit a JSON envelope")
-        .option("--skip-keys", "skip credential collection")
-        .option("--skip-skills", "skip skill installation")
-        .option("--skip-mcp", "skip registering the jevitate MCP server in detected harnesses")
-        .option("--targets <ids>", "comma-separated runtime ids to force-install to, overriding detection")
-        .option("--force", "overwrite a user-modified installed skill file/block or MCP config entry")
-        .option("--dry-run", "report planned skill-install/mcp-register actions without writing")
-        .action(async function () {
-        const { json, skipKeys, skipSkills, skipMcp, targets, force, dryRun } = this.opts();
-        try {
-            const data = { initialized: true };
-            if (!skipKeys) {
-                // SECURITY: reuses the existing, already-guardrailed credential
-                // collection. The report holds only key NAMES (required/collected),
-                // never a value — nothing here reads, echoes, logs, or returns a key.
-                const store = envCredentialStore(deps.ai?.env ?? process.env, deps.ai?.localConfig ?? {});
-                const io = deps.ai?.secureIO ?? realSecureIO();
-                data.keys = await collectAllMissingKeys(store, io);
-            }
-            // Explicit `--targets` overrides detection entirely (the user takes
-            // full control); otherwise `detectRuntimes` decides, always including
-            // the always-on generic fallback. Shared by the skill install and the
-            // MCP registration so a single selection drives both.
-            const runtimes = targets
-                ? targets.split(",").map((t) => t.trim()).filter((t) => t.length > 0)
-                : detectRuntimes(deps.init?.detection);
-            if (!skipSkills) {
-                const paths = resolveInstallTargetPaths(deps.init?.detection);
-                const statePath = deps.init?.statePath ?? resolveDataDir(["skills-install-state.json"]);
-                const skills = loadManifest();
-                data.skills = await installSkills(runtimes, skills, paths, statePath, { force, dryRun });
-            }
-            if (!skipMcp) {
-                // Register the `jevitate mcp` server for each detected/selected
-                // harness, with the SAME never-clobber safety as skills: a user's
-                // conflicting or unparseable config is never overwritten without
-                // --force; each declined target reports a printable instruction
-                // instead (honest, never corrupts a config). `generic` has no MCP
-                // convention and is skipped inside `registerMcp`.
-                const mcpPaths = resolveMcpTargetPaths(deps.init?.detection);
-                data.mcp = await registerMcp(runtimes, mcpPaths, { force, dryRun });
-            }
-            const envelope = ok(data);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                const out = program.configureOutput().writeOut;
-                out?.("jevitate initialized\n");
-                if (data.keys)
-                    out?.(`keys: ${JSON.stringify(data.keys)}\n`);
-                if (data.skills)
-                    out?.(`skills: ${data.skills.length} target/skill pairs processed\n`);
-                if (data.mcp)
-                    out?.(`mcp: ${data.mcp.length} harness config(s) processed\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_INIT", String(err instanceof Error ? err.message : err)));
-        }
-    });
-    const profile = program.command("profile");
-    profile
-        .command("create <name>")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (name) {
-        const { json } = this.opts();
-        try {
-            const status = await deps.profiles.create(name);
-            const envelope = ok(status);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`profile '${status.name}' created at ${status.dir}\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_PROFILE_CREATE", String(err)));
-        }
-    });
-    profile
-        .command("status <name>")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (name) {
-        const { json } = this.opts();
-        try {
-            const status = await deps.profiles.status(name);
-            const envelope = ok(status);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`profile '${status.name}': ${status.exists ? "exists" : "missing"} (${status.dir})\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_PROFILE_STATUS", String(err)));
-        }
-    });
-    const site = program.command("site");
-    const sitePolicy = site.command("policy");
-    sitePolicy
-        .command("get <site>")
-        .option("--account <account>", "account id", "primary")
-        .option("--db <path>", "sqlite db path")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (siteId) {
-        const { account, db, json } = this.opts();
-        try {
-            const dbPath = resolveDbPath(deps, db);
-            const policy = await withSitePolicyRepository(dbPath, (repository) => repository.get(siteId, account));
-            const envelope = ok(policy);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                if (policy) {
-                    program.configureOutput().writeOut?.(`policy for '${siteId}' (version ${policy.version}): ${JSON.stringify(policy)}\n`);
-                }
-                else {
-                    program.configureOutput().writeOut?.(`no policy configured for '${siteId}' (account '${account}')\n`);
-                }
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_SITE_POLICY_GET", String(err)));
-        }
-    });
-    sitePolicy
-        .command("set <site>")
-        .requiredOption("--file <path>", "path to a policy JSON file")
-        .option("--account <account>", "account id", "primary")
-        .option("--db <path>", "sqlite db path")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (siteId) {
-        const { account, db, file, json } = this.opts();
-        let policy;
-        try {
-            const raw = await readFile(file, "utf8");
-            policy = SitePolicySchema.parse(JSON.parse(raw));
-        }
-        catch (err) {
-            emitJson(program, fail("E_INVALID_POLICY", String(err)));
-            return;
-        }
-        try {
-            const dbPath = resolveDbPath(deps, db);
-            await withSitePolicyRepository(dbPath, (repository) => repository.set(siteId, account, policy));
-            const envelope = ok({ site: siteId, account, version: policy.version });
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`policy for '${siteId}' (account '${account}') set to version ${policy.version}\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_SITE_POLICY_SET", String(err)));
-        }
-    });
-    site
-        .command("simulate <site>")
-        .requiredOption("--script <path>", "path to a planned-step script JSON file")
-        .option("--seed <n>", "deterministic RNG seed", "0")
-        .option("--account <account>", "account id", "primary")
-        .option("--db <path>", "sqlite db path")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (siteId) {
-        const { account, db, script, seed, json } = this.opts();
-        let plannedScript;
-        try {
-            const raw = await readFile(script, "utf8");
-            plannedScript = parsePlannedScript(raw);
-        }
-        catch (err) {
-            emitJson(program, fail("E_INVALID_SCRIPT", String(err)));
-            return;
-        }
-        const seedNum = Number(seed);
-        if (!Number.isFinite(seedNum)) {
-            emitJson(program, fail("E_INVALID_SEED", `--seed must be a finite number, got ${JSON.stringify(seed)}`));
-            return;
-        }
-        try {
-            const dbPath = resolveDbPath(deps, db);
-            const policy = await withSitePolicyRepository(dbPath, (repository) => repository.get(siteId, account));
-            const interaction = policy?.interaction ?? {};
-            const profile = simulateTiming(interaction, seedNum, plannedScript);
-            const envelope = ok(profile);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                const out = program.configureOutput().writeOut;
-                for (const step of profile.steps) {
-                    out?.(`${step.kind} '${step.label}': ${step.delayMs}ms\n`);
-                }
-                out?.(`totalMs: ${profile.totalMs}\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_SITE_SIMULATE", String(err)));
-        }
-    });
-    const recording = program.command("recording");
-    recording
-        .command("promote <file>")
-        .requiredOption("--page <n>", "page index")
-        .requiredOption("--step <n>", "step index within the page")
-        .requiredOption("--var <name>", "variable name to bind")
-        .action(async function (file) {
-        const { page, step, var: varName } = this.opts();
-        try {
-            const raw = await readFile(file, "utf8");
-            const rec = RecordingSchema.parse(JSON.parse(raw));
-            const result = promoteToVariable(rec, { page: Number(page), step: Number(step) }, varName);
-            program.configureOutput().writeOut?.(`${JSON.stringify(result, null, 2)}\n`);
-            process.exitCode = 0;
-        }
-        catch (err) {
-            emitJson(program, fail("E_INVALID_RECORDING", String(err)));
-        }
-    });
-    recording
-        .command("diff <takeA> <takeB> [more...]")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (takeA, takeB, more) {
-        const { json } = this.opts();
-        try {
-            const files = [takeA, takeB, ...more];
-            const takes = await Promise.all(files.map(async (f) => {
-                const raw = await readFile(f, "utf8");
-                const parsed = AuthoringTakeSchema.parse(JSON.parse(raw));
-                return { recording: parsed.recording, values: new Map(Object.entries(parsed.values)) };
-            }));
-            const diffResult = diffTakes(takes);
-            const envelope = ok(diffResult);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                const out = program.configureOutput().writeOut;
-                diffResult.columns.forEach((col, i) => {
-                    const type = col.inferredType ? `, type=${col.inferredType}` : "";
-                    out?.(`column ${i}: ${col.kind} (confidence ${col.confidence.toFixed(2)}${type}) values=${JSON.stringify(col.values)}\n`);
-                });
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_INVALID_TAKE", String(err)));
-        }
-    });
-    recording
-        .command("fit <file>")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (file) {
-        const { json } = this.opts();
-        try {
-            const raw = await readFile(file, "utf8");
-            const rec = RecordingSchema.parse(JSON.parse(raw));
-            const interaction = fitInteractionPolicy(rec);
-            const policy = { version: "1.0.0", interaction };
-            if (json) {
-                emitJson(program, ok(policy));
-            }
-            else {
-                program.configureOutput().writeOut?.(`${JSON.stringify(policy, null, 2)}\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_INVALID_RECORDING", String(err)));
-        }
-    });
-    recording
-        .command("postdoc <take> [more...]")
-        .option("--decisions <file>", "path to a PostdocDecision[] JSON file (non-interactive mode)")
-        .option("--out <file>", "write the resulting Recording to this file instead of stdout")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (take, more) {
-        const { decisions: decisionsFile, out, json } = this.opts();
-        try {
-            const files = [take, ...more];
-            const takes = await Promise.all(files.map(async (f) => {
-                const raw = await readFile(f, "utf8");
-                const parsed = AuthoringTakeSchema.parse(JSON.parse(raw));
-                return { recording: parsed.recording, values: new Map(Object.entries(parsed.values)) };
-            }));
-            const diff = diffTakes(takes);
-            let decisions;
-            if (decisionsFile !== undefined) {
-                decisions = await loadDecisions(decisionsFile);
-            }
-            else {
-                decisions = await promptForDecisions(takes[0]);
-            }
-            const result = applyPostdoc(takes[0], diff, decisions);
-            if (out !== undefined) {
-                await writeFile(out, `${JSON.stringify(result, null, 2)}\n`, "utf8");
-            }
-            if (json) {
-                emitJson(program, ok(result));
-            }
-            else if (out === undefined) {
-                program.configureOutput().writeOut?.(`${JSON.stringify(result, null, 2)}\n`);
-                process.exitCode = 0;
-            }
-            else {
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof DecisionsParseError) {
-                emitJson(program, fail("E_INVALID_DECISIONS", String(err.cause)));
-            }
-            else {
-                emitJson(program, fail("E_INVALID_TAKE", String(err)));
-            }
-        }
-    });
-    const journey = program.command("journey");
-    /**
-     * `journey list` = ALL journeys' metadata via the store directly
-     * (promoted AND unpromoted) — a local/dev-facing listing of everything on
-     * disk. `journey find` (below) = promoted-only, via `JourneyRegistry.find`
-     * — the same promoted-only projection external callers (e.g. the
-     * mcp-facade) see. Keeping these distinct means `list` is useful for
-     * authoring/debugging while `find` genuinely reflects what's discoverable.
-     */
-    journey
-        .command("list")
-        .option("--dir <path>", "journeys directory (default: ~/.jevitate/journeys)")
-        .option("--json", "emit a JSON envelope")
-        .action(async function () {
-        const { dir, json } = this.opts();
-        try {
-            const store = new FsJourneyStore(resolveJourneysDir(deps, dir));
-            const metas = await store.list();
-            const envelope = ok(metas);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                const out = program.configureOutput().writeOut;
-                for (const m of metas) {
-                    out?.(`${m.id}\t${m.name}${m.promoted ? "" : " (unpromoted)"}\n`);
-                }
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_JOURNEY_LIST", String(err)));
-        }
-    });
-    // RULING 5: uses `JourneyRegistry.find` (from `@jevitate/journey`) directly —
-    // NEVER `@jevitate/mcp-facade`'s `findCapabilities` — Slice 1 forbids the CLI
-    // depending on `@jevitate/mcp-facade`. `JourneyRegistry.find` is already
-    // promoted-only, so this is the same promoted-only view without the
-    // forbidden dependency.
-    journey
-        .command("find <query>")
-        .option("--dir <path>", "journeys directory (default: ~/.jevitate/journeys)")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (query) {
-        const { dir, json } = this.opts();
-        try {
-            const store = new FsJourneyStore(resolveJourneysDir(deps, dir));
-            const registry = new JourneyRegistry(store);
-            const metas = await registry.find(query);
-            const capabilities = metas.map((m) => ({
-                id: m.id,
-                name: m.name,
-                description: m.description,
-                params: m.params,
-            }));
-            const envelope = ok(capabilities);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                const out = program.configureOutput().writeOut;
-                for (const c of capabilities) {
-                    out?.(`${c.id}\t${c.name}\tparams=[${c.params.join(", ")}]\n`);
-                }
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_JOURNEY_FIND", String(err)));
-        }
-    });
-    journey
-        .command("run <id>")
-        .option("--dir <path>", "journeys directory (default: ~/.jevitate/journeys)")
-        .option("--param <kv>", "param as key=value (repeatable)", collectParam, {})
-        // Ticket #7 (additive): opt a run into scoped self-healing. Default
-        // `fail-closed` preserves Slice 1 behavior exactly (no healer wired). A
-        // write/irreversible step NEVER auto-heals in any mode (enforced by the
-        // runtime's write floor). `hybrid`/`full` need an AI gateway, selected
-        // with --real/--fake-ai (mirrors `explore`); requesting a heal mode
-        // without one fails CLOSED, never a silent unhealed run.
-        .option("--self-heal <mode>", "self-heal policy mode: fail-closed | hybrid | full", "fail-closed")
-        .option("--real", "use live Jev + OpenRouter gateways for self-heal (requires keys)", false)
-        .option("--fake-ai", "use deterministic fake gateways for self-heal (pipeline smoke only)", false)
-        .option("--json", "emit a JSON envelope")
-        .action(async function (id) {
-        const { dir, param, selfHeal, real, fakeAi, json } = this.opts();
-        if (selfHeal !== "fail-closed" && selfHeal !== "hybrid" && selfHeal !== "full") {
-            emitJson(program, fail("E_SELF_HEAL_MODE", `--self-heal must be one of fail-closed | hybrid | full (got '${selfHeal}')`));
-            return;
-        }
-        const selfHealMode = selfHeal;
-        // When a heal mode is requested, build the SelfHealer HERE (this action
-        // owns `deps` + the credential preflight); a missing/unselected gateway
-        // fails CLOSED before any browser launch, rather than silently running
-        // with no healer. fail-closed needs no gateway (identical to today).
-        let selfHealer;
-        let policy = safeRunPolicy();
-        if (selfHealMode !== "fail-closed") {
-            let judge;
-            let gen;
-            try {
-                ({ judge, gen } = await buildExploreGateways(deps, { real: real ?? false, fakeAi: fakeAi ?? false }));
-            }
-            catch (err) {
-                if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError) {
-                    emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
-                }
-                else {
-                    emitJson(program, fail("E_JOURNEY_RUN", String(err instanceof Error ? err.message : err)));
-                }
-                return;
-            }
-            selfHealer = makeExploreSelfHealer(judge, gen);
-            policy = { ...policy, selfHeal: { mode: selfHealMode } };
-        }
-        try {
-            // `runJourneyProgrammatically` validates params UP FRONT (before any
-            // browser launch). The default policy stays `safeRunPolicy()`
-            // (fail-closed secret mode) — only `selfHeal.mode` is threaded from
-            // the flag; a `--secret-mode` override is a later slice's concern.
-            const result = await runJourneyProgrammatically({
-                dir: resolveJourneysDir(deps, dir),
-                id,
-                params: param,
-                policy,
-                selfHealer,
-            });
-            const envelope = ok(result);
-            if (json) {
-                emitJson(program, envelope);
-                // "ok" and "healed" (a recovered run) are both successes; only
-                // "quarantined" is a non-zero exit.
-                if (result.outcome === "quarantined")
-                    process.exitCode = 1;
-            }
-            else {
-                program.configureOutput().writeOut?.(`${JSON.stringify(result)}\n`);
-                process.exitCode = result.outcome === "quarantined" ? 1 : 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnknownJourneyError) {
-                emitJson(program, fail("E_UNKNOWN_JOURNEY", String(err.message)));
-            }
-            else if (err instanceof ParamValidationError) {
-                emitJson(program, fail("E_INVALID_PARAMS", String(err.message)));
-            }
-            else {
-                emitJson(program, fail("E_JOURNEY_RUN", String(err)));
-            }
-        }
-    });
-    // #19 — publish a promoted local Journey to a registered distributed source.
-    // Preserves every publish-side guard in `@jevitate/sources` (promoted-only,
-    // secret-references-only, declared-origin coverage); writes onto a NEW
-    // `publish/<id>` branch and degrades gracefully when `gh` is absent.
-    journey
-        .command("publish <id>")
-        .requiredOption("--to <source>", "registered source name to publish into")
-        .option("--dir <path>", "journeys directory (default: ~/.jevitate/journeys)")
-        .option("--declare-origin <origin>", "origin this Journey is authorized for (repeatable; default: derived from navigate steps)", (v, prev) => [...prev, v], [])
-        .option("--as <id>", "publish under a different id than the local one")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (id) {
-        const { to, dir, declareOrigin, as: asId, json } = this.opts();
-        try {
-            const apiDeps = resolveSourceApiDeps(deps);
-            const gh = deps.sources?.gh ?? realGhPort;
-            const result = await publishJourneyToSource({ ...apiDeps, gh }, {
-                journeysDir: resolveJourneysDir(deps, dir),
-                id,
-                toSource: to,
-                declareOrigins: declareOrigin,
-                asId,
-            });
-            const envelope = ok(result);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                const out = program.configureOutput().writeOut;
-                out?.(`published '${id}' to '${to}' on branch ${result.branch}\n`);
-                if (result.prUrl)
-                    out?.(`PR: ${result.prUrl}\n`);
-                else if (result.instructions)
-                    out?.(`${result.instructions}\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnknownSourceError) {
-                emitJson(program, fail("E_JOURNEY_PUBLISH_UNKNOWN_SOURCE", err.message));
-            }
-            else if (err instanceof UnknownJourneyError) {
-                emitJson(program, fail("E_JOURNEY_PUBLISH_UNKNOWN_JOURNEY", err.message));
-            }
-            else if (err instanceof NotPromotedError) {
-                emitJson(program, fail("E_JOURNEY_PUBLISH_NOT_PROMOTED", err.message));
-            }
-            else if (err instanceof NoDeclaredOriginsError) {
-                emitJson(program, fail("E_JOURNEY_PUBLISH_NO_ORIGINS", err.message));
-            }
-            else if (err instanceof EmbeddedSecretError) {
-                emitJson(program, fail("E_JOURNEY_PUBLISH_SECRET", err.message));
-            }
-            else if (err instanceof UndeclaredOriginError) {
-                emitJson(program, fail("E_JOURNEY_PUBLISH_ORIGIN", err.message));
-            }
-            else {
-                emitJson(program, fail("E_JOURNEY_PUBLISH", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    // #18 — manage distributed Journey sources (add/list/pull/update/remove/
-    // trust). Trust is an explicit user act, content-hash-bound; add/pull/update
-    // never trust anything implicitly.
-    const source = program.command("source");
-    source
-        .command("add <name> <gitUrl>")
-        .option("--accept-tou", "acknowledge the source's declared Terms of Use (required before its Journeys can run)")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (name, gitUrl) {
-        const { acceptTou, json } = this.opts();
-        try {
-            const apiDeps = resolveSourceApiDeps(deps);
-            const result = await addSource(apiDeps, {
-                name,
-                gitUrl,
-                acceptTou: acceptTou ?? false,
-                ackedBy: resolveApprovedBy(deps),
-            });
-            const envelope = ok(result);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                const out = program.configureOutput().writeOut;
-                out?.(`added '${name}' pinned at ${result.pinnedCommit}\n`);
-                out?.(`Terms of Use for ${result.touSurface.gitUrl}:\n`);
-                for (const site of result.touSurface.sites)
-                    out?.(`  ${site.origin}\t${site.touBasis}\n`);
-                out?.(result.touAccepted ? "ToU acknowledged.\n" : "ToU NOT acknowledged — re-run with --accept-tou before running this source's Journeys.\n");
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof SourceValidationError) {
-                emitJson(program, fail("E_SOURCE_INVALID_MANIFEST", err.message));
-            }
-            else {
-                emitJson(program, fail("E_SOURCE_ADD", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    source
-        .command("list")
-        .option("--json", "emit a JSON envelope")
-        .action(async function () {
-        const { json } = this.opts();
-        try {
-            const listing = await listSources(resolveSourceApiDeps(deps));
-            const envelope = ok(listing);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                const out = program.configureOutput().writeOut;
-                for (const s of listing) {
-                    out?.(`${s.name}\t${s.gitUrl}\t${s.pinnedCommit}\ttrusted=[${s.trustedJourneys.join(", ")}]\n`);
-                }
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_SOURCE_LIST", String(err instanceof Error ? err.message : err)));
-        }
-    });
-    source
-        .command("pull <name>")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (name) {
-        const { json } = this.opts();
-        try {
-            const result = await pullSource(resolveSourceApiDeps(deps), name);
-            const envelope = ok(result);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`pulled '${name}' (pin unchanged at ${result.pinnedCommit}; run 'source update' to advance)\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnknownSourceError) {
-                emitJson(program, fail("E_SOURCE_UNKNOWN", err.message));
-            }
-            else {
-                emitJson(program, fail("E_SOURCE_PULL", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    source
-        .command("update <name>")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (name) {
-        const { json } = this.opts();
-        try {
-            const result = await updateSource(resolveSourceApiDeps(deps), name);
-            const envelope = ok(result);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`updated '${name}' -> pinned at ${result.pinnedCommit}\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnknownSourceError) {
-                emitJson(program, fail("E_SOURCE_UNKNOWN", err.message));
-            }
-            else {
-                emitJson(program, fail("E_SOURCE_UPDATE", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    source
-        .command("remove <name>")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (name) {
-        const { json } = this.opts();
-        try {
-            const result = await removeSource(resolveSourceApiDeps(deps), name);
-            const envelope = ok(result);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`removed '${name}'\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnknownSourceError) {
-                emitJson(program, fail("E_SOURCE_UNKNOWN", err.message));
-            }
-            else {
-                emitJson(program, fail("E_SOURCE_REMOVE", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    source
-        .command("trust <name> <journeyId>")
-        .description("explicitly trust one Journey in a source, bound to its current content hash")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (name, journeyId) {
-        const { json } = this.opts();
-        try {
-            const result = await trustJourney(resolveSourceApiDeps(deps), {
-                sourceName: name,
-                journeyId,
-                approvedBy: resolveApprovedBy(deps),
-            });
-            // Never emit the Journey's content — only the address + bound hash.
-            const view = { sourceId: result.sourceId, journeyId: result.journeyId, contentHash: result.contentHash, approvedBy: result.approvedBy, approvedAtIso: result.approvedAtIso };
-            const envelope = ok(view);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`trusted '${name}/${journeyId}' at ${result.contentHash}\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnknownSourceError) {
-                emitJson(program, fail("E_SOURCE_UNKNOWN", err.message));
-            }
-            else if (err instanceof UnknownJourneyError) {
-                emitJson(program, fail("E_SOURCE_UNKNOWN_JOURNEY", err.message));
-            }
-            else {
-                emitJson(program, fail("E_SOURCE_TRUST", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    // #26 — run a Journey that lives in a trusted remote source, THROUGH the
-    // existing run-gate (`@jevitate/sources`' `resolveForRun`). RULING: this is a
-    // `source run` subcommand (not `journey run --from-source`) because the whole
-    // trust boundary is source-scoped — the `<source>/<id>` address, the
-    // per-source manifest/ToU-ack/trust records all live under `source`. `journey
-    // run` stays the LOCAL FsJourneyStore path; keeping remote runs here keeps the
-    // two trust boundaries visibly separate. The run NEVER bypasses a gate: every
-    // refusal below is a typed error thrown by `resolveForRun` BEFORE any browser.
-    source
-        .command("run <name> <journeyId>")
-        .description("run a Journey from a trusted remote source through the run-gate")
-        .option("--param <kv>", "param as key=value (repeatable)", collectParam, {})
-        .option("--json", "emit a JSON envelope")
-        .action(async function (name, journeyId) {
-        const { param, json } = this.opts();
-        try {
-            const apiDeps = {
-                ...resolveSourceApiDeps(deps),
-                runJourney: deps.sources?.runJourney ?? realResolvedJourneyRunner,
-            };
-            const result = await runSourceJourney(apiDeps, { sourceName: name, journeyId, params: param });
-            const envelope = ok(result);
-            if (json) {
-                emitJson(program, envelope);
-                if (result.outcome === "quarantined")
-                    process.exitCode = 1;
-            }
-            else {
-                program.configureOutput().writeOut?.(`${JSON.stringify(result)}\n`);
-                process.exitCode = result.outcome === "quarantined" ? 1 : 0;
-            }
-        }
-        catch (err) {
-            // Each run-gate refusal maps to a distinct E_SOURCE_RUN* code so a
-            // caller can tell WHY the run was refused without string-matching.
-            if (err instanceof UnknownSourceError) {
-                emitJson(program, fail("E_SOURCE_RUN_UNKNOWN", err.message));
-            }
-            else if (err instanceof HashMismatchError) {
-                emitJson(program, fail("E_SOURCE_RUN_HASH_MISMATCH", err.message));
-            }
-            else if (err instanceof UntrustedRiskyJourneyError) {
-                emitJson(program, fail("E_SOURCE_RUN_UNTRUSTED", err.message));
-            }
-            else if (err instanceof UndeclaredOriginError) {
-                emitJson(program, fail("E_SOURCE_RUN_ORIGIN", err.message));
-            }
-            else if (err instanceof UndeclaredTouError) {
-                emitJson(program, fail("E_SOURCE_RUN_TOU", err.message));
-            }
-            else if (err instanceof EmbeddedSecretError) {
-                emitJson(program, fail("E_SOURCE_RUN_SECRET", err.message));
-            }
-            else if (err instanceof SourceValidationError) {
-                emitJson(program, fail("E_SOURCE_RUN_INVALID_MANIFEST", err.message));
-            }
-            else if (err instanceof ParamValidationError) {
-                emitJson(program, fail("E_INVALID_PARAMS", err.message));
-            }
-            else {
-                emitJson(program, fail("E_SOURCE_RUN", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    const load = program.command("load");
-    load
-        .command("run <journeyId>")
-        .option("--dir <path>", "journeys directory (default: ~/.jevitate/journeys)")
-        .option("--param <kv>", "param as key=value (repeatable)", collectParam, {})
-        // `--authorized-origin` is mandatory, but enforced IN THE ACTION (below)
-        // via a `fail` envelope rather than commander's `.requiredOption` — which
-        // hard-exits via `process.exit`, inconsistent with this CLI's convention
-        // of emitting a JSON envelope + setting `process.exitCode` (see emitJson).
-        .option("--authorized-origin <origin>", "allowed load-test target origin (repeatable) — required, fails closed if omitted", (v, prev) => [...prev, v], [])
-        .option("--concurrency <n>", "pool size", "1")
-        .option("--iterations <n>", "iterations per actor", "1")
-        .option("--seed <n>", "master RNG seed", "1")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (journeyId) {
-        const { dir, param, authorizedOrigin, concurrency, iterations, seed, json } = this.opts();
-        if (authorizedOrigin.length === 0) {
-            emitJson(program, fail("E_LOAD_RUN", "at least one --authorized-origin is required (refusing to load-test with an empty allowlist)"));
-            return;
-        }
-        try {
-            const report = await runJourneyLoadTest({
-                dir: resolveJourneysDir(deps, dir),
-                id: journeyId,
-                params: param,
-                concurrency: Number(concurrency),
-                iterationsPerActor: Number(iterations),
-                seed: Number(seed),
-                authorizedOrigins: authorizedOrigin,
-            });
-            const envelope = ok(report);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`${JSON.stringify(report, null, 2)}\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnknownLoadJourneyError) {
-                emitJson(program, fail("E_UNKNOWN_JOURNEY", String(err.message)));
-            }
-            else {
-                emitJson(program, fail("E_LOAD_RUN", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    program
-        .command("explore")
-        .description("goal-directed exploration -> a deterministic Recording (authoring/test plane)")
-        .option("--url <url>", "target URL (must be an authorized origin)")
-        .option("--strategy <name>", "exploration strategy: goal (default) | coverage | exploratory | adversarial | usability (UX review: ranked, cited findings)", "goal")
-        .option("--goal <text>", "natural-language goal / job (required for --strategy goal and usability)")
-        .option("--app-class <class>", "app class for UX calibration (required for --strategy usability), e.g. consumer|admin|internal")
-        .option("--success <spec>", "independent success assertion, e.g. urlIncludes:/inbox")
-        .option("--feature <name>", "run the capability-scoped feature-testing mission (instead of --goal/--success)")
-        .option("--route <glob>", "in-scope route glob for --feature (repeatable), e.g. /thread/**", (v, prev) => [...prev, v], [])
-        .option("--allow <origin>", "authorized origin (repeatable); defaults to the URL's own origin", (v, prev) => [...prev, v], [])
-        .option("--secret <value>", "a secret/PII value to keep out of every model call (repeatable)", (v, prev) => [...prev, v], [])
-        .option("--max-actions <n>", "hard cap on executed actions")
-        .option("--max-decisions <n>", "hard cap on model decisions")
-        .option("--real", "use live Jev + OpenRouter gateways (requires keys)", false)
-        .option("--fake-ai", "use deterministic fake gateways (pipeline smoke only)", false)
-        .option("--out <dir>", "directory to write the emitted Recording")
-        .option("--json", "emit a JSON envelope")
-        .action(async function () {
-        const o = this.opts();
-        const strategy = o.strategy ?? "goal";
-        // Additive coverage/exploratory strategy: proof-by-induction state coverage.
-        // It takes no goal/success (the frontier itself is the objective), so it is
-        // a distinct, goal-free path that leaves the goal strategy below unchanged.
-        if (strategy === "coverage" || strategy === "exploratory") {
-            if (!o.url) {
-                emitJson(program, fail("E_EXPLORE_ARGS", "--url is required"));
-                return;
-            }
-            const covAllowlist = resolveExploreAllowlist(o.url, o.allow);
-            const covBounds = {};
-            if (o.maxActions !== undefined)
-                covBounds.maxActions = Number(o.maxActions);
-            if (o.maxDecisions !== undefined)
-                covBounds.maxDecisions = Number(o.maxDecisions);
-            let covJudge;
-            let covGen;
-            try {
-                ({ judge: covJudge, gen: covGen } = await buildExploreGateways(deps, {
-                    real: o.real ?? false,
-                    fakeAi: o.fakeAi ?? false,
-                }));
-            }
-            catch (err) {
-                if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError) {
-                    emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
-                }
-                else {
-                    emitJson(program, fail("E_EXPLORE_SETUP", String(err instanceof Error ? err.message : err)));
-                }
-                return;
-            }
-            try {
-                const result = await runCoverageMission({
-                    url: o.url,
-                    allowlist: covAllowlist,
-                    judge: covJudge,
-                    gen: covGen,
-                    bounds: Object.keys(covBounds).length > 0 ? covBounds : undefined,
-                    outDir: o.out,
-                    browserPortFactory: deps.explore?.browserPortFactory,
-                });
-                const envelope = ok(result);
-                if (o.json) {
-                    emitJson(program, envelope);
-                }
-                else {
-                    program.configureOutput().writeOut?.(`${JSON.stringify(result)}\n`);
-                }
-                if (result.coverage.defects.length > 0)
-                    process.exitCode = 1;
-            }
-            catch (err) {
-                if (err instanceof UnauthorizedExploreTargetError) {
-                    emitJson(program, fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
-                }
-                else {
-                    emitJson(program, fail("E_EXPLORE_RUN", String(err instanceof Error ? err.message : err)));
-                }
-            }
-            return;
-        }
-        // Additive adversarial strategy: a bounded "try to break it" run whose
-        // stop decision comes from a trusted hard-signal oracle (never Jev's
-        // Noul). Requires only --url; --goal/--success are goal-strategy inputs.
-        if (strategy === "adversarial") {
-            if (!o.url) {
-                emitJson(program, fail("E_EXPLORE_ARGS", "--url is required for --strategy adversarial"));
-                return;
-            }
-            const advAllowlist = resolveExploreAllowlist(o.url, o.allow);
-            let advJudge;
-            let advGen;
-            try {
-                ({ judge: advJudge, gen: advGen } = await buildExploreGateways(deps, {
-                    real: o.real ?? false,
-                    fakeAi: o.fakeAi ?? false,
-                }));
-            }
-            catch (err) {
-                if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError) {
-                    emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
-                }
-                else {
-                    emitJson(program, fail("E_EXPLORE_SETUP", String(err instanceof Error ? err.message : err)));
-                }
-                return;
-            }
-            const profileDir = await mkdtemp(join(tmpdir(), "jevitate-adversarial-"));
-            try {
-                const result = await runAdversarialCliMission({
-                    seedUrl: o.url,
-                    allowlist: advAllowlist,
-                    strategies: [
-                        "ordering-violation",
-                        "repeat-rapid",
-                        "boundary-input",
-                        "contradictory-actions",
-                        "nav-during-pending",
-                    ],
-                    judgment: advJudge,
-                    generation: advGen,
-                    profileDir,
-                    browserPortFactory: deps.explore?.browserPortFactory,
-                });
-                emitJson(program, ok(result));
-                // A discovered defect gates CI, mirroring how a failing test would.
-                if (result.outcome === "defect")
-                    process.exitCode = 1;
-            }
-            catch (err) {
-                if (err instanceof UnauthorizedExploreTargetError) {
-                    emitJson(program, fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
-                }
-                else {
-                    emitJson(program, fail("E_EXPLORE_RUN", String(err instanceof Error ? err.message : err)));
-                }
-            }
-            finally {
-                await rm(profileDir, { recursive: true, force: true });
-            }
-            return;
-        }
-        // Additive: `--strategy usability` (issue #30) — a UX review. Reuses the
-        // explore loop (goal = the job) and analyzes each observed screen against
-        // the cited @jevitate/ux rubric. Findings are ADVISORY: a UX finding never
-        // gates the run (no non-zero exit).
-        if (strategy === "usability") {
-            if (!o.url || !o.goal) {
-                emitJson(program, fail("E_EXPLORE_ARGS", "--url and --goal (the job) are required for --strategy usability"));
-                return;
-            }
-            if (!o.appClass) {
-                emitJson(program, fail("E_UX_ARGS", "--app-class is required for --strategy usability"));
-                return;
-            }
-            const uxAllowlist = resolveExploreAllowlist(o.url, o.allow);
-            const uxBounds = {};
-            if (o.maxActions !== undefined)
-                uxBounds.maxActions = Number(o.maxActions);
-            if (o.maxDecisions !== undefined)
-                uxBounds.maxDecisions = Number(o.maxDecisions);
-            let uxJudge;
-            let uxGen;
-            try {
-                ({ judge: uxJudge, gen: uxGen } = await buildExploreGateways(deps, {
-                    real: o.real ?? false,
-                    fakeAi: o.fakeAi ?? false,
-                }));
-            }
-            catch (err) {
-                if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError) {
-                    emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
-                }
-                else {
-                    emitJson(program, fail("E_EXPLORE_SETUP", String(err instanceof Error ? err.message : err)));
-                }
-                return;
-            }
-            try {
-                const result = await runUsabilityMission({
-                    url: o.url,
-                    job: o.goal,
-                    allowlist: uxAllowlist,
-                    appContext: { appClass: o.appClass, job: o.goal },
-                    judge: uxJudge,
-                    gen: uxGen,
-                    bounds: Object.keys(uxBounds).length > 0 ? uxBounds : undefined,
-                    secrets: o.secret.length > 0 ? o.secret : undefined,
-                    outDir: o.out,
-                    browserPortFactory: deps.explore?.browserPortFactory,
-                });
-                emitJson(program, ok(result));
-            }
-            catch (err) {
-                if (err instanceof UnauthorizedExploreTargetError) {
-                    emitJson(program, fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
-                }
-                else if (err instanceof UxAnalysisFailedError) {
-                    emitJson(program, fail("E_UX_ANALYSIS", err.message));
-                }
-                else {
-                    emitJson(program, fail("E_EXPLORE_RUN", String(err instanceof Error ? err.message : err)));
-                }
-            }
-            return;
-        }
-        // Additive: `--feature <name>` runs the capability-scoped feature-testing
-        // mission (ticket #2 / site #11). It is model-free, so it needs neither
-        // --goal/--success nor a gateway selection; the goal-based path below is
-        // untouched when --feature is absent.
-        if (o.feature) {
-            if (!o.url) {
-                emitJson(program, fail("E_EXPLORE_ARGS", "--url is required with --feature"));
-                return;
-            }
-            const featAllowlist = resolveExploreAllowlist(o.url, o.allow);
-            const profileDir = await mkdtemp(join(tmpdir(), "jevitate-feature-"));
-            try {
-                const result = await runFeatureCliMission({
-                    seedUrl: o.url,
-                    allowlist: featAllowlist,
-                    capability: o.feature,
-                    routeGlobs: o.route ?? [],
-                    profileDir,
-                });
-                emitJson(program, ok(result));
-            }
-            catch (err) {
-                if (err instanceof UnauthorizedExploreTargetError) {
-                    emitJson(program, fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
-                }
-                else {
-                    emitJson(program, fail("E_EXPLORE_RUN", String(err instanceof Error ? err.message : err)));
-                }
-            }
-            finally {
-                await rm(profileDir, { recursive: true, force: true });
-            }
-            return;
-        }
-        if (!o.url || !o.goal || !o.success) {
-            emitJson(program, fail("E_EXPLORE_ARGS", "--url, --goal and --success are all required"));
-            return;
-        }
-        let successAssertion;
-        try {
-            successAssertion = parseAssertionSpec(o.success);
-        }
-        catch (err) {
-            emitJson(program, fail("E_EXPLORE_ASSERTION", String(err instanceof Error ? err.message : err)));
-            return;
-        }
-        const allowlist = resolveExploreAllowlist(o.url, o.allow);
-        const bounds = {};
-        if (o.maxActions !== undefined)
-            bounds.maxActions = Number(o.maxActions);
-        if (o.maxDecisions !== undefined)
-            bounds.maxDecisions = Number(o.maxDecisions);
-        let judge;
-        let gen;
-        try {
-            ({ judge, gen } = await buildExploreGateways(deps, { real: o.real ?? false, fakeAi: o.fakeAi ?? false }));
-        }
-        catch (err) {
-            if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError) {
-                emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
-            }
-            else {
-                emitJson(program, fail("E_EXPLORE_SETUP", String(err instanceof Error ? err.message : err)));
-            }
-            return;
-        }
-        try {
-            const result = await runExploration({
-                url: o.url,
-                goal: o.goal,
-                successAssertion,
-                allowlist,
-                judge,
-                gen,
-                bounds: Object.keys(bounds).length > 0 ? bounds : undefined,
-                secrets: o.secret.length > 0 ? o.secret : undefined,
-                outDir: o.out,
-                browserPortFactory: deps.explore?.browserPortFactory,
-            });
-            const envelope = ok(result);
-            if (o.json) {
-                emitJson(program, envelope);
-                if (result.outcome !== "succeeded")
-                    process.exitCode = 1;
-            }
-            else {
-                program.configureOutput().writeOut?.(`${JSON.stringify(result)}\n`);
-                process.exitCode = result.outcome === "succeeded" ? 0 : 1;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnauthorizedExploreTargetError) {
-                emitJson(program, fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
-            }
-            else {
-                emitJson(program, fail("E_EXPLORE_RUN", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    // Additive: `explore author-journey` — Jev-driving authors a promotable
-    // Journey (Ticket #6). Drives the goal-based mission, feeds its take(s)
-    // through RxD's diff/postdoc pipeline, and writes an UNPROMOTED,
-    // parameterized Journey to the journeys store. The record-by-demonstration
-    // authoring path is untouched.
-    program
-        .command("explore-author-journey")
-        .description("Jev-driving authors a promotable Journey (authoring plane); never auto-promoted")
-        .option("--url <url>", "target URL (must be an authorized origin)")
-        .option("--goal <text>", "natural-language goal")
-        .option("--success <spec>", "independent success assertion, e.g. urlIncludes:/confirmed")
-        .option("--id <id>", "journey id (used for the <id>.json filename in the store)")
-        .option("--name <name>", "human-readable journey name")
-        .option("--takes <n>", "corroborating takes incl. discovery (default 1)", "1")
-        .option("--journeys-dir <dir>", "journeys store directory (default: ~/.jevitate/journeys)")
-        .option("--allow <origin>", "authorized origin (repeatable); defaults to the URL's own origin", (v, prev) => [...prev, v], [])
-        .option("--max-actions <n>", "hard cap on executed actions")
-        .option("--max-decisions <n>", "hard cap on model decisions")
-        .option("--real", "use live Jev + OpenRouter gateways (requires keys)", false)
-        .option("--fake-ai", "use deterministic fake gateways (pipeline smoke only)", false)
-        .option("--json", "emit a JSON envelope")
-        .action(async function () {
-        const o = this.opts();
-        if (!o.url || !o.goal || !o.success || !o.id || !o.name) {
-            emitJson(program, fail("E_AUTHOR_ARGS", "--url, --goal, --success, --id and --name are all required"));
-            return;
-        }
-        let successAssertion;
-        try {
-            successAssertion = parseAssertionSpec(o.success);
-        }
-        catch (err) {
-            emitJson(program, fail("E_EXPLORE_ASSERTION", String(err instanceof Error ? err.message : err)));
-            return;
-        }
-        const allowlist = resolveExploreAllowlist(o.url, o.allow);
-        const bounds = {};
-        if (o.maxActions !== undefined)
-            bounds.maxActions = Number(o.maxActions);
-        if (o.maxDecisions !== undefined)
-            bounds.maxDecisions = Number(o.maxDecisions);
-        let judge;
-        let gen;
-        try {
-            ({ judge, gen } = await buildExploreGateways(deps, { real: o.real ?? false, fakeAi: o.fakeAi ?? false }));
-        }
-        catch (err) {
-            if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError) {
-                emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
-            }
-            else {
-                emitJson(program, fail("E_EXPLORE_SETUP", String(err instanceof Error ? err.message : err)));
-            }
-            return;
-        }
-        try {
-            const result = await runAuthorJourney({
-                url: o.url,
-                goal: o.goal,
-                successAssertion,
-                allowlist,
-                journeysDir: resolveJourneysDir(deps, o.journeysDir),
-                journeyId: o.id,
-                journeyName: o.name,
-                takes: Number(o.takes),
-                judge,
-                gen,
-                bounds: Object.keys(bounds).length > 0 ? bounds : undefined,
-                browserPortFactory: deps.explore?.browserPortFactory,
-            });
-            const envelope = ok(result);
-            if (o.json) {
-                emitJson(program, envelope);
-                if (result.outcome !== "authored")
-                    process.exitCode = 1;
-            }
-            else {
-                program.configureOutput().writeOut?.(`${JSON.stringify(result)}\n`);
-                process.exitCode = result.outcome === "authored" ? 0 : 1;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnauthorizedExploreTargetError) {
-                emitJson(program, fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
-            }
-            else {
-                emitJson(program, fail("E_AUTHOR_JOURNEY", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    // Additive: `jevitate record` — record-by-demonstration (Ticket #22). Opens a
-    // real browser on an authorized origin, lets the user demonstrate a flow, and
-    // captures it into a schema-valid, replayable Recording written to disk. The
-    // authorized-origin guard is enforced FIRST (fail-closed) inside runRecording,
-    // before any browser is opened; the temp profile dir is always cleaned up.
-    program
-        .command("record")
-        .description("record a demonstrated flow into a Recording (authoring plane)")
-        .option("--url <url>", "start URL to demonstrate from (must be an authorized origin)")
-        .option("--intent <text>", "your framing of the journey (carried to Recording.intent)")
-        .option("--retro <text>", "optional retrospective note (carried to Recording.retro)")
-        .option("--allow <origin>", "authorized origin (repeatable); defaults to the URL's own origin", (v, prev) => [...prev, v], [])
-        .option("--headless", "run headless (default: headed — a record session is a live demonstration)", false)
-        .option("--out <dir>", "directory to write the emitted Recording (default: ~/.jevitate/recordings)")
-        .option("--json", "emit a JSON envelope")
-        .action(async function () {
-        const o = this.opts();
-        if (!o.url) {
-            emitJson(program, fail("E_RECORD_ARGS", "--url is required"));
-            return;
-        }
-        const allowlist = resolveRecordAllowlist(o.url, o.allow);
-        try {
-            const result = await runRecording({
-                url: o.url,
-                allowlist,
-                intent: o.intent,
-                retro: o.retro,
-                outDir: o.out,
-                headless: o.headless ?? false,
-                browserPortFactory: deps.record?.browserPortFactory,
-                recorderFactory: deps.record?.recorderFactory,
-                waitForStop: deps.record?.waitForStop,
-            });
-            const summary = {
-                recordingPath: result.recordingPath,
-                steps: result.steps,
-                pages: result.pages,
-                finalUrl: result.finalUrl,
-            };
-            if (o.json) {
-                emitJson(program, ok(summary));
-            }
-            else {
-                program.configureOutput().writeOut?.(`${JSON.stringify(summary)}\n`);
-            }
-        }
-        catch (err) {
-            if (err instanceof UnauthorizedExploreTargetError) {
-                emitJson(program, fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
-            }
-            else {
-                emitJson(program, fail("E_RECORD_RUN", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    // Additive: `@jevitate/regression` — reproduce -> minimize -> commit a
-    // failing Recording into a committed regression artifact (Ticket #5).
-    // Independent of the `journey`/`load` commands above; wires a real
-    // Playwright-backed `makeActor` (one fresh browser session per
-    // reproduce/minimize attempt, closed after each use) into
-    // `runRegressionCapture`.
-    const regression = program.command("regression");
-    regression
-        .command("capture")
-        .requiredOption("--from <file>", "path to the schema-valid failing Recording JSON to capture")
-        .requiredOption("--id <id>", "regression id (used for the committed <id>.recording.json/<id>.meta.json filenames)")
-        .option("--dir <path>", "regressions directory (default: ~/.jevitate/regressions)")
-        .option("--attempts <n>", "reproduction attempts before labeling flaky", "3")
-        .option("--summary <text>", "optional human-readable bug summary recorded in the meta sidecar")
-        .option("--json", "emit a JSON envelope")
-        .action(async function () {
-        const { from, id, dir, attempts, summary, json } = this.opts();
-        const opened = [];
-        try {
-            const raw = JSON.parse(await readFile(from, "utf8"));
-            const recording = RecordingSchema.parse(raw);
-            const result = await runRegressionCapture({
-                failingRecordingPath: from,
-                id,
-                regressionsDir: resolveRegressionsDir(dir),
-                attempts: Number(attempts),
-                bugSummary: summary,
-                makeActor: async () => {
-                    const { actor, close } = await makeRealBrowserActor(recording.site);
-                    opened.push(close);
-                    return actor;
-                },
-            });
-            const envelope = ok(result);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`${JSON.stringify(result)}\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_REGRESSION_CAPTURE", String(err instanceof Error ? err.message : err)));
-        }
-        finally {
-            for (const close of opened)
-                await close();
-        }
-    });
-    // Additive: `mission target` — register/list/promote exploration mission
-    // targets (Ticket #21). Wires the real fs-backed `@jevitate/missions`
-    // store/registry (the SAME store `queue_exploration` resolves promoted
-    // targets from). SECURITY: `add` registers UNPROMOTED — the promoted-only
-    // gate stays intact, so a registered target is not resolvable by
-    // `queue_exploration` until a separate `promote` flips it.
-    const mission = program.command("mission");
-    const missionTarget = mission.command("target");
-    missionTarget
-        .command("add <id>")
-        .description("register an exploration mission target (UNPROMOTED — not usable by queue_exploration until promoted)")
-        .option("--name <name>", "human-readable target name")
-        .option("--authorized-origin <origin>", "the single authorized exploration origin for this target")
-        .option("--base-url <url>", "the base URL a mission starts navigation from")
-        .option("--description <text>", "optional human-readable description")
-        .option("--dir <path>", "mission targets directory (default: ~/.jevitate/missions/targets)")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (id) {
-        const { name, authorizedOrigin, baseUrl, description, dir, json } = this.opts();
-        // Validate in-action + fail envelope (not commander's hard-exiting
-        // `.requiredOption`), matching this CLI's convention.
-        if (!name || !authorizedOrigin || !baseUrl) {
-            emitJson(program, fail("E_MISSION_TARGET_ARGS", "--name, --authorized-origin and --base-url are all required"));
-            return;
-        }
-        try {
-            const ctx = missionTargetContext(resolveMissionTargetsDir(deps, dir));
-            const target = await addMissionTarget(ctx, { id, name, authorizedOrigin, baseUrl, description });
-            const envelope = ok(target);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`registered mission target '${target.id}' (unpromoted — run 'jevitate mission target promote ${target.id}' to make it resolvable)\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_MISSION_TARGET_ADD", String(err instanceof Error ? err.message : err)));
-        }
-    });
-    missionTarget
-        .command("list")
-        .description("list ALL mission targets (promoted and unpromoted) — a local/dev-facing listing")
-        .option("--dir <path>", "mission targets directory (default: ~/.jevitate/missions/targets)")
-        .option("--json", "emit a JSON envelope")
-        .action(async function () {
-        const { dir, json } = this.opts();
-        try {
-            const ctx = missionTargetContext(resolveMissionTargetsDir(deps, dir));
-            const targets = await listMissionTargets(ctx);
-            const envelope = ok(targets);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                const out = program.configureOutput().writeOut;
-                for (const t of targets) {
-                    out?.(`${t.id}\t${t.name}\t${t.authorizedOrigin}${t.promoted ? "" : " (unpromoted)"}\n`);
-                }
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            emitJson(program, fail("E_MISSION_TARGET_LIST", String(err instanceof Error ? err.message : err)));
-        }
-    });
-    missionTarget
-        .command("promote <id>")
-        .description("promote a registered target so queue_exploration can resolve it")
-        .option("--dir <path>", "mission targets directory (default: ~/.jevitate/missions/targets)")
-        .option("--json", "emit a JSON envelope")
-        .action(async function (id) {
-        const { dir, json } = this.opts();
-        try {
-            const ctx = missionTargetContext(resolveMissionTargetsDir(deps, dir));
-            const target = await promoteMissionTarget(ctx, id);
-            const envelope = ok(target);
-            if (json) {
-                emitJson(program, envelope);
-            }
-            else {
-                program.configureOutput().writeOut?.(`promoted mission target '${target.id}'\n`);
-                process.exitCode = 0;
-            }
-        }
-        catch (err) {
-            if (err instanceof UnknownMissionTargetError) {
-                emitJson(program, fail("E_UNKNOWN_MISSION_TARGET", err.message));
-            }
-            else {
-                emitJson(program, fail("E_MISSION_TARGET_PROMOTE", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
-    // Additive: `jevitate mcp` (Ticket #20) — start an MCP stdio server that
-    // exposes ONLY `@jevitate/mcp-facade`'s allowlisted tools (never the raw
-    // browser primitives in FORBIDDEN_TOOLS). This is the subcommand form of the
-    // MCP server (single-bundle deployment — no separate published package).
-    // The server owns stdin/stdout as the MCP protocol channel, so on success it
-    // blocks and writes NOTHING to stdout; only a setup failure (before the
-    // transport connects) emits a JSON envelope.
-    program
-        .command("mcp")
-        .description("start an MCP stdio server exposing only the allowlisted Jevitate tools")
-        .option("--dir <path>", "journeys directory (default: ~/.jevitate/journeys)")
-        .option("--print-config <harness>", "print the config snippet to register `jevitate mcp` in a harness (claude | cursor | codex | json) and exit — prints only, writes nothing")
-        .action(async function () {
-        const { dir, printConfig } = this.opts();
-        // `--print-config <harness>` is the universal escape hatch: render the
-        // exact registration snippet and exit WITHOUT starting the server (safe:
-        // no writes, no stdio takeover). An unknown harness is a fail envelope.
-        if (printConfig !== undefined) {
-            const harness = printConfig;
-            if (harness !== "claude" && harness !== "cursor" && harness !== "codex" && harness !== "json") {
-                emitJson(program, fail("E_MCP_PRINT_CONFIG", `--print-config must be one of claude | cursor | codex | json (got '${printConfig}')`));
-                return;
-            }
-            program.configureOutput().writeOut?.(`${renderPrintConfig(harness)}\n`);
-            process.exitCode = 0;
-            return;
-        }
-        try {
-            // Credential store + generation gateway for the allowlisted
-            // `ai_generate_text` tool. The gateway is the REAL OpenRouter adapter:
-            // the key is read only inside it (Authorization header only), every
-            // outbound payload passes the never-to-model guard, and the facade's
-            // preflight returns a typed `setup_required` when the key is absent —
-            // so no `--real/--fake` flag is needed for the non-interactive server.
-            const aiStore = envCredentialStore(deps.ai?.env ?? process.env, deps.ai?.localConfig ?? {});
-            const generationGateway = deps.ai?.gateway ??
-                new OpenRouterGenerationGateway({
-                    store: aiStore,
-                    catalog: deps.ai?.catalog ?? DEFAULT_EXPLORE_CATALOG,
-                    constraints: deps.ai?.constraints ?? DEFAULT_EXPLORE_CONSTRAINTS,
-                    call: await realOpenRouterCall(),
-                });
-            await startMcpServer({
-                journeysDir: resolveJourneysDir(deps, dir),
-                missionTargetsDir: resolveMissionTargetsDir(deps),
-                missionQueueDir: resolveDataDir(["missions", "queue"]),
-                inboxDir: resolveInboxDir(deps),
-                credentialStore: aiStore,
-                generationGateway,
-            });
-        }
-        catch (err) {
-            emitJson(program, fail("E_MCP_SERVE", String(err instanceof Error ? err.message : err)));
-        }
-    });
-    // Additive: `jevitate ui` (Task 8) — starts the local, loopback-only HTTP
-    // HITL approval dashboard (ui-api.ts's `startUiServer`). Resolves the SAME
-    // inbox dir `jevitate mcp`'s inbox tools serve (resolveInboxDir), so the
-    // two commands agree on where approvals/handbacks/reviews live. On success
-    // it prints the bound URL (carrying the capability token) and stays alive —
-    // the open HTTP server keeps the process running, the same way `mcp`'s open
-    // stdio transport does.
-    program
-        .command("ui")
-        .description("start the local HITL approval dashboard (loopback-only HTTP server)")
-        .option("--port <n>", "explicit port (fails on conflict; default 4180, retries on conflict)")
-        .option("--no-open", "do not open the dashboard URL in the default browser")
-        .option("--inbox-dir <path>", "inbox store directory (default: ~/.jevitate/inbox — same dir `jevitate mcp` serves)")
-        .action(async function () {
-        const o = this.opts();
-        try {
-            const start = deps.ui?.startUiServer ?? startUiServer;
-            const handle = await start({
-                inboxDir: resolveInboxDir(deps, o.inboxDir),
-                open: o.open ?? true,
-                ...(o.port !== undefined ? { port: Number(o.port) } : {}),
-            });
-            program.configureOutput().writeOut?.(`${handle.url}\n`);
-        }
-        catch (err) {
-            emitJson(program, fail("E_UI_SERVE", String(err instanceof Error ? err.message : err)));
-        }
-    });
-    // Additive: `jevitate ux <recording>` (issue #30) — offline UX review of a
-    // saved Recording. Findings are advisory; a `failed` analysis is a non-zero
-    // fail envelope (never a fabricated clean report).
-    program
-        .command("ux <recording>")
-        .description("offline UX review of a saved Recording — ranked, cited usability findings")
-        .option("--app-class <class>", "app class for calibration (required), e.g. consumer|admin|internal")
-        .option("--persona <p>", "optional persona for calibration")
-        .option("--job <text>", "the job the flow pursues (improves relevance)")
-        .option("--out <dir>", "directory to write the UX report")
-        .option("--real", "use live Jev gateways (requires keys)", false)
-        .option("--fake-ai", "use deterministic fake gateways", false)
-        .option("--json", "emit a JSON envelope")
-        .action(async function (recordingPath) {
-        const o = this.opts();
-        if (!o.appClass) {
-            emitJson(program, fail("E_UX_ARGS", "--app-class is required"));
-            return;
-        }
-        let recording;
-        try {
-            recording = RecordingSchema.parse(JSON.parse(await readFile(recordingPath, "utf8")));
-        }
-        catch (err) {
-            emitJson(program, fail("E_UX_RECORDING", String(err instanceof Error ? err.message : err)));
-            return;
-        }
-        let uxJudge;
-        try {
-            ({ judge: uxJudge } = await buildExploreGateways(deps, { real: o.real ?? false, fakeAi: o.fakeAi ?? false }));
-        }
-        catch (err) {
-            if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError) {
-                emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
-            }
-            else {
-                emitJson(program, fail("E_UX_SETUP", String(err instanceof Error ? err.message : err)));
-            }
-            return;
-        }
-        try {
-            const result = await runUxReview({
-                recording,
-                appContext: {
-                    appClass: o.appClass,
-                    ...(o.persona ? { persona: o.persona } : {}),
-                    ...(o.job ? { job: o.job } : {}),
-                },
-                judge: uxJudge,
-                outDir: o.out,
-            });
-            emitJson(program, ok(result));
-        }
-        catch (err) {
-            if (err instanceof UxAnalysisFailedError) {
-                emitJson(program, fail("E_UX_ANALYSIS", err.message));
-            }
-            else {
-                emitJson(program, fail("E_UX_RUN", String(err instanceof Error ? err.message : err)));
-            }
-        }
-    });
+    program.name("jevitate").description("Autonomous browser testing that turns discovered bugs into deterministic regression tests").version(versionString());
+    // #218: the shared refusal path (cli-refusal.ts) needs to know which command is running.
+    trackActionCommand(program);
+    registerInitCommands(program, deps);
+    registerProfileCommands(program, deps);
+    registerSiteCommands(program, deps);
+    registerRecordingCommands(program, deps);
+    registerJourneyCommands(program, deps);
+    registerSourceCommands(program, deps);
+    registerLoadCommands(program, deps);
+    registerExploreCommands(program, deps, buildProgram);
+    registerCampaignCommands(program, deps, buildProgram); // #293: journey-anchored campaigns
+    registerVerifyFixCommands(program, deps);
+    // `ledger add|verify|list` (#195 part 6): the repro material verify-fix needs, kept by fingerprint.
+    registerLedgerCommands(program, {
+        ...(deps.explore?.targetsConfigPath === undefined ? {} : { targetsConfigPath: deps.explore.targetsConfigPath }),
+        ...(deps.explore?.browserPortFactory === undefined ? {} : { browserPortFactory: deps.explore.browserPortFactory }),
+        browserLaunch: (flags) => browserLaunchFromFlags(flags),
+    }, withBrowserLaunchFlags);
+    registerAuthorJourneyCommands(program, deps);
+    registerDemoCommands(program, deps);
+    registerRecordCommands(program, deps);
+    registerRegressionCommands(program, deps);
+    registerMissionCommands(program, deps);
+    registerServeCommands(program, deps, buildProgram);
+    registerInboxCommands(program, deps); // #254: MCP inbox tools from the CLI
+    registerUxCommands(program, deps);
     registerAiCommands(program, deps);
+    // #137 / #138 / #139 — CI gate, baseline diff and the consolidated defect report (own files).
+    registerCheckCommand(program, {
+        buildGateways: (sel) => buildExploreGateways(deps, sel),
+        journeysDir: resolveJourneysDir(deps),
+        sitePolicyDbPath: resolveDbPath(deps),
+        ...(deps.explore?.targetsConfigPath === undefined ? {} : { targetsConfigPath: deps.explore.targetsConfigPath }),
+        ...(deps.environmentsFile === undefined ? {} : { environmentsFile: deps.environmentsFile }),
+        ...(deps.explore?.browserPortFactory === undefined ? {} : { browserPortFactory: deps.explore.browserPortFactory }),
+        browserLaunch: (flags) => browserLaunchFromFlags(flags),
+    }, withBrowserLaunchFlags);
+    registerReportCommands(program, { missionTargetsDir: resolveMissionTargetsDir(deps) });
+    registerLogsCommands(program, deps);
+    registerInvariantsCommands(program);
+    registerDoctorCommand(program); // #205: resource governance — host load, machine browser slots, orphans
+    useUsageExitCode(program);
     return program;
 }
-/** Distinct from MissingCredentialError: "no --real/--fake-ai selected" vs "keys missing." */
-class GatewaySelectionError extends Error {
-}
-const DEFAULT_EXPLORE_CATALOG = [
-    { id: "openai/gpt-4o-mini", promptUsdPer1k: 0.15, completionUsdPer1k: 0.6, regions: [], latencyClass: "fast", capabilities: [] },
-];
-const DEFAULT_EXPLORE_CONSTRAINTS = { requiredCapabilities: [] };
 /**
- * Selects the exploration gateways. Injected gateways (tests) win; otherwise
- * `--real` builds the live Jev + OpenRouter adapters behind a fail-closed
- * credential preflight, and `--fake-ai` uses deterministic fakes (a pipeline
- * smoke — the fake judge always proposes `done`, so it will not drive to a
- * goal). No selection is a fail-closed refusal, never a silent fake.
+ * #210: a commander parse error (unknown option, missing argument or required option, bad choice)
+ * is a usage error — exit 64 like every command's own argument errors, never 1 (defects found).
+ * Wraps each command's `error()`, which every commander parse error goes through.
  */
-async function buildExploreGateways(deps, opts) {
-    if (deps.explore?.judge && deps.explore?.gen) {
-        return { judge: deps.explore.judge, gen: deps.explore.gen };
-    }
-    const store = envCredentialStore(deps.explore?.env ?? process.env, deps.explore?.localConfig ?? {});
-    if (opts.real) {
-        requireKeys("generation", store); // fail-closed
-        requireKeys("judgment", store); // fail-closed
-        const gen = new OpenRouterGenerationGateway({
-            store,
-            catalog: DEFAULT_EXPLORE_CATALOG,
-            constraints: DEFAULT_EXPLORE_CONSTRAINTS,
-            call: await realOpenRouterCall(),
-        });
-        const judge = new JevJudgmentGateway(store, await realJevClientCall());
-        return { judge, gen };
-    }
-    if (opts.fakeAi) {
-        return { judge: fakeDoneJudge(), gen: new FakeGenerationGateway() };
-    }
-    throw new GatewaySelectionError("no gateway selected — pass --real for live Jev+OpenRouter (after `jevitate ai setup`), or --fake-ai for a deterministic pipeline smoke");
-}
-/** A judge that always proposes `done` — used only by `--fake-ai` (smoke). */
-function fakeDoneJudge() {
-    return {
-        async systemOne(_args) {
-            return { op: { kind: "choice", value: "done", confidence: 1 } };
-        },
-    };
-}
-/** Real OpenRouter seam (lazy import; not unit-tested) — mirrors ai-cli.ts. */
-async function realOpenRouterCall() {
-    const { generateObject } = await import("ai");
-    const { createOpenRouter } = await import("@openrouter/ai-sdk-provider");
-    return async ({ model, schema, body, authHeader }) => {
-        const openrouter = createOpenRouter({ headers: { Authorization: authHeader } });
-        const start = Date.now();
-        const { object } = await generateObject({ model: openrouter(model), schema, prompt: JSON.stringify(body) });
-        return { object, latencyMs: Date.now() - start };
+function useUsageExitCode(cmd) {
+    const original = cmd.error.bind(cmd);
+    cmd.error = (message, errorOptions) => {
+        // An argParser's InvalidArgumentError (cli-args.ts) carries commander's generic exit code 1.
+        const exitCode = errorOptions?.code === "commander.invalidArgument" ? EXIT_CODES.usage : (errorOptions?.exitCode ?? EXIT_CODES.usage);
+        const bare = message.replace(/^error: /, "");
+        // #218: a bad numeric value (cli-args.ts), unknown flag or missing argument under `--json` still
+        // yields the one envelope line a machine caller parses; commander's human line goes to stderr.
+        if (exitCode === EXIT_CODES.usage && rawArgsOf(rootOf(cmd)).includes("--json")) {
+            const envelope = fail(usageParseErrorCode(cmd), bare);
+            rootOf(cmd).configureOutput().writeOut?.(`${JSON.stringify(envelope)}\n`);
+        }
+        // #227: the human stderr line matches every other refusal's `error <CODE>: …` (+ a --help hint) —
+        // never commander's own unlabeled `error: …` text, which used to be the only usage refusal
+        // without a code (the code appeared only under --json).
+        const path = commandPath(cmd);
+        const human = exitCode === EXIT_CODES.usage ? `error ${usageParseErrorCode(cmd)}: ${bare}\nnext: jevitate ${path === "" ? "" : `${path} `}--help` : message;
+        return original(human, { ...errorOptions, exitCode });
     };
+    for (const sub of cmd.commands)
+        useUsageExitCode(sub);
 }
 /**
- * Real Jev seam (documented, lazy, not unit-tested). Uses a non-literal
- * specifier so this package builds and tests without `@typesafe-ai/sdk`
- * installed; the host installs + wires it for live judgment.
+ * The envelope code of a command line commander refused while parsing it (a usage error, 64): the
+ * command's own `E_<COMMAND>_ARGS` (`explore` → E_EXPLORE_ARGS, `verify-fix` → E_VERIFY_FIX_ARGS),
+ * the code its in-action argument checks already use; `E_CLI_ARGS` at the root (an unknown command).
  */
-async function realJevClientCall() {
-    const specifier = "@typesafe-ai/sdk";
-    const sdk = (await import(specifier).catch(() => {
-        throw new Error("live judgment requires @typesafe-ai/sdk to be installed and wired (see jev.ts seam)");
-    }));
-    return async ({ state, questions, authHeader }) => {
-        const client = sdk.createClient({ authHeader });
-        return client.systemOne({ state, questions });
-    };
-}
-/**
- * Distinguishes a malformed `--decisions <file>` (E_INVALID_DECISIONS) from
- * every other failure mode of the `postdoc` action (E_INVALID_TAKE) without
- * making `loadDecisions` itself responsible for emitting the CLI envelope —
- * matching this file's existing pattern of one try/catch per subcommand
- * mapping to one error code.
- */
-class DecisionsParseError extends Error {
-    cause;
-    constructor(cause) {
-        super(String(cause));
-        this.cause = cause;
-    }
-}
-async function loadDecisions(file) {
-    let raw;
-    let parsed;
-    try {
-        raw = await readFile(file, "utf8");
-        parsed = JSON.parse(raw);
-    }
-    catch (err) {
-        throw new DecisionsParseError(err);
-    }
-    const result = PostdocDecisionsSchema.safeParse(parsed);
-    if (!result.success) {
-        throw new DecisionsParseError(result.error);
-    }
-    return result.data;
-}
-/**
- * Thin `@clack/prompts` adapter: walks `authoring`'s fill/select steps in
- * order and asks the human how to classify each one. ALL logic (variance
- * guards, secret-materialization checks, the actual step rewrite) lives in
- * `applyPostdoc`/`diffTakes` — this function only collects a
- * `PostdocDecision[]` to hand them.
- */
-async function promptForDecisions(authoring) {
-    clack.intro("recording postdoc — review captured fill/select steps");
-    const decisions = [];
-    const fillSteps = flattenBaseFillSteps(authoring.recording);
-    for (const { ref } of fillSteps) {
-        const classify = await clack.select({
-            message: `Step ${ref.page}:${ref.step} — how should this value be classified?`,
-            options: [
-                { value: "constant", label: "constant", hint: "fix this value in the artifact" },
-                { value: "variable", label: "variable", hint: "prompt for a value at replay time" },
-                { value: "handback", label: "handback", hint: "hand control to a human at replay time" },
-            ],
-        });
-        if (clack.isCancel(classify)) {
-            clack.cancel("postdoc review cancelled");
-            process.exit(1);
-        }
-        const label = await promptOptionalText("Label for this step? (blank to skip)");
-        const chunk = await promptOptionalText("Chunk name for this step? (blank to skip)");
-        let decision;
-        if (classify === "constant") {
-            const acknowledgeVaried = await clack.confirm({
-                message: "Acknowledge this value varied across takes anyway?",
-                initialValue: false,
-            });
-            if (clack.isCancel(acknowledgeVaried)) {
-                clack.cancel("postdoc review cancelled");
-                process.exit(1);
-            }
-            decision = { step: ref, classify: "constant", ...(acknowledgeVaried ? { acknowledgeVaried: true } : {}) };
-        }
-        else if (classify === "variable") {
-            const name = await clack.text({ message: "Variable name?" });
-            if (clack.isCancel(name)) {
-                clack.cancel("postdoc review cancelled");
-                process.exit(1);
-            }
-            decision = { step: ref, classify: "variable", name };
-        }
-        else {
-            const prompt = await clack.text({ message: "Handback prompt for the human operator?" });
-            if (clack.isCancel(prompt)) {
-                clack.cancel("postdoc review cancelled");
-                process.exit(1);
-            }
-            decision = { step: ref, classify: "handback", prompt };
-        }
-        if (label !== undefined)
-            decision = { ...decision, label };
-        if (chunk !== undefined)
-            decision = { ...decision, chunk };
-        decisions.push(decision);
-    }
-    clack.outro("review complete");
-    return decisions;
-}
-async function promptOptionalText(message) {
-    const value = await clack.text({ message, defaultValue: "" });
-    if (clack.isCancel(value)) {
-        clack.cancel("postdoc review cancelled");
-        process.exit(1);
-    }
-    return value === "" ? undefined : value;
+function usageParseErrorCode(cmd) {
+    const path = commandPath(cmd);
+    return `E_${path === "" ? "CLI" : path.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_ARGS`;
+}
+/** The command line as given (commander keeps it on the root; untyped). */
+function rawArgsOf(root) {
+    const raw = root.rawArgs;
+    return Array.isArray(raw) ? raw : [];
+}
+function rootOf(cmd) {
+    let c = cmd;
+    while (c.parent !== null)
+        c = c.parent;
+    return c;
 }
 //# sourceMappingURL=program.js.map