@jevitate/cli 0.2.0 → 0.4.0

package/dist/explore-cli.js

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 import { envCredentialStore, MissingCredentialError } from "@jevitate/ai-core";
 import { loadLocalCredentials } from "./credentials-file.js";
-import { FixtureNotFoundError, ScopeUnderivableError, UnauthorizedExploreTargetError, resolveCoverageThresholds, parseSecretField, SecretFieldSpecError, validateDenyPatterns, } from "@jevitate/explore";
+import { FixtureNotFoundError, ScopeUnderivableError, UnauthorizedExploreTargetError, resolveCoverageThresholds, parseSecretField, SecretFieldSpecError, TypeFixtureSpecError, validateDenyPatterns, } from "@jevitate/explore";
+import { loadTypeFixtures } from "./type-fixture-file.js";
 import { ok, fail } from "./envelope.js";
 import { SessionFileInProjectError, assertSessionFileOutsideProject } from "./project-dir.js";
 import { InvariantsFileError, loadInvariantFiles, resolveInvariantAuthTokens } from "./invariants-file.js";
@@ -10,8 +11,8 @@ import { fileDraftsWithEvidence } from "./defect-evidence.js";
 import { parseScreenshotsArg } from "./run-screenshots.js";
 import { GitHubIssueFiler } from "./github-issue-filer.js";
 import { TargetConfigError, loadTargetsFile, resolveTargetConfig } from "./target-config.js";
-import { buildMissionFixtures, checkSetupRefs, checkUrlRefOrigin, invariantSetupTexts, substituteSpecSetupRefs, fixtureSetupFailedResult, withFixtureFlags, } from "./fixture-cli.js";
-import { FixtureSetupError, FixtureSpecError, SETUP_REF, UnboundSetupRefError, substituteSetupRefs, } from "./mission-fixtures.js";
+import { buildMissionFixtures, checkSetupRefs, checkUrlRefOrigin, substituteUrlSetupRefs, setupRefFreeUrl, invariantSetupTexts, substituteSpecSetupRefs, fixtureSetupFailedResult, withFixtureFlags, } from "./fixture-cli.js";
+import { FixtureSetupError, FixtureSpecError, UnboundSetupRefError, substituteSetupRefs, } from "./mission-fixtures.js";
 import { LITERAL_SECRET_WARNING, SecretArgError, resolveSecretArgs } from "./secret-args.js";
 import { withEngine } from "./engine.js";
 import { setKillSwitchOutput } from "./kill-signal.js";
@@ -20,31 +21,63 @@ import { intArg, positiveNumberArg, nonNegativeIntArg, positiveIntArg, ratioArg
 import { formatMissionHuman, formatMultiRunHuman } from "./cli-output.js";
 import { runExploration, runCoverageMission, runAdversarialCliMission, CLI_ADVERSARIAL_STRATEGIES, runFeatureCliMission, parseSuccessSpec, resolveExploreAllowlist, } from "./explore-api.js";
 import { parseLogSourceSpecs, LogSourceSpecError } from "./log-sources.js";
-import { parseLogDefectSpecs, parseLogIgnoreSpecs } from "./log-correlation.js";
+import { triagedServerLog } from "./explore-shared.js";
+import { parseLogDefectSpecs, parseLogIgnoreSpecs, parseLogScopeSpecs } from "./log-correlation.js";
+import { parseCorrelationHeaders, parseLogIdPatterns } from "./log-trace.js";
 import { LogSpecError } from "./log-lines.js";
 import { MultiRunArgsError, resolveMultiRunPlan, wantsMultiRun } from "./multi-run.js";
 import { MultiRunAbortedError, runExploreMultiRun } from "./multi-run-cli.js";
 import { checkActorsAgainstSpec, resolveMissionActors } from "./mission-actors.js";
 import { runUsabilityMission, UsabilityInvariantsUnsupportedError } from "./ux-api.js";
 import { UxConfigError } from "./ux-config.js";
-import { MinConfidenceError, QualityPolicyError, MaxFindingsPerRouteError } from "@jevitate/ux";
-import { withBrowserLaunchFlags, withDemoFlags, withScreenshotsFlag, browserRunFromFlags, withEmulationFlags, emulationFromFlags, emitCommandResult, stallTimeoutMs, EXPLORE_STRATEGIES, EXPLORE_OUTCOME_HELP, GatewaySelectionError, buildExploreGateways, } from "./cli-shared.js";
-import { multiWindowWarning } from "./browser-run-options.js";
+import { MinConfidenceError, QualityPolicyError, MaxFindingsPerRouteError, ProductFactsError } from "@jevitate/ux";
+import { withBrowserLaunchFlags, withDemoFlags, withScreenshotsFlag, browserRunFromFlags, withEmulationFlags, emulationFromFlags, emitCommandResult, collectParam, environmentSeams, resolveDbPath, resolveJourneysDir, resolveMissionTargetsDir, stallTimeoutMs, EXPLORE_STRATEGIES, EXPLORE_OUTCOME_HELP, GatewaySelectionError, buildExploreGateways, } from "./cli-shared.js";
+import { allowWithExtensions, assertExtensionTargetLoaded, multiWindowWarning } from "./browser-run-options.js";
+import { ParamValidationError } from "@jevitate/journey";
+import { SiteGateRefusedError } from "@jevitate/runtime";
+import { JourneyRequiresAuthError, UnknownJourneyError } from "./journey-api.js";
+import { environmentFromFlags, isEnvironmentError, withEnvironmentFlags } from "./environments.js";
+import { resolve as resolvePath } from "node:path";
+import { CAMPAIGN_LIMITS, isSweepMode } from "@jevitate/journey";
+import { CampaignSpecError, runCampaign, validateCampaignSpec } from "./campaign-api.js";
+import { formatCampaignHuman } from "./campaign-cli.js";
+import { forwardedArgv } from "./multi-run-cli.js";
+import { ANCHORED_STRATEGIES, JourneyPrefixArgsError, JourneyPrefixStaleError, journeyStaleResult, resolveJourneyPrefix, } from "./journey-prefix.js";
+import { clock } from "@jevitate/domain";
+/**
+ * #293: the flags a sweep sets on each of its missions itself (the rest of the command line is
+ * forwarded to every mission as given).
+ */
+const SWEEP_OWNED = new Set([
+    "fromJourney", "atStep", "strategy", "journeysDir", "param", "env", "baseUrl", "storageState", "maxActions", "maxDecisions",
+    "goal", "success", "appClass", "real", "fakeAi", "fixtures", "before", "after", "allowShellHooks", "hookTimeoutMs",
+]);
 /**
  * Registers `jevitate explore` (every strategy: goal, coverage, exploratory, adversarial, usability, feature, multi-run).
  * `buildProgram` builds a fresh program for each run of a multi-run (#141/#143).
  */
 export function registerExploreCommands(program, deps, buildProgram) {
-    withScreenshotsFlag(withEmulationFlags(withFixtureFlags(withDemoFlags(withBrowserLaunchFlags(program
+    withEnvironmentFlags(withScreenshotsFlag(withEmulationFlags(withFixtureFlags(withDemoFlags(withBrowserLaunchFlags(program
         .command("explore")
-        .description("goal-directed exploration -> a deterministic Recording (authoring/test plane)")), { recordVideo: true, overlay: true }))))
+        .description("goal-directed exploration -> a deterministic Recording (authoring/test plane)")), { recordVideo: true, overlay: true })))))
         .option("--url <url>", "target URL (must be an authorized origin)")
+        .option("--from-journey <id>", "journey-anchored exploration (#293): start from a PROMOTED Journey instead of --url — its first --at-step steps are replayed " +
+        "in the mission's own browser context (page, form contents and session kept; fail-closed, never self-healed; --env/--base-url apply), " +
+        "then the mission starts on the live page. A replay that stops before the anchor ends the run inconclusive (failure.kind journey-stale, exit 2). " +
+        "Strategies: goal, coverage, exploratory, adversarial, usability")
+        .option("--at-step <n|name|all|anchors>", "with --from-journey: the step to branch off — a 1-based top-level step number or an anchor name (`jevitate journey anchors <id>`); " +
+        "`all` sweeps every step and `anchors` every anchor: each a fresh session (restored by --fixtures), --max-actions/--max-decisions split evenly per stop, one deduped report")
+        .option("--param <kv>", "with --from-journey: a Journey param as key=value (repeatable); only the prefix's own params are required", collectParam, {})
+        .option("--journeys-dir <path>", "with --from-journey: the journeys directory (default: the repo's .jevitate/journeys; outside a repo ~/.jevitate/journeys)")
         .option("--strategy <name>", "exploration strategy: goal (default) | coverage | exploratory | adversarial | usability (UX review: ranked, cited findings)", "goal")
         .option("--goal <text>", "natural-language goal / job (required for --strategy goal and usability)")
         .option("--app-class <class>", "app class for UX calibration (required for --strategy usability), e.g. consumer|admin|internal")
         .option("--show <labels>", "opt-in filter on the quality grade (comma list of actionable,relevant-minor,generic,wrong); others are suppressed and counted; default JEVITATE_UX_SHOW, then ~/.jevitate/config.json ux.show, then ALL grades — the grader is uncalibrated (#133), so by default every finding is shown with its grade")
         .option("--min-confidence <n>", "(--strategy usability) findings below this FINDING confidence (0..1, a finding's own violation/applicability/grounding score — NOT its quality-grade confidence, a separate independent-grader number shown as finding.quality.confidence) are suppressed and counted in report.suppressed; default JEVITATE_UX_MIN_CONFIDENCE, then ~/.jevitate/config.json ux.minConfidence, then 0.3")
         .option("--max-findings-per-page <n>", "(--strategy usability) cap on UX findings per route/page, highest-confidence first; the rest are counted in report.suppressed as per-page-cap, never dropped silently; default JEVITATE_UX_MAX_FINDINGS_PER_PAGE, then ~/.jevitate/config.json ux.maxFindingsPerPage, then 5")
+        .option("--product <file>", "(--strategy usability) product facts JSON (plans/prices, key journeys, each page's intended next step) the review checks screens against in code; default .jevitate/product.json in the project when present (docs/ux-findings.md)")
+        .option("--probe-guards", "(--strategy usability) opt in to clicking each destructive control once to check for a confirmation step — fail-safe: every write and destructive-looking request is aborted, and a page with an open WebSocket/EventSource or a service worker is not probed; without it those claims are reported unverifiable (docs/ux-findings.md)")
+        .option("--polish", "(--strategy usability) polish each verified UX finding's recommendation with one generation call (opt-in; the default prose is built from templates)")
         .option("--success <spec>", [
         "independent success check (repeatable; every one must hold; --strategy goal and usability). Kinds:",
         "urlIncludes:<text> | visible:<d> | textIncludes:<d>|<text> (case-insensitive) | count:<d>|min=<n>,max=<n>",
@@ -64,6 +97,9 @@ export function registerExploreCommands(program, deps, buildProgram) {
         .option("--success-when <when>", "when the --success page checks must hold: final (default; on the final page) | held (on the final page, or all together at any settled step — a one-time secret, a toast). reloadThen is always final")
         .option("--allow-vacuous-checks", "downgrade a vacuous --success check to a warning. By default a check satisfied before the run's first action — a page check that held on the seed page and never changed " +
         "(an empty result container), a requestMade/responseStatus matched only by a page-load or polling request — FAILS: it cannot verify the goal")
+        .option("--action-deltas", "opt-in (#303; every --strategy, not --feature): record what each action changed on the page — an accessibility snapshot before and after, announcements, " +
+        "the action's requests — redacted, with a code verdict per step (no-change | relevant-change | inconclusive) used by the goal loop's no-progress check and a persistence re-check after writes (goal), and as defect evidence (adversarial, coverage); " +
+        "adds `delta` to every transcript step (and Recording step, goal) and `actionDeltas` to the result. Costs about 50-100 ms per action on a small page, 0.3-0.5 s on a large one")
         .option("--feature <name>", "run the capability-scoped feature-testing mission (instead of --goal/--success)")
         .option("--route <glob>", "in-scope route glob (repeatable), e.g. /thread/** — for --feature it replaces the default scope (the start URL's route and everything under it); it widens --strategy adversarial/coverage/exploratory beyond the start URL's route", (v, prev) => [...prev, v], [])
         .option("--scope <mode>", "--strategy coverage/exploratory: 'app' widens containment to the whole app (same as --route '/**'); default: the start URL's route plus --route globs")
@@ -71,6 +107,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
         .option("--secret <value|env:VAR>", "REDACTION ONLY: a secret/PII value kept out of every model call and artifact (repeatable); env:VAR reads it from the environment (preferred: a literal is visible in the process list and shell history). It is never typed into a field — to log in, bind it with --secret-field (or start from --storage-state)", (v, prev) => [...prev, v], [])
         .option("--secret-field <binding>", "goal/usability strategy: '<label|testId|type|id|name>=<value>=env:<VAR>' (repeatable), e.g. 'label=Password=env:APP_PASSWORD'. When the run types into a matching field, code types $VAR itself; the model sees only «secret:VAR» and the Recording {redacted:true}", (v, prev) => [...prev, v], [])
         .option("--totp <binding>", "goal/usability strategy: '<descriptor>=env:<VAR>' with $VAR a base32 TOTP seed (repeatable), e.g. 'label=Authentication code=env:APP_TOTP_SEED'. The 6-digit code is computed locally (RFC 6238) when the field is typed; the seed never reaches a model or disk", (v, prev) => [...prev, v], [])
+        .option("--type-fixture <binding>", "goal strategy: '<label|testId|type|id|name>=<value>=<file>' (repeatable), e.g. 'label=Paste your text=./fixtures/import.txt'. When the run types into a matching field, code types the file's exact text verbatim (line breaks kept, never paraphrased or capped); the model sees only «fixture:<file name>». Recorded as typed unless it holds a --secret", (v, prev) => [...prev, v], [])
         .option("--fixture <path>", "local file the upload op attaches to a file input (goal and usability strategies); must exist")
         .option("--storage-state <file>", "Playwright storageState JSON to start the session authenticated (deterministic login pre-step); must exist")
         .option("--actor <name=storageState>", "multi-actor mission (#147, goal only; repeatable): the FIRST actor is the primary (the only one the model drives, " +
@@ -91,7 +128,9 @@ export function registerExploreCommands(program, deps, buildProgram) {
         .option("--reply-ceiling-ms <ms>", "conversational pages: hard ceiling on one reply wait, however busy the page stays (default 180000; never below --reply-wait-ms)", positiveIntArg)
         .option("--reply-max-chars <n>", "conversational pages: cap on each generated chat message (goal and usability; default 300)", intArg({ min: 20, max: 2000 }))
         .option("--job-wait-ms <ms>", "goal and usability: while the page shows an in-progress status (\"Simulating…\", aria-busy, a job \"is running\"), " +
-        "waits keep waiting with backoff — and a model 'blocked' is deferred — up to this budget (default: --reply-ceiling-ms, 180000)", positiveIntArg)
+        "waits keep waiting with backoff — and a model 'blocked' is deferred — up to this budget (default: --reply-ceiling-ms, 180000); " +
+        "it also bounds a busy indicator the app visibly keeps working behind (live progress, a job poll) before it is a hang, " +
+        "and a wait the page documents (\"usually takes a minute\") can raise it", positiveIntArg)
         .option("--deny <pattern>", "a control no mission may click (repeatable): an accessible-name regex (/Archive/i or Archive) or a descriptor role=button;name=Archive. " +
         "Session-ending (Sign out), destructive (Delete, Revoke, Rotate) and paid (Buy, Run simulation, Generate, Send invite) controls are refused by default", (v, prev) => [...prev, v], [])
         .option("--paid <pattern>", "an app control that costs money or credits (repeatable; same syntax as --deny), e.g. /^(Analyze|Draft|Improve)\\b/i: treated like the built-in paid " +
@@ -124,15 +163,21 @@ export function registerExploreCommands(program, deps, buildProgram) {
         .option("--log-defect <level|/regex/>", "backend log lines matching this (repeatable) become a server-log defect: a level (error|warn|info|debug, matched as level>=this) or a /regex/flags/ over the raw line. Its fingerprint is the normalized message (ids/numbers/uuids/timestamps stripped) plus the correlated route; verify-fix re-checks it by re-tailing the same --log-source(s)", (v, prev) => [...prev, v], [])
         .option("--log-quiet-ok <spec>", "declares a --log-source spec (exact match, repeatable) as legitimately quiet: zero lines from it does not make the --log-defect oracle unhealthy (#169). Without it, a declared source that opened but delivered not one line makes an otherwise-clean run inconclusive, same as one that failed to open", (v, prev) => [...prev, v], [])
         .option("--log-ignore <regex|substring>", "excludes known-noise backend log lines (repeatable, /regex/flags/ over the raw line or a plain substring) from BOTH correlation and the --log-defect oracle (#169 item 3) — e.g. a periodic background job's own expected error. Counted separately as serverLogs.ignoredLines; never makes --log-quiet-ok unnecessary, since an ignored line still proves the source is being tailed", (v, prev) => [...prev, v], [])
+        .option("--log-scope <regex|substring>", "attributes only backend log lines matching this (repeatable, /regex/flags/ or a plain substring, e.g. a tenant id) to the run (#282); the rest count as serverLogs.ignoredLines. For concurrent runs tailing one log. A line carrying one of the run's own correlation ids is in scope", (v, prev) => [...prev, v], [])
+        .option("--log-correlation-header <name>", "another request/response header that carries a correlation id (repeatable; built in: traceparent, x-request-id, x-correlation-id, request-id, x-amzn-trace-id, x-b3-traceid, x-cloud-trace-context). A log line carrying a request's id is attached to that exact request and the step that sent it, not by time (#204)", (v, prev) => [...prev, v], [])
+        .option("--log-id-pattern </regex/>", "how a correlation id is written in your log lines, when not as trace_id=/request_id=/correlation_id= or a traceparent (repeatable; the first capture group is the id). Once ids correlate, a line with another request's id is never attributed to the run (#204)", (v, prev) => [...prev, v], [])
+        .option("--log-triage", "#313: record the run's whole signal timeline (backend lines at every level, the browser's console, page errors, failed requests) to <run>.signals.jsonl, " +
+        "and attach to each defect only the lines that relate to it (defects[].relatedLogs): code keeps the lines correlated to its request and prefilters its step's window, " +
+        "then, with --real, Jev scores each remaining line's relevance (log text goes to the judgment model, redacted — operator opt-in, never an MCP argument). Needs --log-source")
         .option("--server-log-drain-ms <ms>", "how long to keep tailing --log-source after the run's last action, to catch async backend work that settles after the browser gave up (default 3000)", nonNegativeIntArg)
         .option("--repeat <n>", "run the mission N times, one after another, each in a fresh browser context, and vote (#141): findings seen in fewer than --min-agreement runs are reported as flaky, not counted")
         .option("--min-agreement <k>", "with --repeat: runs a finding (and the outcome) must recur in to count (default: a majority of N)")
         .option("--persona <name=storageState>", "run the same mission once per persona (repeatable), serially, each from its own storageState, and diff them (#143): requests, statuses (a 403 vs 200 is a candidate RBAC finding), controls, outcome", (v, prev) => [...prev, v], [])
         .option("--personas <file>", "personas JSON: {\"<name>\": \"<storageState>\"} or {\"personas\": [{\"name\", \"storageState\"}]}")
-        .option("--check-overflow", "check the horizontal-overflow hard signal (#149) even at a desktop (>=1024px) viewport — --strategy coverage/exploratory " +
+        .option("--check-overflow", "check the horizontal-overflow (#149) and vertical-clipping (#302: text cut off by a fixed-height box or above the page top) hard signals even at a desktop (>=1024px) viewport — --strategy coverage/exploratory " +
         "(a defect), adversarial (a defect) or usability (a signal finding). " +
         "On by default whenever --viewport/--device emulates a viewport narrower than 1024px")
-        .option("--ignore-overflow <selector>", "a CSS selector (repeatable) whose overflow is intentional — excluded from the horizontal-overflow signal, like --ignore-no-progress", (v, prev) => [...prev, v], [])
+        .option("--ignore-overflow <selector>", "a CSS selector (repeatable) whose overflow or clipping is intentional — excluded from the horizontal-overflow and vertical-clipping signals, like --ignore-no-progress", (v, prev) => [...prev, v], [])
         .option("--evidence-video", "per defect: replay its minimal repro with captions + the failing step marked, record a masked clip and before/at screenshots (defects[].evidence; linked from drafts)")
         .option("--json", "emit the JSON envelope (default: a human summary)")
         .addHelpText("after", [
@@ -178,12 +223,153 @@ export function registerExploreCommands(program, deps, buildProgram) {
             }
         }
         const strategy = o.strategy ?? "goal";
+        // #293 journey-anchored exploration: the Journey, step, params and environment are resolved (and
+        // refused, exit 64) before anything else — the start URL every later check uses is where the
+        // Journey's prefix lands.
+        let journeyPrefix;
+        const anchoredFlags = [o.fromJourney, o.atStep, o.journeysDir, o.env, o.baseUrl].some((v) => v !== undefined);
+        if (anchoredFlags || Object.keys(o.param).length > 0) {
+            const refuse = (message) => emitExplore(fail("E_EXPLORE_ARGS", message));
+            if (o.fromJourney === undefined || o.atStep === undefined) {
+                refuse("--from-journey and --at-step go together (and --param, --env, --base-url and --journeys-dir need them)");
+                return;
+            }
+            if (o.url !== undefined) {
+                refuse("--url cannot be combined with --from-journey: the mission starts where the Journey's prefix leaves the page");
+                return;
+            }
+            if (o.feature !== undefined || !ANCHORED_STRATEGIES.includes(strategy)) {
+                refuse(`--from-journey supports --strategy ${ANCHORED_STRATEGIES.join(", ")} (not --feature)`);
+                return;
+            }
+            if (wantsMultiRun(o) || o.actor.length > 0) {
+                refuse("--from-journey runs one anchored mission: --repeat, --persona, --personas and --actor are not supported with it (a campaign runs several)");
+                return;
+            }
+            // #293 sweep: `--at-step all|anchors` runs the strategy from EVERY step (or anchor), each in a
+            // fresh session with --fixtures restored around it, --max-actions/--max-decisions split evenly
+            // over the stop points, and reads them as one deduped report (a one-job campaign).
+            // #312: one anchored step with a state restore (--fixtures/--before/--after) on a non-goal
+            // strategy runs the same way — as a one-stop campaign, whose runner restores around the run.
+            const restoredSingle = !isSweepMode(o.atStep) && strategy !== "goal" && (o.fixtures !== undefined || o.before !== undefined || o.after !== undefined);
+            if (isSweepMode(o.atStep) || restoredSingle) {
+                if (o.real !== true && o.fakeAi !== true) {
+                    emitExplore(fail("E_AI_SETUP_REQUIRED", "a sweep's missions are model-driven: pass --real or --fake-ai"));
+                    return;
+                }
+                const journeysDir = resolveJourneysDir(deps, o.journeysDir);
+                const abs = (p) => resolvePath(p);
+                const spec = {
+                    version: 1,
+                    name: restoredSingle ? `${o.fromJourney} at step ${o.atStep.trim()} (${strategy}, restored)` : `sweep of ${o.fromJourney} (${o.atStep}, ${strategy})`,
+                    ...(o.env === undefined ? {} : { env: o.env }),
+                    ...(o.baseUrl === undefined ? {} : { baseUrl: o.baseUrl }),
+                    ...(o.storageState === undefined ? {} : { storageState: abs(o.storageState) }),
+                    ...(o.fixtures === undefined ? {} : { fixtures: abs(o.fixtures) }),
+                    ...(o.before === undefined ? {} : { before: o.before }),
+                    ...(o.after === undefined ? {} : { after: o.after }),
+                    discovery: false,
+                    maxRuns: CAMPAIGN_LIMITS.maxRuns,
+                    jobs: [
+                        {
+                            id: "sweep",
+                            journey: o.fromJourney,
+                            params: o.param,
+                            anchors: restoredSingle ? [o.atStep.trim()] : o.atStep.trim(),
+                            strategies: [strategy],
+                            ...(o.goal === undefined ? {} : { goal: o.goal }),
+                            ...(o.appClass === undefined ? {} : { appClass: o.appClass }),
+                            ...(o.success.length === 0 ? {} : { success: o.success }),
+                            ...(o.maxActions === undefined ? {} : { maxActions: Number(o.maxActions) }),
+                            ...(o.maxDecisions === undefined ? {} : { maxDecisions: Number(o.maxDecisions) }),
+                        },
+                    ],
+                };
+                try {
+                    const plan = await validateCampaignSpec(spec, resolvePath("explore-sweep.json"), {
+                        journeysDir,
+                        allowShellHooks: o.allowShellHooks === true,
+                        ...(o.hookTimeoutMs === undefined ? {} : { hookTimeoutMs: Number(o.hookTimeoutMs) }),
+                        environmentSeams: environmentSeams(deps),
+                    });
+                    const result = await runCampaign(plan, {
+                        newProgram: () => buildProgram(deps),
+                        journeysDir,
+                        missionTargetsDir: resolveMissionTargetsDir(deps),
+                        ...(o.out === undefined ? {} : { outDir: o.out }),
+                        ...(o.real === true ? { real: true } : {}),
+                        ...(o.fakeAi === true ? { fakeAi: true } : {}),
+                        missionArgs: forwardedArgv(this, SWEEP_OWNED),
+                    });
+                    emitExplore(ok(withEngine({ sweep: { journeyId: o.fromJourney, mode: restoredSingle ? "step" : o.atStep.trim(), ...(restoredSingle ? { atStep: o.atStep.trim() } : {}), strategy, stops: plan.totalRuns, budgetPerStop: { maxActions: plan.jobs[0]?.maxActions, ...(plan.jobs[0]?.maxDecisions === undefined ? {} : { maxDecisions: plan.jobs[0].maxDecisions }) } }, ...result })), result.exitCode, formatCampaignHuman);
+                }
+                catch (err) {
+                    if (err instanceof CampaignSpecError)
+                        emitExplore(fail("E_EXPLORE_ARGS", err.message));
+                    else
+                        emitExplore(fail("E_EXPLORE_RUN", String(err instanceof Error ? err.message : err)));
+                }
+                return;
+            }
+            try {
+                const environment = environmentFromFlags({ ...(o.env === undefined ? {} : { env: o.env }), ...(o.baseUrl === undefined ? {} : { baseUrl: o.baseUrl }) }, environmentSeams(deps));
+                // The environment's own session applies when --storage-state names none (as `journey run`).
+                if (o.storageState === undefined && environment?.storageState !== undefined)
+                    o.storageState = environment.storageState;
+                journeyPrefix = await resolveJourneyPrefix({
+                    dir: resolveJourneysDir(deps, o.journeysDir),
+                    id: o.fromJourney,
+                    atStep: o.atStep,
+                    params: o.param,
+                    ...(environment === undefined ? {} : { environment }),
+                    ...(o.storageState === undefined ? {} : { storageState: o.storageState }),
+                    dbPath: resolveDbPath(deps),
+                    environmentFlags: { ...(o.env === undefined ? {} : { env: o.env }), ...(o.baseUrl === undefined ? {} : { baseUrl: o.baseUrl }) },
+                });
+            }
+            catch (err) {
+                if (isEnvironmentError(err) || err instanceof JourneyPrefixArgsError)
+                    emitExplore(fail(err.code, err.message));
+                else if (err instanceof UnknownJourneyError)
+                    emitExplore(fail("E_UNKNOWN_JOURNEY", err.message));
+                else if (err instanceof ParamValidationError)
+                    emitExplore(fail("E_INVALID_PARAMS", err.message));
+                else if (err instanceof JourneyRequiresAuthError)
+                    emitExplore(fail("E_JOURNEY_REQUIRES_AUTH", err.message));
+                else
+                    emitExplore(fail("E_EXPLORE_ARGS", err instanceof Error ? err.message : String(err)));
+                return;
+            }
+            // The prefix types its secret params into the page the mission perceives: they are redacted like
+            // --secret. Coverage/exploratory carry no redaction set, so a prefix with secrets refuses them.
+            if (journeyPrefix.secrets.length > 0 && (strategy === "coverage" || strategy === "exploratory")) {
+                refuse(`journey '${o.fromJourney}' types a secret param before step ${journeyPrefix.branch.step}: --strategy ${strategy} cannot redact it — use goal, adversarial or usability`);
+                return;
+            }
+            o.url = journeyPrefix.startUrl;
+            // Default allowlist: the origins the Journey's steps may be on (the environment's), not just the landing's.
+            if (o.allow.length === 0)
+                o.allow = [...journeyPrefix.allowedOrigins];
+        }
+        const withPrefix = journeyPrefix === undefined ? {} : { journeyPrefix };
+        /** #293: a prefix that no longer replays, or a site policy that refused it — typed, handled once for every strategy. */
+        const emitJourneyFailure = (err) => {
+            if (err instanceof JourneyPrefixStaleError) {
+                emitExplore(ok(withEngine(journeyStaleResult(err, strategy))), EXIT_CODES.inconclusive);
+                return true;
+            }
+            if (err instanceof SiteGateRefusedError) {
+                emitExplore(fail(err.code, err.message));
+                return true;
+            }
+            return false;
+        };
         // #195: `--secret env:VAR` is resolved from the environment before anything runs (fail closed).
         try {
             const resolved = resolveSecretArgs(o.secret, process.env, "--secret");
             if (resolved.literals > 0)
                 program.configureOutput().writeErr?.(LITERAL_SECRET_WARNING);
-            o.secret = resolved.secrets;
+            o.secret = [...resolved.secrets, ...(journeyPrefix?.secrets ?? [])];
         }
         catch (err) {
             if (!(err instanceof SecretArgError))
@@ -196,6 +382,9 @@ export function registerExploreCommands(program, deps, buildProgram) {
         let browser;
         try {
             browser = browserRunFromFlags(o, deps.explore?.env ?? process.env);
+            // #256: a chrome-extension:// --url must be a loaded extension's; loaded extensions' origins are allowed.
+            assertExtensionTargetLoaded(o.url, browser);
+            o.allow = allowWithExtensions(o.url, o.allow, browser);
         }
         catch (err) {
             emitExplore(fail("E_EXPLORE_ARGS", err instanceof Error ? err.message : String(err)));
@@ -261,12 +450,9 @@ export function registerExploreCommands(program, deps, buildProgram) {
             emitExplore(fail("E_EXPLORE_ARGS", "--job-wait-ms must be a positive integer"));
             return;
         }
-        // #154: refused BEFORE any browser opens. 0 is valid: "don't replay" — a hang is then
+        // #154: refused BEFORE any browser opens — `nonNegativeIntArg` already rejects a bad value at
+        // parse time (#275: the value is a number here). 0 is valid: "don't replay" — a hang is then
         // reported unconfirmed (inconclusive), never replayed and never a crash.
-        if (o.hangReplays !== undefined && !/^\d+$/.test(o.hangReplays.trim())) {
-            emitExplore(fail("E_EXPLORE_ARGS", `--hang-replays must be a non-negative integer (0 = don't replay; the hang is reported unconfirmed), got "${o.hangReplays}"`));
-            return;
-        }
         try {
             validateDenyPatterns(o.deny);
             validateDenyPatterns(o.paid, "--paid");
@@ -293,7 +479,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
                     ...(o.fileIssues === undefined ? {} : { fileIssues: o.fileIssues }),
                     ...(o.issueRepo === undefined ? {} : { issueRepo: o.issueRepo }),
                     ...(o.jevitateRepo === undefined ? {} : { jevitateRepo: o.jevitateRepo }),
-                }, new URL(o.url).origin);
+                }, new URL(setupRefFreeUrl(o.url)).origin);
             }
             catch (err) {
                 if (err instanceof FilingConfigError) {
@@ -309,7 +495,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
         let target;
         if (o.url !== undefined) {
             try {
-                target = resolveTargetConfig(loadTargetsFile(deps.explore?.targetsConfigPath), new URL(o.url).origin, {
+                target = resolveTargetConfig(loadTargetsFile(deps.explore?.targetsConfigPath), new URL(setupRefFreeUrl(o.url)).origin, {
                     settleIgnore: o.settleIgnore,
                     ignoreNoProgress: o.ignoreNoProgress,
                     apiPrefixes: o.apiPrefix,
@@ -343,7 +529,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
                 return result;
             let out = result;
             if (filing?.enabled === true)
-                out = await fileDraftsWithEvidence(out, filing, issueFiler, new Date().toISOString());
+                out = await fileDraftsWithEvidence(out, filing, issueFiler, clock.nowIso());
             return out;
         };
         // `--fixture` feeds the upload op, which only the explore loop (goal and
@@ -353,6 +539,11 @@ export function registerExploreCommands(program, deps, buildProgram) {
             emitExplore(fail("E_EXPLORE_ARGS", "--fixture is supported only with --strategy goal or usability"));
             return;
         }
+        // #198: product facts and polish shape the UX review's findings only.
+        if ((o.product !== undefined || o.polish === true || o.probeGuards === true) && (o.feature !== undefined || strategy !== "usability")) {
+            emitExplore(fail("E_EXPLORE_ARGS", "--product, --polish and --probe-guards are supported only with --strategy usability"));
+            return;
+        }
         // #225: success checks judge a goal / a usability job — every other strategy (and --feature) would
         // silently ignore them, so they are refused up front, never dropped.
         if ((o.success.length > 0 || o.successWhen !== undefined || o.allowVacuousChecks === true) &&
@@ -360,6 +551,12 @@ export function registerExploreCommands(program, deps, buildProgram) {
             emitExplore(fail("E_EXPLORE_ARGS", `--success, --success-when and --allow-vacuous-checks are supported only with --strategy goal or usability (not ${o.feature !== undefined ? "--feature" : `--strategy ${strategy}`})`));
             return;
         }
+        // #303: action deltas are recorded by the goal loop (goal and usability runs) only — refused
+        // elsewhere, never silently ignored.
+        if (o.actionDeltas === true && o.feature !== undefined) {
+            emitExplore(fail("E_EXPLORE_ARGS", "--action-deltas is not supported with --feature (goal, usability, coverage, exploratory and adversarial runs record deltas)"));
+            return;
+        }
         if (o.storageState !== undefined && !existsSync(o.storageState)) {
             emitExplore(fail("E_EXPLORE_ARGS", `storage state not found: ${o.storageState}`));
             return;
@@ -436,12 +633,18 @@ export function registerExploreCommands(program, deps, buildProgram) {
                 const sources = parseLogSourceSpecs(o.logSource, o.allowLogCmd ?? false);
                 const logDefect = parseLogDefectSpecs(o.logDefect);
                 const logIgnore = parseLogIgnoreSpecs(o.logIgnore);
+                const logScope = parseLogScopeSpecs(o.logScope);
+                const correlationHeaders = parseCorrelationHeaders(o.logCorrelationHeader);
+                const idPatterns = parseLogIdPatterns(o.logIdPattern);
                 serverLog = {
                     sources,
                     logDefect,
                     allowLogCmd: o.allowLogCmd ?? false,
                     quietOk: o.logQuietOk,
                     logIgnore,
+                    logScope,
+                    correlationHeaders,
+                    idPatterns,
                     ...(o.serverLogDrainMs === undefined ? {} : { drainMs: Number(o.serverLogDrainMs) }),
                 };
             }
@@ -453,6 +656,13 @@ export function registerExploreCommands(program, deps, buildProgram) {
                 throw err;
             }
         }
+        if (o.logTriage === true) {
+            if (serverLog === undefined) {
+                emitExplore(fail("E_EXPLORE_ARGS", "--log-triage triages the run's backend and browser signals: it needs at least one --log-source"));
+                return;
+            }
+            serverLog = { ...serverLog, triage: {} };
+        }
         const withServerLog = serverLog === undefined ? {} : { serverLog };
         // Secret field bindings (#72): resolved from the environment here, typed by code in the goal loop.
         let secretFields = [];
@@ -474,10 +684,27 @@ export function registerExploreCommands(program, deps, buildProgram) {
                 return;
             }
         }
+        // #281: fields typed with a file's exact text — read (and checked) before any browser opens.
+        let typeFixtures = [];
+        if (o.typeFixture.length > 0) {
+            if (o.feature !== undefined || strategy !== "goal") {
+                emitExplore(fail("E_EXPLORE_ARGS", "--type-fixture is supported only with --strategy goal"));
+                return;
+            }
+            try {
+                typeFixtures = loadTypeFixtures(o.typeFixture);
+            }
+            catch (err) {
+                if (!(err instanceof TypeFixtureSpecError))
+                    throw err;
+                emitExplore(fail(err.code, err.message));
+                return;
+            }
+        }
         // Mission fixtures (#140/#144) run around the goal loop and its replays only.
         const fixtureFlagsGiven = o.fixtures !== undefined || o.before !== undefined || o.after !== undefined;
         if (fixtureFlagsGiven && (o.feature !== undefined || strategy !== "goal")) {
-            emitExplore(fail("E_EXPLORE_ARGS", "--fixtures, --before and --after are supported only with --strategy goal"));
+            emitExplore(fail("E_EXPLORE_ARGS", "--fixtures, --before and --after are supported only with --strategy goal, or with --from-journey (any anchored strategy)"));
             return;
         }
         // Additive coverage/exploratory strategy: proof-by-induction state coverage.
@@ -527,6 +754,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
             try {
                 const result = await runCoverageMission({
                     ...(target === undefined ? {} : { target }),
+                    ...(o.actionDeltas === true ? { actionDeltas: true } : {}),
                     url: o.url,
                     allowlist: covAllowlist,
                     judge: covJudge,
@@ -545,12 +773,15 @@ export function registerExploreCommands(program, deps, buildProgram) {
                     ...(o.storageState !== undefined ? { storageState: o.storageState } : {}),
                     ...(o.saveStorageState !== undefined ? { saveStorageState: o.saveStorageState } : {}),
                     ...withInvariants,
-                    ...withServerLog,
+                    ...triagedServerLog(serverLog, covJudge, o.real === true),
+                    ...withPrefix,
                 });
                 // Typed verdict → exit code (0 clean · 1 defects · 2 crashed; see exit-codes.ts).
                 emitExplore(ok(await withEvidence(result)), result.exitCode);
             }
             catch (err) {
+                if (emitJourneyFailure(err))
+                    return;
                 if (err instanceof UnauthorizedExploreTargetError) {
                     emitExplore(fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
                 }
@@ -610,6 +841,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
             try {
                 const result = await runAdversarialCliMission({
                     ...(target === undefined ? {} : { target }),
+                    ...(o.actionDeltas === true ? { actionDeltas: true } : {}),
                     seedUrl: o.url,
                     allowlist: advAllowlist,
                     usage: advUsage,
@@ -619,7 +851,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
                     secrets: o.secret.length > 0 ? o.secret : undefined,
                     ...(runFiling === undefined ? {} : { filing: runFiling }),
                     issueFiler,
-                    ...(o.hangReplays === undefined ? {} : { hangReplays: Number(o.hangReplays) }),
+                    ...(o.hangReplays === undefined ? {} : { hangReplays: o.hangReplays }),
                     strategies: CLI_ADVERSARIAL_STRATEGIES,
                     judgment: advJudge,
                     generation: advGen,
@@ -632,13 +864,16 @@ export function registerExploreCommands(program, deps, buildProgram) {
                     ...(o.storageState !== undefined ? { storageState: o.storageState } : {}),
                     ...(o.saveStorageState !== undefined ? { saveStorageState: o.saveStorageState } : {}),
                     ...withInvariants,
-                    ...withServerLog,
+                    ...triagedServerLog(serverLog, advJudge, o.real === true),
+                    ...withPrefix,
                 });
                 // The typed verdict gates CI: 0 clean · 1 defects found (a failing check) · 2 the run
                 // itself broke (inconclusive/crashed) — see exit-codes.ts.
                 emitExplore(ok(await withEvidence(result)), result.exitCode);
             }
             catch (err) {
+                if (emitJourneyFailure(err))
+                    return;
                 if (err instanceof UnauthorizedExploreTargetError) {
                     emitExplore(fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
                 }
@@ -720,6 +955,9 @@ export function registerExploreCommands(program, deps, buildProgram) {
                     ...(o.minConfidence !== undefined ? { minConfidence: o.minConfidence } : {}),
                     ...(o.show !== undefined ? { show: o.show } : {}),
                     ...(o.maxFindingsPerPage !== undefined ? { maxFindingsPerRoute: o.maxFindingsPerPage } : {}),
+                    ...(o.product !== undefined ? { product: o.product } : {}),
+                    ...(o.polish === true ? { polish: true } : {}),
+                    ...(o.probeGuards === true ? { probeGuards: true } : {}),
                     bounds: Object.keys(uxBounds).length > 0 ? uxBounds : undefined,
                     conversation,
                     secrets: o.secret.length > 0 ? o.secret : undefined,
@@ -733,17 +971,21 @@ export function registerExploreCommands(program, deps, buildProgram) {
                     overflow,
                     ...(o.storageState !== undefined ? { storageState: o.storageState } : {}),
                     ...(o.saveStorageState !== undefined ? { saveStorageState: o.saveStorageState } : {}),
-                    ...withServerLog,
+                    ...triagedServerLog(serverLog, uxJudge, o.real === true),
                     ...withInvariants,
                     ...(uxSuccessChecks.length === 0 ? {} : { successChecks: uxSuccessChecks }),
                     ...(o.successWhen === "held" || o.successWhen === "final" ? { successWhen: o.successWhen } : {}),
                     ...(o.allowVacuousChecks === true ? { allowVacuousChecks: true } : {}),
+                    ...withPrefix,
+                    ...(o.actionDeltas === true ? { actionDeltas: true } : {}),
                 });
                 // UX findings are advisory (0); a failed --success check (#225) is 1, as on a goal run; a
                 // broken run or an unavailable analysis is 2.
                 emitExplore(ok(await withEvidence(result)), result.exitCode);
             }
             catch (err) {
+                if (emitJourneyFailure(err))
+                    return;
                 if (err instanceof UnauthorizedExploreTargetError) {
                     emitExplore(fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
                 }
@@ -760,6 +1002,9 @@ export function registerExploreCommands(program, deps, buildProgram) {
                 else if (err instanceof UsabilityInvariantsUnsupportedError) {
                     emitExplore(fail("E_EXPLORE_ARGS", err.message));
                 }
+                else if (err instanceof ProductFactsError) {
+                    emitExplore(fail(err.code, err.message));
+                }
                 else {
                     emitExplore(fail("E_EXPLORE_RUN", String(err instanceof Error ? err.message : err)));
                 }
@@ -840,7 +1085,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
             return;
         }
         const successWhen = o.successWhen === "held" || o.successWhen === "final" ? o.successWhen : undefined;
-        const allowlist = resolveExploreAllowlist(o.url, o.allow);
+        const allowlist = resolveExploreAllowlist(setupRefFreeUrl(o.url), o.allow);
         // Fixtures (#140/#144): the spec and every ${setup.x} reference are validated here, before any
         // browser or request; the setup itself runs just before the mission (below).
         let fx;
@@ -848,11 +1093,12 @@ export function registerExploreCommands(program, deps, buildProgram) {
             checkUrlRefOrigin(o.url);
             fx = buildMissionFixtures(o, {
                 allowlist,
-                baseUrl: o.url.replace(SETUP_REF, "0"),
+                baseUrl: setupRefFreeUrl(o.url),
                 ...(primaryStorageState === undefined ? {} : { storageState: primaryStorageState }),
                 secretFields,
                 secrets: o.secret,
                 ...(target?.fixtures === undefined ? {} : { targetFixtures: target.fixtures }),
+                ...(target?.personas === undefined ? {} : { personas: target.personas }),
             });
             checkSetupRefs({ "--url": o.url, "--goal": o.goal, "--success": o.success, ...invariantSetupTexts(invariants) }, fx);
         }
@@ -891,7 +1137,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
             try {
                 await fx.setup();
                 const b = fx.bindings();
-                url = substituteSetupRefs(o.url, b, { where: "--url" });
+                url = substituteUrlSetupRefs(o.url, b);
                 goal = substituteSetupRefs(o.goal, b, { where: "--goal" });
                 successChecks = o.success.map((spec) => parseSuccessSpec(substituteSetupRefs(spec, b, { where: "--success" })));
                 // #187: ${setup.x} in the invariants (probe paths, deniedAs.open, capture routes), origin-fixed.
@@ -916,6 +1162,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
                 successChecks,
                 ...(successWhen === undefined ? {} : { successWhen }),
                 ...(o.allowVacuousChecks === true ? { allowVacuousChecks: true } : {}),
+                ...(o.actionDeltas === true ? { actionDeltas: true } : {}),
                 allowlist,
                 judge,
                 gen,
@@ -923,6 +1170,7 @@ export function registerExploreCommands(program, deps, buildProgram) {
                 bounds: Object.keys(bounds).length > 0 ? bounds : undefined,
                 secrets: o.secret.length > 0 ? o.secret : undefined,
                 ...(secretFields.length > 0 ? { secretFields } : {}),
+                ...(typeFixtures.length > 0 ? { typeFixtures } : {}),
                 fixture: o.fixture,
                 outDir: o.out,
                 browserPortFactory: deps.explore?.browserPortFactory,
@@ -934,16 +1182,19 @@ export function registerExploreCommands(program, deps, buildProgram) {
                 ...(actors === null ? {} : { actors }),
                 ...(runFiling === undefined ? {} : { filing: runFiling }),
                 issueFiler,
-                ...(o.hangReplays === undefined ? {} : { hangReplays: Number(o.hangReplays) }),
+                ...(o.hangReplays === undefined ? {} : { hangReplays: o.hangReplays }),
                 conversation,
                 ...runInvariants,
-                ...withServerLog,
+                ...triagedServerLog(serverLog, judge, o.real === true),
                 ...(fx === undefined ? {} : { fixtures: fx }),
+                ...withPrefix,
             });
             // 0 succeeded · 1 assertion not met · 2 the run broke (inconclusive/crashed).
             emitExplore(ok(await withEvidence(result)), result.exitCode);
         }
         catch (err) {
+            if (emitJourneyFailure(err))
+                return;
             if (err instanceof UnauthorizedExploreTargetError) {
                 emitExplore(fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
             }