@skillcap/gdh 0.13.2 → 0.14.0

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

@@ -90,7 +90,8 @@ export async function checkRuntimeRecipe(input) {
     });
 }
 export async function runRuntimeRecipe(input) {
-    const screenshotRequested = input.screenshotPolicy === "fallback";
+    const screenshotCapture = resolveRuntimeScreenshotCapture(input);
+    const screenshotRequested = screenshotCapture === "rendered";
     const liveCheck = await checkRuntimeRecipe(input);
     if (liveCheck.state !== "runnable" || liveCheck.recipe === null) {
         return {
@@ -161,7 +162,7 @@ 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 preparedScreenshot = buildRuntimeScreenshotCapture(executionCheck.launchPreview, artifactDirectory, screenshotCapture);
         const startedAt = new Date().toISOString();
         let execution = null;
         try {
@@ -786,12 +787,23 @@ async function buildLaunchPreview(input) {
     }));
     const environmentEntries = new Map(environment.map((entry) => [entry.name, entry.value]));
     if (input.provider.resolved === DOCKER_RUNTIME_PROVIDER) {
+        const dockerGodotProjectRecipe = input.recipe.launch.kind === "godot_project"
+            ? input.recipe
+            : null;
+        const dockerGodotProjectLaunch = dockerGodotProjectRecipe === null
+            ? null
+            : await prepareDockerGodotProjectLaunch({
+                evaluationRootPath: input.evaluationRootPath,
+                recipe: dockerGodotProjectRecipe,
+            });
         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,
+                "--audio-driver",
+                "Dummy",
+                dockerGodotProjectLaunch?.scenePath ?? input.recipe.launch.scenePath,
                 ...input.recipe.launch.arguments,
                 ...parameterArguments,
                 ...featureArguments,
@@ -817,6 +829,8 @@ async function buildLaunchPreview(input) {
             command: dockerCommand,
             environment: environmentEntries,
             workspaceMode: input.workspaceMode,
+            extraDockerArgs: dockerGodotProjectLaunch?.extraDockerArgs ?? [],
+            extraCleanupHints: dockerGodotProjectLaunch?.cleanupHints ?? [],
         });
     }
     if (input.recipe.launch.kind === "godot_project") {
@@ -870,6 +884,143 @@ async function buildLaunchPreview(input) {
         cleanupHints: [],
     };
 }
+async function prepareDockerGodotProjectLaunch(input) {
+    const projectDirectory = path.join(input.evaluationRootPath, input.recipe.projectPath);
+    const projectGodotPath = path.join(projectDirectory, "project.godot");
+    const extensionListPath = path.join(projectDirectory, ".godot", "extension_list.cfg");
+    const needsUidResolution = input.recipe.launch.scenePath.startsWith("uid://");
+    const projectGodotContent = await fs.readFile(projectGodotPath, "utf8").catch(() => null);
+    const extensionListContent = await fs.readFile(extensionListPath, "utf8").catch(() => null);
+    const projectNeedsAutoloadUidRepair = projectGodotContent !== null && projectGodotContent.includes("uid://");
+    if (!needsUidResolution &&
+        !projectNeedsAutoloadUidRepair &&
+        (extensionListContent === null || !extensionListContent.includes("res://temp/"))) {
+        return {
+            scenePath: input.recipe.launch.scenePath,
+            extraDockerArgs: [],
+            cleanupHints: [],
+        };
+    }
+    const uidLookup = needsUidResolution || projectNeedsAutoloadUidRepair
+        ? await collectRuntimeUidLookup(projectDirectory)
+        : new Map();
+    const resolvedScenePath = uidLookup.get(input.recipe.launch.scenePath) ?? input.recipe.launch.scenePath;
+    const sanitizedProjectGodot = projectGodotContent === null
+        ? null
+        : sanitizeProjectGodotAutoloadUids(projectGodotContent, uidLookup);
+    const sanitizedExtensionList = extensionListContent === null
+        ? null
+        : sanitizeDockerExtensionList(extensionListContent);
+    const needsProjectGodotOverlay = projectGodotContent !== null && sanitizedProjectGodot !== projectGodotContent;
+    const needsExtensionListOverlay = extensionListContent !== null && sanitizedExtensionList !== extensionListContent;
+    if (!needsProjectGodotOverlay && !needsExtensionListOverlay) {
+        return {
+            scenePath: resolvedScenePath,
+            extraDockerArgs: [],
+            cleanupHints: [],
+        };
+    }
+    const overlayRoot = await fs.mkdtemp(path.join(os.tmpdir(), "gdh-docker-overlay-"));
+    const extraDockerArgs = [];
+    if (needsProjectGodotOverlay && sanitizedProjectGodot !== null) {
+        const overlayProjectGodotPath = path.join(overlayRoot, "project.godot");
+        await fs.writeFile(overlayProjectGodotPath, sanitizedProjectGodot, "utf8");
+        extraDockerArgs.push("--mount", `type=bind,src=${overlayProjectGodotPath},dst=${toDockerContainerPath(input.evaluationRootPath, projectGodotPath)},readonly`);
+    }
+    if (needsExtensionListOverlay && sanitizedExtensionList !== null) {
+        const overlayExtensionListPath = path.join(overlayRoot, ".godot", "extension_list.cfg");
+        await fs.mkdir(path.dirname(overlayExtensionListPath), { recursive: true });
+        await fs.writeFile(overlayExtensionListPath, sanitizedExtensionList, "utf8");
+        extraDockerArgs.push("--mount", `type=bind,src=${overlayExtensionListPath},dst=${toDockerContainerPath(input.evaluationRootPath, extensionListPath)},readonly`);
+    }
+    return {
+        scenePath: resolvedScenePath,
+        extraDockerArgs,
+        cleanupHints: [
+            {
+                kind: "temporary_path",
+                path: overlayRoot,
+            },
+        ],
+    };
+}
+async function collectRuntimeUidLookup(projectDirectory) {
+    const lookup = new Map();
+    async function walk(currentPath) {
+        const entries = await fs.readdir(currentPath, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const absolutePath = path.join(currentPath, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === ".git" || entry.name === ".gdh-state") {
+                    continue;
+                }
+                await walk(absolutePath);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith(".uid")) {
+                continue;
+            }
+            const uid = await fs.readFile(absolutePath, "utf8").catch(() => null);
+            if (uid === null) {
+                continue;
+            }
+            const normalizedUid = uid.trim();
+            if (!normalizedUid.startsWith("uid://")) {
+                continue;
+            }
+            const relativePath = path.relative(projectDirectory, absolutePath).split(path.sep).join("/");
+            lookup.set(normalizedUid, `res://${relativePath.slice(0, -".uid".length)}`);
+        }
+    }
+    await walk(projectDirectory);
+    return lookup;
+}
+function sanitizeProjectGodotAutoloadUids(content, uidLookup) {
+    const lines = content.split(/\r?\n/);
+    const section = findProjectSettingSection(lines, "autoload");
+    if (section === null) {
+        return content;
+    }
+    const nextLines = [...lines];
+    for (let index = section.start + 1; index < section.end; index += 1) {
+        const line = lines[index] ?? "";
+        const match = /^(\s*[^=\s]+)\s*=\s*"(\*?)(uid:\/\/[^"]+)"\s*$/.exec(line);
+        if (match === null) {
+            continue;
+        }
+        const key = match[1] ?? "";
+        const prefix = match[2] ?? "";
+        const uid = match[3] ?? "";
+        const resolvedPath = uidLookup.get(uid) ?? null;
+        if (resolvedPath === null) {
+            continue;
+        }
+        nextLines[index] = `${key}="${prefix}${resolvedPath}"`;
+    }
+    return `${nextLines.join("\n").replace(/\n+$/, "\n")}`;
+}
+function sanitizeDockerExtensionList(content) {
+    const nextLines = content
+        .split(/\r?\n/)
+        .filter((line) => !line.startsWith("res://temp/"));
+    return `${nextLines.join("\n").replace(/\n+$/, "\n")}`;
+}
+function findProjectSettingSection(lines, name) {
+    const header = `[${name}]`;
+    const start = lines.findIndex((line) => line.trim() === header);
+    if (start < 0) {
+        return null;
+    }
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const line = lines[index]?.trim() ?? "";
+        if (line.startsWith("[") && line.endsWith("]")) {
+            end = index;
+            break;
+        }
+    }
+    return { start, end };
+}
 function bridgeNotRequired() {
     return {
         required: false,
@@ -927,8 +1078,8 @@ async function createRunArtifactDirectory(targetPath, recipeId) {
     await fs.mkdir(directory, { recursive: true });
     return directory;
 }
-function buildRuntimeScreenshotCapture(preview, artifactDirectory, screenshotPolicy) {
-    if (screenshotPolicy !== "fallback") {
+function buildRuntimeScreenshotCapture(preview, artifactDirectory, screenshotCapture) {
+    if (screenshotCapture !== "rendered") {
         return {
             preview,
             result: buildOmittedRuntimeScreenshotResult(),
@@ -1206,6 +1357,16 @@ function buildUnavailableRuntimeScreenshotResult(summary, reason) {
         metadataPath: null,
     };
 }
+function resolveRuntimeScreenshotCapture(input) {
+    if (input.screenshotCapture === "rendered") {
+        return "rendered";
+    }
+    if (input.screenshotCapture === "never") {
+        return "never";
+    }
+    const legacyScreenshotPolicy = input.screenshotPolicy;
+    return legacyScreenshotPolicy === "fallback" ? "rendered" : "never";
+}
 async function executeCommand(preview, artifactDirectory, launchKind, maxRuntimeSeconds) {
     const command = preview.command;
     if (command === null || command.length === 0) {
@@ -1353,6 +1514,10 @@ async function applyLaunchCleanupHints(hints) {
     for (const hint of hints) {
         if (hint.kind === "docker_container") {
             await removeDockerContainer(hint.containerName);
+            continue;
+        }
+        if (hint.kind === "temporary_path") {
+            await fs.rm(hint.path, { recursive: true, force: true });
         }
     }
 }
@@ -1376,6 +1541,7 @@ async function removeDockerContainer(containerName) {
 const BRIDGE_SESSION_DIRECTORY = ".gdh-state/bridge-sessions";
 const BRIDGE_LAUNCH_HOLD_ITERATIONS = "3600";
 const BRIDGE_HANDSHAKE_TIMEOUT_MS = 30000;
+const BRIDGE_DOCKER_HANDSHAKE_TIMEOUT_MS = 90000;
 const HOST_RUNTIME_BRIDGE_ENTRIES = [
     {
         id: "state.node_property.await",
@@ -1386,6 +1552,24 @@ const HOST_RUNTIME_BRIDGE_ENTRIES = [
         executionRoute: null,
         safetyLevel: "read_only",
     },
+    {
+        id: "state.node_presence.await",
+        summary: "Wait for one exact node path to become present or absent through bounded polling.",
+        kind: "waiter",
+        shape: "composite",
+        source: "core",
+        executionRoute: null,
+        safetyLevel: "read_only",
+    },
+    {
+        id: "state.signal.await",
+        summary: "Wait for one observed signal emission to occur after an optional observed-count baseline.",
+        kind: "waiter",
+        shape: "composite",
+        source: "core",
+        executionRoute: null,
+        safetyLevel: "read_only",
+    },
 ];
 export function createRuntimeBridgeManager() {
     const sessions = new Map();
@@ -1515,7 +1699,9 @@ export function createRuntimeBridgeManager() {
                     port: bridgePort,
                     token: bridgeToken,
                     sessionId,
-                    timeoutMs: BRIDGE_HANDSHAKE_TIMEOUT_MS,
+                    timeoutMs: executionCheck.provider?.resolved === DOCKER_RUNTIME_PROVIDER
+                        ? BRIDGE_DOCKER_HANDSHAKE_TIMEOUT_MS
+                        : BRIDGE_HANDSHAKE_TIMEOUT_MS,
                 });
                 startedSocket = ws;
                 const entries = mergeRuntimeBridgeEntries(await listBridgeEntriesFromSocket(ws, sessionId));
@@ -1648,6 +1834,7 @@ export function createRuntimeBridgeManager() {
                     summary: `Runtime bridge session "${sessionId}" was not found.`,
                     reasons: ["bridge_session_not_found"],
                     result: null,
+                    waiterEvidence: null,
                     transcriptPath: null,
                 };
             }
@@ -1659,6 +1846,7 @@ export function createRuntimeBridgeManager() {
                     summary: `Runtime bridge session "${sessionId}" is no longer active.`,
                     reasons: ["bridge_session_not_active"],
                     result: null,
+                    waiterEvidence: null,
                     transcriptPath: session.transcriptPath,
                 };
             }
@@ -1670,6 +1858,7 @@ export function createRuntimeBridgeManager() {
                     summary: `Runtime bridge session "${sessionId}" is already handling another invocation.`,
                     reasons: ["bridge_session_busy"],
                     result: null,
+                    waiterEvidence: null,
                     transcriptPath: session.transcriptPath,
                 };
             }
@@ -1696,6 +1885,7 @@ export function createRuntimeBridgeManager() {
                             : `Bridge entry "${entryId}" returned state "${syntheticResponse.state}".`,
                         reasons: syntheticResponse.error ? [syntheticResponse.error] : [],
                         result: syntheticResponse.result,
+                        waiterEvidence: syntheticResponse.waiterEvidence,
                         transcriptPath: session.transcriptPath,
                     };
                 }
@@ -1715,6 +1905,7 @@ export function createRuntimeBridgeManager() {
                         : `Bridge entry "${entryId}" returned state "${response.state}".`,
                     reasons: response.error ? [response.error] : [],
                     result: response.result,
+                    waiterEvidence: null,
                     transcriptPath: session.transcriptPath,
                 };
             }
@@ -1730,6 +1921,7 @@ export function createRuntimeBridgeManager() {
                     summary: `Bridge entry "${entryId}" failed: ${formatBridgeError(error)}.`,
                     reasons: ["bridge_invoke_failed"],
                     result: null,
+                    waiterEvidence: null,
                     transcriptPath: session.transcriptPath,
                 };
             }
@@ -1833,6 +2025,12 @@ async function invokeSyntheticBridgeEntry(session, entryId, inputValue) {
     if (entryId === "state.node_property.await") {
         return invokeNodePropertyAwaitEntry(session, inputValue);
     }
+    if (entryId === "state.node_presence.await") {
+        return invokeNodePresenceAwaitEntry(session, inputValue);
+    }
+    if (entryId === "state.signal.await") {
+        return invokeSignalAwaitEntry(session, inputValue);
+    }
     return null;
 }
 async function invokeNodePropertyAwaitEntry(session, inputValue) {
@@ -1848,6 +2046,7 @@ async function invokeNodePropertyAwaitEntry(session, inputValue) {
             state: "failed",
             result: null,
             error: "state.node_property.await requires nodePath and property.",
+            waiterEvidence: null,
         };
     }
     if (!hasExpected) {
@@ -1855,12 +2054,20 @@ async function invokeNodePropertyAwaitEntry(session, inputValue) {
             state: "failed",
             result: null,
             error: "state.node_property.await requires an expected value.",
+            waiterEvidence: null,
         };
     }
-    const startedAt = Date.now();
+    const target = {
+        nodePath,
+        property,
+        expected,
+    };
+    const startedAt = new Date().toISOString();
+    const startedAtMs = Date.now();
+    recordWaiterStarted(session, "state.node_property.await", target, timeoutMs, pollIntervalMs);
     let attempts = 0;
     let lastValue = null;
-    while (Date.now() - startedAt <= timeoutMs) {
+    while (Date.now() - startedAtMs <= timeoutMs) {
         attempts += 1;
         recordBridgeEvent(session, "invoke_expanded_leaf_step", {
             parentEntryId: "state.node_property.await",
@@ -1888,37 +2095,326 @@ async function invokeNodePropertyAwaitEntry(session, inputValue) {
                 state: response.state,
                 result: response.result,
                 error: response.error,
+                waiterEvidence: null,
             };
         }
         const payload = toJsonRecord(response.result);
         lastValue = (payload["value"] ?? null);
         if (jsonValuesEqual(lastValue, expected)) {
+            const result = {
+                nodePath,
+                property,
+                expected,
+                value: lastValue,
+                attempts,
+                elapsedMs: Date.now() - startedAtMs,
+            };
+            const waiterEvidence = buildWaiterEvidence({
+                waiterId: "state.node_property.await",
+                outcome: "satisfied",
+                startedAt,
+                timeoutMs,
+                pollCount: attempts,
+                target,
+                result,
+            });
+            recordWaiterSatisfied(session, "state.node_property.await", target, attempts, result);
             return {
                 state: "ok",
-                result: {
-                    nodePath,
-                    property,
-                    expected,
-                    value: lastValue,
-                    attempts,
-                    elapsedMs: Date.now() - startedAt,
-                },
+                result,
                 error: null,
+                waiterEvidence,
             };
         }
         await waitMs(pollIntervalMs);
     }
+    const result = {
+        nodePath,
+        property,
+        expected,
+        value: lastValue,
+        attempts,
+        elapsedMs: Date.now() - startedAtMs,
+    };
+    const waiterEvidence = buildWaiterEvidence({
+        waiterId: "state.node_property.await",
+        outcome: "timed_out",
+        startedAt,
+        timeoutMs,
+        pollCount: attempts,
+        target,
+        result,
+    });
+    recordWaiterTimedOut(session, "state.node_property.await", target, attempts, result);
     return {
         state: "unavailable",
-        result: {
+        result,
+        error: "Timed out waiting for the requested node property value.",
+        waiterEvidence,
+    };
+}
+async function invokeNodePresenceAwaitEntry(session, inputValue) {
+    const input = toJsonRecord(inputValue);
+    const nodePath = typeof input["nodePath"] === "string" ? input["nodePath"] : "";
+    const expected = typeof input["expected"] === "string" ? input["expected"] : "";
+    const timeoutMs = clampNumber(input["timeoutMs"], 1500, 100, 5000);
+    const pollIntervalMs = clampNumber(input["pollIntervalMs"], 50, 25, 250);
+    if (nodePath.length === 0) {
+        return {
+            state: "failed",
+            result: null,
+            error: "state.node_presence.await requires nodePath.",
+            waiterEvidence: null,
+        };
+    }
+    if (expected !== "present" && expected !== "absent") {
+        return {
+            state: "failed",
+            result: null,
+            error: 'state.node_presence.await requires expected = "present" or "absent".',
+            waiterEvidence: null,
+        };
+    }
+    const target = {
+        nodePath,
+        expected,
+    };
+    recordWaiterStarted(session, "state.node_presence.await", target, timeoutMs, pollIntervalMs);
+    const startedAt = new Date().toISOString();
+    const startedAtMs = Date.now();
+    let attempts = 0;
+    let lastSnapshot = null;
+    while (Date.now() - startedAtMs <= timeoutMs) {
+        attempts += 1;
+        recordBridgeEvent(session, "invoke_expanded_leaf_step", {
+            parentEntryId: "state.node_presence.await",
+            leafEntryId: "state.node_presence.get",
+            attempt: attempts,
+            input: {
+                nodePath,
+            },
+        });
+        const response = await invokeBridgeEntryOverSocket(session.ws, session.sessionId, "state.node_presence.get", {
             nodePath,
-            property,
-            expected,
-            value: lastValue,
-            attempts,
-            elapsedMs: Date.now() - startedAt,
+        });
+        recordBridgeEvent(session, "invoke_expanded_leaf_response", {
+            parentEntryId: "state.node_presence.await",
+            leafEntryId: "state.node_presence.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,
+                waiterEvidence: null,
+            };
+        }
+        const payload = toJsonRecord(response.result);
+        lastSnapshot = payload;
+        const present = payload["present"] === true;
+        const matches = expected === "present" ? present : !present;
+        if (matches) {
+            const result = {
+                nodePath,
+                expected,
+                present,
+                name: (payload["name"] ?? null),
+                className: (payload["className"] ?? null),
+                attempts,
+                elapsedMs: Date.now() - startedAtMs,
+            };
+            const waiterEvidence = buildWaiterEvidence({
+                waiterId: "state.node_presence.await",
+                outcome: "satisfied",
+                startedAt,
+                timeoutMs,
+                pollCount: attempts,
+                target,
+                result,
+            });
+            recordWaiterSatisfied(session, "state.node_presence.await", target, attempts, result);
+            return {
+                state: "ok",
+                result,
+                error: null,
+                waiterEvidence,
+            };
+        }
+        await waitMs(pollIntervalMs);
+    }
+    const result = {
+        nodePath,
+        expected,
+        present: lastSnapshot?.["present"] === true,
+        name: (lastSnapshot?.["name"] ?? null),
+        className: (lastSnapshot?.["className"] ?? null),
+        attempts,
+        elapsedMs: Date.now() - startedAtMs,
+    };
+    const waiterEvidence = buildWaiterEvidence({
+        waiterId: "state.node_presence.await",
+        outcome: "timed_out",
+        startedAt,
+        timeoutMs,
+        pollCount: attempts,
+        target,
+        result,
+    });
+    recordWaiterTimedOut(session, "state.node_presence.await", target, attempts, result);
+    return {
+        state: "unavailable",
+        result,
+        error: "Timed out waiting for the requested node presence state.",
+        waiterEvidence,
+    };
+}
+async function invokeSignalAwaitEntry(session, inputValue) {
+    const input = toJsonRecord(inputValue);
+    const nodePath = typeof input["nodePath"] === "string" ? input["nodePath"] : "";
+    const signalName = typeof input["signalName"] === "string" ? input["signalName"] : "";
+    const afterCount = clampCount(input["afterCount"], 0);
+    const timeoutMs = clampNumber(input["timeoutMs"], 1500, 100, 5000);
+    const pollIntervalMs = clampNumber(input["pollIntervalMs"], 50, 25, 250);
+    if (nodePath.length === 0 || signalName.length === 0) {
+        return {
+            state: "failed",
+            result: null,
+            error: "state.signal.await requires nodePath and signalName.",
+            waiterEvidence: null,
+        };
+    }
+    const target = {
+        nodePath,
+        signalName,
+        afterCount,
+    };
+    recordWaiterStarted(session, "state.signal.await", target, timeoutMs, pollIntervalMs);
+    recordBridgeEvent(session, "invoke_expanded_leaf_step", {
+        parentEntryId: "state.signal.await",
+        leafEntryId: "state.signal_observation.start",
+        attempt: 1,
+        input: {
+            nodePath,
+            signalName,
         },
-        error: "Timed out waiting for the requested node property value.",
+    });
+    const startResponse = await invokeBridgeEntryOverSocket(session.ws, session.sessionId, "state.signal_observation.start", {
+        nodePath,
+        signalName,
+    });
+    recordBridgeEvent(session, "invoke_expanded_leaf_response", {
+        parentEntryId: "state.signal.await",
+        leafEntryId: "state.signal_observation.start",
+        attempt: 1,
+        state: startResponse.state,
+        result: startResponse.result,
+        error: startResponse.error,
+    });
+    if (startResponse.state !== "ok") {
+        return {
+            state: startResponse.state,
+            result: startResponse.result,
+            error: startResponse.error,
+            waiterEvidence: null,
+        };
+    }
+    const startedAt = new Date().toISOString();
+    const startedAtMs = Date.now();
+    let attempts = 0;
+    let lastSnapshot = null;
+    while (Date.now() - startedAtMs <= timeoutMs) {
+        attempts += 1;
+        recordBridgeEvent(session, "invoke_expanded_leaf_step", {
+            parentEntryId: "state.signal.await",
+            leafEntryId: "state.signal_observation.get",
+            attempt: attempts,
+            input: {
+                nodePath,
+                signalName,
+            },
+        });
+        const response = await invokeBridgeEntryOverSocket(session.ws, session.sessionId, "state.signal_observation.get", {
+            nodePath,
+            signalName,
+        });
+        recordBridgeEvent(session, "invoke_expanded_leaf_response", {
+            parentEntryId: "state.signal.await",
+            leafEntryId: "state.signal_observation.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,
+                waiterEvidence: null,
+            };
+        }
+        const payload = toJsonRecord(response.result);
+        lastSnapshot = payload;
+        const count = clampCount(payload["count"], 0);
+        if (count > afterCount) {
+            const result = {
+                nodePath,
+                signalName,
+                afterCount,
+                count,
+                lastObservedAt: (payload["lastObservedAt"] ?? null),
+                lastPayload: (payload["lastPayload"] ?? null),
+                attempts,
+                elapsedMs: Date.now() - startedAtMs,
+            };
+            const waiterEvidence = buildWaiterEvidence({
+                waiterId: "state.signal.await",
+                outcome: "satisfied",
+                startedAt,
+                timeoutMs,
+                pollCount: attempts,
+                target,
+                result,
+            });
+            recordWaiterSatisfied(session, "state.signal.await", target, attempts, result);
+            return {
+                state: "ok",
+                result,
+                error: null,
+                waiterEvidence,
+            };
+        }
+        await waitMs(pollIntervalMs);
+    }
+    const result = {
+        nodePath,
+        signalName,
+        afterCount,
+        count: clampCount(lastSnapshot?.["count"], 0),
+        lastObservedAt: (lastSnapshot?.["lastObservedAt"] ?? null),
+        lastPayload: (lastSnapshot?.["lastPayload"] ?? null),
+        attempts,
+        elapsedMs: Date.now() - startedAtMs,
+    };
+    const waiterEvidence = buildWaiterEvidence({
+        waiterId: "state.signal.await",
+        outcome: "timed_out",
+        startedAt,
+        timeoutMs,
+        pollCount: attempts,
+        target,
+        result,
+    });
+    recordWaiterTimedOut(session, "state.signal.await", target, attempts, result);
+    return {
+        state: "unavailable",
+        result,
+        error: "Timed out waiting for the requested signal emission.",
+        waiterEvidence,
     };
 }
 function toJsonRecord(value) {
@@ -1933,6 +2429,12 @@ function clampNumber(value, fallback, minimum, maximum) {
     }
     return Math.max(minimum, Math.min(maximum, Math.trunc(value)));
 }
+function clampCount(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.max(0, Math.trunc(value));
+}
 function jsonValuesEqual(left, right) {
     return JSON.stringify(left) === JSON.stringify(right);
 }
@@ -1957,6 +2459,42 @@ function recordBridgeEvent(session, event, payload) {
         ...payload,
     });
 }
+function recordWaiterStarted(session, entryId, target, timeoutMs, pollIntervalMs) {
+    recordBridgeEvent(session, "invoke_waiter_started", {
+        entryId,
+        target,
+        timeoutMs,
+        pollIntervalMs,
+    });
+}
+function recordWaiterSatisfied(session, entryId, target, attempts, result) {
+    recordBridgeEvent(session, "invoke_waiter_satisfied", {
+        entryId,
+        target,
+        attempts,
+        result,
+    });
+}
+function recordWaiterTimedOut(session, entryId, target, attempts, result) {
+    recordBridgeEvent(session, "invoke_waiter_timed_out", {
+        entryId,
+        target,
+        attempts,
+        result,
+    });
+}
+function buildWaiterEvidence(input) {
+    return {
+        waiterId: input.waiterId,
+        outcome: input.outcome,
+        startedAt: input.startedAt,
+        finishedAt: new Date().toISOString(),
+        timeoutMs: input.timeoutMs,
+        pollCount: input.pollCount,
+        target: input.target,
+        result: input.result,
+    };
+}
 function bridgeMissing(reason) {
     return {
         required: true,