modwright 0.1.0

package/dist/core/bridge/cet-log.js

@@ -0,0 +1,362 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { bridgeDoneSchema, bridgeHeartbeatSchema, bridgeResultSchema } from "./types.js";
+import { HEARTBEAT_FRESH_MS } from "./locate.js";
+import { bridgeFileNames, cetModDir } from "./paths.js";
+import { pollBudgetMs, POLL_INTERVAL_MS, readCompleteResult } from "./poll.js";
+export const CET_RESULT_TAG = "[MODWRIGHT-RESULT]";
+export const CET_DONE_TAG = "[MODWRIGHT-DONE]";
+export const CET_HEARTBEAT_TAG = "[MODWRIGHT-HEARTBEAT]";
+export const CET_LOG_HEARTBEAT_FRESH_MS = 45_000;
+export const CET_LOG_TAIL_BYTES = 512 * 1024;
+const CET_LINE_TIMESTAMP = /\[(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}) UTC([+-]\d{2}:\d{2})\]/;
+function cetPluginDir(install, surface) {
+    const cet = surface?.logs?.(install).find((source) => source.id === "cet");
+    if (cet?.path)
+        return path.dirname(cet.path);
+    return path.join(install.root, "bin", "x64", "plugins", "cyber_engine_tweaks");
+}
+export const CET_MOD_LOG_FALLBACK = "ModWrightBridge.log";
+export async function cetLogCandidates(install, surface) {
+    const dir = cetPluginDir(install, surface);
+    const modDir = cetModDir(install);
+    return [
+        ...(await modLogsIn(modDir)),
+        path.join(dir, "cyber_engine_tweaks.log"),
+        path.join(dir, "gamelog.log"),
+    ];
+}
+async function modLogsIn(modDir) {
+    let names;
+    try {
+        names = await fs.readdir(modDir);
+    }
+    catch {
+        return [path.join(modDir, CET_MOD_LOG_FALLBACK)];
+    }
+    const logs = [];
+    for (const name of names) {
+        if (!name.toLowerCase().endsWith(".log"))
+            continue;
+        const file = path.join(modDir, name);
+        try {
+            logs.push({ file, mtimeMs: (await fs.stat(file)).mtimeMs });
+        }
+        catch {
+            continue;
+        }
+    }
+    if (logs.length === 0)
+        return [path.join(modDir, CET_MOD_LOG_FALLBACK)];
+    return logs.sort((a, b) => b.mtimeMs - a.mtimeMs).map((l) => l.file);
+}
+export async function readLogTail(absPath, maxBytes = CET_LOG_TAIL_BYTES) {
+    let handle;
+    try {
+        handle = await fs.open(absPath, "r");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const { size } = await handle.stat();
+        const start = Math.max(0, size - maxBytes);
+        const length = size - start;
+        const buffer = Buffer.alloc(length);
+        if (length > 0)
+            await handle.read(buffer, 0, length, start);
+        const text = buffer.toString("utf8");
+        return start > 0 ? text.slice(text.indexOf("\n") + 1) : text;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function parseLineTimestamp(line) {
+    const match = line.match(CET_LINE_TIMESTAMP);
+    if (!match)
+        return undefined;
+    const parsed = new Date(`${match[1]}T${match[2]}${match[3]}`);
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+const TAGS = [
+    { tag: "result", text: CET_RESULT_TAG },
+    { tag: "done", text: CET_DONE_TAG },
+    { tag: "heartbeat", text: CET_HEARTBEAT_TAG },
+];
+export function scanCetLog(text, file) {
+    const entries = [];
+    const lines = text.split(/\r?\n/);
+    for (const line of lines) {
+        let best;
+        for (const candidate of TAGS) {
+            const at = line.indexOf(`${candidate.text} `);
+            if (at >= 0 && (best === undefined || at < best.at))
+                best = { tag: candidate.tag, at, text: candidate.text };
+        }
+        if (!best)
+            continue;
+        const json = line.slice(best.at + best.text.length + 1);
+        if (json === "")
+            continue;
+        const at = parseLineTimestamp(line.slice(0, best.at));
+        entries.push({
+            tag: best.tag,
+            json,
+            bytes: Buffer.byteLength(json, "utf8"),
+            ...(at ? { at } : {}),
+            file,
+            index: entries.length,
+        });
+    }
+    return entries;
+}
+function olderThanArm(entry, armedAt) {
+    if (!armedAt || !entry.at)
+        return false;
+    return entry.at.getTime() < armedAt.getTime() - 1000;
+}
+export function cetCapabilities(heartbeat) {
+    for (const entry of heartbeat.writeRootErrors ?? []) {
+        const at = entry.indexOf("capabilities: ");
+        if (at < 0)
+            continue;
+        try {
+            const parsed = JSON.parse(entry.slice(at + "capabilities: ".length));
+            if (parsed && typeof parsed === "object")
+                return parsed;
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+export function cetSandboxIo(heartbeat) {
+    const caps = cetCapabilities(heartbeat);
+    const io = caps?.["io"];
+    if (typeof io === "boolean")
+        return io;
+    if (heartbeat.writeRoot && heartbeat.writeRoot !== "log-only")
+        return true;
+    return undefined;
+}
+export async function findCetResult(files, match, deps = {}) {
+    const readTail = deps.readTail ?? ((absPath) => readLogTail(absPath));
+    let incomplete;
+    for (const file of files) {
+        const text = await readTail(file);
+        if (text === undefined)
+            continue;
+        const entries = scanCetLog(text, file);
+        const dones = entries.filter((e) => e.tag === "done");
+        for (const entry of entries) {
+            if (entry.tag !== "result" || olderThanArm(entry, match.armedAt))
+                continue;
+            let parsed;
+            try {
+                parsed = bridgeResultSchema.safeParse(JSON.parse(entry.json));
+            }
+            catch {
+                parsed = undefined;
+            }
+            const done = dones.find((d) => {
+                if (d.index <= entry.index)
+                    return false;
+                try {
+                    const marker = bridgeDoneSchema.parse(JSON.parse(d.json));
+                    return marker.id === match.id && marker.nonce === match.nonce;
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (!done) {
+                if (parsed?.success && parsed.data.id === match.id && parsed.data.nonce === match.nonce) {
+                    incomplete ??= { status: "incomplete", reason: "no-done-marker", file, actualBytes: entry.bytes };
+                }
+                continue;
+            }
+            const marker = bridgeDoneSchema.parse(JSON.parse(done.json));
+            if (marker.bytes !== entry.bytes) {
+                incomplete = { status: "incomplete", reason: "truncated", file, expectedBytes: marker.bytes, actualBytes: entry.bytes };
+                continue;
+            }
+            if (!parsed?.success) {
+                incomplete = { status: "incomplete", reason: "truncated", file, expectedBytes: marker.bytes, actualBytes: entry.bytes };
+                continue;
+            }
+            if (parsed.data.id !== match.id || parsed.data.nonce !== match.nonce)
+                continue;
+            return { status: "complete", result: parsed.data, file };
+        }
+    }
+    return incomplete ?? { status: "absent" };
+}
+export async function readCetHeartbeat(files, deps = {}) {
+    const readTail = deps.readTail ?? ((absPath) => readLogTail(absPath));
+    let newest;
+    let newestAt = Number.NEGATIVE_INFINITY;
+    for (const file of files) {
+        const text = await readTail(file);
+        if (text === undefined)
+            continue;
+        for (const entry of scanCetLog(text, file)) {
+            if (entry.tag !== "heartbeat")
+                continue;
+            let parsed;
+            try {
+                parsed = bridgeHeartbeatSchema.safeParse(JSON.parse(entry.json));
+            }
+            catch {
+                continue;
+            }
+            if (!parsed.success)
+                continue;
+            const at = Date.parse(parsed.data.at);
+            if (Number.isNaN(at) || at < newestAt)
+                continue;
+            newestAt = at;
+            newest = { heartbeat: parsed.data, file, raw: entry.json, ...(entry.at ? { loggedAt: entry.at } : {}) };
+        }
+    }
+    return newest;
+}
+function defaultReadFile(absPath) {
+    return fs.readFile(absPath, "utf8");
+}
+export async function pollCyberpunk(input) {
+    const now = input.now ?? (() => new Date());
+    const sleep = input.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const readTail = input.readTail ?? ((absPath) => readLogTail(absPath));
+    const readFile = input.readFile ?? defaultReadFile;
+    const budgetMs = Math.min(input.timeoutMs ?? Number.POSITIVE_INFINITY, pollBudgetMs(input.probeCount, input.windowSeconds));
+    const start = now();
+    let lastIncomplete;
+    for (;;) {
+        for (const dir of input.dirs ?? []) {
+            const result = await readCompleteResult(dir, input.id, "cyberpunk2077", readFile);
+            if (result && result.nonce === input.nonce) {
+                return { status: "complete", result, transport: "file", file: dir, elapsedMs: now().getTime() - start.getTime() };
+            }
+        }
+        const scan = await findCetResult(input.files, { id: input.id, nonce: input.nonce, armedAt: input.armedAt }, { readTail });
+        if (scan.status === "complete") {
+            return { status: "complete", result: scan.result, transport: "log", file: scan.file, elapsedMs: now().getTime() - start.getTime() };
+        }
+        if (scan.status === "incomplete")
+            lastIncomplete = scan;
+        const elapsedMs = now().getTime() - start.getTime();
+        if (elapsedMs >= budgetMs) {
+            if (lastIncomplete?.reason === "truncated") {
+                return {
+                    status: "timeout",
+                    reason: "truncated",
+                    file: lastIncomplete.file,
+                    elapsedMs,
+                    message: `A ${CET_RESULT_TAG} line for "${input.id}" is in ${lastIncomplete.file}, but its ${CET_DONE_TAG} marker declares ` +
+                        `${lastIncomplete.expectedBytes} bytes and the line carries ${lastIncomplete.actualBytes} — the line was cut mid-write. ` +
+                        `Re-run the console line rather than reading a partial answer.`,
+                };
+            }
+            return classifyCetTimeout(input, elapsedMs, lastIncomplete, { readTail, readFile, now });
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+export function pollCetLog(input) {
+    return pollCyberpunk(input);
+}
+async function readCetFileHeartbeat(dirs, readFile) {
+    let newest;
+    let newestAt = Number.NEGATIVE_INFINITY;
+    for (const dir of dirs) {
+        let raw;
+        try {
+            raw = await readFile(path.join(dir, bridgeFileNames("cyberpunk2077").heartbeat));
+        }
+        catch {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = bridgeHeartbeatSchema.safeParse(JSON.parse(raw));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed.success)
+            continue;
+        const at = Date.parse(parsed.data.at);
+        if (Number.isNaN(at) || at < newestAt)
+            continue;
+        newestAt = at;
+        newest = { heartbeat: parsed.data, dir };
+    }
+    return newest;
+}
+async function classifyCetTimeout(input, elapsedMs, lastIncomplete, deps) {
+    const fromFile = await readCetFileHeartbeat(input.dirs ?? [], deps.readFile);
+    const fromLog = await readCetHeartbeat(input.files, { readTail: deps.readTail });
+    const useFile = fromFile !== undefined &&
+        (fromLog === undefined || Date.parse(fromFile.heartbeat.at) >= Date.parse(fromLog.heartbeat.at));
+    const found = useFile
+        ? { heartbeat: fromFile.heartbeat, transport: "file", path: fromFile.dir, freshMs: HEARTBEAT_FRESH_MS }
+        : fromLog
+            ? { heartbeat: fromLog.heartbeat, transport: "log", path: fromLog.file, freshMs: CET_LOG_HEARTBEAT_FRESH_MS }
+            : undefined;
+    if (!found) {
+        return {
+            status: "timeout",
+            reason: "absent",
+            elapsedMs,
+            message: `No heartbeat anywhere: no ${bridgeFileNames("cyberpunk2077").heartbeat} in ${(input.dirs ?? []).join(" or ") || "any candidate directory"}, ` +
+                `and no ${CET_HEARTBEAT_TAG} line in ${input.files.join(" or ")} — the bridge is not deployed, the game has not run ` +
+                `since deploy, or its output lands somewhere none of those cover (the bridge's own m.where() line tells those apart).`,
+        };
+    }
+    const heartbeatFrom = { transport: found.transport, path: found.path };
+    const ageMs = deps.now().getTime() - Date.parse(found.heartbeat.at);
+    if (ageMs > found.freshMs) {
+        return {
+            status: "timeout",
+            reason: "stale",
+            heartbeat: found.heartbeat,
+            heartbeatFrom,
+            elapsedMs,
+            message: `The newest heartbeat (${found.transport} transport, ${found.path}) is ${Math.round(ageMs / 1000)}s old — the game is not running, or the bridge stopped ticking.`,
+        };
+    }
+    if (found.heartbeat.state === "running") {
+        return {
+            status: "timeout",
+            reason: "hung",
+            heartbeat: found.heartbeat,
+            heartbeatFrom,
+            elapsedMs,
+            message: `The bridge heartbeat is fresh and still "running" after the poll budget — a probe is hung, or its settleSeconds has not elapsed.`,
+        };
+    }
+    if (found.heartbeat.lastRequestId !== input.id) {
+        return {
+            status: "timeout",
+            reason: "unseen",
+            heartbeat: found.heartbeat,
+            heartbeatFrom,
+            elapsedMs,
+            message: `The bridge is idle and its lastRequestId ("${found.heartbeat.lastRequestId ?? "none"}") is not "${input.id}" — it never saw ` +
+                `this request. On the log transport that means the console line was never run (or m.arm refused it, which prints as an ` +
+                `"[ModWrightBridge] arm refused: …" line); on the file transport it means the request went to the wrong write root.`,
+        };
+    }
+    return {
+        status: "timeout",
+        reason: "hung",
+        heartbeat: found.heartbeat,
+        heartbeatFrom,
+        ...(lastIncomplete ? { file: lastIncomplete.file } : {}),
+        elapsedMs,
+        message: `The bridge is idle and reports lastRequestId "${input.id}" but no complete result reached either transport. ` +
+            `Check the CET log for an error while handling the request.`,
+    };
+}

package/dist/core/bridge/index.js

@@ -0,0 +1,11 @@
+export * from "./types.js";
+export { bridgeFileNames, bridgeCandidateDirs, cetModDir } from "./paths.js";
+export { HEARTBEAT_FRESH_MS, locateBridge } from "./locate.js";
+export { bridgeStatus } from "./status.js";
+export { armBridge, buildRequest, generateNonce, generateRequestId, planArmRequest } from "./arm.js";
+export { CET_CONSOLE_MOD, cetArmConsoleLine, cetArmSteps, compactRequestJson, luaSingleQuoted } from "./cet-console.js";
+export { CET_DONE_TAG, CET_HEARTBEAT_TAG, CET_LOG_HEARTBEAT_FRESH_MS, CET_LOG_TAIL_BYTES, CET_RESULT_TAG, CET_MOD_LOG_FALLBACK, cetCapabilities, cetLogCandidates, cetSandboxIo, findCetResult, pollCetLog, pollCyberpunk, readCetHeartbeat, readLogTail, scanCetLog, } from "./cet-log.js";
+export { buildPendingArm, listPendingArms, pendingArmDir, pendingArmFile, pendingArmSchema, planRecordPendingArm, readPendingArm } from "./pending.js";
+export { MAX_BUDGET_SECONDS, MIN_BUDGET_SECONDS, POLL_INTERVAL_MS, SECONDS_PER_PROBE, pollBudgetMs, pollForResult, readCompleteResult } from "./poll.js";
+export { bridgeDeployTarget, bridgeId, bridgesRootDir, bridgeSourceDir, planStageBridge, stageBridge, stagedBridgeDir } from "./stage.js";
+export { bridgeNeverShipValidator } from "./validate.js";

package/dist/core/bridge/locate.js

@@ -0,0 +1,35 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { bridgeCandidateDirs, bridgeFileNames } from "./paths.js";
+import { bridgeHeartbeatSchema } from "./types.js";
+export const HEARTBEAT_FRESH_MS = 15_000;
+function defaultReadFile(absPath) {
+    return fs.readFile(absPath, "utf8");
+}
+export async function locateBridge(game, install, surface, deps = {}) {
+    const candidates = bridgeCandidateDirs(game, install, surface);
+    const files = bridgeFileNames(game);
+    const readFile = deps.readFile ?? defaultReadFile;
+    const now = deps.now ?? (() => new Date());
+    for (const dir of candidates) {
+        let raw;
+        try {
+            raw = await readFile(path.join(dir, files.heartbeat));
+        }
+        catch {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = bridgeHeartbeatSchema.safeParse(JSON.parse(raw));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed.success)
+            continue;
+        const ageMs = now().getTime() - Date.parse(parsed.data.at);
+        return { candidates, dir, heartbeat: parsed.data, ageMs, raw };
+    }
+    return { candidates };
+}

package/dist/core/bridge/paths.js

@@ -0,0 +1,34 @@
+import * as path from "node:path";
+const BG3_FILES = {
+    heartbeat: "ModWright_hb.json",
+    heartbeatClient: "ModWright_hb_client.json",
+    request: "ModWright_req.json",
+    requestMarker: "ModWright_req.marker.json",
+    result: (id) => `ModWright_res_${id}.json`,
+    resultDone: (id) => `ModWright_res_${id}.done.json`,
+    log: "ModWright_log.json",
+};
+const CP2077_FILES = {
+    heartbeat: "modwright_hb.json",
+    request: "modwright_req.json",
+    requestMarker: "modwright_req.marker.json",
+    result: (id) => `modwright_res_${id}.json`,
+    resultDone: (id) => `modwright_res_${id}.done.json`,
+};
+export function bridgeFileNames(game) {
+    return game === "baldursgate3" ? BG3_FILES : CP2077_FILES;
+}
+export function bridgeCandidateDirs(game, install, surface) {
+    if (game === "baldursgate3") {
+        const root = surface.modRoots(install).find((r) => r.id === "scriptextender");
+        if (!root) {
+            throw new Error(`bridge: surface "${surface.id}" declares no "scriptextender" mod root — cannot resolve the BG3 bridge directory.`);
+        }
+        return [root.path];
+    }
+    const binX64 = path.join(install.root, "bin", "x64");
+    return [cetModDir(install), binX64, install.root];
+}
+export function cetModDir(install) {
+    return path.join(install.root, "bin", "x64", "plugins", "cyber_engine_tweaks", "mods", "ModWrightBridge");
+}

package/dist/core/bridge/pending.js

@@ -0,0 +1,89 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+import { planDelete, planFile } from "../safety/index.js";
+import { PROTOCOL_VERSION, bridgeGameSchema, bridgeRequestSchema } from "./types.js";
+export function pendingArmDir(projectRoot) {
+    return path.join(projectRoot, ".modwright", "bridge", "pending");
+}
+export function pendingArmFile(projectRoot, id) {
+    return path.join(pendingArmDir(projectRoot), `${id}.json`);
+}
+export const pendingArmSchema = z
+    .object({
+    protocolVersion: z.number().int(),
+    game: bridgeGameSchema,
+    id: z.string().min(1),
+    nonce: z.string().min(1),
+    probeCount: z.number().int().positive(),
+    armedAt: z.string(),
+    armedUntil: z.string(),
+    windowSeconds: z.number().nonnegative().optional(),
+    consoleLine: z.string().min(1).optional(),
+    request: bridgeRequestSchema,
+})
+    .strict();
+export function buildPendingArm(request, consoleLine, armedAt, windowSeconds) {
+    return pendingArmSchema.parse({
+        protocolVersion: PROTOCOL_VERSION,
+        game: request.game,
+        id: request.id,
+        nonce: request.nonce,
+        probeCount: request.probes.length,
+        armedAt: armedAt.toISOString(),
+        armedUntil: request.armedUntil,
+        ...(windowSeconds !== undefined ? { windowSeconds } : {}),
+        ...(consoleLine !== undefined ? { consoleLine } : {}),
+        request,
+    });
+}
+export function planRecordPendingArm(projectRoot, pending) {
+    return {
+        purpose: `record pending console arm ${pending.id} (${pending.game})`,
+        operations: [planFile(pendingArmFile(projectRoot, pending.id), `${JSON.stringify(pending, null, 2)}\n`)],
+    };
+}
+export async function readPendingArm(projectRoot, id) {
+    let raw;
+    try {
+        raw = await fs.readFile(pendingArmFile(projectRoot, id), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = pendingArmSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : undefined;
+}
+export async function listPendingArms(projectRoot, game, opts) {
+    let names;
+    try {
+        names = await fs.readdir(pendingArmDir(projectRoot));
+    }
+    catch {
+        return [];
+    }
+    const activeAtMs = opts?.activeAt ? opts.activeAt.getTime() : undefined;
+    const found = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const pending = await readPendingArm(projectRoot, name.slice(0, -".json".length));
+        if (!pending)
+            continue;
+        if (game && pending.game !== game)
+            continue;
+        if (activeAtMs !== undefined && Date.parse(pending.armedUntil) <= activeAtMs)
+            continue;
+        found.push(pending);
+    }
+    return found.sort((a, b) => Date.parse(b.armedAt) - Date.parse(a.armedAt));
+}
+export async function planPruneExpiredPendingArms(projectRoot, game, before) {
+    const beforeMs = before.getTime();
+    const ops = [];
+    for (const pending of await listPendingArms(projectRoot, game)) {
+        if (Date.parse(pending.armedUntil) <= beforeMs)
+            ops.push(planDelete(pendingArmFile(projectRoot, pending.id)));
+    }
+    return ops;
+}

package/dist/core/bridge/poll.js

@@ -0,0 +1,155 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { HEARTBEAT_FRESH_MS } from "./locate.js";
+import { bridgeFileNames } from "./paths.js";
+import { bridgeDoneSchema, bridgeHeartbeatSchema, bridgeResultSchema } from "./types.js";
+export const POLL_INTERVAL_MS = 500;
+export const MIN_BUDGET_SECONDS = 15;
+export const SECONDS_PER_PROBE = 3;
+export const MAX_BUDGET_SECONDS = 300;
+export function pollBudgetMs(probeCount, windowSeconds = 0) {
+    const seconds = Math.min(MAX_BUDGET_SECONDS, Math.max(MIN_BUDGET_SECONDS, SECONDS_PER_PROBE * probeCount) + windowSeconds);
+    return seconds * 1000;
+}
+function defaultReadFile(absPath) {
+    return fs.readFile(absPath, "utf8");
+}
+function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function readCompleteResult(dir, id, game, readFile) {
+    const files = bridgeFileNames(game);
+    let doneRaw;
+    try {
+        doneRaw = await readFile(path.join(dir, files.resultDone(id)));
+    }
+    catch {
+        return undefined;
+    }
+    let done;
+    try {
+        done = bridgeDoneSchema.parse(JSON.parse(doneRaw));
+    }
+    catch {
+        return undefined;
+    }
+    if (done.id !== id)
+        return undefined;
+    let resultRaw;
+    try {
+        resultRaw = await readFile(path.join(dir, files.result(id)));
+    }
+    catch {
+        return undefined;
+    }
+    if (Buffer.byteLength(resultRaw, "utf8") !== done.bytes)
+        return undefined;
+    let parsed;
+    try {
+        parsed = bridgeResultSchema.safeParse(JSON.parse(resultRaw));
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed.success)
+        return undefined;
+    return parsed.data;
+}
+async function lastProbeStarted(dir, id, game, readFile) {
+    try {
+        const raw = await readFile(path.join(dir, bridgeFileNames(game).result(id)));
+        const parsed = JSON.parse(raw);
+        const probes = Array.isArray(parsed.probes) ? parsed.probes : [];
+        const last = probes[probes.length - 1];
+        return typeof last?.id === "string" ? last.id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function classifyTimeout(input, readFile, now, elapsedMs) {
+    for (const dir of input.dirs) {
+        let raw;
+        try {
+            raw = await readFile(path.join(dir, bridgeFileNames(input.game).heartbeat));
+        }
+        catch {
+            continue;
+        }
+        let heartbeat;
+        try {
+            heartbeat = bridgeHeartbeatSchema.parse(JSON.parse(raw));
+        }
+        catch {
+            continue;
+        }
+        const ageMs = now().getTime() - Date.parse(heartbeat.at);
+        if (ageMs > HEARTBEAT_FRESH_MS) {
+            return {
+                status: "timeout",
+                reason: "stale",
+                heartbeat,
+                heartbeatDir: dir,
+                elapsedMs,
+                message: `Heartbeat at ${dir} is ${Math.round(ageMs / 1000)}s old — the game is not running, or the bridge crashed. Check the SE/CET log.`,
+            };
+        }
+        if (heartbeat.state === "running") {
+            const lastProbe = await lastProbeStarted(dir, input.id, input.game, readFile);
+            return {
+                status: "timeout",
+                reason: "hung",
+                heartbeat,
+                heartbeatDir: dir,
+                elapsedMs,
+                message: `Bridge heartbeat is fresh and still "running" after the poll budget — a probe is hung.` +
+                    (lastProbe ? ` Last probe started: ${lastProbe}.` : ""),
+            };
+        }
+        if (heartbeat.lastRequestId !== input.id) {
+            return {
+                status: "timeout",
+                reason: "unseen",
+                heartbeat,
+                heartbeatDir: dir,
+                elapsedMs,
+                message: `Bridge is idle and its lastRequestId ("${heartbeat.lastRequestId ?? "none"}") does not match the armed ` +
+                    `request ("${input.id}") — the request was never seen, so the write root (CET) or storage dir is wrong.`,
+            };
+        }
+        return {
+            status: "timeout",
+            reason: "hung",
+            heartbeat,
+            heartbeatDir: dir,
+            elapsedMs,
+            message: `Bridge is idle and reports lastRequestId "${input.id}" but produced no result — check the SE/CET log for an error while handling the request.`,
+        };
+    }
+    return {
+        status: "timeout",
+        reason: "absent",
+        elapsedMs,
+        message: "No heartbeat found in any candidate directory — the bridge is not deployed, or the game has not run since deploy.",
+    };
+}
+export async function pollForResult(input) {
+    const now = input.now ?? (() => new Date());
+    const sleep = input.sleep ?? realSleep;
+    const readFile = input.readFile ?? defaultReadFile;
+    const budgetMs = Math.min(input.timeoutMs ?? Number.POSITIVE_INFINITY, pollBudgetMs(input.probeCount, input.windowSeconds));
+    const start = now();
+    for (;;) {
+        for (const dir of input.dirs) {
+            const result = await readCompleteResult(dir, input.id, input.game, readFile);
+            if (result && result.nonce === input.nonce) {
+                return { status: "complete", result, dir, elapsedMs: now().getTime() - start.getTime() };
+            }
+        }
+        const elapsedMs = now().getTime() - start.getTime();
+        if (elapsedMs >= budgetMs) {
+            return classifyTimeout({ game: input.game, dirs: input.dirs, id: input.id }, readFile, now, elapsedMs);
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}