@skillcap/gdh 0.1.2

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

@@ -0,0 +1,1699 @@
+import { 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 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";
+export { inspectRuntimeBridgeSurface, installRuntimeBridgeSurface, removeRuntimeBridgeSurface, repairRuntimeBridgeSurface, resolveRuntimeBridgeConfig, } from "./bridge-surface.js";
+export const runtimePackage = definePackageBoundary({
+    name: "@gdh/runtime",
+    layer: "capability",
+    responsibility: "Local run adapters, runtime bridge coordination, and runtime readiness surfaces.",
+    allowedInternalDependencies: ["@gdh/core"],
+});
+const PRIMARY_RUN_CONFIGURATION_DIRECTORY = ".gdh/run-configurations";
+const LEGACY_RECIPE_DIRECTORY = ".gdh/recipes";
+export async function listRuntimeRecipes(input) {
+    const context = await loadRuntimeRecipeContext(input);
+    const recipes = context.recipes.map((recipe) => ({
+        id: recipe.id,
+        name: recipe.name,
+        status: recipe.status,
+        projectPath: recipe.projectPath,
+        launchKind: recipe.launch.kind,
+        providers: recipe.providers,
+    }));
+    if (recipes.length === 0) {
+        return {
+            targetPath: input.targetPath,
+            state: "unavailable",
+            summary: input.projectConfig === null
+                ? "Runtime recipes are unavailable because the target has not been onboarded yet."
+                : "No runtime recipes are defined for this target yet.",
+            reasons: input.projectConfig === null
+                ? ["project_not_onboarded", "no_recipes_defined"]
+                : ["no_recipes_defined"],
+            projectConfigPresent: input.projectConfig !== null,
+            recipes,
+        };
+    }
+    return {
+        targetPath: input.targetPath,
+        state: "ready",
+        summary: `Loaded ${recipes.length} runtime recipe(s).`,
+        reasons: [],
+        projectConfigPresent: input.projectConfig !== null,
+        recipes,
+    };
+}
+export async function showRuntimeRecipe(input) {
+    const context = await loadRuntimeRecipeContext(input);
+    const recipe = context.recipes.find((entry) => entry.id === input.recipeId) ?? null;
+    if (recipe === null) {
+        return {
+            targetPath: input.targetPath,
+            state: "unavailable",
+            summary: `Runtime recipe "${input.recipeId}" was not found.`,
+            reasons: ["recipe_not_found"],
+            recipe: null,
+        };
+    }
+    return {
+        targetPath: input.targetPath,
+        state: "ready",
+        summary: `Loaded runtime recipe "${recipe.id}".`,
+        reasons: [],
+        recipe,
+    };
+}
+export async function checkRuntimeRecipe(input) {
+    const context = await loadRuntimeRecipeContext(input);
+    return inspectRuntimeRecipe({
+        ...input,
+        evaluationRootPath: input.targetPath,
+        context,
+    });
+}
+export async function runRuntimeRecipe(input) {
+    const liveCheck = await checkRuntimeRecipe(input);
+    if (liveCheck.state !== "runnable" || liveCheck.recipe === null) {
+        return {
+            version: GDH_RUNTIME_RECIPE_RUN_VERSION,
+            targetPath: input.targetPath,
+            recipeId: input.recipeId,
+            state: "blocked",
+            summary: liveCheck.summary,
+            reasons: liveCheck.reasons,
+            recipe: liveCheck.recipe,
+            check: liveCheck,
+            session: null,
+            startedAt: null,
+            finishedAt: new Date().toISOString(),
+            exitCode: null,
+            launchCommand: liveCheck.launchPreview?.command ?? null,
+            artifacts: [],
+            statusPromotion: "none",
+        };
+    }
+    const workspace = await prepareWorkspace(input.targetPath, input.workspaceMode);
+    try {
+        const executionContext = await loadRuntimeRecipeContext({
+            targetPath: workspace.workspacePath,
+            projectConfig: input.projectConfig,
+        });
+        const executionCheck = await inspectRuntimeRecipe({
+            ...input,
+            evaluationRootPath: workspace.workspacePath,
+            context: executionContext,
+        });
+        if (executionCheck.state !== "runnable" || executionCheck.launchPreview === null) {
+            return {
+                version: GDH_RUNTIME_RECIPE_RUN_VERSION,
+                targetPath: input.targetPath,
+                recipeId: input.recipeId,
+                state: "blocked",
+                summary: executionCheck.summary,
+                reasons: executionCheck.reasons,
+                recipe: executionCheck.recipe,
+                check: executionCheck,
+                session: {
+                    launchMode: "gdh_launch",
+                    workspaceMode: input.workspaceMode,
+                    targetPath: input.targetPath,
+                    workingCopyPath: input.workspaceMode === "isolated_copy" ? workspace.workspacePath : null,
+                },
+                startedAt: null,
+                finishedAt: new Date().toISOString(),
+                exitCode: null,
+                launchCommand: executionCheck.launchPreview?.command ?? null,
+                artifacts: [],
+                statusPromotion: "none",
+            };
+        }
+        const session = {
+            launchMode: "gdh_launch",
+            workspaceMode: input.workspaceMode,
+            targetPath: input.targetPath,
+            workingCopyPath: input.workspaceMode === "isolated_copy" ? workspace.workspacePath : null,
+        };
+        const artifactDirectory = input.artifactDirectory ??
+            (await createRunArtifactDirectory(input.targetPath, `recipe-${input.recipeId}`));
+        await fs.mkdir(artifactDirectory, { recursive: true });
+        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);
+        }
+        catch (error) {
+            execution = {
+                exitCode: 1,
+                state: "failed",
+                reasons: ["launch_process_error"],
+                summaryOverride: null,
+                artifacts: [
+                    {
+                        id: "launch-error",
+                        path: artifactDirectory,
+                        description: `Runtime launch failed before the process exited: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                errorMessage: error instanceof Error ? error.message : String(error),
+            };
+        }
+        const finishedAt = new Date().toISOString();
+        const reportPath = path.join(artifactDirectory, "report.json");
+        const result = {
+            version: GDH_RUNTIME_RECIPE_RUN_VERSION,
+            targetPath: input.targetPath,
+            recipeId: input.recipeId,
+            state: execution.state,
+            summary: execution.summaryOverride ??
+                (execution.state === "passed"
+                    ? `Runtime recipe "${input.recipeId}" ran successfully.`
+                    : execution.errorMessage !== null
+                        ? `Runtime recipe "${input.recipeId}" failed before the process exited: ${execution.errorMessage}.`
+                        : `Runtime recipe "${input.recipeId}" exited with code ${execution.exitCode}.`),
+            reasons: execution.errorMessage !== null
+                ? ["launch_process_error"]
+                : execution.reasons,
+            recipe: executionCheck.recipe,
+            check: executionCheck,
+            session,
+            startedAt,
+            finishedAt,
+            exitCode: execution.exitCode,
+            launchCommand: executionCheck.launchPreview.command,
+            artifacts: [
+                ...execution.artifacts,
+                {
+                    id: "report",
+                    path: reportPath,
+                    description: "Structured runtime recipe report for this execution.",
+                },
+            ],
+            statusPromotion: execution.state === "passed" && executionCheck.recipe?.status === "draft"
+                ? "candidate_observed"
+                : "none",
+        };
+        await fs.writeFile(reportPath, `${JSON.stringify(presentPublicRuntimeTerms(result), null, 2)}\n`, "utf8");
+        return result;
+    }
+    finally {
+        await workspace.cleanup();
+    }
+}
+export async function inspectRuntimeRecipeRunState(result) {
+    const launchArtifactPath = result.artifacts.find((entry) => entry.id === "launch")?.path ?? null;
+    const stdoutArtifactPath = result.artifacts.find((entry) => entry.id === "stdout")?.path ?? null;
+    const stderrArtifactPath = result.artifacts.find((entry) => entry.id === "stderr")?.path ?? null;
+    const reportArtifactPath = result.artifacts.find((entry) => entry.id === "report")?.path ?? null;
+    return [
+        await inspectJsonArtifact({
+            id: "launch",
+            artifactPath: launchArtifactPath,
+            missingSummary: "Launch-preview state was not captured for this recipe run.",
+            invalidSummary: "Launch-preview state exists but is not valid JSON.",
+            availableSummary: "Launch-preview state is available for runtime inspection.",
+        }),
+        await inspectJsonArtifact({
+            id: "stdout_json",
+            artifactPath: stdoutArtifactPath,
+            missingSummary: "Structured stdout state was not captured for this recipe run.",
+            invalidSummary: "Stdout was captured, but it is not valid JSON and cannot be inspected structurally.",
+            availableSummary: "Structured stdout state is available for runtime inspection.",
+        }),
+        await inspectTextArtifact({
+            id: "stdout_text",
+            artifactPath: stdoutArtifactPath,
+            missingSummary: "Stdout text was not captured for this recipe run.",
+            availableSummary: "Stdout text is available for runtime inspection.",
+        }),
+        await inspectJsonArtifact({
+            id: "stderr_json",
+            artifactPath: stderrArtifactPath,
+            missingSummary: "Structured stderr state was not captured for this recipe run.",
+            invalidSummary: "Stderr was captured, but it is not valid JSON and cannot be inspected structurally.",
+            availableSummary: "Structured stderr state is available for runtime inspection.",
+        }),
+        await inspectTextArtifact({
+            id: "stderr_text",
+            artifactPath: stderrArtifactPath,
+            missingSummary: "Stderr text was not captured for this recipe run.",
+            availableSummary: "Stderr text is available for runtime inspection.",
+        }),
+        await inspectJsonArtifact({
+            id: "recipe_report",
+            artifactPath: reportArtifactPath,
+            missingSummary: "Runtime recipe report metadata is missing.",
+            invalidSummary: "Runtime recipe report exists but is not valid JSON.",
+            availableSummary: "Runtime recipe report state is available for inspection.",
+        }),
+    ];
+}
+async function loadRuntimeRecipeContext(input) {
+    return {
+        targetPath: input.targetPath,
+        projectConfig: input.projectConfig,
+        recipes: await readRecipeDefinitions(input.targetPath),
+    };
+}
+async function readRecipeDefinitions(targetPath) {
+    const recipesDirectory = await resolveRuntimeDefinitionDirectory(targetPath, PRIMARY_RUN_CONFIGURATION_DIRECTORY, LEGACY_RECIPE_DIRECTORY);
+    const entries = await fs.readdir(recipesDirectory, { withFileTypes: true }).catch(() => []);
+    const recipeFiles = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".yaml"))
+        .map((entry) => entry.name)
+        .sort();
+    const recipes = [];
+    for (const recipeFile of recipeFiles) {
+        const absolutePath = path.join(recipesDirectory, recipeFile);
+        const content = await fs.readFile(absolutePath, "utf8");
+        recipes.push(parseRecipeDefinition(content));
+    }
+    return recipes;
+}
+function parseRecipeDefinition(content) {
+    const parsed = toRecord(parse(content));
+    const launch = toRecord(parsed["launch"]);
+    const launchKind = readString(launch["kind"]);
+    const parsedVersion = readNumber(parsed["version"]);
+    return {
+        schemaVersion: (parsedVersion <= GDH_RECIPE_SCHEMA_VERSION
+            ? GDH_RECIPE_SCHEMA_VERSION
+            : parsedVersion),
+        id: readString(parsed["id"]),
+        name: readString(parsed["name"]),
+        status: readString(parsed["status"]),
+        draftReason: readNullableString(parsed["draft_reason"]),
+        projectPath: readString(parsed["project_path"]),
+        providers: readStringArray(parsed["providers"], ["local"]),
+        parameters: readObjectArray(parsed["parameters"]).map((entry) => ({
+            id: readString(entry["id"]),
+            summary: readString(entry["summary"]),
+            required: readBoolean(entry["required"], false),
+            defaultValue: readNullableString(entry["default_value"]),
+            argumentTokens: readStringArray(entry["argument_tokens"]),
+            envVarName: readNullableString(entry["env_var_name"]),
+        })),
+        featureFlags: readObjectArray(parsed["feature_flags"]).map((entry) => ({
+            id: readString(entry["id"]),
+            summary: readString(entry["summary"]),
+            enabledByDefault: readBoolean(entry["enabled_by_default"], false),
+            argumentTokens: readStringArray(entry["argument_tokens"]),
+            envVarName: readNullableString(entry["env_var_name"]),
+            envValue: readNullableString(entry["env_value"]),
+        })),
+        environment: readObjectArray(parsed["env"]).map((entry) => ({
+            name: readString(entry["name"]),
+            summary: readString(entry["summary"]),
+            source: readString(entry["source"]),
+            value: readNullableString(entry["value"]),
+            required: readBoolean(entry["required"], false),
+        })),
+        preChecks: readObjectArray(parsed["pre_checks"]).map((entry) => ({
+            id: readString(entry["id"]),
+            kind: readString(entry["kind"]),
+            summary: readString(entry["summary"]),
+            required: readBoolean(entry["required"], true),
+            relativePath: readNullableString(entry["relative_path"]),
+            envVarName: readNullableString(entry["env_var_name"]),
+        })),
+        launch: launchKind === "project_launch_adapter"
+            ? {
+                kind: "project_launch_adapter",
+                scriptPath: readString(launch["script_path"]),
+                interpreter: readNullableString(launch["interpreter"]),
+                arguments: readStringArray(launch["arguments"]),
+                workingDirectory: readNullableString(launch["working_directory"]),
+            }
+            : {
+                kind: "godot_project",
+                scenePath: readString(launch["scene_path"]),
+                entryPointKind: readString(launch["entry_point_kind"]),
+                arguments: readStringArray(launch["arguments"]),
+            },
+        provenance: {
+            source: readString(toRecord(parsed["provenance"])["source"]),
+            observedAt: readString(toRecord(parsed["provenance"])["observed_at"]),
+            evidenceFiles: readStringArray(toRecord(parsed["provenance"])["evidence_files"]),
+            reason: readString(toRecord(parsed["provenance"])["reason"]),
+        },
+    };
+}
+async function resolveRuntimeDefinitionDirectory(targetPath, primaryRelativePath, legacyRelativePath) {
+    const primaryDirectory = path.join(targetPath, primaryRelativePath);
+    if (await directoryExists(primaryDirectory)) {
+        return primaryDirectory;
+    }
+    return path.join(targetPath, legacyRelativePath);
+}
+async function directoryExists(directoryPath) {
+    try {
+        const stats = await fs.stat(directoryPath);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function inspectRuntimeRecipe(input) {
+    const recipe = input.context.recipes.find((entry) => entry.id === input.recipeId) ?? null;
+    if (recipe === null) {
+        return {
+            targetPath: input.targetPath,
+            recipeId: input.recipeId,
+            state: "misconfigured",
+            summary: `Runtime recipe "${input.recipeId}" was not found.`,
+            reasons: ["recipe_not_found"],
+            recipe: null,
+            provider: null,
+            parameters: [],
+            featureFlags: [],
+            environment: [],
+            preChecks: [],
+            bridge: bridgeNotRequired(),
+            launchPreview: null,
+        };
+    }
+    const values = resolveRuntimeValues(recipe, input);
+    const provider = resolveProvider(recipe, input.projectConfig, input.provider);
+    const preChecks = await resolvePrechecks({
+        targetPath: input.targetPath,
+        evaluationRootPath: input.evaluationRootPath,
+        recipe,
+        environment: values.environment,
+    });
+    const launchPreview = await buildLaunchPreview({
+        targetPath: input.targetPath,
+        evaluationRootPath: input.evaluationRootPath,
+        recipe,
+        values,
+        workspaceMode: input.workspaceMode,
+    });
+    const reasons = [
+        ...resolveParameterReasons(values.parameters),
+        ...resolveEnvironmentReasons(values.environment),
+        ...resolvePrecheckReasons(preChecks),
+    ];
+    if (!provider.supported) {
+        reasons.push("provider_not_supported");
+    }
+    const hasMisconfiguration = preChecks.some((entry) => entry.status === "failed" &&
+        (entry.kind === "project_path_exists" ||
+            entry.kind === "godot_project_exists" ||
+            entry.kind === "launch_adapter_exists"));
+    const isBlocked = reasons.length > 0 &&
+        !hasMisconfiguration &&
+        launchPreview !== null &&
+        (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);
+    const state = hasMisconfiguration
+        ? "misconfigured"
+        : isBlocked || launchPreview === null
+            ? "blocked"
+            : "runnable";
+    return {
+        targetPath: input.targetPath,
+        recipeId: recipe.id,
+        state,
+        summary: state === "runnable"
+            ? `Runtime recipe "${recipe.id}" is runnable.`
+            : state === "blocked"
+                ? `Runtime recipe "${recipe.id}" is blocked by environment or input requirements.`
+                : `Runtime recipe "${recipe.id}" is misconfigured.`,
+        reasons,
+        recipe,
+        provider,
+        parameters: values.parameters,
+        featureFlags: values.featureFlags,
+        environment: values.environment,
+        preChecks,
+        bridge: bridgeNotRequired(),
+        launchPreview,
+    };
+}
+function resolveRuntimeValues(recipe, input) {
+    const parameters = recipe.parameters.map((definition) => {
+        const inputValue = input.parameters[definition.id];
+        const value = inputValue ?? definition.defaultValue;
+        return {
+            id: definition.id,
+            summary: definition.summary,
+            status: value === null ? "missing" : "resolved",
+            required: definition.required,
+            value,
+            source: inputValue !== undefined
+                ? "input"
+                : definition.defaultValue !== null
+                    ? "default"
+                    : "missing",
+            argumentTokens: definition.argumentTokens,
+            envVarName: definition.envVarName,
+        };
+    });
+    const featureFlags = recipe.featureFlags.map((definition) => {
+        const explicitlyEnabled = input.enabledFeatures.includes(definition.id);
+        const explicitlyDisabled = input.disabledFeatures.includes(definition.id);
+        const enabled = explicitlyEnabled
+            ? true
+            : explicitlyDisabled
+                ? false
+                : definition.enabledByDefault;
+        return {
+            id: definition.id,
+            summary: definition.summary,
+            enabled,
+            source: explicitlyEnabled || explicitlyDisabled ? "input" : "default",
+            argumentTokens: definition.argumentTokens,
+            envVarName: definition.envVarName,
+            envValue: definition.envValue,
+        };
+    });
+    const parameterEnv = new Map();
+    for (const parameter of parameters) {
+        if (parameter.envVarName !== null && parameter.value !== null) {
+            parameterEnv.set(parameter.envVarName, parameter.value);
+        }
+    }
+    const featureEnv = new Map();
+    for (const featureFlag of featureFlags) {
+        if (featureFlag.enabled &&
+            featureFlag.envVarName !== null &&
+            featureFlag.envValue !== null) {
+            featureEnv.set(featureFlag.envVarName, featureFlag.envValue);
+        }
+    }
+    const environment = recipe.environment.map((definition) => {
+        const inputValue = input.environment[definition.name];
+        if (inputValue !== undefined) {
+            return {
+                name: definition.name,
+                summary: definition.summary,
+                status: "resolved",
+                required: definition.required,
+                value: inputValue,
+                source: "input",
+            };
+        }
+        if (parameterEnv.has(definition.name)) {
+            return {
+                name: definition.name,
+                summary: definition.summary,
+                status: "resolved",
+                required: definition.required,
+                value: parameterEnv.get(definition.name) ?? null,
+                source: "input",
+            };
+        }
+        if (featureEnv.has(definition.name)) {
+            return {
+                name: definition.name,
+                summary: definition.summary,
+                status: "resolved",
+                required: definition.required,
+                value: featureEnv.get(definition.name) ?? null,
+                source: "input",
+            };
+        }
+        if (definition.source === "inline" && definition.value !== null) {
+            return {
+                name: definition.name,
+                summary: definition.summary,
+                status: "resolved",
+                required: definition.required,
+                value: definition.value,
+                source: "inline",
+            };
+        }
+        const processValue = process.env[definition.name];
+        if (definition.source === "process_env" && processValue !== undefined) {
+            return {
+                name: definition.name,
+                summary: definition.summary,
+                status: "resolved",
+                required: definition.required,
+                value: processValue,
+                source: "process_env",
+            };
+        }
+        return {
+            name: definition.name,
+            summary: definition.summary,
+            status: "missing",
+            required: definition.required,
+            value: null,
+            source: "missing",
+        };
+    });
+    for (const [name, value] of parameterEnv.entries()) {
+        if (environment.some((entry) => entry.name === name)) {
+            continue;
+        }
+        environment.push({
+            name,
+            summary: `Derived from recipe parameter "${name}".`,
+            status: "resolved",
+            required: false,
+            value,
+            source: "input",
+        });
+    }
+    for (const [name, value] of featureEnv.entries()) {
+        if (environment.some((entry) => entry.name === name)) {
+            continue;
+        }
+        environment.push({
+            name,
+            summary: `Derived from recipe feature flag "${name}".`,
+            status: "resolved",
+            required: false,
+            value,
+            source: "input",
+        });
+    }
+    for (const [name, rawValue] of Object.entries(input.environment)) {
+        if (environment.some((entry) => entry.name === name)) {
+            continue;
+        }
+        environment.push({
+            name,
+            summary: `Provided as an explicit runtime environment override for "${name}".`,
+            status: "resolved",
+            required: false,
+            value: rawValue,
+            source: "input",
+        });
+    }
+    return {
+        parameters,
+        featureFlags,
+        environment,
+    };
+}
+function resolveProvider(recipe, projectConfig, requestedProvider) {
+    const allowedProviders = projectConfig?.allowedProviders ?? ["local"];
+    const declaredProviders = recipe.providers.length > 0 ? recipe.providers : ["local"];
+    const resolved = requestedProvider ?? declaredProviders[0] ?? null;
+    const supported = resolved !== null &&
+        allowedProviders.includes(resolved) &&
+        declaredProviders.includes(resolved);
+    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.`,
+    };
+}
+async function resolvePrechecks(input) {
+    const results = [];
+    const environmentMap = new Map(input.environment
+        .filter((entry) => entry.value !== null)
+        .map((entry) => [entry.name, entry.value ?? ""]));
+    for (const definition of input.recipe.preChecks) {
+        if (definition.kind === "project_path_exists") {
+            const absolutePath = path.join(input.evaluationRootPath, definition.relativePath ?? input.recipe.projectPath);
+            const exists = await pathExists(absolutePath);
+            results.push({
+                ...definition,
+                status: exists ? "passed" : "failed",
+                reason: exists ? null : "project_path_missing",
+            });
+            continue;
+        }
+        if (definition.kind === "godot_project_exists") {
+            const projectRelativePath = definition.relativePath ?? input.recipe.projectPath;
+            const absolutePath = path.join(input.evaluationRootPath, projectRelativePath, "project.godot");
+            const exists = await pathExists(absolutePath);
+            results.push({
+                ...definition,
+                status: exists ? "passed" : "failed",
+                reason: exists ? null : "project_godot_missing",
+            });
+            continue;
+        }
+        if (definition.kind === "godot_editor_configured") {
+            const configured = Boolean(await resolveConfiguredGodotEditorBin({
+                targetPath: input.targetPath,
+                environmentOverride: environmentMap.get("GDH_GODOT_EDITOR_BIN") ?? null,
+                environment: process.env,
+            }));
+            results.push({
+                ...definition,
+                status: configured ? "passed" : "failed",
+                reason: configured ? null : "godot_editor_not_configured",
+            });
+            continue;
+        }
+        if (definition.kind === "launch_adapter_exists") {
+            const relativePath = definition.relativePath ??
+                (input.recipe.launch.kind === "project_launch_adapter"
+                    ? input.recipe.launch.scriptPath
+                    : null);
+            const exists = relativePath === null
+                ? false
+                : await pathExists(path.join(input.evaluationRootPath, relativePath));
+            results.push({
+                ...definition,
+                relativePath,
+                status: exists ? "passed" : "failed",
+                reason: exists ? null : "launch_adapter_missing",
+            });
+            continue;
+        }
+        const envValue = definition.envVarName === null
+            ? null
+            : environmentMap.get(definition.envVarName) ??
+                process.env[definition.envVarName] ??
+                null;
+        results.push({
+            ...definition,
+            status: envValue === null ? "failed" : "passed",
+            reason: envValue === null ? "environment_value_missing" : null,
+        });
+    }
+    return results;
+}
+async function buildLaunchPreview(input) {
+    const parameterArguments = input.values.parameters.flatMap((entry) => entry.value === null ? [] : [...entry.argumentTokens, entry.value]);
+    const featureArguments = input.values.featureFlags.flatMap((entry) => entry.enabled ? entry.argumentTokens : []);
+    const environmentMap = new Map(input.values.environment
+        .filter((entry) => entry.value !== null)
+        .map((entry) => [entry.name, entry.value ?? ""]));
+    for (const parameter of input.values.parameters) {
+        if (parameter.envVarName !== null && parameter.value !== null) {
+            environmentMap.set(parameter.envVarName, parameter.value);
+        }
+    }
+    for (const featureFlag of input.values.featureFlags) {
+        if (featureFlag.enabled &&
+            featureFlag.envVarName !== null &&
+            featureFlag.envValue !== null) {
+            environmentMap.set(featureFlag.envVarName, featureFlag.envValue);
+        }
+    }
+    const environment = [...environmentMap.entries()].map(([name, value]) => ({
+        name,
+        value,
+    }));
+    if (input.recipe.launch.kind === "godot_project") {
+        const godotBin = await resolveConfiguredGodotEditorBin({
+            targetPath: input.targetPath,
+            environmentOverride: environmentMap.get("GDH_GODOT_EDITOR_BIN") ?? null,
+            environment: process.env,
+        });
+        if (godotBin === null) {
+            return null;
+        }
+        const projectDirectory = path.join(input.evaluationRootPath, input.recipe.projectPath);
+        return {
+            command: [
+                godotBin,
+                "--path",
+                projectDirectory,
+                input.recipe.launch.scenePath,
+                ...input.recipe.launch.arguments,
+                ...parameterArguments,
+                ...featureArguments,
+            ],
+            cwd: projectDirectory,
+            env: environment,
+            workspaceMode: input.workspaceMode,
+        };
+    }
+    const scriptPath = path.join(input.evaluationRootPath, input.recipe.launch.scriptPath);
+    const command = input.recipe.launch.interpreter === null
+        ? [
+            scriptPath,
+            ...input.recipe.launch.arguments,
+            ...parameterArguments,
+            ...featureArguments,
+        ]
+        : [
+            input.recipe.launch.interpreter,
+            scriptPath,
+            ...input.recipe.launch.arguments,
+            ...parameterArguments,
+            ...featureArguments,
+        ];
+    return {
+        command,
+        cwd: path.join(input.evaluationRootPath, input.recipe.launch.workingDirectory ?? input.recipe.projectPath),
+        env: environment,
+        workspaceMode: input.workspaceMode,
+    };
+}
+function bridgeNotRequired() {
+    return {
+        required: false,
+        state: "not_required",
+        summary: "Recipe execution alone does not require the runtime bridge yet. Bridge readiness becomes relevant once scenarios and runtime assertions run above this layer.",
+        reasons: [],
+    };
+}
+function resolveParameterReasons(parameters) {
+    return parameters
+        .filter((entry) => entry.required && entry.status === "missing")
+        .map((entry) => `missing_parameter:${entry.id}`);
+}
+function resolveEnvironmentReasons(environment) {
+    return environment
+        .filter((entry) => entry.required && entry.status === "missing")
+        .map((entry) => `missing_environment:${entry.name}`);
+}
+function resolvePrecheckReasons(preChecks) {
+    return preChecks
+        .filter((entry) => entry.required && entry.status === "failed")
+        .map((entry) => `${entry.kind}:${entry.reason ?? "failed"}`);
+}
+async function prepareWorkspace(targetPath, workspaceMode) {
+    if (workspaceMode === "live_workspace") {
+        return {
+            workspacePath: targetPath,
+            cleanup: async () => { },
+        };
+    }
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "gdh-run-"));
+    const workspacePath = path.join(tempRoot, path.basename(targetPath));
+    await fs.cp(targetPath, workspacePath, {
+        recursive: true,
+        verbatimSymlinks: true,
+        filter: async (sourcePath) => {
+            const relativePath = path.relative(targetPath, sourcePath);
+            if (relativePath === "") {
+                return true;
+            }
+            const segments = relativePath.split(path.sep);
+            return !segments.includes(".gdh-state") && !segments.includes(".git");
+        },
+    });
+    return {
+        workspacePath,
+        cleanup: async () => {
+            await fs.rm(tempRoot, { recursive: true, force: true });
+        },
+    };
+}
+async function createRunArtifactDirectory(targetPath, recipeId) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const directory = path.join(targetPath, ".gdh-state/runs", `${timestamp}-${recipeId}`);
+    await fs.mkdir(directory, { recursive: true });
+    return directory;
+}
+async function executeCommand(preview, artifactDirectory, launchKind, maxRuntimeSeconds) {
+    const command = preview.command;
+    if (command === null || command.length === 0) {
+        throw new Error("Cannot execute a runtime recipe without a launch command.");
+    }
+    const stdoutPath = path.join(artifactDirectory, "stdout.log");
+    const stderrPath = path.join(artifactDirectory, "stderr.log");
+    const launchPath = path.join(artifactDirectory, "launch.json");
+    const terminationPath = path.join(artifactDirectory, "termination.json");
+    await fs.writeFile(launchPath, `${JSON.stringify({
+        cwd: preview.cwd,
+        command,
+        env: preview.env,
+        workspaceMode: preview.workspaceMode,
+    }, 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"],
+        });
+        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,
+            });
+        });
+    });
+    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,
+    };
+}
+function detectFatalGodotStderr(input) {
+    if (input.launchKind !== "godot_project" || input.exitCode !== 0) {
+        return {
+            detected: false,
+            reason: null,
+            summary: null,
+        };
+    }
+    const stderr = input.stderr.trim();
+    if (stderr.length === 0) {
+        return {
+            detected: false,
+            reason: null,
+            summary: null,
+        };
+    }
+    const fatalPatterns = [
+        /^\s*SCRIPT ERROR:/m,
+        /^\s*ERROR:/m,
+        /Failed loading resource/i,
+        /Parse Error:/i,
+    ];
+    if (!fatalPatterns.some((pattern) => pattern.test(stderr))) {
+        return {
+            detected: false,
+            reason: null,
+            summary: null,
+        };
+    }
+    return {
+        detected: true,
+        reason: "godot_stderr_fatal_error_detected",
+        summary: "Runtime run exited with code 0 but emitted fatal Godot errors to stderr.",
+    };
+}
+const BRIDGE_SESSION_DIRECTORY = ".gdh-state/bridge-sessions";
+const BRIDGE_LAUNCH_HOLD_ITERATIONS = "3600";
+const BRIDGE_HANDSHAKE_TIMEOUT_MS = 15000;
+export function createRuntimeBridgeManager() {
+    const sessions = new Map();
+    return {
+        async startSession(input) {
+            const liveCheck = await checkRuntimeRecipe(input);
+            if (liveCheck.state !== "runnable" || liveCheck.recipe === null || liveCheck.launchPreview === null) {
+                return {
+                    targetPath: input.targetPath,
+                    recipeId: input.recipeId,
+                    state: liveCheck.state === "blocked" ? "blocked" : "failed",
+                    summary: liveCheck.summary,
+                    reasons: liveCheck.reasons,
+                    bridge: bridgeMissing("Runtime bridge session start requires a runnable run configuration."),
+                    launchCommand: liveCheck.launchPreview?.command ?? null,
+                    session: null,
+                };
+            }
+            if (liveCheck.recipe.launch.kind === "godot_project") {
+                const bridgeStatus = await inspectRuntimeBridgeSurface({
+                    targetPath: input.targetPath,
+                    projectConfig: input.projectConfig,
+                });
+                if (bridgeStatus.state !== "ready") {
+                    return {
+                        targetPath: input.targetPath,
+                        recipeId: input.recipeId,
+                        state: "blocked",
+                        summary: "Runtime bridge session start is blocked until the project-side GDH bridge is installed and healthy for direct Godot launches.",
+                        reasons: [
+                            "runtime_bridge_surface_not_ready",
+                            ...bridgeStatus.reasons,
+                        ],
+                        bridge: bridgeMissing(bridgeStatus.summary),
+                        launchCommand: liveCheck.launchPreview.command,
+                        session: null,
+                    };
+                }
+            }
+            const sessionId = buildBridgeSessionId(input.recipeId);
+            const workspace = await prepareWorkspace(input.targetPath, input.workspaceMode);
+            const artifactDirectory = await createBridgeArtifactDirectory(input.targetPath, input.recipeId, sessionId);
+            const bridgePort = await reserveTcpPort();
+            const bridgeToken = randomBytes(24).toString("hex");
+            const launchPath = path.join(artifactDirectory, "launch.json");
+            const transcriptPath = path.join(artifactDirectory, "bridge-transcript.json");
+            const stdoutPath = path.join(artifactDirectory, "stdout.log");
+            const stderrPath = path.join(artifactDirectory, "stderr.log");
+            const startedAt = new Date().toISOString();
+            let startedChild = null;
+            let startedSocket = null;
+            try {
+                const executionCheck = await checkRuntimeRecipe({
+                    ...input,
+                    targetPath: workspace.workspacePath,
+                    environment: {
+                        ...input.environment,
+                        GDH_BRIDGE_ENABLED: "1",
+                        GDH_BRIDGE_PORT: String(bridgePort),
+                        GDH_BRIDGE_TOKEN: bridgeToken,
+                        GDH_BRIDGE_SESSION_ID: sessionId,
+                        GDH_BRIDGE_HOLD_ITERATIONS: BRIDGE_LAUNCH_HOLD_ITERATIONS,
+                    },
+                });
+                if (executionCheck.state !== "runnable" ||
+                    executionCheck.recipe === null ||
+                    executionCheck.launchPreview === null) {
+                    await workspace.cleanup();
+                    return {
+                        targetPath: input.targetPath,
+                        recipeId: input.recipeId,
+                        state: executionCheck.state === "blocked" ? "blocked" : "failed",
+                        summary: executionCheck.summary,
+                        reasons: executionCheck.reasons,
+                        bridge: bridgeMissing("Runtime bridge session start could not assemble a runnable launch preview."),
+                        launchCommand: executionCheck.launchPreview?.command ?? null,
+                        session: null,
+                    };
+                }
+                await fs.writeFile(launchPath, `${JSON.stringify({
+                    cwd: executionCheck.launchPreview.cwd,
+                    command: executionCheck.launchPreview.command,
+                    env: executionCheck.launchPreview.env,
+                    workspaceMode: executionCheck.launchPreview.workspaceMode,
+                    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,
+                    env: {
+                        ...process.env,
+                        ...Object.fromEntries(executionCheck.launchPreview.env.map((entry) => [entry.name, entry.value])),
+                    },
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                startedChild = child;
+                const stdoutChunks = [];
+                const stderrChunks = [];
+                child.stdout.on("data", (chunk) => {
+                    const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+                    stdoutChunks.push(text);
+                    void fs.appendFile(stdoutPath, text, "utf8");
+                });
+                child.stderr.on("data", (chunk) => {
+                    const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+                    stderrChunks.push(text);
+                    void fs.appendFile(stderrPath, text, "utf8");
+                });
+                const exitCode = { value: null };
+                const exitPromise = new Promise((resolve, reject) => {
+                    child.on("error", reject);
+                    child.on("close", (code) => {
+                        exitCode.value = code ?? 1;
+                        resolve(exitCode.value);
+                    });
+                });
+                const ws = await connectBridgeSocket({
+                    port: bridgePort,
+                    token: bridgeToken,
+                    sessionId,
+                    timeoutMs: BRIDGE_HANDSHAKE_TIMEOUT_MS,
+                });
+                startedSocket = ws;
+                const entries = await listBridgeEntriesFromSocket(ws, sessionId);
+                const handle = {
+                    sessionId,
+                    targetPath: input.targetPath,
+                    recipeId: input.recipeId,
+                    artifactDirectory,
+                    workspace,
+                    workspaceMode: input.workspaceMode,
+                    startedAt,
+                    launchPreview: executionCheck.launchPreview,
+                    bridgePort,
+                    bridgeToken,
+                    workingCopyPath: input.workspaceMode === "isolated_copy" ? workspace.workspacePath : null,
+                    child,
+                    stdoutPath,
+                    stderrPath,
+                    transcriptPath,
+                    launchPath,
+                    stdoutChunks,
+                    stderrChunks,
+                    transcript: [],
+                    exitPromise,
+                    exitCode,
+                    ws,
+                    entries,
+                    state: "ready",
+                    finishedAt: null,
+                    invocationBusy: false,
+                };
+                recordBridgeEvent(handle, "session_started", {
+                    bridgePort,
+                    entryCount: entries.length,
+                });
+                sessions.set(sessionId, handle);
+                child.on("close", () => {
+                    if (handle.state !== "closed") {
+                        handle.state = "closed";
+                        handle.finishedAt = new Date().toISOString();
+                        recordBridgeEvent(handle, "process_closed", {
+                            exitCode: handle.exitCode.value,
+                        });
+                        void finalizeBridgeSession(handle);
+                    }
+                });
+                ws.on("close", () => {
+                    if (handle.state !== "closed" && handle.exitCode.value === null) {
+                        recordBridgeEvent(handle, "socket_closed", {});
+                    }
+                });
+                ws.on("error", (error) => {
+                    recordBridgeEvent(handle, "socket_error", {
+                        message: error.message,
+                    });
+                });
+                return {
+                    targetPath: input.targetPath,
+                    recipeId: input.recipeId,
+                    state: "ready",
+                    summary: `Runtime bridge session "${sessionId}" is ready.`,
+                    reasons: [],
+                    bridge: {
+                        required: true,
+                        state: "ready",
+                        summary: "Runtime bridge session is connected and ready for bounded invocation.",
+                        reasons: [],
+                    },
+                    launchCommand: executionCheck.launchPreview.command,
+                    session: summarizeBridgeSession(handle),
+                };
+            }
+            catch (error) {
+                if (startedSocket && startedSocket.readyState === WebSocket.OPEN) {
+                    startedSocket.close();
+                }
+                if (startedChild) {
+                    startedChild.kill("SIGTERM");
+                }
+                await workspace.cleanup();
+                return {
+                    targetPath: input.targetPath,
+                    recipeId: input.recipeId,
+                    state: "failed",
+                    summary: `Runtime bridge session start failed: ${formatBridgeError(error)}.`,
+                    reasons: ["bridge_start_failed"],
+                    bridge: bridgeMissing(formatBridgeError(error)),
+                    launchCommand: liveCheck.launchPreview.command,
+                    session: null,
+                };
+            }
+        },
+        async listEntries(sessionId) {
+            const session = sessions.get(sessionId) ?? null;
+            if (session === null) {
+                return {
+                    sessionId,
+                    state: "missing",
+                    summary: `Runtime bridge session "${sessionId}" was not found.`,
+                    reasons: ["bridge_session_not_found"],
+                    entries: [],
+                };
+            }
+            if (session.state !== "ready") {
+                return {
+                    sessionId,
+                    state: "missing",
+                    summary: `Runtime bridge session "${sessionId}" is no longer active.`,
+                    reasons: ["bridge_session_not_active"],
+                    entries: session.entries,
+                };
+            }
+            session.entries = await listBridgeEntriesFromSocket(session.ws, sessionId);
+            return {
+                sessionId,
+                state: "ready",
+                summary: `Loaded ${session.entries.length} bridge entr${session.entries.length === 1 ? "y" : "ies"} for session "${sessionId}".`,
+                reasons: [],
+                entries: session.entries,
+            };
+        },
+        async invokeEntry(sessionId, entryId, inputValue) {
+            const session = sessions.get(sessionId) ?? null;
+            if (session === null) {
+                return {
+                    sessionId,
+                    entryId,
+                    state: "unavailable",
+                    summary: `Runtime bridge session "${sessionId}" was not found.`,
+                    reasons: ["bridge_session_not_found"],
+                    result: null,
+                    transcriptPath: null,
+                };
+            }
+            if (session.state !== "ready") {
+                return {
+                    sessionId,
+                    entryId,
+                    state: "unavailable",
+                    summary: `Runtime bridge session "${sessionId}" is no longer active.`,
+                    reasons: ["bridge_session_not_active"],
+                    result: null,
+                    transcriptPath: session.transcriptPath,
+                };
+            }
+            if (session.invocationBusy) {
+                return {
+                    sessionId,
+                    entryId,
+                    state: "busy",
+                    summary: `Runtime bridge session "${sessionId}" is already handling another invocation.`,
+                    reasons: ["bridge_session_busy"],
+                    result: null,
+                    transcriptPath: session.transcriptPath,
+                };
+            }
+            session.invocationBusy = true;
+            try {
+                recordBridgeEvent(session, "invoke_request", {
+                    entryId,
+                    input: inputValue,
+                });
+                const response = await invokeBridgeEntryOverSocket(session.ws, sessionId, entryId, inputValue);
+                recordBridgeEvent(session, "invoke_response", {
+                    entryId,
+                    state: response.state,
+                    result: response.result,
+                    error: response.error,
+                });
+                return {
+                    sessionId,
+                    entryId,
+                    state: response.state,
+                    summary: response.state === "ok"
+                        ? `Bridge entry "${entryId}" completed successfully.`
+                        : `Bridge entry "${entryId}" returned state "${response.state}".`,
+                    reasons: response.error ? [response.error] : [],
+                    result: response.result,
+                    transcriptPath: session.transcriptPath,
+                };
+            }
+            catch (error) {
+                recordBridgeEvent(session, "invoke_error", {
+                    entryId,
+                    message: formatBridgeError(error),
+                });
+                return {
+                    sessionId,
+                    entryId,
+                    state: "failed",
+                    summary: `Bridge entry "${entryId}" failed: ${formatBridgeError(error)}.`,
+                    reasons: ["bridge_invoke_failed"],
+                    result: null,
+                    transcriptPath: session.transcriptPath,
+                };
+            }
+            finally {
+                session.invocationBusy = false;
+            }
+        },
+        async stopSession(sessionId) {
+            const session = sessions.get(sessionId) ?? null;
+            if (session === null) {
+                return {
+                    sessionId,
+                    state: "missing",
+                    summary: `Runtime bridge session "${sessionId}" was not found.`,
+                    reasons: ["bridge_session_not_found"],
+                    session: null,
+                    transcriptPath: null,
+                    exitCode: null,
+                };
+            }
+            sessions.delete(sessionId);
+            return stopBridgeSessionHandle(session);
+        },
+        async stopAll() {
+            const activeSessions = [...sessions.values()];
+            sessions.clear();
+            await Promise.all(activeSessions.map((session) => stopBridgeSessionHandle(session)));
+        },
+    };
+}
+async function stopBridgeSessionHandle(session) {
+    session.state = "closed";
+    recordBridgeEvent(session, "session_stop_requested", {});
+    if (session.ws.readyState === WebSocket.OPEN || session.ws.readyState === WebSocket.CONNECTING) {
+        session.ws.close();
+    }
+    if (session.exitCode.value === null) {
+        session.child.kill("SIGTERM");
+        const exited = await Promise.race([
+            session.exitPromise,
+            waitMs(2000).then(() => null),
+        ]);
+        if (exited === null) {
+            session.child.kill("SIGKILL");
+            await session.exitPromise;
+        }
+    }
+    session.finishedAt = new Date().toISOString();
+    recordBridgeEvent(session, "session_stopped", {
+        exitCode: session.exitCode.value,
+    });
+    await finalizeBridgeSession(session);
+    return {
+        sessionId: session.sessionId,
+        state: "stopped",
+        summary: `Runtime bridge session "${session.sessionId}" stopped.`,
+        reasons: [],
+        session: summarizeBridgeSession(session),
+        transcriptPath: session.transcriptPath,
+        exitCode: session.exitCode.value,
+    };
+}
+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,
+        },
+        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 summarizeBridgeSession(session) {
+    return {
+        sessionId: session.sessionId,
+        targetPath: session.targetPath,
+        recipeId: session.recipeId,
+        state: session.state,
+        startedAt: session.startedAt,
+        finishedAt: session.finishedAt,
+        workspaceMode: session.workspaceMode,
+        workingCopyPath: session.workingCopyPath,
+        artifactDirectory: session.artifactDirectory,
+        entries: session.entries,
+    };
+}
+function recordBridgeEvent(session, event, payload) {
+    session.transcript.push({
+        recordedAt: new Date().toISOString(),
+        event,
+        ...payload,
+    });
+}
+function bridgeMissing(reason) {
+    return {
+        required: true,
+        state: "missing",
+        summary: "Runtime bridge is required for this operation but is not available.",
+        reasons: [reason],
+    };
+}
+function buildBridgeSessionId(recipeId) {
+    return `${new Date().toISOString().replace(/[:.]/g, "-")}-${recipeId}`;
+}
+function waitMs(delayMs) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, delayMs);
+    });
+}
+function bridgeDataToString(data) {
+    if (typeof data === "string") {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return Buffer.from(data).toString("utf8");
+    }
+    if (Array.isArray(data)) {
+        return Buffer.concat(data.map((entry) => Buffer.from(entry))).toString("utf8");
+    }
+    return Buffer.from(data).toString("utf8");
+}
+async function createBridgeArtifactDirectory(targetPath, recipeId, sessionId) {
+    const directory = path.join(targetPath, BRIDGE_SESSION_DIRECTORY, `${sessionId}-${recipeId}`);
+    await fs.mkdir(directory, { recursive: true });
+    return directory;
+}
+async function reserveTcpPort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : null;
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                if (port === null) {
+                    reject(new Error("Failed to reserve a dynamic TCP port for the runtime bridge."));
+                    return;
+                }
+                resolve(port);
+            });
+        });
+    });
+}
+async function connectBridgeSocket(input) {
+    const deadline = Date.now() + input.timeoutMs;
+    let lastError = null;
+    while (Date.now() < deadline) {
+        try {
+            return await attemptBridgeSocketConnection(input);
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            lastError = failure;
+            const codeCandidate = failure;
+            const code = typeof codeCandidate.code === "string" ? codeCandidate.code : null;
+            const retryable = code === "ECONNREFUSED" ||
+                code === "ECONNRESET" ||
+                code === "ENOENT" ||
+                failure.message.includes("socket hang up");
+            if (!retryable && !failure.message.includes("Timed out waiting")) {
+                throw failure;
+            }
+            await waitMs(100);
+        }
+    }
+    throw new Error(lastError?.message ??
+        "Timed out waiting for the runtime bridge WebSocket handshake.");
+}
+async function attemptBridgeSocketConnection(input) {
+    return new Promise((resolve, reject) => {
+        const socket = new WebSocket(`ws://127.0.0.1:${input.port}`);
+        const timeout = setTimeout(() => {
+            socket.close();
+            reject(new Error("Timed out waiting for the runtime bridge WebSocket handshake."));
+        }, Math.min(1000, input.timeoutMs));
+        socket.once("error", (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        socket.once("open", () => {
+            socket.send(JSON.stringify({
+                kind: "hello",
+                session_id: input.sessionId,
+                token: input.token,
+            }));
+        });
+        socket.on("message", (data) => {
+            try {
+                const parsed = JSON.parse(bridgeDataToString(data));
+                if (parsed.kind === "hello_ok") {
+                    clearTimeout(timeout);
+                    socket.removeAllListeners("message");
+                    socket.gdhEntries =
+                        parsed.entries ?? [];
+                    resolve(socket);
+                    return;
+                }
+                if (parsed.kind === "error") {
+                    clearTimeout(timeout);
+                    socket.close();
+                    reject(new Error(parsed.error ?? "Runtime bridge handshake failed."));
+                }
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                socket.close();
+                reject(error);
+            }
+        });
+    });
+}
+async function listBridgeEntriesFromSocket(socket, sessionId) {
+    const cachedEntries = socket.gdhEntries ??
+        null;
+    if (cachedEntries !== null) {
+        return cachedEntries;
+    }
+    const response = await sendBridgeRequest(socket, {
+        kind: "list_entries",
+        request_id: `${sessionId}-list-${randomBytes(8).toString("hex")}`,
+    });
+    const entries = response.result ?? [];
+    socket.gdhEntries = entries;
+    return entries;
+}
+async function invokeBridgeEntryOverSocket(socket, sessionId, entryId, input) {
+    const response = await sendBridgeRequest(socket, {
+        kind: "invoke",
+        request_id: `${sessionId}-invoke-${randomBytes(8).toString("hex")}`,
+        entry_id: entryId,
+        input,
+    });
+    return {
+        state: normalizeBridgeInvocationState(response.state),
+        result: response.result ?? null,
+        error: response.error ?? null,
+    };
+}
+async function sendBridgeRequest(socket, payload) {
+    const requestId = String(payload["request_id"] ?? "");
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            socket.off("message", onMessage);
+            socket.off("error", onError);
+            socket.off("close", onClose);
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onClose = () => {
+            cleanup();
+            reject(new Error("Runtime bridge socket closed while waiting for a response."));
+        };
+        const onMessage = (data) => {
+            try {
+                const parsed = JSON.parse(bridgeDataToString(data));
+                if (parsed.kind !== "response" || parsed.request_id !== requestId) {
+                    return;
+                }
+                cleanup();
+                resolve({
+                    state: parsed.state ?? "failed",
+                    result: parsed.result ?? null,
+                    error: parsed.error ?? null,
+                });
+            }
+            catch (error) {
+                cleanup();
+                reject(error);
+            }
+        };
+        socket.on("message", onMessage);
+        socket.once("error", onError);
+        socket.once("close", onClose);
+        socket.send(JSON.stringify(payload), (error) => {
+            if (error) {
+                cleanup();
+                reject(error);
+            }
+        });
+    });
+}
+function normalizeBridgeInvocationState(value) {
+    if (value === "ok" ||
+        value === "unavailable" ||
+        value === "busy" ||
+        value === "failed" ||
+        value === "cancelled") {
+        return value;
+    }
+    return "failed";
+}
+function formatBridgeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function inspectJsonArtifact(input) {
+    if (input.artifactPath === null) {
+        return {
+            id: input.id,
+            state: "missing",
+            summary: input.missingSummary,
+            artifactPath: null,
+            value: null,
+        };
+    }
+    const content = await fs.readFile(input.artifactPath, "utf8").catch(() => null);
+    if (content === null) {
+        return {
+            id: input.id,
+            state: "missing",
+            summary: input.missingSummary,
+            artifactPath: input.artifactPath,
+            value: null,
+        };
+    }
+    try {
+        return {
+            id: input.id,
+            state: "available",
+            summary: input.availableSummary,
+            artifactPath: input.artifactPath,
+            value: JSON.parse(content),
+        };
+    }
+    catch {
+        return {
+            id: input.id,
+            state: "invalid",
+            summary: input.invalidSummary,
+            artifactPath: input.artifactPath,
+            value: null,
+        };
+    }
+}
+async function inspectTextArtifact(input) {
+    if (input.artifactPath === null) {
+        return {
+            id: input.id,
+            state: "missing",
+            summary: input.missingSummary,
+            artifactPath: null,
+            value: null,
+        };
+    }
+    const content = await fs.readFile(input.artifactPath, "utf8").catch(() => null);
+    if (content === null) {
+        return {
+            id: input.id,
+            state: "missing",
+            summary: input.missingSummary,
+            artifactPath: input.artifactPath,
+            value: null,
+        };
+    }
+    return {
+        id: input.id,
+        state: "available",
+        summary: input.availableSummary,
+        artifactPath: input.artifactPath,
+        value: content,
+    };
+}
+async function pathExists(targetPath) {
+    return fs
+        .access(targetPath)
+        .then(() => true)
+        .catch(() => false);
+}
+function toRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function readString(value) {
+    if (typeof value !== "string") {
+        return "";
+    }
+    return value;
+}
+function readNullableString(value) {
+    return typeof value === "string" ? value : null;
+}
+function readNumber(value) {
+    return typeof value === "number" ? value : Number.parseInt(readString(value), 10);
+}
+function readBoolean(value, fallback) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    return fallback;
+}
+function readStringArray(value, fallback = []) {
+    if (!Array.isArray(value)) {
+        return fallback;
+    }
+    return value
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry);
+}
+function readObjectArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((entry) => toRecord(entry));
+}
+//# sourceMappingURL=index.js.map