@jevitate/cli 0.12.0 → 0.13.0

package/dist/ux-usability.js

@@ -1,55 +1,11 @@
-// ux-usability.ts — the live usability mission runner (`explore --strategy usability`) (#231).
-import { journeyFixtureBaseDir, resolveProjectMissionFixture } from "./journey-api.js";
-import { logsDirFor } from "./project-dir.js";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve as resolvePath } from "node:path";
-import { PlaywrightBrowserPort } 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 { explore, runGoalBasedMission, assertAuthorizedExploreTarget, reproduceHang, hangFinding, hangOutcome, InvariantMonitor, BudgetMonitor, secretFieldSecrets, clippingSummary, detectClipping, detectOverflow, shouldCheckOverflow } from "@jevitate/explore";
-import { a11yChecks, analyzeClaims, buildReport, calibrationCaveat, claimsCaveat, detectFriction, detectSignals, groundFindings, loadV1Rubric, persistableScreen, resolveMinConfidence, resolveMaxFindingsPerRoute, resolveQualityPolicy, withSignalFindings, makeSignalFinding } from "@jevitate/ux";
-import { captureFindingShots, planGuardProbes, runGuardProbes, skippedProbes, withProbePage } from "./ux-claim-probe.js";
-import { NO_PRODUCT_FACTS_CAVEAT, loadProductFacts } from "./ux-product.js";
-import { conversationConfig } from "./conversation-options.js";
-import { loadUxMaxFindingsPerPage, loadUxMinConfidence, loadUxMinConfidenceByAppClass, loadUxShow } from "./ux-config.js";
-import { foldGoalOutcome, clock } from "@jevitate/domain";
-import { MissionJournal, artifactStamp, closeQuietly, resultPathFor, writeMissionResult } from "./mission-journal.js";
-import { MISSION_RESULT_SCHEMA_VERSION, advisoryDefects, defectFields } from "./result-schema.js";
-import { missionExitCode } from "./mission-exit.js";
-import { launchArmed } from "./launch-armed.js";
-import { branchFields, startFromJourney } from "./journey-prefix.js";
-import { failureWithHostStarved, finishHostHealth } from "./host-health-run.js";
-import { Http5xxOracle } from "@jevitate/explore";
-import { currentEngineInfo } from "./engine.js";
-import { openServerLogRuntime } from "./log-correlation.js";
-import { triageOf, serverLogRuntimeOptions } from "./explore-shared.js";
-import { assertSaveStorageStateOutsideProject, currentUrlSafe, persistStorageState, serverLogResult } from "./explore-api.js";
-import { transcriptPathFor } from "./transcript-file.js";
-import { UsabilityCapture } from "./usability-capture.js";
-import { DEFAULT_JUDGMENT_BUDGET, extractTypedValues, snapshotToEvidence } from "./ux-evidence.js";
-import { UxAnalysisFailedError } from "./ux-review.js";
-/** Usability reads only a spec's `budget` (#150) — never its `invariants`/`capture` (#86/#147, not supported here). */
-export class UsabilityInvariantsUnsupportedError extends Error {
-    code = "E_USABILITY_INVARIANTS";
-    constructor() {
-        super("usability does not check app-declared invariants or captures — only a `budget` is read; " +
-            "give a spec with an empty invariants array (and no capture) to use --invariants with usability");
-        this.name = "UsabilityInvariantsUnsupportedError";
-    }
-}
-/**
- * Opens a FRESH browser session for replays (hang reproduction): a new context from the same port
- * and options — same authenticated storageState, never the session the finding was made in.
- */
-function freshSessionOpener(portFactory, launch, allowlist) {
-    return async () => {
-        const session = await portFactory().open(launch);
-        const actor = CastActor.named("replay").whoCan(new BrowseTheWeb(session, [...allowlist]));
-        return { page: session.page, actor, close: () => session.close() };
-    };
-}
+import { UsabilityInvariantsUnsupportedError, setUpUsabilityMission } from "./ux-usability/setup.js";
+import { runUsabilityLoop } from "./ux-usability/loop.js";
+import { analyzeUsabilityRun } from "./ux-usability/analysis.js";
+import { reproduceUsabilityHang } from "./ux-usability/hang.js";
+import { adjudicateUsabilityJob } from "./ux-usability/done-adjudication.js";
+import { writeUsabilityResult } from "./ux-usability/result.js";
+import { tearDownUsabilityMission } from "./ux-usability/teardown.js";
+export { UsabilityInvariantsUnsupportedError };
 /**
  * Live usability mission. Guardrail #1 authorizes BEFORE opening a browser.
  * Reuses explore()'s loop (goal = the job) and, via the additive onSnapshot
@@ -58,546 +14,16 @@ function freshSessionOpener(portFactory, launch, allowlist) {
  * ignored by explore). The temp profile dir is always removed.
  */
 export async function runUsabilityMission(opts) {
-    const origin = assertAuthorizedExploreTarget(opts.url, opts.allowlist);
-    assertSaveStorageStateOutsideProject(opts.saveStorageState);
-    // #150 — usability reads only a spec's `budget`: it does not check invariants or captures (#86/
-    // #147) today. Refused BEFORE a browser opens, same as every other bad-input refusal here.
-    if (opts.invariants !== undefined && (opts.invariants.invariants.length > 0 || opts.invariants.capture !== undefined)) {
-        throw new UsabilityInvariantsUnsupportedError();
-    }
-    // Validate the cutoff before a browser opens — a bad value fails fast, never mid-run.
-    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));
-    const fixture = opts.fixture === undefined ? undefined : await resolveProjectMissionFixture(opts.fixture);
-    // #198: the product facts are validated before a browser opens (a bad file is a usage error).
-    const product = await loadProductFacts(opts.product);
-    // #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 runCapture = runCaptureFor({
-        recordsVideo: opts.browser?.recordVideo !== undefined,
-        screenshots: opts.screenshots,
-        secrets: [...(opts.secrets ?? []), ...secretFieldSecrets(opts.secretFields)],
-        artifactPath: () => journal.recordingPath,
-        title: `usability: ${opts.job}`,
-    });
-    const portFactory = runCapture.wrap(opts.browserPortFactory ?? (() => new PlaywrightBrowserPort()));
-    const port = portFactory();
-    const collected = [];
-    const history = [];
-    // #149: one signal finding per distinct fingerprint (route + element) — a wide table seen across
-    // many observed screens is still ONE finding, never a finding per occurrence.
-    const overflowFindings = [];
-    const seenOverflow = new Set();
-    const extract = opts.extractText ??
-        (async (s) => s.page.evaluate(() => (typeof document !== "undefined" && document.body ? document.body.innerText : "")));
-    const outDir = opts.outDir ?? logsDirFor();
-    const iso = (opts.nowIso ?? (() => clock.nowIso()))();
-    const stamp = artifactStamp(iso);
-    const reportPath = join(outDir, `usability-${stamp}.json`);
-    // #98 — the same artifact shape as goal/adversarial missions, next to the report: the decision
-    // transcript (each step's redacted typed value and screenshot), the Recording and the per-step
-    // screenshots. Crash-safe: the transcript and partial Recording are flushed after every step.
-    const journal = new MissionJournal(join(outDir, `usability-${stamp}.recording.json`), transcriptPathFor(reportPath));
-    const screenshotDir = join(outDir, `usability-${stamp}.screens`);
-    // #245: shown/recorded like every other strategy's session (videos in `usability-<stamp>.videos/`).
-    const videoDir = runVideoDir(opts.browser, reportPath);
-    const launch = {
-        ...sessionLaunchOptions(opts.browser, videoDir),
-        allowedOrigins: [...opts.allowlist],
-        baseUrl: origin,
-        ...opts.emulation,
-        ...(opts.storageState !== undefined ? { storageState: opts.storageState } : {}),
-    };
-    // A bound secret (or TOTP seed) is a run secret too: masked on screen, redacted everywhere.
-    const secrets = [...(opts.secrets ?? []), ...secretFieldSecrets(opts.secretFields)];
-    // #163: this run's own share of a (possibly shared) tracker: its usage and sidecar.
-    const runUsage = opts.usage?.scope();
-    // The screenshot capture needs the open page; until then a killed run has taken none.
-    let armedCapture;
-    // Crash-safe on SIGTERM/SIGINT too (#94): a partial `inconclusive` result is written from
-    // whatever the journal has already flushed, and the process exits with the conventional code.
-    // #120: the transcript lives next to the REPORT (`usability-<stamp>.transcript.json`), not the
-    // Recording — so the killed run's result names the real file, and reports the live step list,
-    // the tokens spent so far and the screens already observed.
-    // #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: () => port.open(launch),
-        mission: (hooks) => ({
-            // #220: the killed run's partial result carries the unified schema's common fields too.
-            strategy: "usability",
-            target: { seedUrl: opts.url, 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,
-            ...(runUsage === undefined ? {} : { usage: runUsage }),
-            partialReport: () => ({ screensObserved: collected.length, screenshotDir, screenshots: armedCapture === undefined ? [] : armedCapture.screenshots() }),
-            ...(opts.saveStorageState === undefined ? {} : { storageState: { path: opts.saveStorageState, snapshot: hooks.snapshot } }),
-        }),
-    });
-    // #324: the engine runs a cmd: binding's command at type time. A value read mid-run joins this
-    // run's secrets at once (screenshots' scan, result, evidence, report) and — #360 — the run's pixel
-    // mask, before the value is typed. (It was once handed to UsabilityCapture, which has no such
-    // option, so a usability run could not type a cmd: field at all.)
-    const uxSecretCommand = opts.secretCommand === undefined
-        ? undefined
-        : async (command) => {
-            const out = await opts.secretCommand(command);
-            const value = out.trim();
-            if (value !== "" && !secrets.includes(value))
-                secrets.push(value);
-            if (value !== "")
-                await runCapture.mask.addSecret(value);
-            return out;
-        };
-    // #208: the shared HTTP 5xx hard signal, listening from before the first navigation.
-    const http5xx = new Http5xxOracle(session.page, { allowlist: opts.allowlist });
-    const capture = new UsabilityCapture({
-        page: session.page,
-        screenshotDir,
-        secrets,
-        ...(opts.secretFields === undefined ? {} : { secretFields: opts.secretFields }),
-    });
-    armedCapture = capture;
-    // The usability capture (screenshots) and the journal (crash-safe flush) are the EXISTING listener
-    // chain; a server-log runtime (#142) is inserted in FRONT of it (never replacing it) so every step
-    // still gets its screenshot/flush exactly as before, whether or not --log-source was given. #159:
-    // every settled step also refreshes the in-memory storageState snapshot (a cheap no-op when
-    // `--save-storage-state` was not given).
-    const journalListener = (entry, all) => {
-        runCapture.noteEntry(session.page, entry);
-        health.noteStep(entry);
-        http5xx.noteStep(entry);
-        capture.noteEntry(entry, all);
-        journal.onTranscriptEntry(entry, capture.withScreenshots(all));
-        snapshotter.noteSettledStep(currentUrlSafe(session));
-    };
-    const serverLog = openServerLogRuntime({
-        ...serverLogRuntimeOptions(opts.serverLog),
-        secrets,
-        onTranscriptEntry: journalListener,
-    });
-    // #204: every request's correlation ids, from before the first navigation.
-    serverLog?.observe(session.page);
-    // #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);
-    });
+    const ctx = await setUpUsabilityMission(opts);
     try {
-        // #293: a journey-anchored review first replays its Journey's prefix into this very session.
-        const start = await startFromJourney(opts.journeyPrefix, session, opts.url, opts.allowlist, opts.browser);
-        const actor = CastActor.named("usability-mission").whoCan(new BrowseTheWeb(session, [...opts.allowlist]));
-        // #150 — usability's own budget wiring: a plain `InvariantMonitor` reads a budget's declared
-        // observables (the same #86/#135 read/auth/redaction machinery), but this mission folds NO
-        // invariant defects — only a budget crossing can end the run early, via the same pre-action
-        // guard / post-settle hooks `explore()` offers every mission.
-        const budgetDecls = opts.invariants?.budget ?? [];
-        const invariantMonitor = opts.invariants === undefined || budgetDecls.length === 0
-            ? null
-            : new InvariantMonitor(opts.invariants, {
-                allowlist: opts.allowlist,
-                baseUrl: opts.url,
-                ...(opts.secrets === undefined ? {} : { secrets: opts.secrets }),
-                ...(opts.invariantAuthTokens === undefined ? {} : { authTokens: opts.invariantAuthTokens }),
-            });
-        const budget = invariantMonitor === null ? null : new BudgetMonitor(budgetDecls, invariantMonitor);
-        let budgetSettledSteps = 0;
-        const exploreCfg = {
-            ...(opts.target?.timing === undefined ? {} : { timingConfig: opts.target.timing }),
-            ...(opts.target?.settle === undefined ? {} : { settle: opts.target.settle }),
-            ...(opts.target?.hangs === undefined ? {} : { hangs: opts.target.hangs }),
-            ...(opts.target?.safety === undefined ? {} : { safety: opts.target.safety }),
-            onTranscriptEntry: serverLog?.onTranscriptEntry ?? journalListener,
-            onRecording: journal.onRecording,
-            // #303 (opt-in): action deltas, with Jev's advisory relevance labels.
-            ...(opts.actionDeltas === true ? { actionDeltas: { jev: true } } : {}),
-            hostHealth: health,
-            demoOverlay: demoOverlayOf(opts.browser),
-            ...(opts.secretFields === undefined ? {} : { secretFields: opts.secretFields }),
-            ...(uxSecretCommand === undefined ? {} : { secretCommand: uxSecretCommand }),
-            ...(opts.secretCommandAttempts === undefined ? {} : { secretCommandAttempts: opts.secretCommandAttempts }),
-            actor,
-            judge: opts.judge,
-            gen: opts.gen,
-            goal: opts.job,
-            allowlist: opts.allowlist,
-            startUrl: start.url,
-            ...(start.branch === undefined ? {} : { startInPlace: true }),
-            ...(start.restart === undefined ? {} : { restartAtStart: start.restart.restartAtStart }),
-            bounds: opts.bounds,
-            secrets: opts.secrets,
-            site: origin,
-            fixture,
-            fixtureRoot: journeyFixtureBaseDir(),
-            ...conversationConfig(opts.conversation),
-            onSnapshot: async (snap) => {
-                let visibleText = "";
-                try {
-                    visibleText = await extract(session);
-                }
-                catch {
-                    visibleText = ""; // best-effort; the analyzer Skips visibleText items honestly
-                }
-                const ev = snapshotToEvidence(snap, visibleText, opts.appContext, opts.job, [...history]);
-                collected.push(ev);
-                history.push({ screenId: ev.screenId, url: ev.url });
-                // #98 the step's (secret-masked) screenshot; #96 the screen's facts for the signal oracles.
-                await capture.observe(snap, visibleText);
-                // #149: horizontal-overflow hard signal — pure DOM geometry, never a model judgment.
-                // Best-effort like visibleText extraction above: a detection failure never fails the mission.
-                try {
-                    const vp = session.page.viewportSize();
-                    if (shouldCheckOverflow(vp?.width, opts.overflow?.checkOverflow ?? false)) {
-                        const overflow = await detectOverflow(session.page, {
-                            viewport: vp ?? { width: 1280, height: 720 },
-                            ...(opts.emulation?.device === undefined ? {} : { device: opts.emulation.device }),
-                            ...(opts.overflow?.toleranceCss === undefined ? {} : { toleranceCss: opts.overflow.toleranceCss }),
-                            ...(opts.overflow?.ignoreSelectors === undefined ? {} : { ignoreSelectors: opts.overflow.ignoreSelectors }),
-                            secrets,
-                        });
-                        if (overflow !== null && !seenOverflow.has(overflow.fingerprint)) {
-                            seenOverflow.add(overflow.fingerprint);
-                            overflowFindings.push(makeSignalFinding({
-                                kind: "horizontal-overflow",
-                                confidence: 0.9,
-                                url: ev.url,
-                                screenId: ev.screenId,
-                                observation: `${overflow.element.descriptor} overflows the ${overflow.viewport.width}px viewport by ${overflow.overflowPx}px on ${overflow.route}.`,
-                                userImpact: "Content extends past the visible viewport; a user on this device must discover and use horizontal scrolling to see it, and may miss it entirely.",
-                                recommendation: `Constrain ${overflow.element.descriptor} to the viewport width (e.g. a responsive layout, or an explicit scroll container) at ${overflow.viewport.width}px.`,
-                                controls: [overflow.element.descriptor],
-                                evidence: {
-                                    kind: "horizontal-overflow",
-                                    steps: [history.length],
-                                    requests: [],
-                                    detail: `scrollWidth exceeds innerWidth by ${overflow.overflowPx}px at a ${overflow.viewport.width}x${overflow.viewport.height} viewport`,
-                                },
-                            }));
-                        }
-                        // #302: text cut off vertically (a fixed-height box, or above the page top) — one finding per element.
-                        const clipped = await detectClipping(session.page, {
-                            viewport: vp ?? { width: 1280, height: 720 },
-                            ...(opts.emulation?.device === undefined ? {} : { device: opts.emulation.device }),
-                            ...(opts.overflow?.ignoreSelectors === undefined ? {} : { ignoreSelectors: opts.overflow.ignoreSelectors }),
-                            secrets,
-                        });
-                        for (const c of clipped) {
-                            if (seenOverflow.has(c.fingerprint))
-                                continue;
-                            seenOverflow.add(c.fingerprint);
-                            overflowFindings.push(makeSignalFinding({
-                                kind: "vertical-clipping",
-                                confidence: 0.9,
-                                url: ev.url,
-                                screenId: ev.screenId,
-                                observation: c.cause === "overflow-hidden"
-                                    ? `${c.element.descriptor} cuts off its text by ${c.clippedPx}px on ${c.route}: the content is taller than the box and overflow is hidden.`
-                                    : `${c.element.descriptor} is cut off ${c.clippedPx}px above the top of the page on ${c.route}.`,
-                                userImpact: "Part of the text is cut off and no scroll position shows it: a user on this device cannot read it.",
-                                recommendation: c.cause === "overflow-hidden"
-                                    ? `Let ${c.element.descriptor} grow with its content (min-height instead of height), make it scrollable, or truncate on purpose with line-clamp at ${c.viewport.width}px.`
-                                    : `Give the container of ${c.element.descriptor} room for its wrapped content (no fixed height, or no wrapping) at ${c.viewport.width}px.`,
-                                controls: [c.element.descriptor],
-                                evidence: { kind: "vertical-clipping", steps: [history.length], requests: [], detail: clippingSummary(c) },
-                            }));
-                        }
-                    }
-                }
-                catch {
-                    // Best-effort: the run's own explore loop is never held up or failed by this check.
-                }
-            },
-            ...(budget === null
-                ? {}
-                : {
-                    onBeforeAction: async (info) => {
-                        const g = await budget.guard(session.page, info);
-                        return g.refuse ? { refuse: true, reason: g.reason ?? "budget guard refused the action" } : { refuse: false };
-                    },
-                    onSettled: async () => {
-                        budgetSettledSteps += 1;
-                        // The FIRST settled snapshot (before any action) is the budget's baseline.
-                        if (budgetSettledSteps === 1) {
-                            const b = await budget.baseline(session.page);
-                            return b.crossed ? { stop: true, reason: b.reason ?? "budget observable unreadable at run start" } : { stop: false };
-                        }
-                        const r = await budget.afterSettle(session.page, budgetSettledSteps);
-                        return r.crossed ? { stop: true, reason: r.reason ?? "mission budget crossed" } : { stop: false };
-                    },
-                }),
-        };
-        const brief = "usability review: pursue the stated job as a plausible first-time user, using only what is on screen";
-        // #225: `--success` is never ignored — with checks the loop runs through the goal mission's
-        // independent adjudication (the same oracle, `held`/vacuous rules and verdict as a goal run).
-        const checks = opts.successChecks ?? [];
-        const adjudication = checks.length === 0
-            ? undefined
-            : await runGoalBasedMission({
-                ...exploreCfg,
-                missionBrief: brief,
-                successChecks: checks,
-                // #225: a `done` whose check failed on a job judged done ends the run — never the whole budget.
-                stopWhenJudgedDone: true,
-                ...(opts.successWhen === undefined ? {} : { successWhen: opts.successWhen }),
-                ...(opts.allowVacuousChecks === true ? { allowVacuousChecks: true } : {}),
-            });
-        const run = adjudication?.run ?? (await explore({ ...exploreCfg, missionContext: brief }));
-        // Never blocks the mission itself: the drain wait happens AFTER `explore()` returned.
-        const serverLogRun = serverLog === undefined ? undefined : await serverLog.finish(run.transcript);
-        journal.writeRecording(run.recording);
-        journal.writeTranscript(capture.withScreenshots(serverLogRun?.transcript ?? run.transcript));
-        // #85 item 1: the live run's own typed values (from its emitted Recording's fill/select
-        // steps — never a secret), so the vocabulary/jargon tier can tell the app's own copy apart
-        // from user-authored content it merely echoed back (same mechanism as the offline pass).
-        const typedValues = extractTypedValues(run.recording);
-        const screens = typedValues.length > 0 ? collected.map((ev) => ({ ...ev, typedValues })) : collected;
-        // #96: findings from the run's own measurements (hung request, duplicate write, internal id,
-        // inert control) — independent code, no model — reported alongside the rubric's.
-        const signalCapture = await capture.signalCapture(run.transcript, typedValues);
-        // A gRPC-web/Connect read is never a duplicate write (#110); `--read-rpc` marks more reads.
-        const readRequests = opts.target?.safety?.readRequests;
-        const signalFindings = [
-            ...detectSignals(signalCapture, readRequests === undefined ? opts.signals : { ...opts.signals, readRequests }),
-            // #149: horizontal-overflow, computed live during the run (never from the captured timeline).
-            ...overflowFindings,
-        ];
-        // #132: the friction the run walked into — what grounds (or not) each rubric finding.
-        const friction = detectFriction(signalCapture, run.outcome);
-        // #198: every destructive control on an analyzed screen is clicked once with its writes blocked
-        // (ux-claim-probe.ts) — the code evidence `destructive-unguarded` claims are verified against.
-        // On a dedicated page in the run's context, after the loop: the run's oracles never see it.
-        // A screen that cannot be redacted means no probes at all (destructive claims: unverifiable).
-        let probes;
-        try {
-            const plan = planGuardProbes(screens, secrets, opts.target?.safety);
-            probes = [...plan.refused];
-            // Clicking is opt-in (--probe-guards): without it every destructive control is `skipped`, and
-            // its guard claim is reported unverifiable — never asserted, never silently dropped.
-            if (opts.probeGuards !== true)
-                probes.push(...skippedProbes(plan.targets));
-            else if (plan.targets.length > 0) {
-                try {
-                    probes.push(...(await runGuardProbes(session.page, plan.targets, { allowlist: opts.allowlist, secrets })));
-                }
-                catch (err) {
-                    const why = `the guard probe could not open a page: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`;
-                    probes.push(...plan.targets.map((t) => ({ screenId: t.screen.screenId, route: t.route, control: t.label, controlKey: t.key, status: "failed", detail: why })));
-                }
-            }
-        }
-        catch {
-            probes = undefined;
-        }
-        // #134: the evidence sidecar, written through the redaction door BEFORE analysis (so it exists
-        // even when analysis fails). Fail-closed: if any screen cannot be redacted, no file is written.
-        const evidencePath = join(outDir, `usability-${stamp}.evidence.json`);
-        let evidenceWritten = null;
-        try {
-            const file = {
-                version: 1,
-                appContext: opts.appContext,
-                job: opts.job,
-                screens: screens.map((ev) => persistableScreen(ev, secrets)),
-                signals: signalCapture,
-                outcome: run.outcome,
-                ...(probes === undefined ? {} : { probes }),
-            };
-            await mkdir(outDir, { recursive: true });
-            await writeFile(evidencePath, `${JSON.stringify(file, null, 2)}\n`, "utf8");
-            evidenceWritten = evidencePath;
-        }
-        catch {
-            evidenceWritten = null;
-        }
-        // #198: findings are claims verified by code (claims.ts) — guard probes, product facts and the
-        // friction the run walked into — categorized and graded by Jev, written from templates.
-        const claimed = await analyzeClaims({
-            screens,
-            rubric: loadV1Rubric(),
-            appContext: opts.appContext,
-            secrets,
-            judgmentBudget: opts.judgmentBudget ?? DEFAULT_JUDGMENT_BUDGET,
-            friction,
-            steps: signalCapture.steps,
-            signalFindings,
-            ...(probes === undefined ? {} : { probes }),
-            ...(product.facts === undefined ? {} : { facts: product.facts }),
-        }, { judge: opts.judge, gen: opts.gen, a11yChecker: a11yChecks, ...(opts.polish === true ? { polish: true } : {}) });
-        // #198: a cropped, masked screenshot with the cited control boxed, per verified claim finding.
-        let outcome = claimed;
-        if (claimed.kind === "analyzed" && claimed.findings.some((f) => f.claim !== undefined)) {
-            const byScreen = new Map(screens.map((ev) => [ev.screenId, ev]));
-            const dir = join(outDir, `usability-${stamp}.findings`);
-            try {
-                const findings = await withProbePage(session.page, (p) => captureFindingShots(p, claimed.findings, byScreen, { dir, allowlist: opts.allowlist, secrets }));
-                outcome = { ...claimed, findings };
-            }
-            catch {
-                outcome = claimed; // presentation only: findings without screenshots are still the findings
-            }
-        }
-        // #126: a run that stops on a hang is never `clean` — it is reproduced in fresh contexts (same
-        // as a goal mission) and mapped through the same hang/intermittent/inconclusive rule.
-        let hang;
-        if (run.stop === "hang" && run.hang !== undefined) {
-            const h = run.hang;
-            const reproduction = await reproduceHang({
-                recording: run.recording,
-                recordingStepIndex: h.recordingStepIndex,
-                hang: h.signal,
-                openSession: freshSessionOpener(portFactory, launch, opts.allowlist),
-                fixtureBaseDir: journeyFixtureBaseDir(),
-                ...(opts.target?.safety === undefined ? {} : { safety: opts.target.safety }),
-                writtenBy: run.sideEffects.map((e) => e.control), // #181
-                perceive: {
-                    ...(opts.target?.settle === undefined ? {} : { settleConfig: opts.target.settle }),
-                    ...(opts.target?.hangs === undefined ? {} : { hangConfig: opts.target.hangs }),
-                },
-            });
-            hang = hangFinding(h.signal, run.transcript, h.recordingStepIndex, reproduction);
-        }
-        // #150 — a declared mission spend budget crossed (or a paid action was refused before crossing
-        // it): a clean, deliberate stop, never `crashed` — but never `clean` either (the run's own work
-        // past the stop is unproven), so it maps to `inconclusive` the same as `run.stop === "inconclusive"`.
-        const loopOutcome = run.stop === "crashed"
-            ? "crashed"
-            : run.stop === "inconclusive" || run.stop === "budget"
-                ? "inconclusive"
-                : run.stop === "hang"
-                    ? hangOutcome(hang?.reproduction.status ?? "inconclusive")
-                    : "clean";
-        // #209: a review whose job was never completed (the loop gave up, ran out of budget, or its
-        // `done` was never verified) did not see what a user who finished it would: its silence about
-        // the rest proves nothing, so it is `inconclusive` (`job-incomplete`) — never `clean`, whatever
-        // the advisory UX findings say.
-        const jobIncomplete = loopOutcome === "clean" && run.outcome.status === "incomplete"
-            ? { kind: "job-incomplete", message: `the job under review was not completed: ${run.outcome.reason}` }
-            : undefined;
-        // #225: with success checks, THEY decide whether the job was done — folded exactly like a goal
-        // run's ending (a failed check `defects-found`, a vacuous one `inconclusive`, all held `clean`).
-        const checked = adjudication === undefined ? undefined : foldGoalOutcome(adjudication.outcome);
-        const jobVerdict = loopOutcome !== "clean" ? loopOutcome : checked !== undefined ? checked : jobIncomplete === undefined ? "clean" : "inconclusive";
-        // #225/#209: a failed success check is named as such (never "job-incomplete"), as on a goal run.
-        const failedChecks = adjudication?.checks.filter((c) => !c.passed) ?? [];
-        const checkFailure = adjudication?.failure ??
-            (failedChecks.length === 0
-                ? undefined
-                : { kind: "success-check-failed", message: `success check ${failedChecks.map((c) => `'${c.check}' ${c.detail}`).join("; ")}` });
-        const jobFailure = loopOutcome !== "clean" ? undefined : checked === undefined ? jobIncomplete : checked === "clean" ? undefined : (checkFailure ?? jobIncomplete);
-        // #203: most steps on a starved host → `inconclusive` (degraded-environment), never `clean`.
-        // #213: a job whose completion code verified (#225: its success checks held, or its done was
-        // adjudicated from save signals) is a positive proof — a starved host does not undo it. Only an
-        // unverified ending is downgraded, and it keeps its own reason (a failed check) in the degraded one.
-        // A model-only `grounded-judgment` is not code's proof, so it is still downgraded.
-        const jobVerified = jobVerdict === "clean" &&
-            (checked === "clean" || (checked === undefined && run.outcome.status === "completed" && run.outcome.verifiedBy !== "grounded-judgment"));
-        const host = await finishHostHealth(health, jobVerdict, {
-            verified: jobVerified,
-            ...(run.failure === undefined ? {} : { failure: run.failure }),
-            ...(jobFailure === undefined ? {} : { wouldHaveBeen: jobFailure.message }),
-        });
-        const runOutcome = host.outcome;
-        // #245: every context closed (videos finalized) before the result naming them is written.
-        const shotFields = await runCapture.finish();
-        const videos = await finalizeVideos(videoDir, closeSession);
-        const base = {
-            schemaVersion: MISSION_RESULT_SCHEMA_VERSION,
-            strategy: "usability",
-            target: {
-                seedUrl: start.persistUrl,
-                allowlist: [...opts.allowlist],
-                ...(opts.storageState !== undefined ? { storageStatePath: resolvePath(opts.storageState) } : {}),
-            },
-            ...branchFields(start),
-            recordingPaths: [journal.recordingPath],
-            ...videos,
-            ...shotFields,
-            resultPath: resultPathFor(journal.recordingPath),
-            hangs: hang === undefined ? [] : [hang],
-            timing: run.timing,
-            stop: run.stop,
-            outcome: run.outcome,
-            ...(run.answer === undefined ? {} : { answer: run.answer }),
-            screensObserved: collected.length,
-            transcriptPath: journal.transcriptPath,
-            screenshotDir,
-            evidencePath: evidenceWritten,
-            screenshots: capture.screenshots(),
-            sideEffects: run.sideEffects,
-            ...(run.sideEffectsTruncated === undefined ? {} : { sideEffectsTruncated: run.sideEffectsTruncated }),
-            ...(run.safetyOverrides === undefined ? {} : { safetyOverrides: run.safetyOverrides }),
-            ...(run.actionDeltas === undefined ? {} : { actionDeltas: run.actionDeltas }),
-            engine: currentEngineInfo(),
-            ...(() => {
-                const f = failureWithHostStarved(host, run.failure ?? host.failure ?? jobFailure);
-                return f === undefined ? {} : { failure: f };
-            })(),
-            ...(run.crash === undefined ? {} : { crash: run.crash }),
-            finalUrl: run.finalUrl,
-            decisions: run.decisions,
-            actions: run.actions,
-            depth: run.depth,
-            ...(runUsage === undefined ? {} : { usage: runUsage.snapshot() }),
-            ...(hang === undefined ? {} : { hang }),
-            // #142 follow-up: reported but never gates `missionOutcome`/`exitCode` — a UX finding is
-            // always advisory, and a `server-log` defect here is treated the same way. So is an HTTP 5xx
-            // hard-signal defect (#208): listed with its fingerprint (verify-fix replays it), advisory here.
-            ...serverLogResult(serverLogRun),
-            ...defectFields([
-                ...http5xx.defects(run.transcript, run.recording.pages.flatMap((p) => p.steps)[0]?.step.kind === "navigate" ? 1 : 0).map((d) => ({ ...d, advisory: true })),
-                ...advisoryDefects(serverLogRun?.defects),
-            ]),
-            ...(budget === null ? {} : { budget: budget.trajectory() }),
-            ...(adjudication === undefined
-                ? {}
-                : {
-                    goalOutcome: adjudication.outcome,
-                    checks: adjudication.checks,
-                    ...(adjudication.warnings === undefined ? {} : { checkWarnings: adjudication.warnings }),
-                }),
-            ...host.fields,
-        };
-        if (outcome.kind === "failed") {
-            // The analysis is the review's product: without it the review is inconclusive (never a
-            // fabricated clean report) — but the run's transcript is kept, and this is a typed result.
-            const why = new UxAnalysisFailedError(outcome.reason, outcome.screenId, outcome.rubricItemId).message;
-            const missionOutcome = runOutcome === "clean" ? "inconclusive" : runOutcome;
-            const unavailable = {
-                ...base,
-                report: null,
-                reportPath: null,
-                missionOutcome,
-                exitCode: missionExitCode(missionOutcome),
-                analysisUnavailable: why,
-            };
-            // Persisted like every other mission's typed result, so MCP `get_mission_result` can read it (#117).
-            return await withRunEvidence({ ...unavailable, resultPath: writeMissionResult(journal.recordingPath, missionOutcome, unavailable.exitCode, unavailable, runUsage) }, evidenceOf(opts, secrets), triageOf(opts, serverLogRun, secrets));
-        }
-        const report = buildReport(groundFindings(withSignalFindings(outcome, signalFindings), friction), {
-            minConfidence,
-            quality,
-            maxFindingsPerRoute,
-            ...(product.facts === undefined ? { evidenceCaveats: [NO_PRODUCT_FACTS_CAVEAT] } : {}),
-            calibrationCaveats: [calibrationCaveat(opts.appContext.appClass), claimsCaveat()],
-        });
-        await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
-        const reviewed = { ...base, report, reportPath, missionOutcome: runOutcome, exitCode: missionExitCode(runOutcome) };
-        return await withRunEvidence({ ...reviewed, resultPath: writeMissionResult(journal.recordingPath, runOutcome, reviewed.exitCode, reviewed, runUsage) }, evidenceOf(opts, secrets), triageOf(opts, serverLogRun, secrets));
+        const loop = await runUsabilityLoop(ctx);
+        const analysis = await analyzeUsabilityRun(ctx, loop);
+        const hang = await reproduceUsabilityHang(ctx, loop.run);
+        const verdict = await adjudicateUsabilityJob(ctx, loop, hang);
+        return await writeUsabilityResult(ctx, loop, analysis, hang, verdict);
     }
     finally {
-        capture.detach();
-        disarmKillSwitch();
-        health.stop();
-        // Safety net: if the mission threw before `serverLog.finish()` ran, close sources immediately
-        // (no drain wait) rather than leaving them open until process exit.
-        await serverLog?.abort();
-        // #159: reaches this even when the mission above threw — the context is still open here.
-        await closeSession();
+        await tearDownUsabilityMission(ctx);
     }
 }
 //# sourceMappingURL=ux-usability.js.map