@skyramp/mcp 0.4.1 → 0.4.2-rc.1

package/build/tools/generate-tests/generateIntegrationRestTool.js

@@ -9,6 +9,7 @@ import { isTestbotEnabled } from "../../utils/featureFlags.js";
 import { guardScenarioApproved, pathFromEndpointURL } from "./planGuard.js";
 import { readScenarioNameFromFile } from "./scenarioFileIdentity.js";
 import { toolError } from "../../utils/utils.js";
+import { enhanceAssertionsStep } from "../../skills/enhanceAssertionsSkill.js";
 const ADD_ASSERTIONS_DEFAULT = isTestbotEnabled();
 const integrationTestSchema = z
     .object({
@@ -26,7 +27,9 @@ const integrationTestSchema = z
     exclude: baseTraceSchema.shape.exclude.optional(),
     scenarioFile: z
         .string()
-        .endsWith(".json", { message: "scenarioFile must be a path to a .json file." })
+        .endsWith(".json", {
+        message: "scenarioFile must be a path to a .json file.",
+    })
         .optional()
         .describe("Absolute path to the scenario JSON file produced by skyramp_batch_scenario_test_generation. " +
         "When provided, DO NOT also pass apiSchema or endpointURL — the scenario file already contains all endpoint information."),
@@ -63,9 +66,12 @@ export class IntegrationTestService extends TestGenerationService {
         return { ...result, content };
     }
     buildAssertionEnhancementInstructions() {
+        // Routed through the shared helper, never hardcoded: MCP tool output wins
+        // over the prompt on conflict, so a literal tool name here overrides the
+        // prompt's skill routing and the skill is never reached (SKYR-4310).
         return `
 ### CRITICAL NEXT STEP — Enhance response body assertions after each request
-Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated test file, \`testType: "integration"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
+${enhanceAssertionsStep("integration", "generated test file")}
 `;
     }
     buildGenerationOptions(params) {
@@ -113,16 +119,22 @@ Generate an integration test from a scenario file or a live endpoint trace.
     }, async (params) => {
         if (params.scenarioFile && (params.apiSchema || params.endpointURL)) {
             return {
-                content: [{
+                content: [
+                    {
                         type: "text",
                         text: "**skyramp_integration_test_generation Error: Conflicting parameters**\n\n" +
                             "`scenarioFile` is mutually exclusive with `apiSchema` and `endpointURL`.\n\n" +
-                            "**Received:** scenarioFile=" + params.scenarioFile +
+                            "**Received:** scenarioFile=" +
+                            params.scenarioFile +
                             (params.apiSchema ? ", apiSchema=" + params.apiSchema : "") +
-                            (params.endpointURL ? ", endpointURL=" + params.endpointURL : "") + "\n\n" +
+                            (params.endpointURL
+                                ? ", endpointURL=" + params.endpointURL
+                                : "") +
+                            "\n\n" +
                             "**How to fix:** Remove `apiSchema` and `endpointURL` when passing `scenarioFile` — " +
                             "the scenario file already contains all endpoint and schema information.",
-                    }],
+                    },
+                ],
                 isError: true,
             };
         }
@@ -134,7 +146,10 @@ Generate an integration test from a scenario file or a live endpoint trace.
             // match, so an active plan rejects it; standalone usage (no active
             // run / no plan) is still allowed by guardScenarioApproved itself.
             const scenarioName = readScenarioNameFromFile(params.scenarioFile);
-            guardMessage = await guardScenarioApproved({ scenarioName, testType: "integration" });
+            guardMessage = await guardScenarioApproved({
+                scenarioName,
+                testType: "integration",
+            });
         }
         else {
             guardMessage = await guardScenarioApproved({

package/build/tools/generate-tests/generateMockRestTool.js

@@ -480,7 +480,9 @@ This file must:
                 ...responseDataOption,
                 url: params.endpointURL,
                 topic: params.kafkaTopic,
-                requestData: params.requestData?.trim() ? params.requestData : undefined,
+                requestData: params.requestData?.trim()
+                    ? params.requestData
+                    : undefined,
             };
         }
         return {

package/build/tools/generate-tests/generateUIRestTool.d.ts

@@ -8,6 +8,7 @@ export declare class UITestService extends TestGenerationService {
     protected buildGenerationOptions(params: BaseTestParams & {
         playwrightInput?: string;
         uniqueUIFormInputs?: string[];
+        testName?: string;
     }): any;
     protected handleApiAnalysis(_params: BaseTestParams): Promise<CallToolResult | null>;
     generateTest(params: BaseTestParams & Record<string, any>): Promise<CallToolResult>;
@@ -19,6 +20,7 @@ export declare const uiTestSchema: {
     include: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
     exclude: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
     uniqueUIFormInputs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    testName: z.ZodOptional<z.ZodString>;
     output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
     outputDir: z.ZodString;
     force: z.ZodDefault<z.ZodBoolean>;

package/build/tools/generate-tests/generateUIRestTool.js

@@ -1,4 +1,4 @@
-import { baseSchema, languageSchema, TestType, codeRefactoringSchema, baseTraceSchema, } from "../../types/TestTypes.js";
+import { baseSchema, languageSchema, TestType, codeRefactoringSchema, baseTraceSchema, testNameField, } from "../../types/TestTypes.js";
 import { z } from "zod";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { TestGenerationService, } from "../../services/TestGenerationService.js";
@@ -7,6 +7,7 @@ import { getPersonaPrefix } from "../../prompts/personas.js";
 import { isTestbotEnabled } from "../../utils/featureFlags.js";
 import { toolError } from "../../utils/utils.js";
 import { checkTraceReuse, recordTraceOutput } from "./trace-reuse-guard.js";
+import { enhanceAssertionsStep } from "../../skills/enhanceAssertionsSkill.js";
 const TOOL_NAME = "skyramp_ui_test_generation";
 export class UITestService extends TestGenerationService {
     getTestType() {
@@ -20,6 +21,11 @@ export class UITestService extends TestGenerationService {
             // SKYR-4012: create-form inputs the agent flagged as unique-constrained,
             // so Skyramp codegen types a per-run-unique value into them.
             uniqueUIFormInputs: params.uniqueUIFormInputs,
+            // SKYR-4468: free-form title for the generated test, so the spec names the
+            // behaviour it verifies instead of the generic `testUi`. The option is
+            // inert until the pinned @skyramp/skyramp release carries it — the client
+            // ignores options it does not know, so passing it early is safe.
+            testName: params.testName,
         };
     }
     async handleApiAnalysis(_params) {
@@ -51,7 +57,7 @@ export class UITestService extends TestGenerationService {
     buildUIPostGenInstructions(enhanceAssertions, modularize) {
         const steps = [];
         if (enhanceAssertions) {
-            steps.push(`### Step ${steps.length + 1} — Enhance UI assertions [REQUIRED]\nCall \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.`);
+            steps.push(`### Step ${steps.length + 1} — Enhance UI assertions [REQUIRED]\n${enhanceAssertionsStep("ui", "generated test file")}`);
         }
         if (modularize) {
             steps.push(`### Step ${steps.length + 1} — Modularize [REQUIRED]\nCall \`skyramp_modularization\` with \`testFile\` set to the absolute path of the generated test file, \`language\`, \`testType: "ui"\`, and \`isTraceBased: true\`.`);
@@ -85,6 +91,7 @@ export const uiTestSchema = {
         .array(z.string().min(1))
         .optional()
         .describe("Create-form inputs whose value is UNIQUE-constrained (e.g. a name/slug that the backend rejects as a duplicate). Identify each by the accessible label or selector you typed into during recording (the same value passed to getByLabel/getByPlaceholder/getByRole, or a raw selector). Skyramp types a per-run-unique value into these inputs — and reuses it in later assertions — so the generated UI test can be re-run without hitting a duplicate/conflict error. Inspect the app's data model for unique constraints; omit when no create-form field is unique-constrained."),
+    testName: testNameField("testUi"),
     output: baseSchema.shape.output,
     outputDir: baseSchema.shape.outputDir,
     force: baseSchema.shape.force,
@@ -122,6 +129,8 @@ This tells you exactly which frontend files changed so you record traces for the
 
 **Idempotency (re-runnable create flows):** If the recorded flow creates a resource by typing into a UNIQUE-constrained field (a name/slug the backend rejects as a duplicate on a second run), pass those inputs in \`uniqueUIFormInputs\`. Skyramp then types a per-run-unique value into them (and reuses it in later assertions) so the generated test can be re-run without a duplicate/conflict failure.
 
+**Test title:** Pass \`testName\` with the behaviour this recording verifies (e.g. "Add to cart from search results"), taken from the recommendation the recording came from. Omit it and the spec is titled \`testUi\`, which claims nothing.
+
 **DOM Analyzer tools for blueprint-aware recording:** alongside the basic \`browser_*\` interaction tools, the Skyramp MCP exposes \`browser_blueprint\` (canonical PageBlueprint capture). This enables semantic target selection and delta-derived assertions: capture a blueprint before each meaningful action, perform the action, then capture again — the delta between the two grounds your assertions in observable state changes rather than author guesses about what "success" looks like.
 
 **CRITICAL: Do NOT use skyramp_start_trace_collection/skyramp_stop_trace_collection for UI test recording — use browser_* tools + skyramp_export_zip instead.**`,

package/build/tools/generate-tests/loadTestSchema.js

@@ -1,8 +1,6 @@
 import { z } from "zod";
 import { baseTestSchema, baseTraceSchema } from "../../types/TestTypes.js";
-export const numericString = (description) => z
-    .string()
-    .refine((val) => !val || /^\d+$/.test(val), {
+export const numericString = (description) => z.string().refine((val) => !val || /^\d+$/.test(val), {
     message: `${description} must be a non-negative integer`,
 });
 export const loadTestSchema = {

package/build/tools/generate-tests/planGuard.js

@@ -4,7 +4,7 @@
  * Conditional on an ACTIVE run whose agent has registered a plan: standalone use
  * and runs with no plan are unaffected. The report gate refuses a missing plan.
  */
-import { resolveRunStatePath, StateManager } from "../../utils/AnalysisStateManager.js";
+import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateManager.js";
 import { matchesPlanCandidates, nameMatchedEndpointMismatches, nameMatchedTypeMismatches, } from "../../utils/planMatchKeys.js";
 import { TOOL_REGISTER_TEST_PLAN } from "../../toolNames.js";
 /** Re-exported for the generation tools that already import it from here.
@@ -23,7 +23,8 @@ export async function guardScenarioApproved(query) {
         return null;
     let stateData;
     try {
-        stateData = await StateManager.fromStatePath(statePath).readData();
+        stateData =
+            await StateManager.fromStatePath(statePath).readData();
     }
     catch {
         // Unreadable/corrupt state must never block generation on an infra hiccup.
@@ -52,7 +53,9 @@ export async function guardScenarioApproved(query) {
         // agent invented, and the message must not say otherwise.
         const plannedSteps = nearMisses
             .flatMap((item) => {
-            const steps = Array.isArray(item?.scenario?.steps) ? item.scenario.steps : [];
+            const steps = Array.isArray(item?.scenario?.steps)
+                ? item.scenario.steps
+                : [];
             return steps
                 .filter((step) => step?.method || step?.path)
                 .map((step) => `  - [${item?.scenario?.testType ?? "?"}] ${item?.scenario?.scenarioName ?? "(unnamed)"} ` +

package/build/tools/generate-tests/scenarioFileIdentity.js

@@ -16,7 +16,10 @@ import * as path from "path";
 import { logger } from "../../utils/logger.js";
 /** File name the batch tool writes for a scenario: `scenario_<slug>.json`. */
 export function scenarioFileNameFor(scenarioName) {
-    const slug = scenarioName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "scenario";
+    const slug = scenarioName
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "scenario";
     return `scenario_${slug}.json`;
 }
 /**

package/build/tools/generate-tests/scenarioLint.js

@@ -21,7 +21,7 @@
 import { singularize } from "../../utils/pluralization.js";
 const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 function isIdLikeKey(key) {
-    return /^(id|pk|uuid)$/i.test(key) || /_id$/i.test(key) || /[a-z]Id$/.test(key);
+    return (/^(id|pk|uuid)$/i.test(key) || /_id$/i.test(key) || /[a-z]Id$/.test(key));
 }
 function isIdishSegment(seg) {
     return /^\d+$/.test(seg) || UUID_RE.test(seg);
@@ -142,7 +142,13 @@ export function lintScenarioChaining(steps) {
                     existing.keys.push(key);
             }
             else {
-                list.push({ step: idx, segment, keys: [key], creates, collectionCreate });
+                list.push({
+                    step: idx,
+                    segment,
+                    keys: [key],
+                    creates,
+                    collectionCreate,
+                });
             }
             producers.set(value, list);
         });
@@ -160,7 +166,10 @@ export function lintScenarioChaining(steps) {
             segs.forEach((seg, i) => {
                 if (!isIdishSegment(seg) || refs.has(seg))
                     return;
-                refs.set(seg, { desc: "path segment", resource: owningSegment(segs, i) });
+                refs.set(seg, {
+                    desc: "path segment",
+                    resource: owningSegment(segs, i),
+                });
             });
         }
         // Body values: only id-like keys, or keys resource-affine to a producer.
@@ -170,7 +179,8 @@ export function lintScenarioChaining(steps) {
                 if (refs.has(value))
                     return;
                 const producerList = producers.get(value) ?? [];
-                const relevant = isIdLikeKey(key) || producerList.some((p) => keyResourceAffinity(key, p.segment));
+                const relevant = isIdLikeKey(key) ||
+                    producerList.some((p) => keyResourceAffinity(key, p.segment));
                 if (!relevant)
                     return;
                 refs.set(value, { desc: `body field "${key}"`, resource: key, key });
@@ -207,7 +217,9 @@ export function lintScenarioChaining(steps) {
             // by `collectionCreate`, so the measured `/orders/{id}/confirm` echo is
             // untouched.
             const creator = later.find((p) => p.creates && keyResourceAffinity(ref.resource, p.segment)) ??
-                later.find((p) => p.collectionCreate && ref.key !== undefined && p.keys.includes(ref.key));
+                later.find((p) => p.collectionCreate &&
+                    ref.key !== undefined &&
+                    p.keys.includes(ref.key));
             const echoesReferencingField = ref.key !== undefined &&
                 creator === undefined &&
                 later.every((p) => p.keys.every((k) => k === ref.key));

package/build/tools/generate-tests/trace-reuse-guard.js

@@ -70,8 +70,11 @@ export async function checkTraceReuse(playwrightInput, output, outputDir, allowT
     }
     const identity = outputIdentity(output, outputDir);
     const outputs = generatedFromTrace.get(key);
-    if (!allowTraceReuse && outputs && outputs.size > 0 && !outputs.has(identity)) {
-        const prior = [...outputs].map(p => path.basename(p)).join(", ");
+    if (!allowTraceReuse &&
+        outputs &&
+        outputs.size > 0 &&
+        !outputs.has(identity)) {
+        const prior = [...outputs].map((p) => path.basename(p)).join(", ");
         return {
             key,
             identity,

package/build/tools/generateEnrichedIntegrationTestTool.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { SkyrampClient } from "@skyramp/skyramp";
 import { logger } from "../utils/logger.js";
-import { RuntimeEnvironment, runtimeEnvironmentInputSchema } from "../types/TestTypes.js";
-import { injectMockImports, isSupportedMockEnrichmentLanguage } from "./enrichTestWithMocksTool.js";
+import { RuntimeEnvironment, TestType, runtimeEnvironmentInputSchema, } from "../types/TestTypes.js";
+import { injectMockImports, isSupportedMockEnrichmentLanguage, } from "./enrichTestWithMocksTool.js";
 import { isAuthorizationHeaderName } from "../utils/workspaceAuth.js";
 import { WORKER_CONTROL_PORT } from "../utils/versions.js";
+import { persistGeneratedTest } from "../utils/generatedTestRecord.js";
 import * as fs from "fs";
 import * as path from "path";
 import { isInsideExecutorWorkDir, executorWorkDirRefusal, generationTargets, } from "../utils/executorWorkDir.js";
@@ -130,7 +131,8 @@ export async function executeGenerateEnrichedIntegrationTest(params) {
         // if authScheme is set and authHeader is Authorization, use authType only.
         let resolvedAuthHeader = authHeader;
         const resolvedAuthType = authScheme;
-        if (resolvedAuthType !== undefined && isAuthorizationHeaderName(resolvedAuthHeader || "")) {
+        if (resolvedAuthType !== undefined &&
+            isAuthorizationHeaderName(resolvedAuthHeader || "")) {
             resolvedAuthHeader = undefined;
         }
         // This tool calls the client directly instead of going through
@@ -189,6 +191,10 @@ export async function executeGenerateEnrichedIntegrationTest(params) {
         const enrichedContent = injectMockImports(testContent, testFilePath, scenarioName, mockFiles, traceComments, resolvedLanguage);
         // Step 5: Write the enriched content back
         fs.writeFileSync(testFilePath, enrichedContent);
+        // This tool calls the client directly rather than going through
+        // TestGenerationService, so it has to record the file it wrote itself —
+        // otherwise nothing notices when the test it just created is never run.
+        await persistGeneratedTest(testFilePath, TestType.INTEGRATION);
         logger.info(`Generated and enriched integration test: ${testFilePath}`, {
             scenarioName,
             mockFileCount: mockFiles.length,

package/build/tools/one-click/oneClickTool.js

@@ -350,7 +350,9 @@ export function registerOneClickTool(server) {
         finally {
             void Promise.resolve(AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
                 workflow: params.workflow,
-            })).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            })).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/preflightMockCheckTool.js

@@ -1,22 +1,38 @@
 import { z } from "zod";
 import { validateMockCompatibility, MockProtocol, } from "../utils/mockCompatibility.js";
 const warningSchema = z.object({
-    code: z.string().describe("Warning code identifier (e.g. REST_LOOPBACK_URL, GRPC_PERSISTENT_CONN)."),
+    code: z
+        .string()
+        .describe("Warning code identifier (e.g. REST_LOOPBACK_URL, GRPC_PERSISTENT_CONN)."),
     message: z.string().describe("Human-readable description of the issue."),
-    suggestion: z.string().describe("Recommended action to resolve or work around the issue."),
-    affectedMocks: z.array(z.string()).describe("Mock identifiers (service name or endpoint URL) affected by this warning."),
-    blocking: z.boolean().optional().describe("When true, the affected mocks cannot intercept traffic and must not be generated or deployed."),
+    suggestion: z
+        .string()
+        .describe("Recommended action to resolve or work around the issue."),
+    affectedMocks: z
+        .array(z.string())
+        .describe("Mock identifiers (service name or endpoint URL) affected by this warning."),
+    blocking: z
+        .boolean()
+        .optional()
+        .describe("When true, the affected mocks cannot intercept traffic and must not be generated or deployed."),
 });
 const preflightOutputSchema = {
-    hasBlockers: z.boolean().describe("True when at least one warning is blocking. Blocking mocks must be removed from the generation list before proceeding."),
-    warnings: z.array(warningSchema).describe("All compatibility warnings. Inspect the blocking field on each entry; blocking ones must be skipped, advisory ones may proceed with caution."),
+    hasBlockers: z
+        .boolean()
+        .describe("True when at least one warning is blocking. Blocking mocks must be removed from the generation list before proceeding."),
+    warnings: z
+        .array(warningSchema)
+        .describe("All compatibility warnings. Inspect the blocking field on each entry; blocking ones must be skipped, advisory ones may proceed with caution."),
 };
 const TOOL_NAME = "skyramp_preflight_mock_check";
 const mockSpecSchema = z.object({
     protocol: z.nativeEnum(MockProtocol).describe("The protocol of the mock"),
     endpointURL: z.string().describe("The endpoint URL for the mock"),
     method: z.string().optional().describe("HTTP method (for REST mocks)"),
-    grpcServiceName: z.string().optional().describe("gRPC service name (for gRPC mocks)"),
+    grpcServiceName: z
+        .string()
+        .optional()
+        .describe("gRPC service name (for gRPC mocks)"),
     kafkaTopic: z.string().optional().describe("Kafka topic (for Kafka mocks)"),
 });
 const inputSchema = {

package/build/tools/runExistingTestsTool.d.ts

@@ -45,7 +45,7 @@ export interface RunExistingTestsParams {
     mode?: "confirm" | "verify";
     project?: string;
     stateFile?: string;
-    repository?: string;
+    repository: string;
     timeoutMs?: number;
     maxTests?: number;
 }

package/build/tools/runExistingTestsTool.js

@@ -5,12 +5,12 @@ import * as crypto from "crypto";
 import { promises as fs } from "fs";
 import { spawn } from "child_process";
 import { stripVTControlCharacters } from "util";
-import { WorkspaceConfigManager } from "../workspace/workspace.js";
-import { resolveSuites } from "../workspace/testSuites.js";
+import { WorkspaceConfigManager, } from "../workspace/workspace.js";
+import { resolveSuites, } from "../workspace/testSuites.js";
 import { StateManager, } from "../utils/AnalysisStateManager.js";
 import { buildPlaywrightArgs, parsePlaywrightJson, } from "../adapters/playwrightAdapter.js";
 import { buildPytestArgs, parsePytestJson } from "../adapters/pytestAdapter.js";
-import { buildJestArgs, buildVitestArgs, parseJestJson } from "../adapters/jestAdapter.js";
+import { buildJestArgs, buildVitestArgs, parseJestJson, } from "../adapters/jestAdapter.js";
 import { buildMochaArgs, parseMochaJson } from "../adapters/mochaAdapter.js";
 import picomatch from "picomatch";
 import { AnalyticsService } from "../services/AnalyticsService.js";
@@ -218,7 +218,13 @@ function toResolvedRunConfig(s) {
  *  text: sums counts, concatenates results, ANDs environmentHealthy, joins the
  *  unhealthy details. */
 export function aggregateRuns(parsed) {
-    const summary = { ran: 0, failed: 0, errored: 0, skipped: 0, truncated: false };
+    const summary = {
+        ran: 0,
+        failed: 0,
+        errored: 0,
+        skipped: 0,
+        truncated: false,
+    };
     const results = [];
     let environmentHealthy = true;
     const details = [];
@@ -354,7 +360,12 @@ export async function runExternalSuite(spec, cfg, opts) {
             stderrTail: stderr.slice(-STDERR_TAIL_CHARS),
             stdoutTail: outTail,
         }));
-        child.on("error", (e) => resolve({ code: -1, stdout: out, stderrTail: String(e), stdoutTail: outTail }));
+        child.on("error", (e) => resolve({
+            code: -1,
+            stdout: out,
+            stderrTail: String(e),
+            stdoutTail: outTail,
+        }));
     });
     let report;
     try {
@@ -420,7 +431,8 @@ export async function runExternalSuite(spec, cfg, opts) {
     if (!parsed.environmentHealthy) {
         const detail = buildOutputDiagnostic(stderrTail, stdoutTail);
         if (detail) {
-            parsed.healthDetail = `${parsed.healthDetail ?? `${spec.framework} environment unhealthy (exit ${code}).`} ${detail}`;
+            parsed.healthDetail = `${parsed.healthDetail ??
+                `${spec.framework} environment unhealthy (exit ${code}).`} ${detail}`;
         }
     }
     return parsed;
@@ -447,11 +459,11 @@ async function persistExternalRun(stateFile, repository, record) {
         const sm = StateManager.fromStatePath(stateFile);
         const state = await sm.readRepoData(repository);
         if (!state) {
-            logger.warning(`${TOOL_NAME}: no analysis state found for repo ${repository ?? "(primary)"}; skipping externalTestResults write`);
+            logger.warning(`${TOOL_NAME}: no analysis state found for repo ${repository}; skipping externalTestResults write`);
             return;
         }
         state.externalTestResults = [...(state.externalTestResults ?? []), record];
-        await sm.writeRepoData(state, { repo: repository });
+        await sm.updateRepoData(state, { repo: repository });
     }
     catch (err) {
         logger.error(`${TOOL_NAME}: failed to persist externalTestResults: ${err.message}`);
@@ -465,6 +477,12 @@ async function persistExternalRun(stateFile, repository, record) {
 export async function runExternalTests(params, deps = defaultDeps) {
     const mode = params.mode ?? "confirm";
     const selectors = params.testSelectors ?? [];
+    // `repository` names the state section; `stateFile` says whether there is any
+    // state to write. A standalone run — the SUT-setup canary, which runs before
+    // any analysis exists — names its repository but writes nothing.
+    const stateSection = params.stateFile
+        ? { file: params.stateFile, repo: params.repository }
+        : undefined;
     let effective = selectors;
     let truncated = false;
     if (params.maxTests && selectors.length > params.maxTests) {
@@ -483,17 +501,17 @@ export async function runExternalTests(params, deps = defaultDeps) {
             skipped: true,
             skipReason: reason,
         };
-        if (params.stateFile) {
-            await persistExternalRun(params.stateFile, params.repository, {
+        if (stateSection) {
+            await persistExternalRun(stateSection.file, stateSection.repo, {
                 ...skippedRun,
                 mode,
                 ranAt: deps.now(),
-                repository: params.repository,
+                repository: stateSection.repo,
             });
         }
         return skippedRun;
     }
-    const knownTestFiles = await loadKnownTestFiles(params.stateFile, params.repository);
+    const knownTestFiles = await loadKnownTestFiles(stateSection?.file, stateSection?.repo);
     const perSuite = [];
     for (const cfg of resolution.runs) {
         const routing = routeSelectorsToSuite({
@@ -515,12 +533,12 @@ export async function runExternalTests(params, deps = defaultDeps) {
                 skipReason: `suite "${cfg.serviceName}" owns ${owned}, and none of the ${routing.dropped.length} requested selector(s) fall under it — nothing for this suite to run. Widen its testSuites pathGlobs, or add a suite that owns those paths.`,
             };
             perSuite.push(routedOut);
-            if (params.stateFile) {
-                await persistExternalRun(params.stateFile, params.repository, {
+            if (stateSection) {
+                await persistExternalRun(stateSection.file, stateSection.repo, {
                     ...routedOut,
                     mode,
                     ranAt: deps.now(),
-                    repository: params.repository,
+                    repository: stateSection.repo,
                 });
             }
             continue;
@@ -538,15 +556,18 @@ export async function runExternalTests(params, deps = defaultDeps) {
         });
         const suiteResult = {
             ...parsed,
-            summary: { ...parsed.summary, truncated: parsed.summary.truncated || truncated },
+            summary: {
+                ...parsed.summary,
+                truncated: parsed.summary.truncated || truncated,
+            },
         };
         perSuite.push(suiteResult);
-        if (params.stateFile) {
-            await persistExternalRun(params.stateFile, params.repository, {
+        if (stateSection) {
+            await persistExternalRun(stateSection.file, stateSection.repo, {
                 ...suiteResult,
                 mode,
                 ranAt: deps.now(),
-                repository: params.repository,
+                repository: stateSection.repo,
             });
         }
     }
@@ -587,8 +608,9 @@ export function registerRunExistingTestsTool(server) {
                 .describe("Path to the analyze-changes state file. When set, results are appended to externalTestResults so drift analysis and the report can fold in CONFIRMED failures."),
             repository: z
                 .string()
-                .optional()
-                .describe("owner/repo whose state section to write into (multi-repo runs). Omit for a single-repo run."),
+                .trim()
+                .min(1)
+                .describe("owner/repo whose state section to write into. Set it on every call."),
             timeoutMs: z
                 .number()
                 .int()