@jevitate/cli 0.7.0 → 0.9.0

package/dist/login-cli.js

@@ -0,0 +1,161 @@
+import { redactUrl } from "@jevitate/ai-core";
+import { normalizeAllowlist } from "@jevitate/explore";
+import { PlaywrightBrowserPort } from "@jevitate/playwright";
+import { fail, ok } from "./envelope.js";
+import { emitCommandResult } from "./cli-shared.js";
+import { positiveIntArg } from "./cli-args.js";
+import { loadPersonasFile, MultiRunArgsError, projectPersonas } from "./multi-run.js";
+import { apiVerifyUrl, checkSaveTarget, LoginArgsError, LoginFailedError, loginFromFlags, mintStorageState, parseAuthCheck } from "./persona-login.js";
+const DEFAULT_TIMEOUT_S = 30;
+const PERSONA_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+function formatLoginHuman(data) {
+    const r = data;
+    return `signed in${r.persona === undefined ? "" : ` as persona ${r.persona}`}${r.method === "api" ? " through the API" : ""} (${r.userEnv}/${r.passwordEnv}) — storage state saved to ${r.saved} (mode 0600)\n`;
+}
+/** The persona's declared login parameters and session, from `--personas` or the project's `.jevitate/personas.json`. */
+function declaredPersona(name, personasFile) {
+    const all = personasFile === undefined ? projectPersonas() : loadPersonasFile(personasFile);
+    return all.find((p) => p.name === name);
+}
+export function registerLoginCommand(program, deps) {
+    program
+        .command("login")
+        .description("#427: sign in as a persona with credentials from environment variables and save its Playwright storage state (mode 0600) — " +
+        "the session `explore --storage-state/--persona` starts from. Credentials are never accepted as values, never printed or recorded")
+        .option("--persona <name>", "the persona being signed in (names it in the result); with a declared persona (--personas or .jevitate/personas.json) its login parameters and storage state path are the defaults")
+        .option("--personas <file>", "personas JSON to read --persona's login parameters from (default: the project's .jevitate/personas.json)")
+        .option("--url <loginUrl>", "the sign-in page (must be an authorized origin: its own, or --allow)")
+        .option("--api <url>", "#449: sign in through this HTTP endpoint instead of a form: the credentials are POSTed as JSON (must be an authorized origin; redirects are never followed)")
+        .option("--api-user-key <key>", "with --api: the JSON body key the username is sent under (default username)")
+        .option("--api-password-key <key>", "with --api: the JSON body key the password is sent under (default password)")
+        .option("--token-path <path>", "with --api: a dotted path into the JSON response whose value is the session token (e.g. token, data.accessToken); without it the response's cookies are the session")
+        .option("--storage-key <key>", "with --token-path: the localStorage key the token is written under (default: the path's last segment)")
+        .option("--storage <where>", "with --token-path: local (the only choice — a Playwright storage state has no sessionStorage)")
+        .option("--verify-url <url>", "with --api: the app page the new session is proven on, and whose origin receives the token (default: the endpoint's origin root)")
+        .option("--auth-check <check>", "with --api: how --verify-url proves the session: off | auto | urlExcludes:<text> | selector:<css> (default auto)")
+        .option("--user-env <VAR>", "environment variable holding the username (its NAME — the value is read from the environment)")
+        .option("--password-env <VAR>", "environment variable holding the password (its NAME — the value is read from the environment)")
+        .option("--user-field <field>", "the username field: its label, else a CSS selector (default: found by autocomplete/type/name)")
+        .option("--password-field <field>", "the password field: its label, else a CSS selector (default: the visible password input)")
+        .option("--submit <name>", "the submit button's accessible name (default: the form's submit button, else Enter)")
+        .option("--success <check>", "how a successful sign-in is recognised: urlIncludes:<text> | selector:<css> | text:<text> (default: the page leaves the sign-in form — no login-like URL, no password field)")
+        .option("--save <file>", "where to write the storage state (parent directory created; mode 0600; never inside a repo's .jevitate/)")
+        .option("--allow <origin>", "an origin credentials may be typed into (repeatable; default: the sign-in page's own) — e.g. an SSO provider", (v, prev) => [...prev, v], [])
+        .option("--timeout <seconds>", `how long each step of the sign-in may take (default ${DEFAULT_TIMEOUT_S})`, positiveIntArg)
+        .option("--json", "emit a JSON envelope")
+        .action(async function () {
+        const o = this.opts();
+        const emit = (envelope) => emitCommandResult(program, envelope, { json: o.json === true, command: "login", human: formatLoginHuman });
+        let login;
+        let save;
+        let warnings;
+        let authCheck;
+        try {
+            if (o.persona !== undefined && !PERSONA_NAME.test(o.persona)) {
+                throw new LoginArgsError(`--persona ${JSON.stringify(o.persona)} must be 1-64 of [A-Za-z0-9_.-], starting alphanumeric`);
+            }
+            const declared = o.persona === undefined ? undefined : declaredPersona(o.persona, o.personas);
+            if (o.personas !== undefined && o.persona === undefined)
+                throw new LoginArgsError("--personas reads a declared persona's login parameters: pass --persona <name> too");
+            if (o.personas !== undefined && declared === undefined)
+                throw new LoginArgsError(`persona ${o.persona} is not declared in ${o.personas}`);
+            const base = declared?.login;
+            const apiFlags = [
+                ["--api-user-key", o.apiUserKey],
+                ["--api-password-key", o.apiPasswordKey],
+                ["--token-path", o.tokenPath],
+                ["--storage-key", o.storageKey],
+                ["--storage", o.storage],
+                ["--verify-url", o.verifyUrl],
+                ["--auth-check", o.authCheck],
+            ]
+                .filter(([, v]) => v !== undefined)
+                .map(([k]) => k);
+            if (o.api !== undefined && o.url !== undefined)
+                throw new LoginArgsError("--api and --url are two ways to sign in: pass one");
+            const viaApi = o.api !== undefined || (o.url === undefined && base?.api !== undefined);
+            if (!viaApi && apiFlags.length > 0)
+                throw new LoginArgsError(`${apiFlags.join(", ")} ${apiFlags.length === 1 ? "applies" : "apply"} to a sign-in through an HTTP endpoint: pass --api <url> too`);
+            authCheck = parseAuthCheck(o.authCheck);
+            const url = viaApi ? undefined : (o.url ?? base?.url);
+            const apiUrl = viaApi ? (o.api ?? base?.api?.url) : undefined;
+            const userEnv = o.userEnv ?? base?.userEnv;
+            const passwordEnv = o.passwordEnv ?? base?.passwordEnv;
+            const target = o.save ?? declared?.storageState;
+            const missing = [url === undefined && apiUrl === undefined ? "--url (or --api)" : null, userEnv === undefined ? "--user-env" : null, passwordEnv === undefined ? "--password-env" : null, target === undefined ? "--save" : null].filter((m) => m !== null);
+            if (missing.length > 0) {
+                throw new LoginArgsError(`missing ${missing.join(", ")}${o.persona === undefined ? "" : ` (persona ${o.persona} declares no login parameters for ${missing.length === 1 ? "it" : "them"})`}`);
+            }
+            const b = base?.api;
+            login = loginFromFlags({
+                ...(url === undefined ? {} : { url }),
+                ...(apiUrl === undefined
+                    ? {}
+                    : {
+                        api: {
+                            url: apiUrl,
+                            userKey: o.apiUserKey ?? b?.userKey,
+                            passwordKey: o.apiPasswordKey ?? b?.passwordKey,
+                            tokenPath: o.tokenPath ?? b?.tokenPath,
+                            // A declared storage key belongs to the declared token path: a --token-path flag takes its own default.
+                            storageKey: o.storageKey ?? (o.tokenPath === undefined ? b?.storageKey : undefined),
+                            storage: o.storage,
+                            verifyUrl: o.verifyUrl ?? b?.verifyUrl,
+                        },
+                    }),
+                userEnv: userEnv,
+                passwordEnv: passwordEnv,
+                ...pick("userField", o.userField ?? (viaApi ? undefined : base?.userField)),
+                ...pick("passwordField", o.passwordField ?? (viaApi ? undefined : base?.passwordField)),
+                ...pick("submit", o.submit ?? (viaApi ? undefined : base?.submit)),
+                ...pick("success", o.success ?? (viaApi ? undefined : base?.success)),
+            });
+            ({ path: save, warnings } = checkSaveTarget(target, "--save"));
+        }
+        catch (err) {
+            if (err instanceof LoginArgsError || err instanceof MultiRunArgsError) {
+                emit(fail("E_LOGIN_ARGS", err.message));
+                return;
+            }
+            throw err;
+        }
+        const loginUrl = login.api?.url ?? login.url;
+        const allowlist = o.allow.length > 0 ? normalizeAllowlist(o.allow) : normalizeAllowlist([loginUrl]);
+        for (const w of warnings)
+            program.configureOutput().writeErr?.(`warning: ${w}\n`);
+        try {
+            const minted = await mintStorageState({
+                login,
+                save,
+                allowlist,
+                env: deps.explore?.env ?? process.env,
+                port: (deps.explore?.browserPortFactory ?? (() => new PlaywrightBrowserPort()))(),
+                timeoutMs: (o.timeout ?? DEFAULT_TIMEOUT_S) * 1000,
+                ...(login.api === undefined ? {} : { verify: { url: apiVerifyUrl(login.api), check: authCheck } }),
+            });
+            const result = {
+                ...(o.persona === undefined ? {} : { persona: o.persona }),
+                saved: minted.saved,
+                loginUrl: redactUrl(loginUrl),
+                method: login.api === undefined ? "form" : "api",
+                landedUrl: minted.landedUrl,
+                userEnv: login.userEnv,
+                passwordEnv: login.passwordEnv,
+                warnings,
+            };
+            emit(ok(result));
+        }
+        catch (err) {
+            if (err instanceof LoginArgsError)
+                emit(fail("E_LOGIN_ARGS", err.message));
+            else if (err instanceof LoginFailedError)
+                emit(fail("E_LOGIN_FAILED", err.message));
+            else
+                throw err;
+        }
+    });
+}
+function pick(k, v) {
+    return (v === undefined ? {} : { [k]: v });
+}
+//# sourceMappingURL=login-cli.js.map

package/dist/login-cli.js.map

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

package/dist/logs-cli.js

@@ -1,3 +1,4 @@
+import { JEV_PROVIDER_FLAG_HELP, jevProviderArg } from "./cli-shared.js";
 import { ok, fail } from "./envelope.js";
 import { LogsConfigError, loadLogsRetention, pruneLogs } from "./logs-retention.js";
 import { logsRoot } from "./project-dir.js";
@@ -60,6 +61,7 @@ export function registerLogsCommands(program, deps) {
         .option("--threshold <p>", "Jev relevance probability at or above which a line is kept (default 0.5)", (v) => Number(v))
         .option("--real", "score relevance with the live Jev gateway (requires keys; log text goes to the judgment model, redacted)", false)
         .option("--fake-ai", "no model: keep the correlated lines and the window's error/warning lines (code only)", false)
+        .option("--jev-provider <provider>", JEV_PROVIDER_FLAG_HELP, jevProviderArg)
         .option("--json", "emit a JSON envelope")
         .action(async function () {
         const o = this.opts();
@@ -87,7 +89,7 @@ export function registerLogsCommands(program, deps) {
             const file = JSON.parse(readFileSync(o.result, "utf8"));
             if (typeof file.result !== "object" || file.result === null)
                 return emit(fail("E_LOGS_ARGS", `${o.result} is not a jevitate run result`));
-            const judge = o.real === true ? (await buildExploreGateways(deps, { real: true, fakeAi: false })).judge : undefined;
+            const judge = o.real === true ? (await buildExploreGateways(deps, { real: true, fakeAi: false, jevProvider: o.jevProvider })).judge : undefined;
             const updated = await triageRunResult(file.result, o.result, {
                 secrets,
                 ...(judge === undefined ? {} : { judge }),

package/dist/logs-cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"logs-cli.js","sourceRoot":"","sources":["../src/logs-cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAgB,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,wGAAwG;AACxG,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,wBAAwB,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;AAErI,MAAM,UAAU,oBAAoB,CAAC,OAAgB,EAAE,IAAa;IAClE,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5E,IAAI,IAAI,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YAC1C,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBAAE,OAAO;YACrD,4FAA4F;YAC5F,2FAA2F;YAC3F,MAAM,SAAS,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;YAChD,IAAI,CAAC;gBACH,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,IAAI,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC;YAC1D,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACxG,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,8DAA8D,CAAC,CAAC;IACjH,IAAI;SACD,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,2IAA2I,CAAC;SACxJ,MAAM,CAAC,aAAa,EAAE,mFAAmF,CAAC;SAC1G,MAAM,CAAC,WAAW,EAAE,8CAA8C,CAAC;SACnE,MAAM,CAAC,QAAQ,EAAE,sBAAsB,CAAC;SACxC,MAAM,CAAC;QACN,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAsD,CAAC;QAC1E,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;YAChD,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,IAAI,QAAQ,EAAE,EAAE,SAAS,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACpI,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACjE,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI;gBAAE,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;;gBAC5C,OAAO,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,iBAAiB,MAAM,CAAC,QAAQ,SAAS,SAAS,CAAC,OAAO,kBAAkB,SAAS,CAAC,UAAU,KAAK,CAAC,CAAC;QAC7N,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,eAAe;gBAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;;gBAC9E,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACjG,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,IAAI;SACD,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CACV,0JAA0J;QACxJ,4KAA4K,CAC/K;SACA,cAAc,CAAC,iBAAiB,EAAE,2EAA2E,CAAC;SAC9G,MAAM,CAAC,0BAA0B,EAAE,iGAAiG,EAAE,CAAC,CAAS,EAAE,IAAc,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,EAAc,CAAC;SAClM,MAAM,CAAC,iBAAiB,EAAE,0EAA0E,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;SAC/H,MAAM,CAAC,QAAQ,EAAE,0GAA0G,EAAE,KAAK,CAAC;SACnI,MAAM,CAAC,WAAW,EAAE,sFAAsF,EAAE,KAAK,CAAC;SAClH,MAAM,CAAC,QAAQ,EAAE,sBAAsB,CAAC;SACxC,MAAM,CAAC,KAAK;QACX,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAA8G,CAAC;QAClI,MAAM,IAAI,GAAG,CAAC,QAAwC,EAAQ,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC7F,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,kEAAkE,CAAC,CAAC,CAAC;QAC/I,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,2CAA2C,CAAC,CAAC,CAAC;QACxJ,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,sBAAsB,CAAC,CAAC,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,yDAAyD,CAAC,CAAC,CAAC;QACzJ,CAAC;QACD,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,iBAAiB,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YACtE,IAAI,QAAQ,CAAC,QAAQ,GAAG,CAAC;gBAAE,OAAO,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,sBAAsB,CAAC,CAAC;YACxF,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,cAAc;gBAAE,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACjF,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAyC,CAAC;YAChG,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,MAAM,+BAA+B,CAAC,CAAC,CAAC;YAC1I,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,oBAAoB,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;YACpH,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;gBAC3D,OAAO;gBACP,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;gBACzC,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;aACjE,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAA6D,CAAC;YACpI,MAAM,IAAI,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;YACjK,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI;gBAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;iBAC/B,CAAC;gBACJ,MAAM,CAAC,GAAG,OAAO,CAAC,OAA4G,CAAC;gBAC/H,OAAO,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,WAAW,OAAO,CAAC,MAAM,mBAAmB,CAAC,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,UAAU,uBAAuB,CAAC,CAAC,MAAM,CAAC,QAAQ,0BAA0B,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;YAC1P,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChF,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"logs-cli.js","sourceRoot":"","sources":["../src/logs-cli.ts"],"names":[],"mappings":"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"}

package/dist/mcp-api.d.ts

@@ -2,7 +2,7 @@ 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 { ChangeScope, 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";
@@ -46,6 +46,10 @@ export interface McpTool {
 export interface McpJourneyRunOptions {
     readonly policy?: RunPolicy;
     readonly selfHealer?: SelfHealer;
+    /** #453: the change context a hybrid/full self-heal is explained by (`changes`/`changeNote`). */
+    readonly heal?: {
+        readonly scope: ChangeScope;
+    };
     readonly environment?: ResolvedJourneyEnvironment;
     readonly browser?: BrowserRunOptions;
     readonly emulation?: EmulationSpec;
@@ -97,6 +101,7 @@ export interface McpApiDeps {
     selfHealGateways?: (sel: {
         real: boolean;
         fakeAi: boolean;
+        jevProvider?: string | undefined;
     }) => Promise<{
         judge: JudgmentPort;
         gen: GenerationPort;

package/dist/mcp-api.js

@@ -12,7 +12,8 @@ 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 { RunTagError, JOURNEY_RUN_OUTCOMES, journeyExitCode, safeRunPolicy as defaultRunPolicy, validateRunTags } from "@jevitate/domain";
+import { stampRunMetadata, withRunMetadata } from "./run-metadata.js";
 import { JourneyRequiresAuthError, UnknownJourneyError, runJourneyProgrammatically } from "./journey-api.js";
 import { runVerifyFix } from "./verify-fix-api.js";
 import { ExtensionMismatchError } from "./browser-run-options.js";
@@ -21,7 +22,9 @@ 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 { makeEvidenceSelfHealer } from "./self-heal-adapter.js";
+import { JourneyHealArgsError, MCP_HEAL_NAMES, journeyHealBudget, readJourneyChangeScope, validateJourneyHeal } from "./journey-heal.js";
+import { ChangesArgsError, ChangesInputError } from "./change-context.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";
@@ -49,6 +52,15 @@ function assertAllowlisted(name) {
         throw new Error(`refusing to serve non-allowlisted tool '${name}'`);
     }
 }
+/** #453: a Journey run result with the CLI's exit code for its outcome (anything else unchanged). */
+function withJourneyExitCode(result) {
+    if (result === null || typeof result !== "object")
+        return result;
+    const outcome = result.outcome;
+    if (typeof outcome !== "string" || !JOURNEY_RUN_OUTCOMES.includes(outcome))
+        return result;
+    return { ...result, exitCode: journeyExitCode(outcome) };
+}
 function jsonResult(value) {
     return { content: [{ type: "text", text: JSON.stringify(value) }] };
 }
@@ -64,6 +76,16 @@ function goalOutcomeOf(file) {
     const result = file.result;
     return result !== null && typeof result === "object" && "goalOutcome" in result ? result.goalOutcome : undefined;
 }
+/** #423: a persisted result's `defectOutcome.status` (`none`/`defects`), when present. */
+function defectStatusOf(file) {
+    const outcome = resultField(file, "defectOutcome");
+    return outcome !== null && typeof outcome === "object" && "status" in outcome ? outcome.status : undefined;
+}
+/** One field of a persisted result's `result` object, else undefined. */
+function resultField(file, key) {
+    const result = file.result;
+    return result !== null && typeof result === "object" && key in result ? result[key] : undefined;
+}
 /** A model-backed option was asked for without usable gateways/keys (typed `setup_required`). */
 class SetupRequired extends Error {
 }
@@ -99,6 +121,7 @@ export function buildMcpTools(deps) {
             ...(storageState !== undefined ? { storageState } : {}),
             ...(siteGate === undefined ? {} : { siteGate }),
             ...(o?.selfHealer === undefined ? {} : { selfHealer: o.selfHealer }),
+            ...(o?.heal === undefined ? {} : { heal: o.heal }),
             ...(o?.environment === undefined ? {} : { environment: o.environment }),
             ...(o?.browser === undefined ? {} : { browser: o.browser }),
             ...(o?.emulation === undefined ? {} : { emulation: o.emulation }),
@@ -267,14 +290,21 @@ export function buildMcpTools(deps) {
         }
         // #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))
+            ? parseResultOutcome(parsed.missionOutcome, goalOutcomeOf(parsed), defectStatusOf(parsed))
             : null;
         if (parsedOutcome === null) {
             return errorResult({ error: "corrupt_result", ...ids });
         }
+        // #423: the two orthogonal verdicts beside the status — did the goal get reached (goalOutcome +
+        // goalReason) and did the app break (defectOutcome, counted by kind) — read from the structured
+        // result, never from its `reason` prose.
+        const goalReason = resultField(parsed, "goalReason");
+        const defectOutcome = resultField(parsed, "defectOutcome");
         const status = {
             ...missionStatus(parsedOutcome.outcome),
             ...(parsedOutcome.goalOutcome === undefined ? {} : { goalOutcome: parsedOutcome.goalOutcome }),
+            ...(typeof goalReason === "string" ? { goalReason } : {}),
+            ...(defectOutcome !== null && typeof defectOutcome === "object" ? { defectOutcome } : {}),
         };
         const result = parsed.result ?? null;
         // An adversarial run's coverage is surfaced next to the status: an `inconclusive` run says what
@@ -345,6 +375,19 @@ export function buildMcpTools(deps) {
             throw new McpArgError(err instanceof Error ? err.message : String(err));
         }
     };
+    /** #426: the run tools' `tags` object — validated like `--tag` (an invalid one is invalid_args, never dropped). */
+    const tagsArg = (args) => {
+        if (args.tags === undefined)
+            return { tags: {} };
+        try {
+            return { tags: validateRunTags(args.tags, "tags") };
+        }
+        catch (err) {
+            if (!(err instanceof RunTagError))
+                throw err;
+            return { error: { error: "invalid_args", code: err.code, message: err.message } };
+        }
+    };
     const verifyFixTool = async (args) => {
         if (!deps.recordingsDir) {
             return errorResult({ error: "not_configured", message: "verify_fix requires recordingsDir" });
@@ -354,6 +397,9 @@ export function buildMcpTools(deps) {
             !/^[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'" });
         }
+        const tagged = tagsArg(args);
+        if ("error" in tagged)
+            return errorResult(tagged.error);
         let options;
         try {
             options = verifyFixOptions(args);
@@ -387,13 +433,14 @@ export function buildMcpTools(deps) {
             }
         }
         try {
-            const report = await verifyFixImpl({ ...options, resultPath, fingerprint: args.fingerprint });
-            const body = {
+            const fingerprint = args.fingerprint;
+            const report = await withRunMetadata({ tags: tagged.tags }, () => verifyFixImpl({ ...options, resultPath, fingerprint }));
+            const body = stampRunMetadata({
                 id: args.id,
                 ...(ref.missionId === undefined ? {} : { missionId: ref.missionId, resultId: ref.resultId }),
                 status: report.verdict,
                 ...report,
-            };
+            }, { tags: tagged.tags });
             // 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);
@@ -460,22 +507,44 @@ export function buildMcpTools(deps) {
         const selfHeal = optEnum(args, "selfHeal", ["fail-closed", "hybrid", "full"]) ?? "fail-closed";
         const real = optBool(args, "real") ?? false;
         const fakeAi = optBool(args, "fakeAi") ?? false;
+        // #429: the Jev provider for self-heal judgments (typesafe | openrouter), as `--jev-provider`.
+        const jevProvider = optEnum(args, "jevProvider", ["typesafe", "openrouter"]);
+        // #453 Q1: the same refusals as `journey run` — a heal needs a change context, the change and
+        // budget arguments need a heal — before any gateway, Journey lookup or browser.
+        const changes = optString(args, "changes");
+        const healMaxAttempts = optInt(args, "healMaxAttempts", 1);
+        const healMaxModelCalls = optInt(args, "healMaxModelCalls", 1);
+        const healMaxMs = optInt(args, "healMaxMs", 1);
+        const healMaxRunAttempts = optInt(args, "healMaxRunAttempts", 1);
+        const healMaxRunMs = optInt(args, "healMaxRunMs", 1);
+        const healRequest = {
+            selfHeal,
+            ...(changes === undefined ? {} : { changes }),
+            changeNotes: optStringArray(args, "changeNote") ?? [],
+            ...(healMaxAttempts === undefined ? {} : { maxAttempts: healMaxAttempts }),
+            ...(healMaxModelCalls === undefined ? {} : { maxModelCalls: healMaxModelCalls }),
+            ...(healMaxMs === undefined ? {} : { maxMs: healMaxMs }),
+            ...(healMaxRunAttempts === undefined ? {} : { maxRunAttempts: healMaxRunAttempts }),
+            ...(healMaxRunMs === undefined ? {} : { maxRunMs: healMaxRunMs }),
+        };
+        validateJourneyHeal(healRequest, MCP_HEAL_NAMES);
+        const healScope = selfHeal === "fail-closed" ? undefined : await readJourneyChangeScope(healRequest, deps.journeysDir);
         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;
+            // #453: the healer is evidence-only — its model is an advisory ranker; judgment never decides a heal.
             let gen;
             try {
-                ({ judge, gen, usage } = await deps.selfHealGateways({ real, fakeAi }));
+                ({ gen, usage } = await deps.selfHealGateways({ real, fakeAi, ...(jevProvider === undefined ? {} : { jevProvider }) }));
             }
             catch (err) {
                 throw new SetupRequired(redactCredentials(err instanceof Error ? err.message : String(err), credentialStore));
             }
-            selfHealer = makeExploreSelfHealer(judge, gen);
-            policy = { ...policy, selfHeal: { mode: selfHeal } };
+            selfHealer = makeEvidenceSelfHealer(gen, usage === undefined ? {} : { usage });
+            policy = { ...policy, selfHeal: { mode: selfHeal, budget: journeyHealBudget(healRequest) } };
         }
         return {
             params,
@@ -484,6 +553,7 @@ export function buildMcpTools(deps) {
                 policy,
                 fixtures,
                 ...(selfHealer === undefined ? {} : { selfHealer }),
+                ...(healScope === undefined ? {} : { heal: { scope: healScope } }),
                 ...(environment === undefined ? {} : { environment }),
                 ...(browser === undefined ? {} : { browser }),
                 ...(emulation === undefined ? {} : { emulation }),
@@ -498,7 +568,7 @@ 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'); 'geolocation' '<lat>,<lng>[,<accuracy m>]' (#329); " +
-                "'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.",
+                "'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); 'tags' (#426: {key: value} run metadata, returned on the result — never a secret). 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: {
@@ -521,6 +591,7 @@ export function buildMcpTools(deps) {
                     extension: { type: "array", items: { type: "string" } },
                     maxBrowsers: { type: "integer", minimum: 1 },
                     maxBrowserMemory: { type: "integer", minimum: 1 },
+                    tags: { type: "object", additionalProperties: { type: "string" } },
                 },
                 required: ["id", "fingerprint"],
             },
@@ -544,7 +615,7 @@ export function buildMcpTools(deps) {
                 "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); 'geolocation' '<lat>,<lng>[,<accuracy m>]' (#329); '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}.",
+                "'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; 'jevProvider' typesafe | openrouter picks the Jev key with real, #429) — #453: a heal mode needs a change context, 'changes' (a git range such as HEAD~1..HEAD, read-only) and/or 'changeNote' (strings), else it is refused; only a break that change explains is retargeted, one-for-one, and the run ends healed-pending-review (exitCode 5: a proposed revision a person accepts, never a pass); budgets 'healMaxAttempts'/'healMaxModelCalls'/'healMaxMs' (per broken step) and 'healMaxRunAttempts'/'healMaxRunMs' (per run), each >= 1; the result's 'exitCode' is the CLI's (0 ok, 5 pending review, 1 failed); '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); 'tags' (#426: {key: value} run metadata, returned on the result — never a secret). A site-policy refusal is {error: throttled, retryAfter}.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -563,12 +634,21 @@ export function buildMcpTools(deps) {
                     fixtures: { type: "string" },
                     fixtureIdentity: { type: "array", items: { type: "string" } },
                     selfHeal: { type: "string", enum: ["fail-closed", "hybrid", "full"] },
+                    changes: { type: "string" },
+                    changeNote: { type: "array", items: { type: "string" } },
+                    healMaxAttempts: { type: "integer", minimum: 1 },
+                    healMaxModelCalls: { type: "integer", minimum: 1 },
+                    healMaxMs: { type: "integer", minimum: 1 },
+                    healMaxRunAttempts: { type: "integer", minimum: 1 },
+                    healMaxRunMs: { type: "integer", minimum: 1 },
                     real: { type: "boolean" },
                     fakeAi: { type: "boolean" },
+                    jevProvider: { type: "string", enum: ["typesafe", "openrouter"] },
                     extension: { type: "array", items: { type: "string" } },
                     maxBrowsers: { type: "integer", minimum: 1 },
                     maxBrowserMemory: { type: "integer", minimum: 1 },
                     actionDeltas: { type: "boolean" },
+                    tags: { type: "object", additionalProperties: { type: "string" } },
                 },
                 required: ["id"],
             },
@@ -576,6 +656,9 @@ 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'" });
                 }
+                const tagged = tagsArg(args);
+                if ("error" in tagged)
+                    return errorResult(tagged.error);
                 // 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;
@@ -586,6 +669,9 @@ export function buildMcpTools(deps) {
                     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 JourneyHealArgsError || err instanceof ChangesArgsError || err instanceof ChangesInputError) {
+                        return errorResult({ error: "invalid_args", code: err.code, message: err.message });
+                    }
                     if (err instanceof SetupRequired)
                         return errorResult({ error: "setup_required", message: err.message });
                     throw err;
@@ -595,9 +681,12 @@ export function buildMcpTools(deps) {
                 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() });
+                    const id = args.id;
+                    const result = await withRunMetadata({ tags: tagged.tags }, () => runJourney(id, resolved.params, resolved.storageState, resolved.options));
+                    // #163: a self-healing run's model usage lands on its result, as on the CLI. #426: so do its tags.
+                    const withUsage = resolved.usage === undefined || result === null || typeof result !== "object" ? result : { ...result, usage: resolved.usage.snapshot() };
+                    // #453: the CLI's exit code for the outcome — 0 ok, 5 healed-pending-review (a proposed revision, never a pass), 1 otherwise.
+                    return jsonResult(stampRunMetadata(withJourneyExitCode(withUsage), { tags: tagged.tags }));
                 }
                 catch (err) {
                     // A site-policy refusal (throttle, budget, quiet hours) is an answer the agent acts on — when to retry.
@@ -624,7 +713,7 @@ export function buildMcpTools(deps) {
             },
         },
         queue_exploration: {
-            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`.",
+            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). #424: 'minEffort' {minActions, minDistinctStates} (goal-based only) — the minimum exploration before the model may conclude, capped by the budget. Same as `jevitate mission queue`.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -658,6 +747,11 @@ export function buildMcpTools(deps) {
                     screenshots: { type: "string", enum: [...QUEUED_SCREENSHOT_MODES] },
                     evidenceVideo: { type: "boolean" },
                     persona: { type: "string" },
+                    // #424 (goal-based only): the minimum exploration effort before the model may conclude.
+                    minEffort: {
+                        type: "object",
+                        properties: { minActions: { type: "number" }, minDistinctStates: { type: "number" } },
+                    },
                 },
                 required: ["target"],
             },