@skillcap/gdh 0.11.0 → 0.13.0

package/node_modules/@gdh/runtime/dist/index.js

@@ -1,13 +1,15 @@
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
+import { promisify } from "node:util";
 import WebSocket, {} from "ws";
 import { GDH_RECIPE_SCHEMA_VERSION, GDH_RUNTIME_RECIPE_RUN_VERSION, definePackageBoundary, presentPublicRuntimeTerms, resolveConfiguredGodotEditorBin, } from "@gdh/core";
 import { parse } from "yaml";
 import { inspectRuntimeBridgeSurface } from "./bridge-surface.js";
+import { buildDockerRuntimeLaunchPreview, ensureDockerRuntimeImagePlan, inspectDockerRuntimeProvider, toDockerContainerPath, } from "./docker-provider.js";
 export { inspectRuntimeBridgeSurface, installRuntimeBridgeSurface, removeRuntimeBridgeSurface, repairRuntimeBridgeSurface, resolveRuntimeBridgeConfig, } from "./bridge-surface.js";
 export const runtimePackage = definePackageBoundary({
     name: "@gdh/runtime",
@@ -17,6 +19,15 @@ export const runtimePackage = definePackageBoundary({
 });
 const PRIMARY_RUN_CONFIGURATION_DIRECTORY = ".gdh/run-configurations";
 const LEGACY_RECIPE_DIRECTORY = ".gdh/recipes";
+const LOCAL_RUNTIME_PROVIDER = "local";
+const DOCKER_RUNTIME_PROVIDER = "docker";
+const RUNTIME_SCREENSHOT_IMAGE_FILENAME = "screenshot.png";
+const RUNTIME_SCREENSHOT_METADATA_FILENAME = "screenshot.json";
+const RUNTIME_SCREENSHOT_CONTAINER_DIRECTORY = "/gdh-artifacts";
+const ENV_SCREENSHOT_CAPTURE = "GDH_SCREENSHOT_CAPTURE";
+const ENV_SCREENSHOT_PATH = "GDH_SCREENSHOT_PATH";
+const ENV_SCREENSHOT_METADATA_PATH = "GDH_SCREENSHOT_METADATA_PATH";
+const execFileAsync = promisify(execFile);
 export async function listRuntimeRecipes(input) {
     const context = await loadRuntimeRecipeContext(input);
     const recipes = context.recipes.map((recipe) => ({
@@ -79,6 +90,7 @@ export async function checkRuntimeRecipe(input) {
     });
 }
 export async function runRuntimeRecipe(input) {
+    const screenshotRequested = input.screenshotPolicy === "fallback";
     const liveCheck = await checkRuntimeRecipe(input);
     if (liveCheck.state !== "runnable" || liveCheck.recipe === null) {
         return {
@@ -95,6 +107,9 @@ export async function runRuntimeRecipe(input) {
             finishedAt: new Date().toISOString(),
             exitCode: null,
             launchCommand: liveCheck.launchPreview?.command ?? null,
+            screenshot: screenshotRequested
+                ? buildUnavailableRuntimeScreenshotResult("Screenshot capture was requested, but the runtime recipe was blocked before launch.", "runtime_launch_blocked")
+                : buildOmittedRuntimeScreenshotResult(),
             artifacts: [],
             statusPromotion: "none",
         };
@@ -130,6 +145,9 @@ export async function runRuntimeRecipe(input) {
                 finishedAt: new Date().toISOString(),
                 exitCode: null,
                 launchCommand: executionCheck.launchPreview?.command ?? null,
+                screenshot: screenshotRequested
+                    ? buildUnavailableRuntimeScreenshotResult("Screenshot capture was requested, but GDH could not assemble a runnable launch preview.", "launch_preview_unavailable")
+                    : buildOmittedRuntimeScreenshotResult(),
                 artifacts: [],
                 statusPromotion: "none",
             };
@@ -143,10 +161,11 @@ export async function runRuntimeRecipe(input) {
         const artifactDirectory = input.artifactDirectory ??
             (await createRunArtifactDirectory(input.targetPath, `recipe-${input.recipeId}`));
         await fs.mkdir(artifactDirectory, { recursive: true });
+        const preparedScreenshot = buildRuntimeScreenshotCapture(executionCheck.launchPreview, artifactDirectory, input.screenshotPolicy ?? "never");
         const startedAt = new Date().toISOString();
         let execution = null;
         try {
-            execution = await executeCommand(executionCheck.launchPreview, artifactDirectory, executionCheck.recipe?.launch.kind ?? "project_launch_adapter", input.maxRuntimeSeconds ?? null);
+            execution = await executeCommand(preparedScreenshot.preview, artifactDirectory, executionCheck.recipe?.launch.kind ?? "project_launch_adapter", input.maxRuntimeSeconds ?? null);
         }
         catch (error) {
             execution = {
@@ -165,6 +184,7 @@ export async function runRuntimeRecipe(input) {
             };
         }
         const finishedAt = new Date().toISOString();
+        const screenshot = await finalizeRuntimeScreenshotCapture(preparedScreenshot.result);
         const reportPath = path.join(artifactDirectory, "report.json");
         const result = {
             version: GDH_RUNTIME_RECIPE_RUN_VERSION,
@@ -186,9 +206,28 @@ export async function runRuntimeRecipe(input) {
             startedAt,
             finishedAt,
             exitCode: execution.exitCode,
-            launchCommand: executionCheck.launchPreview.command,
+            launchCommand: preparedScreenshot.preview.command,
+            screenshot,
             artifacts: [
                 ...execution.artifacts,
+                ...(screenshot.state === "captured" && screenshot.imagePath !== null
+                    ? [
+                        {
+                            id: "screenshot",
+                            path: screenshot.imagePath,
+                            description: "Rendered screenshot captured during this runtime recipe run.",
+                        },
+                    ]
+                    : []),
+                ...(screenshot.metadataPath !== null
+                    ? [
+                        {
+                            id: "screenshot-metadata",
+                            path: screenshot.metadataPath,
+                            description: "Structured screenshot-capture metadata for this runtime recipe run.",
+                        },
+                    ]
+                    : []),
                 {
                     id: "report",
                     path: reportPath,
@@ -380,18 +419,20 @@ async function inspectRuntimeRecipe(input) {
         };
     }
     const values = resolveRuntimeValues(recipe, input);
-    const provider = resolveProvider(recipe, input.projectConfig, input.provider);
+    const provider = await inspectProvider(recipe, input.projectConfig, input.provider, values.environment);
     const preChecks = await resolvePrechecks({
         targetPath: input.targetPath,
         evaluationRootPath: input.evaluationRootPath,
         recipe,
         environment: values.environment,
+        provider,
     });
     const launchPreview = await buildLaunchPreview({
         targetPath: input.targetPath,
         evaluationRootPath: input.evaluationRootPath,
         recipe,
         values,
+        provider,
         workspaceMode: input.workspaceMode,
     });
     const reasons = [
@@ -399,8 +440,10 @@ async function inspectRuntimeRecipe(input) {
         ...resolveEnvironmentReasons(values.environment),
         ...resolvePrecheckReasons(preChecks),
     ];
-    if (!provider.supported) {
-        reasons.push("provider_not_supported");
+    for (const reason of provider.reasons) {
+        if (!reasons.includes(reason)) {
+            reasons.push(reason);
+        }
     }
     const hasMisconfiguration = preChecks.some((entry) => entry.status === "failed" &&
         (entry.kind === "project_path_exists" ||
@@ -412,7 +455,7 @@ async function inspectRuntimeRecipe(input) {
         (preChecks.some((entry) => entry.status === "failed" && entry.required) ||
             values.parameters.some((entry) => entry.status === "missing" && entry.required) ||
             values.environment.some((entry) => entry.status === "missing" && entry.required) ||
-            !provider.supported);
+            provider.state !== "ready");
     const state = hasMisconfiguration
         ? "misconfigured"
         : isBlocked || launchPreview === null
@@ -425,7 +468,9 @@ async function inspectRuntimeRecipe(input) {
         summary: state === "runnable"
             ? `Runtime recipe "${recipe.id}" is runnable.`
             : state === "blocked"
-                ? `Runtime recipe "${recipe.id}" is blocked by environment or input requirements.`
+                ? provider.state === "blocked"
+                    ? provider.summary
+                    : `Runtime recipe "${recipe.id}" is blocked by environment or input requirements.`
                 : `Runtime recipe "${recipe.id}" is misconfigured.`,
         reasons,
         recipe,
@@ -596,21 +641,48 @@ function resolveRuntimeValues(recipe, input) {
         environment,
     };
 }
-function resolveProvider(recipe, projectConfig, requestedProvider) {
-    const allowedProviders = projectConfig?.allowedProviders ?? ["local"];
-    const declaredProviders = recipe.providers.length > 0 ? recipe.providers : ["local"];
+async function inspectProvider(recipe, projectConfig, requestedProvider, environment) {
+    const allowedProviders = projectConfig?.allowedProviders ?? [LOCAL_RUNTIME_PROVIDER];
+    const declaredProviders = recipe.providers.length > 0 ? recipe.providers : [LOCAL_RUNTIME_PROVIDER];
     const resolved = requestedProvider ?? declaredProviders[0] ?? null;
-    const supported = resolved !== null &&
+    const supportedBySelection = resolved !== null &&
         allowedProviders.includes(resolved) &&
         declaredProviders.includes(resolved);
+    if (!supportedBySelection) {
+        return {
+            requested: requestedProvider,
+            resolved,
+            allowedProviders,
+            supported: false,
+            state: "unsupported",
+            reasons: ["provider_not_supported"],
+            summary: resolved === null
+                ? "No runtime provider could be resolved for this run configuration."
+                : `Provider "${resolved}" is not supported by the recipe or project configuration.`,
+        };
+    }
+    if (resolved === DOCKER_RUNTIME_PROVIDER) {
+        const docker = await inspectDockerRuntimeProvider(new Map(environment
+            .filter((entry) => entry.value !== null)
+            .map((entry) => [entry.name, entry.value ?? ""])));
+        return {
+            requested: requestedProvider,
+            resolved,
+            allowedProviders,
+            supported: docker.state === "ready",
+            state: docker.state,
+            reasons: docker.reasons,
+            summary: docker.summary,
+        };
+    }
     return {
         requested: requestedProvider,
         resolved,
         allowedProviders,
-        supported,
-        summary: supported
-            ? `Provider "${resolved}" is allowed for this target.`
-            : `Provider "${resolved}" is not supported by the recipe or project configuration.`,
+        supported: true,
+        state: "ready",
+        reasons: [],
+        summary: `Provider "${resolved}" is allowed for this target.`,
     };
 }
 async function resolvePrechecks(input) {
@@ -641,6 +713,14 @@ async function resolvePrechecks(input) {
             continue;
         }
         if (definition.kind === "godot_editor_configured") {
+            if (input.provider.resolved === DOCKER_RUNTIME_PROVIDER) {
+                results.push({
+                    ...definition,
+                    status: "skipped",
+                    reason: null,
+                });
+                continue;
+            }
             const configured = Boolean(await resolveConfiguredGodotEditorBin({
                 targetPath: input.targetPath,
                 environmentOverride: environmentMap.get("GDH_GODOT_EDITOR_BIN") ?? null,
@@ -704,6 +784,41 @@ async function buildLaunchPreview(input) {
         name,
         value,
     }));
+    const environmentEntries = new Map(environment.map((entry) => [entry.name, entry.value]));
+    if (input.provider.resolved === DOCKER_RUNTIME_PROVIDER) {
+        const dockerCommand = input.recipe.launch.kind === "godot_project"
+            ? [
+                "/usr/local/bin/godot-linux",
+                "--path",
+                toDockerContainerPath(input.evaluationRootPath, path.join(input.evaluationRootPath, input.recipe.projectPath)),
+                input.recipe.launch.scenePath,
+                ...input.recipe.launch.arguments,
+                ...parameterArguments,
+                ...featureArguments,
+            ]
+            : [
+                input.recipe.launch.interpreter === null
+                    ? toDockerContainerPath(input.evaluationRootPath, path.join(input.evaluationRootPath, input.recipe.launch.scriptPath))
+                    : input.recipe.launch.interpreter,
+                ...(input.recipe.launch.interpreter === null
+                    ? []
+                    : [
+                        toDockerContainerPath(input.evaluationRootPath, path.join(input.evaluationRootPath, input.recipe.launch.scriptPath)),
+                    ]),
+                ...input.recipe.launch.arguments,
+                ...parameterArguments,
+                ...featureArguments,
+            ];
+        return buildDockerRuntimeLaunchPreview({
+            evaluationRootPath: input.evaluationRootPath,
+            containerWorkingDirectory: toDockerContainerPath(input.evaluationRootPath, path.join(input.evaluationRootPath, input.recipe.launch.kind === "project_launch_adapter"
+                ? input.recipe.launch.workingDirectory ?? input.recipe.projectPath
+                : input.recipe.projectPath)),
+            command: dockerCommand,
+            environment: environmentEntries,
+            workspaceMode: input.workspaceMode,
+        });
+    }
     if (input.recipe.launch.kind === "godot_project") {
         const godotBin = await resolveConfiguredGodotEditorBin({
             targetPath: input.targetPath,
@@ -727,6 +842,8 @@ async function buildLaunchPreview(input) {
             cwd: projectDirectory,
             env: environment,
             workspaceMode: input.workspaceMode,
+            prepareHints: [],
+            cleanupHints: [],
         };
     }
     const scriptPath = path.join(input.evaluationRootPath, input.recipe.launch.scriptPath);
@@ -749,6 +866,8 @@ async function buildLaunchPreview(input) {
         cwd: path.join(input.evaluationRootPath, input.recipe.launch.workingDirectory ?? input.recipe.projectPath),
         env: environment,
         workspaceMode: input.workspaceMode,
+        prepareHints: [],
+        cleanupHints: [],
     };
 }
 function bridgeNotRequired() {
@@ -808,6 +927,285 @@ async function createRunArtifactDirectory(targetPath, recipeId) {
     await fs.mkdir(directory, { recursive: true });
     return directory;
 }
+function buildRuntimeScreenshotCapture(preview, artifactDirectory, screenshotPolicy) {
+    if (screenshotPolicy !== "fallback") {
+        return {
+            preview,
+            result: buildOmittedRuntimeScreenshotResult(),
+        };
+    }
+    const imagePath = path.resolve(artifactDirectory, RUNTIME_SCREENSHOT_IMAGE_FILENAME);
+    const metadataPath = path.resolve(artifactDirectory, RUNTIME_SCREENSHOT_METADATA_FILENAME);
+    return {
+        preview: isDockerLaunchPreview(preview)
+            ? attachDockerScreenshotCapture(preview, artifactDirectory)
+            : {
+                ...preview,
+                env: [
+                    ...preview.env,
+                    {
+                        name: ENV_SCREENSHOT_CAPTURE,
+                        value: "1",
+                    },
+                    {
+                        name: ENV_SCREENSHOT_PATH,
+                        value: imagePath,
+                    },
+                    {
+                        name: ENV_SCREENSHOT_METADATA_PATH,
+                        value: metadataPath,
+                    },
+                ],
+            },
+        result: {
+            requested: true,
+            state: "unavailable",
+            summary: "Screenshot capture was requested but has not completed yet.",
+            reason: null,
+            imagePath,
+            metadataPath,
+        },
+    };
+}
+function isDockerLaunchPreview(preview) {
+    return (preview.prepareHints ?? []).some((hint) => hint.kind === "docker_runtime_image");
+}
+function attachDockerScreenshotCapture(preview, artifactDirectory) {
+    const prepareHint = (preview.prepareHints ?? []).find((hint) => hint.kind === "docker_runtime_image") ?? null;
+    if (prepareHint === null ||
+        preview.command === null ||
+        preview.command[0] !== "docker") {
+        return preview;
+    }
+    const imageIndex = preview.command.lastIndexOf(prepareHint.imageTag);
+    if (imageIndex <= 0) {
+        return preview;
+    }
+    const resolvedArtifactDirectory = path.resolve(artifactDirectory);
+    const injectedArgs = [
+        "--mount",
+        `type=bind,src=${resolvedArtifactDirectory},dst=${RUNTIME_SCREENSHOT_CONTAINER_DIRECTORY}`,
+        "--env",
+        `${ENV_SCREENSHOT_CAPTURE}=1`,
+        "--env",
+        `${ENV_SCREENSHOT_PATH}=${RUNTIME_SCREENSHOT_CONTAINER_DIRECTORY}/${RUNTIME_SCREENSHOT_IMAGE_FILENAME}`,
+        "--env",
+        `${ENV_SCREENSHOT_METADATA_PATH}=${RUNTIME_SCREENSHOT_CONTAINER_DIRECTORY}/${RUNTIME_SCREENSHOT_METADATA_FILENAME}`,
+    ];
+    return {
+        ...preview,
+        command: [
+            ...preview.command.slice(0, imageIndex),
+            ...injectedArgs,
+            ...preview.command.slice(imageIndex),
+        ],
+    };
+}
+function prepareBridgeSessionLaunchPreview(preview) {
+    const explicitCapture = readExplicitScreenshotCapture(preview);
+    if (explicitCapture === null || !isDockerLaunchPreview(preview)) {
+        return preview;
+    }
+    return attachDockerExplicitScreenshotCapture(preview, explicitCapture);
+}
+function readExplicitScreenshotCapture(preview) {
+    const environment = readLaunchEnvironment(preview);
+    if (environment.get(ENV_SCREENSHOT_CAPTURE) !== "1") {
+        return null;
+    }
+    const imagePath = environment.get(ENV_SCREENSHOT_PATH) ?? null;
+    const metadataPath = environment.get(ENV_SCREENSHOT_METADATA_PATH) ?? null;
+    if (imagePath === null || metadataPath === null) {
+        return null;
+    }
+    return {
+        imagePath: path.resolve(imagePath),
+        metadataPath: path.resolve(metadataPath),
+    };
+}
+function readLaunchEnvironment(preview) {
+    const environment = new Map(preview.env.map((entry) => [entry.name, entry.value]));
+    if (preview.command?.[0] !== "docker") {
+        return environment;
+    }
+    for (let index = 1; index < preview.command.length; index += 1) {
+        if (preview.command[index] !== "--env") {
+            continue;
+        }
+        const assignment = preview.command[index + 1];
+        if (typeof assignment !== "string") {
+            continue;
+        }
+        const separatorIndex = assignment.indexOf("=");
+        if (separatorIndex <= 0 || separatorIndex === assignment.length - 1) {
+            continue;
+        }
+        environment.set(assignment.slice(0, separatorIndex), assignment.slice(separatorIndex + 1));
+        index += 1;
+    }
+    return environment;
+}
+async function ensureExplicitScreenshotCaptureDirectories(capture) {
+    if (capture === null) {
+        return;
+    }
+    await Promise.all([
+        fs.mkdir(path.dirname(capture.imagePath), { recursive: true }),
+        fs.mkdir(path.dirname(capture.metadataPath), { recursive: true }),
+    ]);
+}
+function attachDockerExplicitScreenshotCapture(preview, capture) {
+    const prepareHint = (preview.prepareHints ?? []).find((hint) => hint.kind === "docker_runtime_image") ?? null;
+    if (prepareHint === null ||
+        preview.command === null ||
+        preview.command[0] !== "docker") {
+        return preview;
+    }
+    const imageIndex = preview.command.lastIndexOf(prepareHint.imageTag);
+    if (imageIndex <= 0) {
+        return preview;
+    }
+    const beforeImage = stripDockerEnvArguments(preview.command.slice(1, imageIndex), new Set([
+        ENV_SCREENSHOT_CAPTURE,
+        ENV_SCREENSHOT_PATH,
+        ENV_SCREENSHOT_METADATA_PATH,
+    ]));
+    const afterImage = preview.command.slice(imageIndex);
+    const mountMappings = new Map();
+    const mapHostFileToContainer = (hostFilePath) => {
+        const hostDirectory = path.dirname(hostFilePath);
+        let containerDirectory = mountMappings.get(hostDirectory) ?? null;
+        if (containerDirectory === null) {
+            containerDirectory = `${RUNTIME_SCREENSHOT_CONTAINER_DIRECTORY}/bridge-${mountMappings.size}`;
+            mountMappings.set(hostDirectory, containerDirectory);
+        }
+        return path.posix.join(containerDirectory, path.basename(hostFilePath));
+    };
+    const containerImagePath = mapHostFileToContainer(capture.imagePath);
+    const containerMetadataPath = mapHostFileToContainer(capture.metadataPath);
+    const mountArgs = [...mountMappings.entries()].flatMap(([hostDirectory, containerDirectory]) => [
+        "--mount",
+        `type=bind,src=${hostDirectory},dst=${containerDirectory}`,
+    ]);
+    return {
+        ...preview,
+        command: [
+            "docker",
+            ...beforeImage,
+            ...mountArgs,
+            "--env",
+            `${ENV_SCREENSHOT_CAPTURE}=1`,
+            "--env",
+            `${ENV_SCREENSHOT_PATH}=${containerImagePath}`,
+            "--env",
+            `${ENV_SCREENSHOT_METADATA_PATH}=${containerMetadataPath}`,
+            ...afterImage,
+        ],
+    };
+}
+function stripDockerEnvArguments(dockerArgs, environmentNames) {
+    const stripped = [];
+    for (let index = 0; index < dockerArgs.length; index += 1) {
+        const current = dockerArgs[index];
+        if (current !== "--env") {
+            stripped.push(current);
+            continue;
+        }
+        const next = dockerArgs[index + 1];
+        const environmentName = typeof next === "string" ? next.split("=")[0] ?? "" : "";
+        if (next !== undefined && environmentNames.has(environmentName)) {
+            index += 1;
+            continue;
+        }
+        stripped.push(current);
+        if (next !== undefined) {
+            stripped.push(next);
+            index += 1;
+        }
+    }
+    return stripped;
+}
+async function finalizeRuntimeScreenshotCapture(provisional) {
+    if (!provisional.requested) {
+        return provisional;
+    }
+    const metadataPath = provisional.metadataPath;
+    if (metadataPath === null) {
+        return buildUnavailableRuntimeScreenshotResult("Screenshot capture was requested, but GDH did not reserve a metadata artifact path.", "screenshot_metadata_path_missing");
+    }
+    const metadataRaw = await fs.readFile(metadataPath, "utf8").catch(() => null);
+    if (metadataRaw === null) {
+        return {
+            ...provisional,
+            state: "unavailable",
+            summary: "Screenshot capture was requested, but the runtime did not write screenshot metadata.",
+            reason: "screenshot_metadata_missing",
+        };
+    }
+    let parsed = null;
+    try {
+        parsed = JSON.parse(metadataRaw);
+    }
+    catch {
+        return {
+            ...provisional,
+            state: "failed",
+            summary: "Screenshot metadata was written but is not valid JSON.",
+            reason: "screenshot_metadata_invalid",
+        };
+    }
+    const state = parsed?.state === "captured" ||
+        parsed?.state === "unavailable" ||
+        parsed?.state === "failed"
+        ? parsed.state
+        : "failed";
+    const reason = typeof parsed?.reason === "string" ? parsed.reason : null;
+    const summary = typeof parsed?.summary === "string"
+        ? parsed.summary
+        : state === "captured"
+            ? "Rendered screenshot captured successfully."
+            : state === "unavailable"
+                ? "Rendered screenshot capture was unavailable for this run."
+                : "Rendered screenshot capture failed.";
+    if (state === "captured") {
+        const imagePresent = provisional.imagePath !== null &&
+            (await pathExists(provisional.imagePath));
+        if (!imagePresent) {
+            return {
+                ...provisional,
+                state: "failed",
+                summary: "Screenshot metadata reported success, but the image artifact is missing.",
+                reason: "screenshot_image_missing",
+            };
+        }
+    }
+    return {
+        ...provisional,
+        state,
+        summary,
+        reason,
+    };
+}
+function buildOmittedRuntimeScreenshotResult() {
+    return {
+        requested: false,
+        state: "omitted",
+        summary: "Screenshot capture was not requested for this runtime recipe run.",
+        reason: null,
+        imagePath: null,
+        metadataPath: null,
+    };
+}
+function buildUnavailableRuntimeScreenshotResult(summary, reason) {
+    return {
+        requested: true,
+        state: "unavailable",
+        summary,
+        reason,
+        imagePath: null,
+        metadataPath: null,
+    };
+}
 async function executeCommand(preview, artifactDirectory, launchKind, maxRuntimeSeconds) {
     const command = preview.command;
     if (command === null || command.length === 0) {
@@ -822,110 +1220,153 @@ async function executeCommand(preview, artifactDirectory, launchKind, maxRuntime
         command,
         env: preview.env,
         workspaceMode: preview.workspaceMode,
+        prepareHints: preview.prepareHints ?? [],
+        cleanupHints: preview.cleanupHints ?? [],
     }, null, 2)}\n`, "utf8");
-    const output = await new Promise((resolve, reject) => {
-        const child = spawn(command[0], command.slice(1), {
-            cwd: preview.cwd ?? undefined,
-            env: {
-                ...process.env,
-                ...Object.fromEntries(preview.env.map((entry) => [entry.name, entry.value])),
-            },
-            stdio: ["ignore", "pipe", "pipe"],
+    await applyLaunchPrepareHints(preview.prepareHints ?? []);
+    try {
+        const output = await new Promise((resolve, reject) => {
+            const child = spawn(command[0], command.slice(1), {
+                cwd: preview.cwd ?? undefined,
+                env: {
+                    ...process.env,
+                    ...Object.fromEntries(preview.env.map((entry) => [entry.name, entry.value])),
+                },
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            let stdout = "";
+            let stderr = "";
+            let timedOut = false;
+            let timeoutHandle = null;
+            let forceKillHandle = null;
+            if (maxRuntimeSeconds !== null && maxRuntimeSeconds > 0) {
+                timeoutHandle = setTimeout(() => {
+                    timedOut = true;
+                    child.kill("SIGTERM");
+                    forceKillHandle = setTimeout(() => {
+                        child.kill("SIGKILL");
+                    }, 5000);
+                }, maxRuntimeSeconds * 1000);
+            }
+            child.stdout.on("data", (chunk) => {
+                stdout += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            });
+            child.stderr.on("data", (chunk) => {
+                stderr += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            });
+            child.on("error", reject);
+            child.on("close", (exitCode, signal) => {
+                if (timeoutHandle !== null) {
+                    clearTimeout(timeoutHandle);
+                }
+                if (forceKillHandle !== null) {
+                    clearTimeout(forceKillHandle);
+                }
+                resolve({
+                    exitCode: exitCode ?? (timedOut ? 0 : 1),
+                    signal: signal ?? null,
+                    stdout,
+                    stderr,
+                    timedOut,
+                });
+            });
         });
-        let stdout = "";
-        let stderr = "";
-        let timedOut = false;
-        let timeoutHandle = null;
-        let forceKillHandle = null;
-        if (maxRuntimeSeconds !== null && maxRuntimeSeconds > 0) {
-            timeoutHandle = setTimeout(() => {
-                timedOut = true;
-                child.kill("SIGTERM");
-                forceKillHandle = setTimeout(() => {
-                    child.kill("SIGKILL");
-                }, 5000);
-            }, maxRuntimeSeconds * 1000);
+        await fs.writeFile(stdoutPath, output.stdout, "utf8");
+        await fs.writeFile(stderrPath, output.stderr, "utf8");
+        if (output.timedOut) {
+            await fs.writeFile(terminationPath, `${JSON.stringify({
+                policy: "max_runtime_seconds",
+                maxRuntimeSeconds,
+                signal: output.signal,
+            }, null, 2)}\n`, "utf8");
         }
-        child.stdout.on("data", (chunk) => {
-            stdout += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-        });
-        child.stderr.on("data", (chunk) => {
-            stderr += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        const stderrFatality = detectFatalGodotStderr({
+            launchKind,
+            exitCode: output.exitCode,
+            stderr: output.stderr,
         });
-        child.on("error", reject);
-        child.on("close", (exitCode, signal) => {
-            if (timeoutHandle !== null) {
-                clearTimeout(timeoutHandle);
-            }
-            if (forceKillHandle !== null) {
-                clearTimeout(forceKillHandle);
-            }
-            resolve({
-                exitCode: exitCode ?? (timedOut ? 0 : 1),
-                signal: signal ?? null,
-                stdout,
-                stderr,
-                timedOut,
+        const timedOutSuccessfully = output.timedOut && !stderrFatality.detected;
+        return {
+            exitCode: output.exitCode,
+            state: timedOutSuccessfully || (!stderrFatality.detected && output.exitCode === 0)
+                ? "passed"
+                : "failed",
+            reasons: stderrFatality.detected && stderrFatality.reason !== null
+                ? [stderrFatality.reason]
+                : timedOutSuccessfully || output.exitCode === 0
+                    ? []
+                    : [`process_exit_${output.exitCode}`],
+            summaryOverride: stderrFatality.summary ??
+                (timedOutSuccessfully
+                    ? `Runtime run stayed alive for ${maxRuntimeSeconds} second(s) and GDH terminated it intentionally.`
+                    : null),
+            artifacts: [
+                {
+                    id: "launch",
+                    path: launchPath,
+                    description: "Assembled launch preview used for the runtime recipe run.",
+                },
+                {
+                    id: "stdout",
+                    path: stdoutPath,
+                    description: "Captured standard output from the runtime recipe process.",
+                },
+                {
+                    id: "stderr",
+                    path: stderrPath,
+                    description: "Captured standard error from the runtime recipe process.",
+                },
+                ...(output.timedOut
+                    ? [
+                        {
+                            id: "termination",
+                            path: terminationPath,
+                            description: "Termination policy artifact for a bounded runtime run stopped by GDH.",
+                        },
+                    ]
+                    : []),
+            ],
+            errorMessage: null,
+        };
+    }
+    finally {
+        await applyLaunchCleanupHints(preview.cleanupHints ?? []).catch(() => { });
+    }
+}
+async function applyLaunchPrepareHints(hints) {
+    for (const hint of hints) {
+        if (hint.kind === "docker_runtime_image") {
+            await ensureDockerRuntimeImagePlan({
+                imageTag: hint.imageTag,
+                platform: hint.platform,
+                source: hint.source,
             });
+        }
+    }
+}
+async function applyLaunchCleanupHints(hints) {
+    for (const hint of hints) {
+        if (hint.kind === "docker_container") {
+            await removeDockerContainer(hint.containerName);
+        }
+    }
+}
+async function removeDockerContainer(containerName) {
+    try {
+        await execFileAsync("docker", ["rm", "-f", containerName], {
+            env: process.env,
+            maxBuffer: 5 * 1024 * 1024,
         });
-    });
-    await fs.writeFile(stdoutPath, output.stdout, "utf8");
-    await fs.writeFile(stderrPath, output.stderr, "utf8");
-    if (output.timedOut) {
-        await fs.writeFile(terminationPath, `${JSON.stringify({
-            policy: "max_runtime_seconds",
-            maxRuntimeSeconds,
-            signal: output.signal,
-        }, null, 2)}\n`, "utf8");
-    }
-    const stderrFatality = detectFatalGodotStderr({
-        launchKind,
-        exitCode: output.exitCode,
-        stderr: output.stderr,
-    });
-    const timedOutSuccessfully = output.timedOut && !stderrFatality.detected;
-    return {
-        exitCode: output.exitCode,
-        state: timedOutSuccessfully || (!stderrFatality.detected && output.exitCode === 0)
-            ? "passed"
-            : "failed",
-        reasons: stderrFatality.detected && stderrFatality.reason !== null
-            ? [stderrFatality.reason]
-            : timedOutSuccessfully || output.exitCode === 0
-                ? []
-                : [`process_exit_${output.exitCode}`],
-        summaryOverride: stderrFatality.summary ??
-            (timedOutSuccessfully
-                ? `Runtime run stayed alive for ${maxRuntimeSeconds} second(s) and GDH terminated it intentionally.`
-                : null),
-        artifacts: [
-            {
-                id: "launch",
-                path: launchPath,
-                description: "Assembled launch preview used for the runtime recipe run.",
-            },
-            {
-                id: "stdout",
-                path: stdoutPath,
-                description: "Captured standard output from the runtime recipe process.",
-            },
-            {
-                id: "stderr",
-                path: stderrPath,
-                description: "Captured standard error from the runtime recipe process.",
-            },
-            ...(output.timedOut
-                ? [
-                    {
-                        id: "termination",
-                        path: terminationPath,
-                        description: "Termination policy artifact for a bounded runtime run stopped by GDH.",
-                    },
-                ]
-                : []),
-        ],
-        errorMessage: null,
-    };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("No such container") ||
+            message.includes("is not running") ||
+            message.includes("Error: No such container")) {
+            return;
+        }
+        throw error;
+    }
 }
 function detectFatalGodotStderr(input) {
     if (input.launchKind !== "godot_project" || input.exitCode !== 0) {
@@ -965,6 +1406,17 @@ function detectFatalGodotStderr(input) {
 const BRIDGE_SESSION_DIRECTORY = ".gdh-state/bridge-sessions";
 const BRIDGE_LAUNCH_HOLD_ITERATIONS = "3600";
 const BRIDGE_HANDSHAKE_TIMEOUT_MS = 30000;
+const HOST_RUNTIME_BRIDGE_ENTRIES = [
+    {
+        id: "state.node_property.await",
+        summary: "Wait for one serializable node property to match an expected value through bounded polling.",
+        kind: "waiter",
+        shape: "composite",
+        source: "core",
+        executionRoute: null,
+        safetyLevel: "read_only",
+    },
+];
 export function createRuntimeBridgeManager() {
     const sessions = new Map();
     return {
@@ -1015,6 +1467,7 @@ export function createRuntimeBridgeManager() {
             const startedAt = new Date().toISOString();
             let startedChild = null;
             let startedSocket = null;
+            let executionLaunchPreview = null;
             try {
                 const executionCheck = await checkRuntimeRecipe({
                     ...input,
@@ -1043,21 +1496,27 @@ export function createRuntimeBridgeManager() {
                         session: null,
                     };
                 }
+                const explicitScreenshotCapture = readExplicitScreenshotCapture(executionCheck.launchPreview);
+                executionLaunchPreview = prepareBridgeSessionLaunchPreview(executionCheck.launchPreview);
+                await ensureExplicitScreenshotCaptureDirectories(explicitScreenshotCapture);
                 await fs.writeFile(launchPath, `${JSON.stringify({
-                    cwd: executionCheck.launchPreview.cwd,
-                    command: executionCheck.launchPreview.command,
-                    env: executionCheck.launchPreview.env,
-                    workspaceMode: executionCheck.launchPreview.workspaceMode,
+                    cwd: executionLaunchPreview.cwd,
+                    command: executionLaunchPreview.command,
+                    env: executionLaunchPreview.env,
+                    workspaceMode: executionLaunchPreview.workspaceMode,
+                    prepareHints: executionLaunchPreview.prepareHints ?? [],
+                    cleanupHints: executionLaunchPreview.cleanupHints ?? [],
                     bridge: {
                         port: bridgePort,
                         sessionId,
                     },
                 }, null, 2)}\n`, "utf8");
-                const child = spawn(executionCheck.launchPreview.command?.[0] ?? "", executionCheck.launchPreview.command?.slice(1) ?? [], {
-                    cwd: executionCheck.launchPreview.cwd ?? undefined,
+                await applyLaunchPrepareHints(executionLaunchPreview.prepareHints ?? []);
+                const child = spawn(executionLaunchPreview.command?.[0] ?? "", executionLaunchPreview.command?.slice(1) ?? [], {
+                    cwd: executionLaunchPreview.cwd ?? undefined,
                     env: {
                         ...process.env,
-                        ...Object.fromEntries(executionCheck.launchPreview.env.map((entry) => [entry.name, entry.value])),
+                        ...Object.fromEntries(executionLaunchPreview.env.map((entry) => [entry.name, entry.value])),
                     },
                     stdio: ["ignore", "pipe", "pipe"],
                 });
@@ -1089,7 +1548,7 @@ export function createRuntimeBridgeManager() {
                     timeoutMs: BRIDGE_HANDSHAKE_TIMEOUT_MS,
                 });
                 startedSocket = ws;
-                const entries = await listBridgeEntriesFromSocket(ws, sessionId);
+                const entries = mergeRuntimeBridgeEntries(await listBridgeEntriesFromSocket(ws, sessionId));
                 const handle = {
                     sessionId,
                     targetPath: input.targetPath,
@@ -1098,7 +1557,7 @@ export function createRuntimeBridgeManager() {
                     workspace,
                     workspaceMode: input.workspaceMode,
                     startedAt,
-                    launchPreview: executionCheck.launchPreview,
+                    launchPreview: executionLaunchPreview,
                     bridgePort,
                     bridgeToken,
                     workingCopyPath: input.workspaceMode === "isolated_copy" ? workspace.workspacePath : null,
@@ -1155,7 +1614,7 @@ export function createRuntimeBridgeManager() {
                         summary: "Runtime bridge session is connected and ready for bounded invocation.",
                         reasons: [],
                     },
-                    launchCommand: executionCheck.launchPreview.command,
+                    launchCommand: executionLaunchPreview.command,
                     session: summarizeBridgeSession(handle),
                 };
             }
@@ -1166,6 +1625,7 @@ export function createRuntimeBridgeManager() {
                 if (startedChild) {
                     startedChild.kill("SIGTERM");
                 }
+                await applyLaunchCleanupHints(executionLaunchPreview?.cleanupHints ?? []).catch(() => { });
                 await workspace.cleanup();
                 return {
                     targetPath: input.targetPath,
@@ -1199,7 +1659,7 @@ export function createRuntimeBridgeManager() {
                     entries: session.entries,
                 };
             }
-            session.entries = await listBridgeEntriesFromSocket(session.ws, sessionId);
+            session.entries = mergeRuntimeBridgeEntries(await listBridgeEntriesFromSocket(session.ws, sessionId));
             return {
                 sessionId,
                 state: "ready",
@@ -1249,6 +1709,26 @@ export function createRuntimeBridgeManager() {
                     entryId,
                     input: inputValue,
                 });
+                const syntheticResponse = await invokeSyntheticBridgeEntry(session, entryId, inputValue);
+                if (syntheticResponse !== null) {
+                    recordBridgeEvent(session, "invoke_response", {
+                        entryId,
+                        state: syntheticResponse.state,
+                        result: syntheticResponse.result,
+                        error: syntheticResponse.error,
+                    });
+                    return {
+                        sessionId,
+                        entryId,
+                        state: syntheticResponse.state,
+                        summary: syntheticResponse.state === "ok"
+                            ? `Bridge entry "${entryId}" completed successfully.`
+                            : `Bridge entry "${entryId}" returned state "${syntheticResponse.state}".`,
+                        reasons: syntheticResponse.error ? [syntheticResponse.error] : [],
+                        result: syntheticResponse.result,
+                        transcriptPath: session.transcriptPath,
+                    };
+                }
                 const response = await invokeBridgeEntryOverSocket(session.ws, sessionId, entryId, inputValue);
                 recordBridgeEvent(session, "invoke_response", {
                     entryId,
@@ -1343,19 +1823,148 @@ async function stopBridgeSessionHandle(session) {
     };
 }
 async function finalizeBridgeSession(session) {
-    const payload = {
-        session: summarizeBridgeSession(session),
-        launch: {
-            cwd: session.launchPreview.cwd,
-            command: session.launchPreview.command,
-            env: session.launchPreview.env,
-            workspaceMode: session.launchPreview.workspaceMode,
+    try {
+        await applyLaunchCleanupHints(session.launchPreview.cleanupHints ?? []);
+    }
+    catch (error) {
+        recordBridgeEvent(session, "cleanup_error", {
+            message: formatBridgeError(error),
+        });
+    }
+    finally {
+        const payload = {
+            session: summarizeBridgeSession(session),
+            launch: {
+                cwd: session.launchPreview.cwd,
+                command: session.launchPreview.command,
+                env: session.launchPreview.env,
+                workspaceMode: session.launchPreview.workspaceMode,
+                prepareHints: session.launchPreview.prepareHints ?? [],
+                cleanupHints: session.launchPreview.cleanupHints ?? [],
+            },
+            transcript: session.transcript,
+        };
+        await fs.mkdir(session.artifactDirectory, { recursive: true });
+        await fs.writeFile(session.transcriptPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+        await session.workspace.cleanup();
+    }
+}
+function mergeRuntimeBridgeEntries(entries) {
+    const merged = [...entries];
+    const presentIds = new Set(entries.map((entry) => entry.id));
+    for (const entry of HOST_RUNTIME_BRIDGE_ENTRIES) {
+        if (!presentIds.has(entry.id)) {
+            merged.push(entry);
+        }
+    }
+    return merged;
+}
+async function invokeSyntheticBridgeEntry(session, entryId, inputValue) {
+    if (entryId === "state.node_property.await") {
+        return invokeNodePropertyAwaitEntry(session, inputValue);
+    }
+    return null;
+}
+async function invokeNodePropertyAwaitEntry(session, inputValue) {
+    const input = toJsonRecord(inputValue);
+    const nodePath = typeof input["nodePath"] === "string" ? input["nodePath"] : "";
+    const property = typeof input["property"] === "string" ? input["property"] : "";
+    const hasExpected = Object.prototype.hasOwnProperty.call(input, "expected");
+    const expected = hasExpected ? input["expected"] : null;
+    const timeoutMs = clampNumber(input["timeoutMs"], 1500, 100, 5000);
+    const pollIntervalMs = clampNumber(input["pollIntervalMs"], 50, 25, 250);
+    if (nodePath.length === 0 || property.length === 0) {
+        return {
+            state: "failed",
+            result: null,
+            error: "state.node_property.await requires nodePath and property.",
+        };
+    }
+    if (!hasExpected) {
+        return {
+            state: "failed",
+            result: null,
+            error: "state.node_property.await requires an expected value.",
+        };
+    }
+    const startedAt = Date.now();
+    let attempts = 0;
+    let lastValue = null;
+    while (Date.now() - startedAt <= timeoutMs) {
+        attempts += 1;
+        recordBridgeEvent(session, "invoke_expanded_leaf_step", {
+            parentEntryId: "state.node_property.await",
+            leafEntryId: "state.node_property.get",
+            attempt: attempts,
+            input: {
+                nodePath,
+                property,
+            },
+        });
+        const response = await invokeBridgeEntryOverSocket(session.ws, session.sessionId, "state.node_property.get", {
+            nodePath,
+            property,
+        });
+        recordBridgeEvent(session, "invoke_expanded_leaf_response", {
+            parentEntryId: "state.node_property.await",
+            leafEntryId: "state.node_property.get",
+            attempt: attempts,
+            state: response.state,
+            result: response.result,
+            error: response.error,
+        });
+        if (response.state !== "ok") {
+            return {
+                state: response.state,
+                result: response.result,
+                error: response.error,
+            };
+        }
+        const payload = toJsonRecord(response.result);
+        lastValue = (payload["value"] ?? null);
+        if (jsonValuesEqual(lastValue, expected)) {
+            return {
+                state: "ok",
+                result: {
+                    nodePath,
+                    property,
+                    expected,
+                    value: lastValue,
+                    attempts,
+                    elapsedMs: Date.now() - startedAt,
+                },
+                error: null,
+            };
+        }
+        await waitMs(pollIntervalMs);
+    }
+    return {
+        state: "unavailable",
+        result: {
+            nodePath,
+            property,
+            expected,
+            value: lastValue,
+            attempts,
+            elapsedMs: Date.now() - startedAt,
         },
-        transcript: session.transcript,
+        error: "Timed out waiting for the requested node property value.",
     };
-    await fs.mkdir(session.artifactDirectory, { recursive: true });
-    await fs.writeFile(session.transcriptPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-    await session.workspace.cleanup();
+}
+function toJsonRecord(value) {
+    if (value === null || Array.isArray(value) || typeof value !== "object") {
+        return {};
+    }
+    return value;
+}
+function clampNumber(value, fallback, minimum, maximum) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.max(minimum, Math.min(maximum, Math.trunc(value)));
+}
+function jsonValuesEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
 }
 function summarizeBridgeSession(session) {
     return {