@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/tools/executeSkyrampTestTool.js

@@ -1,39 +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, getTestsRepoDir, } 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 * as fs from "fs";
+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 { getMaxFixAttempts } from "../utils/fixAttempts.js";
+import { runSerialized } from "../utils/runSerialized.js";
+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.
@@ -46,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:
@@ -76,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
@@ -85,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
@@ -119,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);
@@ -154,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 = [];
@@ -193,7 +425,11 @@ export function diffBaselineState(before, after) {
 export function authorizeRebaseline(stateData, testFile, requested) {
     if (requested.length === 0)
         return {};
-    const verdict = (stateData?.maintenanceVerdicts ?? []).find((v) => v.testFilePath === testFile && v.action === DriftAction.Update);
+    // Canonical on both sides: the verdict and the row were written by analysis,
+    // the argument by the agent, and `/repo/tests/./a.spec.ts` is one file.
+    const key = canonicalTestPath(testFile);
+    const verdict = (stateData?.maintenanceVerdicts ?? []).find((v) => canonicalTestPath(String(v.testFilePath ?? "")) === key &&
+        v.action === DriftAction.Update);
     if (!verdict) {
         return {
             error: `rebaselineSnapshots refused: no UPDATE verdict for ${testFile} in the stateFile. Only a maintained test whose skyramp_analyze_test_health verdict listed the baselines can be refreshed — a newly generated test writes its own baseline on its first run and has nothing to refresh.`,
@@ -206,8 +442,12 @@ export function authorizeRebaseline(stateData, testFile, requested) {
             error: `rebaselineSnapshots refused: ${unauthorized.join(", ")} not in the UPDATE verdict for ${path.basename(testFile)} (authorized: ${authorized.size ? [...authorized].join(", ") : "none"}). Pass exactly the rebaseline_snapshots skyramp_actions returned, using the name the test passes to toHaveScreenshot (page-001.png), not the on-disk file (page-001-chromium-linux.png).`,
         };
     }
-    const entry = (stateData?.existingTests ?? []).find((t) => t.testFile === testFile);
-    if (!entry?.executionBefore) {
+    const entry = (stateData?.existingTests ?? []).find((t) => canonicalTestPath(t.testFile) === key);
+    // The reservation writes an Unknown placeholder into this row while a before
+    // run is in flight (SKYR-4460); a run that died there left no evidence, so
+    // the placeholder must not read as a recorded baseline.
+    if (!entry?.executionBefore ||
+        entry.executionBefore.status === TestExecutionStatus.Unknown) {
         return {
             error: `rebaselineSnapshots refused: no phase: "before" execution is recorded for ${path.basename(testFile)}. Run the pre-edit baseline first (it is the evidence the baseline is stale), then pass rebaselineSnapshots on the final run.`,
         };
@@ -223,30 +463,33 @@ 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;
     const next = verdicts.map((v) => {
-        if (v.testFilePath !== testFile || v.action !== DriftAction.Update)
+        if (canonicalTestPath(String(v.testFilePath ?? "")) !==
+            canonicalTestPath(testFile) ||
+            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;
             void _dropped;
             void _only;
-            return { ...rest, action: DriftAction.Verify, rationale: `${v.rationale} [${reason}]` };
+            return {
+                ...rest,
+                action: DriftAction.Verify,
+                rationale: `${v.rationale} [${reason}]`,
+            };
         }
         note = `Verdict for ${path.basename(testFile)}: ${reason}; the UPDATE is held to its spec/POM edit only.`;
         const { rebaselineSnapshots: _dropped, ...rest } = v;
@@ -271,11 +514,82 @@ 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(" ");
 }
-export function buildExecutionFailureText(result) {
+/**
+/**
+ * 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
+ * gets a refusal instead of another execution. Only the "after" phase counts —
+ * a maintained test's baseline run is evidence, not an attempt — and a record
+ * from before the counter existed reads as zero attempts.
+ *
+ * Deliberate limit: `phase: "before"` runs are never refused. The cap bounds
+ * the fix-and-rerun loop, which is a final-phase activity; a baseline is taken
+ * once per file by the prompt (and once per existing test by the baseline
+ * runner), so there is no loop to bound there. A runaway baseline loop would
+ * need its own guard — it is not this one.
+ */
+export function fixAttemptRefusal(record, phase, cap, testFile) {
+    if (phase !== "after")
+        return undefined;
+    const prior = record?.afterRuns ?? 0;
+    if (prior < cap)
+        return undefined;
+    return (`Attempt cap reached: ${path.basename(testFile)} has already been executed ` +
+        `${prior} time${prior === 1 ? "" : "s"} in the final phase, and the cap for this ` +
+        `run is ${cap} (maxFixAttempts). It was NOT run again. Do not edit and re-run it: ` +
+        // The report accepts Pass, Fail or Skipped: a run that errored, or one that
+        // recorded no result, is reported as Fail.
+        (record?.status === TestExecutionStatus.Pass
+            ? `report it as status "Pass" (its last run passed)`
+            : record?.status && record.status !== TestExecutionStatus.Unknown
+                ? `report it as status "Fail" (its last run ended ${record.status})`
+                : `its last run recorded no result, so the report will publish "Unknown" for it — describe the failure in its details`) +
+        ` with the failure details already in your context, then move on. A failing test ` +
+        `that documents a real bug is a valid outcome; say in the report whether the ` +
+        `failure is the bug or the test, and that the attempt cap was reached.`);
+}
+/** The budget line appended to a failure, so the agent knows how many
+ *  fix-and-rerun attempts remain for this file before it must report. */
+/** Wait before the tool's single retry of a transient connection error.
+ *  Module state with a test seam, so the handler test does not sleep 10s. */
+let transientRetryDelayMs = 10_000;
+export function setTransientRetryDelayForTests(ms) {
+    transientRetryDelayMs = ms;
+}
+/** Appended to the response when the tool re-ran a thrown transient connection
+ *  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.`;
+export function describeAttempt(priorAfterRuns, cap, opts = {}) {
+    const attempt = priorAfterRuns + 1;
+    const remaining = Math.max(0, cap - attempt);
+    const head = `Execution attempt ${attempt} of ${cap} for this file (maxFixAttempts=${cap}).`;
+    if (remaining === 0) {
+        return (`${head} No fix-and-rerun attempts remain: do not edit and re-run this file ` +
+            `again — report it as failed with these details.`);
+    }
+    const budget = `${head} ${remaining} fix-and-rerun attempt${remaining === 1 ? "" : "s"} remain` +
+        `${remaining === 1 ? "s" : ""}. `;
+    if (opts.unchangedRerun) {
+        // The file's contents did not move since the previous run: this WAS the
+        // one unchanged re-run the file gets. Say so instead of offering another.
+        return (budget +
+            `This run was an unchanged re-run of the previous one (same file contents), ` +
+            `so no further unchanged re-run is allowed for this file: change the test ` +
+            `file or its inputs to address the cause above, or report it.`);
+    }
+    return (budget +
+        `Re-run only after changing the test file or its ` +
+        `inputs to address the cause above. A file gets ONE unchanged re-run, for ` +
+        `either of two failures: a run that produced no output at all, or a ` +
+        `connection error — and not even that when this response carries the tool's ` +
+        `retry note, which means the tool has already spent it.`);
+}
+export function buildExecutionFailureText(result, opts = {}) {
     const output = stripVTControlCharacters(result.output || "").trim();
     const facts = [`status=${result.status}`];
     if (typeof result.exitCode === "number")
@@ -288,22 +602,27 @@ export function buildExecutionFailureText(result) {
         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 " +
             "here shows that. Check any Errors line below and that the test runner " +
-            "started, then retry once; if it fails the same way, report the execution " +
-            "failure with its cause unresolved and leave the generated test unchanged.");
+            "started, then " +
+            (opts.unchangedRerun
+                ? "— this run was already an unchanged re-run of the previous one, so do " +
+                    "NOT re-run it again — "
+                : "re-run it once unchanged if the attempt budget still allows it and this " +
+                    "response carries no retry note — a run that produced no output is one " +
+                    "of the two cases an unchanged re-run is right (the other is a " +
+                    "connection error), and neither applies once the tool has already " +
+                    "re-run the file itself; if it fails the same way, ") +
+            "report the execution failure with its cause unresolved and leave the " +
+            "generated test unchanged.");
     }
     if (errors.length > 0)
         sections.push(`Errors: ${errors.join("; ")}`);
@@ -317,357 +636,664 @@ export function buildExecutionFailureText(result) {
     }
     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()
-                .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()
-                .optional()
-                .describe("The owner/repo whose analysis section to write execution results into (e.g. 'letsramp/api-insight'). In a multi-repo run, ALWAYS set it — 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. Omit only for a single-repo run."),
-        },
+        inputSchema,
         _meta: {
             keywords: ["run test", "execute test"],
         },
     }, async (params, extra) => {
-        let errorResult;
-        // 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
+        // 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;
-            }
-            const rebaseline = resolveRebaselineSnapshots(params.rebaselineSnapshots, params.phase);
-            if (rebaseline.error) {
-                errorResult = toolError(rebaseline.error);
-                return errorResult;
+        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
+        // report reads. Only a call with no run at all executes uncounted. A blank
+        // path is "omitted", not a file, so it takes the same fallback. Inside a
+        // run, a named path must be THIS run's file under any spelling: another
+        // run's (or a copied) state file would hand the file a fresh counter and
+        // put the result where the report never looks, so it is refused before
+        // anything is queued or written. The path is then canonicalized (real
+        // path) so every later read and write names one file — a write through a
+        // symlink would otherwise replace the link instead of the target.
+        const requestedStateFile = params.stateFile?.trim();
+        let stateFilePath;
+        if (requestedStateFile) {
+            const own = resolveOwnRunStatePath(requestedStateFile);
+            if (own.refusal) {
+                // Worded here, not with the shared refusal: that one ends "leave
+                // stateFile out", and this tool's other messages and the prompt say
+                // to pass it on every call. Both are true; say so in one sentence.
+                return toolError(`Not executed: stateFile names ${requestedStateFile}, which is not this run's state file. ` +
+                    `Pass this run's stateFile (${currentRunStateFile()}) with repository — or leave stateFile out, ` +
+                    `and the run's own file is used. The attempt cap is enforced against that file either way.`);
             }
-            const rebaselineSnapshots = rebaseline.snapshots;
-            if (rebaselineSnapshots.length > 0) {
-                if (!params.stateFile) {
-                    errorResult = toolError("rebaselineSnapshots requires stateFile: the refresh is authorized against the UPDATE verdict skyramp_actions persisted there.");
+            stateFilePath = own.path;
+        }
+        else {
+            stateFilePath = currentRunStateFile();
+        }
+        if (stateFilePath)
+            stateFilePath = canonicalStateFilePath(stateFilePath);
+        // The "no run at all" branch: nothing below counts or records. Say so
+        // where an operator will look six months later, and tell the agent the
+        // result will not reach the report.
+        if (!stateFilePath) {
+            logger.warning(`${TOOL_NAME} has no run state: attempt cap not enforced, result not recorded`, {
+                testFile: params.testFile,
+                resolvedRunStatePath: resolveRunStatePath(),
+            });
+        }
+        // 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 —
+        // is a read-modify-write of one section, so two calls in the same run
+        // for ANY two files could overwrite each other. Serializing the whole
+        // handler on the state file closes every one of those windows at once;
+        // reserve/persist also serialize on this key and re-enter it. The prompt
+        // already forbids parallel execute calls; this keeps the state exact even
+        // when that is ignored. The key is the file's real path, so two spellings
+        // of one state file share one queue. A call with no run state serializes
+        // per file (a symlink and its target share one queue via the canonical path).
+        return runSerialized(stateFilePath
+            ? stateFileKey(stateFilePath)
+            : canonicalTestPath(params.testFile), async () => {
+            let errorResult;
+            try {
+                if (!path.isAbsolute(params.testFile)) {
+                    errorResult = toolError(`testFile must be an absolute path, got: ${params.testFile}`);
                     return errorResult;
                 }
-                const authState = await StateManager.fromStatePath(params.stateFile).readRepoData(params.repository);
-                const auth = authorizeRebaseline(authState, params.testFile, rebaselineSnapshots);
-                if (auth.error) {
-                    errorResult = toolError(auth.error);
+                // 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;
                 }
-            }
-            // 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 (params.stateFile) {
-                try {
-                    const stateManager = StateManager.fromStatePath(params.stateFile);
-                    const stateData = await stateManager.readRepoData(params.repository);
-                    const entry = stateData?.existingTests?.find((t) => t.testFile === 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.`,
-                                },
-                            ],
-                        };
+                // 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;
                     }
                 }
-                catch (err) {
-                    logger.warning(`External-test guard could not read stateFile (${err.message}); proceeding with execution`);
-                }
-            }
-            // 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.
-            await stageAndRecordRetrofits(params.testFile, undefined, params.stateFile);
-            // 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 params.stateFile 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. The external-test guard
-            // below already reads params.stateFile, so this one honours the same input.
-            const owedReuseVerification = await pendingReuseDebt(params.testFile, params.stateFile, params.testType);
-            if (owedReuseVerification) {
-                errorResult = toolError(owedReuseVerification);
-                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, params.stateFile);
-            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, params.stateFile);
-            // 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 (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;
                     }
-                    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"));
+                    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;
                     }
                 }
-            }
-            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.
-            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)
-                : {};
-            let result;
-            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 10s...", { error: errMsg });
-                    await sendProgress(50, 100, "SUT connection error — retrying in 10s...");
-                    await new Promise((r) => setTimeout(r, 10_000));
-                    result = await executionService.executeTest(execOptions, onExecutionProgress);
+                // 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"));
+                const rebaseline = resolveRebaselineSnapshots(params.rebaselineSnapshots, params.phase);
+                if (rebaseline.error) {
+                    errorResult = toolError(rebaseline.error);
+                    return errorResult;
                 }
-                else {
-                    throw firstErr;
+                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(stateFilePath).readRepoData(params.repository);
+                    const auth = authorizeRebaseline(authState, params.testFile, snapshots);
+                    if (auth.error) {
+                        errorResult = toolError(auth.error);
+                        return errorResult;
+                    }
                 }
-            }
-            // Update stateFile with execution results if provided. Multi-repo: write
-            // into the section for `repository` (primary when omitted/matching the
-            // root) of the run-scoped file.
-            if (params.stateFile) {
-                try {
-                    const stateManager = StateManager.fromStatePath(params.stateFile);
-                    const stateData = await stateManager.readRepoData(params.repository);
-                    if (stateData && stateData.existingTests) {
-                        const testIndex = stateData.existingTests.findIndex((t) => t.testFile === params.testFile);
-                        if (testIndex >= 0) {
-                            if (params.phase === "before") {
-                                stateData.existingTests[testIndex].executionBefore = result;
-                            }
-                            else {
-                                stateData.existingTests[testIndex].executionAfter = result;
-                            }
-                            await stateManager.writeRepoData(stateData, {
-                                repo: params.repository,
-                            });
-                            logger.info(`Updated stateFile with execution results for ${params.testFile}`);
-                        }
-                        else {
-                            logger.warning(`Test file ${params.testFile} not found in stateFile`);
+                // `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.
+                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".
+                        const pinned = await readPinnedMaxFixAttempts(stateSection.file);
+                        const current = getMaxFixAttempts();
+                        maxFixAttempts = pinned ?? current;
+                        if (pinned !== undefined && pinned !== current) {
+                            logger.warning("Enforcing the attempt cap pinned in the run's state, not the current prompt's", { pinned, current, stateFile: stateSection.file });
                         }
+                        record =
+                            stateData.testExecutions?.[canonicalTestPath(params.testFile)];
+                    }
+                    catch (err) {
+                        errorResult = toolError(`Not executed: the attempt-cap check could not use stateFile ${stateSection.file} — ${err.message}. ` +
+                            `Fix the stateFile or repository argument and call again; do not drop stateFile.`);
+                        return errorResult;
+                    }
+                    priorAfterRuns = record?.afterRuns ?? 0;
+                    unchangedRerun =
+                        params.phase === "after" &&
+                            record?.phase === "after" &&
+                            record.fileHash !== undefined &&
+                            record.fileHash === fileHash;
+                    const refusal = fixAttemptRefusal(record, params.phase, maxFixAttempts, params.testFile);
+                    if (refusal) {
+                        logger.info(`Refusing execution of ${params.testFile}: attempt cap ${maxFixAttempts} reached`);
+                        errorResult = toolError(refusal);
+                        return errorResult;
                     }
                 }
-                catch (err) {
-                    logger.error(`Failed to update stateFile: ${err.message}`);
-                    // Don't fail the tool call if stateFile update fails
+                // SKYR-4220: a utils file left unstaged ships a test importing a module the PR lacks.
+                await stageAndRecordRetrofits(params.testFile, undefined, stateFilePath);
+                const owedReuse = await pendingReuseDebt(params.testFile, stateFilePath, params.testType);
+                if (owedReuse) {
+                    errorResult = toolError(owedReuse);
+                    return errorResult;
                 }
-            }
-            // 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, params.stateFile);
-            // 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}`);
-                        }
-                    }
+                const assertionFeedback = await assertionFeedbackForExecution(params.testFile, stateFilePath);
+                if (assertionFeedback) {
+                    errorResult = toolError(assertionFeedback);
+                    return errorResult;
                 }
-                if (outcome.notRefreshed.length > 0 && params.stateFile) {
+                await recordAssertionExecution(params.testFile, params.testType, stateFilePath);
+                // 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 stateManager = StateManager.fromStatePath(params.stateFile);
-                        const stateData = await stateManager.readRepoData(params.repository);
-                        if (stateData?.maintenanceVerdicts) {
-                            const reconciled = applyRefreshOutcomeToVerdicts(stateData.maintenanceVerdicts, params.testFile, outcome, EXECUTOR_DOCKER_IMAGE);
-                            await stateManager.writeRepoData({ ...stateData, maintenanceVerdicts: reconciled.verdicts }, { repo: params.repository });
-                            if (reconciled.note)
-                                refreshOutcomeText += ` ${reconciled.note}`;
-                        }
+                        const reservation = await reserveTestExecutionAttempt(stateSection.file, stateSection.repo, params.testType, params.phase, params.testFile, maxFixAttempts, fileHash);
+                        priorAfterRuns = reservation.priorAfterRuns;
+                        maxFixAttempts = reservation.cap;
+                        reserved = true;
                     }
                     catch (err) {
-                        logger.warning(`Could not reconcile the maintenance verdict with the refresh outcome: ${err.message}`);
+                        errorResult = toolError(`Not executed: could not reserve the execution attempt in stateFile ${stateSection.file} (${err.message}).`);
+                        return errorResult;
                     }
                 }
+                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 {
+                    return command === undefined
+                        ? await runInExecutor(runParams, snapshots, budget, onExecutionProgress, sendProgress)
+                        : await runOnHost(runParams, command, cwd, snapshots, budget);
+                }
+                catch (err) {
+                    return accountForThrow(runParams, err, budget);
+                }
             }
-            const withRefreshOutcome = (text) => refreshOutcomeText ? `${text}\n\n${refreshOutcomeText}` : text;
-            // Progress is already reported by TestExecutionService
-            // Only report final status if not already at 100%
-            if (result.status !== TestExecutionStatus.Pass) {
-                errorResult = toolError(withRefreshOutcome(withVideoInfo(buildExecutionFailureText(result), result.videoPath)));
+            catch (err) {
+                errorResult = toolError(`Test execution failed: ${err.message}`);
                 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) {
-            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;
-                }
+            finally {
+                AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
+                    testFile: params.testFile,
+                    language: params.language,
+                    testType: params.testType,
+                }).catch((err) => {
+                    logger.warning("Analytics event failed", { error: String(err) });
+                });
             }
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
-                testFile: params.testFile,
-                workspacePath: params.workspacePath,
-                language: params.language,
-                testType: params.testType,
-            }).catch((err) => {
-                logger.warning("Analytics event failed", { error: String(err) });
-            });
-        }
+        });
     });
 }