@jevitate/cli 0.1.0 → 0.3.0

package/dist/explore-feature.d.ts

@@ -0,0 +1,125 @@
+import type { UsageCounts } from "@jevitate/ai-core";
+import { type BrowserPort, type EmulationSpec } from "@jevitate/playwright";
+import { type BrowserRunOptions } from "./browser-run-options.js";
+import { type ScreenshotsSpec } from "./run-screenshots.js";
+import { type InvariantSpec } from "@jevitate/recording";
+import type { HostHealthSampler, InvariantDefect, SafetyConfig } from "@jevitate/explore";
+import type { EnvironmentDegraded, HostHealthSummary } from "@jevitate/domain";
+import { type Bounds, type FeatureRunResult, type MissionRouteScope, type Http5xxDefect } from "@jevitate/explore";
+import { type MissionOutcome } from "@jevitate/domain";
+import { type EngineInfo } from "./engine.js";
+import { MISSION_RESULT_SCHEMA_VERSION } from "./result-schema.js";
+import { type ServerLogDefect, type ServerLogsSummary } from "./log-correlation.js";
+import { type ServerLogOptions, type MissionTarget } from "./explore-shared.js";
+/**
+ * The programmatic surface behind `jevitate explore --feature <name>` — the
+ * capability-scoped feature-testing mission (ticket #2, paired site ticket
+ * #11). Model-free by design, so unlike `runExploration` it needs no gateways.
+ *
+ * The authorized-target guard runs FIRST (fail-closed), BEFORE any browser is
+ * opened — an unauthorized origin never launches Chromium.
+ */
+export interface RunFeatureCliMissionOptions {
+    /** Test seam (#203): the run's host-health sampler (a deterministic fake host). Default: this host's. */
+    readonly hostHealth?: HostHealthSampler;
+    readonly seedUrl: string;
+    readonly allowlist: readonly string[];
+    readonly capability: string;
+    /**
+     * The `--route` globs, used exactly as given. Empty/absent (#224): the start URL's route and
+     * everything under it — the default every strategy shares (`resolveRouteScope`), stated in the
+     * result's `scope`. A start URL no default can be derived from is refused up front
+     * (`ScopeUnderivableError`, a usage error) before any browser opens.
+     */
+    readonly routeGlobs?: readonly string[];
+    /** No-progress watchdog (CLI `--stall-timeout`, #114): ends the run `stalled` (inconclusive). Default 120s. */
+    readonly stallTimeoutMs?: number;
+    /** Step/action budget (CLI `--max-actions` / `--max-decisions`). */
+    readonly bounds?: Partial<Bounds>;
+    /** Testing seam — defaults to a real `PlaywrightBrowserPort`. */
+    readonly browserPortFactory?: () => BrowserPort;
+    /** How Chromium is launched (executable/channel/extra args) and shown (#245 demo mode). Default: pinned Chromium, headless. */
+    readonly browser?: BrowserRunOptions;
+    /** #251 `--screenshots`: masked screenshots (one per distinct screen, or per step) + `index.md`. */
+    readonly screenshots?: ScreenshotsSpec;
+    /**
+     * #250 `--evidence-video`: after the result is written, each defect's minimal repro is replayed
+     * with captions (the failing step marked) into a masked clip + before/at screenshots, attached as
+     * `defects[].evidence` (and to its issue draft).
+     */
+    readonly evidenceVideo?: boolean;
+    /**
+     * Playwright storageState JSON to seed the session from (CLI `--storage-state`) —
+     * the deterministic authenticated pre-step. Contains live session cookies: it is
+     * handed only to the browser, never to a model or a Recording.
+     */
+    readonly storageState?: string;
+    /** Where the recordings, transcript and typed result are written. Default `.jevitate/logs/<date>` (project, else `~/.jevitate`). */
+    readonly outDir?: string;
+    /** ISO clock for output filenames. Default `Date.now()`. */
+    readonly nowIso?: () => string;
+    /**
+     * Writes the browser context's storageState (cookies + origin storage) here when the run ends
+     * (CLI `--save-storage-state`) — so a rotating refresh token stays usable across runs instead of
+     * invalidating `--storage-state`'s file on first use. The file holds live session credentials:
+     * written with mode 0600, and its contents are never logged. See
+     * `RunExplorationOptions.saveStorageState`'s own doc for the full behaviour (#159: written on
+     * every exit path including a crash/kill signal, never over a lost/logged-out session).
+     */
+    readonly saveStorageState?: string;
+    /** App-declared invariants (`--invariants`, #86), already validated against the allowlist. */
+    readonly invariants?: InvariantSpec;
+    /** Backend log sources (`--log-source`/`--log-defect`, #142), already validated. */
+    readonly serverLog?: ServerLogOptions;
+    /** Resolved `authFrom.secret` refs (#135) a declared probe may use: `env:VAR` → its value. */
+    readonly invariantAuthTokens?: ReadonlyMap<string, string>;
+    /** The shared safety policy (#116: `--deny`, `--allow-destructive`, `--read-rpc`). */
+    readonly safety?: SafetyConfig;
+    /** Per-mission viewport/device emulation (#149); see `RunExplorationOptions.emulation`. */
+    readonly emulation?: EmulationSpec;
+}
+/** The feature mission's result plus its typed verdict, exit code, and where its artifacts landed. */
+export type FeatureCliMissionResult = Omit<FeatureRunResult, "outcome"> & {
+    /** The frontier's ending — `insufficient-coverage` (#209) when it emptied having proved nothing about the feature. */
+    readonly outcome: FeatureRunResult["outcome"] | "insufficient-coverage";
+    /** The result schema's version (#195): the common fields are filled the same way by every strategy. */
+    readonly schemaVersion: typeof MISSION_RESULT_SCHEMA_VERSION;
+    readonly strategy: "feature";
+    /** The route scope the run used (#224): the `--route` globs, or the one derived from the start URL. */
+    readonly scope: MissionRouteScope;
+    /**
+     * `clean` only when the run actually exercised an in-scope, non-chrome
+     * control of the named capability (`coverage.inScopeActionsExercised > 0`).
+     * A run that touched nothing but global chrome and/or left `--route` scope
+     * on every attempt is `inconclusive` — never a fabricated `clean` (ticket
+     * #78's guardrail: a run that proved nothing is never `clean`).
+     */
+    readonly missionOutcome: MissionOutcome;
+    readonly exitCode: number;
+    /** Which build produced this result (issue #83): `{version, commit, builtAt}`. */
+    readonly engine: EngineInfo;
+    /** One Recording per distinct discovered path (`feature-<stamp>-path-<n>.json`). */
+    readonly recordingPaths: string[];
+    /** #245: `--record-video` files, finalized before this result was written (absent when not recording). */
+    readonly videoPaths?: string[];
+    /** The shared decision transcript (`feature-<stamp>.transcript.json`). */
+    readonly transcriptPath: string;
+    /** The persisted typed result (`feature-<stamp>.result.json`), readable via MCP `get_mission_result`. */
+    readonly resultPath: string;
+    /** Where the run happened — what `verify-fix` needs to replay a declared-invariant defect. */
+    readonly target: MissionTarget;
+    /** EVERY defect the run found (#195): declared-invariant defects (#86, each with its own path Recording) and `server-log` defects (#142). */
+    readonly defects: Array<InvariantDefect | Http5xxDefect | ServerLogDefect>;
+    readonly invariantSpec?: InvariantSpec;
+    /** Backend log correlation summary (#142) — present only when `--log-source` was given. */
+    readonly serverLogs?: ServerLogsSummary;
+    /** Always zero (#188): a feature mission makes no model call — stated, never absent ("not tracked"). */
+    readonly usage: UsageCounts;
+    /** The host's health over the run (#203): peaks, the slowest render, starved steps. */
+    readonly hostHealth: HostHealthSummary;
+    /** Findings met while the host was starved (#203) — advisory, never a defect/hang, never failing the run. */
+    readonly environmentDegraded: EnvironmentDegraded[];
+};
+/** A model-free mission's usage (#188): nothing called, nothing to price — a known $0. */
+export declare const NO_MODEL_USAGE: UsageCounts;
+export declare function runFeatureCliMission(opts: RunFeatureCliMissionOptions): Promise<FeatureCliMissionResult>;

package/dist/explore-feature.js

@@ -0,0 +1,218 @@
+/** The feature strategy runner behind `jevitate explore --strategy feature`. */
+import { writeFile } from "node:fs/promises";
+import { logsDirFor } from "./project-dir.js";
+import { join, resolve as resolvePath } from "node:path";
+import { PlaywrightBrowserPort, resolveEmulation } from "@jevitate/playwright";
+import { closeOnce, demoOverlayOf, finalizeVideos, runVideoDir, sessionLaunchOptions } from "./browser-run-options.js";
+import { runCaptureFor } from "./run-screenshots.js";
+import { evidenceOf, withRunEvidence } from "./defect-evidence.js";
+import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
+import { runFeatureMission, assertAuthorizedExploreTarget, resolveRouteScope, refusalNote, safetyRefusalsFromTranscript, Http5xxOracle, hangOutcome, } from "@jevitate/explore";
+import { combineOutcomes, clock } from "@jevitate/domain";
+import { currentEngineInfo } from "./engine.js";
+import { MissionJournal, artifactStamp, closeQuietly, resultPathFor, writeMissionResult } from "./mission-journal.js";
+import { MISSION_RESULT_SCHEMA_VERSION, unifiedDefects } from "./result-schema.js";
+import { missionExitCode } from "./mission-exit.js";
+import { launchArmed } from "./launch-armed.js";
+import { finishHostHealth } from "./host-health-run.js";
+import { applyServerLogOutcome, openServerLogRuntime, } from "./log-correlation.js";
+import { serverLogResult, freshSessionOpener, currentUrlSafe, assertSaveStorageStateOutsideProject, persistStorageState, declaredResult, serverLogRuntimeOptions, } from "./explore-shared.js";
+/** A model-free mission's usage (#188): nothing called, nothing to price — a known $0. */
+export const NO_MODEL_USAGE = {
+    judgments: 0,
+    generations: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    totalUsd: 0,
+    priced: "full",
+    priceSource: ["no model call"],
+};
+export async function runFeatureCliMission(opts) {
+    // Guardrail #1 — authorize BEFORE opening a browser. Throws on refusal.
+    const origin = assertAuthorizedExploreTarget(opts.seedUrl, opts.allowlist);
+    assertSaveStorageStateOutsideProject(opts.saveStorageState);
+    // #224: no --route → the start URL's route (the shared default); refused up front when underivable.
+    const routeScope = resolveRouteScope(opts.seedUrl, opts.routeGlobs);
+    const scope = { name: opts.capability, originAllowlist: opts.allowlist, routeGlobs: routeScope.routeGlobs };
+    // #149: refused BEFORE any browser opens.
+    resolveEmulation(opts.emulation);
+    // #250/#251: a recorded or screenshotted run's sessions carry the live pixel mask from their first
+    // paint; `--screenshots` captures after each step (the Recording path names their folder).
+    const capture = runCaptureFor({
+        recordsVideo: opts.browser?.recordVideo !== undefined,
+        screenshots: opts.screenshots,
+        secrets: [],
+        artifactPath: () => journal.recordingPath,
+        title: `feature: ${opts.capability}`,
+    });
+    const portFactory = capture.wrap(opts.browserPortFactory ?? (() => new PlaywrightBrowserPort()));
+    // Persist recordings + transcript + a typed result, like the goal and
+    // coverage missions do (ticket #78 — previously nothing was written).
+    const outDir = opts.outDir ?? logsDirFor();
+    const iso = (opts.nowIso ?? (() => clock.nowIso()))();
+    const stamp = artifactStamp(iso);
+    const journal = new MissionJournal(join(outDir, `feature-${stamp}.json`));
+    // #245: the mission session and every hang-replay session are shown/recorded alike.
+    const videoDir = runVideoDir(opts.browser, journal.recordingPath);
+    const launch = {
+        ...sessionLaunchOptions(opts.browser, videoDir),
+        allowedOrigins: [...opts.allowlist],
+        baseUrl: origin,
+        ...opts.emulation,
+        ...(opts.storageState !== undefined ? { storageState: opts.storageState } : {}),
+    };
+    // #226: the kill switch is armed BEFORE the host sampler and the browser launch (see launch-armed.ts).
+    const { disarmKillSwitch, health, session, snapshotter } = await launchArmed({
+        hostHealth: opts.hostHealth,
+        saveStorageState: opts.saveStorageState !== undefined,
+        open: () => portFactory().open(launch),
+        mission: (hooks) => ({
+            // #220: the killed run's partial result carries the unified schema's common fields too.
+            strategy: "feature",
+            target: { seedUrl: opts.seedUrl, allowlist: [...opts.allowlist], ...(opts.storageState !== undefined ? { storageStatePath: resolvePath(opts.storageState) } : {}) },
+            recordingPath: journal.recordingPath,
+            hostHealth: hooks.hostHealth,
+            ...(videoDir === undefined ? {} : { videoDir }),
+            transcriptPath: journal.transcriptPath,
+            transcript: () => journal.transcript,
+            ...(opts.saveStorageState === undefined ? {} : { storageState: { path: opts.saveStorageState, snapshot: hooks.snapshot } }),
+        }),
+    });
+    // #208: the shared HTTP 5xx hard signal, listening from before the first navigation.
+    const http5xx = new Http5xxOracle(session.page, { allowlist: opts.allowlist });
+    const serverLog = openServerLogRuntime({
+        ...serverLogRuntimeOptions(opts.serverLog),
+        secrets: [],
+        onTranscriptEntry: journal.onTranscriptEntry,
+    });
+    // #204: every request's correlation ids, from before the first navigation.
+    serverLog?.observe(session.page);
+    const onTranscriptEntry = (entry, all) => {
+        capture.noteEntry(session.page, entry);
+        health.noteStep(entry);
+        http5xx.noteStep(entry);
+        (serverLog?.onTranscriptEntry ?? journal.onTranscriptEntry)(entry, all);
+        snapshotter.noteSettledStep(currentUrlSafe(session));
+    };
+    // #159/#245: persisted and closed once — early (before the result is written) when recording video.
+    const closeSession = closeOnce(async () => {
+        await persistStorageState(session, opts.saveStorageState, snapshotter);
+        await closeQuietly(session);
+    });
+    try {
+        const actor = CastActor.named("feature-mission").whoCan(new BrowseTheWeb(session, [...opts.allowlist]));
+        const result = await runFeatureMission({
+            openFreshSession: freshSessionOpener(portFactory, launch, opts.allowlist),
+            page: session.page,
+            actor,
+            seedUrl: opts.seedUrl,
+            allowlist: opts.allowlist,
+            scope,
+            bounds: opts.bounds,
+            onTranscriptEntry,
+            ...(opts.invariants === undefined ? {} : { invariants: opts.invariants }),
+            ...(opts.invariantAuthTokens === undefined ? {} : { invariantAuthTokens: opts.invariantAuthTokens }),
+            ...(opts.stallTimeoutMs === undefined ? {} : { stallTimeoutMs: opts.stallTimeoutMs }),
+            ...(opts.safety === undefined ? {} : { safety: opts.safety }),
+            hostHealth: health,
+            demoOverlay: demoOverlayOf(opts.browser),
+        });
+        const serverLogRun = serverLog === undefined ? undefined : await serverLog.finish(result.transcript);
+        const recordingPaths = [];
+        for (let i = 0; i < result.recordings.length; i++) {
+            const p = join(outDir, `feature-${stamp}-path-${i}.json`);
+            await writeFile(p, `${JSON.stringify(result.recordings[i], null, 2)}\n`, "utf8");
+            recordingPaths.push(p);
+        }
+        journal.writeTranscript(serverLogRun?.transcript ?? result.transcript);
+        // Honest outcome (ticket #78): a run that exercised nothing in-scope and
+        // non-chrome proved nothing about the named capability — `inconclusive`,
+        // never `clean`, whatever the loop's own stop reason was. Mirrors the
+        // adversarial mission's `insufficient-coverage` idiom.
+        const chromeOnly = result.outcome !== "crashed" && result.coverage.inScopeActionsExercised === 0;
+        // #209: in-scope, non-chrome controls were exercised — but none of them had anything to do with
+        // the named capability (every one at relevance=0 against its words). That proves no more about
+        // it than the chrome-only case: `inconclusive`, never `clean`.
+        const words = result.coverage.featureWords;
+        const irrelevant = !chromeOnly && result.outcome !== "crashed" && words.length > 0 && result.coverage.relevantActionsExercised === 0;
+        const thin = chromeOnly || irrelevant;
+        const coverageFailure = chromeOnly
+            ? {
+                kind: "insufficient-coverage",
+                message: `no in-scope, non-chrome control of "${opts.capability}" was exercised within route(s) [${routeScope.routeGlobs.join(", ")}]${routeScope.source === "start-url" ? " (derived from the start URL)" : ""} — ${result.coverage.boundaryEdges.length} boundary edge(s) hit instead${refusalNote(safetyRefusalsFromTranscript(result.transcript))}`,
+            }
+            : irrelevant
+                ? {
+                    kind: "insufficient-coverage",
+                    message: `no control relevant to "${opts.capability}" was exercised: all ${result.coverage.inScopeActionsExercised} in-scope action(s) were on controls at relevance=0 (none named with ${words.map((w) => `"${w}"`).join(", ")}) — name the feature with the words its controls use, or point --url/--route at the page that has them`,
+                }
+                : undefined;
+        // A declared-invariant violation (#86) is a hard defect even on a thin run: it was observed.
+        // #208: the shared HTTP 5xx hard signal's defects count like declared-invariant ones.
+        const httpDefects = http5xx.defects(result.transcript);
+        const hardDefects = (result.invariantDefects?.length ?? 0) + httpDefects.length;
+        // #150 — a crossed mission spend budget is a deliberate, clean stop (not the run breaking): it
+        // maps to `inconclusive`, but a defect found before it still wins, reported with `stop: "budget"`.
+        const preLogOutcome = combineOutcomes([
+            result.outcome === "crashed"
+                ? "crashed"
+                : result.outcome === "scope-unreachable" || result.outcome === "stalled"
+                    ? "inconclusive"
+                    : result.outcome === "budget"
+                        ? hardDefects > 0
+                            ? "defects-found"
+                            : "inconclusive"
+                        : hardDefects > 0
+                            ? "defects-found"
+                            : thin
+                                ? "inconclusive"
+                                : "clean",
+            ...result.hangs.map((h) => hangOutcome(h.reproduction.status)),
+        ]);
+        // #142 follow-up: a server-log defect counts as `defects-found`; an unreadable `--log-defect`
+        // oracle turns an otherwise-`clean` run `inconclusive` — never a false clean.
+        const host = await finishHostHealth(health, applyServerLogOutcome(preLogOutcome, serverLogRun));
+        const missionOutcome = host.outcome;
+        const exitCode = missionExitCode(missionOutcome);
+        // #245: every context closed (videos finalized) before the result naming them is written.
+        const shotFields = await capture.finish();
+        const videos = await finalizeVideos(videoDir, closeSession);
+        const typed = {
+            ...result,
+            // #209: one name — a frontier that emptied having proved nothing about the feature is not
+            // `exhausted` ("fully covered"): it is `insufficient-coverage`, the same word as its failure.kind.
+            outcome: thin && result.outcome === "exhausted" ? "insufficient-coverage" : result.outcome,
+            schemaVersion: MISSION_RESULT_SCHEMA_VERSION,
+            strategy: "feature",
+            scope: routeScope,
+            transcript: (serverLogRun?.transcript ?? result.transcript),
+            failure: result.failure ?? host.failure ?? coverageFailure,
+            missionOutcome,
+            exitCode,
+            recordingPaths,
+            ...videos,
+            ...shotFields,
+            transcriptPath: journal.transcriptPath,
+            engine: currentEngineInfo(),
+            target: {
+                seedUrl: opts.seedUrl,
+                allowlist: [...opts.allowlist],
+                ...(opts.storageState !== undefined ? { storageStatePath: resolvePath(opts.storageState) } : {}),
+            },
+            ...declaredResult(opts.invariants, result.invariantDefects, result.invariants),
+            ...serverLogResult(serverLogRun),
+            defects: unifiedDefects([...(opts.invariants === undefined ? [] : (result.invariantDefects ?? [])), ...httpDefects], serverLogRun?.defects),
+            resultPath: resultPathFor(journal.recordingPath),
+            usage: NO_MODEL_USAGE,
+            ...host.fields,
+        };
+        return await withRunEvidence({ ...typed, resultPath: writeMissionResult(journal.recordingPath, missionOutcome, exitCode, typed) }, evidenceOf(opts, []));
+    }
+    finally {
+        disarmKillSwitch();
+        health.stop();
+        await serverLog?.abort();
+        await closeSession();
+    }
+}
+//# sourceMappingURL=explore-feature.js.map

package/dist/explore-feature.js.map

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

package/dist/explore-goal.d.ts

@@ -0,0 +1,271 @@
+import type { JudgmentPort, GenerationPort, UsageTracker, UsageCounts } from "@jevitate/ai-core";
+import { type BrowserPort, type EmulationSpec } from "@jevitate/playwright";
+import { type BrowserRunOptions } from "./browser-run-options.js";
+import { type ScreenshotsSpec } from "./run-screenshots.js";
+import { type Assertion, type InvariantSpec, type Recording } from "@jevitate/recording";
+import type { ActionDeltaStats, HostHealthSampler, InvariantDefect, InvariantReport, SideEffect } from "@jevitate/explore";
+import type { EnvironmentDegraded, HostHealthSummary } from "@jevitate/domain";
+import { type Bounds, type GoalBasedOutcome, type StopReason, type TranscriptEntry, type RunAnswer, type RunOutcome, type SuccessCheck, type SuccessCheckResult, type SuccessWhen, type SecretField, type TypeFixture, type BudgetTrajectory, type CrashReport, type Http5xxDefect } from "@jevitate/explore";
+import { type ConversationOptions } from "./conversation-options.js";
+import { type FilingConfig, type IssueFilerPort, type MissionFailure, type MissionOutcome } from "@jevitate/domain";
+import { type HangFinding, type TimingSummary } from "@jevitate/explore";
+import { type FindingsIssues } from "./findings-filing.js";
+import { type EngineInfo } from "./engine.js";
+import type { TargetConfig } from "./target-config.js";
+import { MISSION_RESULT_SCHEMA_VERSION } from "./result-schema.js";
+import { type JourneyPrefix } from "./journey-prefix.js";
+import type { JourneyBranchPoint } from "@jevitate/journey";
+import { type ServerLogDefect, type ServerLogsSummary, type TranscriptEntryWithLogs } from "./log-correlation.js";
+import { type MissionFixtureResult, type MissionFixtures } from "./mission-fixtures.js";
+import { type MissionActors } from "./mission-actors.js";
+import { type ServerLogOptions, type MissionTarget } from "./explore-shared.js";
+/**
+ * The programmatic surface behind `jevitate explore` — wires a real Playwright
+ * `Page` + gateways to `@jevitate/explore`'s goal-based mission, then persists
+ * the emitted `Recording` under `.jevitate/logs/<date>`.
+ *
+ * The authorized-target guard runs FIRST (fail-closed), BEFORE any browser is
+ * opened — an unauthorized origin never launches Chromium. Gateways are
+ * injected (fakes in tests / live wiring in `program.ts`), so this file needs
+ * no keys or network to be unit-tested.
+ */
+export interface RunExplorationOptions {
+    /** Test seam (#203): the run's host-health sampler (a deterministic fake host). Default: this host's. */
+    readonly hostHealth?: HostHealthSampler;
+    readonly url: string;
+    readonly goal: string;
+    /** A success assertion on the final page. With `successChecks`, every one must hold. */
+    readonly successAssertion?: Assertion;
+    /** More independent checks (`--success`, repeatable): page, reloadThen, requestMade, responseStatus. */
+    readonly successChecks?: readonly SuccessCheck[];
+    /**
+     * When the page checks must hold (`--success-when`, #80): `final` (default) — on the final page;
+     * `held` — on the final page or together at any settled step. `reloadThen` is final-only.
+     */
+    readonly successWhen?: SuccessWhen;
+    /**
+     * #202 (`--allow-vacuous-checks`): a check satisfied before the run's first action (held on the
+     * seed page and never changed; a request matched only by page load/polling) is a warning instead
+     * of a failure. Default: it fails — a run that proved nothing is never clean.
+     */
+    readonly allowVacuousChecks?: boolean;
+    /**
+     * #303 `--action-deltas` (opt-in, off by default): record what each action changed on the page
+     * (code's verdict per action) — attached to every transcript and Recording step, summarised in the
+     * result (`actionDeltas`), told to the model and used by the no-progress check. Off: no capture.
+     */
+    readonly actionDeltas?: boolean;
+    readonly allowlist: readonly string[];
+    readonly judge: JudgmentPort;
+    readonly gen: GenerationPort;
+    /**
+     * Usage accounting (#100): when supplied, its snapshot (judgments/generations/tokens/`usd`) lands
+     * in the result as `usage`. The CLI builds one per invocation and hands it to the gateways
+     * `judge`/`gen` were constructed with, so the counts here are exactly what this run made.
+     */
+    readonly usage?: UsageTracker;
+    readonly bounds?: Partial<Bounds>;
+    readonly secrets?: readonly string[];
+    /**
+     * Secret field bindings (CLI `--secret-field` / `--totp`, resolved from the environment): typed
+     * by code, never by the model; each value/seed is also a run secret (redacted everywhere).
+     */
+    readonly secretFields?: readonly SecretField[];
+    /** #281: fields typed with a file's exact text (CLI `--type-fixture`, read by the CLI). */
+    readonly typeFixtures?: readonly TypeFixture[];
+    /**
+     * Local file the `upload` op attaches (CLI `--fixture`). Validated before any
+     * browser opens: a missing file throws `FixtureNotFoundError`.
+     */
+    readonly fixture?: string;
+    /** Where the Recording is written. Default `.jevitate/logs/<date>` (project, else `~/.jevitate`). */
+    readonly outDir?: string;
+    /** Testing seam — defaults to a real `PlaywrightBrowserPort`. */
+    readonly browserPortFactory?: () => BrowserPort;
+    /** How Chromium is launched (executable/channel/extra args) and shown (#245 demo mode). Default: pinned Chromium, headless. */
+    readonly browser?: BrowserRunOptions;
+    /** #251 `--screenshots`: masked screenshots (one per distinct screen, or per step) + `index.md`. */
+    readonly screenshots?: ScreenshotsSpec;
+    /**
+     * #250 `--evidence-video`: after the result is written, each defect's minimal repro is replayed
+     * with captions (the failing step marked) into a masked clip + before/at screenshots, attached as
+     * `defects[].evidence` (and to its issue draft).
+     */
+    readonly evidenceVideo?: boolean;
+    /**
+     * Playwright storageState JSON to seed the session from (CLI `--storage-state`) —
+     * the deterministic authenticated pre-step. Contains live session cookies: it is
+     * handed only to the browser, never to a model or a Recording.
+     */
+    readonly storageState?: string;
+    /**
+     * Writes the browser context's storageState (cookies + origin storage) here when the run ends
+     * (CLI `--save-storage-state`) — so a rotating refresh token stays usable across runs instead of
+     * invalidating `--storage-state`'s file on first use. The file holds live session credentials:
+     * written with mode 0600, and its contents are never logged.
+     *
+     * #159: written on EVERY exit path, not only a clean one — a crash (thrown mid-mission, still
+     * reaches `persistStorageState` in this function's `finally`) and a kill signal (SIGTERM/SIGINT,
+     * via the kill switch's own synchronous write of the mission's `StorageStateSnapshotter`, see
+     * `storage-state-snapshot.ts`) both still get a write. Neither ever overwrites a good file with a
+     * session that is already lost/logged-out (a page that looks login-like at the moment of capture):
+     * the mission falls back to the last snapshot taken while the session still looked authenticated,
+     * and writes nothing at all if it never captured one. There is currently no flag to force a write
+     * over that guard — an operator who wants the raw end-state regardless can inspect the Recording's
+     * `finalUrl` and re-run with a fresh `--storage-state` login.
+     */
+    readonly saveStorageState?: string;
+    /** ISO clock for the recording filename. Default `Date.now()`. */
+    readonly nowIso?: () => string;
+    /** The target's settle/hang configuration (`~/.jevitate/targets.json` + flags). */
+    readonly target?: TargetConfig;
+    /** Issue filing for a crash (off unless enabled + a repo is configured). Default: drafts only. */
+    readonly filing?: FilingConfig;
+    /** Creates the filer — called only when filing is enabled. */
+    readonly issueFiler?: () => IssueFilerPort;
+    /** Fresh-context replays that confirm a hang (default 2). */
+    readonly hangReplays?: number;
+    /** Conversational pages: the reply wait (ms) and the cap (chars) on each generated message. */
+    readonly conversation?: ConversationOptions;
+    /** App-declared invariants (`--invariants`, #86), already validated against the allowlist. */
+    readonly invariants?: InvariantSpec;
+    /** Backend log sources (`--log-source`/`--log-defect`, #142), already validated. */
+    readonly serverLog?: ServerLogOptions;
+    /** Resolved `authFrom.secret` refs (#135) a declared probe may use: `env:VAR` → its value. */
+    readonly invariantAuthTokens?: ReadonlyMap<string, string>;
+    /**
+     * Mission fixtures (#140/#144), ALREADY set up by the caller: every hang replay re-runs
+     * restore+setup first, the state is restored when the mission ends (the caller also restores on
+     * every exit path — idempotent), and the result/Recording carry the identity.
+     */
+    readonly fixtures?: MissionFixtures;
+    /**
+     * Per-mission viewport/device emulation (#149, CLI `--viewport <W>x<H>` / `--device "<name>"`,
+     * mutually exclusive). An unknown device name (or both given together) is refused BEFORE any
+     * browser opens (`PlaywrightBrowserPort.open`'s `resolveEmulation`). Recorded on the Recording,
+     * so replay/verify-fix reproduce under the SAME device by default.
+     */
+    readonly emulation?: EmulationSpec;
+    /**
+     * #147: the mission's actors (`--actor`). The primary's storageState seeds the mission session
+     * (it must equal `storageState` when both are given); each observer gets its own fresh context,
+     * opened only when a declared cross-actor check needs it, never driven by the model.
+     */
+    readonly actors?: MissionActors;
+    /**
+     * #293 `--from-journey`/`--at-step`: replayed into the session (after fixture setup) before the
+     * goal loop, which then starts on the live page it left — never a fresh navigation. `url` is only
+     * the expected landing.
+     */
+    readonly journeyPrefix?: JourneyPrefix;
+}
+export interface RunExplorationResult {
+    /** The result schema's version (#195): the common fields below are filled the same way by every strategy. */
+    readonly schemaVersion: typeof MISSION_RESULT_SCHEMA_VERSION;
+    readonly strategy: "goal";
+    /**
+     * #213: the `--storage-state` session was not honoured — the run's first page was a sign-in page, so
+     * whatever it did (the model may sign in by itself), it did not start as that session. A warning.
+     */
+    readonly sessionLost?: {
+        readonly reason: string;
+    };
+    /**
+     * The portable verdict — ALWAYS canonical (#217): `goalOutcome` folded by the domain's single
+     * mapping (`GOAL_OUTCOME_FOLD`): succeeded → clean; failed/exhausted/blocked → defects-found.
+     */
+    readonly missionOutcome: MissionOutcome;
+    /** The goal run's own ending (#217): succeeded/failed/exhausted/blocked, or a shared outcome. Equal to `outcome`. */
+    readonly goalOutcome: GoalBasedOutcome;
+    readonly outcome: GoalBasedOutcome;
+    /** The writes the run's actions fired (#116), marked when the control was paid / destructive. */
+    readonly sideEffects: SideEffect[];
+    readonly sideEffectsTruncated?: number;
+    /** #303: the run's action deltas (verdict counts, per-action overhead) — only with `--action-deltas`. */
+    readonly actionDeltas?: ActionDeltaStats;
+    /**
+     * Did the loop complete its goal (`completed`, verified by the success assertion), or why not
+     * (`incomplete` + reason)? `outcome` above is the mission verdict; this is the run's own account.
+     */
+    readonly runOutcome: RunOutcome;
+    /** A find-out goal's answer (#101), present only when code grounded it on the observed pages. */
+    readonly answer?: RunAnswer;
+    readonly assertionPassed: boolean;
+    /** Each success check's verdict and what the oracle saw. */
+    readonly checks: SuccessCheckResult[];
+    /** Warnings about the verdict (#174: a `--success-when held` check that already held on the start page). */
+    readonly checkWarnings?: string[];
+    readonly stop: StopReason;
+    readonly finalUrl: string;
+    readonly decisions: number;
+    readonly actions: number;
+    /** Every Recording the run wrote (#195: one list on every strategy) — a goal run writes one. */
+    readonly recordingPaths: string[];
+    /** #245: `--record-video` files, finalized before this result was written (absent when not recording). */
+    readonly videoPaths?: string[];
+    /**
+     * The per-decision trail (op, target, confidence, whether the action succeeded and why
+     * not, URL, page signature) — so a stalled or failed run is explainable. Written next to
+     * the Recording as `<recording>.transcript.json`. Built from already-redacted state.
+     */
+    readonly transcriptPath: string;
+    readonly transcript: readonly TranscriptEntry[];
+    /** Process exit code for this outcome (see `goalExitCode`). */
+    readonly exitCode: number;
+    /** Why the run ended `crashed`/`inconclusive`. */
+    readonly failure?: MissionFailure;
+    /** Why the mission did not succeed (every outcome but `succeeded`, `blocked`/`exhausted` included). */
+    readonly reason?: string;
+    /** Issue drafts (a crash) written next to the Recording, and what filing did with them. */
+    readonly issues: FindingsIssues;
+    /** Slowest pages/transitions and endpoints (p50/max), keyed by normalized route/endpoint. */
+    readonly timing: TimingSummary;
+    /** Hang findings (0 or 1: the loop stops at a hang), each with its fresh-context reproduction. */
+    readonly hangs: HangFinding[];
+    /** #126: seed-load hangs that did not reproduce (the goal was retried) — evidence, whatever the outcome. */
+    readonly intermittentHangs?: HangFinding[];
+    /** For a `crashed` run: the evidence and its attribution (jevitate / system under test / uncertain). */
+    readonly crash?: CrashReport;
+    /** Declared mission spend budgets (#150/#180): the observed trajectory, whatever the outcome. */
+    readonly budget?: BudgetTrajectory[];
+    /** The run's Recording (also written to `recordingPath`). */
+    readonly recording: Recording;
+    /** Where the run happened — what `verify-fix` needs to replay a finding. */
+    readonly target: MissionTarget;
+    /** The persisted typed result (`<recording>.result.json`). */
+    readonly resultPath: string;
+    /** Which build produced this result (issue #83): `{version, commit, builtAt}`. */
+    readonly engine: EngineInfo;
+    /**
+     * EVERY defect the run found (#195): HTTP 5xx hard-signal defects (#208), declared-invariant defects (#86, with `--invariants`) and
+     * `server-log` defects (#142, with `--log-defect`) — `verify-fix` replays any of them by fingerprint.
+     */
+    readonly defects: Array<InvariantDefect | Http5xxDefect | ServerLogDefect>;
+    /** Per declared invariant: applied / held / violated / unreadable counts. */
+    readonly invariants?: InvariantReport[];
+    /** The declared spec the run evaluated — persisted so `verify-fix` re-checks the SAME invariants. */
+    readonly invariantSpec?: InvariantSpec;
+    /** Judgment/generation call counts and tokens for this run (#100); present only when `opts.usage` was supplied. */
+    readonly usage?: UsageCounts;
+    /** Backend log correlation summary (#142) — present only when `--log-source` was given. */
+    readonly serverLogs?: ServerLogsSummary;
+    /** The fixture the mission started from (#140/#144): identity, non-secret outputs, the setup/restore log. */
+    readonly fixtures?: MissionFixtureResult;
+    /** The host's health over the run (#203): peaks, the slowest render, starved steps. */
+    readonly hostHealth: HostHealthSummary;
+    /** Findings met while the host was starved (#203) — advisory, never a defect/hang, never failing the run. */
+    readonly environmentDegraded: EnvironmentDegraded[];
+    /** #293: the Journey step a journey-anchored run branched from (absent on a bare-URL run). */
+    readonly branch?: JourneyBranchPoint;
+}
+/**
+ * Pairs an already-computed UI-side `reason` with the correlated server cause on the step the run
+ * ended on (#165 "Also"): `"<UI reason>; server: <level> \"<message>\""` — or, when the line was
+ * correlated to its exact request by a trace/correlation id (#204), `"<UI reason>; caused by:
+ * <level> \"<message>\" on POST /x (500)"`. A no-op when there is no
+ * `reason` to pair with, the outcome isn't one of blocked/exhausted/inconclusive (a `defects-found`
+ * or an oracle-unhealthy `inconclusive` already gets its own `serverLogOutcomeReason`), or no
+ * server-log evidence attached to that step — including when `--log-source` was never given.
+ */
+export declare function withServerCause(reason: string | undefined, outcome: GoalBasedOutcome, transcript: readonly TranscriptEntryWithLogs[] | undefined): string | undefined;
+export declare function runExploration(opts: RunExplorationOptions): Promise<RunExplorationResult>;