@skyramp/mcp 0.4.2-rc.1 → 0.4.2-rc.2

package/build/tools/executeSkyrampTestTool.js

@@ -1,44 +1,46 @@
 import { z } from "zod";
-import { pendingReuseDebt } from "./code-refactor/reuse-state.js";
-import { assertionFeedbackForExecution, recordAssertionExecution, } from "./code-refactor/assertion-state.js";
-import { stageAndRecordRetrofits } from "./code-refactor/retrofit-state.js";
+import { TestExecutionService } from "../services/TestExecutionService.js";
+import { getWorkspaceBaseUrl } from "../utils/workspaceAuth.js";
+import { spawn } from "child_process";
+import crypto from "crypto";
+import * as fs from "fs";
 import path from "path";
 import { stripVTControlCharacters } from "util";
-import { TestExecutionService } from "../services/TestExecutionService.js";
-import { AnalyticsService } from "../services/AnalyticsService.js";
 import { makeProgressReporter } from "../utils/progress.js";
+import { pendingReuseDebt } from "./code-refactor/reuse-state.js";
+import { assertionFeedbackForExecution, canonicalTestPath, recordAssertionExecution, } from "./code-refactor/assertion-state.js";
+import { stageAndRecordRetrofits } from "./code-refactor/retrofit-state.js";
+import { AnalyticsService } from "../services/AnalyticsService.js";
 import { TestExecutionStatus, } from "../types/TestExecution.js";
-import { getWorkspaceBaseUrl } from "../utils/workspaceAuth.js";
 import { ProgrammingLanguage, TestType } from "../types/TestTypes.js";
-import { StateManager, currentRunStateFile, getTestsRepoDir, resolveOwnRunStatePath, resolveRunStatePath, } from "../utils/AnalysisStateManager.js";
-import { DriftAction, TestSource, } from "../types/TestAnalysis.js";
+import { StateManager, currentRunStateFile, getPrimaryRepository, getTestsRepoDir, resolveOwnRunStatePath, resolveRunStatePath, } from "../utils/AnalysisStateManager.js";
+import { DriftAction, } from "../types/TestAnalysis.js";
 import { logger } from "../utils/logger.js";
 import { toolError } from "../utils/utils.js";
 import { recordExecutionVideo } from "./execution-video-state.js";
 import { stageGeneratedPaths } from "../utils/gitStaging.js";
+import { walkDir } from "../utils/fileWalk.js";
+import { findRepoPlaywrightConfig, writeWrapperConfig, commandPassesBrowserFlag, } from "../execution/wrapperConfig.js";
 import { canonicalStateFilePath, persistTestExecutionResult, readPinnedMaxFixAttempts, readRepoSectionOrThrow, reserveTestExecutionAttempt, stateFileKey, } from "../utils/testExecutionRecord.js";
-import { canonicalTestPath } from "./code-refactor/assertion-state.js";
 import { getMaxFixAttempts } from "../utils/fixAttempts.js";
 import { runSerialized } from "../utils/runSerialized.js";
-import * as fs from "fs";
 import { sha256Of } from "../utils/assertion-verify/index.js";
 import { baselineFileMatchesStem, baselineStem, rebaselineSnapshotNameSchema, snapshotDirFor, } from "../utils/rebaselineSnapshots.js";
-import { EXECUTOR_DOCKER_IMAGE } from "../utils/versions.js";
-const TOOL_NAME = "skyramp_execute_test";
-export const CONTRACT_EXECUTION_MODES = ["provider", "consumer"];
+export const TOOL_NAME = "skyramp_execute_test";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const MAX_TIMEOUT_MS = 3_600_000;
+/** Output kept per run, from its end: it is held in memory, saved to the state file, and returned to the agent. */
+export const MAX_OUTPUT_CHARS = 200_000;
 /**
- * Resolve the effective auth token for test execution.
- * `unauthenticated: true` forces no token (empty string) so the container
- * env omits SKYRAMP_TEST_TOKEN entirely — unauthenticated endpoints won't
- * receive an empty Authorization header that triggers encoding errors (E7).
+ * `unauthenticated: true` forces no token, so the child env carries no
+ * SKYRAMP_TEST_TOKEN at all — an empty Authorization header triggers encoding
+ * errors on unauthenticated endpoints (E7). An empty `token` means "use the
+ * server's environment", as the local-dev prompt passes it.
  */
 export function resolveEffectiveToken(unauthenticated, paramToken, envToken) {
     if (unauthenticated)
         return "";
-    return paramToken ?? envToken ?? "";
-}
-export function shouldInjectSkyrampBaseUrl(testType, contractMode) {
-    return testType !== TestType.CONTRACT || contractMode !== "consumer";
+    return paramToken || envToken || "";
 }
 /**
  * Append the recorded video path to execution output.
@@ -51,6 +53,242 @@ export function shouldInjectSkyrampBaseUrl(testType, contractMode) {
 export function withVideoInfo(output, videoPath) {
     return videoPath ? `${output}\n\nVideo recording: ${videoPath}` : output;
 }
+function isBrowserTest(testType) {
+    return testType === TestType.UI || testType === TestType.E2E;
+}
+/**
+ * One directory per run: a unique name leaves nothing to clean up between runs, and
+ * the random suffix keeps two runs in the same millisecond apart.
+ */
+export function videoSubdirName(testFile) {
+    const basename = path
+        .basename(testFile, path.extname(testFile))
+        .replace(/[^A-Za-z0-9._-]/g, "-");
+    const hash = crypto
+        .createHash("sha256")
+        .update(testFile)
+        .digest("hex")
+        .slice(0, 8);
+    return `${basename}-${hash}-${Date.now()}-${crypto.randomBytes(3).toString("hex")}`;
+}
+/** The first `video.webm` under a run's video directory, if one was recorded. */
+export function collectVideoPath(videoDir) {
+    try {
+        for (const [entry, fullPath] of walkDir(videoDir)) {
+            if (entry.name === "video.webm")
+                return fullPath;
+        }
+    }
+    catch (err) {
+        logger.warning(`Could not scan ${videoDir} for a video`, {
+            error: String(err),
+        });
+    }
+    return undefined;
+}
+/**
+ * The directory whose `.skyramp/workspace.yml` describes this run: the nearest
+ * ancestor of `cwd` that has one, else the run's primary checkout (a tests repo
+ * delivered apart from the SUT has no workspace.yml of its own), else `cwd`.
+ */
+export function resolveWorkspaceRoot(cwd) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, ".skyramp", "workspace.yml")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return getPrimaryRepository()?.repositoryPath ?? path.resolve(cwd);
+}
+/** pytest splits PYTEST_ADDOPTS with shlex, so a path with whitespace needs quotes. */
+export function appendPytestVideoOpts(existing, videoDir) {
+    const dir = /\s/.test(videoDir) ? JSON.stringify(videoDir) : videoDir;
+    return [existing?.trim(), `--video on --output ${dir}`]
+        .filter(Boolean)
+        .join(" ");
+}
+/**
+ * The names by which a command can select `testFile`: its basename, and for Java the
+ * class name, because Maven selects a test with `-Dtest=FooTest`.
+ */
+export function testFileNames(testFile) {
+    const basename = path.basename(testFile);
+    return path.extname(basename) === ".java"
+        ? [basename, path.basename(basename, ".java")]
+        : [basename];
+}
+/**
+ * Backslashes are ignored: Playwright and Jest read the path as a regular
+ * expression, so the agent escapes it (`a\.spec\.ts`).
+ *
+ * A trailing shell comment is removed first. `npm test # a_test.py` names the
+ * file only in a comment and would run the whole suite, and the check exists
+ * to stop exactly that. This is a name check, not a parse: a command that
+ * mentions the file in some other way it does not run still passes.
+ */
+/** The config an explicit `--config <path>` names, resolved against `cwd`, or
+ *  undefined when the command carries none. `$SKYRAMP_PLAYWRIGHT_CONFIG` is
+ *  ours and is not a repository config. */
+export function explicitPlaywrightConfig(command, cwd) {
+    const m = /--config[= ]\s*("[^"]+"|'[^']+'|[^\s]+)/.exec(command);
+    if (!m)
+        return undefined;
+    const raw = m[1].replace(/^["']|["']$/g, "");
+    if (raw.includes("SKYRAMP_PLAYWRIGHT_CONFIG"))
+        return undefined;
+    const resolved = path.isAbsolute(raw) ? raw : path.join(cwd, raw);
+    return fs.existsSync(resolved) ? resolved : undefined;
+}
+/** The command with its `--config <repo config>` pointed at the wrapper. The
+ *  wrapper imports that same config, so the run keeps the repository's testDir
+ *  and projects and gains the video overlay. Without this swap a command that
+ *  names a config runs the config directly and records nothing. */
+export function pointConfigAtWrapper(command, wrapperPath) {
+    return command.replace(/(--config[= ]\s*)("[^"]+"|'[^']+'|[^\s]+)/, (_m, flag) => `${flag}${JSON.stringify(wrapperPath)}`);
+}
+export function commandNamesTestFile(command, testFile) {
+    const withoutComment = command.replace(/(^|\s)#.*$/, "$1");
+    const unescaped = withoutComment.replace(/\\/g, "");
+    return testFileNames(testFile).some((name) => unescaped.includes(name));
+}
+/** pytest exits 4 on a usage error; without pytest-playwright `--video` is one. */
+export function pytestRejectedVideoOptions(run) {
+    return (run.exitCode === 4 &&
+        /unrecognized arguments:[^\n]*--video/.test(run.output));
+}
+/** What the output says when the command ended before any test ran. Each entry
+ *  is the line the runner prints instead of a result: a missing package, or a
+ *  file the runner never matched. Node, Playwright and Jest all exit 1 for
+ *  these, so without this the run is recorded as a failing test. */
+const NO_RUN_PATTERNS = [
+    /^.*\bError: Cannot find module\b.*$/m,
+    /^Cannot find module\b.*$/m,
+    /^.*\bERR_MODULE_NOT_FOUND\b.*$/m,
+    /^(?:Error: )?No tests found\b.*$/im,
+    // npx --no-install refuses to fetch a runner the repository does not have.
+    /^.*\bnpx canceled due to missing packages\b.*$/m,
+    // Jest matched the file and loaded it, and it declared no test.
+    /^.*\bYour test suite must contain at least one test\b.*$/m,
+];
+/** The line proving no test ran, or undefined when the output does not say so. */
+export function noTestRanReason(output) {
+    for (const pattern of NO_RUN_PATTERNS) {
+        const hit = pattern.exec(output);
+        if (hit)
+            return hit[0].trim();
+    }
+    return undefined;
+}
+export function verdictForExit(exitCode, timedOut, output = "") {
+    if (timedOut)
+        return TestExecutionStatus.Error;
+    if (exitCode === 0)
+        return TestExecutionStatus.Pass;
+    // Exit 1 is the failing-test code, but it is also what a runner returns when
+    // it never got as far as a test. Error keeps those out of the failing count.
+    if (exitCode === 1)
+        return noTestRanReason(output)
+            ? TestExecutionStatus.Error
+            : TestExecutionStatus.Fail;
+    return TestExecutionStatus.Error;
+}
+/**
+ * How long output may keep arriving after the shell exits. A background process the
+ * command started holds the pipes open, so waiting for them to close would wait for it.
+ */
+const EXIT_OUTPUT_GRACE_MS = 2_000;
+/**
+ * Runs `command` through the shell in its own process group, so a timeout kills
+ * the runner's children too. stdout and stderr share one buffer in arrival order.
+ */
+export function spawnTestCommand(opts) {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        let output = "";
+        let timedOut = false;
+        let spawnError;
+        let exitCode = null;
+        let settled = false;
+        let grace;
+        const child = spawn(opts.command, {
+            cwd: opts.cwd,
+            env: opts.env,
+            shell: true,
+            detached: process.platform !== "win32",
+        });
+        const killGroup = () => {
+            try {
+                if (process.platform !== "win32" && child.pid) {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                else if (child.pid) {
+                    // Windows has no process group: child.kill reaches the shell and
+                    // leaves the runner beneath it alive, still writing to the checkout.
+                    // /T takes the tree, /F forces it.
+                    spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+                        stdio: "ignore",
+                    });
+                }
+            }
+            catch {
+                // already gone
+            }
+        };
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(grace);
+            if (output.length > MAX_OUTPUT_CHARS) {
+                output = output.slice(-MAX_OUTPUT_CHARS);
+                truncated = true;
+            }
+            resolve({
+                exitCode,
+                output: (truncated
+                    ? `[output truncated to its last ${MAX_OUTPUT_CHARS} characters]\n`
+                    : "") + stripVTControlCharacters(output),
+                timedOut,
+                spawnError,
+                duration: Date.now() - startedAt,
+            });
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup();
+        }, opts.timeoutMs);
+        let truncated = false;
+        const append = (d) => {
+            output += String(d);
+            if (output.length > 2 * MAX_OUTPUT_CHARS) {
+                output = output.slice(-MAX_OUTPUT_CHARS);
+                truncated = true;
+            }
+        };
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+        child.on("error", (err) => {
+            spawnError = String(err);
+            finish();
+        });
+        child.on("exit", (code) => {
+            exitCode = code;
+            clearTimeout(timer);
+            grace = setTimeout(() => {
+                killGroup();
+                finish();
+            }, EXIT_OUTPUT_GRACE_MS);
+        });
+        child.on("close", (code) => {
+            exitCode = code ?? exitCode;
+            finish();
+        });
+    });
+}
 /**
  * Where a real HTTP 401 shows up in runner output. Every entry is a shape taken from
  * actual skyramp_execute_test output in the eval logs, not from guesswork:
@@ -81,7 +319,6 @@ const HTTP_401_SHAPES = [
     // there, while a test TITLE ("should return 401 Unauthorized for an expired
     // token") always has words in front of it and is not evidence of a response.
     /^\s*401\s+unauthori[sz]ed\b/im,
-    // Status line, as curl -i and Go's httputil print it.
     /\bHTTP\/[\d.]+\s+401\b/i,
     // A status FIELD set to 401 — the value the response carried. Only `:` is
     // accepted: `== 401` and `= 401` are an assertion or echoed test source, which
@@ -90,8 +327,6 @@ const HTTP_401_SHAPES = [
     // (`Expected: {"status": 401}`) alongside `Received: {"status": 500}` is not a
     // 401 the app sent. Reject the line rather than the value.
     /^(?!.*\bexpected\b).*\b(?:status|status[_-]?code|statuscode|code|errorcode)\\?"?\s*:\s*401\b/im,
-    // Playwright prints both compared values. `Received` is what the app sent;
-    // `Expected` is what the test wanted, so it is not evidence of a 401.
     /^\s*Received:\s*401\b/im,
     // pytest assertion rewriting. A Skyramp-generated test reads
     // `assert response.status_code == N`, so the OBSERVED value is on the left and
@@ -124,14 +359,10 @@ export function resolveRebaselineSnapshots(requested, phase) {
     return { snapshots };
 }
 /**
- * Snapshot of the requested baselines under `<spec>-snapshots/` (SKYR-4298): for
- * each requested name, every PNG whose name matches the stem (a spec may hold both
- * `<stem>-linux.png` and `<stem>-chromium-linux.png`; latching onto one of them would
- * misreport the other) with its size and mtime. Taken before and after the run so
- * the tool can tell the agent which baselines were actually rewritten — SmartPlaywright
- * is the only party that knows the exact filename, and an executor image that lacks
- * SKYRAMP_UPDATE_SNAPSHOTS (or a name matching no toHaveScreenshot call) leaves
- * every file untouched.
+ * For each requested name, every PNG under `<spec>-snapshots/` whose name matches the
+ * stem, with size and mtime. A spec may hold both `<stem>-linux.png` and
+ * `<stem>-chromium-linux.png`; latching onto one would misreport the other. Taken
+ * before and after the run to tell which baselines were actually rewritten.
  */
 export function readBaselineState(specFile, requested) {
     const dir = snapshotDirFor(specFile);
@@ -159,10 +390,6 @@ export function readBaselineState(specFile, requested) {
     }
     return state;
 }
-/**
- * Which requested baselines changed on disk between two readBaselineState calls, and
- * which files carried the change (the ones to stage).
- */
 export function diffBaselineState(before, after) {
     const refreshed = [];
     const notRefreshed = [];
@@ -236,16 +463,13 @@ export function authorizeRebaseline(stateData, testFile, requested) {
     return {};
 }
 /**
- * Reconcile the persisted verdict with what the executor actually did (SKYR-4298).
- * An executor image whose @skyramp/skyramp predates SKYRAMP_UPDATE_SNAPSHOTS rewrites
- * nothing; left alone, the verdict would still promise a refresh, the report gate
- * would refuse the report, and nothing in the prompt makes the agent's way out
- * deterministic. So: names that were not refreshed are dropped from the verdict; a
- * rebaseline-only UPDATE with nothing left becomes VERIFY (the test stays red, the
- * rationale says why), and an UPDATE that also carried edits keeps UPDATE and is
- * held to its edit. The report then reflects what happened, not what was asked.
+ * Reconcile the persisted verdict with what the run actually did (SKYR-4298). A
+ * @skyramp/skyramp that predates SKYRAMP_UPDATE_SNAPSHOTS rewrites nothing; left
+ * alone, the verdict would still promise a refresh and the report gate would refuse
+ * the report. Names not refreshed are dropped; a rebaseline-only UPDATE with nothing
+ * left becomes VERIFY, and an UPDATE that also carried edits is held to its edit.
  */
-export function applyRefreshOutcomeToVerdicts(verdicts, testFile, outcome, executorImage) {
+export function applyRefreshOutcomeToVerdicts(verdicts, testFile, outcome) {
     if (outcome.notRefreshed.length === 0)
         return { verdicts };
     let note;
@@ -255,7 +479,7 @@ export function applyRefreshOutcomeToVerdicts(verdicts, testFile, outcome, execu
             v.action !== DriftAction.Update)
             return v;
         const remaining = (v.rebaselineSnapshots ?? []).filter((n) => !outcome.notRefreshed.includes(n));
-        const reason = `baseline refresh of ${outcome.notRefreshed.join(", ")} was not applied by ${executorImage} (its @skyramp/skyramp lacks SKYRAMP_UPDATE_SNAPSHOTS, or the name matches no toHaveScreenshot call)`;
+        const reason = `baseline refresh of ${outcome.notRefreshed.join(", ")} was not applied by the test run (its @skyramp/skyramp lacks SKYRAMP_UPDATE_SNAPSHOTS, or the name matches no toHaveScreenshot call)`;
         if (remaining.length === 0 && v.rebaselineOnly) {
             note = `Verdict for ${path.basename(testFile)} downgraded UPDATE → VERIFY: ${reason}. The test stays as it is; report it honestly.`;
             const { rebaselineSnapshots: _dropped, rebaselineOnly: _only, ...rest } = v;
@@ -290,10 +514,11 @@ export function describeRefreshOutcome(outcome) {
         parts.push(`Visual baselines refreshed: ${outcome.refreshed.join(", ")}.`);
     }
     if (outcome.notRefreshed.length > 0) {
-        parts.push(`Visual baselines NOT refreshed: ${outcome.notRefreshed.join(", ")} — the executor image may lack SKYRAMP_UPDATE_SNAPSHOTS support (needs @skyramp/skyramp with SKYR-4298), or the name matches no toHaveScreenshot() call in this spec. Do not report these as refreshed.`);
+        parts.push(`Visual baselines NOT refreshed: ${outcome.notRefreshed.join(", ")} — the test's @skyramp/skyramp may lack SKYRAMP_UPDATE_SNAPSHOTS support, or the name matches no toHaveScreenshot() call in this spec. Do not report these as refreshed.`);
     }
     return parts.join(" ");
 }
+/**
 /**
  * The fix-and-rerun attempt cap (SKYR-4460), enforced where the prompt's prose
  * cannot be: a file that has already received `cap` runs in the final phase
@@ -339,13 +564,6 @@ export function setTransientRetryDelayForTests(ms) {
  *  error itself: two executions, one attempt. The prompt withholds the agent's
  *  own unchanged re-run when it sees this, so one attempt is never three runs. */
 const TRANSIENT_RETRY_NOTE = `\n\nNote: the executor hit a transient connection error and re-ran this file once unchanged before answering; the two runs count as one attempt. Do not re-run it unchanged again — fix the cause the output names, or report it.`;
-/** The warning both result paths append when the run's state could not take
- *  the result: the attempt was counted at reservation, the record was not. */
-function persistFailureWarning(stateFile, reason) {
-    return (`\n\nWarning: this run's result could not be recorded in stateFile ` +
-        `${stateFile} (${reason}). The attempt was counted; the report will read ` +
-        `this file's result as Unknown unless the state file is repaired.`);
-}
 export function describeAttempt(priorAfterRuns, cap, opts = {}) {
     const attempt = priorAfterRuns + 1;
     const remaining = Math.max(0, cap - attempt);
@@ -384,16 +602,12 @@ export function buildExecutionFailureText(result, opts = {}) {
         sections.push(output);
     }
     else if (errors.length > 0) {
-        // The executor reported a cause of its own (e.g. "Docker image setup
-        // failed"). Saying the cause cannot be determined would contradict the
-        // Errors line below and throw away the only thing known about the failure.
-        sections.push("The executor captured no test output, so there are no per-test diagnostics. " +
-            "It did report the error below, which is the cause on record — use it. Do " +
-            "NOT infer anything the Errors line does not say, and leave the generated " +
-            "test unchanged.");
+        sections.push("The command printed no output, so there are no per-test diagnostics. " +
+            "The error below is the cause on record — use it. Do NOT infer anything " +
+            "the Errors line does not say, and leave the generated test unchanged.");
     }
     else {
-        sections.push("The executor captured no output, so this failure carries no diagnostics of " +
+        sections.push("The command printed no output, so this failure carries no diagnostics of " +
             "its own and the cause cannot be determined from it. The test runner, the " +
             "test process, or the application could each have died silently. Do NOT " +
             "report the app as unreachable or misconfigured on this basis — nothing " +
@@ -422,69 +636,415 @@ export function buildExecutionFailureText(result, opts = {}) {
     }
     return sections.join("\n\n");
 }
+export const inputSchema = {
+    commandOverride: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("The shell command that runs this one test file with the repository's own test runner, run on this host. Prefer it: the test then runs the way the repository's own CI runs it. Take the command from the suite's testRunCommand in .skyramp/workspace.yml, a Makefile target, a package script, or the command the repository's CI runs, and limit it to this one file. When workspace.yml records more than one suite, take it from the suite whose pathGlobs match the file: another suite's runner either fails to load it or reports a result for a file it never ran. If the repository has none, use the framework's default: `npx --no-install <runner> <file>` for playwright, jest, vitest or mocha, so a runner the repository does not have fails the run instead of downloading a different version; `python -m pytest <file> -q` with the interpreter the repository's own tests use; `mvn -q test -Dtest=<class> -DfailIfNoTests=false` for junit. It must name the test file; a command that does not is refused without running. For a TypeScript or JavaScript ui or e2e test, the server sets SKYRAMP_PLAYWRIGHT_CONFIG to a config that records video. Pass it even when you expect the runner or a package to be missing: the failure output is what names what is missing, and a check you make before the run reaches no repair. Omit it to run the test in the Skyramp executor container instead, which needs workspacePath — that is the fallback for a repository this host cannot run, not the first choice."),
+    cwd: z
+        .string()
+        .optional()
+        .describe("Absolute path of the directory commandOverride runs in. Required with commandOverride."),
+    workspacePath: z
+        .string()
+        .optional()
+        .describe("Absolute path of the Skyramp workspace. Required when commandOverride is omitted, because the executor resolves the service and its base URL from it."),
+    testFile: z.string().describe("Absolute path to the test file to execute."),
+    language: z
+        .nativeEnum(ProgrammingLanguage)
+        .describe("Programming language of the test file to execute (e.g., python, javascript, typescript, java)"),
+    testType: z
+        .nativeEnum(TestType)
+        .describe("Type of the test to execute. Note: 'mock' is NOT a valid test type — mock files are deployed via their apply_mock() function, not executed as tests."),
+    phase: z
+        .enum(["before", "after"])
+        .default("after")
+        .describe("Execution phase for maintained tests: 'before' captures pre-edit baseline; 'after' (default) records post-edit result."),
+    stateFile: z
+        .string()
+        .optional()
+        .describe("Path to state file from skyramp_analyze_changes. Always pass when available — results are written back so skyramp_submit_report can override before/afterStatus with ground-truth pass/fail."),
+    repository: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("The owner/repo whose analysis section to write execution results into (e.g. 'letsramp/api-insight'). Set it on every call — the primary's owner/repo for a primary-repo test, or a related repo's owner/repo for that repo's section of the run-scoped stateFile."),
+    token: z
+        .string()
+        .optional()
+        .describe("Explicit authentication token, set as SKYRAMP_TEST_TOKEN. Omit it, or pass an empty string, to use SKYRAMP_TEST_TOKEN from the server's environment. Use `unauthenticated: true` for no auth."),
+    unauthenticated: z
+        .boolean()
+        .optional()
+        .describe("Set true to force this test execution to carry NO auth token, even if SKYRAMP_TEST_TOKEN is set in the environment or a token was passed. Use for tests that must assert 401/403 unauthenticated behavior."),
+    rebaselineSnapshots: z
+        .array(rebaselineSnapshotNameSchema)
+        .optional()
+        .describe('UI tests only. toHaveScreenshot() baseline filenames (e.g. ["page-001.png"]) this run REPLACES instead of comparing against, because the PR intentionally changed how the captured page/element/region looks (SKYR-4298). ' +
+        "Pass exactly the list skyramp_actions returned as rebaseline_snapshots for this spec — the tool checks it against the persisted UPDATE verdict in stateFile (so stateFile is required) and refuses names the verdict did not authorize, a spec with no such verdict, or a spec whose phase: 'before' run has not been recorded yet. Use the name as the test passes it (page-001.png), not the on-disk file (page-001-chromium-linux.png). " +
+        "The refreshed PNGs land beside the spec and are delivered with the Testbot PR as image diffs; the result names which baselines were refreshed and which were not. Never use this to silence a screenshot mismatch the diff does not explain."),
+    timeout: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_TIMEOUT_MS, `timeout must be at most ${MAX_TIMEOUT_MS} ms`)
+        .optional()
+        .describe(`Milliseconds before the command is killed and the run recorded as Error. Default ${DEFAULT_TIMEOUT_MS}.`),
+};
+/** Returns a warning when the result, or its pre-edit baseline, was not saved. */
+async function writeExecutionToState(params, result, reserved) {
+    if (!params.stateFile)
+        return undefined;
+    const where = `testFile ${params.testFile} in repository ${params.repository}`;
+    try {
+        const written = await persistTestExecutionResult(params.stateFile, params.repository, params.testType, params.phase, result, 
+        // A reserved attempt already advanced the counters before the run.
+        { reserved });
+        if (!written.saved) {
+            return `This result was not saved: the stateFile has no section for repository ${params.repository}.`;
+        }
+        if (params.phase === "before" && !written.matchedExistingTest) {
+            return `The phase: "before" result was not saved as a baseline: the stateFile lists no existing test for ${where}.`;
+        }
+        return undefined;
+    }
+    catch (err) {
+        // The attempt was counted at reservation, so the count is right. The RESULT
+        // is what the report reads for afterStatus, so an unrecorded one has to
+        // reach the agent, not only the log.
+        return (`This result for ${where} was not saved to the stateFile: ${err.message}. ` +
+            `The attempt was counted; the report will read this file's result as Unknown ` +
+            `unless the state file is repaired.`);
+    }
+}
+/** Stages rewritten baselines and reconciles the verdict; returns the text to append. */
+async function settleRefresh(params, snapshots, before) {
+    const outcome = diffBaselineState(before, readBaselineState(params.testFile, snapshots));
+    let text = describeRefreshOutcome(outcome);
+    // The rewritten files themselves, never the directory: `git add` on the directory
+    // would ship anything else sitting there under one authorized baseline's authority.
+    for (const name of outcome.refreshed) {
+        for (const file of outcome.refreshedFiles[name] ?? []) {
+            try {
+                await stageGeneratedPaths(path.join(snapshotDirFor(params.testFile), file));
+            }
+            catch (err) {
+                logger.warning(`Could not stage refreshed visual baseline ${file}: ${err.message}`);
+            }
+        }
+    }
+    if (outcome.notRefreshed.length > 0 && params.stateFile) {
+        try {
+            const stateManager = StateManager.fromStatePath(params.stateFile);
+            const repo = params.repository;
+            const stateData = await stateManager.readRepoData(repo);
+            if (repo && stateData?.maintenanceVerdicts) {
+                const reconciled = applyRefreshOutcomeToVerdicts(stateData.maintenanceVerdicts, params.testFile, outcome);
+                await stateManager.updateRepoData({ ...stateData, maintenanceVerdicts: reconciled.verdicts }, { repo });
+                if (reconciled.note)
+                    text += ` ${reconciled.note}`;
+            }
+        }
+        catch (err) {
+            logger.warning(`Could not reconcile the maintenance verdict with the refresh outcome: ${err.message}`);
+        }
+    }
+    return text;
+}
+/** The fallback: no commandOverride, so the Skyramp executor container runs the
+ *  test. Kept while host execution is proven — the container resolves the
+ *  service and its base URL from the workspace, which the host path leaves to
+ *  the agent's own command.
+ *
+ *  It records the same result the host path records, through the same writer,
+ *  so the report cannot tell which path produced a run. */
+async function runInExecutor(params, snapshots, budget, onProgress, sendProgress) {
+    // runTest validated this for the executor mode before anything wrote state.
+    const workspacePath = params.workspacePath;
+    const token = resolveEffectiveToken(params.unauthenticated, params.token, process.env.SKYRAMP_TEST_TOKEN);
+    // Delivered tests and the state file sit outside workspacePath in a
+    // cross-repo run, so the executor needs the tests-repo root both to mount
+    // them and to match the service that owns the file.
+    const testRepoPath = getTestsRepoDir();
+    const { baseUrl, candidates, dockerNetwork } = await getWorkspaceBaseUrl(workspacePath, params.testFile, params.language, testRepoPath);
+    if (!baseUrl && candidates.length > 0) {
+        return toolError([
+            "Cannot determine SKYRAMP_TEST_BASE_URL — the test file matches more than one service:",
+            ...candidates.map((c) => `  \u2022 ${c.serviceName}: ${c.baseUrl}`),
+            "",
+            "Set SKYRAMP_TEST_BASE_URL to the right service URL, or give each service its own testDirectory in .skyramp/workspace.yml.",
+        ].join("\n"));
+    }
+    let injectedBaseUrl = false;
+    if (baseUrl && !process.env.SKYRAMP_TEST_BASE_URL) {
+        process.env.SKYRAMP_TEST_BASE_URL = baseUrl;
+        injectedBaseUrl = true;
+    }
+    const execOptions = {
+        testFile: params.testFile,
+        workspacePath,
+        testRepoPath,
+        language: params.language,
+        testType: params.testType,
+        token,
+        dockerNetwork,
+        useHostNetwork: false,
+        ...(snapshots.length > 0 ? { rebaselineSnapshots: snapshots } : {}),
+        ...(params.timeout !== undefined ? { timeout: params.timeout } : {}),
+    };
+    let result;
+    // The executor's own retry of a transient connection error: two executions
+    // billed as ONE attempt, on purpose — the SUT's hiccup is not the agent's fix
+    // to make. An EOF or a refused connection means the SUT is not ready yet, not
+    // that the test failed. Only a throw from the executor is retried here; a
+    // connection error inside the test's own output reaches the agent as a normal
+    // failure.
+    let transientRetried = false;
+    try {
+        const service = new TestExecutionService();
+        try {
+            result = await service.executeTest(execOptions, onProgress);
+        }
+        catch (firstErr) {
+            const errMsg = firstErr instanceof Error ? firstErr.message : String(firstErr);
+            if (!/\bEOF\b|connection refused|ECONNREFUSED|ECONNRESET/i.test(errMsg)) {
+                throw firstErr;
+            }
+            logger.info(`Test execution hit transient connection error, retrying after ${transientRetryDelayMs}ms...`, { error: errMsg });
+            await sendProgress(50, 100, "SUT connection error — retrying in 10s...");
+            await new Promise((r) => setTimeout(r, transientRetryDelayMs));
+            transientRetried = true;
+            try {
+                result = await service.executeTest(execOptions, onProgress);
+            }
+            catch (secondErr) {
+                // Both runs threw: the caller's catch owes the agent the retry note, or
+                // the prompt lets it spend an unchanged re-run the tool already used.
+                throw Object.assign(secondErr, { transientRetried: true });
+            }
+        }
+    }
+    finally {
+        // Unset only what this call set; a caller's own value must survive.
+        if (injectedBaseUrl)
+            delete process.env.SKYRAMP_TEST_BASE_URL;
+    }
+    const warnings = [...result.warnings];
+    if (transientRetried) {
+        warnings.push("The executor hit a transient connection error and re-ran this file once unchanged before answering. This is the second run's result, counted as one attempt. Do not re-run it unchanged again — fix the cause the output names, or report it.");
+    }
+    const stateWarning = await writeExecutionToState(params, result, budget.reserved);
+    if (stateWarning)
+        warnings.push(stateWarning);
+    await recordExecutionVideo(result, params.stateFile);
+    const compose = (text) => [
+        withVideoInfo(text, result.videoPath),
+        ...warnings.map((w) => `Warning: ${w}`),
+    ]
+        .filter(Boolean)
+        .join("\n\n") + budget.noRunNote;
+    if (result.status !== TestExecutionStatus.Pass) {
+        return toolError(compose(buildExecutionFailureText(result, {
+            unchangedRerun: budget.unchangedRerun,
+        }) + budget.attemptLine));
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: compose(`Test execution passed in the executor (duration=${result.duration}ms).\n\n${result.output ?? ""}`),
+            },
+        ],
+    };
+}
+/** A throw after the attempt was reserved has spent it (a Docker image setup,
+ *  a workspace check, a spawn that died). Land an Error result so the record is
+ *  not left as the reservation placeholder, and tell the agent the attempt went. */
+async function accountForThrow(params, err, budget) {
+    let persistNote = "";
+    if (budget.reserved) {
+        const warning = await writeExecutionToState(params, {
+            testFile: params.testFile,
+            status: TestExecutionStatus.Error,
+            executedAt: new Date().toISOString(),
+            duration: 0,
+            errors: [err.message],
+            warnings: [],
+            output: "",
+        }, true);
+        if (warning)
+            persistNote = `\n\nWarning: ${warning}`;
+    }
+    const retryNote = err.transientRetried
+        ? TRANSIENT_RETRY_NOTE
+        : "";
+    return toolError(`Test execution failed: ${err.message}${retryNote}${budget.attemptLine}${persistNote}${budget.noRunNote}`);
+}
+/** The preferred path: the agent supplied the command, so the server runs it on
+ *  this host in `cwd` and reads the verdict off the exit code. */
+async function runOnHost(params, command, hostCwd, snapshots, budget) {
+    const warnings = [];
+    const invEnv = {};
+    const workspaceRoot = resolveWorkspaceRoot(hostCwd);
+    const token = resolveEffectiveToken(params.unauthenticated, params.token, process.env.SKYRAMP_TEST_TOKEN);
+    if (token)
+        invEnv.SKYRAMP_TEST_TOKEN = token;
+    else if (!params.unauthenticated) {
+        warnings.push("No auth token available — authenticated endpoints will likely return 401. Set SKYRAMP_TEST_TOKEN or pass token/unauthenticated.");
+    }
+    if (snapshots.length > 0) {
+        invEnv.SKYRAMP_UPDATE_SNAPSHOTS = snapshots.join(",");
+    }
+    let videoDir;
+    let wrapper;
+    /** The config the server picked because the command named none. */
+    let autoFoundConfig;
+    if (isBrowserTest(params.testType)) {
+        videoDir = path.join(workspaceRoot, ".skyramp", "videos", videoSubdirName(params.testFile));
+        fs.mkdirSync(videoDir, { recursive: true });
+        if (params.language === ProgrammingLanguage.PYTHON) {
+            invEnv.PYTEST_ADDOPTS = appendPytestVideoOpts(process.env.PYTEST_ADDOPTS, videoDir);
+        }
+        else if (params.language === ProgrammingLanguage.TYPESCRIPT ||
+            params.language === ProgrammingLanguage.JAVASCRIPT) {
+            const namedConfig = explicitPlaywrightConfig(command, hostCwd);
+            // A repository with one Playwright config per suite gets whichever sits
+            // nearest the test file, and its testDir may not collect that file. The
+            // agent cannot see the choice, so name it when the run finds no test.
+            autoFoundConfig = namedConfig
+                ? undefined
+                : findRepoPlaywrightConfig(params.testFile, hostCwd);
+            wrapper = writeWrapperConfig({
+                // The wrapper replaces whatever --config the command carried, so an
+                // explicit one must be imported or the repository loses its projects,
+                // testDir and CI settings -- the thing the wrapper exists to keep.
+                repoConfigPath: namedConfig ?? autoFoundConfig,
+                fallbackDir: hostCwd,
+                outputDir: videoDir,
+                testFile: path.resolve(params.testFile),
+                commandPassesBrowserFlag: commandPassesBrowserFlag(command),
+            });
+            invEnv.SKYRAMP_PLAYWRIGHT_CONFIG = wrapper.path;
+            // A command that names its own config would otherwise load it directly and
+            // record no video, which is how a passing run loses its evidence.
+            if (namedConfig)
+                command = pointConfigAtWrapper(command, wrapper.path);
+        }
+    }
+    // testbot exports NODE_PATH=<mcp>/node_modules job-wide. Inheriting it lets the test
+    // load our @skyramp/skyramp and @playwright/test instead of the repository's own.
+    const env = { ...process.env, ...invEnv };
+    delete env.NODE_PATH;
+    if (!token)
+        delete env.SKYRAMP_TEST_TOKEN;
+    const baselinesBefore = snapshots.length > 0 ? readBaselineState(params.testFile, snapshots) : {};
+    const executedAt = new Date().toISOString();
+    const timeoutMs = params.timeout ?? DEFAULT_TIMEOUT_MS;
+    let run;
+    try {
+        run = await spawnTestCommand({
+            command,
+            cwd: hostCwd,
+            env,
+            timeoutMs,
+        });
+    }
+    finally {
+        // The wrapper sits in the customer's repo; a broad `git add` would ship it.
+        wrapper?.cleanup();
+    }
+    if (invEnv.PYTEST_ADDOPTS && pytestRejectedVideoOptions(run)) {
+        const plainEnv = { ...env };
+        if (process.env.PYTEST_ADDOPTS === undefined)
+            delete plainEnv.PYTEST_ADDOPTS;
+        else
+            plainEnv.PYTEST_ADDOPTS = process.env.PYTEST_ADDOPTS;
+        run = await spawnTestCommand({
+            command,
+            cwd: hostCwd,
+            env: plainEnv,
+            timeoutMs,
+        });
+        warnings.push("pytest did not recognize the added --video and --output options, so the test ran again without them. No video was recorded.");
+        videoDir = undefined;
+    }
+    const errors = [];
+    if (run.timedOut)
+        errors.push(`the command timed out after ${timeoutMs} ms`);
+    if (run.spawnError)
+        errors.push(run.spawnError);
+    const videoPath = videoDir ? collectVideoPath(videoDir) : undefined;
+    if (videoDir && !videoPath) {
+        warnings.push(`No video.webm was recorded under ${videoDir}. The verdict stands; the report has no video for this test.`);
+    }
+    const noRunReason = run.exitCode === 1 ? noTestRanReason(run.output) : undefined;
+    if (noRunReason) {
+        warnings.push(`No test ran here: the output reports "${noRunReason}". Exit 1 is the runner's, not a test's.`);
+        if (autoFoundConfig) {
+            warnings.push(`SKYRAMP_PLAYWRIGHT_CONFIG wraps ${path.relative(hostCwd, autoFoundConfig) || autoFoundConfig}, the nearest Playwright config above the test file, because the command named none. Its testDir decides which files the run collects — name the config the file belongs to if this is the wrong one.`);
+        }
+    }
+    const result = {
+        testFile: params.testFile,
+        status: verdictForExit(run.exitCode, run.timedOut || !!run.spawnError, run.output),
+        executedAt,
+        duration: run.duration,
+        errors,
+        warnings,
+        output: run.output,
+        ...(run.exitCode !== null ? { exitCode: run.exitCode } : {}),
+        ...(videoPath ? { videoPath } : {}),
+    };
+    const stateWarning = await writeExecutionToState(params, result, budget.reserved);
+    if (stateWarning)
+        warnings.push(stateWarning);
+    await recordExecutionVideo(result, params.stateFile);
+    const refreshText = snapshots.length > 0
+        ? await settleRefresh(params, snapshots, baselinesBefore)
+        : "";
+    const compose = (text) => [
+        withVideoInfo(text, videoPath),
+        refreshText,
+        ...warnings.map((w) => `Warning: ${w}`),
+    ]
+        .filter(Boolean)
+        .join("\n\n") + budget.noRunNote;
+    if (result.status !== TestExecutionStatus.Pass) {
+        return toolError(compose(buildExecutionFailureText(result, {
+            unchangedRerun: budget.unchangedRerun,
+        }) + budget.attemptLine));
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: compose(`Test execution passed (exitCode=0, duration=${result.duration}ms).\n\n${result.output ?? ""}`),
+            },
+        ],
+    };
+}
 export function registerExecuteSkyrampTestTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `Execute a Skyramp-generated test in isolated containerized environments for reliable, deterministic testing. Call this once a test file exists on disk (from a skyramp_*_test_generation tool). First-time execution may take longer while Docker images download — this is expected, not a failure.`,
+        description: "Run one test file and record the verdict from the exit code: 0 is Pass, 1 is Fail, any other exit or a timeout is Error. With `commandOverride` the server runs that command on this machine in `cwd`, with the server's environment. Without it the Skyramp executor container runs the test, which needs `workspacePath`. Either way the output is kept from its end, up to 200,000 characters.",
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
         },
-        inputSchema: {
-            workspacePath: z
-                .string()
-                .describe("The path to the workspace directory where the test file is located"),
-            language: z
-                .nativeEnum(ProgrammingLanguage)
-                .describe("Programming language of the test file to execute (e.g., python, javascript, typescript, java)"),
-            testType: z
-                .nativeEnum(TestType)
-                .describe("Type of the test to execute. Note: 'mock' is NOT a valid test type — mock files are deployed via their apply_mock() function, not executed as tests."),
-            testFile: z
-                .string()
-                .describe("Absolute path to the test file to execute."),
-            contractMode: z
-                .enum(CONTRACT_EXECUTION_MODES)
-                .optional()
-                .describe("Only applies when testType is 'contract'. Use 'provider' for provider contract tests that hit the real service under test and need SKYRAMP_TEST_BASE_URL. Use 'consumer' only for consumer contract tests with inline mocks that do not hit the real service. Defaults to provider behavior when omitted."),
-            token: z
-                .string()
-                .optional()
-                .describe("Explicit Skyramp authentication token for test execution. Omit this parameter to use SKYRAMP_TEST_TOKEN from the environment. An empty string is passed through as a literal token value, not a 'no auth' signal — use `unauthenticated: true` for tests that must run without credentials."),
-            unauthenticated: z
-                .boolean()
-                .optional()
-                .describe("Set true to force this test execution to carry NO auth token, even if SKYRAMP_TEST_TOKEN is set in the environment or a token was passed. Use for tests that must assert 401/403 unauthenticated behavior."),
-            playwrightSaveStoragePath: z
-                .string()
-                .optional()
-                .describe("Path to save Playwright session storage after test execution for authentication purposes. Can be a relative path to the workspace (e.g., 'auth-session.json') or an absolute path. The session will be saved after the test completes."),
-            stateFile: z
-                .string()
-                .trim()
-                .optional()
-                .describe("Path to state file from skyramp_analyze_changes. Always pass when available — results are written back so skyramp_submit_report can override before/afterStatus with ground-truth pass/fail."),
-            phase: z
-                .enum(["before", "after"])
-                .default("after")
-                .describe("Execution phase for maintained tests: 'before' captures pre-edit baseline; 'after' (default) records post-edit result."),
-            rebaselineSnapshots: z
-                .array(rebaselineSnapshotNameSchema)
-                .optional()
-                .describe('UI tests only. toHaveScreenshot() baseline filenames (e.g. ["page-001.png"]) this run REPLACES instead of comparing against, because the PR intentionally changed how the captured page/element/region looks (SKYR-4298). ' +
-                "Pass exactly the list skyramp_actions returned as rebaseline_snapshots for this spec — the tool checks it against the persisted UPDATE verdict in stateFile (so stateFile is required) and refuses names the verdict did not authorize, a spec with no such verdict, or a spec whose phase: 'before' run has not been recorded yet. Use the name as the test passes it (page-001.png), not the on-disk file (page-001-chromium-linux.png). " +
-                "The refreshed PNGs land beside the spec and are delivered with the Testbot PR as image diffs; the result names which baselines were refreshed and which were not. Never use this to silence a screenshot mismatch the diff does not explain."),
-            repository: z
-                .string()
-                .trim()
-                .min(1)
-                .describe("The owner/repo whose analysis section to write execution results into (e.g. 'letsramp/api-insight'). Set it on every call — the primary's owner/repo for a primary-repo test, or a related repo's owner/repo for that repo's section of the run-scoped stateFile."),
-        },
+        inputSchema,
         _meta: {
             keywords: ["run test", "execute test"],
         },
     }, async (params, extra) => {
+        const sendProgress = makeProgressReporter(extra);
+        // Progress callback adapter for TestExecutionService.
+        const onExecutionProgress = async (progress) => {
+            await sendProgress(progress.percent, 100, progress.message);
+        };
+        await sendProgress(0, 100, "Starting execution...");
         // `stateFile` may be omitted by the agent; the run's own state file (the
         // one skyramp_analyze_changes wrote for this run) is the fallback, so a
         // dropped argument cannot dodge the attempt cap or lose the result the
@@ -524,9 +1084,6 @@ export function registerExecuteSkyrampTestTool(server) {
                 resolvedRunStatePath: resolveRunStatePath(),
             });
         }
-        const noRunNote = stateFilePath
-            ? ""
-            : `\n\nNote: no run state file was found (none passed, and no active run), so this execution was not counted against an attempt cap and its result is not recorded for the report.`;
         // One execution at a time per run: everything below that touches the
         // state file — the cap read, the reservation, the retrofit staging, the
         // assertion proof, the result, the video record, the baseline verdict —
@@ -542,49 +1099,50 @@ export function registerExecuteSkyrampTestTool(server) {
             ? stateFileKey(stateFilePath)
             : canonicalTestPath(params.testFile), async () => {
             let errorResult;
-            // Attempt-cap bookkeeping (SKYR-4460), visible to the outer catch so a
-            // throw after the reservation can still account for the attempt.
-            let maxFixAttempts = getMaxFixAttempts();
-            let priorAfterRuns = 0;
-            let reserved = false;
-            // Set when the tool re-ran a thrown transient connection error itself
-            // (see the executor call): both the result path and the outer catch
-            // must say so, or the agent is told it may re-run unchanged once more.
-            let transientRetried = false;
-            // The record the cap check read, and whether this run re-executes the
-            // same file contents it ran last time (SKYR-4460: the one unchanged
-            // re-run a file gets is then spent, and the texts say so).
-            let unchangedRerun = false;
-            // `repository` names the state section; `stateFilePath` (the argument, else
-            // this run's own file) says whether there is any state to write. A standalone
-            // execution — the local-dev workflow, an IDE call, no run — names its
-            // repository but writes nothing.
-            const stateSection = stateFilePath
-                ? { file: stateFilePath, repo: params.repository }
-                : undefined;
-            // Helper to send progress notifications to the MCP client.
-            const sendProgress = makeProgressReporter(extra);
-            // Send immediate acknowledgment
-            await sendProgress(0, 100, "Starting execution...");
-            // Progress callback adapter for TestExecutionService
-            const onExecutionProgress = async (progress) => {
-                await sendProgress(progress.percent, 100, progress.message);
-            };
-            const previousBaseUrl = process.env.SKYRAMP_TEST_BASE_URL;
-            let didSetSkyrampBaseUrl = false;
-            let dockerNetwork;
             try {
                 if (!path.isAbsolute(params.testFile)) {
                     errorResult = toolError(`testFile must be an absolute path, got: ${params.testFile}`);
                     return errorResult;
                 }
-                // A missing test file is an argument error: refuse it before any
-                // side effect (retrofit staging, the assertion proof record, the
-                // attempt reservation) has recorded an execution that never ran.
+                // A missing test file is an argument error: refuse it before any side effect
+                // (retrofit staging, the assertion proof record, the attempt reservation) has
+                // recorded an execution that never ran.
                 if (!fs.existsSync(params.testFile)) {
                     errorResult = toolError(`Test file does not exist: ${params.testFile}`);
                     return errorResult;
                 }
+                // Validate the inputs of whichever mode this call is in, before anything
+                // below writes state: a call that cannot run must not record that it did.
+                const command = params.commandOverride;
+                const cwd = params.cwd;
+                if (command === undefined) {
+                    if (params.workspacePath === undefined) {
+                        errorResult = toolError("workspacePath is required when commandOverride is omitted: the executor resolves the service and its base URL from the workspace. Pass commandOverride to run the test on this host instead.");
+                        return errorResult;
+                    }
+                    if (!path.isAbsolute(params.workspacePath)) {
+                        errorResult = toolError(`workspacePath must be an absolute path, got: ${params.workspacePath}`);
+                        return errorResult;
+                    }
+                }
+                else {
+                    if (cwd === undefined) {
+                        errorResult = toolError("cwd is required with commandOverride.");
+                        return errorResult;
+                    }
+                    if (!path.isAbsolute(cwd)) {
+                        errorResult = toolError(`cwd must be an absolute path, got: ${cwd}`);
+                        return errorResult;
+                    }
+                    if (!fs.statSync(cwd, { throwIfNoEntry: false })?.isDirectory()) {
+                        errorResult = toolError(`cwd ${cwd} is not an existing directory. The command was not run.`);
+                        return errorResult;
+                    }
+                    if (!commandNamesTestFile(command, params.testFile)) {
+                        errorResult = toolError(`commandOverride does not contain ${testFileNames(params.testFile).join(" or ")}, the name of testFile. The command was not run.`);
+                        return errorResult;
+                    }
+                }
                 // Hashed once, before any state write: recorded with the reservation
                 // so the NEXT run can tell an unchanged re-run from a fixed file.
                 const fileHash = sha256Of(fs.readFileSync(params.testFile, "utf8"));
@@ -593,63 +1151,49 @@ export function registerExecuteSkyrampTestTool(server) {
                     errorResult = toolError(rebaseline.error);
                     return errorResult;
                 }
-                const rebaselineSnapshots = rebaseline.snapshots;
-                if (rebaselineSnapshots.length > 0) {
-                    if (!stateSection) {
+                const snapshots = rebaseline.snapshots;
+                if (snapshots.length > 0) {
+                    if (!stateFilePath) {
                         errorResult = toolError("rebaselineSnapshots requires stateFile: the refresh is authorized against the UPDATE verdict skyramp_actions persisted there.");
                         return errorResult;
                     }
-                    const authState = await StateManager.fromStatePath(stateSection.file).readRepoData(stateSection.repo);
-                    const auth = authorizeRebaseline(authState, params.testFile, rebaselineSnapshots);
+                    const authState = await StateManager.fromStatePath(stateFilePath).readRepoData(params.repository);
+                    const auth = authorizeRebaseline(authState, params.testFile, snapshots);
                     if (auth.error) {
                         errorResult = toolError(auth.error);
                         return errorResult;
                     }
                 }
-                // Deterministic external-test guard (SKYR-3924): this tool runs Skyramp-generated
-                // tests in the executor and cannot run a repo's native (user-written) suite, so a
-                // run on an external test only errors (e.g. pytest import/collection failure).
-                // If the stateFile records this test as external, skip execution — the prompt asks
-                // the agent to exclude them, and this enforces it. Best-effort and conservative:
-                // only skip on a positive external match; any state-read issue falls through to
-                // normal execution, and a not-found test (e.g. a newly generated one) is not skipped.
-                if (stateSection) {
-                    try {
-                        const stateManager = StateManager.fromStatePath(stateSection.file);
-                        const stateData = await stateManager.readRepoData(stateSection.repo);
-                        const entry = stateData?.existingTests?.find((t) => canonicalTestPath(t.testFile) ===
-                            canonicalTestPath(params.testFile));
-                        if (entry?.source === TestSource.External) {
-                            logger.info(`Skipping execution of external test ${params.testFile} — native suites are not run by ${TOOL_NAME}`);
-                            return {
-                                content: [
-                                    {
-                                        type: "text",
-                                        text: `Skipped execution: ${params.testFile} is marked external in the state file. ${TOOL_NAME} runs Skyramp-generated tests only; external (native) suites are not executed here.`,
-                                    },
-                                ],
-                            };
-                        }
-                    }
-                    catch (err) {
-                        logger.warning(`External-test guard could not read stateFile (${err.message}); proceeding with execution`);
-                    }
-                }
+                // `stateFile` says whether there is any run state to count against and write
+                // into; `repository` names the section inside it. A standalone execution —
+                // the local-dev workflow, an IDE call, no run — names its repository but
+                // writes nothing, and the tool says so in its answer.
+                const stateSection = stateFilePath
+                    ? { file: stateFilePath, repo: params.repository }
+                    : undefined;
+                const noRunNote = stateSection
+                    ? ""
+                    : `\n\nNote: no run state file was found (none passed, and no active run), so this execution was not counted against an attempt cap and its result is not recorded for the report.`;
                 // Fix-and-rerun attempt cap (SKYR-4460). With a stateFile the cap is the one
-                // pinned in the run's state (the first call pins the prompt's value), and
-                // the check fails CLOSED: this is the enforcement boundary, so a state that
-                // cannot be read refuses the run instead of counting as zero prior
-                // attempts. A call without any run state resolves from the environment and
-                // the default and enforces nothing — there is no run to count against.
-                maxFixAttempts = getMaxFixAttempts();
+                // pinned in the run's state (the first call pins the prompt's value), and the
+                // check fails CLOSED: this is the enforcement boundary, so a state that cannot
+                // be read refuses the run instead of counting as zero prior attempts. A call
+                // without any run state resolves from the environment and the default and
+                // enforces nothing — there is no run to count against.
+                let maxFixAttempts = getMaxFixAttempts();
+                // Whether this run re-executes the same file contents as the last
+                // one (SKYR-4460): the single unchanged re-run a file gets is then
+                // spent, and the failure texts say so instead of offering another.
+                let unchangedRerun = false;
+                let priorAfterRuns = 0;
                 if (stateSection) {
                     let record;
                     try {
                         const stateData = await readRepoSectionOrThrow(stateSection.file, stateSection.repo);
-                        // The pin is run-wide and lives at the ROOT, whichever section
-                        // this file's record is in. A pinned value is re-validated: a
-                        // hand-edited or half-written state must not turn into "cap 0,
-                        // nothing ever runs" or "no cap".
+                        // The pin is run-wide and lives at the ROOT, whichever section this
+                        // file's record is in. A pinned value is re-validated: a hand-edited or
+                        // half-written state must not turn into "cap 0, nothing ever runs" or
+                        // "no cap".
                         const pinned = await readPinnedMaxFixAttempts(stateSection.file);
                         const current = getMaxFixAttempts();
                         maxFixAttempts = pinned ?? current;
@@ -677,112 +1221,26 @@ export function registerExecuteSkyrampTestTool(server) {
                         return errorResult;
                     }
                 }
-                // SKYR-4220: stage the shared utils file (see stageUtilsArtifacts) — execution is
-                // the last step before delivery, and a utils file left unstaged here ships a
-                // test importing a module the PR lacks. After the external-test skip: a native
-                // suite this tool will not run gets no scan and no staging.
+                // SKYR-4220: a utils file left unstaged ships a test importing a module the PR lacks.
                 await stageAndRecordRetrofits(params.testFile, undefined, stateFilePath);
-                // SKYR-4115 backstop: enhance_assertions carries the same check, but nothing
-                // guarantees the agent calls it, and execution is the last step that still
-                // precedes reporting. See pendingReuseVerification for why enforcing the verify
-                // CALL needs no retry budget.
-                //
-                // Pass the run's state path through: without it the state path resolves
-                // from the CI/Testbot anchor alone and the check returns early — failing
-                // OPEN — for a caller that supplies a valid stateFile outside CI. It is the
-                // canonical path (explicit argument → this run's own file → undefined),
-                // the same one the external-test guard above and every write below use,
-                // so a symlinked argument cannot fork the state into a second file.
-                const owedReuseVerification = await pendingReuseDebt(params.testFile, stateFilePath, params.testType);
-                if (owedReuseVerification) {
-                    errorResult = toolError(owedReuseVerification);
+                const owedReuse = await pendingReuseDebt(params.testFile, stateFilePath, params.testType);
+                if (owedReuse) {
+                    errorResult = toolError(owedReuse);
                     return errorResult;
                 }
-                // Deterministic assertion-enhancement check: the server verifies the file
-                // itself here (never relying on the agent to call `verify: true` — prose
-                // can be ignored, this cannot). Insufficient assertions return feedback
-                // instead of executing; a fixed file passes on the next execute call.
-                // Sits BELOW the external-test guard: an external test is skipped, not
-                // executed, so deferring it for assertion work would demand fixes to a
-                // file this tool will never run.
                 const assertionFeedback = await assertionFeedbackForExecution(params.testFile, stateFilePath);
                 if (assertionFeedback) {
                     errorResult = toolError(assertionFeedback);
                     return errorResult;
                 }
-                // Proof-of-work substrate (SKYR-4262 follow-up): count this execution
-                // server-side so the report can cross-check generated vs executed —
-                // the narrative is LLM-authored, this number is not. Best-effort.
                 await recordAssertionExecution(params.testFile, params.testType, stateFilePath);
-                // Send initial progress
-                await sendProgress(5, 100, "Starting test execution...");
-                // Cross-repo run (SKYR-3819): tests delivered under the run's testsRepoDir
-                // (set by skyramp_analyze_changes, run-scoped) live outside workspacePath.
-                // Thread it through so the executor mounts the test repo and service
-                // matching still resolves the SUT baseUrl/dockerNetwork.
-                const testRepoPath = getTestsRepoDir();
-                // Resolve workspace config for base URL injection and Docker network
-                // attachment. A compose dockerNetwork is not host networking: on macOS
-                // the executor still needs localhost rewritten to host.docker.internal.
-                if (params.workspacePath) {
-                    const workspaceConfig = await getWorkspaceBaseUrl(params.workspacePath, params.testFile, params.language, testRepoPath);
-                    const { baseUrl, candidates } = workspaceConfig;
-                    dockerNetwork = workspaceConfig.dockerNetwork;
-                    const shouldInjectBaseUrl = shouldInjectSkyrampBaseUrl(params.testType, params.contractMode);
-                    if (shouldInjectBaseUrl && !process.env.SKYRAMP_TEST_BASE_URL) {
-                        if (baseUrl) {
-                            process.env.SKYRAMP_TEST_BASE_URL = baseUrl;
-                            didSetSkyrampBaseUrl = true;
-                        }
-                        else if (candidates.length > 0) {
-                            errorResult = toolError([
-                                `Cannot determine SKYRAMP_TEST_BASE_URL — test file matches multiple services:`,
-                                ...candidates.map((c) => `  • ${c.serviceName}: ${c.baseUrl}`),
-                                ``,
-                                `Re-invoke with SKYRAMP_TEST_BASE_URL set to the correct service URL, or make each service's testDirectory unique in .skyramp/workspace.yml.`,
-                            ].join("\n"));
-                            return errorResult;
-                        }
-                    }
-                }
-                const executionService = new TestExecutionService();
-                const effectiveToken = resolveEffectiveToken(params.unauthenticated, params.token, process.env.SKYRAMP_TEST_TOKEN);
-                if (!effectiveToken &&
-                    !params.unauthenticated &&
-                    params.token === undefined) {
-                    logger.warning("No auth token available — authenticated endpoints will likely return 401. Set SKYRAMP_TEST_TOKEN or pass token/unauthenticated.");
-                }
-                // Execute test with progress callback - reports Docker cache/pull status.
-                // Retry once on transient connection errors (EOF, connection refused) —
-                // these indicate the SUT isn't fully ready yet, not a test failure.
-                // Retrying inside the tool call saves agent turns vs failing and
-                // requiring the agent to re-invoke. This covers a connection error the
-                // executor THROWS, under the one attempt already reserved; a connection
-                // error that surfaces inside the test's own output reaches the agent as
-                // a normal failure, and the prompt's unchanged-re-run allowance is for
-                // that one.
-                const execOptions = {
-                    testFile: params.testFile,
-                    workspacePath: params.workspacePath,
-                    testRepoPath,
-                    language: params.language,
-                    testType: params.testType,
-                    token: effectiveToken,
-                    playwrightSaveStoragePath: params.playwrightSaveStoragePath,
-                    dockerNetwork,
-                    useHostNetwork: false,
-                    ...(rebaselineSnapshots.length > 0
-                        ? { rebaselineSnapshots }
-                        : {}),
-                };
-                // Identity of the requested baselines before the run, to report afterwards
-                // which ones SmartPlaywright actually rewrote (SKYR-4298).
-                const baselinesBefore = rebaselineSnapshots.length > 0
-                    ? readBaselineState(params.testFile, rebaselineSnapshots)
-                    : {};
-                // Reserve the attempt before the run (SKYR-4460): the counters advance now
-                // and the cap is pinned, so a state write that fails after the run cannot
-                // hand this file a free attempt. Fails closed, like the check above.
+                // Reserve the attempt before the run (SKYR-4460). It sits ABOVE the mode
+                // dispatch on purpose: the host path spawns the command itself and never
+                // reaches TestExecutionService, so a reservation taken around the executor
+                // call would count nothing on the path this tool now prefers. The counters
+                // advance now and the cap is pinned, so a state write that fails after the
+                // run cannot hand this file a free attempt. Fails closed, like the check above.
+                let reserved = false;
                 if (stateSection) {
                     try {
                         const reservation = await reserveTestExecutionAttempt(stateSection.file, stateSection.repo, params.testType, params.phase, params.testFile, maxFixAttempts, fileHash);
@@ -795,173 +1253,41 @@ export function registerExecuteSkyrampTestTool(server) {
                         return errorResult;
                     }
                 }
-                let result;
-                // The tool's own retry of a transient connection error the executor
-                // THREW (a resolved Error/Fail result whose output mentions
-                // ECONNREFUSED is not retried here — TestExecutionService converts
-                // execution-time exceptions into resolved results): two executions
-                // billed as ONE attempt, on purpose — the SUT's hiccup is not the
-                // agent's fix to make. The response says when it happened, and the
-                // prompt withholds the agent's own unchanged re-run only then, so
-                // one attempt is never more than two runs.
+                const budget = {
+                    // The budget line only means something when the run counts attempts, i.e.
+                    // when a stateFile records them and this is a final-phase run.
+                    attemptLine: stateSection && params.phase === "after"
+                        ? `\n\n${describeAttempt(priorAfterRuns, maxFixAttempts, { unchangedRerun })}`
+                        : "",
+                    reserved,
+                    noRunNote,
+                    unchangedRerun,
+                };
+                await sendProgress(5, 100, "Starting test execution...");
+                // Both modes owe the checks above. Only now does the path diverge.
+                // Both take the RESOLVED state path, not the argument: everything they
+                // hand it to — the result write, the video record, the verdict
+                // reconciliation — must name the same file every check above read.
+                const runParams = {
+                    ...params,
+                    stateFile: stateFilePath,
+                };
                 try {
-                    result = await executionService.executeTest(execOptions, onExecutionProgress);
-                }
-                catch (firstErr) {
-                    const errMsg = firstErr instanceof Error ? firstErr.message : String(firstErr);
-                    if (/\bEOF\b|connection refused|ECONNREFUSED|ECONNRESET/i.test(errMsg)) {
-                        logger.info(`Test execution hit transient connection error, retrying after ${transientRetryDelayMs}ms...`, { error: errMsg });
-                        await sendProgress(50, 100, "SUT connection error — retrying in 10s...");
-                        await new Promise((r) => setTimeout(r, transientRetryDelayMs));
-                        transientRetried = true;
-                        result = await executionService.executeTest(execOptions, onExecutionProgress);
-                    }
-                    else {
-                        throw firstErr;
-                    }
+                    return command === undefined
+                        ? await runInExecutor(runParams, snapshots, budget, onExecutionProgress, sendProgress)
+                        : await runOnHost(runParams, command, cwd, snapshots, budget);
                 }
-                const transientRetryNote = transientRetried
-                    ? TRANSIENT_RETRY_NOTE
-                    : "";
-                // Update stateFile with execution results if provided. Multi-repo: write
-                // into the section for `repository` of the run-scoped file.
-                let persistWarning = noRunNote;
-                if (stateSection) {
-                    try {
-                        await persistTestExecutionResult(stateSection.file, stateSection.repo, params.testType, params.phase, result, { reserved: true });
-                        logger.info(`Updated stateFile with execution results for ${params.testFile}`);
-                    }
-                    catch (err) {
-                        // The attempt was reserved before the run, so the count is right.
-                        // The RESULT is what the report reads for afterStatus, though, so
-                        // an unrecorded one must reach the agent, not only the log.
-                        logger.error(`Failed to update stateFile: ${err.message}`);
-                        persistWarning = persistFailureWarning(stateSection.file, err.message);
-                    }
-                }
-                // Record the recording for the report before returning, so it happens on the
-                // failure path too (SKYR-4156). skyramp_submit_report reads these records to
-                // populate testResults[].videoPath — testbot uploads only the video
-                // directories the report references, so an unrecorded video is never seen.
-                await recordExecutionVideo(result, stateFilePath);
-                // Which requested baselines were actually rewritten (SKYR-4298). Reported on
-                // pass and fail alike; a refreshed PNG is a deliverable like a generated
-                // spec, so stage the spec's snapshot directory whenever one was rewritten —
-                // even on a failing run, since the report gate checks the PNG, not the
-                // status — so the eval harness commit and the artifact collector see it
-                // (production delivery adds the whole test directory anyway). No-op outside
-                // a testbot run, like every other stageGeneratedPaths call; never fails the
-                // execution.
-                let refreshOutcomeText = "";
-                if (rebaselineSnapshots.length > 0) {
-                    const after = readBaselineState(params.testFile, rebaselineSnapshots);
-                    const outcome = diffBaselineState(baselinesBefore, after);
-                    refreshOutcomeText = describeRefreshOutcome(outcome);
-                    // Stage the rewritten files themselves, never the directory: `git add` on
-                    // the directory would ship anything else sitting there under one
-                    // authorized baseline's authority.
-                    for (const name of outcome.refreshed) {
-                        for (const file of outcome.refreshedFiles[name] ?? []) {
-                            try {
-                                await stageGeneratedPaths(path.join(snapshotDirFor(params.testFile), file));
-                            }
-                            catch (err) {
-                                logger.warning(`Could not stage refreshed visual baseline ${file} for ${params.testFile}: ${err.message}`);
-                            }
-                        }
-                    }
-                    if (outcome.notRefreshed.length > 0 && stateSection) {
-                        try {
-                            const stateManager = StateManager.fromStatePath(stateSection.file);
-                            const stateData = await stateManager.readRepoData(stateSection.repo);
-                            if (stateData?.maintenanceVerdicts) {
-                                const reconciled = applyRefreshOutcomeToVerdicts(stateData.maintenanceVerdicts, params.testFile, outcome, EXECUTOR_DOCKER_IMAGE);
-                                await stateManager.updateRepoData({
-                                    ...stateData,
-                                    maintenanceVerdicts: reconciled.verdicts,
-                                }, { repo: stateSection.repo });
-                                if (reconciled.note)
-                                    refreshOutcomeText += ` ${reconciled.note}`;
-                            }
-                        }
-                        catch (err) {
-                            logger.warning(`Could not reconcile the maintenance verdict with the refresh outcome: ${err.message}`);
-                        }
-                    }
+                catch (err) {
+                    return accountForThrow(runParams, err, budget);
                 }
-                const withRefreshOutcome = (text) => (refreshOutcomeText ? `${text}\n\n${refreshOutcomeText}` : text) +
-                    transientRetryNote +
-                    persistWarning;
-                // Progress is already reported by TestExecutionService
-                // Only report final status if not already at 100%
-                if (result.status !== TestExecutionStatus.Pass) {
-                    // The budget line only means something when the run counts attempts,
-                    // i.e. when a stateFile records them and this is a final-phase run.
-                    const attemptLine = stateSection && params.phase === "after"
-                        ? `\n\n${describeAttempt(priorAfterRuns, maxFixAttempts, { unchangedRerun })}`
-                        : "";
-                    errorResult = toolError(withRefreshOutcome(withVideoInfo(buildExecutionFailureText(result, { unchangedRerun }) +
-                        attemptLine, result.videoPath)));
-                    return errorResult;
-                }
-                // Success - progress already reported by TestExecutionService
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: withRefreshOutcome(withVideoInfo(`Test execution result: ${stripVTControlCharacters(result.output || "")}`, result.videoPath)),
-                        },
-                    ],
-                };
             }
             catch (err) {
-                const message = err.message;
-                let attemptNote = "";
-                let persistNote = "";
-                // Both executions threw: the retry happened and the agent must still
-                // hear it, or the prompt lets it spend a third unchanged run.
-                const retryNote = transientRetried ? TRANSIENT_RETRY_NOTE : "";
-                // A throw after the reservation (Docker image setup, a workspace check,
-                // the rethrow from the transient-retry path) has spent an attempt; say
-                // so, and land an Error result so the record is not left as the
-                // reservation placeholder.
-                if (reserved && stateSection) {
-                    try {
-                        await persistTestExecutionResult(stateSection.file, stateSection.repo, params.testType, params.phase, {
-                            testFile: params.testFile,
-                            status: TestExecutionStatus.Error,
-                            executedAt: new Date().toISOString(),
-                            duration: 0,
-                            errors: [message],
-                            warnings: [],
-                            output: "",
-                        }, { reserved: true });
-                    }
-                    catch (persistErr) {
-                        // Same as the main path: the count is right (reserved), the
-                        // record is not, and the agent must hear it, not only the log.
-                        logger.error(`Failed to record the execution error in stateFile: ${persistErr.message}`);
-                        persistNote = persistFailureWarning(stateSection.file, persistErr.message);
-                    }
-                    if (params.phase === "after") {
-                        attemptNote = `\n\n${describeAttempt(priorAfterRuns, maxFixAttempts, { unchangedRerun })}`;
-                    }
-                }
-                errorResult = toolError(`Test execution failed: ${message}${retryNote}${attemptNote}${persistNote}${noRunNote}`);
+                errorResult = toolError(`Test execution failed: ${err.message}`);
                 return errorResult;
             }
             finally {
-                if (didSetSkyrampBaseUrl) {
-                    if (previousBaseUrl === undefined) {
-                        delete process.env.SKYRAMP_TEST_BASE_URL;
-                    }
-                    else {
-                        process.env.SKYRAMP_TEST_BASE_URL = previousBaseUrl;
-                    }
-                }
                 AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
                     testFile: params.testFile,
-                    workspacePath: params.workspacePath,
                     language: params.language,
                     testType: params.testType,
                 }).catch((err) => {