@skyramp/mcp 0.4.4-rc.2 → 0.5.0-rc.1

package/build/index.js

@@ -33,7 +33,6 @@ import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js
 import { registerBatchMockTool } from "./tools/generate-tests/batchMockGenerationTool.js";
 import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, registerRegisterTestPlanTool, registerResolveScreenTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
-import { registerSutSetupResource } from "./resources/sutSetupResource.js";
 import { registerTestbotResource } from "./resources/testbotResource.js";
 import { registerLocalDevPrompt } from "./prompts/local-dev/local-dev-prompts.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
@@ -74,7 +73,7 @@ else if (localDevEnabled) {
     oneClickInstructions = localDevInstructions;
 }
 // Global workspace-init nudge for bare MCP usage. Suppressed in testbot mode,
-// which runs its own INIT_WORKSPACE step (buildWorkspaceInitSection()) instead.
+// which initializes the workspace in its own steps instead.
 const workspaceInitInstructions = isTestbotEnabled() || oneClickEnabled || localDevEnabled
     ? ""
     : `
@@ -167,8 +166,6 @@ async function createServer({ era }) {
         prompts.push(registerTestbotPrompt);
         registerTestbotResource(server);
         logger.info("Testbot prompt enabled via SKYRAMP_FEATURE_TESTBOT");
-        registerSutSetupResource(server);
-        logger.info("Testbot SUT setup resource enabled via SKYRAMP_FEATURE_TESTBOT");
     }
     if (isLocalDevEnabled()) {
         prompts.push(registerLocalDevPrompt);

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.d.ts

@@ -1 +1,18 @@
 export declare const INIT_WORKSPACE_INSTRUCTIONS: string;
+/** A repository of the Target other than the workspace's own, scanned into the same workspace.yml. */
+export interface ScanRelatedRepository {
+    /** owner/repo, set verbatim as each of its services' `repository`. */
+    repository: string;
+    repositoryPath: string;
+}
+/**
+ * The scan instructions for one workspace. With related repositories, every
+ * repository is scanned into the one workspace.yml at `workspacePath`, each
+ * related repository's services carrying its `repository`. With a test
+ * repository, testDirectory is read from, and relative to, that checkout.
+ */
+export declare function buildInitWorkspaceInstructions(target: {
+    workspacePath: string;
+    relatedRepositories?: ScanRelatedRepository[];
+    testRepositoryPath?: string;
+}): string;

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.js

@@ -1,9 +1,10 @@
 import { getPersonaPrefix } from "../personas.js";
 import { AUTH_TYPES_PROMPT_LIST } from "../../utils/workspaceAuth.js";
+import { SUPPORTED_FRAMEWORKS } from "../../workspace/frameworks.js";
 export const INIT_WORKSPACE_INSTRUCTIONS = `${getPersonaPrefix()}Your task is to scan this repository, discover ALL services, and call the skyramp_init_workspace tool with the discovered services array and the scanToken.
 
 After scanning the workspace, before calling the skyramp_init_workspace tool, you MUST:
-1. Output a <thinking> block to justify the reasoning behind each field mapping for every discovered service. Follow the scanning sections first, then field definitions, then verification.
+1. For each discovered service, list where each field value came from: the file it was read from, or the documented inference or fallback rule below that produced it (for example the deterministic testDirectory fallback, or the authType fallback). Follow the scanning sections first, then field definitions, then verification.
 2. Then output a Discovery Summary with the exact services array you will pass to the tool:
 \`\`\`json
 [
@@ -13,7 +14,7 @@ After scanning the workspace, before calling the skyramp_init_workspace tool, yo
     "framework": "<framework>",
     "testDirectory": "<path>",
     "api": { "schemaPath": "<path-or-url>", "baseUrl": "<url>", "authType": "<type>", "authHeader": "<header>" },
-    "runtimeDetails": { "runtime": "<runtime>", "serverStartCommand": "<command>", "serverStopCommand": "<docker stop command>", "dockerNetwork": "<network>" }
+    "runtimeDetails": { "runtime": "<runtime>", "serverStartCommand": "<command>", "serverStopCommand": "<docker stop command>", "dockerNetwork": "<network>", "testSuites": [{ "framework": "<framework>", "testRunCommand": "<command>", "pathGlobs": ["<dir>/**"] }] }
   }
 ]
 \`\`\`
@@ -89,7 +90,7 @@ Create one service entry per deployable unit. You MUST include every backend/API
    - JUnit: Usually src/test/java. Check pom.xml or build.gradle for custom test source directories.
    If no framework-configured test directory is available, use the Skyramp deterministic fallback:
    - Single service: set testDirectory to tests/skyramp.
-   - Multiple services or monorepos: set testDirectory to tests/skyramp/<serviceDirName>, where <serviceDirName> is the service directory name with path separators and whitespace replaced by hyphens.
+   - Multiple services or monorepos: set testDirectory to tests/skyramp/<serviceDirName>, where <serviceDirName> is the service's directory relative to its repository root with path separators and whitespace replaced by hyphens, or the repository's name for a service at the root.
    Framework config takes precedence. Use the Skyramp deterministic fallback only when no framework-configured test directory is available.
    NEVER set testDirectory to \`.skyramp\`, to any path inside it, or to \`.\` or the repo root, whatever the framework config or existing test files say. \`.skyramp\` is the executor's own working area: it holds the run videos and executor artefacts. skyramp_init_workspace rejects all of these, and the generation tools refuse to write there.
 </basic_fields>
@@ -123,7 +124,7 @@ Create one service entry per deployable unit. You MUST include every backend/API
       - Laravel: auth:sanctum on API indicates bearer. middleware("auth") on web indicates cookie.
       - Rust/Axum: Authorization<Bearer> extraction indicates bearer.
    d. Query-parameter auth: Some APIs pass credentials as a URL query param rather than a header (such as ?key=<key>, ?api_key=<key>, or ?access_token=<token>). Signals include source code reading credentials from req.query.key, request.query_params["api_key"], or @RequestParam("token"), and API docs or README showing auth examples like /endpoint?key=<your-key>.
-   e. Fallback: For frontend or UI services, use none. For backend APIs with no header-based auth signals, use bearer.
+   e. Fallback: when none of the signals above applies, use none, for any service. An API that answers without credentials is unauthenticated; never assume bearer without a signal.
 4. api.authHeader: The exact HTTP header name carrying the credential.
    - For bearer, basic, oauth, or token: always "Authorization" (inferred automatically, so you may omit it).
    - For cookie or session: always "Cookie" (also inferred automatically).
@@ -146,12 +147,21 @@ Create one service entry per deployable unit. You MUST include every backend/API
    - For "k8s" runtime: Use a deploy command such as "kubectl apply -f deploy/", "helm install myrelease .", or "skaffold run". This is always derivable from the manifests or charts present in the repo.
    - For "local" runtime: Use an application command such as "uvicorn main:app", "npm run dev", or "java -jar app.jar". Derive from Makefile, package.json scripts, or README. If no start command is discoverable, omit this field entirely.
    NEVER mix runtime types with incompatible commands (for example, using "uvicorn" with runtime "docker" will cause errors). For "local" runtime, NEVER fabricate a command. Only use commands found in Makefile, package.json scripts, or README.
-3. runtimeDetails.serverStopCommand: Optional command to stop the service after test execution. ONLY set when runtime is "docker" and serverStartCommand starts persistent Docker infrastructure. For docker compose starts, prefer matching stop/down commands from the same compose file. Omit this field for "local" and "k8s" runtimes, or when teardown is unsafe or not discoverable.
+   When the SUT recipe (.skyramp/sut/setup.sh) is what brings a service up and no compose service in the repository runs it, set serverStartCommand to "bash .skyramp/sut/setup.sh" and serverStopCommand to "bash .skyramp/sut/teardown.sh". Never invent a container name or a hand-built docker build or docker run command.
+3. runtimeDetails.serverStopCommand: Optional command to stop the service after test execution. ONLY set when runtime is "docker" and serverStartCommand starts persistent Docker infrastructure, or to "bash .skyramp/sut/teardown.sh" when serverStartCommand runs the SUT recipe. For docker compose starts, prefer matching stop/down commands from the same compose file. Omit this field for "local" and "k8s" runtimes, or when teardown is unsafe or not discoverable.
 4. runtimeDetails.dockerNetwork: Docker network name. ONLY set when runtime is "docker". NEVER set for "local" or "k8s".
 5. runtimeDetails.k8sNamespace: Kubernetes namespace. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
 6. runtimeDetails.k8sContext: Kubernetes context. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
 </runtime_fields>
 
+### Existing test suites
+<test_suites>
+runtimeDetails.testSuites records the service's own existing tests, which later runs execute and maintain. They cannot find a suite missing from this list. Each distinct (runner, test directory) pair is one suite: a Mocha suite under packages/api/test/ and a Playwright suite under e2e/ are two. Find them in two places and record the union: every test-runner config in the test tree (playwright.config.*, cypress.config.*, vitest.config.*, pytest.ini, test projects, and so on), and every CI step that runs tests (npm test, pytest, go test, dotnet test, mvn test or verify, cypress run, and so on), including a separate integration-test step. Record each suite under the service it tests, even when there is only one, and every suite you run yourself. Omit testSuites only when the service has no existing tests. Each entry sets:
+1. framework: the suite's runner, one of ${SUPPORTED_FRAMEWORKS.join(", ")}. Leave it out when the runner is none of these; record the suite all the same.
+2. testRunCommand: the command that runs the suite, from the root of the repository the suite lives in, taken from its CI job or package scripts. A machine-readable reporter flag and the test file paths, relative to that root, are appended to the end of it, so it must accept appended arguments and must not cd into a subdirectory: point the runner at the suite instead, with the repository's own config file or a package filter (for example "npx playwright test --config e2e/playwright.config.ts" or "pnpm --filter @acme/api test").
+3. pathGlobs: the directories the suite owns, as globs relative to that same root (for example ["e2e/tests/**"]). Set it on every suite. Scope by directory, not by filename, and keep the suites' globs disjoint, so each test file belongs to exactly one suite.
+</test_suites>
+
 ### Verification
 <verification>
 Before calling skyramp_init_workspace, confirm all of the following:
@@ -168,11 +178,44 @@ Before calling skyramp_init_workspace, confirm all of the following:
 11. For "local" runtime: if no start command is discoverable from Makefile, package.json scripts, or README, omit serverStartCommand rather than guessing.
 12. dockerNetwork is set only when runtime is "docker".
 13. k8sNamespace and k8sContext are set only when runtime is "k8s".
-14. If force-recreating a workspace.yml due to a schema validation error, correct the schema error but keep any valid system-under-test setup (serviceName, baseUrl, auth config, runtime details) as it is.
+14. Every existing test suite, from the test tree and from CI, is recorded under runtimeDetails.testSuites with its testRunCommand and pathGlobs.
+15. If force-recreating a workspace.yml due to a schema validation error, correct the schema error but keep any valid system-under-test setup (serviceName, baseUrl, auth config, runtime details) as it is.
 </verification>
 
 Once verified, call skyramp_init_workspace with:
 - workspacePath: the repository root path
 - services: the array built above
 - scanToken: the token returned by the first call to skyramp_init_scan
-- force: defaults to false. Set to true only if the user explicitly asks to overwrite an existing .skyramp/workspace.yml, or if the existing file must be regenerated due to a validation failure such as a schema mismatch, unknown fields, or a parse error.`;
+- force: defaults to false. Set to true only if the user explicitly asks to overwrite an existing .skyramp/workspace.yml, or if the existing file must be regenerated due to a validation failure such as a schema mismatch, unknown fields, or a parse error.
+
+skyramp_init_workspace checks the services against these rules before writing anything. When it refuses, it lists each problem: fix every one and call it again with the full corrected services array and the same scanToken, which a refusal leaves valid.`;
+/**
+ * The scan instructions for one workspace. With related repositories, every
+ * repository is scanned into the one workspace.yml at `workspacePath`, each
+ * related repository's services carrying its `repository`. With a test
+ * repository, testDirectory is read from, and relative to, that checkout.
+ */
+export function buildInitWorkspaceInstructions(target) {
+    const related = target.relatedRepositories ?? [];
+    const deliveryRoot = target.testRepositoryPath ?? target.workspacePath;
+    const blocks = [];
+    if (related.length > 0) {
+        const count = related.length + 1;
+        blocks.push(`### Target repositories
+<target_repositories>
+This workspace covers ${count} repositories. Scan EACH one with every section above, as if it were the only repository (its monorepo packages, frontend packages and CI test steps included), and pass the services of all ${count} to ONE skyramp_init_workspace call:
+- ${target.workspacePath}: this workspace's own repository. Its services carry no repository field.
+${related.map((r) => `- ${r.repositoryPath}: set repository to "${r.repository}" on every service found here.`).join("\n")}
+For a related repository's service, write every path and command as it reads from that repository's root (schemaPath, compose files, testRunCommand, pathGlobs), except testDirectory: every testDirectory is relative to ${deliveryRoot}, where generated tests are delivered. When no framework config sets it, a related repository's service uses tests/skyramp/<repoName>-<serviceDirName>, so services of two repositories never share one by accident. Call skyramp_init_workspace with workspacePath "${target.workspacePath}" only. A related repository gets no workspace.yml of its own.
+</target_repositories>`);
+    }
+    if (target.testRepositoryPath) {
+        blocks.push(`### Test repository
+<test_repository>
+Generated tests are delivered into the test repository at ${target.testRepositoryPath}, not into the repository that holds the service. Read each service's testDirectory from the test repository's own framework config (Playwright testDir, pytest testpaths, the JUnit test source directory), relative to the test repository's root; the deterministic fallback applies there too. The test repository holds tests, not services: register no service for it. Record the suites it already has under the service each one tests, with testRunCommand and pathGlobs relative to the test repository's root.
+</test_repository>`);
+    }
+    return blocks.length
+        ? `${INIT_WORKSPACE_INSTRUCTIONS}\n\n${blocks.join("\n\n")}`
+        : INIT_WORKSPACE_INSTRUCTIONS;
+}

package/build/prompts/test-maintenance/driftAnalysisShared.js

@@ -57,7 +57,7 @@ ${opts.domainNotes}
 
 **If your rationale concludes the test is unaffected, assign IGNORE, not VERIFY.** Assign VERIFY only for a doubt that the code you read does not settle. A rule that forbids IGNORE still applies.
 
-**A stated requirement wins over the code.** Before you write a new value or refresh a screenshot in an existing test, compare it with what the pull request title, the description and any requirements file they name state. If the new value breaks a stated requirement, do not write it: keep that assertion on the requirement's value and make only the other edits. If no other edit remains, mark the test VERIFY. The test stays red; do not relax it. If the requirements file is unchanged and the description presents the new behaviour as intended, the file is out of date: update the test.
+**A stated requirement wins over the code.** Before you write a new value or refresh a screenshot in an existing test, compare it with what the pull request title, the description and any requirements file they name state. If the new value breaks a stated requirement, do not write it: keep that assertion on the requirement's value and make only the other edits. If no other edit remains, mark the test VERIFY. The test stays red; do not relax it. Authority runs requirements > PR description > code change: an unchanged requirements file that the description contradicts still wins — keep the assertion on the file's value and report the requirement conflict.
 
 **Pre-commit verification — confirm before finalizing UPDATE/REGENERATE/DELETE:**
 1. You can quote a specific diff line${opts.blueprintSuffix} this test observes that triggered the action.

package/build/tools/workspace/initScanWorkspaceTool.d.ts

@@ -1,4 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/server";
-export declare function issueScanToken(): string;
+import { type ScanRelatedRepository } from "../../prompts/initialize-workspace/initializeWorkspacePrompt.js";
+/** What a scan token was issued for: when it expires, and the related
+ *  repositories its scan named, which skyramp_init_workspace verifies the
+ *  services against. */
+export interface ScanGrant {
+    expiry: number;
+    relatedRepositories: ScanRelatedRepository[];
+}
+export declare function issueScanToken(relatedRepositories?: ScanRelatedRepository[]): string;
+/** The grant of a valid, unexpired token, without consuming it. */
+export declare function scanTokenGrant(token: string): ScanGrant | undefined;
 export declare function validateAndConsumeScanToken(token: string): boolean;
 export declare function registerInitScanWorkspaceTool(server: McpServer): void;

package/build/tools/workspace/initScanWorkspaceTool.js

@@ -1,24 +1,33 @@
 import { z } from "zod";
 import { randomUUID } from "crypto";
+import fs from "fs";
 import { WorkspaceConfigManager } from "../../workspace/workspace.js";
+import { resolveRealPath, tryRepositorySlug, } from "../../utils/repositorySlug.js";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
-import { INIT_WORKSPACE_INSTRUCTIONS } from "../../prompts/initialize-workspace/initializeWorkspacePrompt.js";
+import { buildInitWorkspaceInstructions, } from "../../prompts/initialize-workspace/initializeWorkspacePrompt.js";
 const TOOL_NAME = "skyramp_init_scan";
-// Token store: token -> expiry timestamp (ms)
 const scanTokens = new Map();
 const TOKEN_TTL_MS = 10 * 60 * 1000; // 10 minutes
-export function issueScanToken() {
+export function issueScanToken(relatedRepositories = []) {
     const token = randomUUID();
-    scanTokens.set(token, Date.now() + TOKEN_TTL_MS);
+    scanTokens.set(token, {
+        expiry: Date.now() + TOKEN_TTL_MS,
+        relatedRepositories,
+    });
     return token;
 }
+/** The grant of a valid, unexpired token, without consuming it. */
+export function scanTokenGrant(token) {
+    const grant = scanTokens.get(token);
+    return grant && Date.now() < grant.expiry ? grant : undefined;
+}
 export function validateAndConsumeScanToken(token) {
-    const expiry = scanTokens.get(token);
-    if (!expiry)
+    const grant = scanTokens.get(token);
+    if (!grant)
         return false;
     scanTokens.delete(token);
-    return Date.now() < expiry;
+    return Date.now() < grant.expiry;
 }
 const initScanWorkspaceSchema = z.object({
     workspacePath: z.string().describe("Path to the workspace/repository root"),
@@ -26,12 +35,66 @@ const initScanWorkspaceSchema = z.object({
         .boolean()
         .default(false)
         .describe("Set to true to force a re-scan even if .skyramp/workspace.yml already exists. Default is false."),
+    relatedRepositories: z
+        .array(z.object({
+        repositoryPath: z
+            .string()
+            .describe("Path to the related repository's checkout"),
+        repository: z
+            .string()
+            .optional()
+            .describe("The related repository's owner/repo. Defaults to the one its checkout's origin remote names."),
+    }))
+        .optional()
+        .describe("The other repositories of a multi-repository Target. Each is scanned into the one workspace.yml at workspacePath, its services carrying its owner/repo as `repository`; none gets a workspace.yml of its own. Omit for a single repository."),
+    testRepositoryPath: z
+        .string()
+        .optional()
+        .describe("Path to the separate test repository generated tests are delivered into, when there is one. Each service's testDirectory is then read from, and relative to, that checkout."),
 });
+const OWNER_REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Each related repository with its owner/repo, or the first problem with them:
+ * a checkout that is not a directory, is the workspace itself, or names no
+ * owner/repo, and a repository listed twice. Paths compare with symlinks
+ * resolved, and owner/repo case-insensitively, as GitHub does.
+ */
+async function resolveRelatedRepositories(workspacePath, entries) {
+    const repos = [];
+    const workspaceReal = await resolveRealPath(workspacePath);
+    for (const entry of entries) {
+        const at = entry.repositoryPath;
+        if (!isDirectory(at))
+            return { error: `relatedRepositories: ${at} is not a directory` };
+        if ((await resolveRealPath(at)) === workspaceReal)
+            return {
+                error: `relatedRepositories: ${at} is workspacePath itself; list only the other repositories`,
+            };
+        const repository = entry.repository?.trim() || (await tryRepositorySlug(at));
+        if (!repository || !OWNER_REPO.test(repository))
+            return {
+                error: `relatedRepositories: no owner/repo for ${at}${repository ? ` ("${repository}" is not owner/repo)` : " (its checkout has no origin remote)"}; pass its repository`,
+            };
+        if (repos.some((r) => r.repository.toLowerCase() === repository.toLowerCase()))
+            return { error: `relatedRepositories: ${repository} is listed twice` };
+        repos.push({ repository, repositoryPath: at });
+    }
+    return { repos };
+}
 export function registerInitScanWorkspaceTool(server) {
     server.registerTool(TOOL_NAME, {
         description: "Call this FIRST, before any other Skyramp tool (test generation, execution, analysis), whenever workspacePath is a git repository and .skyramp/workspace.yml does not exist at its root. " +
             "PREREQUISITE for skyramp_init_workspace. " +
             "Scans a repository and returns instructions for discovering all services, along with a scanToken. " +
+            "For a Target spanning several repositories, call it ONCE with the others in relatedRepositories, so all their services go into one workspace.yml. " +
             "Follow the instructions to build the services array, then pass both to skyramp_init_workspace to create the workspace config.",
         inputSchema: initScanWorkspaceSchema,
     }, async (params) => {
@@ -39,6 +102,8 @@ export function registerInitScanWorkspaceTool(server) {
         const recordParams = {
             workspacePath: params.workspacePath,
             force: String(params.force || false),
+            relatedRepositories: String(params.relatedRepositories?.length ?? 0),
+            testRepository: String(Boolean(params.testRepositoryPath)),
         };
         try {
             const manager = new WorkspaceConfigManager(params.workspacePath);
@@ -53,12 +118,38 @@ export function registerInitScanWorkspaceTool(server) {
                     isError: false,
                 };
             }
-            const token = issueScanToken();
+            const related = await resolveRelatedRepositories(params.workspacePath, params.relatedRepositories ?? []);
+            if ("error" in related) {
+                errorResult = {
+                    content: [{ type: "text", text: related.error }],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            if (params.testRepositoryPath &&
+                !isDirectory(params.testRepositoryPath)) {
+                errorResult = {
+                    content: [
+                        {
+                            type: "text",
+                            text: `testRepositoryPath: ${params.testRepositoryPath} is not a directory`,
+                        },
+                    ],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            const token = issueScanToken(related.repos);
+            const instructions = buildInitWorkspaceInstructions({
+                workspacePath: params.workspacePath,
+                relatedRepositories: related.repos,
+                testRepositoryPath: params.testRepositoryPath,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `SCAN TOKEN: ${token}\n\nSave this token — you MUST pass it as scanToken when calling skyramp_init_workspace.\n\n${INIT_WORKSPACE_INSTRUCTIONS}`,
+                        text: `SCAN TOKEN: ${token}\n\nSave this token — you MUST pass it as scanToken when calling skyramp_init_workspace.\n\n${instructions}`,
                     },
                 ],
                 isError: false,

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -7,7 +7,8 @@ import yaml from "js-yaml";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { SKYRAMP_IMAGE_VERSION } from "../../utils/versions.js";
-import { validateAndConsumeScanToken } from "./initScanWorkspaceTool.js";
+import { scanTokenGrant, validateAndConsumeScanToken, } from "./initScanWorkspaceTool.js";
+import { verifyWorkspaceServices } from "../../workspace/workspaceVerifier.js";
 import { upsertServicesByRepo } from "./serviceUpsert.js";
 import { isInsideDir } from "../../utils/gitStaging.js";
 import { EXECUTOR_VIDEOS_DIR, EXECUTOR_WORK_DIR, isInsideExecutorWorkDir, } from "../../utils/executorWorkDir.js";
@@ -110,7 +111,7 @@ export function registerInitializeWorkspaceTool(server) {
             "1. Fresh init: PREREQUISITE: Call skyramp_init_scan first to get a scanToken and discover services. " +
             "Then call this tool to write .skyramp/workspace.yml with the discovered services and scanToken. " +
             "2. Edit existing workspace.yml: omit scanToken, set force: true, and pass the FULL updated services array (overwrite, not merge — fields not in the array are dropped). " +
-            "The services schema is strict: any field not in the schema (e.g. inventing `serverStopCommand` on `runtimeDetails`) fails validation and the call is rejected.",
+            "The services schema is strict: any field not in the schema (e.g. inventing `healthUrl` on `runtimeDetails`) fails validation and the call is rejected.",
         inputSchema: initializeWorkspaceSchema,
         _meta: {
             keywords: [
@@ -182,11 +183,46 @@ export function registerInitializeWorkspaceTool(server) {
                 if (badMerged)
                     return badTestDirectoryResult(badMerged);
             }
+            // The verifier, before the token is spent: a refusal asks for a
+            // corrected retry, which must be able to reuse the same token. Only the
+            // incoming services: a merge must not be blocked by an older entry.
+            const grant = params.scanToken
+                ? scanTokenGrant(params.scanToken)
+                : undefined;
+            const issues = verifyWorkspaceServices(params.services, {
+                workspacePath,
+                relatedRepositories: grant?.relatedRepositories,
+            });
+            if (issues.length > 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${manager.getConfigPath()} was not written: ${issues.length} problem(s) with the services.\n${issues.map((i) => `- ${i}`).join("\n")}\nFix each one and call skyramp_init_workspace again with the full corrected services array${grant ? " and the same scanToken, which is still valid" : ""}.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
             // scanToken is required for fresh init; for edits (force:true on an
             // existing workspace.yml) the caller supplies the full services array
-            // directly and we skip the token check.
+            // directly and no token is needed. A token passed with an edit is still
+            // validated and spent, so a successful write never leaves it reusable.
             const isEdit = alreadyExists && params.force;
-            if (!isEdit) {
+            if (isEdit && params.scanToken) {
+                if (!validateAndConsumeScanToken(params.scanToken)) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Invalid or expired scanToken. An edit of an existing workspace.yml needs none: call again with force: true and no scanToken.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            else if (!isEdit) {
                 if (!params.scanToken) {
                     return {
                         content: [

package/build/workspace/workspace.d.ts

@@ -273,9 +273,17 @@ export declare class WorkspaceConfigManager {
     /**
      * Initialize workspace — creates .skyramp/workspace.yml with repo info.
      * Auto-detects repoName and repoUrl from git when not provided.
-     * Produces an empty services array and default metadata timestamps.
+     * Produces an empty services array and default metadata timestamps. Over an
+     * existing file it keeps that file's createdAt: the workspace was created
+     * then, however often it is rewritten.
      */
     initialize(workspaceInfo?: WorkspaceSection): Promise<WorkspaceConfig>;
+    /**
+     * The existing file's metadata.createdAt, read leniently: a rewrite is often
+     * the repair of a file that no longer validates, and its createdAt still
+     * stands. Undefined when there is no file or it records none.
+     */
+    private existingCreatedAt;
     /**
      * Update the metadata section of an existing workspace config.
      * Only the provided fields are merged; metadata.updatedAt is refreshed

package/build/workspace/workspace.js

@@ -107,8 +107,7 @@ export const serviceSchema = z
         k8sContext: z.string().optional(),
         // External-suite test contract (SKYR-4002). A service hosts one or more
         // runnable suites — record each under testSuites, even a single suite
-        // (there is no flat single-suite form). Written by the SUT adapt_workflow
-        // bootstrap (skyramp_testbot_sut). Each suite carries its own framework
+        // (there is no flat single-suite form). Each suite carries its own framework
         // (falling back to the service's), testRunCommand, and pathGlobs
         // — the repo-relative paths that suite owns, which the agent reads to find
         // the suite of a test file. One service can host multiple frameworks.
@@ -346,13 +345,18 @@ export class WorkspaceConfigManager {
     /**
      * Initialize workspace — creates .skyramp/workspace.yml with repo info.
      * Auto-detects repoName and repoUrl from git when not provided.
-     * Produces an empty services array and default metadata timestamps.
+     * Produces an empty services array and default metadata timestamps. Over an
+     * existing file it keeps that file's createdAt: the workspace was created
+     * then, however often it is rewritten.
      */
     async initialize(workspaceInfo = {}) {
         await fs.mkdir(this.skyrampDir, { recursive: true });
         // Auto-detect repo info from workspace root when not explicitly provided
         const detected = await detectRepoInfo(this.workspacePath);
         const config = createDefaultConfig();
+        const createdAt = await this.existingCreatedAt();
+        if (createdAt && config.metadata)
+            config.metadata.createdAt = createdAt;
         config.workspace = {
             repoName: workspaceInfo.repoName || detected.repoName || undefined,
             repoUrl: workspaceInfo.repoUrl || detected.repoUrl || undefined,
@@ -361,6 +365,23 @@ export class WorkspaceConfigManager {
         await writeWorkspaceFile(this.configPath, validated);
         return validated;
     }
+    /**
+     * The existing file's metadata.createdAt, read leniently: a rewrite is often
+     * the repair of a file that no longer validates, and its createdAt still
+     * stands. Undefined when there is no file or it records none.
+     */
+    async existingCreatedAt() {
+        try {
+            const doc = yaml.load(await fs.readFile(this.configPath, "utf8"));
+            const createdAt = doc?.metadata?.createdAt;
+            return typeof createdAt === "string" && createdAt.trim()
+                ? createdAt
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * Update the metadata section of an existing workspace config.
      * Only the provided fields are merged; metadata.updatedAt is refreshed

package/build/workspace/workspaceVerifier.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Verifies the services written to .skyramp/workspace.yml against the rules
+ * the scan instructions state and that a file can show deterministically:
+ * service identity, runtime and command consistency, API addressing and auth,
+ * the compose files and services a start command names, and each recorded
+ * test suite's routing. skyramp_init_workspace refuses a write that breaks one,
+ * and the SUT eval runs it on the file a run produced.
+ *
+ * It reports only what is certainly wrong. A rule it cannot decide from the
+ * files (an interpolated compose path, a command that changes directory, a
+ * compose file it cannot parse) is skipped, never guessed.
+ */
+import type { Service } from "./workspace.js";
+/** A repository of the Target other than the workspace's own. */
+export interface VerifierRepository {
+    repository: string;
+    repositoryPath: string;
+}
+export interface WorkspaceVerifierOptions {
+    /** The workspace's own repository root, where a service with no `repository` lives. */
+    workspacePath: string;
+    /** The other repositories the scan named. When given, every service's
+     *  `repository` is one of them, and its compose commands are checked in its
+     *  checkout. */
+    relatedRepositories?: VerifierRepository[];
+}
+/** Every problem with `services`, one line each, naming the service and the fix. */
+export declare function verifyWorkspaceServices(services: readonly Service[], opts: WorkspaceVerifierOptions): string[];