@jevitate/cli 0.1.0 → 0.2.0

package/dist/mission-cli.js

@@ -0,0 +1,247 @@
+import { MissingCredentialError } from "@jevitate/ai-core";
+import { ok, fail } from "./envelope.js";
+import { logsDirFor } from "./project-dir.js";
+import { addMissionTarget, listMissionTargets, promoteMissionTarget, missionTargetContext, missionTargetAuth, updateMissionTargetAuth, withMissionTargetAuthFlags, UnknownMissionTargetError, } from "./mission-api.js";
+import { FsMissionQueueStore } from "@jevitate/missions";
+import { drainMissionQueue, needsModel, realQueuedMissionExecutor } from "./mission-queue-runner.js";
+import { loadTargetsFile } from "./target-config.js";
+import { withEngine } from "./engine.js";
+import { EXIT_CODES } from "./exit-codes.js";
+import { positiveIntArg } from "./cli-args.js";
+import { resolveDataDir } from "./data-dir.js";
+import { registerMissionQueueCommands } from "./mission-queue-cli.js";
+import { resolveMissionTargetsDir, withBrowserLaunchFlags, browserLaunchFromFlags, emitJson, GatewaySelectionError, buildExploreGateways, } from "./cli-shared.js";
+/** Registers `jevitate mission`: `target add|update|list|promote`, `run` (drains the mission queue), `queue` and `result` (#254). */
+export function registerMissionCommands(program, deps) {
+    // 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").description("manage exploration mission targets and drain the mission queue");
+    const missionTarget = mission.command("target");
+    const missionTargetAdd = 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 target's app origin (a bare http(s) origin); --base-url must be on it")
+        .option("--api-origin <origin>", "a further origin the app talks to, e.g. its API on another origin (repeatable) — the queued-mission analogue of a second `explore --allow`", (v, prev) => [...prev, v], [])
+        .option("--base-url <url>", "the base URL a mission starts navigation from")
+        .option("--description <text>", "optional human-readable description");
+    withMissionTargetAuthFlags(missionTargetAdd)
+        .option("--dir <path>", "mission targets directory (default: ~/.jevitate/missions/targets)")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (id) {
+        const { name, authorizedOrigin, apiOrigin, baseUrl, description, dir, json, ...authFlags } = 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 auth = missionTargetAuth(authFlags);
+            const target = await addMissionTarget(ctx, {
+                id,
+                name,
+                authorizedOrigin,
+                apiOrigins: apiOrigin,
+                baseUrl,
+                ...(description === undefined ? {} : { description }),
+                ...(auth === undefined ? {} : { auth }),
+            });
+            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)));
+        }
+    });
+    withMissionTargetAuthFlags(missionTarget
+        .command("update <id>")
+        .description("set a registered target's operator-declared auth for queued missions (#175); keeps its promotion state")
+        .option("--clear-auth", "drop the target's storage state, save-back and secret fields first"))
+        .option("--dir <path>", "mission targets directory (default: ~/.jevitate/missions/targets)")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (id) {
+        const { dir, json, clearAuth, ...authFlags } = this.opts();
+        const auth = missionTargetAuth(authFlags);
+        if (auth === undefined && clearAuth !== true) {
+            emitJson(program, fail("E_MISSION_TARGET_ARGS", "nothing to update: pass --storage-state, --save-storage-state, --secret-field or --clear-auth"));
+            return;
+        }
+        try {
+            const ctx = missionTargetContext(resolveMissionTargetsDir(deps, dir));
+            const target = await updateMissionTargetAuth(ctx, id, { ...(auth ?? {}), ...(clearAuth === true ? { clear: true } : {}) });
+            if (json) {
+                emitJson(program, ok(target));
+            }
+            else {
+                program.configureOutput().writeOut?.(`updated mission target '${target.id}'\n`);
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            if (err instanceof UnknownMissionTargetError) {
+                emitJson(program, fail("E_UNKNOWN_MISSION_TARGET", err.message));
+                return;
+            }
+            emitJson(program, fail("E_MISSION_TARGET_UPDATE", 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) {
+                    const origins = [t.authorizedOrigin, ...(t.apiOrigins ?? [])].join(",");
+                    out?.(`${t.id}\t${t.name}\t${origins}${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)));
+            }
+        }
+    });
+    // `mission run` (#117) — drains the queue `queue_exploration` (MCP) fills: each queued mission runs
+    // through its strategy's CLI runner, its typed result lands in the recordings dir `jevitate mcp`
+    // reads, and its queue record moves queued → running → done (resultId) | failed, so
+    // `get_mission_result {id: missionId}` resolves it. `--once` (default) drains what is queued now
+    // and exits; `--watch` keeps polling.
+    withBrowserLaunchFlags(mission
+        .command("run")
+        .description("run queued missions (queue_exploration) through their strategy's runner; get_mission_result {id: missionId} then reads the result"))
+        .option("--once", "drain the missions queued now, then exit (default)")
+        .option("--watch", "keep draining: poll the queue every --interval ms until interrupted")
+        .option("--interval <ms>", "--watch poll interval in ms (default 5000)", positiveIntArg, 5000)
+        .option("--dir <path>", "mission queue directory (default: ~/.jevitate/missions/queue)")
+        .option("--targets-dir <path>", "mission targets directory (default: ~/.jevitate/missions/targets)")
+        .option("--out <dir>", "where results are written (default: .jevitate/logs/<date> in the project, else ~/.jevitate/logs/<date> — where `jevitate mcp` reads them)")
+        .option("--real", "use live Jev + OpenRouter gateways for model-driven missions (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.once && o.watch) {
+            emitJson(program, fail("E_MISSION_RUN_ARGS", "--once and --watch are mutually exclusive"));
+            return;
+        }
+        const intervalMs = Number(o.interval);
+        if (!Number.isInteger(intervalMs) || intervalMs <= 0) {
+            emitJson(program, fail("E_MISSION_RUN_ARGS", `--interval must be a positive integer (got ${JSON.stringify(o.interval)})`));
+            return;
+        }
+        // Model-driven missions need a gateway selection; without one they stay queued (reported as
+        // skipped), never run against a silently-substituted fake. Feature missions are model-free.
+        let gatewayRefusal;
+        try {
+            await buildExploreGateways(deps, { real: o.real ?? false, fakeAi: o.fakeAi ?? false });
+        }
+        catch (err) {
+            if (!(err instanceof MissingCredentialError || err instanceof GatewaySelectionError))
+                throw err;
+            gatewayRefusal = err.message;
+        }
+        const queue = new FsMissionQueueStore(o.dir ?? deps.missions?.queueDir ?? resolveDataDir(["missions", "queue"]));
+        const targets = missionTargetContext(resolveMissionTargetsDir(deps, o.targetsDir)).registry;
+        // #142 follow-up: ~/.jevitate/targets.json's per-origin logSources/logDefect/allowLogCmd — a
+        // queued mission never carries its own (never an MCP argument); this is the operator's only
+        // way to declare one for a mission drained here.
+        const targetConfigs = loadTargetsFile(deps.explore?.targetsConfigPath);
+        const execute = deps.missions?.execute ??
+            realQueuedMissionExecutor({
+                outDir: o.out ?? logsDirFor(),
+                gateways: () => buildExploreGateways(deps, { real: o.real ?? false, fakeAi: o.fakeAi ?? false }),
+                ...(deps.explore?.browserPortFactory === undefined ? {} : { browserPortFactory: deps.explore.browserPortFactory }),
+                ...(browserLaunchFromFlags(o) === undefined ? {} : { browser: browserLaunchFromFlags(o) }),
+                targets: targetConfigs,
+            });
+        const drainOnce = () => drainMissionQueue({
+            queue,
+            targets,
+            execute,
+            accepts: (m) => (gatewayRefusal !== undefined && needsModel(m) ? `needs a model gateway: ${gatewayRefusal}` : true),
+        });
+        const emit = (report) => {
+            const data = withEngine(report);
+            if (o.json) {
+                emitJson(program, ok(data));
+            }
+            else {
+                program.configureOutput().writeOut?.(`${JSON.stringify(data)}\n`);
+            }
+            // Every claimed mission ran (whatever its own outcome); 2 only when one could not run at all —
+            // it proves nothing, so never 1 (defects) — exit-codes.ts.
+            process.exitCode = report.ran.some((m) => m.status === "failed") ? EXIT_CODES.inconclusive : EXIT_CODES.ok;
+        };
+        try {
+            if (!o.watch) {
+                emit(await drainOnce());
+                return;
+            }
+            // --watch: one envelope per pass that ran something; interrupted by SIGINT/SIGTERM (the kill
+            // switch still writes a killed mission's partial result).
+            for (;;) {
+                const report = await drainOnce();
+                if (report.ran.length > 0)
+                    emit(report);
+                await new Promise((resolve) => setTimeout(resolve, intervalMs));
+            }
+        }
+        catch (err) {
+            emitJson(program, fail("E_MISSION_RUN", String(err instanceof Error ? err.message : err)));
+        }
+    });
+    // #254: `mission queue` / `mission result` — MCP queue_exploration / get_mission_result from the CLI.
+    registerMissionQueueCommands(program, mission, deps);
+}
+//# sourceMappingURL=mission-cli.js.map

package/dist/mission-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mission-cli.js","sourceRoot":"","sources":["../src/mission-cli.ts"],"names":[],"mappings":"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"}

package/dist/mission-exit.d.ts

@@ -0,0 +1,22 @@
+import { type MissionOutcome } from "@jevitate/domain";
+import type { GoalBasedOutcome } from "@jevitate/explore";
+/**
+ * Exit codes for mission runs (documented in the CLI README / `explore --help`):
+ *
+ *  - `0` clean (goal: succeeded)
+ *  - `1` defects found (goal: the success assertion did not hold — the existing convention)
+ *  - `2` inconclusive or crashed — the run itself broke, so it proves nothing
+ *  - `3` hang — the app under test hung and it reproduced on replay
+ *  - `4` intermittent — a hang that did not reproduce on every replay
+ *
+ * Codes 0 and 1 keep their pre-existing meaning; 2–4 are new and never overlap a finding with a
+ * broken run.
+ */
+export declare function missionExitCode(outcome: MissionOutcome): number;
+/**
+ * The goal mission's own outcome → exit code. The mapping itself lives in ONE place —
+ * `outcomeExitCode`/`GOAL_OUTCOME_FOLD` in `@jevitate/domain` (`mission-outcome.ts`) — so the CLI,
+ * MCP and the result schema can never disagree: `succeeded` 0 · `failed`/`exhausted`/`blocked`/
+ * `defects-found` 1 · `inconclusive`/`crashed` 2 · `hang` 3 · `intermittent` 4.
+ */
+export declare function goalExitCode(outcome: GoalBasedOutcome): number;

package/dist/mission-exit.js

@@ -0,0 +1,26 @@
+import { MISSION_EXIT_CODES, outcomeExitCode } from "@jevitate/domain";
+/**
+ * Exit codes for mission runs (documented in the CLI README / `explore --help`):
+ *
+ *  - `0` clean (goal: succeeded)
+ *  - `1` defects found (goal: the success assertion did not hold — the existing convention)
+ *  - `2` inconclusive or crashed — the run itself broke, so it proves nothing
+ *  - `3` hang — the app under test hung and it reproduced on replay
+ *  - `4` intermittent — a hang that did not reproduce on every replay
+ *
+ * Codes 0 and 1 keep their pre-existing meaning; 2–4 are new and never overlap a finding with a
+ * broken run.
+ */
+export function missionExitCode(outcome) {
+    return MISSION_EXIT_CODES[outcome];
+}
+/**
+ * The goal mission's own outcome → exit code. The mapping itself lives in ONE place —
+ * `outcomeExitCode`/`GOAL_OUTCOME_FOLD` in `@jevitate/domain` (`mission-outcome.ts`) — so the CLI,
+ * MCP and the result schema can never disagree: `succeeded` 0 · `failed`/`exhausted`/`blocked`/
+ * `defects-found` 1 · `inconclusive`/`crashed` 2 · `hang` 3 · `intermittent` 4.
+ */
+export function goalExitCode(outcome) {
+    return outcomeExitCode(outcome);
+}
+//# sourceMappingURL=mission-exit.js.map

package/dist/mission-exit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mission-exit.js","sourceRoot":"","sources":["../src/mission-exit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAuB,MAAM,kBAAkB,CAAC;AAG5F;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,OAAuB;IACrD,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAyB;IACpD,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC;AAClC,CAAC"}

package/dist/mission-fixtures.d.ts

@@ -0,0 +1,225 @@
+import { type AuthSources, type RequestAuth } from "./fixture-auth.js";
+/**
+ * Mission fixtures (#140 declarative app setup, #144 setup/restore around missions and replays) —
+ * ONE capability: put the app into a known state before a mission, bind what that setup created
+ * (an item id, an invite URL) into the run as `${setup.<name>}`, restore the state afterwards, and
+ * do the same around EVERY replay (hang reproduction, `verify-fix`, regression capture) so a replay
+ * starts from the state the finding was made in, not whatever earlier runs left behind.
+ *
+ * Two step kinds, both operator-declared:
+ *
+ *  - HTTP steps, from a fixtures JSON file (`--fixtures`, or `fixtures` in `~/.jevitate/targets.json`).
+ *    Only to an `--allow`-listed http(s) origin; authenticated like the page is (`fixture-auth.ts`:
+ *    a storageState localStorage bearer, its cookies, or a `--secret-field` binding). A file can
+ *    never declare a command. A step's json/body/headers may use `${secretField.<VAR>}` (#166) —
+ *    the run's `--secret-field` value bound to env `<VAR>`, so a login step can authenticate; it
+ *    is put on the wire only (never in a URL, the step log, the result or the Recording).
+ *  - Shell hooks, from the operator's own CLI flags only (`--before <cmd>` / `--after <cmd>`, and
+ *    only with `--allow-shell-hooks`). Never model-chosen, never read from a file a run wrote. Exit
+ *    codes are recorded; stdout is never persisted (it may carry `{vars, secret}`), stderr only
+ *    redacted and clipped.
+ *
+ * Fail closed: a setup that fails, times out, or leaves a `${setup.x}` reference unresolved ends
+ * the run `inconclusive` (`fixture setup failed: …`, a configuration error) — a mission never runs
+ * on unknown state. Secret outputs join the run's redaction set and may only be used inside the
+ * fixture's own requests, never in text a model sees.
+ */
+export declare const SETUP_REF: RegExp;
+/**
+ * `${secretField.<VAR>}` (#166): a run's `--secret-field` value (bound to env `<VAR>`), allowed only
+ * in a step's `json`/`body`/`headers` — so a login step can authenticate. Substituted into the
+ * outgoing request only: never into a URL, the step log, the result or the Recording.
+ */
+export declare const SECRET_FIELD_REF: RegExp;
+export interface FixtureHttpStep {
+    readonly name?: string;
+    readonly method: string;
+    /** Absolute, or relative to the mission's start URL. May reference `${setup.<name>}` (not in its origin). */
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly json?: unknown;
+    readonly body?: string;
+    readonly auth?: RequestAuth;
+    /** Accepted statuses. Default: any 2xx. */
+    readonly expectStatus?: readonly number[];
+    /** Output name → `$.json.path` (JSONPath-lite) or `header:<name>`. */
+    readonly outputs?: Readonly<Record<string, string>>;
+    /** Output names that are credentials: redacted everywhere, never substituted into model-visible text. */
+    readonly secretOutputs?: readonly string[];
+    readonly timeoutMs?: number;
+}
+export interface FixtureSpec {
+    readonly name?: string;
+    readonly setup: readonly FixtureHttpStep[];
+    readonly restore: readonly FixtureHttpStep[];
+}
+/** The operator's own shell hooks (CLI flags; never from a file or a model). */
+export interface ShellHooks {
+    readonly before?: string;
+    readonly after?: string;
+    readonly timeoutMs?: number;
+}
+export declare class FixtureSpecError extends Error {
+    readonly code: "E_FIXTURE_SPEC";
+    constructor(message: string);
+}
+/** Setup failed: the run must end `inconclusive` (a configuration error) without touching the app. */
+export declare class FixtureSetupError extends Error {
+    readonly code: "E_FIXTURE_SETUP";
+    constructor(detail: string);
+}
+export interface FixtureBounds {
+    readonly allowlist: readonly string[];
+    /** What a relative step URL resolves against (the mission's start URL). */
+    readonly baseUrl: string;
+}
+/** Every `${setup.x}` name referenced in `text`. */
+export declare function referencedNames(text: string): string[];
+/**
+ * Every `--secret-field` env variable a spec needs (#166): the `auth: {from: "secretField"}` names
+ * and every `${secretField.<VAR>}` in a step's json/body/headers.
+ */
+export declare function secretFieldNames(spec: FixtureSpec | undefined): string[];
+/**
+ * Validates a fixtures spec (fail closed, before any browser or request). `openRefs` allows
+ * references a `--before` hook may bind at run time (unknown statically; still checked when used).
+ */
+export declare function parseFixtureSpec(raw: unknown, bounds: FixtureBounds, opts?: {
+    openRefs?: boolean;
+}): FixtureSpec;
+/** Reads and validates a fixtures JSON file. */
+export declare function loadFixtureFile(path: string, bounds: FixtureBounds, opts?: {
+    openRefs?: boolean;
+}): FixtureSpec;
+/** `$`, `.key`, `[0]`, `["key"]` — the JSONPath-lite output selectors. */
+type PathSeg = string | number;
+export declare function parseJsonPath(path: string, where?: string): PathSeg[];
+/** The scalar at `path` in `doc`, as a string; `undefined` when absent or not a scalar. */
+export declare function selectJsonPath(doc: unknown, path: string): string | undefined;
+/** A setup's bound outputs: values, and which of them are secrets. */
+export interface FixtureBindings {
+    readonly values: Readonly<Record<string, string>>;
+    readonly secretNames: ReadonlySet<string>;
+}
+export declare class UnboundSetupRefError extends Error {
+    readonly code: "E_FIXTURE_REF";
+    constructor(message: string);
+}
+/**
+ * Substitutes every `${setup.x}` in `text`. An unknown name throws (never a hollow run); a SECRET
+ * output throws unless `allowSecret` — goal/URL/success text is model- or artifact-visible.
+ */
+export declare function substituteSetupRefs(text: string, b: FixtureBindings, opts?: {
+    allowSecret?: boolean;
+    where?: string;
+}): string;
+/** One step of setup/restore, as recorded in the result (redacted; never headers or bodies). */
+export interface FixtureStepLog {
+    readonly phase: "setup" | "restore";
+    readonly kind: "http" | "shell";
+    readonly name: string;
+    readonly ok: boolean;
+    readonly durationMs: number;
+    readonly method?: string;
+    readonly url?: string;
+    readonly status?: number;
+    readonly exitCode?: number | null;
+    readonly detail?: string;
+    /** A shell hook's stderr, redacted and clipped (stdout is never persisted). */
+    readonly stderr?: string;
+}
+/** What the result/Recording carries: identity + non-secret outputs; secrets by NAME only. */
+export interface FixtureRecord {
+    /** Hash of the spec (+ hook commands) and the bound outputs (secret outputs by name only). */
+    readonly identity: string;
+    /** Hash of the spec (+ hook commands) alone: equal across runs of the same fixture. */
+    readonly specHash: string;
+    readonly outputs: Readonly<Record<string, string>>;
+    readonly secretOutputs: readonly string[];
+    /** Setup/restore cycles run (1 for the mission + one per replay). */
+    readonly cycles: number;
+    readonly log: readonly FixtureStepLog[];
+}
+/** What a mission result persists so `verify-fix`/regression capture restore the SAME state. */
+export interface PersistedFixtures {
+    readonly identity: string;
+    readonly specHash: string;
+    readonly spec?: FixtureSpec;
+    /** sha256 of each operator hook command — the commands themselves are re-supplied, never replayed from a file. */
+    readonly hooks?: {
+        readonly before?: string;
+        readonly after?: string;
+    };
+    readonly outputs: Readonly<Record<string, string>>;
+    readonly secretOutputs: readonly string[];
+}
+export declare function hookHash(cmd: string): string;
+export interface FixtureRunOptions extends FixtureBounds {
+    readonly spec?: FixtureSpec;
+    readonly hooks?: ShellHooks;
+    /** Required to run `hooks` at all (CLI `--allow-shell-hooks`). */
+    readonly allowShellHooks?: boolean;
+    readonly auth: AuthSources;
+    /** The run's own secrets: redacted from everything a fixture logs. */
+    readonly secrets?: readonly string[];
+    /** Testing seam. */
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * One mission's fixture lifecycle. `setup()` before the mission, `restore()` after it (every exit
+ * path), and `reset()` (restore the active state, then set up again) before each replay.
+ */
+export declare class MissionFixtures {
+    #private;
+    constructor(opts: FixtureRunOptions);
+    hookHashes(): PersistedFixtures["hooks"] | undefined;
+    get specHash(): string;
+    /** The output names the spec declares; `null` when a `--before` hook may bind more at run time. */
+    declaredOutputs(): Set<string> | null;
+    /** The output names the spec declares secret. */
+    declaredSecretOutputs(): Set<string>;
+    bindings(): FixtureBindings;
+    /** Non-secret outputs (what a replay's recorded values are rebound to). */
+    publicOutputs(): Record<string, string>;
+    /** Secret output values: the caller adds them to the run's redaction set. */
+    secrets(): string[];
+    identity(): string;
+    record(): FixtureRecord;
+    persisted(): PersistedFixtures;
+    /** Sets up the fixture. Throws `FixtureSetupError`; the caller still calls `restore()`. */
+    setup(): Promise<void>;
+    /** Restores the state the last `setup()` created. Never throws: every step is logged. */
+    restore(): Promise<void>;
+    /** Before a replay: restore whatever is active, then set up afresh. Throws `FixtureSetupError`. */
+    reset(): Promise<void>;
+}
+/**
+ * A replay session re-uses the Recording of the ORIGINAL run, whose navigations carry the values
+ * that run's setup bound (e.g. `/items/<old id>`). After a fresh setup, the same navigation must go
+ * to the NEW value: this rewrites each recorded value to its current one in every `page.goto` of the
+ * replay's own page (non-secret outputs of 4+ characters only — shorter ones are too ambiguous to
+ * rewrite blindly).
+ */
+export declare function rebindReplayNavigation(page: {
+    goto: (url: string, ...rest: never[]) => Promise<unknown>;
+}, recorded: Readonly<Record<string, string>>, current: Readonly<Record<string, string>>): void;
+/** The fixture identity carried on a Recording (non-secret outputs only). */
+export declare function recordingFixture(r: FixtureRecord): {
+    identity: string;
+    specHash: string;
+    outputs: Record<string, string>;
+};
+/** What a mission result carries: the record (log, identity, outputs) plus what a replay needs to restore the same state. */
+export type MissionFixtureResult = FixtureRecord & Pick<PersistedFixtures, "spec" | "hooks">;
+/**
+ * Wraps a replay-session opener (hang reproduction, `verify-fix`, regression capture) so EVERY
+ * replay starts from the fixture's state: restore whatever is active, set up afresh (a failure
+ * throws, so the replay is "could not open a session" — inconclusive, never evidence), then rebind
+ * the Recording's values (`recorded`, from the run the Recording came from) to the new outputs.
+ */
+export declare function fixtureReplayOpener<S extends {
+    readonly page: {
+        goto: (url: string, ...rest: never[]) => Promise<unknown>;
+    };
+}>(open: () => Promise<S>, fx: MissionFixtures, recorded: Readonly<Record<string, string>>): () => Promise<S>;
+export {};