@jevitate/cli 0.2.0 → 0.3.0

package/dist/log-trace.js

@@ -0,0 +1,210 @@
+import { redactUrl } from "@jevitate/ai-core";
+import { LogSpecError } from "./log-lines.js";
+import { clock } from "@jevitate/domain";
+/**
+ * Request ↔ backend-log correlation by TRACE / CORRELATION ID (#204), instead of by time window.
+ *
+ * The browser side (`RequestIdLedger`) records, for every request the run's page sends, the ids it
+ * carries: W3C `traceparent` (its trace-id), `x-request-id`, `x-correlation-id`, `request-id`,
+ * `x-amzn-trace-id` (its `Root`), `x-b3-traceid`, `x-cloud-trace-context` (its trace) — on the
+ * REQUEST (a frontend with OpenTelemetry) or the RESPONSE (a server-generated request id) — plus
+ * any operator-named header (`--log-correlation-header`). The log side (`lineIds`) finds those
+ * ids in a backend log line: any whitespace/punctuation-delimited token equal to a recorded id
+ * (exact — never a prefix or a substring of a longer token).
+ *
+ * `ServerLogRuntime` then attaches a line that carries a run's id to EXACTLY that request (method,
+ * URL, status) and to the step that sent it — whatever time the line landed — and falls back to the
+ * time window only for lines with no id. Once ids demonstrably correlate (at least one line matched
+ * a run's id), a line carrying a DIFFERENT id (`foreignIds`: a `trace_id=`/`request_id=` key, a
+ * `traceparent`, or an operator `--log-id-pattern`) belongs to other work — another user, a
+ * background job — and is never attributed to this run.
+ *
+ * Ids are not secrets, but every URL is redacted and every attached line is redacted with the run's
+ * secrets, as before.
+ */
+/** Headers whose value identifies a request across the browser and the backend (lower-case). */
+export const DEFAULT_CORRELATION_HEADERS = [
+    "traceparent",
+    "x-request-id",
+    "x-correlation-id",
+    "request-id",
+    "x-amzn-trace-id",
+    "x-b3-traceid",
+    "x-cloud-trace-context",
+];
+/** An id shorter than this would match unrelated tokens (a "1", a "200"): never used. */
+const MIN_ID_CHARS = 8;
+const MAX_ID_CHARS = 128;
+const ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const TRACEPARENT = /^[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/i;
+const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
+/** Most requests the ledger keeps (the oldest are dropped past it). */
+const MAX_REQUESTS = 5_000;
+/** Normalizes an id for comparison (hex trace ids are case-insensitive in practice). */
+const norm = (id) => id.toLowerCase();
+function usable(id) {
+    const v = id.trim();
+    if (v.length < MIN_ID_CHARS || v.length > MAX_ID_CHARS || !ID_SHAPE.test(v))
+        return null;
+    // An all-zero trace id is the W3C "invalid" value: it identifies nothing.
+    if (/^0+$/.test(v.replace(/[-:.]/g, "")))
+        return null;
+    return v;
+}
+/** The correlation id(s) a header value carries. */
+export function idsFromHeader(name, value) {
+    const n = name.toLowerCase();
+    const v = value.trim();
+    let candidates;
+    if (n === "traceparent") {
+        const m = TRACEPARENT.exec(v);
+        candidates = m === null ? [] : [m[1]];
+    }
+    else if (n === "x-amzn-trace-id") {
+        const root = /(?:^|;)\s*Root=([^;]+)/i.exec(v);
+        candidates = root === null ? [] : [root[1]];
+    }
+    else if (n === "x-cloud-trace-context") {
+        candidates = [v.split("/")[0] ?? ""];
+    }
+    else {
+        candidates = v.split(",").map((s) => s.trim());
+    }
+    return candidates.map(usable).filter((x) => x !== null);
+}
+/** Validates `--log-correlation-header` names (fails closed on the first bad one). */
+export function parseCorrelationHeaders(raw) {
+    return raw.map((h) => {
+        const v = h.trim().toLowerCase();
+        if (!HEADER_NAME.test(v))
+            throw new LogSpecError(`--log-correlation-header: not a header name: ${JSON.stringify(h)}`);
+        return v;
+    });
+}
+/**
+ * Parses `--log-id-pattern` values: `/regex/flags` whose first capture group (or whole match) is a
+ * correlation id in a log line of the operator's own format. Bounded and compiled once.
+ */
+export function parseLogIdPatterns(raw) {
+    return raw.map((p) => {
+        const m = /^\/(.+)\/([a-z]*)$/s.exec(p);
+        if (m === null)
+            throw new LogSpecError(`--log-id-pattern must be /regex/flags, got ${JSON.stringify(p)}`);
+        if (m[1].length > 500)
+            throw new LogSpecError("--log-id-pattern is too long (max 500 chars)");
+        try {
+            const flags = m[2].replace(/[gy]/g, "");
+            return new RegExp(m[1], `${flags}g`);
+        }
+        catch (e) {
+            throw new LogSpecError(`--log-id-pattern: invalid regex ${JSON.stringify(p)}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+}
+/** Records every request a run's page sends with its correlation ids (#204). */
+export class RequestIdLedger {
+    #headers;
+    #now;
+    #byRequest = new WeakMap();
+    #byId = new Map();
+    #requests = [];
+    constructor(opts = {}) {
+        this.#headers = new Set([...DEFAULT_CORRELATION_HEADERS, ...(opts.headers ?? []).map((h) => h.toLowerCase())]);
+        this.#now = opts.now ?? clock.now;
+    }
+    /** Starts listening on a page (call before its first navigation). */
+    observe(page) {
+        page.on("request", (r) => {
+            let rec;
+            let headers;
+            try {
+                rec = { method: r.method().toUpperCase(), url: redactUrl(r.url()), status: null, startedAtMs: this.#now(), ids: [] };
+                headers = r.headers();
+            }
+            catch {
+                return; // a request whose page is already gone: nothing to correlate
+            }
+            this.#byRequest.set(r, rec);
+            this.#requests.push(rec);
+            if (this.#requests.length > MAX_REQUESTS) {
+                const old = this.#requests.shift();
+                for (const id of old?.ids ?? [])
+                    if (this.#byId.get(norm(id)) === old)
+                        this.#byId.delete(norm(id));
+            }
+            this.#addIds(rec, headers);
+        });
+        page.on("response", (res) => {
+            try {
+                const rec = this.#byRequest.get(res.request());
+                if (rec === undefined)
+                    return;
+                rec.status = res.status();
+                this.#addIds(rec, res.headers());
+            }
+            catch {
+                // a response whose page is already gone: nothing more to learn
+            }
+        });
+    }
+    #addIds(rec, headers) {
+        for (const [name, value] of Object.entries(headers)) {
+            if (!this.#headers.has(name.toLowerCase()))
+                continue;
+            for (const id of idsFromHeader(name, value)) {
+                if (rec.ids.includes(id))
+                    continue;
+                rec.ids.push(id);
+                // The same id on two requests (a trace spanning several calls): the first sender owns it.
+                if (!this.#byId.has(norm(id)))
+                    this.#byId.set(norm(id), rec);
+            }
+        }
+    }
+    /** How many requests carried at least one id. */
+    get requestsWithIds() {
+        return this.#requests.filter((r) => r.ids.length > 0).length;
+    }
+    /** The request a log line belongs to (by an id it carries), or undefined. */
+    requestFor(raw) {
+        if (this.#byId.size === 0)
+            return undefined;
+        for (const token of tokens(raw)) {
+            const hit = this.#byId.get(norm(token));
+            if (hit !== undefined)
+                return { request: hit, id: token };
+            const tp = TRACEPARENT.exec(token);
+            if (tp !== null) {
+                const t = this.#byId.get(norm(tp[1]));
+                if (t !== undefined)
+                    return { request: t, id: tp[1] };
+            }
+        }
+        return undefined;
+    }
+}
+/** The tokens of a log line an id can be (delimited by anything an id cannot contain). */
+function tokens(raw) {
+    return raw.split(/[^A-Za-z0-9._:-]+/).filter((t) => t.length >= MIN_ID_CHARS && t.length <= 200);
+}
+/** Built-in id keys: `trace_id=…`, `"traceId": "…"`, `request-id: …`, `correlationId=…`, `x-request-id=…`. */
+const KEYED_ID = /(?:^|[^A-Za-z0-9])(?:x-)?(?:trace|request|req|correlation|corr)[_.-]?id["']?\s*[:=]\s*["']?([A-Za-z0-9][A-Za-z0-9._:-]{7,127})/gi;
+const TRACEPARENT_IN_TEXT = /\b[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}\b/gi;
+/**
+ * The correlation ids a log line DECLARES (#204): a keyed id (`trace_id=`, `"requestId":`, …), a
+ * `traceparent`, or an operator `--log-id-pattern` match. Used to tell another request's line
+ * (foreign) from one with no id at all (time-window fallback).
+ */
+export function declaredIds(raw, patterns = []) {
+    const out = new Set();
+    for (const re of [KEYED_ID, TRACEPARENT_IN_TEXT, ...patterns]) {
+        re.lastIndex = 0;
+        for (const m of raw.matchAll(re)) {
+            const id = usable(m[1] ?? m[0]);
+            if (id !== null)
+                out.add(id);
+        }
+    }
+    return [...out];
+}
+//# sourceMappingURL=log-trace.js.map

package/dist/log-trace.js.map

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

package/dist/logs-retention.js

@@ -1,6 +1,7 @@
 import { readFileSync, readdirSync, rmSync, rmdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { resolveDataDir } from "./data-dir.js";
+import { clock } from "@jevitate/domain";
 export const DEFAULT_LOGS_RETENTION = { ttlDays: 14, keepLatest: 50 };
 export class LogsConfigError extends Error {
     code = "E_LOGS_CONFIG";
@@ -65,7 +66,7 @@ function runsIn(root) {
 }
 /** Applies `retention` to the logs under `root`. `dryRun` reports what would go, deleting nothing. */
 export function pruneLogs(root, retention, opts = {}) {
-    const nowMs = opts.nowMs ?? Date.now();
+    const nowMs = opts.nowMs ?? clock.now();
     const { runs, dateDirs } = runsIn(root);
     const newestFirst = [...runs].sort((a, b) => b.mtimeMs - a.mtimeMs);
     const cutoff = nowMs - retention.ttlDays * 86_400_000;

package/dist/logs-retention.js.map

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

package/dist/masked-input.d.ts

@@ -0,0 +1,22 @@
+/**
+ * #269 — masked key entry. The previous prompt muted readline's echo by hooking its private
+ * `_writeToOutput`, but readline's line refresh still moved the cursor and cleared the screen below
+ * it on every keystroke: the instructions printed before the prompt vanished as soon as the user
+ * typed ("flash off too fast to read"), and nothing showed that input was being received.
+ *
+ * This reader never clears anything: the instructions stay on their own line, and each typed (or
+ * pasted) character is echoed as `•` — never the character itself. Backspace erases one mark,
+ * Ctrl-U erases all, Enter finishes, Ctrl-C / Ctrl-D (on an empty entry) cancel. Without a TTY
+ * (piped input) it reads one line and echoes nothing. The value is only ever returned to the
+ * caller; it is never written to `output`.
+ */
+export declare const MASK_CHAR = "\u2022";
+export interface MaskedInput extends NodeJS.ReadableStream {
+    readonly isTTY?: boolean;
+    setRawMode?(mode: boolean): unknown;
+}
+/** Key entry was cancelled (Ctrl-C, Ctrl-D, or the input ended): nothing was entered. */
+export declare class KeyEntryCancelledError extends Error {
+    constructor();
+}
+export declare function readMaskedLine(input: MaskedInput, output: NodeJS.WritableStream, message: string): Promise<string>;

package/dist/masked-input.js

@@ -0,0 +1,99 @@
+/**
+ * #269 — masked key entry. The previous prompt muted readline's echo by hooking its private
+ * `_writeToOutput`, but readline's line refresh still moved the cursor and cleared the screen below
+ * it on every keystroke: the instructions printed before the prompt vanished as soon as the user
+ * typed ("flash off too fast to read"), and nothing showed that input was being received.
+ *
+ * This reader never clears anything: the instructions stay on their own line, and each typed (or
+ * pasted) character is echoed as `•` — never the character itself. Backspace erases one mark,
+ * Ctrl-U erases all, Enter finishes, Ctrl-C / Ctrl-D (on an empty entry) cancel. Without a TTY
+ * (piped input) it reads one line and echoes nothing. The value is only ever returned to the
+ * caller; it is never written to `output`.
+ */
+export const MASK_CHAR = "•";
+/** Key entry was cancelled (Ctrl-C, Ctrl-D, or the input ended): nothing was entered. */
+export class KeyEntryCancelledError extends Error {
+    constructor() {
+        super("key entry cancelled — nothing was stored");
+        this.name = "KeyEntryCancelledError";
+    }
+}
+export function readMaskedLine(input, output, message) {
+    const raw = input.isTTY === true && typeof input.setRawMode === "function";
+    output.write(`${message}\n> `);
+    return new Promise((resolve, reject) => {
+        let value = "";
+        let done = false;
+        const finish = (err) => {
+            if (done)
+                return;
+            done = true;
+            input.removeListener("data", onData);
+            input.removeListener("end", onEnd);
+            if (raw)
+                input.setRawMode?.(false);
+            input.pause();
+            output.write("\n");
+            if (err === null)
+                resolve(value);
+            else
+                reject(err);
+        };
+        const onEnd = () => {
+            // Piped input that ends without a newline still delivers what it held; an empty one is a cancel.
+            if (value.length > 0)
+                finish(null);
+            else
+                finish(new KeyEntryCancelledError());
+        };
+        const onData = (chunk) => {
+            const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            // An escape sequence (arrow keys, function keys) is navigation, never part of a key.
+            if (raw && text.startsWith("\u001b"))
+                return;
+            for (const ch of text) {
+                if (ch === "\r" || ch === "\n") {
+                    finish(null);
+                    return;
+                }
+                if (!raw) {
+                    value += ch;
+                    continue;
+                }
+                if (ch === "\u0003") {
+                    finish(new KeyEntryCancelledError());
+                    return;
+                }
+                if (ch === "\u0004") {
+                    if (value.length === 0)
+                        finish(new KeyEntryCancelledError());
+                    else
+                        finish(null);
+                    return;
+                }
+                if (ch === "\u007f" || ch === "\b") {
+                    if (value.length > 0) {
+                        value = [...value].slice(0, -1).join("");
+                        output.write("\b \b");
+                    }
+                    continue;
+                }
+                if (ch === "\u0015") {
+                    output.write("\b \b".repeat([...value].length));
+                    value = "";
+                    continue;
+                }
+                if (ch < " ")
+                    continue; // other control characters
+                value += ch;
+                output.write(MASK_CHAR);
+            }
+        };
+        if (raw)
+            input.setRawMode?.(true);
+        input.on("data", onData);
+        input.on("end", onEnd);
+        input.resume();
+    });
+}
+//# sourceMappingURL=masked-input.js.map

package/dist/masked-input.js.map

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

package/dist/mcp-api.d.ts

@@ -51,13 +51,15 @@ export interface McpJourneyRunOptions {
     readonly emulation?: EmulationSpec;
     readonly screenshots?: ScreenshotsSpec;
     readonly fixtures?: (site: string) => MissionFixtures | undefined;
+    /** #303: record and compare each replayed step's action delta (`--action-deltas`). */
+    readonly actionDeltas?: boolean;
 }
 /**
  * #255: what `verify_fix` hands the runner — the finding (resolved result path + fingerprint) and
  * the CLI-parity replay options. Operator-only settings (shell hooks, `cmd:` log sources, re-sending
  * paid/destructive hang writes, redaction literals) are never MCP arguments: targets.json decides.
  */
-export type McpVerifyFixArgs = Pick<RunVerifyFixOptions, "resultPath" | "fingerprint"> & Partial<Pick<RunVerifyFixOptions, "storageState" | "browser" | "replays" | "invariantFiles" | "fixtureFlags" | "emulation" | "allowEmulationOverride" | "screenshots">>;
+export type McpVerifyFixArgs = Pick<RunVerifyFixOptions, "resultPath" | "fingerprint"> & Partial<Pick<RunVerifyFixOptions, "storageState" | "browser" | "replays" | "invariantFiles" | "fixtureFlags" | "emulation" | "allowEmulationOverride" | "screenshots" | "actionDeltas">>;
 export interface McpApiDeps {
     /** Journeys store directory (`~/.jevitate/journeys` in production). */
     journeysDir: string;

package/dist/mcp-api.js

@@ -15,17 +15,25 @@ import { ParamValidationError } from "@jevitate/journey";
 import { safeRunPolicy as defaultRunPolicy } from "@jevitate/domain";
 import { JourneyRequiresAuthError, UnknownJourneyError, runJourneyProgrammatically } from "./journey-api.js";
 import { runVerifyFix } from "./verify-fix-api.js";
+import { ExtensionMismatchError } from "./browser-run-options.js";
 import { browserRunFromFlags, emulationFromFlags } from "./cli-shared.js";
 import { environmentFromFlags, isEnvironmentError } from "./environments.js";
 import { buildMissionFixtures, checkSetupRefs } from "./fixture-cli.js";
 import { FixtureSetupError, FixtureSpecError, UnboundSetupRefError } from "./mission-fixtures.js";
 import { parseScreenshotsArg } from "./run-screenshots.js";
 import { makeExploreSelfHealer } from "./self-heal-adapter.js";
-import { McpArgError, argErrorBody, optBool, optEnum, optInt, optPath, optRecordVideo, optScreenshots, optString, optStringArray, optStringMap, optViewport } from "./mcp-args.js";
+import { McpArgError, argErrorBody, optBool, optEnum, optInt, optNamedSessions, optPath, optExtensions, optRecordVideo, optScreenshots, optString, optStringArray, optStringMap, optViewport } from "./mcp-args.js";
 import { defaultMcpPathRoots } from "./mcp-paths.js";
 import { CLI_TOOL_SPECS, cliToolInputSchema, runCliTool } from "./mcp-cli-tools.js";
 import { currentEngineInfo } from "./engine.js";
 import { loadTargetsFile } from "./target-config.js";
+import { resourcePreflight } from "./resource-preflight.js";
+/** #205: a native tool's `maxBrowsers` / `maxBrowserMemory` (MiB) arguments, typed like the CLI flags. */
+function governanceArgs(args) {
+    const maxBrowsers = optInt(args, "maxBrowsers", 1);
+    const maxBrowserMemory = optInt(args, "maxBrowserMemory", 1);
+    return { ...(maxBrowsers === undefined ? {} : { maxBrowsers }), ...(maxBrowserMemory === undefined ? {} : { maxBrowserMemory }) };
+}
 const ALLOWED = new Set(ALLOWED_TOOLS);
 const FORBIDDEN = new Set(FORBIDDEN_TOOLS);
 /**
@@ -96,6 +104,7 @@ export function buildMcpTools(deps) {
             ...(o?.emulation === undefined ? {} : { emulation: o.emulation }),
             ...(o?.screenshots === undefined ? {} : { screenshots: o.screenshots }),
             ...(o?.fixtures === undefined ? {} : { fixtures: o.fixtures }),
+            ...(o?.actionDeltas === true ? { actionDeltas: true } : {}),
         })));
     const pathRoots = deps.pathRoots ?? defaultMcpPathRoots();
     // queue_exploration: enqueue over the SAME promoted fs store `jevitate
@@ -292,6 +301,7 @@ export function buildMcpTools(deps) {
             ...(a.emulation === undefined ? {} : { emulation: a.emulation }),
             ...(a.allowEmulationOverride === undefined ? {} : { allowEmulationOverride: a.allowEmulationOverride }),
             ...(a.screenshots === undefined ? {} : { screenshots: a.screenshots }),
+            ...(a.actionDeltas === true ? { actionDeltas: true } : {}),
         }));
     /** #255: verify_fix's CLI-parity replay options, validated like `verify-fix`'s flags (typed, before any browser). */
     const verifyFixOptions = (args) => {
@@ -301,6 +311,7 @@ export function buildMcpTools(deps) {
         const replays = optInt(args, "replays", 1);
         const invariantFiles = (optStringArray(args, "invariants") ?? []).map((f, i) => optPath({ [`invariants[${i}]`]: f }, `invariants[${i}]`, pathRoots));
         const fixtures = optPath(args, "fixtures", pathRoots);
+        const fixtureIdentity = optNamedSessions(args, "fixtureIdentity", pathRoots);
         const allowEmulationOverride = optBool(args, "allowEmulationOverride");
         const headed = optBool(args, "headed");
         const slowMo = optInt(args, "slowMo", 0);
@@ -308,19 +319,25 @@ export function buildMcpTools(deps) {
         const shots = optScreenshots(args, pathRoots);
         const viewport = optViewport(args);
         const device = optString(args, "device");
+        const extension = optExtensions(args, pathRoots);
+        const governance = governanceArgs(args);
+        const actionDeltas = optBool(args, "actionDeltas");
         try {
-            const browser = browserRunFromFlags({ browserArg: [], ...(headed === undefined ? {} : { headed }), ...(slowMo === undefined ? {} : { slowMo }), ...(recordVideo === undefined ? {} : { recordVideo }) });
+            const browser = browserRunFromFlags({ browserArg: [], ...governance, ...(extension === undefined ? {} : { extension }), ...(headed === undefined ? {} : { headed }), ...(slowMo === undefined ? {} : { slowMo }), ...(recordVideo === undefined ? {} : { recordVideo }) });
             const screenshots = parseScreenshotsArg(shots);
             const emulation = emulationFromFlags({ ...(viewport === undefined ? {} : { viewport }), ...(device === undefined ? {} : { device }) });
             return {
                 ...(storageState === undefined ? {} : { storageState }),
                 ...(replays === undefined ? {} : { replays }),
                 ...(invariantFiles.length === 0 ? {} : { invariantFiles }),
-                ...(fixtures === undefined ? {} : { fixtureFlags: { fixtures } }),
+                ...(fixtures === undefined && fixtureIdentity === undefined
+                    ? {}
+                    : { fixtureFlags: { ...(fixtures === undefined ? {} : { fixtures }), ...(fixtureIdentity === undefined ? {} : { fixtureIdentity }) } }),
                 ...(allowEmulationOverride === undefined ? {} : { allowEmulationOverride }),
                 ...(browser === undefined ? {} : { browser }),
                 ...(screenshots === undefined ? {} : { screenshots }),
                 ...(emulation === undefined ? {} : { emulation }),
+                ...(actionDeltas === true ? { actionDeltas: true } : {}),
             };
         }
         catch (err) {
@@ -346,6 +363,10 @@ export function buildMcpTools(deps) {
                 throw err;
             return errorResult(body);
         }
+        // #205: the same pre-run checks as `jevitate verify-fix` (orphan sweep, starved-host refusal).
+        const starved = await resourcePreflight({});
+        if (starved !== null)
+            return errorResult({ error: "refused", code: starved.error?.code, message: starved.error?.message });
         const ref = await resolveResultId(args.id, "verify_fix");
         if ("response" in ref) {
             // A mission still queued/running has nothing to verify yet: never a pass.
@@ -398,11 +419,13 @@ export function buildMcpTools(deps) {
         const headed = optBool(args, "headed");
         const slowMo = optInt(args, "slowMo", 0);
         const recordVideo = optRecordVideo(args, pathRoots);
+        const extension = optExtensions(args, pathRoots);
+        const governance = governanceArgs(args);
         let browser;
         let screenshots;
         let emulation;
         try {
-            browser = browserRunFromFlags({ browserArg: [], ...(headed === undefined ? {} : { headed }), ...(slowMo === undefined ? {} : { slowMo }), ...(recordVideo === undefined ? {} : { recordVideo }) });
+            browser = browserRunFromFlags({ browserArg: [], ...governance, ...(extension === undefined ? {} : { extension }), ...(headed === undefined ? {} : { headed }), ...(slowMo === undefined ? {} : { slowMo }), ...(recordVideo === undefined ? {} : { recordVideo }) });
             screenshots = parseScreenshotsArg(optScreenshots(args, pathRoots));
             const viewport = optViewport(args);
             const device = optString(args, "device");
@@ -414,9 +437,11 @@ export function buildMcpTools(deps) {
             throw new McpArgError(err instanceof Error ? err.message : String(err));
         }
         const fixturesFile = optPath(args, "fixtures", pathRoots);
+        const fixtureIdentity = optNamedSessions(args, "fixtureIdentity", pathRoots);
         // The environment's hooks apply as on the CLI; they need --allow-shell-hooks, which MCP never sets.
         const fixtureFlags = {
             ...(fixturesFile === undefined ? {} : { fixtures: fixturesFile }),
+            ...(fixtureIdentity === undefined ? {} : { fixtureIdentity }),
             ...(environment?.hooks?.before === undefined ? {} : { before: environment.hooks.before }),
             ...(environment?.hooks?.after === undefined ? {} : { after: environment.hooks.after }),
         };
@@ -461,6 +486,7 @@ export function buildMcpTools(deps) {
                 ...(browser === undefined ? {} : { browser }),
                 ...(emulation === undefined ? {} : { emulation }),
                 ...(screenshots === undefined ? {} : { screenshots }),
+                ...(optBool(args, "actionDeltas") === true ? { actionDeltas: true } : {}),
             },
             ...(usage === undefined ? {} : { usage }),
         };
@@ -470,13 +496,14 @@ export function buildMcpTools(deps) {
             description: "Replay a finding's reproduction (by mission result id — or a finished queue_exploration missionId — + fingerprint) N times in fresh browsers (default 3) — `jevitate verify-fix`. status: fixed (signal absent on every replay) | still-reproduces | intermittent (fired on some but not all replays — never a pass) | inconclusive (replay could not reach the step — never a pass). " +
                 "#255 (same as the CLI flags): 'replays' (>= 1); 'recordVideo' (true or a directory: the before/after evidence pair — `evidence.before` is the run's own clip, `evidence.after` a captioned replay — plus videoPaths); 'screenshots'; 'headed'/'slowMo'; " +
                 "'storageState' (a path inside the project or ~/.jevitate, never a repo's .jevitate/; overrides the mission's session); 'viewport' {width,height} or 'device' (refused when it differs from the finding's recorded emulation unless 'allowEmulationOverride'); " +
-                "'invariants' (invariant file paths re-checking a declared-invariant defect); 'fixtures' (a fixtures file overriding the mission's saved one). Operator-only settings (shell hooks, cmd: log sources, re-sending paid/destructive hang writes) come from targets.json, never an argument.",
+                "'invariants' (invariant file paths re-checking a declared-invariant defect); 'fixtures' (a fixtures file overriding the mission's saved one); 'fixtureIdentity' (#243: 'name=<storageState path>' entries re-binding a fixture step's auth.identity; default: the identities the mission recorded); 'extension' (#256: unpacked extension directories — refused unless the same build the finding was recorded with); 'actionDeltas' (#303, opt-in: the defect step's replayed delta vs the recorded one, as evidence on each attempt); 'maxBrowsers'/'maxBrowserMemory' (#205: machine-wide browser cap, browser memory ceiling in MiB). Operator-only settings (shell hooks, cmd: log sources, re-sending paid/destructive hang writes) come from targets.json, never an argument.",
             inputSchema: {
                 type: "object",
                 properties: {
                     id: { type: "string" },
                     fingerprint: { type: "string" },
                     replays: { type: "integer", minimum: 1 },
+                    actionDeltas: { type: "boolean" },
                     recordVideo: { type: ["boolean", "string"] },
                     screenshots: { type: ["boolean", "string"] },
                     headed: { type: "boolean" },
@@ -487,6 +514,10 @@ export function buildMcpTools(deps) {
                     allowEmulationOverride: { type: "boolean" },
                     invariants: { type: "array", items: { type: "string" } },
                     fixtures: { type: "string" },
+                    fixtureIdentity: { type: "array", items: { type: "string" } },
+                    extension: { type: "array", items: { type: "string" } },
+                    maxBrowsers: { type: "integer", minimum: 1 },
+                    maxBrowserMemory: { type: "integer", minimum: 1 },
                 },
                 required: ["id", "fingerprint"],
             },
@@ -509,8 +540,8 @@ export function buildMcpTools(deps) {
                 "server's own browser, never returned or logged. A Journey that declares metadata.requiresAuth refuses " +
                 "with a clear error when no storageState is given. #255 (same as the CLI flags): 'env' (a named environment in .jevitate/environments.json; its session from ~/.jevitate/targets.json) and/or 'baseUrl'; " +
                 "'headed' (needs a display) and 'slowMo'; 'recordVideo' (true, or a directory) → videoPaths; 'screenshots' (true | screens | steps | mode:<dir> | <dir>) → screenshotPaths; " +
-                "'viewport' {width,height} or 'device' (mutually exclusive); 'fixtures' (a fixtures JSON path: setup before, restore after; an environment's shell hooks are never run over MCP — they refuse as the CLI does without --allow-shell-hooks); " +
-                "'selfHeal' fail-closed (default) | hybrid | full with 'real' or 'fakeAi' (a write step never self-heals). A site-policy refusal is {error: throttled, retryAfter}.",
+                "'viewport' {width,height} or 'device' (mutually exclusive); 'fixtures' (a fixtures JSON path: setup before, restore after; 'fixtureIdentity' (#243) 'name=<storageState path>' entries name who a step with auth.identity authenticates as; an environment's shell hooks are never run over MCP — they refuse as the CLI does without --allow-shell-hooks); " +
+                "'extension' (#256: unpacked extension directories inside the project or ~/.jevitate; a Journey recorded with extensions needs the same build); 'selfHeal' fail-closed (default) | hybrid | full with 'real' or 'fakeAi' (a write step never self-heals); 'actionDeltas' (#303, opt-in: each replayed step's action delta, compared with the recorded one → actionDeltas); 'maxBrowsers'/'maxBrowserMemory' (#205: machine-wide browser cap, browser memory ceiling in MiB). A site-policy refusal is {error: throttled, retryAfter}.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -526,9 +557,14 @@ export function buildMcpTools(deps) {
                     viewport: { type: "object", properties: { width: { type: "integer" }, height: { type: "integer" } }, required: ["width", "height"] },
                     device: { type: "string" },
                     fixtures: { type: "string" },
+                    fixtureIdentity: { type: "array", items: { type: "string" } },
                     selfHeal: { type: "string", enum: ["fail-closed", "hybrid", "full"] },
                     real: { type: "boolean" },
                     fakeAi: { type: "boolean" },
+                    extension: { type: "array", items: { type: "string" } },
+                    maxBrowsers: { type: "integer", minimum: 1 },
+                    maxBrowserMemory: { type: "integer", minimum: 1 },
+                    actionDeltas: { type: "boolean" },
                 },
                 required: ["id"],
             },
@@ -550,6 +586,10 @@ export function buildMcpTools(deps) {
                         return errorResult({ error: "setup_required", message: err.message });
                     throw err;
                 }
+                // #205: the same pre-run checks as `jevitate journey run` (orphan sweep, starved-host refusal).
+                const starved = await resourcePreflight({});
+                if (starved !== null)
+                    return errorResult({ error: "refused", code: starved.error?.code, message: starved.error?.message });
                 try {
                     const result = await runJourney(args.id, resolved.params, resolved.storageState, resolved.options);
                     // #163: a self-healing run's model usage lands on its result, as on the CLI.
@@ -564,6 +604,8 @@ export function buildMcpTools(deps) {
                         return errorResult({ error: "not_found", id: args.id, message: err.message });
                     if (err instanceof JourneyRequiresAuthError)
                         return errorResult({ error: "invalid_args", code: "E_JOURNEY_REQUIRES_AUTH", message: err.message });
+                    if (err instanceof ExtensionMismatchError)
+                        return errorResult({ error: "invalid_args", code: err.code, message: err.message });
                     if (err instanceof ParamValidationError)
                         return errorResult({ error: "invalid_args", code: "E_INVALID_PARAMS", message: err.message });
                     if (isEnvironmentError(err) || err instanceof FixtureSpecError || err instanceof UnboundSetupRefError) {