@skyramp/mcp 0.4.3 → 0.4.4-rc.2

package/build/types/RepositoryAnalysis.js

@@ -20,7 +20,7 @@ export var ScenarioSource;
     ScenarioSource["AgentEnriched"] = "agent-enriched";
 })(ScenarioSource || (ScenarioSource = {}));
 // ── Zod schemas ──
-export const analysisScopeSchema = z.nativeEnum(AnalysisScope);
+export const analysisScopeSchema = z.enum(AnalysisScope);
 export const paramInfoSchema = z.object({
     name: z.string(),
     type: z.string(),
@@ -40,15 +40,15 @@ export const endpointInteractionSchema = z.object({
     type: z.enum(["success", "error", "edge-case"]),
     request: z.object({
         contentType: z.string().optional(),
-        body: z.record(z.any()).optional(),
-        headers: z.record(z.string()).optional(),
-        queryParams: z.record(z.any()).optional(),
+        body: z.record(z.string(), z.any()).optional(),
+        headers: z.record(z.string(), z.string()).optional(),
+        queryParams: z.record(z.string(), z.any()).optional(),
     }),
     response: z.object({
         statusCode: z.number(),
         description: z.string(),
-        body: z.record(z.any()).optional(),
-        headers: z.record(z.string()).optional(),
+        body: z.record(z.string(), z.any()).optional(),
+        headers: z.record(z.string(), z.string()).optional(),
         cookies: z.array(cookieInfoSchema).optional(),
     }),
 });
@@ -83,9 +83,11 @@ export const scenarioStepSchema = z.object({
     path: z.string(),
     description: z.string(),
     interactionType: z.enum(["success", "error", "edge-case"]),
-    requestBody: z.record(z.any()).optional(),
-    queryParams: z.record(z.any()).optional(),
-    responseBody: z.union([z.record(z.any()), z.array(z.any())]).optional(),
+    requestBody: z.record(z.string(), z.any()).optional(),
+    queryParams: z.record(z.string(), z.any()).optional(),
+    responseBody: z
+        .union([z.record(z.string(), z.any()), z.array(z.any())])
+        .optional(),
     expectedStatusCode: z.number(),
     expectedResponseFields: z.array(z.string()).optional(),
     chainsFrom: z
@@ -192,7 +194,7 @@ export const repositoryAnalysisSchema = z.object({
             contract: z.number(),
             smoke: z.number(),
         }),
-        testLocations: z.record(z.string()),
+        testLocations: z.record(z.string(), z.string()),
         hasCoverageReports: z.boolean(),
         estimatedCoverage: z.number().optional(),
         relevantExternalTestPaths: z.array(z.string()).optional(),

package/build/types/StepMethod.d.ts

@@ -37,4 +37,27 @@ export declare const STEP_METHOD_DESCRIPTION: string;
  * The field itself: normalised first, then checked, so a rejection is about the
  * verb and never about its capitalisation.
  */
-export declare const stepMethodSchema: z.ZodEffects<z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE", "CONNECT", "assert", "click", "drag", "drag-hold", "hover", "inspect", "navigate", "press", "release", "tap", "type", "wait", "OPERATION"]>, "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "type" | "TRACE" | "CONNECT" | "assert" | "click" | "drag" | "drag-hold" | "hover" | "inspect" | "navigate" | "press" | "release" | "tap" | "wait" | "OPERATION", unknown>;
+export declare const stepMethodSchema: z.ZodPreprocess<z.ZodEnum<{
+    GET: "GET";
+    POST: "POST";
+    PUT: "PUT";
+    DELETE: "DELETE";
+    PATCH: "PATCH";
+    HEAD: "HEAD";
+    OPTIONS: "OPTIONS";
+    type: "type";
+    TRACE: "TRACE";
+    CONNECT: "CONNECT";
+    assert: "assert";
+    click: "click";
+    drag: "drag";
+    "drag-hold": "drag-hold";
+    hover: "hover";
+    inspect: "inspect";
+    navigate: "navigate";
+    press: "press";
+    release: "release";
+    tap: "tap";
+    wait: "wait";
+    OPERATION: "OPERATION";
+}>, unknown>;

package/build/types/StepMethod.js

@@ -87,5 +87,5 @@ export const STEP_METHOD_DESCRIPTION = "What this step does to the system: an HT
 export const stepMethodSchema = z.preprocess((value) => typeof value === "string"
     ? (normalizeStepMethod(value) ?? value.trim())
     : value, z.enum(STEP_METHODS, {
-    errorMap: () => ({ message: `method ${STEP_METHOD_HELP}` }),
+    error: () => `method ${STEP_METHOD_HELP}`,
 }));

package/build/types/TestTypes.d.ts

@@ -51,28 +51,22 @@ export declare enum RuntimeEnvironment {
     DOCKER = "docker",
     KUBERNETES = "k8s"
 }
-export declare const runtimeEnvironmentSchema: z.ZodNativeEnum<typeof RuntimeEnvironment>;
-export declare const runtimeEnvironmentInputSchema: z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>;
+export declare const runtimeEnvironmentSchema: z.ZodEnum<typeof RuntimeEnvironment>;
+export declare const runtimeEnvironmentInputSchema: z.ZodPreprocess<z.ZodEnum<typeof RuntimeEnvironment>, unknown>;
 export declare function normalizeRuntimeEnvironment(value: RuntimeEnvironment | "kubernetes"): RuntimeEnvironment;
 export interface TestConfig {
     testType: TestType;
     toolName: string;
     description: string;
-    additionalFields?: Record<string, z.ZodSchema>;
+    additionalFields?: Record<string, z.ZodType>;
 }
 export declare const languageSchema: z.ZodObject<{
-    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    language: z.ZodEnum<typeof ProgrammingLanguage>;
     framework: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    language: ProgrammingLanguage;
-    framework: string;
-}, {
-    language: ProgrammingLanguage;
-    framework: string;
-}>;
+}, z.core.$strip>;
 export declare const baseSchema: z.ZodObject<{
     deployDashboard: z.ZodDefault<z.ZodBoolean>;
-    runtime: z.ZodDefault<z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>>;
+    runtime: z.ZodDefault<z.ZodPreprocess<z.ZodEnum<typeof RuntimeEnvironment>, unknown>>;
     dockerNetwork: z.ZodDefault<z.ZodString>;
     dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
     k8sNamespace: z.ZodDefault<z.ZodString>;
@@ -81,78 +75,35 @@ export declare const baseSchema: z.ZodObject<{
     authHeader: z.ZodDefault<z.ZodString>;
     authScheme: z.ZodDefault<z.ZodString>;
     insecure: z.ZodDefault<z.ZodBoolean>;
-    output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    output: z.ZodOptional<z.ZodString>;
     outputDir: z.ZodString;
     force: z.ZodDefault<z.ZodBoolean>;
     mockPort: z.ZodDefault<z.ZodNumber>;
     optionalFields: z.ZodDefault<z.ZodBoolean>;
     prompt: z.ZodString;
-    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    language: z.ZodEnum<typeof ProgrammingLanguage>;
     framework: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    language: ProgrammingLanguage;
-    framework: string;
-    deployDashboard: boolean;
-    runtime: RuntimeEnvironment;
-    dockerNetwork: string;
-    dockerWorkerPort: number;
-    k8sNamespace: string;
-    k8sConfig: string;
-    k8sContext: string;
-    authHeader: string;
-    authScheme: string;
-    insecure: boolean;
-    outputDir: string;
-    force: boolean;
-    mockPort: number;
-    optionalFields: boolean;
-    prompt: string;
-    output?: string | undefined;
-}, {
-    language: ProgrammingLanguage;
-    framework: string;
-    outputDir: string;
-    prompt: string;
-    deployDashboard?: boolean | undefined;
-    runtime?: unknown;
-    dockerNetwork?: string | undefined;
-    dockerWorkerPort?: number | undefined;
-    k8sNamespace?: string | undefined;
-    k8sConfig?: string | undefined;
-    k8sContext?: string | undefined;
-    authHeader?: string | undefined;
-    authScheme?: string | undefined;
-    insecure?: boolean | undefined;
-    output?: string | undefined;
-    force?: boolean | undefined;
-    mockPort?: number | undefined;
-    optionalFields?: boolean | undefined;
-}>;
+}, z.core.$strip>;
 export declare const basePlaywrightSchema: z.ZodObject<{
     playwrightInput: z.ZodString;
     playwrightStoragePath: z.ZodOptional<z.ZodString>;
     playwrightSaveStoragePath: z.ZodOptional<z.ZodString>;
-    playwrightViewportSize: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["", "hd", "full-hd", "2k"]>, z.ZodString]>>;
-    browser: z.ZodDefault<z.ZodEnum<["chromium", "firefox", "webkit"]>>;
+    playwrightViewportSize: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+        "": "";
+        hd: "hd";
+        "full-hd": "full-hd";
+        "2k": "2k";
+    }>, z.ZodString]>>;
+    browser: z.ZodDefault<z.ZodEnum<{
+        chromium: "chromium";
+        firefox: "firefox";
+        webkit: "webkit";
+    }>>;
     device: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    playwrightInput: string;
-    playwrightViewportSize: string;
-    browser: "chromium" | "firefox" | "webkit";
-    device: string;
-    playwrightStoragePath?: string | undefined;
-    playwrightSaveStoragePath?: string | undefined;
-}, {
-    playwrightInput: string;
-    playwrightStoragePath?: string | undefined;
-    playwrightSaveStoragePath?: string | undefined;
-    playwrightViewportSize?: string | undefined;
-    browser?: "chromium" | "firefox" | "webkit" | undefined;
-    device?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const baseTraceSchema: z.ZodObject<{
     deployDashboard: z.ZodDefault<z.ZodBoolean>;
-    runtime: z.ZodDefault<z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>>;
+    runtime: z.ZodDefault<z.ZodPreprocess<z.ZodEnum<typeof RuntimeEnvironment>, unknown>>;
     dockerNetwork: z.ZodDefault<z.ZodString>;
     dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
     k8sNamespace: z.ZodDefault<z.ZodString>;
@@ -161,65 +112,21 @@ export declare const baseTraceSchema: z.ZodObject<{
     authHeader: z.ZodDefault<z.ZodString>;
     authScheme: z.ZodDefault<z.ZodString>;
     insecure: z.ZodDefault<z.ZodBoolean>;
-    output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    output: z.ZodOptional<z.ZodString>;
     outputDir: z.ZodString;
     force: z.ZodDefault<z.ZodBoolean>;
     mockPort: z.ZodDefault<z.ZodNumber>;
     optionalFields: z.ZodDefault<z.ZodBoolean>;
     prompt: z.ZodString;
-    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    language: z.ZodEnum<typeof ProgrammingLanguage>;
     framework: z.ZodString;
     trace: z.ZodString;
-    include: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    exclude: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    language: ProgrammingLanguage;
-    framework: string;
-    deployDashboard: boolean;
-    runtime: RuntimeEnvironment;
-    dockerNetwork: string;
-    dockerWorkerPort: number;
-    k8sNamespace: string;
-    k8sConfig: string;
-    k8sContext: string;
-    authHeader: string;
-    authScheme: string;
-    insecure: boolean;
-    outputDir: string;
-    force: boolean;
-    mockPort: number;
-    optionalFields: boolean;
-    prompt: string;
-    trace: string;
-    include: string[];
-    exclude: string[];
-    output?: string | undefined;
-}, {
-    language: ProgrammingLanguage;
-    framework: string;
-    outputDir: string;
-    prompt: string;
-    trace: string;
-    deployDashboard?: boolean | undefined;
-    runtime?: unknown;
-    dockerNetwork?: string | undefined;
-    dockerWorkerPort?: number | undefined;
-    k8sNamespace?: string | undefined;
-    k8sConfig?: string | undefined;
-    k8sContext?: string | undefined;
-    authHeader?: string | undefined;
-    authScheme?: string | undefined;
-    insecure?: boolean | undefined;
-    output?: string | undefined;
-    force?: boolean | undefined;
-    mockPort?: number | undefined;
-    optionalFields?: boolean | undefined;
-    include?: string[] | undefined;
-    exclude?: string[] | undefined;
-}>;
+    include: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 export declare const baseTestSchema: {
     deployDashboard: z.ZodDefault<z.ZodBoolean>;
-    runtime: z.ZodDefault<z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>>;
+    runtime: z.ZodDefault<z.ZodPreprocess<z.ZodEnum<typeof RuntimeEnvironment>, unknown>>;
     dockerNetwork: z.ZodDefault<z.ZodString>;
     dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
     k8sNamespace: z.ZodDefault<z.ZodString>;
@@ -228,33 +135,34 @@ export declare const baseTestSchema: {
     authHeader: z.ZodDefault<z.ZodString>;
     authScheme: z.ZodDefault<z.ZodString>;
     insecure: z.ZodDefault<z.ZodBoolean>;
-    output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    output: z.ZodOptional<z.ZodString>;
     outputDir: z.ZodString;
     force: z.ZodDefault<z.ZodBoolean>;
     mockPort: z.ZodDefault<z.ZodNumber>;
     optionalFields: z.ZodDefault<z.ZodBoolean>;
     prompt: z.ZodString;
-    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    language: z.ZodEnum<typeof ProgrammingLanguage>;
     framework: z.ZodString;
     endpointURL: z.ZodString;
-    method: z.ZodDefault<z.ZodUnion<[z.ZodNativeEnum<typeof HttpMethod>, z.ZodLiteral<"">]>>;
+    method: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<typeof HttpMethod>, z.ZodLiteral<"">]>>;
     apiSchema: z.ZodDefault<z.ZodString>;
     pathParams: z.ZodDefault<z.ZodString>;
     queryParams: z.ZodDefault<z.ZodString>;
     formParams: z.ZodDefault<z.ZodString>;
-    requestData: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
-    responseStatusCode: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+    requestData: z.ZodDefault<z.ZodString>;
+    responseStatusCode: z.ZodDefault<z.ZodString>;
 };
 export declare const codeRefactoringSchema: z.ZodObject<{
     codeReuse: z.ZodDefault<z.ZodBoolean>;
     modularizeCode: z.ZodDefault<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    codeReuse: boolean;
-    modularizeCode: boolean;
-}, {
-    codeReuse?: boolean | undefined;
-    modularizeCode?: boolean | undefined;
-}>;
+}, z.core.$strip>;
+/** The `testName` field for a recording-driven generation tool.
+ *
+ *  Single-sourced because the description is prompt text: it is the only thing
+ *  steering the agent's choice of title, it gets re-tuned against eval results,
+ *  and two copies would let the UI and E2E tools drift apart silently. Each
+ *  tool passes the title its own generator falls back to (SKYR-4468). */
+export declare const testNameField: (fallbackTitle: string) => z.ZodOptional<z.ZodString>;
 /** Test types skyramp_enhance_assertions supports — single-sourced so the
  *  tool's schema enum and generation-time baseline seeding cannot drift
  *  (contract additionally requires provider mode at the seeding site). */

package/build/types/TestTypes.js

@@ -64,14 +64,14 @@ export var RuntimeEnvironment;
     RuntimeEnvironment["DOCKER"] = "docker";
     RuntimeEnvironment["KUBERNETES"] = "k8s";
 })(RuntimeEnvironment || (RuntimeEnvironment = {}));
-export const runtimeEnvironmentSchema = z.nativeEnum(RuntimeEnvironment);
+export const runtimeEnvironmentSchema = z.enum(RuntimeEnvironment);
 export const runtimeEnvironmentInputSchema = z.preprocess((value) => (value === "kubernetes" ? RuntimeEnvironment.KUBERNETES : value), runtimeEnvironmentSchema);
 export function normalizeRuntimeEnvironment(value) {
     return value === "kubernetes" ? RuntimeEnvironment.KUBERNETES : value;
 }
 export const languageSchema = z.object({
     language: z
-        .nativeEnum(ProgrammingLanguage)
+        .enum(ProgrammingLanguage)
         .describe("Programming language for the generated test (default: python). Must be one of: python, typescript, javascript, java"),
     framework: z
         .string()
@@ -217,7 +217,7 @@ export const baseTestSchema = {
         "(e.g., https://demoshop.skyramp.dev/api/v1/products). " +
         "MUST include both the base URL and the endpoint path — never just the base URL alone."),
     method: z
-        .union([z.nativeEnum(HttpMethod), z.literal("")])
+        .union([z.enum(HttpMethod), z.literal("")])
         .default("")
         .describe('HTTP method to use. DEFAULT: Use empty string ("") to test ALL available methods from OpenAPI schema (recommended). Only specify a specific method (GET, POST, PUT, DELETE, etc.) if user explicitly requests testing a single method only.'),
     apiSchema: z
@@ -291,6 +291,28 @@ export const codeRefactoringSchema = z.object({
         .default(false)
         .describe("Whether to modularize the code"),
 });
+/** The `testName` field for a recording-driven generation tool.
+ *
+ *  Single-sourced because the description is prompt text: it is the only thing
+ *  steering the agent's choice of title, it gets re-tuned against eval results,
+ *  and two copies would let the UI and E2E tools drift apart silently. Each
+ *  tool passes the title its own generator falls back to (SKYR-4468). */
+export const testNameField = (fallbackTitle) => z
+    .string()
+    // .trim() normalises incidental whitespace and, combined with .min(1),
+    // rejects a whitespace-only title, which would otherwise produce a
+    // meaningless test title and identifier (SKYR-4468).
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Title for the generated test. Name the BEHAVIOUR this recording verifies, " +
+    "taken from the recommendation the recording came from — not the page it happens on. " +
+    "Keep it to one short phrase, under about 60 characters. " +
+    'Example: "Add to cart from search results", not "Search page". ' +
+    "Skyramp emits it verbatim as the Playwright test title for TypeScript/JavaScript. " +
+    "Python and Java get it as a comment above the test, and a function name built from " +
+    "its ASCII words and cut at 80 characters. " +
+    `Omit it and the test stays titled \`${fallbackTitle}\`, which claims nothing.`);
 /** Test types skyramp_enhance_assertions supports — single-sourced so the
  *  tool's schema enum and generation-time baseline seeding cannot drift
  *  (contract additionally requires provider mode at the seeding site). */

package/build/types/TestbotReport.d.ts

@@ -227,7 +227,10 @@ export interface TestbotReport {
         /** Files an UPDATE or REGENERATE verdict edited, minus any already counted as
          *  generated — one file owes one run however it was written. */
         updated: number;
-        /** How many of those `generated + updated` files were passed to
+        /** Files a VERIFY verdict names in the primary repository, minus any already
+         *  counted above. Never edited, but each owes one run. */
+        verified: number;
+        /** How many of those `generated + updated + verified` files were passed to
          *  skyramp_execute_test. The file reached the runner; that is not proof a test
          *  ran, because a runner can exit 0 having executed nothing. */
         executed: number;

package/build/utils/assertion-verify/metrics.js

@@ -197,6 +197,18 @@ function expectSites(raw, stripped) {
             matcher = link[1];
             break;
         }
+        // `expect(async () => { ... }).toPass()` is a retry wrapper, not an
+        // assertion: the assertions are the expect() calls inside it. Record none
+        // for the wrapper and resume scanning inside its argument, so the inner
+        // ones are scored for what they check (the generated order assertion
+        // compares boundingBox() geometry inside toPass()).
+        // `.not.toPass()` inverts the block (it must keep failing), so its inner
+        // assertions are not positive checks: it falls through to ordinary wrapper
+        // scoring (weight 1). Python's Playwright has no to_pass equivalent.
+        if (matcher === "toPass" && !links.includes("not")) {
+            re.lastIndex = openIdx + 1;
+            continue;
+        }
         let matcherArgs;
         if (matcher !== undefined) {
             const matcherOpen = /^\s*\(/.exec(stripped.slice(cursor));

package/build/utils/docker.d.ts

@@ -1,15 +1,37 @@
+/**
+ * Whether a pull failed because the image has nothing for the requested platform. The
+ * wording depends on the daemon and its image store: a Windows daemon answers a linux-only
+ * image, even a multi-platform one, with "image operating system ... cannot be used on this
+ * platform" (observed on Windows Server 2022, Docker 29.7.2); a manifest list without the
+ * platform gives "no matching manifest"; the containerd image store says "no match for
+ * platform in manifest". Anything else -- the network, a rate limit, a full disk -- is not
+ * this.
+ */
+export declare function isPlatformUnavailableError(err: unknown): boolean;
+/**
+ * Returns the Docker platform string for the current host architecture.
+ * Mirrors the backend's getDockerPlatform() in cmd/libs/init.go.
+ */
+export declare function getDockerPlatform(): string;
 /**
  * Pull a Docker image by name.
  *
- * When `dockerPlatform` is provided, pulls with that exact platform — no
- * fallback logic runs.  Use this for images whose platform is known ahead
- * of time (e.g. executor is amd64-only).
- *
- * When `dockerPlatform` is omitted, uses the host architecture and falls
- * back to linux/amd64 if the arm64 pull fails or the image doesn't land
- * locally (Docker Desktop quirk on Apple Silicon).
+ * `dockerPlatform` defaults to the host architecture. Whether given or
+ * defaulted, a `linux/arm64` pull falls back to `linux/amd64` when the arm64
+ * pull reports no matching manifest or completes without the image landing
+ * locally (Docker Desktop quirk on Apple Silicon). Any other platform is
+ * pulled exactly, with no fallback.
  */
 export declare function pullDockerImage(imageName: string, dockerPlatform?: string): Promise<void>;
+/**
+ * The default daemon's operating system ("windows" or "linux"), or undefined when it
+ * cannot be determined. The startup prefetch pulls each image for this OS; when it is
+ * undefined the executor is pulled as linux/amd64 and the worker for the host's own
+ * architecture (getDockerPlatform). Guessing is acceptable there because the prefetch is
+ * best-effort: a wrong guess costs a download, and the run itself refuses to guess
+ * (resolvePlatform in FleetExecutionService).
+ */
+export declare function dockerDaemonOsType(): Promise<string | undefined>;
 /**
  * Check if a Docker image exists locally for the given reference (repo:tag or digest).
  * Uses image inspect (daemon name resolution), not listImages tag scanning.

package/build/utils/docker.js

@@ -26,11 +26,26 @@ function isManifestMismatchError(err) {
     const msg = err?.message ?? "";
     return msg.includes("no matching manifest");
 }
+/**
+ * Whether a pull failed because the image has nothing for the requested platform. The
+ * wording depends on the daemon and its image store: a Windows daemon answers a linux-only
+ * image, even a multi-platform one, with "image operating system ... cannot be used on this
+ * platform" (observed on Windows Server 2022, Docker 29.7.2); a manifest list without the
+ * platform gives "no matching manifest"; the containerd image store says "no match for
+ * platform in manifest". Anything else -- the network, a rate limit, a full disk -- is not
+ * this.
+ */
+export function isPlatformUnavailableError(err) {
+    const msg = err?.message ?? "";
+    return (msg.includes("no matching manifest") ||
+        msg.includes("cannot be used on this platform") ||
+        msg.includes("no match for platform in manifest"));
+}
 /**
  * Returns the Docker platform string for the current host architecture.
  * Mirrors the backend's getDockerPlatform() in cmd/libs/init.go.
  */
-function getDockerPlatform() {
+export function getDockerPlatform() {
     return process.arch === "arm64" ? "linux/arm64" : "linux/amd64";
 }
 async function doPull(docker, imageName, platform) {
@@ -40,14 +55,27 @@ async function doPull(docker, imageName, platform) {
                 return reject(err);
             if (!stream)
                 return reject(new Error("No stream received from docker pull"));
+            // A pull can fail INSIDE the progress stream: followProgress still finishes
+            // without an error object, and the failure appears only as an `error` field on
+            // one of the messages. Without reading them, a pull that stored nothing is
+            // logged as a success. The Go side guards the same thing (`message.Error` in
+            // RunSkyrampWorker).
+            let streamError;
             docker.modem.followProgress(stream, (err) => {
                 if (err)
                     return reject(err);
+                if (streamError) {
+                    return reject(new Error(`docker pull ${imageName} (${platform}) failed: ${streamError}`));
+                }
                 logger.info("Docker image pulled successfully", {
                     image: imageName,
                     platform,
                 });
                 resolve();
+            }, (msg) => {
+                if (msg?.error && streamError === undefined) {
+                    streamError = msg.errorDetail?.message ?? msg.error;
+                }
             });
         });
     });
@@ -55,39 +83,67 @@ async function doPull(docker, imageName, platform) {
 /**
  * Pull a Docker image by name.
  *
- * When `dockerPlatform` is provided, pulls with that exact platform — no
- * fallback logic runs.  Use this for images whose platform is known ahead
- * of time (e.g. executor is amd64-only).
- *
- * When `dockerPlatform` is omitted, uses the host architecture and falls
- * back to linux/amd64 if the arm64 pull fails or the image doesn't land
- * locally (Docker Desktop quirk on Apple Silicon).
+ * `dockerPlatform` defaults to the host architecture. Whether given or
+ * defaulted, a `linux/arm64` pull falls back to `linux/amd64` when the arm64
+ * pull reports no matching manifest or completes without the image landing
+ * locally (Docker Desktop quirk on Apple Silicon). Any other platform is
+ * pulled exactly, with no fallback.
  */
 export async function pullDockerImage(imageName, dockerPlatform) {
     const client = new Dockerode();
-    if (dockerPlatform) {
-        await doPull(client, imageName, dockerPlatform);
-        return;
+    const platform = dockerPlatform ?? getDockerPlatform();
+    // Docker Desktop on Apple Silicon serves amd64-only images under emulation, but an arm64
+    // pull of one either reports no matching manifest or completes and stores nothing. Those
+    // are the same rule, not two special cases: try these platforms in order until one
+    // actually lands.
+    const candidates = platform === "linux/arm64" ? [platform, "linux/amd64"] : [platform];
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        const next = candidates[i + 1];
+        try {
+            await doPull(client, imageName, candidate);
+        }
+        catch (err) {
+            // A manifest mismatch is the one failure another platform can answer.
+            if (next === undefined || !isManifestMismatchError(err))
+                throw err;
+            logger.info("pull failed, retrying on the next platform", {
+                image: imageName,
+                failed: candidate,
+                next,
+            });
+            continue;
+        }
+        // A pull can end its stream cleanly and store nothing, so success is the image being
+        // present -- not the pull returning.
+        if (await dockerImageExistsLocally(imageName))
+            return;
+        if (next === undefined)
+            break;
+        logger.info("pull completed but the image is absent, retrying on the next platform", {
+            image: imageName,
+            failed: candidate,
+            next,
+        });
     }
-    const platform = getDockerPlatform();
+    throw new Error(`docker pull ${imageName} (${candidates.join(", ")}) reported success but the image is not present locally`);
+}
+/**
+ * The default daemon's operating system ("windows" or "linux"), or undefined when it
+ * cannot be determined. The startup prefetch pulls each image for this OS; when it is
+ * undefined the executor is pulled as linux/amd64 and the worker for the host's own
+ * architecture (getDockerPlatform). Guessing is acceptable there because the prefetch is
+ * best-effort: a wrong guess costs a download, and the run itself refuses to guess
+ * (resolvePlatform in FleetExecutionService).
+ */
+export async function dockerDaemonOsType() {
     try {
-        await doPull(client, imageName, platform);
+        const info = (await new Dockerode().info());
+        return info?.OSType;
     }
     catch (err) {
-        if (platform === "linux/arm64" && isManifestMismatchError(err)) {
-            logger.info("arm64 pull failed, retrying with linux/amd64 (emulation on Apple Silicon)", { image: imageName });
-            await doPull(client, imageName, "linux/amd64");
-            return;
-        }
-        throw err;
-    }
-    // On Docker Desktop/Mac, pulling an amd64-only image with linux/arm64 can
-    // complete the stream without error yet not store the image locally.
-    // Verify it actually landed, and fall back to amd64 if not.
-    if (platform === "linux/arm64" &&
-        !(await dockerImageExistsLocally(imageName))) {
-        logger.info("arm64 pull completed but image not found locally, retrying with linux/amd64", { image: imageName });
-        await doPull(client, imageName, "linux/amd64");
+        logger.warning("Could not determine the Docker daemon OS", { error: err });
+        return undefined;
     }
 }
 /**

package/build/utils/findUp.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The first `<dir>/<candidate>` that exists, checking `from` and then each
+ * ancestor, or undefined.
+ *
+ * With `stopAtRepoRoot`, only the directories up to the nearest one holding
+ * `.git` (a directory or a file, so worktrees count) are searched, and a `from`
+ * outside any checkout searches nothing: a parent directory is not the
+ * repository's to answer for. The walk never passes the filesystem root or
+ * MAX_LEVELS.
+ */
+export declare function findUp(from: string, candidates: readonly string[], { stopAtRepoRoot }?: {
+    stopAtRepoRoot?: boolean;
+}): string | undefined;
+/** The package's manifest as Node would find it from `from`: the nearest
+ *  `node_modules/<pkg>/package.json` walking UP from there. Node's own lookup
+ *  never reads NODE_PATH for this, and neither does this one. A manifest that
+ *  does not parse is logged and treated as absent. */
+export declare function installedManifest(pkg: string, from: string, options?: {
+    stopAtRepoRoot?: boolean;
+}): Record<string, unknown> | undefined;