@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.bfa11ebe98c6

package/dist/runtime/host-diagnostics.js

@@ -0,0 +1,191 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { readCanonicalSourceFile } from "./canonical-source-file.js";
+import { assertCanonicalDirectory } from "./attempt-private-directory.js";
+import { runAttemptArchiveOperation, runAttemptPathOperation } from "./attempt-path-operation.js";
+import { readPinnedSourceDirectory } from "./pinned-source-directory.js";
+import { compactHostAttemptId } from "./host-execution-root.js";
+const maximumEvidenceBytes = 200 * 1024 * 1024;
+const diagnosticsRetentionDeadlineMs = 30_000;
+const diagnosticsHelperTerminationConfirmationMs = 2_000;
+export class HostDiagnosticsBudgetError extends Error {
+    constructor(message) {
+        super(`host_diagnostics_budget: ${message}`);
+        this.name = "HostDiagnosticsBudgetError";
+    }
+}
+/** Runner-local evidence, never web-served; browser-profile, cache and temporary directories are excluded. */
+export async function retainHostDiagnostics(stateRoot, attemptRoot, attemptId, expectedAttemptRootIdentity, attemptOwnerRoot = stateRoot, options = {}) {
+    const requestedDeadlineMs = options.deadlineMs;
+    const configuredDeadlineMs = Math.max(1, Math.min(diagnosticsRetentionDeadlineMs, Number.isFinite(requestedDeadlineMs) && (requestedDeadlineMs ?? 0) > 0
+        ? Math.floor(requestedDeadlineMs)
+        : diagnosticsRetentionDeadlineMs));
+    const retentionDeadline = Date.now() + configuredDeadlineMs;
+    const identity = attemptId.replaceAll("-", "").toLowerCase();
+    const compactAttemptRoot = path.resolve(attemptOwnerRoot, "a", compactHostAttemptId(attemptId));
+    const legacyAttemptRoot = path.resolve(stateRoot, "host-attempts", identity);
+    if (!/^[0-9a-f]{32}$/u.test(identity)
+        || (path.resolve(attemptRoot) !== compactAttemptRoot
+            && path.resolve(attemptRoot) !== legacyAttemptRoot)) {
+        throw new Error("host_diagnostics_invalid_owner: refusing an unowned attempt path.");
+    }
+    const attemptStat = await withinRetentionDeadline(async () => await fs.lstat(attemptRoot).catch(error => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }), retentionDeadline, configuredDeadlineMs);
+    if (attemptStat) {
+        if (!expectedAttemptRootIdentity) {
+            throw new Error("host_diagnostics_invalid_owner: original attempt-root identity is unavailable.");
+        }
+        await withinRetentionDeadline(() => assertHostAttemptRootIdentity(attemptRoot, expectedAttemptRootIdentity), retentionDeadline, configuredDeadlineMs);
+    }
+    const target = path.join(stateRoot, "diagnostics", "host", identity);
+    const manifestPath = path.join(target, "manifest.json");
+    await withinRetentionDeadline(() => assertCanonicalDirectory(stateRoot), retentionDeadline, configuredDeadlineMs);
+    await createArchiveDirectory(target, retentionDeadline, configuredDeadlineMs);
+    const priorManifest = await withinRetentionDeadline(async () => await fs.lstat(manifestPath).catch(error => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }), retentionDeadline, configuredDeadlineMs);
+    if (priorManifest && (!priorManifest.isFile() || priorManifest.isSymbolicLink()))
+        throw new Error("host_diagnostics_unsafe_path: manifest is not an ordinary file.");
+    if (priorManifest && !attemptStat) {
+        const saved = JSON.parse((await withinRetentionDeadline(() => readCanonicalSourceFile(manifestPath, maximumEvidenceBytes), retentionDeadline, configuredDeadlineMs)).toString("utf8"));
+        if (saved.attemptId !== attemptId)
+            throw new Error("host_diagnostics_invalid_owner: archive identity mismatch.");
+        return target;
+    }
+    const files = [];
+    let bytes = 0;
+    let entries = 0;
+    let excludedGeneratedFiles = 0;
+    let excludedGeneratedBytes = 0n;
+    const readDirectory = async (directory, identity) => {
+        const timing = remainingHelperTiming(retentionDeadline, configuredDeadlineMs);
+        return await runWithinRetentionHelperDeadline(() => readPinnedSourceDirectory(directory, identity, timing.operationTimeoutMs, timing.terminationConfirmationMs), retentionDeadline, configuredDeadlineMs);
+    };
+    const walk = async (relative, entry) => {
+        if (++entries > 10000)
+            throw new HostDiagnosticsBudgetError("evidence inventory exceeds retention budget.");
+        const source = path.join(attemptRoot, relative);
+        if (entry.kind === "symlink")
+            throw new Error("host_diagnostics_unsafe_path: evidence contains a symlink.");
+        if (entry.kind === "directory") {
+            await createArchiveDirectory(path.join(target, relative), retentionDeadline, configuredDeadlineMs);
+            for (const child of await readDirectory(source, entry.identity)) {
+                await walk(path.join(relative, child.name), child);
+            }
+            return;
+        }
+        if (entry.kind !== "file")
+            throw new Error("host_diagnostics_unsafe_path: evidence is not an ordinary file.");
+        // .NET test result directories contain copied assemblies and symbols, often
+        // many times over. They are reproducible build products, not diagnostics.
+        if (relative.startsWith(`test-output${path.sep}`) && /\.(?:dll|pdb)$/iu.test(relative)) {
+            excludedGeneratedFiles += 1;
+            excludedGeneratedBytes += entry.size;
+            return;
+        }
+        if (files.length >= 5000 || entry.size > BigInt(maximumEvidenceBytes - bytes))
+            throw new HostDiagnosticsBudgetError("evidence exceeds retention budget; original attempt retained for recovery.");
+        const destination = path.join(target, relative);
+        const contents = await withinRetentionDeadline(() => readCanonicalSourceFile(source, maximumEvidenceBytes - bytes, entry.identity), retentionDeadline, configuredDeadlineMs);
+        bytes += contents.length;
+        const sha256 = createHash("sha256").update(contents).digest("hex");
+        remainingRetentionMs(retentionDeadline, configuredDeadlineMs);
+        await writeArchiveFile(destination, contents, sha256, retentionDeadline, configuredDeadlineMs);
+        files.push({ path: relative, bytes: contents.length, sha256 });
+    };
+    if (attemptStat) {
+        await withinRetentionDeadline(() => assertHostAttemptRootIdentity(attemptRoot, expectedAttemptRootIdentity), retentionDeadline, configuredDeadlineMs);
+        const rootEntries = await readDirectory(attemptRoot, expectedAttemptRootIdentity);
+        for (const directory of ["logs", "test-output"]) {
+            const entry = rootEntries.find(candidate => candidate.name === directory);
+            if (entry)
+                await walk(directory, entry);
+        }
+    }
+    // Only owned relative evidence paths and hashes go into the public-facing manifest.
+    const manifest = Buffer.from(JSON.stringify({
+        schemaVersion: 1,
+        attemptId,
+        retainedAt: new Date().toISOString(),
+        files,
+        excludedGeneratedFiles,
+        excludedGeneratedBytes: excludedGeneratedBytes.toString(),
+    }, null, 2));
+    await writeArchiveFile(manifestPath, manifest, createHash("sha256").update(manifest).digest("hex"), retentionDeadline, configuredDeadlineMs);
+    return target;
+}
+export async function assertHostAttemptRootIdentity(attemptRoot, expected) {
+    const current = await assertCanonicalDirectory(attemptRoot);
+    if (!current || current.dev !== expected.dev || current.ino !== expected.ino) {
+        throw new Error("host_diagnostics_invalid_owner: attempt-root identity changed.");
+    }
+}
+async function writeArchiveFile(target, bytes, sha256, retentionDeadline, configuredDeadlineMs) {
+    const parent = path.dirname(path.resolve(target));
+    const identity = (await withinRetentionDeadline(() => assertCanonicalDirectory(parent), retentionDeadline, configuredDeadlineMs));
+    const timing = remainingHelperTiming(retentionDeadline, configuredDeadlineMs);
+    await runWithinRetentionHelperDeadline(() => runAttemptArchiveOperation(parent, identity, { name: path.basename(target), bytes, sha256 }, timing.operationTimeoutMs, timing.terminationConfirmationMs), retentionDeadline, configuredDeadlineMs);
+}
+async function createArchiveDirectory(target, retentionDeadline, configuredDeadlineMs) {
+    const resolved = path.resolve(target);
+    if (await withinRetentionDeadline(() => assertCanonicalDirectory(resolved, true), retentionDeadline, configuredDeadlineMs))
+        return;
+    let parent = path.dirname(resolved);
+    let identity = await withinRetentionDeadline(() => assertCanonicalDirectory(parent, true), retentionDeadline, configuredDeadlineMs);
+    while (!identity) {
+        parent = path.dirname(parent);
+        identity = await withinRetentionDeadline(() => assertCanonicalDirectory(parent, true), retentionDeadline, configuredDeadlineMs);
+    }
+    const timing = remainingHelperTiming(retentionDeadline, configuredDeadlineMs);
+    await runWithinRetentionHelperDeadline(() => runAttemptPathOperation(parent, identity, { kind: "mkdir", segments: path.relative(parent, resolved).split(path.sep) }, timing.operationTimeoutMs, timing.terminationConfirmationMs), retentionDeadline, configuredDeadlineMs);
+    await withinRetentionDeadline(() => assertCanonicalDirectory(resolved), retentionDeadline, configuredDeadlineMs);
+}
+function remainingHelperTiming(retentionDeadline, configuredDeadlineMs) {
+    const remainingMs = remainingRetentionMs(retentionDeadline, configuredDeadlineMs);
+    const terminationConfirmationMs = Math.min(diagnosticsHelperTerminationConfirmationMs, Math.max(1, Math.floor(remainingMs / 4)));
+    const operationTimeoutMs = remainingMs - terminationConfirmationMs;
+    if (operationTimeoutMs <= 0)
+        throw diagnosticsDeadlineError(configuredDeadlineMs);
+    return { operationTimeoutMs, terminationConfirmationMs };
+}
+function remainingRetentionMs(retentionDeadline, configuredDeadlineMs) {
+    const remainingMs = retentionDeadline - Date.now();
+    if (remainingMs <= 0)
+        throw diagnosticsDeadlineError(configuredDeadlineMs);
+    return remainingMs;
+}
+async function withinRetentionDeadline(operation, retentionDeadline, configuredDeadlineMs) {
+    const remainingMs = remainingRetentionMs(retentionDeadline, configuredDeadlineMs);
+    let timer;
+    try {
+        return await Promise.race([
+            operation(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(diagnosticsDeadlineError(configuredDeadlineMs)), remainingMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function runWithinRetentionHelperDeadline(operation, retentionDeadline, configuredDeadlineMs) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (Date.now() >= retentionDeadline)
+            throw diagnosticsDeadlineError(configuredDeadlineMs);
+        throw error;
+    }
+}
+function diagnosticsDeadlineError(configuredDeadlineMs) {
+    return new Error(`host_diagnostics_temporary_unavailable: diagnostics retention exceeded ${configuredDeadlineMs} ms.`);
+}

package/dist/runtime/host-execution-root.d.ts

@@ -0,0 +1,4 @@
+/** Keep ephemeral host-attempt trees short and per-user. */
+export declare function defaultHostExecutionRoot(configuredRoot?: string | undefined, platform?: NodeJS.Platform, homeDirectory?: string): string;
+export declare function assertHostExecutionRoot(executionRoot: string, platform?: NodeJS.Platform): void;
+export declare function compactHostAttemptId(dispatchAttemptId: string): string;

package/dist/runtime/host-execution-root.js

@@ -0,0 +1,39 @@
+import os from "node:os";
+import path from "node:path";
+const windowsPathBudget = 248;
+/** Keep ephemeral host-attempt trees short and per-user. */
+export function defaultHostExecutionRoot(configuredRoot = process.env.FORGE_SANDBOX_EXECUTION_ROOT, platform = process.platform, homeDirectory = os.homedir()) {
+    const platformPath = platform === "win32" ? path.win32 : path.posix;
+    const configured = configuredRoot?.trim();
+    const selected = configured
+        ? platformPath.resolve(configured)
+        : platformPath.resolve(homeDirectory, ".fgx");
+    assertHostExecutionRoot(selected, platform);
+    return selected;
+}
+export function assertHostExecutionRoot(executionRoot, platform = process.platform) {
+    const platformPath = platform === "win32" ? path.win32 : path.posix;
+    if (!platformPath.isAbsolute(executionRoot)) {
+        throw new Error("host_execution_root_invalid: FORGE_SANDBOX_EXECUTION_ROOT must be absolute.");
+    }
+    const resolved = platformPath.resolve(executionRoot);
+    if (resolved === platformPath.parse(resolved).root) {
+        throw new Error("host_execution_root_invalid: the execution root cannot be a filesystem root.");
+    }
+    if (platform !== "win32")
+        return;
+    // Model the deepest Forge-owned test-world plus Git's own bookkeeping. This
+    // rejects unsafe layouts before an agent starts instead of failing midway.
+    const projected = path.win32.join(resolved, "a", "f".repeat(20), "t", "p-i-0", "f".repeat(32), "forge-test-worlds", "f".repeat(32), `activation-commit-${"f".repeat(40)}`, ".git", "worktrees", "f".repeat(20), "locked");
+    if (projected.length > windowsPathBudget) {
+        throw new Error(`host_execution_path_budget_exceeded: '${resolved}' exceeds the safe Windows path budget by ${projected.length - windowsPathBudget} characters. `
+            + "Set FORGE_SANDBOX_EXECUTION_ROOT to a shorter per-user directory before starting the Bridge.");
+    }
+}
+export function compactHostAttemptId(dispatchAttemptId) {
+    const normalized = dispatchAttemptId.replaceAll("-", "").toLowerCase();
+    if (!/^[0-9a-f]{32}$/u.test(normalized)) {
+        throw new Error("host_execution_attempt_invalid: dispatch attempt must be a UUID.");
+    }
+    return normalized.slice(0, 20);
+}

package/dist/runtime/host-listener-inspector.d.ts

@@ -6,6 +6,8 @@ export interface HostInspectionCommandResult {
     readonly stdout: string;
     readonly stderr: string;
     readonly errorCode?: string;
+    readonly timedOut?: boolean;
+    readonly signal?: string;
 }
 export interface HostInspectionCommandRunner {
     run(command: string, args: readonly string[]): Promise<HostInspectionCommandResult>;
@@ -14,12 +16,17 @@ export interface HostInspectionCommandRunner {
 export declare class HostListenerInspector {
     private readonly commands;
     private readonly platform;
-    constructor(commands?: HostInspectionCommandRunner, platform?: NodeJS.Platform);
+    private readonly retryDelayMs;
+    constructor(commands?: HostInspectionCommandRunner, platform?: NodeJS.Platform, retryDelayMs?: number);
     inspect(child: AttemptProcessChildHandle, reservation: HostPortReservation, owner: HostPortLeaseOwner): Promise<HostListenerOwnership>;
     /** Returns loopback TCP ports opened by one exact supervised child process tree. */
     inspectOwnedLoopbackListeners(child: AttemptProcessChildHandle, owner: HostPortLeaseOwner): Promise<readonly number[]>;
+    /** Snapshots loopback TCP ports that predate a supervised child launch. */
+    inspectLoopbackListeners(): Promise<readonly number[]>;
     private inspectWindows;
     private inspectAllWindows;
+    private runWindowsAncestry;
+    private runWindowsNetstat;
     private inspectUnix;
     private inspectAllUnix;
 }

package/dist/runtime/host-listener-inspector.js

@@ -3,13 +3,20 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const windowsListenerOwnerPath = fileURLToPath(new URL("../../runtime/windows-listener-owner.ps1", import.meta.url));
+const windowsNetstatArgs = ["-ano", "-p", "TCP"];
+const windowsNetstatAttempts = 3;
+const windowsAncestryAttempts = 2;
+const windowsNetstatRetryDelayMs = 250;
+const inspectionCommandTimeoutMs = 15_000;
 /** Proves that a loopback listener belongs to one exact supervised child. */
 export class HostListenerInspector {
     commands;
     platform;
-    constructor(commands = new ExecFileInspectionCommandRunner(), platform = process.platform) {
+    retryDelayMs;
+    constructor(commands = new ExecFileInspectionCommandRunner(), platform = process.platform, retryDelayMs = windowsNetstatRetryDelayMs) {
         this.commands = commands;
         this.platform = platform;
+        this.retryDelayMs = retryDelayMs;
     }
     async inspect(child, reservation, owner) {
         if (reservation.hostIp !== "127.0.0.1" || reservation.protocol !== "tcp") {
@@ -35,77 +42,107 @@ export class HostListenerInspector {
             ? await this.inspectAllWindows(metadata.rootPid)
             : await this.inspectAllUnix(metadata.rootPid);
     }
-    async inspectWindows(rootPid, port) {
-        const netstat = await this.commands.run("netstat.exe", ["-ano", "-p", "TCP"]);
-        if (netstat.exitCode !== 0) {
-            throw commandError("netstat", netstat);
+    /** Snapshots loopback TCP ports that predate a supervised child launch. */
+    async inspectLoopbackListeners() {
+        if (this.platform === "win32") {
+            const netstat = await this.runWindowsNetstat();
+            return uniqueSorted(parseWindowsLoopbackListeners(netstat.stdout).map(listener => listener.port));
+        }
+        const lsof = await this.commands.run("lsof", [
+            "-nP",
+            "-a",
+            "-iTCP@127.0.0.1",
+            "-sTCP:LISTEN",
+            "-Fpn",
+        ]);
+        if (lsof.exitCode === 0 || lsof.exitCode === 1) {
+            return uniqueSorted(parseLsofLoopbackListeners(lsof.stdout).map(listener => listener.port));
         }
+        if (lsof.errorCode !== "ENOENT")
+            throw commandError("lsof", lsof);
+        const ss = await this.commands.run("ss", ["-H", "-ltnp"]);
+        if (ss.exitCode !== 0)
+            throw commandError("ss", ss);
+        return uniqueSorted(parseSsLoopbackListeners(ss.stdout).map(listener => listener.port));
+    }
+    async inspectWindows(rootPid, port) {
+        const netstat = await this.runWindowsNetstat();
         const listenerPids = parseWindowsListenerPids(netstat.stdout, port);
         if (listenerPids.length === 0)
             return "unbound";
-        const powershell = windowsPowerShellPath();
-        const ownership = await this.commands.run(powershell, [
-            "-NoLogo",
-            "-NoProfile",
-            "-NonInteractive",
-            "-ExecutionPolicy",
-            "Bypass",
-            "-File",
-            windowsListenerOwnerPath,
-            "-RootProcessId",
-            String(rootPid),
-            "-ListenerProcessIds",
-            listenerPids.join(","),
-        ]);
-        if (ownership.exitCode !== 0)
-            throw commandError("Windows process ancestry", ownership);
-        let parsed;
-        try {
-            parsed = JSON.parse(ownership.stdout.trim());
-        }
-        catch (error) {
-            throw new Error("host_listener_inspection_failed: Windows ancestry output was invalid.", { cause: error });
-        }
-        const values = Array.isArray(parsed) ? parsed : [parsed];
-        return values.length === listenerPids.length && values.every(value => value === true) ? "owned" : "foreign";
+        const values = await this.runWindowsAncestry(rootPid, listenerPids);
+        return values.every(value => value) ? "owned" : "foreign";
     }
     async inspectAllWindows(rootPid) {
-        const netstat = await this.commands.run("netstat.exe", ["-ano", "-p", "TCP"]);
-        if (netstat.exitCode !== 0)
-            throw commandError("netstat", netstat);
+        const netstat = await this.runWindowsNetstat();
         const listeners = parseWindowsLoopbackListeners(netstat.stdout);
         if (listeners.length === 0)
             return [];
         const pids = [...new Set(listeners.map(listener => listener.pid))];
-        const ownership = await this.commands.run(windowsPowerShellPath(), [
-            "-NoLogo",
-            "-NoProfile",
-            "-NonInteractive",
-            "-ExecutionPolicy",
-            "Bypass",
-            "-File",
-            windowsListenerOwnerPath,
-            "-RootProcessId",
-            String(rootPid),
-            "-ListenerProcessIds",
-            pids.join(","),
-        ]);
-        if (ownership.exitCode !== 0)
-            throw commandError("Windows process ancestry", ownership);
-        let parsed;
-        try {
-            parsed = JSON.parse(ownership.stdout.trim());
-        }
-        catch (error) {
-            throw new Error("host_listener_inspection_failed: Windows ancestry output was invalid.", { cause: error });
-        }
-        const values = Array.isArray(parsed) ? parsed : [parsed];
-        if (values.length !== pids.length || values.some(value => typeof value !== "boolean")) {
-            throw new Error("host_listener_inspection_failed: Windows ancestry output was incomplete.");
-        }
+        const values = await this.runWindowsAncestry(rootPid, pids);
         const ownedPids = new Set(pids.filter((_pid, index) => values[index] === true));
         return uniqueSorted(listeners.filter(listener => ownedPids.has(listener.pid)).map(listener => listener.port));
     }
+    async runWindowsAncestry(rootPid, listenerPids) {
+        let lastResult = null;
+        let lastParseError;
+        for (let attempt = 1; attempt <= windowsAncestryAttempts; attempt += 1) {
+            const result = await this.commands.run(windowsPowerShellPath(), [
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                windowsListenerOwnerPath,
+                "-RootProcessId",
+                String(rootPid),
+                "-ListenerProcessIds",
+                listenerPids.join(","),
+            ]);
+            lastResult = result;
+            if (result.exitCode !== 0) {
+                if (!isTransientWindowsInspectionFailure(result) || attempt === windowsAncestryAttempts) {
+                    throw commandError("Windows process ancestry", result);
+                }
+            }
+            else {
+                try {
+                    const parsed = JSON.parse(result.stdout.trim());
+                    const values = Array.isArray(parsed) ? parsed : [parsed];
+                    if (values.length !== listenerPids.length || values.some(value => typeof value !== "boolean")) {
+                        throw new Error("Windows ancestry output was incomplete.");
+                    }
+                    return values;
+                }
+                catch (error) {
+                    lastParseError = error;
+                    if (attempt === windowsAncestryAttempts) {
+                        throw new Error(`host_diagnostics_temporary_unavailable: Windows process ancestry returned invalid output after ${attempt} attempts.`, { cause: error });
+                    }
+                }
+            }
+            await wait(this.retryDelayMs);
+        }
+        if (lastResult)
+            throw commandError("Windows process ancestry", lastResult);
+        throw new Error("host_diagnostics_temporary_unavailable: Windows process ancestry produced no result.", {
+            cause: lastParseError,
+        });
+    }
+    async runWindowsNetstat() {
+        let lastResult = null;
+        for (let attempt = 1; attempt <= windowsNetstatAttempts; attempt += 1) {
+            const result = await this.commands.run("netstat.exe", windowsNetstatArgs);
+            if (result.exitCode === 0)
+                return result;
+            lastResult = result;
+            if (!isTransientWindowsNetstatFailure(result) || attempt === windowsNetstatAttempts)
+                break;
+            await wait(this.retryDelayMs);
+        }
+        throw commandError("netstat", lastResult);
+    }
     async inspectUnix(rootPid, port) {
         let listenerPids = null;
         const lsof = await this.commands.run("lsof", [
@@ -217,15 +254,18 @@ export class ExecFileInspectionCommandRunner {
                 : command;
             execFile(executable, args, {
                 windowsHide: true,
-                timeout: 15_000,
+                timeout: inspectionCommandTimeoutMs,
                 maxBuffer: 4 * 1024 * 1024,
             }, (error, stdout, stderr) => {
                 const processError = error;
+                const timedOut = Boolean(processError?.killed && processError.signal === "SIGTERM" && processError.code == null);
                 resolve({
                     exitCode: typeof processError?.code === "number" ? processError.code : error ? 1 : 0,
                     stdout: String(stdout),
                     stderr: String(stderr),
                     ...(typeof processError?.code === "string" ? { errorCode: processError.code } : {}),
+                    ...(timedOut ? { timedOut: true } : {}),
+                    ...(processError?.signal ? { signal: processError.signal } : {}),
                 });
             });
         });
@@ -313,8 +353,29 @@ function uniqueListeners(values) {
 function commandError(label, result) {
     const detail = result.stderr.replaceAll(/[\r\n\t]+/gu, " ").trim().slice(0, 512);
     const code = result.errorCode ? ` (${result.errorCode})` : "";
+    if (result.timedOut) {
+        return new Error(`host_diagnostics_temporary_unavailable: ${label} timed out after ${inspectionCommandTimeoutMs} ms${result.signal ? ` (${result.signal})` : ""}.`);
+    }
+    if (isTransientWindowsNetstatFailure(result)) {
+        return new Error(`host_diagnostics_temporary_unavailable: ${label} repeatedly exited ${result.exitCode} without diagnostics.`);
+    }
     return new Error(`host_listener_inspection_failed: ${label} exited ${result.exitCode}${code}${detail ? `: ${detail}` : ""}.`);
 }
+function isTransientWindowsNetstatFailure(result) {
+    return isTransientWindowsInspectionFailure(result);
+}
+function isTransientWindowsInspectionFailure(result) {
+    return result.timedOut === true
+        || (result.exitCode === 1
+            && !result.errorCode
+            && !result.stdout.trim()
+            && !result.stderr.trim());
+}
+function wait(milliseconds) {
+    return milliseconds > 0
+        ? new Promise(resolve => setTimeout(resolve, milliseconds))
+        : Promise.resolve();
+}
 function windowsPowerShellPath() {
     return path.win32.join(path.dirname(windowsSystemExecutable("netstat.exe")), "WindowsPowerShell", "v1.0", "powershell.exe");
 }

package/dist/runtime/host-runtime-contract.d.ts

@@ -1,4 +1,6 @@
 export declare const hostRuntimeContractPath = ".forge/forge.runtime.yml";
+export declare const hostRuntimeTestPostgresAdminEnvironment = "FORGE_TEST_POSTGRES_ADMIN_CONNECTION_STRING";
+export declare const hostRuntimeLegacyTestPostgresEnvironment = "FORGE_TEST_POSTGRES_CONNECTION_STRING";
 export type RequestedHostConcurrency = "serial" | "parallel" | "disabled";
 export type HostRuntimePortAdapter = "node" | "vite" | "next" | "aspnetcore";
 export interface HostRuntimeLaunchConfig {
@@ -41,7 +43,16 @@ export interface HostRuntimeDiscovery {
     readonly summary: string;
     readonly candidateFingerprint?: string | null;
 }
-export declare function loadHostRuntimeContract(worktreePath: string): Promise<LoadedHostRuntimeContract>;
+/** Returns retained bytes (or retained absence) for one canonical discovery input. */
+export type HostRuntimeSourceSnapshot = (target: string) => Promise<Buffer | null>;
+export interface HostRuntimeDirectoryEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+}
+/** Returns one identity-bound directory inventory for runtime discovery. */
+export type HostRuntimeDirectorySnapshot = (target: string) => Promise<readonly HostRuntimeDirectoryEntry[]>;
+export declare function loadHostRuntimeContract(worktreePath: string, snapshot?: HostRuntimeSourceSnapshot, directorySnapshot?: HostRuntimeDirectorySnapshot): Promise<LoadedHostRuntimeContract>;
 export declare function defaultHostRuntimeContract(): HostRuntimeContract;
 export declare function validateHostRuntimeContract(source: string): HostRuntimeContract;
 export declare function hostPortEnvironment(config: HostRuntimePortConfig, hostIp: "127.0.0.1", hostPort: number): Readonly<Record<string, string>>;