@jevitate/cli 0.1.0 → 0.3.0

package/dist/mcp-api.js

@@ -1,13 +1,39 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { SiteGateRefusedError } from "@jevitate/runtime";
+import { withSiteGate } from "./site-gate-cli.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { ALLOWED_TOOLS, FORBIDDEN_TOOLS, findCapabilities, queueExploration as facadeQueueExploration, aiGenerateText as facadeAiGenerateText, facadeListIncoming, facadeGetCommand, facadeGetThread, facadeQueueAction, facadeQueueRetrieval, facadeApproveAction, facadeCancelCommand, facadeGetSiteHealth, } from "@jevitate/mcp-facade";
+import { ALLOWED_TOOLS, FORBIDDEN_TOOLS, findCapabilities, queueExploration as facadeQueueExploration, aiGenerateText as facadeAiGenerateText, facadeListIncoming, facadeGetCommand, facadeGetThread, facadeQueueAction, facadeQueueRetrieval, facadeApproveAction, facadeCancelCommand, facadeGetSiteHealth, isMissionResultId, isQueuedMissionId, missionResultFileName, missionStatus, parseResultOutcome, } from "@jevitate/mcp-facade";
 import { FsJourneyStore, JourneyRegistry } from "@jevitate/journey";
-import { FsMissionTargetStore, MissionTargetRegistry, FsMissionQueueStore, } from "@jevitate/missions";
+import { FsMissionTargetStore, MissionTargetRegistry, FsMissionQueueStore, MISSION_STRATEGIES, QUEUED_SCREENSHOT_MODES, } from "@jevitate/missions";
 import { FsInboxStore } from "@jevitate/inbox";
-import { envCredentialStore, } from "@jevitate/ai-core";
-import { safeRunPolicy } from "@jevitate/domain";
-import { runJourneyProgrammatically } from "./journey-api.js";
+import { ALL_CREDENTIAL_KEYS, envCredentialStore, } from "@jevitate/ai-core";
+import { existsSync } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+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, 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);
 /**
@@ -33,9 +59,17 @@ function errorResult(value) {
  *  SDK error (which can echo request internals verbatim) never surfaces a key
  *  through the MCP result. The message returned to the caller is generic and
  *  key-free; this is belt-and-braces on top of the gateway's outbound guard. */
+/** #217: a persisted goal result's own ending (`result.goalOutcome`), when present. */
+function goalOutcomeOf(file) {
+    const result = file.result;
+    return result !== null && typeof result === "object" && "goalOutcome" in result ? result.goalOutcome : undefined;
+}
+/** A model-backed option was asked for without usable gateways/keys (typed `setup_required`). */
+class SetupRequired extends Error {
+}
 function redactCredentials(message, store) {
     let out = message;
-    for (const key of ["OPENROUTER_API_KEY", "TYPESAFE_API_KEY"]) {
+    for (const key of ALL_CREDENTIAL_KEYS) {
         const value = store.read(key);
         if (value)
             out = out.split(value).join("***REDACTED***");
@@ -57,7 +91,22 @@ export function buildMcpTools(deps) {
     const findCaps = deps.findCapabilities ??
         ((query) => findCapabilities(new JourneyRegistry(new FsJourneyStore(deps.journeysDir)), query));
     const runJourney = deps.runJourney ??
-        ((id, params) => runJourneyProgrammatically({ dir: deps.journeysDir, id, params, policy: safeRunPolicy() }));
+        ((id, params, storageState, o) => withSiteGate(deps.sitePolicyDbPath, (siteGate) => runJourneyProgrammatically({
+            dir: deps.journeysDir,
+            id,
+            params,
+            policy: o?.policy ?? defaultRunPolicy(),
+            ...(storageState !== undefined ? { storageState } : {}),
+            ...(siteGate === undefined ? {} : { siteGate }),
+            ...(o?.selfHealer === undefined ? {} : { selfHealer: o.selfHealer }),
+            ...(o?.environment === undefined ? {} : { environment: o.environment }),
+            ...(o?.browser === undefined ? {} : { browser: o.browser }),
+            ...(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
     // mission target` writes. The store is built lazily inside the closure so
     // constructing the tool set never touches disk; a missing dir is a config
@@ -91,7 +140,7 @@ export function buildMcpTools(deps) {
         if (!deps.inboxDir) {
             throw new Error("inbox tools require inboxDir to be configured");
         }
-        return new FsInboxStore(deps.inboxDir);
+        return new FsInboxStore(deps.inboxDir, deps.engine ?? currentEngineInfo());
     };
     function inboxHandler(fn) {
         return async (args) => {
@@ -131,19 +180,391 @@ export function buildMcpTools(deps) {
         },
     };
     const queueCommonRequired = ["run", "journey", "step", "reason", "agent"];
+    // get_mission_result: reads a persisted typed mission result by ID only (the artifact stem the
+    // CLI wrote) — never a caller-supplied path. The status carries the CLI exit code, and a run that
+    // itself broke (inconclusive/crashed) is an MCP error result, so it can never read as a pass.
+    //
+    // The id is either a result stem (`explore-<stamp>`, `usability-<stamp>.recording`, …) or a
+    // `queue_exploration` missionId (#117): the latter resolves through the mission's queue record —
+    // `queued`/`running` is reported as such (not an error, not a result), `failed` as an error, and
+    // `done` reads the result its drain wrote. Both shapes are closed regexes; nothing caller-shaped
+    // ever reaches a path.
+    const resolveResultId = async (id, tool) => {
+        if (isMissionResultId(id))
+            return { resultId: id };
+        if (!isQueuedMissionId(id)) {
+            return {
+                response: errorResult({
+                    error: "invalid_args",
+                    message: `${tool} requires a mission result 'id' (explore-|coverage-|exploratory-|adversarial-|feature-|usability-<stamp>) or a queue_exploration missionId`,
+                }),
+            };
+        }
+        if (!deps.missionQueueDir) {
+            return { response: errorResult({ error: "not_configured", message: `${tool} requires missionQueueDir to resolve a missionId` }) };
+        }
+        let mission;
+        try {
+            mission = await new FsMissionQueueStore(deps.missionQueueDir).get(id);
+        }
+        catch {
+            return { response: errorResult({ error: "corrupt_mission", id }) };
+        }
+        if (mission === null)
+            return { response: errorResult({ error: "not_found", id }) };
+        if (mission.status === "queued" || mission.status === "running") {
+            // Not finished: neither a pass nor a failure — the agent polls again later.
+            const pending = {
+                id,
+                missionId: id,
+                status: mission.status,
+                pending: true,
+                enqueuedAtIso: mission.enqueuedAtIso,
+                ...(mission.startedAtIso === undefined ? {} : { startedAtIso: mission.startedAtIso }),
+            };
+            return { response: jsonResult(pending), pending };
+        }
+        if (mission.status === "failed") {
+            return { response: errorResult({ id, missionId: id, status: "failed", isError: true, error: mission.error ?? "mission failed" }) };
+        }
+        if (!isMissionResultId(mission.resultId))
+            return { response: errorResult({ error: "corrupt_mission", id }) };
+        return { resultId: mission.resultId, missionId: id };
+    };
+    /** The dirs a result may live in: recordings, and (usability reviews) the UX reports dir. */
+    const resultPathsFor = (resultId) => {
+        const file = missionResultFileName(resultId);
+        const dirs = deps.resultDirsFor?.(resultId) ?? [deps.recordingsDir, ...(resultId.startsWith("usability-") ? [deps.uxReportsDir] : [])];
+        return dirs.filter((d) => d !== undefined).map((d) => join(d, file));
+    };
+    const getMissionResult = async (args) => {
+        if (!deps.recordingsDir) {
+            return errorResult({ error: "not_configured", message: "get_mission_result requires recordingsDir" });
+        }
+        const ref = await resolveResultId(args.id, "get_mission_result");
+        if ("response" in ref)
+            return ref.response;
+        const ids = { id: args.id, ...(ref.missionId === undefined ? {} : { missionId: ref.missionId, resultId: ref.resultId }) };
+        let raw;
+        for (const path of resultPathsFor(ref.resultId)) {
+            try {
+                raw = await readFile(path, "utf8");
+                break;
+            }
+            catch {
+                // Try the next candidate dir.
+            }
+        }
+        if (raw === undefined) {
+            return errorResult({ error: "not_found", ...ids });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return errorResult({ error: "corrupt_result", ...ids });
+        }
+        // #217: `missionOutcome` is canonical; a goal run's own ending rides beside it as `goalOutcome`.
+        const parsedOutcome = parsed !== null && typeof parsed === "object" && "missionOutcome" in parsed
+            ? parseResultOutcome(parsed.missionOutcome, goalOutcomeOf(parsed))
+            : null;
+        if (parsedOutcome === null) {
+            return errorResult({ error: "corrupt_result", ...ids });
+        }
+        const status = {
+            ...missionStatus(parsedOutcome.outcome),
+            ...(parsedOutcome.goalOutcome === undefined ? {} : { goalOutcome: parsedOutcome.goalOutcome }),
+        };
+        const result = parsed.result ?? null;
+        // An adversarial run's coverage is surfaced next to the status: an `inconclusive` run says what
+        // it did and did not exercise, so an agent can tell "found nothing" from "tried nothing".
+        const coverage = result !== null && typeof result === "object" && "coverage" in result ? result.coverage : undefined;
+        const body = { ...ids, ...status, ...(coverage === undefined ? {} : { coverage }), result };
+        return status.isError ? errorResult(body) : jsonResult(body);
+    };
+    // verify_fix: replays a persisted finding by (result id, fingerprint) — never a caller-supplied
+    // recording or path (invariant #5 analogue). Passes only if the defect signal is absent; an
+    // unreachable replay is `inconclusive` and returned as an error result, never as "fixed".
+    // #142 follow-up: a `cmd:` server-log source may only be re-run when the OPERATOR opted in for
+    // this origin in ~/.jevitate/targets.json (`allowLogCmd: true`) — never via an MCP argument.
+    const verifyFixImpl = deps.verifyFix ??
+        ((a) => runVerifyFix({
+            targets: loadTargetsFile(deps.targetsConfigPath),
+            resultPath: a.resultPath,
+            fingerprint: a.fingerprint,
+            ...(a.storageState === undefined ? {} : { storageState: a.storageState }),
+            ...(a.browser === undefined ? {} : { browser: a.browser }),
+            ...(a.replays === undefined ? {} : { replays: a.replays }),
+            ...(a.invariantFiles === undefined ? {} : { invariantFiles: a.invariantFiles }),
+            ...(a.fixtureFlags === undefined ? {} : { fixtureFlags: a.fixtureFlags }),
+            ...(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) => {
+        const storageState = optPath(args, "storageState", pathRoots, { session: true });
+        if (storageState !== undefined && !existsSync(storageState))
+            throw new McpArgError(`storage state not found: ${storageState}`);
+        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);
+        const recordVideo = optRecordVideo(args, pathRoots);
+        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: [], ...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 && 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) {
+            throw new McpArgError(err instanceof Error ? err.message : String(err));
+        }
+    };
+    const verifyFixTool = async (args) => {
+        if (!deps.recordingsDir) {
+            return errorResult({ error: "not_configured", message: "verify_fix requires recordingsDir" });
+        }
+        if (!(isMissionResultId(args.id) || isQueuedMissionId(args.id)) ||
+            typeof args.fingerprint !== "string" ||
+            !/^[0-9a-f]{16}$/.test(args.fingerprint)) {
+            return errorResult({ error: "invalid_args", message: "verify_fix requires a mission result 'id' (or missionId) and a 16-hex 'fingerprint'" });
+        }
+        let options;
+        try {
+            options = verifyFixOptions(args);
+        }
+        catch (err) {
+            const body = argErrorBody(err);
+            if (body === undefined)
+                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.
+            return ref.pending === undefined ? ref.response : errorResult({ error: "not_ready", ...ref.pending });
+        }
+        // The first candidate that exists (usability results may sit in the UX reports dir).
+        const candidates = resultPathsFor(ref.resultId);
+        let resultPath = candidates[0];
+        for (const path of candidates) {
+            try {
+                await access(path);
+                resultPath = path;
+                break;
+            }
+            catch {
+                // Try the next candidate dir.
+            }
+        }
+        try {
+            const report = await verifyFixImpl({ ...options, resultPath, fingerprint: args.fingerprint });
+            const body = {
+                id: args.id,
+                ...(ref.missionId === undefined ? {} : { missionId: ref.missionId, resultId: ref.resultId }),
+                status: report.verdict,
+                ...report,
+            };
+            // Neither is a pass: `inconclusive` proved nothing either way, `intermittent` (#74) means the
+            // signal fired on SOME but not all fresh-context replays — never trustworthy as "fixed".
+            return report.verdict === "inconclusive" || report.verdict === "intermittent" ? errorResult(body) : jsonResult(body);
+        }
+        catch (err) {
+            return errorResult({ error: "verify_fix_refused", message: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    /**
+     * #255: `run_journey`'s CLI-parity options, resolved exactly as `journey run` resolves its flags
+     * (the same helpers: environmentFromFlags, browserRunFromFlags, parseScreenshotsArg,
+     * emulationFromFlags, buildMissionFixtures) — every refusal typed, before any browser opens.
+     */
+    const resolveJourneyRun = async (args) => {
+        // Params keep their historical leniency for a non-object (treated as none); a non-string VALUE is refused.
+        const params = args.params && typeof args.params === "object" && !Array.isArray(args.params) ? (optStringMap(args, "params") ?? {}) : {};
+        const envName = optString(args, "env");
+        const baseUrl = optString(args, "baseUrl");
+        const environment = environmentFromFlags({ ...(envName === undefined ? {} : { env: envName }), ...(baseUrl === undefined ? {} : { baseUrl }) }, { ...(deps.environmentsFile === undefined ? {} : { environmentsFile: deps.environmentsFile }), ...(deps.targetsConfigPath === undefined ? {} : { targetsFile: deps.targetsConfigPath }) });
+        // --storage-state wins; else the environment's own session (~/.jevitate/targets.json[<origin>]).
+        const storageState = optPath(args, "storageState", pathRoots, { session: true }) ?? environment?.storageState;
+        if (args.storageState !== undefined && storageState !== undefined && !existsSync(storageState))
+            throw new McpArgError(`storage state not found: ${storageState}`);
+        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: [], ...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");
+            emulation = emulationFromFlags({ ...(viewport === undefined ? {} : { viewport }), ...(device === undefined ? {} : { device }) });
+        }
+        catch (err) {
+            if (err instanceof McpArgError || argErrorBody(err) !== undefined)
+                throw err;
+            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 }),
+        };
+        const fixtures = (site) => {
+            const fx = buildMissionFixtures(fixtureFlags, {
+                allowlist: environment === undefined ? [site] : environment.allowedOrigins,
+                baseUrl: site,
+                ...(storageState !== undefined ? { storageState } : {}),
+                ...(environment?.fixtures === undefined ? {} : { targetFixtures: environment.fixtures }),
+            });
+            checkSetupRefs({ "--param": Object.values(params) }, fx);
+            return fx;
+        };
+        const selfHeal = optEnum(args, "selfHeal", ["fail-closed", "hybrid", "full"]) ?? "fail-closed";
+        const real = optBool(args, "real") ?? false;
+        const fakeAi = optBool(args, "fakeAi") ?? false;
+        let selfHealer;
+        let policy = defaultRunPolicy();
+        let usage;
+        if (selfHeal !== "fail-closed") {
+            if (deps.selfHealGateways === undefined)
+                throw new SetupRequired("run_journey selfHeal needs the model gateways, which this server was not given");
+            let judge;
+            let gen;
+            try {
+                ({ judge, gen, usage } = await deps.selfHealGateways({ real, fakeAi }));
+            }
+            catch (err) {
+                throw new SetupRequired(redactCredentials(err instanceof Error ? err.message : String(err), credentialStore));
+            }
+            selfHealer = makeExploreSelfHealer(judge, gen);
+            policy = { ...policy, selfHeal: { mode: selfHeal } };
+        }
+        return {
+            params,
+            ...(storageState === undefined ? {} : { storageState }),
+            options: {
+                policy,
+                fixtures,
+                ...(selfHealer === undefined ? {} : { selfHealer }),
+                ...(environment === undefined ? {} : { environment }),
+                ...(browser === undefined ? {} : { browser }),
+                ...(emulation === undefined ? {} : { emulation }),
+                ...(screenshots === undefined ? {} : { screenshots }),
+                ...(optBool(args, "actionDeltas") === true ? { actionDeltas: true } : {}),
+            },
+            ...(usage === undefined ? {} : { usage }),
+        };
+    };
     const wired = {
+        verify_fix: {
+            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); '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" },
+                    slowMo: { type: "integer", minimum: 0 },
+                    storageState: { type: "string" },
+                    viewport: { type: "object", properties: { width: { type: "integer" }, height: { type: "integer" } }, required: ["width", "height"] },
+                    device: { type: "string" },
+                    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"],
+            },
+            handler: verifyFixTool,
+        },
+        get_mission_result: {
+            description: "Read a mission's TYPED result by id: a result stem (explore-|coverage-|exploratory-|adversarial-|feature-|usability-<stamp>, e.g. adversarial-2026-09-23T00-00-00-000Z) or a queue_exploration missionId. A queued mission reports status queued | running (pending: true — poll again; `jevitate mission run` drains the queue) or failed (an error: it could not run). A finished one: status is clean | defects-found | hang | intermittent | inconclusive | crashed, with the matching CLI exit code. A broken run (inconclusive/crashed) is returned as an error result — never a pass. An adversarial result carries `coverage` (target controls exercised/total, forms submitted, strategies applied vs found nothing, out-of-scope steps): a run below its coverage thresholds is inconclusive, never clean.",
+            inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+            handler: getMissionResult,
+        },
         find_capabilities: {
             description: "Find promoted Journeys (capabilities) whose metadata matches a query.",
             inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
             handler: async (args) => jsonResult(await findCaps(typeof args.query === "string" ? args.query : "")),
         },
         run_journey: {
-            description: "Run a PUBLISHED Journey by id with string params (fail-closed policy). Never accepts inline steps.",
+            description: "Run a PUBLISHED Journey by id with string params (fail-closed policy) — `jevitate journey run`. Never accepts inline steps. " +
+                "Optional 'storageState': a PATH (on the machine running this MCP server; inside the project or ~/.jevitate, never a repo's .jevitate/) to a Playwright storageState " +
+                "JSON file, for a Journey authored behind a login (#118) — the file's contents are read only by the " +
+                "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; '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: {
                     id: { type: "string" },
                     params: { type: "object", additionalProperties: { type: "string" } },
+                    storageState: { type: "string" },
+                    env: { type: "string" },
+                    baseUrl: { type: "string" },
+                    headed: { type: "boolean" },
+                    slowMo: { type: "integer", minimum: 0 },
+                    recordVideo: { type: ["boolean", "string"] },
+                    screenshots: { type: ["boolean", "string"] },
+                    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"],
             },
@@ -151,16 +572,55 @@ export function buildMcpTools(deps) {
                 if (typeof args.id !== "string" || args.id.length === 0) {
                     return errorResult({ error: "invalid_args", message: "run_journey requires a non-empty string 'id'" });
                 }
-                // Invariant #5: only id + params are threaded through — any inline
-                // `steps`/`recording` in the arguments is deliberately ignored.
-                const params = args.params && typeof args.params === "object" && !Array.isArray(args.params)
-                    ? args.params
-                    : {};
-                return jsonResult(await runJourney(args.id, params));
+                // Invariant #5: only id + params (+ a storageState PATH and the run options below) are
+                // threaded through — any inline `steps`/`recording` in the arguments is deliberately ignored.
+                let resolved;
+                try {
+                    resolved = await resolveJourneyRun(args);
+                }
+                catch (err) {
+                    const body = argErrorBody(err) ?? (isEnvironmentError(err) ? { error: "invalid_args", code: err.code, message: err.message } : undefined);
+                    if (body !== undefined)
+                        return errorResult(body);
+                    if (err instanceof SetupRequired)
+                        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.
+                    return jsonResult(resolved.usage === undefined || result === null || typeof result !== "object" ? result : { ...result, usage: resolved.usage.snapshot() });
+                }
+                catch (err) {
+                    // A site-policy refusal (throttle, budget, quiet hours) is an answer the agent acts on — when to retry.
+                    if (err instanceof SiteGateRefusedError) {
+                        return errorResult({ error: "throttled", reason: err.reason, retryAfter: err.retryAfter, message: err.message });
+                    }
+                    if (err instanceof UnknownJourneyError)
+                        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) {
+                        return errorResult({ error: "invalid_args", code: err.code, message: err.message });
+                    }
+                    // Never run on unknown state: inconclusive (exit 2) — proves nothing, so an error result.
+                    if (err instanceof FixtureSetupError) {
+                        return errorResult({ outcome: "inconclusive", reason: err.message, failure: { kind: "configuration", message: err.message }, attribution: "configuration", exitCode: 2 });
+                    }
+                    throw err;
+                }
             },
         },
         queue_exploration: {
-            description: "Enqueue an exploration mission against a PROMOTED target. Never runs anything — only queues. Refuses unknown/unpromoted targets and over-ceiling budgets.",
+            description: "Enqueue an exploration mission against a PROMOTED target. Never runs anything — only queues; `jevitate mission run` drains the queue, and get_mission_result {id: missionId} reports its status/result. strategy: goal-based (goal|feature|route + successAssertion) | coverage | exploratory (novelty-first coverage) | adversarial (optional in-scope route glob) | feature (feature name, optional route glob); a usability review is not queueable — use run_exploration {strategy: usability}. The target's authorized origin plus its declared apiOrigins are the only reachable origins. Refuses unknown/unpromoted targets, over-ceiling budgets and invalid declared `invariants` (an optional closed spec checked around every action; probes GET/HEAD on the target origin only). Optional 'viewport' ({width,height}) or 'device' (a Playwright devices registry name, e.g. \"iPhone 13\") — mutually exclusive (#149); default: Playwright's own default viewport. An unknown device is refused before any browser opens. #255: 'recordVideo' / 'evidenceVideo' (booleans) and 'screenshots' (screens | steps) write media next to the result (listed in it) — a queued request never names a path; 'persona' names a persona in the operator's ~/.jevitate/targets.json for the target's origin (its session, never the caller's). Same as `jevitate mission queue`.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -169,7 +629,7 @@ export function buildMcpTools(deps) {
                     feature: { type: "string" },
                     route: { type: "string" },
                     successAssertion: { type: "object" },
-                    strategy: { type: "string" },
+                    strategy: { type: "string", enum: [...MISSION_STRATEGIES] },
                     budget: {
                         type: "object",
                         properties: {
@@ -178,6 +638,22 @@ export function buildMcpTools(deps) {
                             maxCandidates: { type: "number" },
                         },
                     },
+                    // App-declared invariants (#86), inline only: a closed schema (observe: dom|network|probe,
+                    // invariants: require|never|always). Probes are GET/HEAD on the target's own origin; a spec
+                    // that does not validate refuses the enqueue.
+                    invariants: { type: "object" },
+                    // Per-mission viewport/device emulation (#149) — mutually exclusive.
+                    viewport: {
+                        type: "object",
+                        properties: { width: { type: "number" }, height: { type: "number" } },
+                        required: ["width", "height"],
+                    },
+                    device: { type: "string" },
+                    // #255: media next to the result (a mode or a boolean — never a path) and a persona NAME.
+                    recordVideo: { type: "boolean" },
+                    screenshots: { type: "string", enum: [...QUEUED_SCREENSHOT_MODES] },
+                    evidenceVideo: { type: "boolean" },
+                    persona: { type: "string" },
                 },
                 required: ["target"],
             },
@@ -293,6 +769,19 @@ export function buildMcpTools(deps) {
             handler: inboxHandler((store) => facadeGetSiteHealth(store)),
         },
     };
+    // #255: every CLI command without a hand-written tool above — mirrored exactly, run in process.
+    for (const spec of CLI_TOOL_SPECS) {
+        if (wired[spec.name] !== undefined)
+            throw new Error(`MCP tool '${spec.name}' is defined twice`);
+        wired[spec.name] = {
+            description: spec.description,
+            inputSchema: cliToolInputSchema(spec),
+            handler: async (args) => {
+                const { isError, body } = await runCliTool(spec, args, { runCli: deps.runCli, roots: pathRoots, redact: (text) => redactCredentials(text, credentialStore) });
+                return isError ? errorResult(body) : jsonResult(body);
+            },
+        };
+    }
     const notImplemented = (name) => async () => errorResult({
         error: "not_implemented",
         tool: name,
@@ -319,7 +808,14 @@ export function buildMcpTools(deps) {
 export function createMcpServer(deps) {
     const tools = buildMcpTools(deps);
     const byName = new Map(tools.map((t) => [t.name, t]));
-    const server = new Server({ name: "jevitate", version: "0.0.0" }, { capabilities: { tools: {} } });
+    // The real build identity (#112), never a placeholder: `version` is the published semver, and the
+    // description names the commit/build time so an MCP client can tie a session to a build.
+    const engine = deps.engine ?? currentEngineInfo();
+    const server = new Server({
+        name: "jevitate",
+        version: engine.version,
+        description: `jevitate ${engine.version} (commit ${engine.commit}, built ${engine.builtAt})`,
+    }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
     }));