@jevitate/cli 0.6.0 → 0.8.0

package/dist/jev-advisor.js

@@ -0,0 +1,172 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { contentHash } from "@jevitate/domain";
+import { JevJudgmentGateway, JevProviderError, MissingCredentialError, RetryingJudgmentPort, UsageTracker, envCredentialStore, jevProviderOverride, realJevClientCall, resolveJevRoute, } from "@jevitate/ai-core";
+import { GatewaySelectionError, keyPreflightOpts } from "./cli-shared.js";
+import { loadLocalCredentials } from "./credentials-file.js";
+import { preflightRunKeys } from "./run-key-preflight.js";
+import { resolveUsagePricing } from "./usage-config.js";
+/**
+ * #434/#435 — the advisory Jev layer of the review sheets and the pre-approval pipeline: one
+ * `JudgmentPort` (the existing judgment gateway, TypeSafe or OpenRouter key, #429) behind a cache
+ * keyed by the content hash of what is asked, plus the usage of every call actually made.
+ *
+ * Model use follows the CLI's `--real` convention: the layer runs only on a command given `--real`
+ * (review sheets, approvals, `catalog analyze`; MCP `real: true`). Unlike a run, a missing judgment
+ * key is not a refusal here — the deterministic layer stands on its own, so the sheet says
+ * "skipped: no judgment key". Without `--real` it says "skipped: pass --real".
+ *
+ * The cache (`<project>/.jevitate/cache/jev/<sha256>.json`, gitignored) holds ANSWERS only — a kind,
+ * a value, a probability — keyed by `sha256(state + questions)`. The state is built from catalog
+ * text (job stories, persona descriptions, a Journey's review-sheet lines, which never carry a
+ * secret value), and it is never written: nothing secret is cached. A re-review of unchanged
+ * content asks nothing new. An unreadable entry is a miss (it is re-asked and rewritten).
+ */
+/** Bumped when the questions' meaning changes in a way their text does not show. */
+export const JEV_CACHE_VERSION = 1;
+/** Why the Jev layer did not run. */
+export const JEV_SKIPPED_PASS_REAL = "pass --real to ask Jev (needs a judgment key)";
+export const JEV_SKIPPED_NO_KEY = "no judgment key — set TYPESAFE_API_KEY or OPENROUTER_API_KEY (jevitate ai setup)";
+function validAnswer(q, a) {
+    if (a === null || typeof a !== "object")
+        return false;
+    const o = a;
+    if (o.kind !== q.kind)
+        return false;
+    if (q.kind === "choice")
+        return typeof o.value === "string" && q.options.includes(o.value) && typeof o.confidence === "number" && Number.isFinite(o.confidence);
+    if (q.kind === "noul")
+        return typeof o.value === "boolean" && typeof o.probability === "number" && Number.isFinite(o.probability);
+    return typeof o.value === "number" && Number.isFinite(o.value);
+}
+function validAnswers(questions, answers) {
+    if (answers === null || typeof answers !== "object")
+        return false;
+    const rec = answers;
+    return Object.entries(questions).every(([name, q]) => validAnswer(q, rec[name]));
+}
+/** #434/#435: the judgment port behind a memory + on-disk answer cache, counting what it asks. */
+export class CachedJevAdvisor {
+    judge;
+    cacheDir;
+    usage;
+    #memory = new Map();
+    #asked = 0;
+    #cached = 0;
+    constructor(judge, 
+    /** The answer cache directory; null: memory only (outside a project). */
+    cacheDir, usage) {
+        this.judge = judge;
+        this.cacheDir = cacheDir;
+        this.usage = usage;
+    }
+    async ask(state, questions) {
+        const key = contentHash({ v: JEV_CACHE_VERSION, state, questions });
+        const hit = this.#memory.get(key) ?? (await this.#read(key, questions));
+        if (hit !== undefined) {
+            this.#memory.set(key, hit);
+            this.#cached += Object.keys(questions).length;
+            return { answers: hit, cached: true };
+        }
+        this.#asked += Object.keys(questions).length;
+        const answers = await this.judge.systemOne({ state, questions });
+        if (!validAnswers(questions, answers))
+            throw new Error("the judgment answers do not match the questions asked");
+        this.#memory.set(key, answers);
+        await this.#write(key, answers);
+        return { answers, cached: false };
+    }
+    layer() {
+        const usage = this.usage.snapshot();
+        const { priceSource, missing, ...counts } = usage;
+        return {
+            status: "ran",
+            asked: this.#asked,
+            cached: this.#cached,
+            ...(usage.judgments + usage.generations === 0
+                ? {}
+                : { usage: { ...counts, ...(priceSource === undefined ? {} : { priceSource: [...priceSource] }), ...(missing === undefined ? {} : { missing: [...missing] }) } }),
+        };
+    }
+    async #read(key, questions) {
+        if (this.cacheDir === null)
+            return undefined;
+        let raw;
+        try {
+            raw = await readFile(join(this.cacheDir, `${key}.json`), "utf8");
+        }
+        catch (err) {
+            if (typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT")
+                return undefined;
+            throw err;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return undefined; // a torn entry is a miss: re-asked and rewritten
+        }
+        const answers = parsed?.version === JEV_CACHE_VERSION ? parsed.answers : undefined;
+        return validAnswers(questions, answers) ? answers : undefined;
+    }
+    async #write(key, answers) {
+        if (this.cacheDir === null)
+            return;
+        await mkdir(this.cacheDir, { recursive: true, mode: 0o700 });
+        const file = join(this.cacheDir, `${key}.json`);
+        const tmp = `${file}.${process.pid}.tmp`;
+        await writeFile(tmp, `${JSON.stringify({ version: JEV_CACHE_VERSION, answers })}\n`, { mode: 0o600 });
+        await rename(tmp, file);
+    }
+}
+/** The answer cache directory of a project data dir (`<.jevitate>/cache/jev`), or null outside a project. */
+export function jevCacheDir(catalogDir) {
+    return catalogDir === null ? null : join(catalogDir, "cache", "jev");
+}
+/** The Jev layer's report when it did not run. */
+export function skippedLayer(reason) {
+    return { status: "skipped", reason, asked: 0, cached: 0 };
+}
+export function jevLayerOf(setup) {
+    if (setup === undefined)
+        return skippedLayer(JEV_SKIPPED_PASS_REAL);
+    return "advisor" in setup ? setup.advisor.layer() : skippedLayer(setup.skipped);
+}
+/**
+ * #434/#435: the Jev layer of one command. Without `--real`: skipped ("pass --real"). With it: an
+ * injected judge (tests) wins; else the live judgment gateway on the resolved Jev route
+ * (`--jev-provider`, else TypeSafe then OpenRouter) after the startup key check — or, when no
+ * judgment key is configured, skipped ("no judgment key"): the deterministic layer still runs.
+ * An unknown `--jev-provider` is refused (`GatewaySelectionError`), never ignored.
+ */
+export async function buildJevSetup(deps, opts) {
+    if (opts.real !== true)
+        return { skipped: JEV_SKIPPED_PASS_REAL };
+    const env = deps.explore?.env ?? process.env;
+    const usage = deps.explore?.usage ?? new UsageTracker(resolveUsagePricing(env));
+    if (deps.explore?.judge !== undefined)
+        return { advisor: new CachedJevAdvisor(deps.explore.judge, opts.cacheDir, usage) };
+    let provider;
+    try {
+        provider = jevProviderOverride(env, opts.jevProvider);
+    }
+    catch (err) {
+        if (err instanceof JevProviderError)
+            throw new GatewaySelectionError(err.message);
+        throw err;
+    }
+    const store = envCredentialStore(env, deps.explore?.localConfig ?? loadLocalCredentials());
+    try {
+        resolveJevRoute(store, provider);
+    }
+    catch (err) {
+        if (err instanceof MissingCredentialError)
+            return { skipped: JEV_SKIPPED_NO_KEY };
+        throw err;
+    }
+    await preflightRunKeys(["judgment"], store, { ...keyPreflightOpts(deps), ...(provider === undefined ? {} : { jevProvider: provider }) });
+    const judge = new RetryingJudgmentPort(new JevJudgmentGateway(store, await realJevClientCall(undefined, usage), provider));
+    return { advisor: new CachedJevAdvisor(judge, opts.cacheDir, usage) };
+}
+//# sourceMappingURL=jev-advisor.js.map

package/dist/jev-advisor.js.map

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

package/dist/journey-api.d.ts

@@ -1,14 +1,17 @@
-import { type Journey } from "@jevitate/journey";
+import { type Journey, type JourneyLintFinding } from "@jevitate/journey";
+import { type ApprovalConfirm } from "./approval-provenance.js";
+import type { JevSetup } from "./jev-advisor.js";
 import { type RunPolicy } from "@jevitate/domain";
 import { type BrowserPort, type BrowserSession, type EmulationSpec } from "@jevitate/playwright";
 import { type BrowserRunOptions } from "./browser-run-options.js";
 import { RecordingInterpreter, type StepObserver } from "@jevitate/interpreter";
-import { type ReplayDeltaSummary } from "@jevitate/explore";
+import { type BlockedWrite, type ReplayDeltaSummary } from "@jevitate/explore";
 import { SecretPixelMask } from "./demo-capture.js";
 import { type ScreenshotsResult, type ScreenshotsSpec } from "./run-screenshots.js";
 import { type JourneyRunResult, type SelfHealer, type SiteGateDeps } from "@jevitate/runtime";
 import { type FixtureRecord, type MissionFixtures } from "./mission-fixtures.js";
 import { type ResolvedJourneyEnvironment } from "./environments.js";
+import { type OutcomeCheckFailure } from "./journey-network-checks.js";
 /**
  * Distinct from `@jevitate/journey`'s `ParamValidationError` so CLI/API callers
  * can tell "no such journey" apart from "params didn't match the journey's
@@ -23,6 +26,25 @@ export declare class UnknownJourneyError extends Error {
  */
 export declare class JourneyRequiresAuthError extends Error {
 }
+/**
+ * #401: the Journey's assertions cannot prove its outcome (the `lintJourney` errors). `promote`
+ * refuses unless the reviewer accepts it with a non-empty `--accept-weak <reason>`.
+ */
+/** #432: `journey promote --reviewed-hash`: the Journey changed after the reviewer's sheet was produced. */
+export declare class StaleReviewError extends Error {
+    readonly code = "E_JOURNEY_REVIEW_STALE";
+}
+export declare class WeakJourneyError extends Error {
+    readonly findings: readonly JourneyLintFinding[];
+    constructor(message: string, findings?: readonly JourneyLintFinding[]);
+}
+/** #401: the assertion-strength lint's verdict for one Journey (`journey lint`). */
+export interface JourneyLintResult {
+    id: string;
+    findings: JourneyLintFinding[];
+    errors: number;
+    warnings: number;
+}
 export interface RunJourneyProgrammaticallyOptions {
     /** Directory a `FsJourneyStore` reads Journey JSON files from. */
     dir: string;
@@ -108,12 +130,55 @@ export interface RunJourneyProgrammaticallyOptions {
      */
     actionDeltas?: boolean;
 }
+/**
+ * #402: how a mutation-proof replay (`journey verify --mutate`) differs from `journey run` — a
+ * separate argument, never a surface option: no other caller passes it.
+ */
+export interface MutationReplayOptions {
+    /**
+     * #402 `journey verify --mutate`: replay a MUTATED copy of the Journey. Applied after params are
+     * validated against the stored Journey (a mutation may stop a step reading a param), and never to
+     * an anchored prefix. Indices must be kept: a mutation changes a step, never removes one.
+     */
+    mutateJourney?: (journey: Journey) => Journey;
+    /** #402: leave this flat step (0-based) out of the replay — `RecordingInterpreter`'s `skipStep`. */
+    skipStep?: (index: number) => boolean;
+    /**
+     * #402: ABORT the write requests (the #110 classifier, first-party only — `ReadOnlyGuard`) that
+     * start while this flat step (0-based) runs, until the network settles after it. Never answered,
+     * never sent; what was blocked comes back as `blockedWrites`.
+     */
+    blockWritesAtStep?: number;
+    /** #402: also return the outcome checks' structured failures (`outcomeFailures`). */
+    structuredFailures?: boolean;
+}
+/** #402: what a mutation-proof replay returns beyond `journey run`'s result. */
+export interface MutationReplayFields {
+    /** The step-request / end-state checks that failed (`structuredFailures`). */
+    outcomeFailures?: OutcomeCheckFailure[];
+    /** The writes aborted in `blockWritesAtStep`'s window. */
+    blockedWrites?: BlockedWrite[];
+}
+/**
+ * #246: a secret parameter's value (declared `secret: true`, or a credential-like name) never comes
+ * back in a run's output — the interpreter's vars start as the params, so the value is masked there.
+ */
+export declare function redactSecretParams<T>(result: T, journey: Journey, params: Record<string, string>): T;
+/** Every string in `result` (deeply) with each secret, in each of its URL forms, masked. */
+export declare function redactSecretValues<T>(result: T, secrets: readonly string[]): T;
 /**
  * #293: the params a Journey PREFIX runs with — a `--param` the whole Journey does not take is
  * refused (`ParamValidationError`), one only a later step uses is dropped; the prefix's own required
  * params are then checked by `validateParams` as usual.
  */
 export declare function prefixParams(full: Journey, prefix: Journey, params: Record<string, string>): Record<string, string>;
+/**
+ * #401: the assertion-strength lint (#401) for one Journey by id — an unknown id is refused,
+ * exactly as `journey run`/`promote` refuse one (`UnknownJourneyError`). Pure read; no browser.
+ */
+export declare function lintJourneyById(dir: string, id: string, opts?: {
+    readRequests?: readonly string[];
+}): Promise<JourneyLintResult>;
 /**
  * Promotes a local Journey (#124, mirrors `promoteMissionTarget` in
  * `mission-api.ts`) so it becomes discoverable via `journey find`/MCP
@@ -121,8 +186,40 @@ export declare function prefixParams(full: Journey, prefix: Journey, params: Rec
  * same as `mission target promote`. An unknown id is refused with
  * `UnknownJourneyError` (never silently created). Returns the persisted,
  * now-promoted Journey.
+ *
+ * #401: lints first — a Journey whose assertions cannot prove its outcome is refused
+ * (`WeakJourneyError`) unless the reviewer accepts it with a non-empty `--accept-weak <reason>`,
+ * which is recorded on the Journey (`metadata.acceptedWeak`). Warnings never block.
+ *
+ * #432: records the approval (`metadata.approval`: the review hash, when, the waiver) and keeps a
+ * snapshot of the approved Journey (`.approved/<id>.json`). Given `reviewedHash` (what the reviewer's
+ * sheet showed), a Journey that changed since is refused (`StaleReviewError`) before anything else.
+ *
+ * #433: then the catalog gate (`journeyCatalogGate`): a Journey linking a job/persona that is not
+ * approved is refused (`UnvettedLinksError`) unless `acceptUnvetted` (recorded in
+ * `approval.waivers`), and the shared pre-approval findings are acknowledged (`acceptFindings`,
+ * recorded in `approval.acceptedFindings`) — the same pipeline `persona|job approve` and
+ * `demo approve` use. `catalogDir` (default: the project's `.jevitate/`) holds personas/jobs.
  */
-export declare function promoteJourney(dir: string, id: string): Promise<Journey>;
+export interface PromoteJourneyOptions {
+    acceptWeak?: string;
+    reviewedHash?: string;
+    acceptUnvetted?: string;
+    acceptFindings?: string;
+    /** The catalog's directory; undefined: the project's `.jevitate/` (none outside a project). */
+    catalogDir?: string | null;
+    /** Which approval path asks (`demo approve` promotes through here too). */
+    action?: "journey promote" | "demo approve";
+    /** #434/#435: the advisory Jev layer of the pre-approval readiness and analysis (`--real`), or why it is skipped. */
+    jev?: JevSetup;
+    /**
+     * #437: confirms the approval (after every gate, before anything is written) and returns its
+     * provenance — the CLI's `makeApprovalConfirm` (a typed confirmation on a TTY, the escape hatch,
+     * or the MCP channel). Omitted: recorded as `non-interactive` (`programmaticProvenance`).
+     */
+    confirm?: ApprovalConfirm;
+}
+export declare function promoteJourney(dir: string, id: string, opts?: PromoteJourneyOptions): Promise<Journey>;
 /**
  * The one programmatic surface for "run this published Journey by id" —
  * used by BOTH the CLI `journey run` action and external callers. Builds
@@ -132,8 +229,10 @@ export declare function promoteJourney(dir: string, id: string): Promise<Journey
  * `ParamValidationError`, from `@jevitate/journey`) BEFORE any browser is
  * launched, then builds the real Actor + `JourneyRunner` and runs.
  */
-export declare function runJourneyProgrammatically(opts: RunJourneyProgrammaticallyOptions): Promise<JourneyRunResult & {
+export declare function runJourneyProgrammatically(opts: RunJourneyProgrammaticallyOptions, mutation?: MutationReplayOptions): Promise<JourneyRunResult & {
     fixtures?: FixtureRecord;
     videoPaths?: string[];
     actionDeltas?: ReplayDeltaSummary;
-} & Partial<ScreenshotsResult>>;
+} & Partial<ScreenshotsResult> & MutationReplayFields>;
+/** `err` with every secret (and its URL-encoded forms) masked in its message and stack — same object, same class. */
+export declare function redactErrorSecrets(err: unknown, secrets: readonly string[]): unknown;

package/dist/journey-api.js

@@ -1,4 +1,8 @@
-import { FsJourneyStore, JourneyRegistry, ParamValidationError, deriveParamSchema, describeStep, flatJourneySteps, journeyPrefix, secretParamValues, validateParams } from "@jevitate/journey";
+import { FsJourneyStore, JourneyRegistry, ParamValidationError, deriveParamSchema, describeStep, flatJourneySteps, journeyPrefix, lintJourney, secretParamValues, validateParams } from "@jevitate/journey";
+import { programmaticProvenance } from "./approval-provenance.js";
+import { journeyReviewHash } from "./journey-review.js";
+import { writeApprovedSnapshot } from "./journey-review-store.js";
+import { journeyCatalogGate, resolveCatalogDir } from "./catalog-api.js";
 import { redactText } from "@jevitate/ai-core";
 import { safeRunPolicy, clock } from "@jevitate/domain";
 import { join } from "node:path";
@@ -8,7 +12,8 @@ import { artifactStamp } from "./mission-journal.js";
 import { logsDirFor } from "./project-dir.js";
 import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
 import { RecordingInterpreter } from "@jevitate/interpreter";
-import { ReplayDeltas, replayDeltaSummary } from "@jevitate/explore";
+import { ReadOnlyGuard, ReplayDeltas, monitorFor, replayDeltaSummary } from "@jevitate/explore";
+import { writeClassifier } from "@jevitate/recording";
 import { BrowseTheWebToken } from "@jevitate/screenplay";
 import { SecretPixelMask, maskingPort } from "./demo-capture.js";
 import { RunScreenshots, composeObservers, screenshotObserver, screenshotsDirFor } from "./run-screenshots.js";
@@ -16,7 +21,7 @@ import { JourneyRunner } from "@jevitate/runtime";
 import { gateJourney } from "./site-gate-cli.js";
 import { substituteSetupRefs } from "./mission-fixtures.js";
 import { applyJourneyEnvironment } from "./environments.js";
-import { withNetworkChecks } from "./journey-network-checks.js";
+import { JourneyOutcomeChecks } from "./journey-network-checks.js";
 /**
  * Distinct from `@jevitate/journey`'s `ParamValidationError` so CLI/API callers
  * can tell "no such journey" apart from "params didn't match the journey's
@@ -31,12 +36,30 @@ export class UnknownJourneyError extends Error {
  */
 export class JourneyRequiresAuthError extends Error {
 }
+/**
+ * #401: the Journey's assertions cannot prove its outcome (the `lintJourney` errors). `promote`
+ * refuses unless the reviewer accepts it with a non-empty `--accept-weak <reason>`.
+ */
+/** #432: `journey promote --reviewed-hash`: the Journey changed after the reviewer's sheet was produced. */
+export class StaleReviewError extends Error {
+    code = "E_JOURNEY_REVIEW_STALE";
+}
+export class WeakJourneyError extends Error {
+    findings;
+    constructor(message, findings = []) {
+        super(message);
+        this.findings = findings;
+    }
+}
 /**
  * #246: a secret parameter's value (declared `secret: true`, or a credential-like name) never comes
  * back in a run's output — the interpreter's vars start as the params, so the value is masked there.
  */
-function redactSecretParams(result, journey, params) {
-    const secrets = secretParamValues(journey, params);
+export function redactSecretParams(result, journey, params) {
+    return redactSecretValues(result, secretParamValues(journey, params));
+}
+/** Every string in `result` (deeply) with each secret, in each of its URL forms, masked. */
+export function redactSecretValues(result, secrets) {
     if (secrets.length === 0)
         return result;
     const scrub = (v) => typeof v === "string"
@@ -62,23 +85,82 @@ export function prefixParams(full, prefix, params) {
     return Object.fromEntries(Object.entries(params).filter(([k]) => needed.includes(k)));
 }
 /**
- * Promotes a local Journey (#124, mirrors `promoteMissionTarget` in
- * `mission-api.ts`) so it becomes discoverable via `journey find`/MCP
- * `find_capabilities` and runnable via `run_journey` — a human-approval gate,
- * same as `mission target promote`. An unknown id is refused with
- * `UnknownJourneyError` (never silently created). Returns the persisted,
- * now-promoted Journey.
+ * #401: the assertion-strength lint (#401) for one Journey by id — an unknown id is refused,
+ * exactly as `journey run`/`promote` refuse one (`UnknownJourneyError`). Pure read; no browser.
  */
-export async function promoteJourney(dir, id) {
+export async function lintJourneyById(dir, id, opts = {}) {
+    const registry = new JourneyRegistry(new FsJourneyStore(dir));
+    const journey = await registry.get(id);
+    if (!journey) {
+        throw new UnknownJourneyError(`unknown journey '${id}'`);
+    }
+    const findings = lintJourney(journey, opts.readRequests === undefined ? {} : { readRequests: opts.readRequests });
+    return {
+        id,
+        findings,
+        errors: findings.filter((f) => f.level === "error").length,
+        warnings: findings.filter((f) => f.level === "warning").length,
+    };
+}
+export async function promoteJourney(dir, id, opts = {}) {
     const store = new FsJourneyStore(dir);
     const registry = new JourneyRegistry(store);
     const existing = await registry.get(id);
     if (!existing) {
         throw new UnknownJourneyError(`unknown journey '${id}'`);
     }
-    await registry.promote(id);
-    const promoted = await registry.get(id);
-    return promoted ?? { ...existing, metadata: { ...existing.metadata, promoted: true } };
+    // #432: approval binds to what the reviewer read — refused when the Journey changed since.
+    const contentHash = journeyReviewHash(existing);
+    if (opts.reviewedHash !== undefined && opts.reviewedHash.trim().toLowerCase() !== contentHash) {
+        throw new StaleReviewError(`journey '${id}' changed after its review sheet was produced (reviewed ${opts.reviewedHash.trim()}, now ${contentHash}) — review it again: jevitate journey review ${id}`);
+    }
+    const errors = lintJourney(existing).filter((f) => f.level === "error");
+    const reason = opts.acceptWeak?.trim() ?? "";
+    if (errors.length > 0 && reason === "") {
+        throw new WeakJourneyError([
+            `journey '${id}' has ${errors.length} assertion-strength error(s):`,
+            ...errors.map((f) => f.message),
+            "strengthen the Journey or pass --accept-weak <reason>",
+        ].join("\n"), errors);
+    }
+    const acceptedWeak = errors.length > 0 ? { reason, rules: [...new Set(errors.map((f) => f.rule))] } : undefined;
+    const gate = await journeyCatalogGate(existing, {
+        catalogDir: opts.catalogDir === undefined ? resolveCatalogDir(undefined) : opts.catalogDir,
+        journeysDir: dir,
+        action: opts.action ?? "journey promote",
+        ...(opts.acceptUnvetted === undefined ? {} : { acceptUnvetted: opts.acceptUnvetted }),
+        ...(opts.acceptFindings === undefined ? {} : { acceptFindings: opts.acceptFindings }),
+        ...(opts.jev === undefined ? {} : { jev: opts.jev }),
+    });
+    // #437: the person confirms the approval and each waiver given with it (or it is refused) — then it is recorded with how it was made.
+    const provenance = opts.confirm === undefined
+        ? programmaticProvenance()
+        : await opts.confirm({
+            kind: opts.action === "demo approve" ? "demo" : "journey",
+            id,
+            contentHash,
+            waivers: [
+                ...(acceptedWeak === undefined ? [] : [{ flag: "--accept-weak", reason: acceptedWeak.reason, detail: acceptedWeak.rules.join(", ") }]),
+                ...(gate.waivers ?? []).map((w) => ({ flag: "--accept-unvetted", reason: w.reason, detail: w.items.join(", ") })),
+                ...(gate.acceptedFindings === undefined ? [] : [{ flag: "--accept-findings", reason: gate.acceptedFindings.reason, detail: gate.acceptedFindings.findings.join(", ") }]),
+            ],
+        });
+    const approval = {
+        contentHash,
+        at: clock.nowIso(),
+        provenance,
+        ...(acceptedWeak === undefined ? {} : { acceptedWeak: { ...acceptedWeak, provenance } }),
+        ...(gate.waivers === undefined ? {} : { waivers: gate.waivers.map((w) => ({ ...w, provenance })) }),
+        ...(gate.acceptedFindings === undefined ? {} : { acceptedFindings: { ...gate.acceptedFindings, provenance } }),
+    };
+    const promoted = {
+        ...existing,
+        metadata: { ...existing.metadata, promoted: true, ...(acceptedWeak === undefined ? {} : { acceptedWeak }), approval },
+    };
+    await store.put(promoted);
+    // #432: the Journey as approved — the next review diffs against it ("change since last approval").
+    await writeApprovedSnapshot(dir, promoted);
+    return (await registry.get(id)) ?? promoted;
 }
 /**
  * The one programmatic surface for "run this published Journey by id" —
@@ -89,7 +171,7 @@ export async function promoteJourney(dir, id) {
  * `ParamValidationError`, from `@jevitate/journey`) BEFORE any browser is
  * launched, then builds the real Actor + `JourneyRunner` and runs.
  */
-export async function runJourneyProgrammatically(opts) {
+export async function runJourneyProgrammatically(opts, mutation = {}) {
     const store = new FsJourneyStore(opts.dir);
     const registry = new JourneyRegistry(store);
     const stored = await registry.get(opts.id);
@@ -113,6 +195,8 @@ export async function runJourneyProgrammatically(opts) {
     // the cost (or risk) of opening a browser.
     const inputParams = journey === full ? opts.params : prefixParams(full, journey, opts.params);
     validateParams(deriveParamSchema(journey.recording), inputParams);
+    // #402: the mutated copy replays (and is judged); the stored Journey still names, redacts and gates.
+    const replayed = mutation.mutateJourney === undefined || journey !== full ? journey : mutation.mutateJourney(journey);
     const policy = opts.policy ?? safeRunPolicy();
     // The site policy (`jevitate site policy set <origin>`): pacing, throttles, budgets, quiet hours —
     // decided before any fixture or browser; a refusal says why and when to retry.
@@ -169,33 +253,91 @@ export async function runJourneyProgrammatically(opts) {
         try {
             const actor = CastActor.named("cli-runner").whoCan(new BrowseTheWeb(session, allowedOrigins), ...gate.abilities);
             const replayDeltas = opts.actionDeltas === true ? new ReplayDeltas({ secrets, recorded: flat.map((f) => f.recorded) }) : undefined;
-            const observer = composeObservers(replayDeltas?.observer(), opts.observer, shots === undefined ? undefined : screenshotObserver(shots, (a) => a.ability(BrowseTheWebToken).session.page, whatOf));
-            const interpreter = opts.interpreter ?? (opts.observer === undefined && shots === undefined && replayDeltas === undefined ? new RecordingInterpreter() : new RecordingInterpreter({ observer }));
+            // #322/#400: a full replay (never an anchored prefix) must also satisfy the Journey's end state
+            // and each step's request expectations.
+            const outcomeChecks = new JourneyOutcomeChecks(session.page, journey === full ? replayed : undefined, { secrets });
+            const blocker = mutation.blockWritesAtStep === undefined ? undefined : await stepWriteBlocker(session.page, mutation.blockWritesAtStep, allowedOrigins);
+            const observer = composeObservers(outcomeChecks.observer(), blocker?.observer, replayDeltas?.observer(), opts.observer, shots === undefined ? undefined : screenshotObserver(shots, (a) => a.ability(BrowseTheWebToken).session.page, whatOf));
+            const skipStep = mutation.skipStep;
+            const interpreter = opts.interpreter ??
+                (opts.observer === undefined && shots === undefined && replayDeltas === undefined && outcomeChecks.observer() === undefined && blocker === undefined && skipStep === undefined
+                    ? new RecordingInterpreter()
+                    : new RecordingInterpreter({ observer, ...(skipStep === undefined ? {} : { skipStep: (i) => skipStep(i) }) }));
             const runner = new JourneyRunner(actor, interpreter, undefined, undefined, opts.selfHealer);
             let result;
             try {
-                // #322: a full replay (never an anchored prefix) must also satisfy the Journey's network checks.
-                const networkChecks = journey === full ? journey.metadata.networkChecks : undefined;
-                result = redactSecretParams(await withNetworkChecks(session.page, networkChecks, () => runner.run({ journey, params, policy })), journey, params);
+                result = redactSecretParams(await outcomeChecks.run(actor, () => runner.run({ journey: replayed, params, policy })), journey, params);
             }
             finally {
                 await gate.done();
+                await blocker?.guard.disarm();
             }
+            const mutationFields = {
+                ...(mutation.structuredFailures === true ? { outcomeFailures: redactSecretParams([...outcomeChecks.lastFailures], journey, params) } : {}),
+                ...(blocker === undefined ? {} : { blockedWrites: blocker.guard.drain() }),
+            };
             const shotFields = shots === undefined ? {} : await shots.finish();
             const deltaFields = replayDeltas === undefined ? {} : { actionDeltas: redactSecretParams(replayDeltaSummary(replayDeltas), journey, params) };
             // #245: the context closed (its video finalized) before the result naming it is returned.
             const videos = await finalizeVideos(videoDir, closeSession);
             if (fx === undefined)
-                return { ...result, ...videos, ...shotFields, ...deltaFields };
+                return { ...result, ...videos, ...shotFields, ...deltaFields, ...mutationFields };
             await fx.restore();
-            return { ...result, ...videos, ...shotFields, ...deltaFields, fixtures: fx.record() };
+            // #399: a fixture output passed in as a secret param (`--param t='${setup.t}'`) is redacted here too.
+            return { ...result, ...videos, ...shotFields, ...deltaFields, ...mutationFields, fixtures: redactSecretParams(fx.record(), journey, params) };
         }
         finally {
             await closeSession();
         }
     }
+    catch (err) {
+        // #399: an error escaping the run (a crash, a closed page) may echo a navigated URL that
+        // carried a secret parameter — its message and stack are redacted, its class kept.
+        throw redactErrorSecrets(err, secretParamValues(journey, { ...inputParams, ...params }));
+    }
     finally {
         await fx?.restore();
     }
 }
+/** How long one blocked step's window stays open for the writes its action triggers (network settle). */
+const BLOCK_WINDOW_SETTLE_MS = 5_000;
+/**
+ * #402 block-write: a `ReadOnlyGuard` armed on the page whose action window is ONLY the given step —
+ * opened as it begins, closed once the network settled after it. Every held write is aborted (a
+ * write navigation too: never answered with a status that could read as a success).
+ */
+async function stepWriteBlocker(page, index, allowedOrigins) {
+    const guard = new ReadOnlyGuard(writeClassifier({}), { allowlist: [...allowedOrigins], navigationWrites: "abort" });
+    await guard.arm(page);
+    const monitor = monitorFor(page);
+    await monitor.instrument();
+    return {
+        guard,
+        observer: {
+            beforeStep: async ({ index: i }) => {
+                if (i === index)
+                    guard.beginAction();
+            },
+            afterStep: async ({ index: i }) => {
+                if (i !== index)
+                    return;
+                try {
+                    await monitor.waitSettled({ ceilingMs: BLOCK_WINDOW_SETTLE_MS });
+                }
+                finally {
+                    guard.settled();
+                }
+            },
+        },
+    };
+}
+/** `err` with every secret (and its URL-encoded forms) masked in its message and stack — same object, same class. */
+export function redactErrorSecrets(err, secrets) {
+    if (!(err instanceof Error) || secrets.length === 0)
+        return err;
+    err.message = redactText(err.message, secrets);
+    if (err.stack !== undefined)
+        err.stack = redactText(err.stack, secrets);
+    return err;
+}
 //# sourceMappingURL=journey-api.js.map