@skyramp/mcp 0.3.2 → 0.3.3

package/build/index.js

@@ -45,6 +45,8 @@ import { registerProgressResource } from "./resources/progressResource.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { registerInitTriggerOnMCPInitialized } from "./utils/initAgent.js";
 import { isTestbotEnabled, isLocalDevEnabled } from "./utils/featureFlags.js";
+import { findRoot, readTestIdAttribute } from "./utils/pom-scope/index.js";
+import { discoverTestIdAttribute } from "./utils/pom-scope/testIdDiscovery.js";
 import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
 // One-click routing instructions — injected into MCP server instructions so agents
 // know to delegate to the one-click tool rather than self-orchestrating.
@@ -212,8 +214,51 @@ if (isTestbotEnabled()) {
     logger.info("Testbot tools enabled via SKYRAMP_FEATURE_TESTBOT");
 }
 infrastructureTools.forEach((registerTool) => registerTool(server));
-// Register Playwright browser tools (trace recording via browser automation)
-registerPlaywrightTools(server).catch((err) => {
+// Register Playwright browser tools (trace recording via browser automation).
+//
+// Tell the capture which attribute this repository uses for test ids. Without
+// it the capture assumes Playwright's `data-testid`, and a repo using anything
+// else gets no test-id anchor and a positional xpath for every element — which
+// resolves at capture time and breaks later, so the miss never announces itself
+// (SKYR-4136). This server is the only component that knows which repository it
+// is running against.
+//
+// A declared `use.testIdAttribute` is authoritative. Failing that, the
+// repository's own tests name the attribute whenever they select on it, so read
+// it out of their selectors rather than guessing from a list of popular names.
+// Never fatal: no answer leaves the capture on Playwright's default.
+(async () => {
+    let testIdAttribute;
+    try {
+        const root = await findRoot(process.cwd());
+        testIdAttribute = await readTestIdAttribute(root);
+        if (testIdAttribute) {
+            logger.info(`testIdAttribute declared by the Playwright config: ${testIdAttribute}`);
+        }
+        else {
+            const discovered = await discoverTestIdAttribute(root);
+            testIdAttribute = discovered.attribute;
+            if (testIdAttribute) {
+                // Log the runner-up counts: on a part-migrated repo the most-used
+                // attribute wins, and a wrong pick should be visible here rather than
+                // showing up later as brittle selectors.
+                logger.info(`testIdAttribute discovered from test selectors: ${testIdAttribute}`, { counts: discovered.counts, filesScanned: discovered.filesScanned });
+            }
+            else {
+                // No name rule can reach an arbitrary convention like `xyz-id`, so name
+                // what the selectors did contain and the variable that overrides it.
+                // Editing the repo's own Playwright config is the wrong instruction: a
+                // suite may have several, and none of them at the root.
+                logger.info("No testIdAttribute declared or discovered — capture stays on Playwright's data-testid. " +
+                    "Set PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE to override.", { attributesSeenInSelectors: discovered.observed, filesScanned: discovered.filesScanned });
+            }
+        }
+    }
+    catch (err) {
+        logger.warning("Could not determine this repository's testIdAttribute", { error: err });
+    }
+    await registerPlaywrightTools(server, { testIdAttribute });
+})().catch((err) => {
     logger.error("Failed to register Playwright tools", { error: err });
 });
 // Global error handlers for crash telemetry

package/build/playwright/PlaywrightTraceService.d.ts

@@ -17,6 +17,14 @@ export interface PlaywrightTraceOptions {
     headless?: boolean;
     /** Directory for output files (zip, HAR). Defaults to cwd. */
     outputDir?: string;
+    /**
+     * The attribute this repository uses for test ids, when its Playwright config
+     * declares one. Forwarded to the blueprint capture, which otherwise only
+     * recognises the common conventions and falls back to positional xpaths —
+     * brittle, and silently so. Only this server knows which repository it runs
+     * against, so only this server can supply it.
+     */
+    testIdAttribute?: string;
 }
 export declare class PlaywrightTraceService {
     private _backend;

package/build/playwright/PlaywrightTraceService.js

@@ -26,6 +26,7 @@ export class PlaywrightTraceService {
             this._backend = new TraceRecordingBackend({
                 headless: this._options.headless,
                 outputDir: this._options.outputDir || process.cwd(),
+                testIdAttribute: this._options.testIdAttribute,
             });
             // Initialize with a synthetic client info
             await this._backend.initialize({

package/build/prompts/pom-aware-code-reuse.js

@@ -1,5 +1,9 @@
 import { generateSkyrampHeader, SKYRAMP_UTILS_HEADER } from "../utils/utils.js";
+import { resolvePomCatalogPath } from "../utils/pom-catalog.js";
 export function getPomAwareCodeReusePrompt(testFile, language = "typescript", scopedPoms) {
+    // Resolved here, not left to the agent: the catalog only survives to the next
+    // run if it lands where delivery stages it (SKYR-4141).
+    const catalogPath = resolvePomCatalogPath(testFile);
     const isJs = language.toLowerCase() === "javascript";
     const ext = isJs ? "js" : "ts";
     const utilsFile = isJs ? "skyrampUtils.js" : "skyrampUtils.ts";
@@ -27,8 +31,6 @@ ${scopedPoms.tier2.map(renderPom).join("\n") || "(none)"}
 
 Do NOT glob or scan for other POM files. Proceed to STEP 2 and catalog exactly these files (plus any file they import or extend that you find essential while reading them).
 
-**Catalog-completeness guard for STEP 2a:** when checking for an existing \`skyramp-pom-catalog.md\`, it is only valid for THIS run if it already contains an entry for EVERY file listed above. If any listed file is missing from the catalog, do NOT reuse it wholesale — keep its existing entries and generate + append entries for the missing listed files (then use the updated catalog).
-
 **Decision:** continue to STEP 2.`
         : `## STEP 1: DETECT POM CLASSES IN THE PROJECT
 
@@ -89,10 +91,13 @@ ${step1Section}
 
 **Step 2a: Check for existing catalog (MANDATORY FIRST STEP)**
 
-Look for \`skyramp-pom-catalog.md\` walking UP from the test file's directory to the repository root; use the FIRST one found (catalogs from earlier runs may live at legacy locations — a found catalog is valid wherever it lives):
-- **If it exists:** Read it and verify it starts with \`<!-- skyramp-pom-catalog: auto-generated -->\`
-  - Valid → Output: *"Using existing POM catalog from /path/to/skyramp-pom-catalog.md"* and **skip to STEP 2b**
-  - Invalid → Continue to full catalog generation below
+Read the catalog at EXACTLY this path — the one canonical location. Do not search for it anywhere else:
+
+   \`${catalogPath}\`
+
+- **If it exists:** verify it starts with \`<!-- skyramp-pom-catalog: auto-generated -->\` AND already contains an entry for EVERY POM file STEP 1 identified — the files listed in STEP 1 above, or the files your own glob found, whichever applies.
+  - Valid and complete → Output: *"Using existing POM catalog from ${catalogPath}"* and **skip to STEP 2b**
+  - Invalid, or missing an entry for any STEP 1 file → do NOT reuse it wholesale — keep its existing entries and continue to full catalog generation below, generating and appending entries only for the missing files
 - **If it doesn't exist:** Continue to full catalog generation below
 
 ---
@@ -121,10 +126,14 @@ Before writing a single line of refactored code, do the following:
      - Whether the method wraps a multi-step sequence using sub-properties or components (e.g. \`searchAssetsByCondition\` internally calls \`searchConditionArea.expandWhenClosed()\`, \`clearBtn.click()\`, \`selectItemName()\`, \`valueKeyword.fill()\`, \`searchBtn.click()\`) — flag these as **wrapping methods**
    - Flag methods as **timing-aware**, **network-aware**, or **wrapping** as appropriate — all three are high-value substitution targets
 
-4. **Write the POM catalog — MANDATORY** — Write the complete catalog to \`skyramp-pom-catalog.md\` at the CANONICAL location: the top of the configured test directory (when this run's instructions declare one containing the test file), otherwise the nearest ancestor directory of the test file that contains a \`package.json\`, otherwise the repository root. Never invent a new location per run — determinism is what lets later runs reuse this file. This gives you a clean structured reference for STEP 2b and leaves a record for debugging.
+4. **Write the POM catalog — MANDATORY** — Write the complete catalog to EXACTLY this path, already resolved for this run, creating the parent directory first if it does not already exist:
+
+   \`${catalogPath}\`
+
+   Use it verbatim — do not re-derive it, shorten it, or pick a directory that looks more natural. Delivery commits this location; a catalog written anywhere else is discarded without warning, and the next run pays full POM rediscovery. This gives you a clean structured reference for STEP 2b and leaves a record for debugging.
 
 **BLOCKING: Do not proceed to STEP 2b until you have written this file and confirmed the path in a single output line:**
-*"POM catalog written to /path/to/skyramp-pom-catalog.md"*
+*"POM catalog written to ${catalogPath}"*
 
 **Verification gate:** Before continuing to STEP 2b, confirm you either (a) found and used an existing catalog in Step 2a, OR (b) just wrote a new catalog in step 4 above. If neither is true, STOP and complete step 4 now.
 

package/build/prompts/testbot/testbot-prompts.d.ts

@@ -1,21 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type Service } from "../../workspace/workspace.js";
-/** One related repository to analyze as shared context in multi-repo mode. */
-export interface RelatedRepository {
-    repositoryPath: string;
-    baseBranch?: string;
-    /** `owner/repo` slug, resolved by the action from the checkout's git remote.
-     *  Used verbatim as the `repository` argument/attribution for this repo so the
-     *  agent never has to infer it. */
-    repo: string;
-}
+import type { RelatedRepository, TestbotPromptOptions } from "../../types/TestbotPromptOptions.js";
 /**
  * Parse the JSON-encoded `relatedRepositories` argument passed via the testbot
  * prompt/resource. Returns undefined for missing/blank input or malformed JSON so the
  * caller cleanly falls back to single-repo behavior.
  */
 export declare function parseRelatedRepositories(raw: string | undefined): RelatedRepository[] | undefined;
-export declare function getTestbotPrompt(prTitle: string, prDescription: string, summaryOutputFile: string, repositoryPath: string, baseBranch?: string, maxRecommendations?: number, maxGenerate?: number, _maxCritical?: number, // Reserved — accepted for API compat but not yet wired into prompt
-prNumber?: number, userPrompt?: string, services?: Service[], uiCredentials?: string, testsRepoDir?: string, relatedRepositories?: RelatedRepository[], primaryRepo?: string, planOnly?: boolean, language?: string): string;
+export declare function getTestbotPrompt(opts: TestbotPromptOptions): string;
 export declare function buildWorkspaceRecoveryPrefix(repositoryPath: string): string;
 export declare function registerTestbotPrompt(server: McpServer): void;

package/build/prompts/testbot/testbot-prompts.js

@@ -54,9 +54,10 @@ export function parseRelatedRepositories(raw) {
         return undefined;
     }
 }
-export function getTestbotPrompt(prTitle, prDescription, summaryOutputFile, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, maxGenerate = MAX_TESTS_TO_GENERATE, _maxCritical = MAX_CRITICAL_TESTS, // Reserved — accepted for API compat but not yet wired into prompt
-prNumber, userPrompt, services, uiCredentials, testsRepoDir, relatedRepositories, primaryRepo, planOnly = false, language) {
-    maxGenerate = Math.min(Math.max(maxGenerate, 0), maxRecommendations);
+export function getTestbotPrompt(opts) {
+    const { prTitle, prDescription, summaryOutputFile, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, prNumber, userPrompt, services, uiCredentials, testsRepoDir, relatedRepositories, primaryRepo, planOnly = false, language, } = opts;
+    // maxCritical is intentionally unused (reserved) — see TestbotPromptOptions.
+    const maxGenerate = Math.min(Math.max(opts.maxGenerate ?? MAX_TESTS_TO_GENERATE, 0), maxRecommendations);
     // TODO(SKYR-3636 follow-up): migrate Task 1 + Task 2 step bodies to PromptPlan
     // (src/prompts/test-recommendation/promptPlan.ts) so step numbers don't have
     // to be hand-maintained when steps are added or reordered.
@@ -552,7 +553,7 @@ ${CONTRACT_MODE_GUIDANCE}
 
     4. **After** the action: \`browser_blueprint\` again. The response shape depends on whether the action navigated:
        - **Same URL (modal/tab/in-place mutation):** \`{ isFullCapture: false, pageHash, previousPageHash, delta, possibleAssertions }\`. The \`delta\` field contains \`elementsAdded\`, \`elementsRemoved\`, \`textChanges\`, \`repeatingCountChanges\`. The \`possibleAssertions\` field is a mechanical translation of those entries into Playwright \`expect(...)\` candidates — see step 5. An empty delta (all arrays empty) is itself a meaningful signal: the action did not change observable DOM (e.g. a silent failure the test should catch).
-       - **Navigated to a new URL** (e.g. router transition, link click, programmatic \`browser_navigate\`): \`{ isFullCapture: true, pageHash, blueprint }\` — a fresh full capture of the new page. No \`possibleAssertions\` here (no delta to translate). Search the new blueprint for the elements your assertion will target.
+       - **Navigated to a new URL** (e.g. router transition, link click, programmatic \`browser_navigate\`): \`{ isFullCapture: true, pageHash, blueprint, possibleAssertions }\` — a fresh full capture of the new page. \`possibleAssertions\` is present here too, but short — there is no previous capture to compare against, so nothing in it tells you what the action changed. Search the new blueprint for the elements your assertion will target.
 
     5. **The second \`browser_blueprint\` response (the capture after the action) includes a \`possibleAssertions[]\` array — mechanical translations of delta entries into ready-to-use Playwright \`expect(...)\` candidates.** Each entry has \`{ code, rationale, tier }\`. Use tier to drive your assertion choices:
 
@@ -733,7 +734,25 @@ export function registerTestbotPrompt(server) {
         },
     }, async (args) => {
         const services = await readWorkspaceServices(args.repositoryPath);
-        let prompt = getTestbotPrompt(args.prTitle, args.prDescription, args.summaryOutputFile, args.repositoryPath, args.baseBranch, args.maxRecommendations, args.maxGenerate, args.maxCritical, args.prNumber, args.userPrompt, services.length ? services : undefined, args.uiCredentials, args.testsRepoDir, parseRelatedRepositories(args.relatedRepositories), args.primaryRepo, args.planOnly, args.language);
+        let prompt = getTestbotPrompt({
+            prTitle: args.prTitle,
+            prDescription: args.prDescription,
+            summaryOutputFile: args.summaryOutputFile,
+            repositoryPath: args.repositoryPath,
+            baseBranch: args.baseBranch,
+            maxRecommendations: args.maxRecommendations,
+            maxGenerate: args.maxGenerate,
+            maxCritical: args.maxCritical,
+            prNumber: args.prNumber,
+            userPrompt: args.userPrompt,
+            services: services.length ? services : undefined,
+            uiCredentials: args.uiCredentials,
+            testsRepoDir: args.testsRepoDir,
+            relatedRepositories: parseRelatedRepositories(args.relatedRepositories),
+            primaryRepo: args.primaryRepo,
+            planOnly: args.planOnly,
+            language: args.language,
+        });
         if (args.workspaceValidationFailed) {
             prompt = buildWorkspaceRecoveryPrefix(args.repositoryPath) + prompt;
         }

package/build/resources/testbotResource.js

@@ -26,10 +26,27 @@ export function registerTestbotResource(server) {
         const maxCrit = parseInt(uri.searchParams.get("maxCritical") || "", 10);
         const repositoryPath = param("repositoryPath", ".");
         const services = await readWorkspaceServices(repositoryPath);
-        const prompt = getTestbotPrompt(param("prTitle", ""), param("prDescription", ""), param("summaryOutputFile", ""), repositoryPath, uri.searchParams.get("baseBranch") || undefined, isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec, isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen, isNaN(maxCrit) ? MAX_CRITICAL_TESTS : maxCrit, isNaN(prNum) ? undefined : prNum, uri.searchParams.get("userPrompt") || undefined, services.length ? services : undefined, uri.searchParams.get("uiCredentials") || undefined, uri.searchParams.get("testsRepoDir") || undefined, parseRelatedRepositories(uri.searchParams.get("relatedRepositories") || undefined), uri.searchParams.get("primaryRepo") || undefined, 
-        // Plan-only eval lane (SKYR-3879): recommendation phase only, nothing
-        // generated or executed. Same accepted spellings as the prompt schema.
-        ["true", "1"].includes(uri.searchParams.get("planOnly") ?? ""), uri.searchParams.get("language") || undefined);
+        const prompt = getTestbotPrompt({
+            prTitle: param("prTitle", ""),
+            prDescription: param("prDescription", ""),
+            summaryOutputFile: param("summaryOutputFile", ""),
+            repositoryPath,
+            baseBranch: uri.searchParams.get("baseBranch") || undefined,
+            maxRecommendations: isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec,
+            maxGenerate: isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen,
+            maxCritical: isNaN(maxCrit) ? MAX_CRITICAL_TESTS : maxCrit,
+            prNumber: isNaN(prNum) ? undefined : prNum,
+            userPrompt: uri.searchParams.get("userPrompt") || undefined,
+            services: services.length ? services : undefined,
+            uiCredentials: uri.searchParams.get("uiCredentials") || undefined,
+            testsRepoDir: uri.searchParams.get("testsRepoDir") || undefined,
+            relatedRepositories: parseRelatedRepositories(uri.searchParams.get("relatedRepositories") || undefined),
+            primaryRepo: uri.searchParams.get("primaryRepo") || undefined,
+            // Plan-only eval lane (SKYR-3879): recommendation phase only, nothing
+            // generated or executed. Same accepted spellings as the prompt schema.
+            planOnly: ["true", "1"].includes(uri.searchParams.get("planOnly") ?? ""),
+            language: uri.searchParams.get("language") || undefined,
+        });
         AnalyticsService.pushMCPToolEvent("skyramp_testbot_prompt", undefined, {}).catch(() => { });
         // Return the original URI — clients may use it to re-fetch the resource,
         // and the caller already has these params. Credentials never appear in

package/build/services/TestExecutionService.d.ts

@@ -2,7 +2,7 @@ import { TestExecutionResult, BatchExecutionResult, TestExecutionOptions, Progre
 import { EXECUTOR_DOCKER_IMAGE } from "../utils/versions.js";
 export { EXECUTOR_DOCKER_IMAGE };
 export declare const PLAYWRIGHT_CONFIG_FILES: string[];
-export declare const EXCLUDED_MOUNT_ITEMS: string[];
+export declare const MOUNT_SCAN_SKIP_DIRS: string[];
 export declare const TEST_REPO_CONTAINER_SUBDIR = ".skyramp-test-repo";
 export declare const MOUNT_NULL_ITEMS: string[];
 /**
@@ -38,18 +38,23 @@ export declare function detectSessionFiles(testFilePath: string): string[];
  */
 export declare function findExcludedPaths(dir: string, excludedItems: string[]): string[];
 /**
- * Find every nested `node_modules` directory under `dir` — i.e. all except the
- * top-level `<dir>/node_modules` (which the workspace mount already excludes).
- * Never descends into a `node_modules`. Used to shadow repo-local node_modules
- * that ride into the executor inside a parent directory's wholesale bind-mount;
- * a leaked `@playwright/test` becomes a second physical copy and trips
- * Playwright's "Requiring @playwright/test second time" guard.
+ * Find every `node_modules` directory under `dir`, including the top-level
+ * `<dir>/node_modules`. Never descends into a `node_modules`. Used to shadow
+ * SHADOWED_NESTED_PACKAGES inside each one: a repo-local `@playwright/test`
+ * becomes a second physical copy and trips Playwright's "Requiring
+ * @playwright/test second time" guard.
+ *
+ * The top-level one is deliberately NOT special-cased (SKYR-4140). When
+ * `workspacePath` is itself an npm package root — the standard `tests/<suite>/`
+ * layout — its node_modules IS the only one, so skipping it left the shadow
+ * machinery with nothing to act on and no customer dependency resolvable.
+ *
  * Skips `.git` (nothing importable lives there) and does not follow symlinks —
  * by design (a symlinked nested node_modules either dangles in-container,
  * falling through to NODE_PATH's global copy, or its real-path target is
  * walked directly).
  */
-export declare function findNestedNodeModules(dir: string): string[];
+export declare function findNodeModulesDirs(dir: string): string[];
 export declare class TestExecutionService {
     private docker;
     private imageReady;

package/build/services/TestExecutionService.js

@@ -54,8 +54,11 @@ export const PLAYWRIGHT_CONFIG_FILES = [
     "playwright.config.js",
     "playwright.config.mjs",
 ];
-// Directories to skip mounting entirely (cannot bind-mount /dev/null to a directory)
-export const EXCLUDED_MOUNT_ITEMS = [
+// Directories the recursive shadow scans must never descend into. node_modules
+// IS mounted (see mountRepoTree) — but walking it would shadow every package's
+// own package.json with empty JSON via MOUNT_NULL_ITEMS, breaking resolution
+// for the whole tree.
+export const MOUNT_SCAN_SKIP_DIRS = [
     "node_modules",
 ];
 // Reserved container subdir under /home/user where a cross-repo test repository
@@ -354,7 +357,7 @@ export function detectSessionFiles(testFilePath) {
  */
 export function findExcludedPaths(dir, excludedItems) {
     const results = [];
-    const shouldSkipDir = (entry) => excludedItems.includes(entry.name) || EXCLUDED_MOUNT_ITEMS.includes(entry.name);
+    const shouldSkipDir = (entry) => excludedItems.includes(entry.name) || MOUNT_SCAN_SKIP_DIRS.includes(entry.name);
     for (const [entry, fullPath] of walkDir(dir, { shouldSkipDir })) {
         // Only shadow files — mounting /dev/null to a directory target causes Docker errors
         if (excludedItems.includes(entry.name)) {
@@ -364,18 +367,23 @@ export function findExcludedPaths(dir, excludedItems) {
     return results;
 }
 /**
- * Find every nested `node_modules` directory under `dir` — i.e. all except the
- * top-level `<dir>/node_modules` (which the workspace mount already excludes).
- * Never descends into a `node_modules`. Used to shadow repo-local node_modules
- * that ride into the executor inside a parent directory's wholesale bind-mount;
- * a leaked `@playwright/test` becomes a second physical copy and trips
- * Playwright's "Requiring @playwright/test second time" guard.
+ * Find every `node_modules` directory under `dir`, including the top-level
+ * `<dir>/node_modules`. Never descends into a `node_modules`. Used to shadow
+ * SHADOWED_NESTED_PACKAGES inside each one: a repo-local `@playwright/test`
+ * becomes a second physical copy and trips Playwright's "Requiring
+ * @playwright/test second time" guard.
+ *
+ * The top-level one is deliberately NOT special-cased (SKYR-4140). When
+ * `workspacePath` is itself an npm package root — the standard `tests/<suite>/`
+ * layout — its node_modules IS the only one, so skipping it left the shadow
+ * machinery with nothing to act on and no customer dependency resolvable.
+ *
  * Skips `.git` (nothing importable lives there) and does not follow symlinks —
  * by design (a symlinked nested node_modules either dangles in-container,
  * falling through to NODE_PATH's global copy, or its real-path target is
  * walked directly).
  */
-export function findNestedNodeModules(dir) {
+export function findNodeModulesDirs(dir) {
     const results = [];
     const walk = (current) => {
         let entries;
@@ -392,8 +400,7 @@ export function findNestedNodeModules(dir) {
                 continue;
             const full = path.join(current, entry.name);
             if (entry.name === "node_modules") {
-                if (current !== dir)
-                    results.push(full); // skip the top-level node_modules
+                results.push(full);
                 continue; // never descend into a node_modules
             }
             walk(full);
@@ -593,17 +600,16 @@ export class TestExecutionService {
             hostConfig.Mounts.push(mount);
         };
         // Mount one repo tree (the workspace, or a cross-repo test repository) into
-        // the container, skipping EXCLUDED_MOUNT_ITEMS completely.
+        // the container.
         //
         // Each top-level entry is bind-mounted at the canonical container path and —
         // when mirrorToHost is set — at its host-absolute path too. The dual mount
         // lets the test resolve any absolute reference the codegen happens to embed
         // (storageState, fixture paths, snapshots) — including the host workspace
         // path that Playwright's TypeScript loader sometimes produces from
-        // `__dirname` — without needing source-code detection. EXCLUDED_MOUNT_ITEMS
-        // (node_modules) stays excluded at both targets; MOUNT_NULL_ITEMS shadows
-        // (package.json → empty JSON, etc.), nested-package shadows, and
-        // PLAYWRIGHT_CONFIG_FILES shadows (minimal config) are applied at both
+        // `__dirname` — without needing source-code detection. MOUNT_NULL_ITEMS
+        // shadows (package.json → empty JSON, etc.), node_modules package shadows,
+        // and PLAYWRIGHT_CONFIG_FILES shadows (minimal config) are applied at both
         // targets too so the protections survive regardless of which path the test
         // resolves to.
         //
@@ -611,7 +617,7 @@ export class TestExecutionService {
         // later mounts over earlier ones, so the top-level entry mounts must be
         // pushed BEFORE the shadow mounts that override paths inside them.
         //
-        // The three recursive scans (findExcludedPaths × 2 + findNestedNodeModules)
+        // The three recursive scans (findExcludedPaths × 2 + findNodeModulesDirs)
         // are deliberately kept as separate walks rather than fused into one pass:
         // each skips node_modules/.git so the cost is small, and separate walks keep
         // each shadow category's semantics independently testable.
@@ -623,11 +629,13 @@ export class TestExecutionService {
             // otherwise the entry mount would win the dedup race and the repo's own
             // config (which may import dotenv, or simply isn't the minimal/generated
             // one) would leak into the container.
+            //
+            // node_modules is NOT filtered out (SKYR-4140): it carries the customer's
+            // test-support deps, and the per-package shadows below neutralise the only
+            // copies that must not load from the repo.
             const entriesToMount = fs
                 .readdirSync(hostRoot)
-                .filter((file) => !EXCLUDED_MOUNT_ITEMS.includes(file) &&
-                !MOUNT_NULL_ITEMS.includes(file) &&
-                !PLAYWRIGHT_CONFIG_FILES.includes(file));
+                .filter((file) => !MOUNT_NULL_ITEMS.includes(file) && !PLAYWRIGHT_CONFIG_FILES.includes(file));
             for (const file of entriesToMount) {
                 const source = path.join(hostRoot, file);
                 pushMount({ Type: "bind", Target: path.join(containerRoot, file), Source: source });
@@ -644,10 +652,9 @@ export class TestExecutionService {
                     pushMount({ Type: "bind", Source: source, Target: absolutePath });
                 }
             }
-            // Shadow SHADOWED_NESTED_PACKAGES inside every nested node_modules leaked in
-            // via a parent-directory bind-mount (see findNestedNodeModules) — the
-            // top-level node_modules is already excluded above via EXCLUDED_MOUNT_ITEMS.
-            for (const nested of findNestedNodeModules(hostRoot)) {
+            // Shadow SHADOWED_NESTED_PACKAGES inside every mounted node_modules — the
+            // repo's own top-level one included (see findNodeModulesDirs).
+            for (const nested of findNodeModulesDirs(hostRoot)) {
                 for (const pkg of SHADOWED_NESTED_PACKAGES) {
                     const pkgPath = path.join(nested, pkg);
                     if (!fs.existsSync(pkgPath))
@@ -711,6 +718,22 @@ export class TestExecutionService {
         if (crossRepoTestRoot) {
             mountRepoTree(crossRepoTestRoot, path.join(containerMountPath, TEST_REPO_CONTAINER_SUBDIR), true);
         }
+        // runner.sh invokes `npx playwright test`, and npx resolves binaries from
+        // <cwd>/node_modules/.bin before PATH — cwd is always containerMountPath. Now
+        // that node_modules is mounted (SKYR-4140), a repo-local .bin/playwright would
+        // run instead of the image's global CLI. The per-package shadows above do not
+        // cover it under a pnpm layout, where .bin/playwright symlinks into .pnpm/
+        // rather than into node_modules/playwright. Shadow this one .bin — the only
+        // one npx can reach — so binary resolution falls through to PATH as before.
+        // Pushed after mountRepoTree so it layers over the node_modules entry mount.
+        if (fs.existsSync(path.join(workspacePath, "node_modules", ".bin"))) {
+            pushMount({
+                Type: "bind",
+                Source: EMPTY_DIR_PATH,
+                Target: path.join(containerMountPath, "node_modules", ".bin"),
+                ReadOnly: true,
+            });
+        }
         // Mount video output directory for browser tests (writable)
         if (browserTest && videoHostDir) {
             pushMount({

package/build/services/containerEnv.js

@@ -44,6 +44,30 @@ export function buildContainerEnv(options, saveStoragePath, hostEnv = process.en
             env.push(`${key}=${shouldRewrite ? rewriteLocalhostForDocker(val) : val}`);
         }
     }
+    // Credentials that generated UI tests read from the environment instead of
+    // carrying as literals (SKYR-3862). Without this the container never sees
+    // them and every generated login fails its guard.
+    //
+    // Forwarded on presence, not truthiness: the generated guard deliberately
+    // distinguishes an unset variable (a misconfiguration, fails fast) from one
+    // set to "" (valid on forms that accept a blank password). A truthy check —
+    // as used for the URL vars above — would drop the empty case and collapse it
+    // into the failure case.
+    //
+    // TODO(SKYR-4110): only ONE credential pair is forwarded, because testbot
+    // exports only the first credential from its `uiCredentials` input. That input
+    // was designed to carry several, so the agent can pick per test case by
+    // authorization role — so a multi-role suite can get a credential its test did
+    // not expect, surfacing as a false 403. The fix is a keyed form
+    // (SKYRAMP_UI_PASSWORD_<KEY>), which needs no new forwarding logic here: the
+    // loop above already forwards SKYRAMP_TEST_SERVICE_URL_* by prefix, so the
+    // same approach applies. Keep the presence-not-truthiness rule when it lands.
+    for (const key of ["SKYRAMP_UI_USERNAME", "SKYRAMP_UI_PASSWORD"]) {
+        const val = hostEnv[key];
+        if (val !== undefined) {
+            env.push(`${key}=${val}`);
+        }
+    }
     if (hostEnv.SKYRAMP_DEBUG) {
         env.push(`SKYRAMP_DEBUG=${hostEnv.SKYRAMP_DEBUG}`);
     }

package/build/tools/queryProxyMocksTool.js

@@ -275,7 +275,6 @@ function startPortForward(kubeconfig, namespace, target, remotePort) {
 async function queryProtocolSamples(baseUrl, protocol, pageSize, destination) {
     const collected = [];
     let offset = 0;
-    // eslint-disable-next-line no-constant-condition
     while (true) {
         const params = new URLSearchParams({
             protocol,

package/build/tools/submitReportTool.js

@@ -591,9 +591,18 @@ export function registerSubmitReportTool(server) {
                         // without it, the cheapest compliant move is a token no-op edit to the
                         // mis-claimed file, which pollutes the delivered branch and leaves the report
                         // crediting the wrong file (observed in the Ghost rc.pom-3 tester run, D-04).
+                        // The two claim kinds have DIFFERENT remedies and must say so. newTestsCreated
+                        // is a tool input, so it can be corrected here. A testMaintenance row is built
+                        // from stateData.maintenanceVerdicts and cannot be — saying so stops the agent
+                        // permuting testMaintenanceDetails, which is what it did for 15 rounds in
+                        // SKYR-4129. Do NOT offer re-running skyramp_actions to restate the verdict:
+                        // this branch only fires when the edit is genuinely absent, so rewriting the
+                        // record to match that would be the tamper path, not the fix.
                         const changedList = changedFiles.slice(0, 20).map((f) => `  - ${f}`).join("\n");
                         errorResult = toolError(`${unbacked.length} report claim(s) are not backed by any change in the working tree — ` +
-                            `Testbot will not report file work that hasn't actually been made. If the work WAS done but in a different file, correct the claim's fileName/description to the file you actually edited (see the changed files below) — do NOT make a token edit to the claimed file just to satisfy this check. Otherwise make the edit, or remove the claim. Then resubmit.\n` +
+                            `Testbot will not report file work that hasn't actually been made. Do NOT make a token edit to the claimed file just to satisfy this check.\n` +
+                            `For a newTestsCreated claim: create the file, correct the claim's fileName to the file you actually created (see the changed files below), or remove the claim.\n` +
+                            `For a testMaintenance claim: make the edit on the named file. That row is derived from the maintenance triage, not from this tool's input, so it cannot be corrected by changing what you pass here.\n` +
                             `Unbacked claims:\n${unbacked.map((u) => `  - ${u}`).join("\n")}\n` +
                             `Files with actual working-tree changes:\n${changedList || "  (none)"}`);
                         return errorResult;

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

@@ -265,14 +265,20 @@ export function registerActionsTool(server) {
                     });
                     return;
                 }
-                // Resolve and validate pomFile with the same path-traversal guard as testFilePath.
+                // Resolve and validate pomFile with the same path-traversal guard as testFilePath,
+                // minus that guard's `=== repoRoot` allowance: the repo root is a directory, never
+                // a page object. Admitting it would make it the edit target, and every consumer
+                // that resolves it relative to repoRoot gets the empty string — which the report's
+                // working-tree check reads as "outside this checkout, exempt", waving through an
+                // UPDATE that changed nothing. Dropping it here means pomFile falls back to the
+                // spec (`pomFile ?? testFilePath`) for both the edit and the check.
                 let resolvedPomFile;
                 if (rec.pomFile) {
                     const rawPom = path.isAbsolute(rec.pomFile)
                         ? rec.pomFile
                         : path.resolve(repoRoot ?? "", rec.pomFile);
                     resolvedPomFile = path.resolve(rawPom);
-                    if (repoRoot && !resolvedPomFile.startsWith(repoRoot + path.sep) && resolvedPomFile !== repoRoot) {
+                    if (repoRoot && !resolvedPomFile.startsWith(repoRoot + path.sep)) {
                         logger.warning(`Skipping pomFile outside repo root: ${rec.pomFile}`);
                         resolvedPomFile = undefined;
                     }
@@ -315,6 +321,10 @@ export function registerActionsTool(server) {
                     ignoredTestFiles,
                     maintenanceVerdicts: recommendations.map((r) => ({
                         testFilePath: r.testFilePath,
+                        // Persisted because the edit lands here, not in testFilePath. Dropping it
+                        // left skyramp_submit_report unable to tell a POM-backed UPDATE from a
+                        // fabricated one, so it rejected real maintenance work (SKYR-4129).
+                        pomFile: r.pomFile,
                         action: r.action,
                         rationale: r.rationale,
                         testType: r.testType,

package/build/types/TestAnalysis.d.ts

@@ -34,12 +34,16 @@ export interface MaintenanceActionCore {
     testType: TestType;
     endpoint: string;
     rationale: string;
+    /** When selectors are abstracted into a page object, pomFile is the POM path to edit.
+     *  testFilePath remains the spec (for catalog lookup and report); pomFile is what gets
+     *  patched. Part of the core shape because the EXECUTED file (the spec, which carries the
+     *  execution records) and the EDITED file (the POM) are structurally different, and every
+     *  downstream stage that reasons about the edit needs both — notably the report-time
+     *  working-tree check, which otherwise calls a POM-backed UPDATE unbacked (SKYR-4129). */
+    pomFile?: string;
 }
 /** Normalized internal recommendation built from LLM-supplied args.recommendations. */
 export interface DriftRecommendation extends MaintenanceActionCore {
-    /** When selectors are abstracted into a page object, pomFile is the POM path to edit.
-     *  testFilePath remains the spec (for catalog lookup and report); pomFile is what gets patched. */
-    pomFile?: string;
     priority: RecommendationPriority;
     estimatedWork: EstimatedWork;
     updateInstructions: string;

package/build/types/TestbotPromptOptions.d.ts

@@ -0,0 +1,35 @@
+import type { Service } from "../workspace/workspace.js";
+/** One related repository to analyze as shared context in multi-repo mode. */
+export interface RelatedRepository {
+    repositoryPath: string;
+    baseBranch?: string;
+    /** `owner/repo` slug, resolved by the action from the checkout's git remote.
+     *  Used verbatim as the `repository` argument/attribution for this repo so the
+     *  agent never has to infer it. */
+    repo: string;
+}
+/**
+ * Options accepted by getTestbotPrompt (src/prompts/testbot/testbot-prompts.ts).
+ * Shared here — rather than declared inline in the prompt module — so testbot.git
+ * can import this exact type instead of hand-maintaining its own mirror.
+ */
+export interface TestbotPromptOptions {
+    prTitle: string;
+    prDescription: string;
+    summaryOutputFile: string;
+    repositoryPath: string;
+    baseBranch?: string;
+    maxRecommendations?: number;
+    maxGenerate?: number;
+    /** Reserved — accepted for API compat but not yet wired into the prompt. */
+    maxCritical?: number;
+    prNumber?: number;
+    userPrompt?: string;
+    services?: Service[];
+    uiCredentials?: string;
+    testsRepoDir?: string;
+    relatedRepositories?: RelatedRepository[];
+    primaryRepo?: string;
+    planOnly?: boolean;
+    language?: string;
+}

package/build/types/TestbotPromptOptions.js

@@ -0,0 +1 @@
+export {};

package/build/types/index.d.ts

@@ -4,3 +4,4 @@ export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } 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/utils/frontendSelectors.js

@@ -74,7 +74,6 @@ export function extractChangedSelectors(fileDiff) {
     // `data-testid="x"`, `data-testid={'x'}`, `data-testid={`x`}`. The closing delimiter
     // deliberately rejects interpolated template literals (`data-testid={`members-${id}`}`),
     // which would otherwise leak a partial prefix (`members-`) into the selector set.
-    // eslint-disable-next-line no-useless-escape
     const ATTR = /\bdata-(?:test-?id|test|cy|qa)\b\s*=\s*\{?\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/g;
     const GET_BY_TEST_ID = /getByTestId\(\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/g;
     const KEBAB = /[a-z][a-z0-9]*(?:-{1,2}[a-z0-9]+)+/g;