@skyramp/mcp 0.4.1 → 0.4.2-rc.1

package/build/tools/executeSkyrampTestTool.js

@@ -10,13 +10,18 @@ import { makeProgressReporter } from "../utils/progress.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, getTestsRepoDir, resolveOwnRunStatePath, resolveRunStatePath, } from "../utils/AnalysisStateManager.js";
+import { DriftAction, TestSource, } 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 { 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";
@@ -193,7 +198,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 +215,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.`,
         };
@@ -237,7 +250,9 @@ export function applyRefreshOutcomeToVerdicts(verdicts, testFile, outcome, execu
         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)`;
@@ -246,7 +261,11 @@ export function applyRefreshOutcomeToVerdicts(verdicts, testFile, outcome, execu
             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;
@@ -275,7 +294,84 @@ export function describeRefreshOutcome(outcome) {
     }
     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.`;
+/** 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);
+    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")
@@ -302,8 +398,17 @@ export function buildExecutionFailureText(result) {
             "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("; ")}`);
@@ -357,6 +462,7 @@ export function registerExecuteSkyrampTestTool(server) {
                 .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
@@ -366,308 +472,502 @@ export function registerExecuteSkyrampTestTool(server) {
             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). " +
+                .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."),
+                .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."),
         },
         _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
-        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;
+        // `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(),
+            });
+        }
+        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 —
+        // 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;
+            // 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;
                 }
-                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.`,
-                                },
-                            ],
-                        };
+                // 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;
+                }
+                const rebaselineSnapshots = rebaseline.snapshots;
+                if (rebaselineSnapshots.length > 0) {
+                    if (!stateSection) {
+                        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);
+                    if (auth.error) {
+                        errorResult = toolError(auth.error);
+                        return errorResult;
                     }
                 }
-                catch (err) {
-                    logger.warning(`External-test guard could not read stateFile (${err.message}); proceeding with execution`);
+                // 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`);
+                    }
                 }
-            }
-            // 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;
+                // 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();
+                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;
                     }
-                    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"));
+                    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;
                     }
                 }
-            }
-            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);
+                // 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, 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);
+                    return errorResult;
                 }
-                else {
-                    throw firstErr;
+                // 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;
                 }
-            }
-            // 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}`);
+                // 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 {
-                            logger.warning(`Test file ${params.testFile} not found in stateFile`);
+                        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;
                         }
                     }
                 }
-                catch (err) {
-                    logger.error(`Failed to update stateFile: ${err.message}`);
-                    // Don't fail the tool call if stateFile update fails
+                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.");
                 }
-            }
-            // 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] ?? []) {
+                // 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.
+                if (stateSection) {
+                    try {
+                        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) {
+                        errorResult = toolError(`Not executed: could not reserve the execution attempt in stateFile ${stateSection.file} (${err.message}).`);
+                        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.
+                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;
+                    }
+                }
+                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 {
-                            await stageGeneratedPaths(path.join(snapshotDirFor(params.testFile), file));
+                            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 stage refreshed visual baseline ${file} for ${params.testFile}: ${err.message}`);
+                            logger.warning(`Could not reconcile the maintenance verdict with the refresh outcome: ${err.message}`);
                         }
                     }
                 }
-                if (outcome.notRefreshed.length > 0 && params.stateFile) {
+                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 {
-                        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}`;
-                        }
+                        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 (err) {
-                        logger.warning(`Could not reconcile the maintenance verdict with the refresh outcome: ${err.message}`);
+                    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 })}`;
                     }
                 }
-            }
-            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)));
+                errorResult = toolError(`Test execution failed: ${message}${retryNote}${attemptNote}${persistNote}${noRunNote}`);
                 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 {
+                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) => {
+                    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) });
-            });
-        }
+        });
     });
 }