@jevitate/cli 0.1.0 → 0.2.0

package/dist/log-sources.js

@@ -0,0 +1,235 @@
+import { spawn } from "node:child_process";
+import { createReadStream, statSync } from "node:fs";
+export class LogSourceSpecError extends Error {
+    code = "E_LOG_SOURCE_SPEC";
+    constructor(message) {
+        super(message);
+        this.name = "LogSourceSpecError";
+    }
+}
+/** Parses one `--log-source` value. Throws `LogSourceSpecError` on an unrecognized/empty spec. */
+export function parseLogSourceSpec(raw) {
+    const i = raw.indexOf(":");
+    if (i < 0)
+        throw new LogSourceSpecError(`--log-source must be file:<path>, docker:<container> or cmd:<command>: got ${JSON.stringify(raw)}`);
+    const kind = raw.slice(0, i);
+    const rest = raw.slice(i + 1);
+    if (rest.trim() === "")
+        throw new LogSourceSpecError(`--log-source ${kind}: missing value`);
+    if (kind === "file")
+        return { kind: "file", path: rest, raw };
+    if (kind === "docker")
+        return { kind: "docker", container: rest, raw };
+    if (kind === "cmd")
+        return { kind: "cmd", command: rest, raw };
+    throw new LogSourceSpecError(`--log-source: unknown source kind ${JSON.stringify(kind)} (want file:, docker: or cmd:)`);
+}
+/**
+ * Validates every spec up front, INCLUDING the `cmd:` + `--allow-log-cmd` gate — so a run refuses
+ * before any browser opens, the same fail-closed discipline as `--invariants`.
+ */
+export function parseLogSourceSpecs(raw, allowLogCmd) {
+    const specs = raw.map(parseLogSourceSpec);
+    for (const s of specs) {
+        if (s.kind === "cmd" && !allowLogCmd) {
+            throw new LogSourceSpecError(`--log-source ${s.raw} needs --allow-log-cmd (an operator-declared command is run as a subprocess)`);
+        }
+    }
+    return specs;
+}
+const DEFAULT_MAX_LINES = 20_000;
+const DEFAULT_FILE_POLL_MS = 250;
+function lineSplitter(onLine) {
+    let carry = "";
+    return (chunk) => {
+        carry += chunk.toString("utf8");
+        const lines = carry.split(/\r?\n/);
+        carry = lines.pop() ?? "";
+        for (const line of lines)
+            if (line !== "")
+                onLine(line, Date.now());
+    };
+}
+function boundedOnLine(handle, opts) {
+    const max = opts.maxLines ?? DEFAULT_MAX_LINES;
+    return (raw, epochMs) => {
+        if (handle.linesRead >= max) {
+            handle.truncated = true;
+            return;
+        }
+        handle.linesRead += 1;
+        opts.onLine(raw, epochMs);
+    };
+}
+/**
+ * `file:` — tails from the CURRENT end by polling the file's size (no `fs.watch`: flaky across
+ * filesystems, notably over WSL's `/mnt/c` drvfs — AGENTS.md). Handles truncation/rotation, AND a
+ * file that does not exist yet at open time (a backend that has not logged anything until later in
+ * the run is the common case, not an error): if the file already exists, its EXISTING content is
+ * history and skipped (`position` starts at its current size); if it does not exist yet, nothing
+ * can predate this run, so `position` starts at 0 and the first line written after the source
+ * opened is the first one delivered, however long the file takes to appear.
+ */
+function openFileSource(spec, opts) {
+    let closed = false;
+    let timer;
+    let position = 0;
+    const handle = {
+        spec,
+        opened: false,
+        linesRead: 0,
+        truncated: false,
+        close: async () => {
+            closed = true;
+            if (timer !== undefined)
+                clearInterval(timer);
+            if (!handle.opened)
+                handle.error = `${spec.path}: never appeared during the run`;
+        },
+        killSync: () => {
+            closed = true;
+            if (timer !== undefined)
+                clearInterval(timer);
+        },
+    };
+    const deliver = lineSplitter(boundedOnLine(handle, opts));
+    try {
+        // The file already exists: its content predates this source and is skipped (never replayed).
+        position = statSync(spec.path).size;
+        handle.opened = true;
+    }
+    catch {
+        // Does not exist yet: `position` stays 0, so whatever is written once it appears is ALL new.
+    }
+    const poll = () => {
+        if (closed)
+            return;
+        let size;
+        try {
+            size = statSync(spec.path).size;
+        }
+        catch {
+            return; // still not there, or a transient stat failure — the next poll tries again
+        }
+        handle.opened = true; // confirmed readable now, even if it appeared after the initial check
+        if (size <= position) {
+            if (size < position)
+                position = 0; // truncated/rotated: resume from the new start
+            return;
+        }
+        const stream = createReadStream(spec.path, { start: position, end: size - 1 });
+        stream.on("data", (chunk) => deliver(chunk));
+        stream.on("error", () => undefined);
+        position = size;
+    };
+    timer = setInterval(poll, opts.filePollMs ?? DEFAULT_FILE_POLL_MS);
+    timer.unref?.();
+    return handle;
+}
+/** Kills a spawned child's whole process GROUP (POSIX): `docker logs`/`cmd:`'s own children die
+ *  too, not just the immediate process. Falls back to killing just the child if the group send fails. */
+function killGroup(child) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGTERM");
+    }
+    catch {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+function openProcessSource(spec, command, args, opts, useShell) {
+    let child;
+    // #199: set the moment WE ask the child to stop (mission end) — BEFORE `killGroup` sends the
+    // signal, so the (always-async) `exit` event below, whenever it lands, can tell "we stopped this"
+    // from "it died on its own". A source jevitate stopped itself is a normal end of tailing, not a
+    // failure, no matter what exit code the child reports for its own signal handling (a `docker logs
+    // -f`/`cmd:` child commonly self-exits 143 for SIGTERM rather than dying to the raw signal).
+    let stopRequested = false;
+    const handle = {
+        spec,
+        opened: false,
+        linesRead: 0,
+        truncated: false,
+        close: async () => {
+            stopRequested = true;
+            if (child === undefined)
+                return;
+            killGroup(child);
+            await new Promise((resolve) => {
+                if (child === undefined || child.exitCode !== null || child.signalCode !== null) {
+                    resolve();
+                    return;
+                }
+                const done = () => resolve();
+                child.once("exit", done);
+                const t = setTimeout(done, 2000);
+                t.unref?.();
+            });
+        },
+        killSync: () => {
+            stopRequested = true;
+            if (child !== undefined)
+                killGroup(child);
+        },
+    };
+    try {
+        child = spawn(command, args, { detached: true, shell: useShell, stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch (e) {
+        handle.error = `cannot start ${spec.raw}: ${e instanceof Error ? e.message : String(e)}`;
+        return handle;
+    }
+    handle.opened = true;
+    const deliver = lineSplitter(boundedOnLine(handle, opts));
+    child.stdout.on("data", deliver);
+    child.stderr.on("data", deliver); // most backends interleave logs on stderr too (docker logs does)
+    child.on("error", (e) => {
+        handle.error = `${spec.raw}: ${e.message}`;
+    });
+    // Startup health check (#169): `docker logs -f <container>` on a container that isn't running (or
+    // doesn't exist) exits almost immediately with a non-zero code — its stderr ("Error: No such
+    // container: …") would otherwise just look like an ordinary, if odd, log line and count toward
+    // `linesRead`, hiding the failure. An early non-zero exit is decisive regardless of what was piped
+    // through in the meantime: this source was never actually tailing the backend.
+    //
+    // #199: BUT only when the child died on its own. `close()`/`killSync()` set `stopRequested` before
+    // signaling, so an exit that lands after WE asked this source to stop (mission end) is a normal
+    // end of tailing — never a failure, whatever code/signal the child reports for handling its own
+    // termination (SIGTERM commonly comes back as a self-reported exit code like 143, not `signal`).
+    child.on("exit", (code, signal) => {
+        if (stopRequested)
+            return;
+        if (code !== null && code !== 0 && handle.error === undefined) {
+            handle.error = `${spec.raw}: exited with code ${code}${signal === null ? "" : ` (signal ${signal})`} — the source may not be running`;
+        }
+    });
+    child.unref();
+    return handle;
+}
+/**
+ * Opens one already-validated `--log-source`. Never throws: an unreadable/unspawnable source comes
+ * back with `.error` set rather than aborting a run that has other sources (the caller decides
+ * whether that's fatal — a `--log-defect` oracle must not count an unreadable source as "held").
+ */
+export function openLogSource(spec, opts) {
+    if (spec.kind === "file")
+        return openFileSource(spec, opts);
+    if (spec.kind === "docker")
+        return openProcessSource(spec, "docker", ["logs", "-f", "--since", "0s", spec.container], opts, false);
+    return openProcessSource(spec, spec.command, [], opts, true);
+}
+export function openLogSources(specs, opts) {
+    return specs.map((spec) => openLogSource(spec, opts));
+}
+/** Closes every handle, best-effort, in parallel. Never throws. */
+export async function closeLogSources(handles) {
+    await Promise.all(handles.map((h) => h.close().catch(() => undefined)));
+}
+//# sourceMappingURL=log-sources.js.map

package/dist/log-sources.js.map

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

package/dist/logs-cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CliDeps } from "./cli-shared.js";
+export declare function registerLogsCommands(program: Command, deps: CliDeps): void;

package/dist/logs-cli.js

@@ -0,0 +1,51 @@
+import { ok, fail } from "./envelope.js";
+import { LogsConfigError, loadLogsRetention, pruneLogs } from "./logs-retention.js";
+import { logsRoot } from "./project-dir.js";
+import { resolveDataDir } from "./data-dir.js";
+import { emitJson } from "./cli-shared.js";
+/** The commands that write run output under `.jevitate/logs` — pruned before, when auto-prune is on. */
+const LOG_WRITING_COMMANDS = new Set(["explore", "explore-author-journey", "record", "ux", "check", "run", "verify-fix", "capture"]);
+export function registerLogsCommands(program, deps) {
+    const configPath = deps.logs?.configPath ?? resolveDataDir(["config.json"]);
+    if (deps.logs?.autoPrune === true) {
+        program.hook("preAction", (_root, action) => {
+            if (!LOG_WRITING_COMMANDS.has(action.name()))
+                return;
+            // A malformed retention config fails closed (the command is refused); a file that cannot be
+            // deleted is housekeeping, not the run's business: it is reported and the command goes on.
+            const retention = loadLogsRetention(configPath);
+            try {
+                pruneLogs(deps.logs?.logsRoot ?? logsRoot(), retention);
+            }
+            catch (e) {
+                process.stderr.write(`warning: log pruning skipped: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
+        });
+    }
+    const logs = program.command("logs").description("run output under .jevitate/logs (dated; pruned by retention)");
+    logs
+        .command("prune")
+        .description("delete runs older than the retention TTL, always keeping the newest runs (config.json logs.ttlDays / logs.keepLatest; defaults 14 and 50)")
+        .option("--dir <dir>", "logs root to prune (default: the project's .jevitate/logs, else ~/.jevitate/logs)")
+        .option("--dry-run", "list what would be deleted, deleting nothing")
+        .option("--json", "emit a JSON envelope")
+        .action(function () {
+        const o = this.opts();
+        try {
+            const retention = loadLogsRetention(configPath);
+            const report = pruneLogs(o.dir ?? deps.logs?.logsRoot ?? logsRoot(), retention, { ...(o.dryRun === true ? { dryRun: true } : {}) });
+            const data = { ...report, retention, dryRun: o.dryRun === true };
+            if (o.json === true)
+                emitJson(program, ok(data));
+            else
+                program.configureOutput().writeOut?.(`${o.dryRun === true ? "would remove" : "removed"} ${report.removed.length} run(s); kept ${report.keptRuns} (ttl ${retention.ttlDays}d, keep latest ${retention.keepLatest})\n`);
+        }
+        catch (err) {
+            if (err instanceof LogsConfigError)
+                emitJson(program, fail(err.code, err.message));
+            else
+                emitJson(program, fail("E_LOGS_PRUNE", err instanceof Error ? err.message : String(err)));
+        }
+    });
+}
+//# sourceMappingURL=logs-cli.js.map

package/dist/logs-cli.js.map

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

package/dist/logs-retention.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Retention for run output under `.jevitate/logs/<date>/` (0.2.0): a run older than `ttlDays` is
+ * deleted, but the newest `keepLatest` runs are always kept, so a quiet project is never wiped.
+ * A run is every file and folder sharing its artifact stem (`explore-2026-09-25T01-26-29-787Z.*`).
+ * Pruned at the start of each command that writes logs, or on demand with `jevitate logs prune`.
+ * Configured in `~/.jevitate/config.json`: `{ "logs": { "ttlDays": 14, "keepLatest": 50 } }`.
+ */
+export interface LogsRetention {
+    readonly ttlDays: number;
+    readonly keepLatest: number;
+}
+export declare const DEFAULT_LOGS_RETENTION: LogsRetention;
+export declare class LogsConfigError extends Error {
+    readonly code: "E_LOGS_CONFIG";
+}
+/** The `logs` section of the config file; the defaults when the file or section is absent. A malformed value fails closed. */
+export declare function loadLogsRetention(path?: string): LogsRetention;
+export interface PruneReport {
+    readonly root: string;
+    /** Runs deleted (`<date>/<stem>`). */
+    readonly removed: string[];
+    readonly keptRuns: number;
+}
+/** Applies `retention` to the logs under `root`. `dryRun` reports what would go, deleting nothing. */
+export declare function pruneLogs(root: string, retention: LogsRetention, opts?: {
+    readonly nowMs?: number;
+    readonly dryRun?: boolean;
+}): PruneReport;

package/dist/logs-retention.js

@@ -0,0 +1,84 @@
+import { readFileSync, readdirSync, rmSync, rmdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveDataDir } from "./data-dir.js";
+export const DEFAULT_LOGS_RETENTION = { ttlDays: 14, keepLatest: 50 };
+export class LogsConfigError extends Error {
+    code = "E_LOGS_CONFIG";
+}
+/** The `logs` section of the config file; the defaults when the file or section is absent. A malformed value fails closed. */
+export function loadLogsRetention(path = resolveDataDir(["config.json"])) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        if (typeof e === "object" && e !== null && "code" in e && e.code === "ENOENT")
+            return DEFAULT_LOGS_RETENTION;
+        throw new LogsConfigError(`cannot read ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new LogsConfigError(`${path} is not valid JSON`);
+    }
+    const logs = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed.logs : undefined;
+    if (logs === undefined)
+        return DEFAULT_LOGS_RETENTION;
+    if (logs === null || typeof logs !== "object" || Array.isArray(logs))
+        throw new LogsConfigError(`${path}: "logs" must be an object`);
+    const o = logs;
+    const int = (k) => {
+        const v = o[k];
+        if (v === undefined)
+            return DEFAULT_LOGS_RETENTION[k];
+        if (typeof v !== "number" || !Number.isInteger(v) || v < 0)
+            throw new LogsConfigError(`${path}: logs.${k} must be a non-negative integer, got ${JSON.stringify(v)}`);
+        return v;
+    };
+    return { ttlDays: int("ttlDays"), keepLatest: int("keepLatest") };
+}
+const RUN_KEY = /^([a-z][a-z-]*-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z)/;
+function runsIn(root) {
+    let dates;
+    try {
+        dates = readdirSync(root).filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d));
+    }
+    catch (e) {
+        if (typeof e === "object" && e !== null && "code" in e && e.code === "ENOENT")
+            return { runs: [], dateDirs: [] };
+        throw e;
+    }
+    const byKey = new Map();
+    for (const date of dates) {
+        for (const name of readdirSync(join(root, date))) {
+            const path = join(root, date, name);
+            const key = `${date}/${RUN_KEY.exec(name)?.[1] ?? name}`;
+            const run = byKey.get(key) ?? { paths: [], mtimeMs: 0 };
+            run.paths.push(path);
+            run.mtimeMs = Math.max(run.mtimeMs, statSync(path).mtimeMs);
+            byKey.set(key, run);
+        }
+    }
+    return { runs: [...byKey].map(([key, r]) => ({ key, ...r })), dateDirs: dates.map((d) => join(root, d)) };
+}
+/** 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 { runs, dateDirs } = runsIn(root);
+    const newestFirst = [...runs].sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const cutoff = nowMs - retention.ttlDays * 86_400_000;
+    const doomed = newestFirst.slice(retention.keepLatest).filter((r) => r.mtimeMs < cutoff);
+    if (opts.dryRun !== true) {
+        for (const r of doomed)
+            for (const p of r.paths)
+                rmSync(p, { recursive: true, force: true });
+        for (const d of dateDirs) {
+            if (readdirSync(d).length === 0)
+                rmdirSync(d);
+        }
+    }
+    return { root, removed: doomed.map((r) => r.key).sort(), keptRuns: runs.length - doomed.length };
+}
+//# sourceMappingURL=logs-retention.js.map

package/dist/logs-retention.js.map

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

package/dist/mcp-api.d.ts

@@ -1,6 +1,17 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { type AiGenerateTextArgs, type AiGenerateTextResult } from "@jevitate/mcp-facade";
 import { type CredentialStore, type GenerationPort, type SetupRequiredResult } from "@jevitate/ai-core";
+import type { JudgmentPort, UsageTracker } from "@jevitate/ai-core";
+import type { SelfHealer } from "@jevitate/runtime";
+import type { EmulationSpec } from "@jevitate/playwright";
+import { type RunPolicy } from "@jevitate/domain";
+import { type RunVerifyFixOptions, type VerifyFixReport } from "./verify-fix-api.js";
+import { type BrowserRunOptions } from "./browser-run-options.js";
+import { type ResolvedJourneyEnvironment } from "./environments.js";
+import { type MissionFixtures } from "./mission-fixtures.js";
+import { type ScreenshotsSpec } from "./run-screenshots.js";
+import type { McpCliRunner } from "./mcp-cli-runner.js";
+import { type EngineInfo } from "./engine.js";
 /**
  * The MCP stdio server behind `jevitate mcp`. It exposes ONLY the tools in
  * `@jevitate/mcp-facade`'s `ALLOWED_TOOLS` and structurally CANNOT serve any
@@ -27,12 +38,34 @@ export interface McpTool {
         type: "object";
         properties: Record<string, unknown>;
         required?: string[];
+        additionalProperties?: boolean;
     };
     handler: (args: Record<string, unknown>) => Promise<McpToolResult>;
 }
+/** #255: what an extended `run_journey` call adds — every field resolved and validated by the handler. */
+export interface McpJourneyRunOptions {
+    readonly policy?: RunPolicy;
+    readonly selfHealer?: SelfHealer;
+    readonly environment?: ResolvedJourneyEnvironment;
+    readonly browser?: BrowserRunOptions;
+    readonly emulation?: EmulationSpec;
+    readonly screenshots?: ScreenshotsSpec;
+    readonly fixtures?: (site: string) => MissionFixtures | undefined;
+}
+/**
+ * #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 interface McpApiDeps {
     /** Journeys store directory (`~/.jevitate/journeys` in production). */
     journeysDir: string;
+    /**
+     * The site-policy database (`jevitate site policy set`): `run_journey` is paced, throttled,
+     * budgeted and kept out of quiet hours per the Journey's origin. Absent file = no policy.
+     */
+    sitePolicyDbPath?: string;
     /**
      * Test seam. Defaults to the real promoted-only projection over the
      * journeys store (`@jevitate/mcp-facade`'s `findCapabilities`).
@@ -41,8 +74,37 @@ export interface McpApiDeps {
     /**
      * Test seam. Defaults to `runJourneyProgrammatically` with a fail-closed
      * `safeRunPolicy()` (invariant #5: PUBLISHED-id-only, never inline steps).
+     * `storageState` (#118) is a PATH to a Playwright storageState JSON file — the file is
+     * read only by the server's own browser launch; its contents never enter this handler,
+     * an MCP result, or a log.
+     */
+    runJourney?: (id: string, params: Record<string, string>, storageState?: string, options?: McpJourneyRunOptions) => Promise<unknown>;
+    /**
+     * #255: the directories MCP path arguments (storage states, fixtures, invariants, output dirs)
+     * must resolve inside — default: the project and `~/.jevitate` (mcp-paths.ts).
+     */
+    pathRoots?: readonly string[];
+    /** #255 (`run_journey {env}`): the environments file (default: the repo's `.jevitate/environments.json`). */
+    environmentsFile?: string;
+    /** `~/.jevitate/targets.json` override (environment sessions, verify_fix target config). */
+    targetsConfigPath?: string;
+    /**
+     * #255 (`run_journey {selfHeal: hybrid|full}`): builds the self-heal gateways exactly as the CLI's
+     * `--real`/`--fake-ai` do (`buildExploreGateways`). Absent: a heal mode is refused (setup_required).
+     */
+    selfHealGateways?: (sel: {
+        real: boolean;
+        fakeAi: boolean;
+    }) => Promise<{
+        judge: JudgmentPort;
+        gen: GenerationPort;
+        usage: UsageTracker;
+    }>;
+    /**
+     * #255: the CLI in-process (mcp-cli-runner.ts) — backs every MCP tool that mirrors a CLI command
+     * (mcp-cli-tools.ts). Absent: those tools refuse with `not_configured`.
      */
-    runJourney?: (id: string, params: Record<string, string>) => Promise<unknown>;
+    runCli?: McpCliRunner;
     /**
      * Promoted mission-target store directory (`~/.jevitate/missions/targets` in
      * production — the SAME store `jevitate mission target` writes). Required for
@@ -89,6 +151,32 @@ export interface McpApiDeps {
      * returns a typed `setup_required` result instead of calling the model.
      */
     aiGenerateText?: (args: AiGenerateTextArgs) => Promise<AiGenerateTextResult | SetupRequiredResult>;
+    /**
+     * Directory holding mission artifacts (the logs root in production): the typed
+     * `<id>.result.json` files `get_mission_result` reads. A missing dir is a config refusal.
+     */
+    recordingsDir?: string;
+    /**
+     * Where usability reviews write their artifacts (0.1.0: `~/.jevitate/ux-reports`): a
+     * `usability-<stamp>` result is looked up here after `recordingsDir`.
+     */
+    uxReportsDir?: string;
+    /**
+     * The directories a result id's files may be in, most likely first (production: its dated
+     * `.jevitate/logs/<date>` dir in the project, then `~/.jevitate`, then the 0.1.0 locations).
+     * Replaces `recordingsDir`/`uxReportsDir` for the lookup when given.
+     */
+    resultDirsFor?: (resultId: string) => string[];
+    /**
+     * Test seam. Defaults to `runVerifyFix` over `<recordingsDir>/<id>.result.json`: replays the
+     * finding's repro in a fresh browser (authorized against the mission's own allowlist).
+     */
+    verifyFix?: (args: McpVerifyFixArgs) => Promise<VerifyFixReport>;
+    /**
+     * The serving build's identity (#112) — reported by `initialize` (`serverInfo.version`) and by
+     * `get_site_health`. Defaults to this build's `currentEngineInfo()`.
+     */
+    engine?: EngineInfo;
 }
 /**
  * Builds the served tool descriptors — EXACTLY one per `ALLOWED_TOOLS` entry.