@jevitate/cli 0.1.0 → 0.3.0

package/dist/ux-review.js

@@ -0,0 +1,171 @@
+// ux-review.ts — offline UX review of a saved Recording (`jevitate ux`) (#231).
+import { logsDirFor } from "./project-dir.js";
+import { existsSync, statSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { a11yChecks, analyzeClaims, buildReport, calibrationCaveat, claimsCaveat, detectFriction, detectRepeatedReplies, detectSignals, evidenceFromFile, groundFindings, loadV1Rubric, parseUxEvidenceFile, resolveMinConfidence, resolveMaxFindingsPerRoute, resolveQualityPolicy, withSignalFindings } from "@jevitate/ux";
+import { NO_PRODUCT_FACTS_CAVEAT, loadProductFacts } from "./ux-product.js";
+import { loadUxMaxFindingsPerPage, loadUxMinConfidence, loadUxMinConfidenceByAppClass, loadUxShow } from "./ux-config.js";
+import { writeUsageSidecar } from "./mission-journal.js";
+import { DEFAULT_JUDGMENT_BUDGET, captureFromTranscript, recordingToEvidence } from "./ux-evidence.js";
+import { clock } from "@jevitate/domain";
+const NO_EVIDENCE_CAVEAT = "no usability evidence sidecar (<stamp>.evidence.json, written next to the Recording by live usability runs, #134): this pass sees only the Recording's touched controls and urls — rubric items needing visible text or a11y facts are Skipped, and the run signals that need the live capture (hung request, stuck job, duplicate write/create, failed submit, inert control, internal id, url mismatch) could not be checked; with a transcript, journey friction and repeated replies still are.";
+const NO_PROBES_CAVEAT = "no guard probes (written by live usability runs into the evidence sidecar, #198): destructive controls could not be checked for a confirmation step offline — such claims are reported as unverifiable coverage, never as findings.";
+const NO_TRANSCRIPT_CAVEAT = "blocked/disabled-target evidence not available: this offline pass has no mission transcript, so a dead end like a button that never enables cannot be seen (pass --result <mission-result.json>, as written by `jevitate explore`, to include it — the same evidence a live usability run sees).";
+/**
+ * Offline UX review. FAIL-FAST: an analyzer `failed` outcome throws
+ * `UxAnalysisFailedError` (the CLI maps it to a non-zero fail envelope) — never
+ * a fabricated "clean" report.
+ */
+export async function runUxReview(opts) {
+    // #163: this review's own share of a (possibly shared) tracker.
+    const runUsage = opts.usage?.scope();
+    const minConfidence = resolveMinConfidence(opts.minConfidence, opts.env ?? process.env, loadUxMinConfidence(opts.configPath), loadUxMinConfidenceByAppClass(opts.configPath, opts.appContext.appClass));
+    const quality = resolveQualityPolicy(opts.show, opts.env ?? process.env, loadUxShow(opts.configPath), opts.appContext.appClass);
+    const maxFindingsPerRoute = resolveMaxFindingsPerRoute(opts.maxFindingsPerRoute, opts.env ?? process.env, loadUxMaxFindingsPerPage(opts.configPath));
+    // #198: product facts are validated before any model call (a bad file is a usage error).
+    const product = await loadProductFacts(opts.product);
+    // #134: a live usability run's evidence sidecar gives offline review the SAME screens and run
+    // signals the live analysis had; otherwise the Recording (+ transcript) is all there is.
+    let screens;
+    let appContext = opts.appContext;
+    let signalFindings = [];
+    let friction = [];
+    let steps = [];
+    let probes;
+    const evidenceCaveats = [];
+    if (opts.evidenceFile !== undefined) {
+        ({ screens, appContext } = evidenceFromFile(opts.evidenceFile, opts.appContext));
+        signalFindings = detectSignals(opts.evidenceFile.signals, opts.signals);
+        friction = detectFriction(opts.evidenceFile.signals, opts.evidenceFile.outcome ?? opts.missionOutcome);
+        steps = opts.evidenceFile.signals.steps;
+        probes = opts.evidenceFile.probes;
+        if (probes === undefined)
+            evidenceCaveats.push(NO_PROBES_CAVEAT);
+    }
+    else {
+        screens = recordingToEvidence(opts.recording, opts.appContext, opts.appContext.job, opts.missionTranscript);
+        if (opts.missionTranscript !== undefined) {
+            const partial = captureFromTranscript(opts.missionTranscript);
+            signalFindings = detectRepeatedReplies(partial, opts.signals);
+            friction = detectFriction(partial, opts.missionOutcome);
+            steps = partial.steps;
+        }
+        else {
+            evidenceCaveats.push(opts.missionTranscriptUnavailable ?? NO_TRANSCRIPT_CAVEAT);
+        }
+        evidenceCaveats.push(opts.evidenceUnavailable === undefined ? NO_EVIDENCE_CAVEAT : `${opts.evidenceUnavailable} — ${NO_EVIDENCE_CAVEAT}`);
+        evidenceCaveats.push(NO_PROBES_CAVEAT);
+    }
+    if (product.facts === undefined)
+        evidenceCaveats.push(NO_PRODUCT_FACTS_CAVEAT);
+    // #198: the same claim pipeline as the live run (claims.ts), over the same evidence.
+    const outcome = await analyzeClaims({
+        screens,
+        rubric: loadV1Rubric(),
+        appContext,
+        ...(opts.secrets === undefined ? {} : { secrets: opts.secrets }),
+        judgmentBudget: opts.judgmentBudget ?? DEFAULT_JUDGMENT_BUDGET,
+        friction,
+        steps,
+        signalFindings,
+        ...(probes === undefined ? {} : { probes }),
+        ...(product.facts === undefined ? {} : { facts: product.facts }),
+    }, { judge: opts.judge, gen: opts.gen, a11yChecker: a11yChecks, ...(opts.polish === true ? { polish: true } : {}) });
+    if (outcome.kind === "failed") {
+        throw new UxAnalysisFailedError(outcome.reason, outcome.screenId, outcome.rubricItemId);
+    }
+    const calibrationCaveats = [calibrationCaveat(opts.appContext.appClass), claimsCaveat()];
+    const report = buildReport(groundFindings(withSignalFindings(outcome, signalFindings), friction), {
+        minConfidence,
+        quality,
+        maxFindingsPerRoute,
+        evidenceCaveats,
+        calibrationCaveats,
+    });
+    const outDir = opts.outDir ?? logsDirFor();
+    await mkdir(outDir, { recursive: true });
+    const iso = (opts.nowIso ?? (() => clock.nowIso()))();
+    const reportPath = join(outDir, `ux-${iso.replace(/[:.]/g, "-")}.json`);
+    await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    if (runUsage !== undefined)
+        writeUsageSidecar(reportPath, runUsage);
+    return { report, reportPath, ...(runUsage === undefined ? {} : { usage: runUsage.snapshot() }) };
+}
+/** Finds the sidecars that exist next to `recordingPath` (only `<stem>.recording.json` has a stem). */
+export function discoverRecordingSidecars(recordingPath) {
+    if (!recordingPath.endsWith(".recording.json"))
+        return {};
+    const stem = recordingPath.slice(0, -".recording.json".length);
+    const file = (p) => (existsSync(p) && statSync(p).isFile() ? p : undefined);
+    const dir = (p) => (existsSync(p) && statSync(p).isDirectory() ? p : undefined);
+    const evidencePath = file(`${stem}.evidence.json`);
+    const transcriptPath = file(`${stem}.transcript.json`);
+    const resultPath = file(`${stem}.result.json`);
+    const screenshotDir = dir(`${stem}.screens`);
+    return {
+        ...(evidencePath === undefined ? {} : { evidencePath }),
+        ...(transcriptPath === undefined ? {} : { transcriptPath }),
+        ...(resultPath === undefined ? {} : { resultPath }),
+        ...(screenshotDir === undefined ? {} : { screenshotDir }),
+    };
+}
+function asOutcome(v) {
+    if (v === null || typeof v !== "object")
+        return undefined;
+    const o = v;
+    if (o.status === "completed")
+        return { status: "completed" };
+    if (o.status === "incomplete")
+        return { status: "incomplete", reason: typeof o.reason === "string" ? o.reason : "not completed" };
+    return undefined;
+}
+/**
+ * Reads the evidence sidecar and the transcript/result (explicit paths win over discovered ones).
+ * Never throws: an unreadable file becomes the matching `…Unavailable` caveat.
+ */
+export async function loadRecordingSidecars(paths) {
+    const out = {};
+    if (paths.evidencePath !== undefined) {
+        try {
+            out.evidenceFile = parseUxEvidenceFile(JSON.parse(await readFile(paths.evidencePath, "utf8")));
+        }
+        catch (err) {
+            out.evidenceUnavailable = `could not read the evidence sidecar ${paths.evidencePath}: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    else {
+        out.evidenceUnavailable = "no evidence sidecar next to the Recording";
+    }
+    const source = paths.resultPath ?? paths.transcriptPath;
+    if (source !== undefined) {
+        try {
+            const raw = JSON.parse(await readFile(source, "utf8"));
+            const obj = (raw ?? {});
+            const transcript = Array.isArray(raw) ? raw : (obj.result?.transcript ?? obj.transcript);
+            if (Array.isArray(transcript))
+                out.missionTranscript = transcript;
+            else
+                out.missionTranscriptUnavailable = `${source} has no transcript`;
+            const outcome = Array.isArray(raw) ? undefined : asOutcome(obj.result?.outcome ?? obj.outcome);
+            if (outcome !== undefined)
+                out.missionOutcome = outcome;
+        }
+        catch (err) {
+            out.missionTranscriptUnavailable = `could not read ${source}: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    return out;
+}
+export class UxAnalysisFailedError extends Error {
+    screenId;
+    rubricItemId;
+    code = "E_UX_ANALYSIS";
+    constructor(reason, screenId, rubricItemId) {
+        super(`UX analysis failed: ${reason}${screenId ? ` (screen ${screenId})` : ""}`);
+        this.screenId = screenId;
+        this.rubricItemId = rubricItemId;
+        this.name = "UxAnalysisFailedError";
+    }
+}
+//# sourceMappingURL=ux-review.js.map

package/dist/ux-review.js.map

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

package/dist/ux-usability.d.ts

@@ -0,0 +1,263 @@
+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 { InvariantSpec } from "@jevitate/recording";
+import { type SuccessCheck, type SuccessCheckResult, type SuccessWhen, type Bounds, type TimingSummary, type RunAnswer, type RunOutcome, type SecretField, type HangFinding, type SideEffect, type BudgetTrajectory, type CrashReport } from "@jevitate/explore";
+import { type AppContext, type SignalOptions, type UxReport } from "@jevitate/ux";
+import { type ConversationOptions } from "./conversation-options.js";
+import { type GoalOutcome, type MissionFailure, type MissionOutcome } from "@jevitate/domain";
+import { MISSION_RESULT_SCHEMA_VERSION, type AdvisoryServerLogDefect } from "./result-schema.js";
+import { type JourneyPrefix } from "./journey-prefix.js";
+import type { JourneyBranchPoint } from "@jevitate/journey";
+import { type ActionDeltaStats, type HostHealthSampler, type Http5xxDefect } from "@jevitate/explore";
+import type { EnvironmentDegraded, HostHealthSummary } from "@jevitate/domain";
+import { type EngineInfo } from "./engine.js";
+import { type ServerLogsSummary } from "./log-correlation.js";
+import { type MissionTarget, type ServerLogOptions } from "./explore-api.js";
+import type { TargetConfig } from "./target-config.js";
+export interface RunUsabilityMissionOptions {
+    /** Test seam (#203): the run's host-health sampler (a deterministic fake host). Default: this host's. */
+    readonly hostHealth?: HostHealthSampler;
+    readonly url: string;
+    readonly job: string;
+    readonly allowlist: readonly string[];
+    readonly appContext: AppContext;
+    readonly judge: JudgmentPort;
+    readonly gen: GenerationPort;
+    /** Usage accounting (#100): see `RunUxReviewOptions.usage`. */
+    readonly usage?: UsageTracker;
+    /** Report cutoff (see `RunUxReviewOptions.minConfidence`). */
+    readonly minConfidence?: number | string;
+    /**
+     * Quality grades to show, e.g. "actionable,relevant-minor". Precedence: this (CLI `--show`) >
+     * `JEVITATE_UX_SHOW` > config `ux.show` > every grade (#133: the uncalibrated grader labels, it does not filter).
+     */
+    readonly show?: string;
+    /** Cap on findings per route (see `RunUxReviewOptions.maxFindingsPerRoute`). */
+    readonly maxFindingsPerRoute?: number | string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Path of the config file holding `ux.minConfidence`. Default `~/.jevitate/config.json`. */
+    readonly configPath?: string;
+    readonly bounds?: Partial<Bounds>;
+    readonly secrets?: readonly string[];
+    /**
+     * Secret field bindings (`--secret-field` / `--totp`, #72): typed by code, never by the model;
+     * masked in every screenshot and redacted from the transcript, Recording and report.
+     */
+    readonly secretFields?: readonly SecretField[];
+    /** Tuning of the run-signal oracles (#96), e.g. the hung-request floor. Defaults suit real apps. */
+    readonly signals?: SignalOptions;
+    /** Local file the `upload` op attaches (CLI `--fixture`); validated before any browser opens. */
+    readonly fixture?: string;
+    readonly judgmentBudget?: number;
+    /** Conversational pages: the reply wait (ms) and the cap (chars) on each generated message. */
+    readonly conversation?: ConversationOptions;
+    readonly outDir?: string;
+    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;
+    /** Per-mission viewport/device emulation (#149, CLI `--viewport <W>x<H>` / `--device "<name>"`). */
+    readonly emulation?: EmulationSpec;
+    /**
+     * Playwright storageState JSON to seed the session from (CLI `--storage-state`) — the
+     * deterministic authenticated pre-step. Holds live session cookies: handed only to the
+     * browser, never to a model or a finding.
+     */
+    readonly storageState?: string;
+    /**
+     * Writes the browser context's storageState here when the run ends (CLI `--save-storage-state`) —
+     * see `RunExplorationOptions.saveStorageState`'s doc for the full behaviour (written on every exit
+     * path including a crash/kill signal, never over a lost/logged-out session, mode 0600).
+     */
+    readonly saveStorageState?: string;
+    readonly nowIso?: () => string;
+    /** The target's settle/hang configuration (`~/.jevitate/targets.json` + flags). */
+    readonly target?: TargetConfig;
+    /** Test seam: extract a page's visible text. Default reads the live page. */
+    readonly extractText?: (session: {
+        page: {
+            evaluate: (fn: () => string) => Promise<string>;
+        };
+    }) => Promise<string>;
+    /**
+     * Backend log sources (`--log-source`/`--log-defect`, #142), already validated. Lines attach to
+     * usability steps the same way as every other strategy; a `server-log` defect is reported in the
+     * result but — like every UX finding — never gates `missionOutcome`/`exitCode` (advisory-only).
+     */
+    readonly serverLog?: ServerLogOptions;
+    /**
+     * Horizontal-overflow hard signal (#149, CLI `--check-overflow` / `--ignore-overflow`): checked
+     * on every observed screen and, when it fires, reported as a `tier: "signal"` UxFinding — pure
+     * DOM geometry (`detectOverflow`), never a model judgment. Runs by default only when the emulated
+     * viewport is narrower than 1024px, or always when `checkOverflow` is set.
+     */
+    readonly overflow?: {
+        readonly checkOverflow?: boolean;
+        readonly toleranceCss?: number;
+        /** `--ignore-overflow <selector>` (repeatable): intentional overflow, never a finding. */
+        readonly ignoreSelectors?: readonly string[];
+    };
+    /**
+     * `--invariants` (#150 only): usability does not check app-declared invariants (#86) or captures
+     * (#147) today — a spec carrying either is refused. Only its `budget` (over its `observe` map) is
+     * read: a pre-action guard and a post-settle check, the same as every other mission.
+     */
+    readonly invariants?: InvariantSpec;
+    /** Resolved `authFrom.secret` refs (#135) a declared budget's probe may use: `env:VAR` → its value. */
+    readonly invariantAuthTokens?: ReadonlyMap<string, string>;
+    /**
+     * #225: independent completion checks on the job (CLI `--success`, a suite mission's `success`) —
+     * the SAME semantics as a goal run's: every one must hold (grounding the model's `done` mid-run and
+     * judged again on the final page), a vacuous one (#202) fails unless `allowVacuousChecks`, and the
+     * verdict folds exactly like a goal run's (`goalOutcome` → `missionOutcome`). Never ignored: with
+     * checks, the job's completion is theirs to decide, not the advisory goal judgment's.
+     */
+    readonly successChecks?: readonly SuccessCheck[];
+    /** When the page checks must hold (`--success-when`): `final` (default) | `held`. */
+    readonly successWhen?: SuccessWhen;
+    /** #202 `--allow-vacuous-checks`: a check satisfied before the first action warns instead of failing. */
+    readonly allowVacuousChecks?: boolean;
+    /**
+     * #198 `--product <file>`: the product facts (plans/prices, key journeys, each page's intended next
+     * step). Default: `.jevitate/product.json` in the project, when present. Validated before a browser
+     * opens (`ProductFactsError`, E_UX_PRODUCT_INPUT).
+     */
+    readonly product?: string;
+    /** #198 `--polish`: polish each verified finding's recommendation with one generation call (opt-in). */
+    readonly polish?: boolean;
+    /**
+     * #198 `--probe-guards` (opt-in): click each destructive control once, fail-safe (every write and
+     * destructive-looking request aborted; refused on a page with an open WebSocket/EventSource or a
+     * controlling service worker), to verify whether a confirmation guards it. Off: nothing is clicked,
+     * and those guard claims are reported unverifiable.
+     */
+    readonly probeGuards?: boolean;
+    /**
+     * #293 `--from-journey`/`--at-step`: replayed into the session before the review, which then starts
+     * on the live page it left — never a fresh navigation. `url` is only the expected landing.
+     */
+    readonly journeyPrefix?: JourneyPrefix;
+    /**
+     * #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;
+}
+/** Usability reads only a spec's `budget` (#150) — never its `invariants`/`capture` (#86/#147, not supported here). */
+export declare class UsabilityInvariantsUnsupportedError extends Error {
+    readonly code: "E_USABILITY_INVARIANTS";
+    constructor();
+}
+export interface RunUsabilityMissionResult {
+    /** 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 review branched from (absent on a bare-URL run). */
+    readonly branch?: JourneyBranchPoint;
+    /** 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: "usability";
+    /** Where the review ran (#195: every strategy states its scope the same way) — a session PATH at most. */
+    readonly target: MissionTarget;
+    /**
+     * EVERY defect the review found (#195) — HTTP 5xx hard-signal defects (#208) and `server-log`
+     * defects (#142), each marked `advisory: true`: reported like every other strategy's, never gating
+     * a UX review's outcome.
+     */
+    readonly defects: Array<AdvisoryServerLogDefect | (Http5xxDefect & {
+        readonly advisory: true;
+    })>;
+    /** Hang findings (0 or 1: the review stops at a hang), as every strategy lists them (#195). */
+    readonly hangs: HangFinding[];
+    /** Every Recording the review wrote (#195: one list on every strategy) — a review writes one. */
+    readonly recordingPaths: string[];
+    /** #245: `--record-video` files, finalized before this result was written (absent when not recording). */
+    readonly videoPaths?: string[];
+    /** The UX report; `null` when the analysis was unavailable (see `analysisUnavailable`). */
+    readonly report: UxReport | null;
+    readonly reportPath: string | null;
+    readonly stop: string;
+    /**
+     * Did the review's journey complete (`completed`: the job's success condition was observably met),
+     * or why not (`incomplete` + reason)? Never a silent early stop.
+     */
+    readonly outcome: RunOutcome;
+    /** A find-out job's answer (#101), present only when code grounded it on the observed pages. */
+    readonly answer?: RunAnswer;
+    readonly screensObserved: number;
+    /** The explore loop's decision transcript, written next to the report (each step: its screenshot). */
+    readonly transcriptPath: string;
+    /** Where the per-step screenshots are written (secret fields masked). */
+    readonly screenshotDir: string;
+    /**
+     * #134: the evidence sidecar (`usability-<stamp>.evidence.json`) — every screen as the analyzer
+     * saw it after redaction, plus the run-signal capture — so `jevitate ux <recording>` reproduces
+     * this run's findings offline. `null` when it could not be written (redaction unavailable).
+     */
+    readonly evidencePath: string | null;
+    /** Every per-step screenshot written, in order. */
+    readonly screenshots: readonly string[];
+    /** The writes the run's actions fired (#116), marked when the control was paid / destructive. */
+    readonly sideEffects: readonly SideEffect[];
+    readonly sideEffectsTruncated?: number;
+    /** #303: the run's action deltas (verdict counts, per-action overhead) — only with `--action-deltas`. */
+    readonly actionDeltas?: ActionDeltaStats;
+    /**
+     * The typed verdict. UX findings are advisory, so a completed review is `clean`; a run whose
+     * loop broke is `crashed`/`inconclusive`, and so is one whose analysis could not be produced — or
+     * (#209) one whose job was never completed (`failure.kind: "job-incomplete"`).
+     */
+    readonly missionOutcome: MissionOutcome;
+    readonly exitCode: number;
+    readonly failure?: MissionFailure;
+    /** For a `crashed` review: the evidence and its attribution (jevitate / system under test / uncertain). */
+    readonly crash?: CrashReport;
+    /** Where the review ended (redacted), and how many decisions/actions it spent — as a goal run reports them. */
+    readonly finalUrl: string;
+    readonly decisions: number;
+    readonly actions: number;
+    /** Why the analysis could not be produced (the run's evidence is still kept). */
+    readonly analysisUnavailable?: string;
+    /** Slowest pages/transitions and endpoints (p50/max), keyed by normalized route/endpoint. */
+    readonly timing: TimingSummary;
+    /** Which build produced this result (issue #83): `{version, commit, builtAt}`. */
+    readonly engine: EngineInfo;
+    /** Judgment/generation call counts and tokens for this run (#100); present only when `opts.usage` was supplied. */
+    readonly usage?: UsageCounts;
+    /** The hang finding (with its reproduction k/N), present when the run stopped on a hang (#126); also in `hangs`. */
+    readonly hang?: HangFinding;
+    /** The persisted typed result (`usability-<stamp>.recording.result.json`), readable via MCP `get_mission_result`. */
+    readonly resultPath: string;
+    /** Backend log correlation summary (#142) — present only when `--log-source` was given. */
+    readonly serverLogs?: ServerLogsSummary;
+    /** Declared mission spend budgets (#150): the observed trajectory, present when any were declared. */
+    readonly budget?: BudgetTrajectory[];
+    /**
+     * #225 — present only when `successChecks` were given: the job's own ending as a goal run names it
+     * (`succeeded` / `failed` / `exhausted` / `blocked` / …), folded onto `missionOutcome` the same way.
+     */
+    readonly goalOutcome?: GoalOutcome;
+    /** #225: each success check's result, when `successChecks` were given. */
+    readonly checks?: readonly SuccessCheckResult[];
+    /** #225/#202: the success checks' warnings (a vacuous check, `held` notes), when there were any. */
+    readonly checkWarnings?: readonly string[];
+}
+/**
+ * Live usability mission. Guardrail #1 authorizes BEFORE opening a browser.
+ * Reuses explore()'s loop (goal = the job) and, via the additive onSnapshot
+ * hook, collects one screen's evidence per observation — then analyzes ONCE
+ * after the run. A UX finding NEVER gates the loop (the hook's result is
+ * ignored by explore). The temp profile dir is always removed.
+ */
+export declare function runUsabilityMission(opts: RunUsabilityMissionOptions): Promise<RunUsabilityMissionResult>;