@skyramp/mcp 0.3.3 → 0.3.4

package/build/tools/test-management/analyzeTestHealthTool.js

@@ -62,7 +62,7 @@ export function registerAnalyzeTestHealthTool(server) {
         inputSchema: {
             stateFile: z
                 .string()
-                .describe("Path to the analyze-changes-state.json file returned by skyramp_analyze_changes (the stateFile field in its output). Do NOT pass summaryOutputFile or testbot-result.txt here."),
+                .describe("Path to the analyze-changes-state.json file returned by skyramp_analyze_changes (the stateFile field in its output). Do NOT pass testbot-result.txt here."),
             blueprintCaptured: z
                 .boolean()
                 .optional()
@@ -88,10 +88,10 @@ export function registerAnalyzeTestHealthTool(server) {
                 return toolError(`State file is empty or invalid: ${args.stateFile}${args.repository ? ` (no section for repository ${args.repository})` : ""}. Call skyramp_analyze_changes first to generate a valid state file.`);
             }
             if (!repositoryPath || typeof repositoryPath !== "string") {
-                return toolError(`repositoryPath not found in state file metadata. The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt. Re-run skyramp_analyze_changes to regenerate it.`);
+                return toolError(`repositoryPath not found in state file metadata. The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not testbot-result.txt. Re-run skyramp_analyze_changes to regenerate it.`);
             }
             if (!Array.isArray(stateData.existingTests)) {
-                return toolError(`stateFile does not contain test discovery data (existingTests missing). The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt.`);
+                return toolError(`stateFile does not contain test discovery data (existingTests missing). The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not testbot-result.txt.`);
             }
             // External tests: UPDATE only — REGENERATE/DELETE are report-only (enforced in
             // skyramp_actions). Already scoped to relevant ones by discovery.

package/build/tools/test-management/registerTestPlanTool.js

@@ -128,38 +128,57 @@ function toDraftedScenario(input) {
         testType: input.testType,
     };
 }
-/** Build the agent-submitted candidates, running discriminator verification
- *  against the persisted diff text. Failed claims demote (never reject). */
-function buildAgentCandidates(candidates, diffText) {
-    const demotions = [];
-    const built = candidates.map((input) => {
+/** Build the agent-submitted candidates. Discriminator claims are verified
+ *  later, by {@link applyDiscriminatorClaims}, once the merge has settled which
+ *  scenario each name resolves to. */
+function buildAgentCandidates(candidates) {
+    return candidates.map((input) => {
         const scenario = toDraftedScenario(input);
-        const candidateId = computeCandidateId(scenario);
-        let verifiedDiscriminator;
-        if (input.discriminator) {
-            const claim = input.discriminator;
-            const result = validateDiscriminator(scenario, claim, diffText);
-            if (result.verified) {
-                verifiedDiscriminator = claim.kind;
-            }
-            else {
-                demotions.push({
-                    candidateId,
-                    reason: result.reason ?? `${claim.kind} discriminator claim could not be verified.`,
-                });
-            }
-        }
-        const candidate = {
+        return {
             scenario,
             priority: derivePriorityTier(scenario),
             novelty: Novelty.NEW,
             source: CandidateSource.AGENT,
-            candidateId,
-            ...(verifiedDiscriminator ? { verifiedDiscriminator } : {}),
+            candidateId: computeCandidateId(scenario),
         };
-        return candidate;
     });
-    return { candidates: built, demotions };
+}
+/**
+ * Verify each declared discriminator against the candidate that actually won
+ * the merge, and mark it. Failed claims demote (never reject).
+ *
+ * Runs AFTER the merge, not while building the agent's candidates: a server
+ * pre-seeded candidate wins the name, so verifying the agent's copy first
+ * attaches the result to a candidate that is about to be discarded — silently
+ * stripping the verification. Verification is against the WINNER's
+ * steps, so a claim that only held for the agent's rewrite is correctly refused
+ * rather than carried across.
+ *
+ * The marker is cleared before the current claim is applied. Each call replaces
+ * the agent's previous submission (see the `candidates` schema), and
+ * recoverServerCandidates restores whatever the LAST plan recorded — so keeping
+ * it would let a boost earned by an earlier registration outlive the claim that
+ * earned it, on a submission that no longer makes that claim or whose new claim
+ * fails.
+ */
+function applyDiscriminatorClaims(candidates, claimsByKey, diffText, reposWithoutDiff = []) {
+    const demotions = [];
+    const marked = candidates.map((candidate) => {
+        const { verifiedDiscriminator: _stale, ...unmarked } = candidate;
+        const claim = claimsByKey.get(scenarioMergeKey(candidate.scenario.scenarioName) || candidate.candidateId);
+        if (!claim)
+            return unmarked;
+        const result = validateDiscriminator(candidate.scenario, claim, diffText, reposWithoutDiff);
+        if (result.verified) {
+            return { ...unmarked, verifiedDiscriminator: claim.kind };
+        }
+        demotions.push({
+            candidateId: candidate.candidateId,
+            reason: result.reason ?? `${claim.kind} discriminator claim could not be verified.`,
+        });
+        return unmarked;
+    });
+    return { candidates: marked, demotions };
 }
 /** Recover full Candidates for pre-seeded ("server") plan items by matching
  *  candidateId back to the analyzed scenarios (repositoryAnalysis.scenarios) —
@@ -190,15 +209,49 @@ function recoverServerCandidates(priorPlan, allScenarios) {
     }
     return recovered;
 }
-function resolveBudgetContext(stateData) {
+/** Whether a repo section's persisted diff classification contains any new,
+ *  modified, or removed endpoint — the same signal `computeScoredCandidates`
+ *  derives `hasApiChanges` from at analyze time. */
+function sectionHasApiChanges(data) {
+    const diff = data?.repositoryAnalysis?.diff;
+    return ((diff?.newEndpoints?.length ?? 0) > 0 ||
+        (diff?.modifiedEndpoints?.length ?? 0) > 0 ||
+        (diff?.removedEndpoints?.length ?? 0) > 0);
+}
+function resolveBudgetContext(stateData, fullState) {
     const pbc = stateData.planBudgetContext;
-    return {
+    const base = {
         maxGenerate: pbc?.maxGenerate ?? MAX_TESTS_TO_GENERATE,
         maxTotal: pbc?.maxTotal ?? MAX_RECOMMENDATIONS,
         isUIOnlyPR: pbc?.isUIOnlyPR ?? false,
         hasFrontendChanges: pbc?.hasFrontendChanges ?? false,
         externalCoverage: new Set(pbc?.externalCoverageKeys ?? []),
     };
+    const relatedSections = Object.values(fullState?.relatedRepos ?? {}).map((section) => section.data);
+    if (relatedSections.length === 0)
+        return base;
+    // SKYR-4204: isUIOnlyPR/hasFrontendChanges are per-SECTION facts — each
+    // analyze call computes them from its own repo's diff. The approved plan is
+    // one run-wide decision, so a frontend-only PRIMARY diff must not put the
+    // budgeter on its all-UI branch (backendGenerateCount() = 0) while a related
+    // repo carries endpoint changes; that pinned GENERATE to UI placeholders and
+    // left every API candidate in ADDITIONAL regardless of maxGenerate. Derive
+    // the flags across ALL sections. A related repo checked out on its default
+    // branch classifies no endpoint changes, so it leaves a UI-only run UI-only.
+    // Budget numbers come from the root (primary) section: the testbot prompt
+    // passes topN/maxGenerate only to the primary analyze call, so related
+    // sections carry defaults.
+    const sections = [fullState ?? undefined, ...relatedSections];
+    const hasFrontendChanges = sections.some((s) => s?.planBudgetContext?.hasFrontendChanges ?? false);
+    const hasApiChanges = sections.some(sectionHasApiChanges);
+    const rootPbc = fullState?.planBudgetContext;
+    return {
+        maxGenerate: rootPbc?.maxGenerate ?? base.maxGenerate,
+        maxTotal: rootPbc?.maxTotal ?? base.maxTotal,
+        isUIOnlyPR: hasFrontendChanges && !hasApiChanges,
+        hasFrontendChanges,
+        externalCoverage: base.externalCoverage,
+    };
 }
 function describeGenerationCall(item) {
     switch (item.testType) {
@@ -316,9 +369,27 @@ export function registerRegisterTestPlanTool(server) {
                 errorResult = toolError(`State file is empty or invalid: ${params.stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
                 return errorResult;
             }
-            const diffText = stateData.diffText ?? "";
+            // SKYR-4203: one register call carries candidates for EVERY repo of the
+            // run, but `stateData` is a single repo's section — and the candidate
+            // schema has no per-candidate repository, so a related repo's anchors
+            // were unverifiable by construction. Verify anchors (and rank diff-hunk
+            // proximity) against the union of ALL sections' diffs: an anchor
+            // grounded in a related repo's change is as real as one in the
+            // primary's. Sections with no diff (a related repo checked out on its
+            // default branch) are collected so an unmatched anchor reads as
+            // uncheckable rather than ungrounded.
+            const fullState = await stateManager.readFullState();
+            const diffSections = [
+                { repo: fullState?.metadata?.repository ?? "the primary repository", diff: fullState?.diffText },
+                ...Object.entries(fullState?.relatedRepos ?? {}).map(([repo, section]) => ({
+                    repo,
+                    diff: section.data?.diffText,
+                })),
+            ];
+            const diffText = diffSections.map((s) => s.diff).filter(Boolean).join("\n");
+            const reposWithoutDiff = diffSections.filter((s) => !s.diff).map((s) => s.repo);
             const allScenarios = stateData.repositoryAnalysis?.scenarios ?? [];
-            const { candidates: agentCandidates, demotions } = buildAgentCandidates(params.candidates ?? [], diffText);
+            const agentCandidates = buildAgentCandidates(params.candidates ?? []);
             const serverCandidates = recoverServerCandidates(stateData.approvedPlan, allScenarios);
             // Merge by scenario-name identity, NOT the full content-hashed candidateId:
             // the server (analyze_changes) and the agent frequently draft their own
@@ -341,7 +412,18 @@ export function registerRegisterTestPlanTool(server) {
                 merged.set(mergeKey(candidate), candidate);
             for (const candidate of serverCandidates)
                 merged.set(mergeKey(candidate), candidate);
-            const allCandidates = [...merged.values()];
+            // The agent declares a claim per scenario NAME, so key the claims the
+            // same way the merge does and verify against whichever copy survived.
+            const claimsByKey = new Map();
+            // Keyed through mergeKey, not scenarioMergeKey alone: a name that
+            // slugifies to nothing (e.g. an all-non-ASCII name) would be stored
+            // under "" while the lookup falls back to the candidateId, so the claim
+            // would be neither verified nor demoted.
+            (params.candidates ?? []).forEach((input, i) => {
+                if (input.discriminator)
+                    claimsByKey.set(mergeKey(agentCandidates[i]), input.discriminator);
+            });
+            const { candidates: allCandidates, demotions } = applyDiscriminatorClaims([...merged.values()], claimsByKey, diffText, reposWithoutDiff);
             // An empty union would persist an authoritative plan with an empty
             // GENERATE list, which the generation gate then enforces — bricking
             // the run until re-registration. Reject instead so the agent can
@@ -351,7 +433,7 @@ export function registerRegisterTestPlanTool(server) {
                     "Submit your complete candidate list (every test you would generate or recommend) in `candidates` — an empty plan would block all generation.");
                 return errorResult;
             }
-            const budgetContext = resolveBudgetContext(stateData);
+            const budgetContext = resolveBudgetContext(stateData, fullState);
             const result = selectPlan(allCandidates, { ...budgetContext, demotions, diffText });
             const approvedPlan = {
                 planId: crypto.randomUUID(),

package/build/types/TestExecution.d.ts

@@ -26,6 +26,20 @@ export interface TestExecutionResult extends TestExecutionData {
     testFile: string;
     videoPath?: string;
 }
+/**
+ * One browser execution's recorded video, as persisted in run state by
+ * skyramp_execute_test and read back by skyramp_submit_report (SKYR-4156).
+ *
+ * `status`/`executedAt` are not rendered in the report — they identify WHICH
+ * execution the referenced recording belongs to, which matters because a retried
+ * test leaves a video directory behind for every attempt.
+ */
+export interface VideoRecord {
+    /** Host path to the recorded video.webm. */
+    videoPath: string;
+    status: TestExecutionStatus;
+    executedAt: string;
+}
 export interface BatchExecutionResult {
     totalTests: number;
     passed: number;

package/build/types/TestTypes.js

@@ -216,8 +216,9 @@ export const baseTestSchema = {
         .string()
         .default("")
         .describe("MUST be string of comma separated values like 'id=1,name=John' for URL query parameters. "
-        + "Workspace-configured api.defaultQueryParams (if set) are merged in automatically — "
-        + "no need to repeat them here. An explicit value for the same key here overrides the workspace default."),
+        + "Workspace-configured api.defaultQueryParams (if set) are merged in automatically, with any "
+        + "api.queryParamOverrides entry whose pathPattern matches this endpoint layered on top — "
+        + "no need to repeat them here. An explicit value for the same key here overrides both."),
     formParams: z
         .string()
         .default("")

package/build/types/TestbotPromptOptions.d.ts

@@ -16,7 +16,6 @@ export interface RelatedRepository {
 export interface TestbotPromptOptions {
     prTitle: string;
     prDescription: string;
-    summaryOutputFile: string;
     repositoryPath: string;
     baseBranch?: string;
     maxRecommendations?: number;

package/build/types/TestbotReport.d.ts

@@ -2,6 +2,15 @@ import type { DriftAction } from "./TestAnalysis.js";
 import type { TestExecutionStatus } from "./TestExecution.js";
 import type { HttpMethod, TestType } from "./TestTypes.js";
 import type { ReuseOutcome } from "./ReuseOutcome.js";
+/** Classification of an issuesFound entry. Bug is a product/code defect; the
+ *  other values are tooling noise that the Testbot report renders in its
+ *  Configuration Errors section instead of Issues Found. */
+export declare enum IssueFoundCategory {
+    Bug = "bug",
+    Lint = "lint",
+    Type = "type",
+    Config = "config"
+}
 /**
  * Shape of the JSON report written by skyramp_submit_report and read by testbot
  * for rendering as Markdown. All fields mirror the corresponding Zod schemas in
@@ -69,6 +78,7 @@ export interface TestbotReport {
     issuesFound: {
         description: string;
         severity?: "critical" | "high" | "medium" | "low";
+        category: IssueFoundCategory;
     }[];
     nextSteps: string[];
     commitMessage: string;

package/build/types/TestbotReport.js

@@ -1 +1,10 @@
-export {};
+/** Classification of an issuesFound entry. Bug is a product/code defect; the
+ *  other values are tooling noise that the Testbot report renders in its
+ *  Configuration Errors section instead of Issues Found. */
+export var IssueFoundCategory;
+(function (IssueFoundCategory) {
+    IssueFoundCategory["Bug"] = "bug";
+    IssueFoundCategory["Lint"] = "lint";
+    IssueFoundCategory["Type"] = "type";
+    IssueFoundCategory["Config"] = "config";
+})(IssueFoundCategory || (IssueFoundCategory = {}));

package/build/types/index.d.ts

@@ -2,6 +2,7 @@ export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } from "./TestbotReport.js";
+export { IssueFoundCategory } from "./TestbotReport.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome } from "./ReuseOutcome.js";
 export type { ReuseOutcome, ReuseSkippedEntry } from "./ReuseOutcome.js";
 export type { RelatedRepository, TestbotPromptOptions, } from "./TestbotPromptOptions.js";

package/build/types/index.js

@@ -1,4 +1,5 @@
 export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
+export { IssueFoundCategory } from "./TestbotReport.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome } from "./ReuseOutcome.js";

package/build/utils/AnalysisStateManager.d.ts

@@ -7,13 +7,33 @@ import type { CandidateUiPage } from "./uiPageEnumerator.js";
 import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
 import type { ApprovedPlanItem } from "../types/Recommendation.js";
 import type { ExternalTestRunRecord } from "../types/ExternalTestExecution.js";
+import type { VideoRecord } from "../types/TestExecution.js";
 export type { CandidateUiPage } from "./uiPageEnumerator.js";
 export declare function setTestsRepoDir(dir: string | undefined): void;
 export declare function getTestsRepoDir(): string | undefined;
-/** Filename of the run-scoped analysis state file under `<RUNNER_TEMP>/skyramp/`.
+/** Filename of the run-scoped analysis state file under `runArtifactDir()`.
  *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
  *  which LOOKS there cannot drift apart. */
 export declare const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
+/**
+ * Directory holding this run's Skyramp artifacts — the state file, and the report written
+ * beside it (SKYR-4147) — or undefined outside a run.
+ *
+ * `RUNNER_TEMP` is a fresh directory per CI job, and the caller and this server can each
+ * work it out from the environment on their own. So neither has to tell the other where
+ * the run's files live, and the path never passes through the model.
+ *
+ * The GitHub Action is the only caller customers run, and GitHub sets `RUNNER_TEMP` for
+ * it; the eval harness sets it itself. Nothing customers run is on another CI system, so
+ * the GitHub-specific name is only a naming problem — it does not break anything today.
+ * If a caller on another CI system is added, rename this then, or let it read that
+ * system's variable. Do not add a second variable for a caller that does not exist.
+ *
+ * Kept in one place for the same reason `RUN_STATE_FILE_NAME` is: the directory used to be
+ * written out at three call sites, so only the filename was safe from the three copies
+ * drifting apart. testbot keeps its matching copy in one place too, in `skyrampTempDir()`.
+ */
+export declare function runArtifactDir(): string | undefined;
 export declare function setActiveRunStatePath(stateFilePath: string): void;
 export declare function getActiveRunStatePath(): string | undefined;
 /** Reset the run anchor — for tests, and as a safety hook between runs. */
@@ -25,7 +45,7 @@ export declare function clearActiveRunStatePath(): void;
  * `setActiveRunStatePath` is only called by skyramp_analyze_changes on multi-repo
  * runs (the ones carrying a `repository` param), but a single-repo Testbot run's
  * path is still deterministic in CI: the StateManager constructor above roots
- * "analysis" state under `$RUNNER_TEMP/skyramp/`. Falling back to that covers
+ * "analysis" state under `runArtifactDir()`. Falling back to that covers
  * single-repo runs without a new anchor mechanism. Standalone/IDE usage has no
  * RUNNER_TEMP and resolves to undefined — correct, since there is no run state.
  *
@@ -166,6 +186,20 @@ export interface UnifiedAnalysisState {
      *  which computes every value in-process; skyramp_submit_report merges it into
      *  the report's `reuse` field. Never supplied by the LLM. */
     reuseOutcomes?: Record<string, ReuseRecord>;
+    /**
+     * SKYR-4156. Recorded video per executed browser test, keyed by test-file
+     * BASENAME (the same key `reuseOutcomes` uses, so matching needs no path
+     * normalization). Written in-process by skyramp_execute_test — the only place
+     * the path is known — and merged into the report's `testResults[].videoPath` by
+     * skyramp_submit_report. Never supplied by the LLM.
+     *
+     * Deliberately separate from `existingTests[].executionBefore/After`: those only
+     * exist for tests skyramp_analyze_changes discovered, so a NEWLY generated spec
+     * has nowhere to record into — which is exactly how one run recorded three videos
+     * and referenced none of them. Last write wins, so a retried execution replaces
+     * the earlier attempt's now-stale directory.
+     */
+    executionVideos?: Record<string, VideoRecord>;
 }
 /**
  * State file metadata

package/build/utils/AnalysisStateManager.js

@@ -35,10 +35,32 @@ export function getTestsRepoDir() {
  * Single-repo / standalone calls (no `repository`) never set or read this.
  */
 let _activeRunStatePath;
-/** Filename of the run-scoped analysis state file under `<RUNNER_TEMP>/skyramp/`.
+/** Filename of the run-scoped analysis state file under `runArtifactDir()`.
  *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
  *  which LOOKS there cannot drift apart. */
 export const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
+/**
+ * Directory holding this run's Skyramp artifacts — the state file, and the report written
+ * beside it (SKYR-4147) — or undefined outside a run.
+ *
+ * `RUNNER_TEMP` is a fresh directory per CI job, and the caller and this server can each
+ * work it out from the environment on their own. So neither has to tell the other where
+ * the run's files live, and the path never passes through the model.
+ *
+ * The GitHub Action is the only caller customers run, and GitHub sets `RUNNER_TEMP` for
+ * it; the eval harness sets it itself. Nothing customers run is on another CI system, so
+ * the GitHub-specific name is only a naming problem — it does not break anything today.
+ * If a caller on another CI system is added, rename this then, or let it read that
+ * system's variable. Do not add a second variable for a caller that does not exist.
+ *
+ * Kept in one place for the same reason `RUN_STATE_FILE_NAME` is: the directory used to be
+ * written out at three call sites, so only the filename was safe from the three copies
+ * drifting apart. testbot keeps its matching copy in one place too, in `skyrampTempDir()`.
+ */
+export function runArtifactDir() {
+    const runnerTemp = process.env.RUNNER_TEMP?.trim();
+    return runnerTemp ? path.join(runnerTemp, "skyramp") : undefined;
+}
 export function setActiveRunStatePath(stateFilePath) {
     _activeRunStatePath = stateFilePath;
 }
@@ -56,7 +78,7 @@ export function clearActiveRunStatePath() {
  * `setActiveRunStatePath` is only called by skyramp_analyze_changes on multi-repo
  * runs (the ones carrying a `repository` param), but a single-repo Testbot run's
  * path is still deterministic in CI: the StateManager constructor above roots
- * "analysis" state under `$RUNNER_TEMP/skyramp/`. Falling back to that covers
+ * "analysis" state under `runArtifactDir()`. Falling back to that covers
  * single-repo runs without a new anchor mechanism. Standalone/IDE usage has no
  * RUNNER_TEMP and resolves to undefined — correct, since there is no run state.
  *
@@ -70,8 +92,9 @@ export function resolveRunStatePath(explicitPath) {
     const anchored = getActiveRunStatePath();
     if (anchored)
         return anchored;
-    if (process.env.RUNNER_TEMP) {
-        return path.join(process.env.RUNNER_TEMP, "skyramp", RUN_STATE_FILE_NAME);
+    const runDir = runArtifactDir();
+    if (runDir) {
+        return path.join(runDir, RUN_STATE_FILE_NAME);
     }
     return undefined;
 }
@@ -169,17 +192,15 @@ export class StateManager {
     constructor(stateType = "analysis", sessionId, stateDir, stateFilePath) {
         this.stateType = stateType;
         this.sessionId = sessionId || crypto.randomUUID();
+        const runDir = stateType === "analysis" ? runArtifactDir() : undefined;
         if (stateFilePath) {
             this.stateFile = stateFilePath;
         }
-        else if (stateType === "analysis" && process.env.RUNNER_TEMP) {
-            // In CI (testbot action), RUNNER_TEMP is a job-isolated dir that both the
-            // action and this tool can independently derive — no LLM input needed.
-            // TODO: interim step — remove this branch when stateFile and summaryOutputFile are merged
-            // (see getTestbotPrompt TODO). RUNNER_TEMP is GitHub Actions-specific; other CI systems
-            // (Jenkins, GitLab, Buildkite) must set it explicitly. Once merged, path flows through
-            // summaryOutputFile which is already testbot-controlled and CI-agnostic.
-            this.stateFile = path.join(process.env.RUNNER_TEMP, "skyramp", RUN_STATE_FILE_NAME);
+        else if (runDir) {
+            // In CI, the run directory is fresh per job and the caller and this tool each work
+            // it out from the environment — no LLM input needed. It is also where
+            // skyramp_submit_report writes the report (SKYR-4147).
+            this.stateFile = path.join(runDir, RUN_STATE_FILE_NAME);
         }
         else {
             const baseDir = stateDir || os.tmpdir();
@@ -435,7 +456,7 @@ export class StateManager {
      * @returns Number of files deleted
      */
     static async cleanupOldFiles(maxAgeHours = 24, stateDir, stateTypes) {
-        const baseDir = stateDir || (process.env.RUNNER_TEMP ? path.join(process.env.RUNNER_TEMP, "skyramp") : os.tmpdir());
+        const baseDir = stateDir || runArtifactDir() || os.tmpdir();
         const files = await fs.promises.readdir(baseDir).catch(() => []);
         const statePrefixes = stateTypes
             ? stateTypes.map((t) => STATE_FILE_PREFIXES[t])

package/build/utils/scenarioDrafting.js

@@ -905,7 +905,13 @@ export function draftResponseShapeScenarios(hopEndpoints, byFile, addedFieldsByF
                 : `reflects the change made in ${fileName}`;
             const nameSuffix = addedFields.length > 0 ? addedFields[0] : "response-change";
             scenarios.push({
-                scenarioName: `${slugify(resource)}-response-shape-${slugify(nameSuffix)}`,
+                // The endpoint path is part of the name because one file can reach
+                // several GETs and neither the resource token (from the file) nor the
+                // suffix (a field name, or the constant "response-change" when the hunk
+                // yields none) varies between them. Two same-named candidates are
+                // merged by name in registerTestPlanTool, so a collision here loses a
+                // scenario outright rather than showing up as a duplicate.
+                scenarioName: `${slugify(resource)}-response-shape-${slugify(nameSuffix)}-${slugify(ep.path)}`,
                 description: `Verify GET ${ep.path} response ${fieldsPhrase}.`,
                 category: "breaking_change",
                 priority: "high",

package/build/utils/skyrampMdContent.d.ts

@@ -2,4 +2,4 @@
  * Skill content for skyramp.md — installed at auto-discovery paths: ~/.claude/skills/skyramp/SKILLS.md, ~/.cursor/skills/skyramp/SKILLS.md, ~/.github/skills/skyramp.md
  * Follows the SKILL.md specification: https://agentskills.io/what-are-skills#the-skill-md-file
  */
-export declare const SKYRAMP_MD_CONTENT = "---\nname: skyramp\ndescription: Generate, execute, and maintain API tests (smoke, contract, fuzz, load, integration, E2E, UI) using Skyramp MCP tools.\n---\n\n# Skyramp\n\n## When to use this skill\nUse this skill whenever the user asks to generate, run, or maintain API tests. Always read `<workspace-root>/.skyramp/workspace.yml` first to get `language`, `framework`, `outputDir`, and `api.baseUrl` \u2014 do not ask the user for values already present.\n\n---\n\n## Tools\n\n### Workspace Setup\n1. **`skyramp_initialize_workspace`** \u2014 Create or update `.skyramp/workspace.yml` in a git repository workspace. Scan the repo for all services before calling. Required before any other Skyramp tool.\n\n### Test Generation\n2. **`skyramp_smoke_test_generation`** \u2014 Verify an endpoint is reachable and returns a valid response.\n3. **`skyramp_contract_test_generation`** \u2014 Validate implementation matches OpenAPI/Swagger schema.\n4. **`skyramp_fuzz_test_generation`** \u2014 Send malformed or boundary inputs to find edge cases and security issues.\n5. **`skyramp_load_test_generation`** \u2014 Test performance under concurrent load. Optional: `loadDuration`, `loadNumThreads`. Accepts `trace` instead of `apiSchema`/`endpointURL`.\n6. **`skyramp_integration_test_generation`** \u2014 Multi-step workflows across one or more services. Supply one of: `apiSchema`+`endpointURL`, `trace`, or `scenarioFile`. Do not combine them.\n7. **`skyramp_e2e_test_generation`** \u2014 Full user journey covering UI and backend. Requires `trace` and `playwrightInput` zip. Do not pass `apiSchema` or `endpointURL`.\n8. **`skyramp_ui_test_generation`** \u2014 UI-only tests from Playwright recordings. Requires `playwrightInput` zip.\n\n### Trace Generation\n9. **`skyramp_start_trace_collection`** \u2014 Start capturing backend traffic. Set `playwright: true` for UI or E2E tests. Use an absolute path for `outputDir`.\n10. **`skyramp_stop_trace_collection`** \u2014 Stop capture and save the trace. Use the same `outputDir` and `playwrightEnabled` values as start.\n11. **`skyramp_scenario_test_generation`** \u2014 Scenario trace generation. Describe a multi-step flow in natural language to produce a scenario file. Pass output to `skyramp_integration_test_generation` via `scenarioFile`.\n\n### Test Execution\n12. **`skyramp_execute_test`** \u2014 Run a single Skyramp-generated test file. Required: `workspacePath`, `language`, `testType`, `testFile`. Optional: `stateFile` (writes execution results back for health analysis). For multiple tests, call sequentially to avoid env var conflicts.\n\n### Test Analysis & Maintenance\n13. **`skyramp_analyze_changes`** \u2014 Unified entry point: scans endpoints, discovers tests, computes diff. Takes `repositoryPath` and `scope`. Returns `stateFile` + recommendations.\n14. **`skyramp_analyze_test_health`** \u2014 Drift and health assessment for existing tests. Takes `stateFile`. Returns LLM prompt for scoring.\n15. **`skyramp_actions`** \u2014 Execute UPDATE / REGENERATE / VERIFY / DELETE actions. Takes `stateFile`. Call after analyze_test_health.\n\n### Code Quality\n16. **`skyramp_fix_errors`** \u2014 Fix compilation or runtime errors in a generated test file.\n17. **`skyramp_modularization`** \u2014 Refactor a test file into reusable modules. Set `isTraceBased: true` for trace-based tests.\n18. **`skyramp_reuse_code`** \u2014 Pull shared helpers from other Skyramp tests. Only when `code_reuse` was `true` at generation time.\n\n### Authentication\n19. **`skyramp_login`** \u2014 Log in to the Skyramp platform.\n20. **`skyramp_logout`** \u2014 Log out from the Skyramp platform.\n\n---\n\n## Prompts\n\nPrefer invoking a prompt over manually chaining tools \u2014 prompts run the full workflow automatically.\n\n- **`skyramp_trace_prompt`** \u2014 Trace collection setup and execution.\n- **`skyramp_test_health_analysis`** \u2014 Full maintenance flow (discover \u2192 drift \u2192 health \u2192 actions).\n- **`skyramp_testbot`** \u2014 PR-scoped recommendations + maintenance + report. Required: `prTitle`, `prDescription`, `summaryOutputFile`, `repositoryPath`.\n\n---\n\n## Workflows\n\nUse these when a prompt is not available.\n\n**Generate and run a test**\nRead `.skyramp/workspace.yml` \u2192 Call appropriate generation tool \u2192 `skyramp_execute_test`\n\n**Trace-based test (integration / load / E2E / UI)**\n`skyramp_start_trace_collection` (set `playwright: true` for UI/E2E) \u2192 User exercises the app \u2192 `skyramp_stop_trace_collection` \u2192 Call target generation tool with `trace` (and `playwrightInput` for E2E/UI)\n\n**Scenario \u2192 integration test**\n`skyramp_scenario_test_generation` \u2192 `skyramp_integration_test_generation` with `scenarioFile`\n\n**Recommend tests for a PR**\n`skyramp_analyze_changes` (with `scope: \"branch_diff\"`) \u2192 follow enrichment steps \u2192 `skyramp_recommend_tests` \u2192 Generate recommended tests\n\n**Maintain existing tests**\n`skyramp_analyze_changes` \u2192 `skyramp_analyze_test_health` \u2192 *(optional)* execute tests via `skyramp_execute_test` with `stateFile` param (writes results back) \u2192 `skyramp_actions` (do not skip)\n\n---\n\n## Conventions\n\n- **`endpointURL`** \u2014 Full URL to a specific endpoint, not just the base URL. Build from `api.baseUrl` + path (e.g. `http://localhost:8000/api/v1/users`).\n- **`outputDir`** \u2014 Use absolute paths for both test output and trace collection.\n- **Mutually exclusive inputs** \u2014 `apiSchema`/`endpointURL`, `trace`, and `scenarioFile` are mutually exclusive for integration and load tests. Use exactly one.\n- **Sequential execution** \u2014 Execute tests sequentially (not in parallel) to avoid environment variable conflicts with `SKYRAMP_TEST_BASE_URL`.\n";
+export declare const SKYRAMP_MD_CONTENT = "---\nname: skyramp\ndescription: Generate, execute, and maintain API tests (smoke, contract, fuzz, load, integration, E2E, UI) using Skyramp MCP tools.\n---\n\n# Skyramp\n\n## When to use this skill\nUse this skill whenever the user asks to generate, run, or maintain API tests. Always read `<workspace-root>/.skyramp/workspace.yml` first to get `language`, `framework`, `outputDir`, and `api.baseUrl` \u2014 do not ask the user for values already present.\n\n---\n\n## Tools\n\n### Workspace Setup\n1. **`skyramp_initialize_workspace`** \u2014 Create or update `.skyramp/workspace.yml` in a git repository workspace. Scan the repo for all services before calling. Required before any other Skyramp tool.\n\n### Test Generation\n2. **`skyramp_smoke_test_generation`** \u2014 Verify an endpoint is reachable and returns a valid response.\n3. **`skyramp_contract_test_generation`** \u2014 Validate implementation matches OpenAPI/Swagger schema.\n4. **`skyramp_fuzz_test_generation`** \u2014 Send malformed or boundary inputs to find edge cases and security issues.\n5. **`skyramp_load_test_generation`** \u2014 Test performance under concurrent load. Optional: `loadDuration`, `loadNumThreads`. Accepts `trace` instead of `apiSchema`/`endpointURL`.\n6. **`skyramp_integration_test_generation`** \u2014 Multi-step workflows across one or more services. Supply one of: `apiSchema`+`endpointURL`, `trace`, or `scenarioFile`. Do not combine them.\n7. **`skyramp_e2e_test_generation`** \u2014 Full user journey covering UI and backend. Requires `trace` and `playwrightInput` zip. Do not pass `apiSchema` or `endpointURL`.\n8. **`skyramp_ui_test_generation`** \u2014 UI-only tests from Playwright recordings. Requires `playwrightInput` zip.\n\n### Trace Generation\n9. **`skyramp_start_trace_collection`** \u2014 Start capturing backend traffic. Set `playwright: true` for UI or E2E tests. Use an absolute path for `outputDir`.\n10. **`skyramp_stop_trace_collection`** \u2014 Stop capture and save the trace. Use the same `outputDir` and `playwrightEnabled` values as start.\n11. **`skyramp_scenario_test_generation`** \u2014 Scenario trace generation. Describe a multi-step flow in natural language to produce a scenario file. Pass output to `skyramp_integration_test_generation` via `scenarioFile`.\n\n### Test Execution\n12. **`skyramp_execute_test`** \u2014 Run a single Skyramp-generated test file. Required: `workspacePath`, `language`, `testType`, `testFile`. Optional: `stateFile` (writes execution results back for health analysis). For multiple tests, call sequentially to avoid env var conflicts.\n\n### Test Analysis & Maintenance\n13. **`skyramp_analyze_changes`** \u2014 Unified entry point: scans endpoints, discovers tests, computes diff. Takes `repositoryPath` and `scope`. Returns `stateFile` + recommendations.\n14. **`skyramp_analyze_test_health`** \u2014 Drift and health assessment for existing tests. Takes `stateFile`. Returns LLM prompt for scoring.\n15. **`skyramp_actions`** \u2014 Execute UPDATE / REGENERATE / VERIFY / DELETE actions. Takes `stateFile`. Call after analyze_test_health.\n\n### Code Quality\n16. **`skyramp_fix_errors`** \u2014 Fix compilation or runtime errors in a generated test file.\n17. **`skyramp_modularization`** \u2014 Refactor a test file into reusable modules. Set `isTraceBased: true` for trace-based tests.\n18. **`skyramp_reuse_code`** \u2014 Pull shared helpers from other Skyramp tests. Only when `code_reuse` was `true` at generation time.\n\n### Authentication\n19. **`skyramp_login`** \u2014 Log in to the Skyramp platform.\n20. **`skyramp_logout`** \u2014 Log out from the Skyramp platform.\n\n---\n\n## Prompts\n\nPrefer invoking a prompt over manually chaining tools \u2014 prompts run the full workflow automatically.\n\n- **`skyramp_trace_prompt`** \u2014 Trace collection setup and execution.\n- **`skyramp_test_health_analysis`** \u2014 Full maintenance flow (discover \u2192 drift \u2192 health \u2192 actions).\n- **`skyramp_testbot`** \u2014 PR-scoped recommendations + maintenance + report. Required: `prTitle`, `prDescription`, `repositoryPath`.\n\n---\n\n## Workflows\n\nUse these when a prompt is not available.\n\n**Generate and run a test**\nRead `.skyramp/workspace.yml` \u2192 Call appropriate generation tool \u2192 `skyramp_execute_test`\n\n**Trace-based test (integration / load / E2E / UI)**\n`skyramp_start_trace_collection` (set `playwright: true` for UI/E2E) \u2192 User exercises the app \u2192 `skyramp_stop_trace_collection` \u2192 Call target generation tool with `trace` (and `playwrightInput` for E2E/UI)\n\n**Scenario \u2192 integration test**\n`skyramp_scenario_test_generation` \u2192 `skyramp_integration_test_generation` with `scenarioFile`\n\n**Recommend tests for a PR**\n`skyramp_analyze_changes` (with `scope: \"branch_diff\"`) \u2192 follow enrichment steps \u2192 `skyramp_recommend_tests` \u2192 Generate recommended tests\n\n**Maintain existing tests**\n`skyramp_analyze_changes` \u2192 `skyramp_analyze_test_health` \u2192 *(optional)* execute tests via `skyramp_execute_test` with `stateFile` param (writes results back) \u2192 `skyramp_actions` (do not skip)\n\n---\n\n## Conventions\n\n- **`endpointURL`** \u2014 Full URL to a specific endpoint, not just the base URL. Build from `api.baseUrl` + path (e.g. `http://localhost:8000/api/v1/users`).\n- **`outputDir`** \u2014 Use absolute paths for both test output and trace collection.\n- **Mutually exclusive inputs** \u2014 `apiSchema`/`endpointURL`, `trace`, and `scenarioFile` are mutually exclusive for integration and load tests. Use exactly one.\n- **Sequential execution** \u2014 Execute tests sequentially (not in parallel) to avoid environment variable conflicts with `SKYRAMP_TEST_BASE_URL`.\n";

package/build/utils/skyrampMdContent.js

@@ -58,7 +58,7 @@ Prefer invoking a prompt over manually chaining tools — prompts run the full w
 
 - **\`skyramp_trace_prompt\`** — Trace collection setup and execution.
 - **\`skyramp_test_health_analysis\`** — Full maintenance flow (discover → drift → health → actions).
-- **\`skyramp_testbot\`** — PR-scoped recommendations + maintenance + report. Required: \`prTitle\`, \`prDescription\`, \`summaryOutputFile\`, \`repositoryPath\`.
+- **\`skyramp_testbot\`** — PR-scoped recommendations + maintenance + report. Required: \`prTitle\`, \`prDescription\`, \`repositoryPath\`.
 
 ---
 

package/build/utils/urlPath.d.ts

@@ -0,0 +1,37 @@
+/**
+ * URL/path derivations shared by the generation tools.
+ *
+ * Both helpers here existed as private copies before: `pathFromEndpointURL`
+ * lived in tools/generate-tests/planGuard.ts, and the base-path derivation was
+ * inlined in ScenarioGenerationService and then mirrored a second time by
+ * generateBatchScenarioRestTool so it could predict the path the service would
+ * emit (SKYR-4127). Two copies of "which path does this request actually have"
+ * is exactly the kind of thing that drifts silently — a pattern that stops
+ * matching produces a 403, not a test failure — so they live in one place now.
+ *
+ * Dependency-free on purpose: this sits below both services/ and tools/ so
+ * either layer can import it without an inversion.
+ */
+/**
+ * Extract the URL path from a generation tool's `endpointURL` param.
+ *
+ * Falls back to treating the value as a bare path when it isn't a parseable
+ * absolute URL, and to undefined when it's neither.
+ *
+ * `new URL()` percent-encodes `{param}` placeholders (`{id}` → `%7Bid%7D`),
+ * which breaks two consumers: plan matchKeys are computed from raw scenario
+ * paths with braces intact, and workspace queryParamOverrides patterns are
+ * authored with braces. Restore them.
+ */
+export declare function pathFromEndpointURL(endpointURL: string | undefined): string | undefined;
+/**
+ * The path prefix a service's `baseURL` contributes to every request under it:
+ * the URL's pathname with any trailing slash removed. Empty string when
+ * `baseURL` is absent or unparseable, and for a host-only URL (`http://host`
+ * → pathname `/` → `""`).
+ *
+ * This is the value ScenarioGenerationService prepends to each step path, so
+ * anything that needs to reason about the emitted path — such as matching
+ * workspace queryParamOverrides — must derive it the same way.
+ */
+export declare function deriveBasePath(baseURL: string | undefined): string;

package/build/utils/urlPath.js

@@ -0,0 +1,55 @@
+/**
+ * URL/path derivations shared by the generation tools.
+ *
+ * Both helpers here existed as private copies before: `pathFromEndpointURL`
+ * lived in tools/generate-tests/planGuard.ts, and the base-path derivation was
+ * inlined in ScenarioGenerationService and then mirrored a second time by
+ * generateBatchScenarioRestTool so it could predict the path the service would
+ * emit (SKYR-4127). Two copies of "which path does this request actually have"
+ * is exactly the kind of thing that drifts silently — a pattern that stops
+ * matching produces a 403, not a test failure — so they live in one place now.
+ *
+ * Dependency-free on purpose: this sits below both services/ and tools/ so
+ * either layer can import it without an inversion.
+ */
+/**
+ * Extract the URL path from a generation tool's `endpointURL` param.
+ *
+ * Falls back to treating the value as a bare path when it isn't a parseable
+ * absolute URL, and to undefined when it's neither.
+ *
+ * `new URL()` percent-encodes `{param}` placeholders (`{id}` → `%7Bid%7D`),
+ * which breaks two consumers: plan matchKeys are computed from raw scenario
+ * paths with braces intact, and workspace queryParamOverrides patterns are
+ * authored with braces. Restore them.
+ */
+export function pathFromEndpointURL(endpointURL) {
+    if (!endpointURL)
+        return undefined;
+    try {
+        return new URL(endpointURL).pathname.replace(/%7B/gi, "{").replace(/%7D/gi, "}");
+    }
+    catch {
+        return endpointURL.startsWith("/") ? endpointURL : undefined;
+    }
+}
+/**
+ * The path prefix a service's `baseURL` contributes to every request under it:
+ * the URL's pathname with any trailing slash removed. Empty string when
+ * `baseURL` is absent or unparseable, and for a host-only URL (`http://host`
+ * → pathname `/` → `""`).
+ *
+ * This is the value ScenarioGenerationService prepends to each step path, so
+ * anything that needs to reason about the emitted path — such as matching
+ * workspace queryParamOverrides — must derive it the same way.
+ */
+export function deriveBasePath(baseURL) {
+    if (!baseURL)
+        return "";
+    try {
+        return new URL(baseURL).pathname.replace(/\/$/, "");
+    }
+    catch {
+        return "";
+    }
+}