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

package/dist/runtime/docker-engine-probe.js

@@ -0,0 +1,333 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BoundedCommandRunner } from "../sandbox/command-runner.js";
+/**
+ * Probes ordinary Docker-daemon access for host-run Testcontainers and project
+ * services. This is deliberately independent from the stricter Forge sandbox
+ * preflight: a usable Docker Desktop engine may satisfy docker_engine even
+ * when it is not approved to host an agent sandbox.
+ */
+export class DockerEngineProbe {
+    commands;
+    cacheMs;
+    cached = null;
+    sampledAtMs = 0;
+    inFlight = null;
+    requiredWorkRecoveryInFlight = null;
+    consecutiveFailures = 0;
+    lastRecoveryAttemptAtMs = null;
+    docker;
+    context;
+    platform;
+    dockerHost;
+    now;
+    wait;
+    recovery;
+    recoveryExecutor;
+    onStatus;
+    constructor(options = {}, commands = new BoundedCommandRunner(), cacheMs = 15_000) {
+        this.commands = commands;
+        this.cacheMs = cacheMs;
+        this.docker = options.dockerExecutable ?? process.env.FORGE_DOCKER_EXECUTABLE ?? "docker";
+        this.context = options.dockerContext?.trim() || process.env.DOCKER_CONTEXT?.trim() || "default";
+        this.platform = options.platform ?? process.platform;
+        this.dockerHost = options.dockerHost ?? process.env.DOCKER_HOST?.trim() ?? "";
+        this.now = options.now ?? Date.now;
+        this.wait = options.wait ?? (delayMs => new Promise(resolve => setTimeout(resolve, delayMs)));
+        this.recovery = {
+            enabled: options.recovery?.enabled ?? false,
+            failureThreshold: positiveInteger(options.recovery?.failureThreshold, 3),
+            confirmationDelayMs: positiveInteger(options.recovery?.confirmationDelayMs, 30_000),
+            cooldownMs: positiveInteger(options.recovery?.cooldownMs, 10 * 60_000),
+            startupTimeoutMs: positiveInteger(options.recovery?.startupTimeoutMs, 2 * 60_000),
+            pollIntervalMs: positiveInteger(options.recovery?.pollIntervalMs, 2_000),
+            canRecover: options.recovery?.canRecover,
+        };
+        this.recoveryExecutor = options.recoveryExecutor ?? new WindowsDockerDesktopRecoveryExecutor(this.platform, commands);
+        this.onStatus = options.onStatus ?? (() => undefined);
+    }
+    current() {
+        return this.cached;
+    }
+    async refresh(force = false) {
+        if (!force && this.cached && this.now() - this.sampledAtMs < this.cacheMs) {
+            return this.cached;
+        }
+        if (this.inFlight)
+            return await this.inFlight;
+        const operation = this.inspectSafely()
+            .then(result => this.recoverIfEligible(result))
+            .then((result) => {
+            this.cached = result;
+            this.sampledAtMs = this.now();
+            return result;
+        })
+            .finally(() => {
+            if (this.inFlight === operation)
+                this.inFlight = null;
+        });
+        this.inFlight = operation;
+        return await operation;
+    }
+    /**
+     * Establishes a fresh daemon fence for work that declares Docker as a hard
+     * prerequisite. This remains bounded, cooldown protected and single-flight;
+     * it never contacts Docker unless a caller explicitly invokes this method.
+     */
+    async ensureAvailableForRequiredWork() {
+        const fresh = await this.refresh(true);
+        if (fresh.available || !this.recovery.enabled || !this.isLocalDockerDesktopContext()) {
+            return fresh;
+        }
+        if (this.requiredWorkRecoveryInFlight)
+            return await this.requiredWorkRecoveryInFlight;
+        const operation = this.recoverIfEligible(fresh, true)
+            .then((result) => {
+            this.cached = result;
+            this.sampledAtMs = this.now();
+            return result;
+        })
+            .finally(() => {
+            if (this.requiredWorkRecoveryInFlight === operation)
+                this.requiredWorkRecoveryInFlight = null;
+        });
+        this.requiredWorkRecoveryInFlight = operation;
+        return await operation;
+    }
+    async inspectSafely() {
+        return await this.inspect().catch((error) => unavailable(this.context, "docker_engine_unreachable", error instanceof Error ? error.message : String(error)));
+    }
+    async recoverIfEligible(snapshot, requiredWork = false) {
+        if (snapshot.available) {
+            this.consecutiveFailures = 0;
+            return snapshot;
+        }
+        this.consecutiveFailures += 1;
+        if (!this.recovery.enabled
+            || !this.isLocalDockerDesktopContext()
+            || (!requiredWork && this.consecutiveFailures < this.recovery.failureThreshold)
+            || (!requiredWork && this.recovery.canRecover?.() === false)) {
+            return snapshot;
+        }
+        const now = this.now();
+        if (this.lastRecoveryAttemptAtMs !== null
+            && now - this.lastRecoveryAttemptAtMs < this.recovery.cooldownMs) {
+            return snapshot;
+        }
+        this.onStatus(`Docker engine remained unavailable for ${this.consecutiveFailures} consecutive probes; waiting for one fresh confirmation before recovery.`);
+        await this.wait(this.recovery.confirmationDelayMs);
+        const confirmed = await this.inspectSafely();
+        if (confirmed.available) {
+            this.consecutiveFailures = 0;
+            this.onStatus("Docker engine recovered during the confirmation window; skipped Docker Desktop recovery.");
+            return confirmed;
+        }
+        if (!requiredWork && this.recovery.canRecover?.() === false) {
+            this.onStatus("Docker Desktop recovery was deferred because runner work became active during confirmation.");
+            return confirmed;
+        }
+        this.consecutiveFailures += 1;
+        this.lastRecoveryAttemptAtMs = this.now();
+        this.onStatus(`Docker engine remained unavailable after confirmation; starting one bounded Docker Desktop recovery.`);
+        const recovery = await this.recoveryExecutor.restart().catch((error) => ({
+            started: false,
+            reason: error instanceof Error ? error.message : String(error),
+        }));
+        if (!recovery.started) {
+            const reason = recovery.reason?.trim() || "Docker Desktop recovery could not be started.";
+            this.onStatus(`Docker Desktop recovery failed to start: ${singleLine(reason)}`);
+            return unavailable(this.context, "docker_engine_recovery_failed", reason);
+        }
+        const deadline = this.now() + this.recovery.startupTimeoutMs;
+        while (this.now() < deadline) {
+            await this.wait(Math.min(this.recovery.pollIntervalMs, Math.max(1, deadline - this.now())));
+            const verified = await this.inspectSafely();
+            if (verified.available) {
+                this.consecutiveFailures = 0;
+                this.onStatus("Docker Desktop recovery completed and the engine passed a fresh daemon probe.");
+                return verified;
+            }
+        }
+        this.onStatus("Docker Desktop recovery timed out before the engine became reachable; cooldown is active.");
+        return unavailable(this.context, "docker_engine_recovery_timeout", "Docker Desktop restart was requested, but the engine did not become reachable before the recovery timeout.");
+    }
+    isLocalDockerDesktopContext() {
+        return this.platform === "win32"
+            && !this.dockerHost
+            && (this.context === "default" || this.context === "desktop-linux");
+    }
+    async inspect() {
+        const dockerArgs = this.context === "default" ? [] : ["--context", this.context];
+        const result = await this.commands.run(this.docker, [...dockerArgs, "info", "--format", "{{json .}}"], { timeoutMs: 10_000, maxOutputBytes: 512 * 1024 });
+        if (result.exitCode !== 0) {
+            return unavailable(this.context, "docker_engine_unreachable", result.stderr || result.stdout || "Docker daemon is unreachable.");
+        }
+        let info;
+        try {
+            const parsed = JSON.parse(result.stdout.trim());
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error("not an object");
+            info = parsed;
+        }
+        catch {
+            return unavailable(this.context, "docker_engine_invalid_response", "Docker returned an invalid info document.");
+        }
+        const version = clean(info.ServerVersion);
+        const operatingSystem = clean(info.OSType)?.toLowerCase() ?? null;
+        const serverErrors = Array.isArray(info.ServerErrors)
+            ? info.ServerErrors.map(clean).filter((value) => Boolean(value))
+            : [];
+        if (serverErrors.length > 0 || !version || !operatingSystem) {
+            return unavailable(this.context, "docker_engine_unavailable_response", serverErrors.join(" ") || "Docker returned an incomplete daemon identity.");
+        }
+        return {
+            available: true,
+            sampledAt: new Date().toISOString(),
+            runtimeVersion: `docker/${version}`,
+            operatingSystem,
+            context: this.context,
+            unavailableCode: null,
+            unavailableReason: null,
+        };
+    }
+}
+/**
+ * Restarts only the local Docker Desktop installation. It never targets a
+ * remote daemon and is used only behind the explicit bridge recovery policy.
+ */
+export class WindowsDockerDesktopRecoveryExecutor {
+    platform;
+    commands;
+    programFiles;
+    wait;
+    constructor(platform = process.platform, commands = new BoundedCommandRunner(), programFiles = process.env.ProgramFiles ?? "C:\\Program Files", wait = delayMs => new Promise(resolve => setTimeout(resolve, delayMs))) {
+        this.platform = platform;
+        this.commands = commands;
+        this.programFiles = programFiles;
+        this.wait = wait;
+    }
+    async restart() {
+        if (this.platform !== "win32") {
+            return { started: false, reason: "Automatic Docker Desktop recovery is supported only on Windows." };
+        }
+        const installRoot = path.join(this.programFiles, "Docker", "Docker");
+        const desktopExecutable = path.join(installRoot, "Docker Desktop.exe");
+        if (!fs.existsSync(desktopExecutable)) {
+            return { started: false, reason: "Docker Desktop executable was not found in the standard installation directory." };
+        }
+        const processState = await this.readProcessState();
+        if (processState === "unknown") {
+            return { started: false, reason: "Docker Desktop process state could not be determined safely." };
+        }
+        if (processState === "stopped") {
+            if (!await this.cleanupOrphanedCompanions()) {
+                return { started: false, reason: "Orphaned Docker Desktop companion processes could not be verified and cleaned safely." };
+            }
+            await this.wait(1_000);
+            return await this.startDesktop(desktopExecutable);
+        }
+        const dockerCli = path.join(installRoot, "DockerCli.exe");
+        if (fs.existsSync(dockerCli)) {
+            await this.commands.run(dockerCli, ["-Shutdown"], {
+                timeoutMs: 15_000,
+                maxOutputBytes: 64 * 1024,
+            }).catch(() => undefined);
+        }
+        const stopScript = [
+            "$ErrorActionPreference = 'SilentlyContinue'",
+            "Get-Process | Where-Object { $_.ProcessName -in @('Docker Desktop', 'com.docker.backend') } | Stop-Process -Force",
+        ].join("; ");
+        await this.commands.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", stopScript], {
+            timeoutMs: 15_000,
+            maxOutputBytes: 64 * 1024,
+        }).catch(() => undefined);
+        await this.commands.run("wsl.exe", ["--terminate", "docker-desktop"], {
+            timeoutMs: 15_000,
+            maxOutputBytes: 64 * 1024,
+        }).catch(() => undefined);
+        await this.wait(5_000);
+        const stoppedState = await this.readProcessState();
+        if (stoppedState !== "stopped") {
+            return {
+                started: false,
+                reason: stoppedState === "running"
+                    ? "Docker Desktop processes did not stop before relaunch."
+                    : "Docker Desktop shutdown state could not be verified safely.",
+            };
+        }
+        if (!await this.cleanupOrphanedCompanions()) {
+            return { started: false, reason: "Orphaned Docker Desktop companion processes could not be verified and cleaned safely." };
+        }
+        await this.wait(1_000);
+        return await this.startDesktop(desktopExecutable);
+    }
+    async readProcessState() {
+        const script = [
+            "$ErrorActionPreference = 'Stop'",
+            "$processes = @(Get-Process -Name 'Docker Desktop','com.docker.backend' -ErrorAction SilentlyContinue)",
+            "if ($processes.Count -gt 0) { Write-Output 'running' } else { Write-Output 'stopped' }",
+        ].join("; ");
+        const result = await this.commands.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { timeoutMs: 5_000, maxOutputBytes: 16 * 1024 }).catch(() => null);
+        if (!result || result.exitCode !== 0)
+            return "unknown";
+        const state = result.stdout.trim().toLowerCase();
+        return state === "running" || state === "stopped" ? state : "unknown";
+    }
+    async cleanupOrphanedCompanions() {
+        const dockerRoot = path.join(this.programFiles, "Docker").replaceAll("'", "''");
+        const script = [
+            "$ErrorActionPreference = 'Stop'",
+            `$dockerRoot = [System.IO.Path]::GetFullPath('${dockerRoot}').TrimEnd('\\') + '\\'`,
+            "$names = @('com.docker.build.exe','docker-sandbox.exe','docker-agent.exe','local-sandboxesd.exe','docker-sandboxd.exe')",
+            "$candidates = @(Get-CimInstance Win32_Process | Where-Object { $_.Name -in $names -and $_.ExecutablePath -and [System.IO.Path]::GetFullPath($_.ExecutablePath).StartsWith($dockerRoot, [System.StringComparison]::OrdinalIgnoreCase) })",
+            "foreach ($candidate in $candidates) { $parent = Get-CimInstance Win32_Process -Filter ('ProcessId=' + $candidate.ParentProcessId) -ErrorAction SilentlyContinue; $parentIsDockerBackend = $null -ne $parent -and $parent.Name -eq 'com.docker.backend.exe' -and $parent.ExecutablePath -and [System.IO.Path]::GetFullPath($parent.ExecutablePath).StartsWith($dockerRoot, [System.StringComparison]::OrdinalIgnoreCase); if (-not $parentIsDockerBackend) { Stop-Process -Id $candidate.ProcessId -Force -ErrorAction Stop } }",
+        ].join("; ");
+        const result = await this.commands.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { timeoutMs: 10_000, maxOutputBytes: 32 * 1024 }).catch(() => null);
+        return result?.exitCode === 0;
+    }
+    async startDesktop(desktopExecutable) {
+        const quotedDesktop = desktopExecutable.replaceAll("'", "''");
+        let lastReason = "Docker Desktop failed to start.";
+        for (let attempt = 1; attempt <= 3; attempt += 1) {
+            const startScript = [
+                "$ErrorActionPreference = 'Stop'",
+                `$desktop = Start-Process -FilePath '${quotedDesktop}' -WindowStyle Hidden -PassThru`,
+                "Start-Sleep -Seconds 3",
+                "if ($desktop.HasExited) { Write-Error ('Docker Desktop exited during startup with code ' + $desktop.ExitCode); exit 1 }",
+            ].join("; ");
+            const start = await this.commands.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", startScript], { timeoutMs: 15_000, maxOutputBytes: 64 * 1024 }).catch((error) => ({
+                exitCode: 1,
+                stdout: "",
+                stderr: error instanceof Error ? error.message : String(error),
+            }));
+            if (start.exitCode === 0)
+                return { started: true };
+            lastReason = start.stderr || start.stdout || lastReason;
+            if (attempt < 3)
+                await this.wait(5_000);
+        }
+        return { started: false, reason: singleLine(lastReason) };
+    }
+}
+function unavailable(context, code, reason) {
+    return {
+        available: false,
+        sampledAt: new Date().toISOString(),
+        runtimeVersion: null,
+        operatingSystem: null,
+        context,
+        unavailableCode: code,
+        unavailableReason: singleLine(reason),
+    };
+}
+function clean(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function singleLine(value) {
+    return value.replace(/[\r\n\t]+/gu, " ").trim().slice(0, 1000);
+}
+function positiveInteger(value, fallback) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.floor(value);
+}

package/dist/runtime/generated-output-reset.d.ts

@@ -1,10 +1,20 @@
+export declare function isGeneratedOutputDirectoryName(name: string): boolean;
+/**
+ * Returns the generated-output directory that contains a Git-relative path,
+ * provided the reset walker would reach it. Paths below discovery boundaries
+ * such as node_modules or .forge are intentionally not reset candidates.
+ */
+export declare function generatedOutputRootForPath(relativePath: string): string | null;
 export interface GeneratedOutputResetResult {
     readonly quarantineDirectory: string;
     readonly quarantinedPaths: readonly string[];
+    readonly retainedPaths: readonly string[];
 }
 /**
  * Moves only known, untracked test-output directories out of a worktree before
  * a managed attempt starts. The quarantine lives in the attempt-owned output
  * directory, so cleanup is recoverable and cannot cross the attempt boundary.
+ * A directory with tracked files is committed source, such as recorded test
+ * evidence, so it is left untouched and reported instead of being moved.
  */
 export declare function resetGeneratedOutputs(worktreePath: string, testOutputDirectory: string): Promise<GeneratedOutputResetResult>;

package/dist/runtime/generated-output-reset.js

@@ -22,10 +22,31 @@ const skippedDirectoryNames = new Set([
     "target",
     "vendor",
 ]);
+export function isGeneratedOutputDirectoryName(name) {
+    return generatedDirectoryNames.has(name);
+}
+/**
+ * Returns the generated-output directory that contains a Git-relative path,
+ * provided the reset walker would reach it. Paths below discovery boundaries
+ * such as node_modules or .forge are intentionally not reset candidates.
+ */
+export function generatedOutputRootForPath(relativePath) {
+    const segments = relativePath.replaceAll("\\", "/").split("/").filter(Boolean);
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        if (skippedDirectoryNames.has(segment))
+            return null;
+        if (isGeneratedOutputDirectoryName(segment))
+            return segments.slice(0, index + 1).join("/");
+    }
+    return null;
+}
 /**
  * Moves only known, untracked test-output directories out of a worktree before
  * a managed attempt starts. The quarantine lives in the attempt-owned output
  * directory, so cleanup is recoverable and cannot cross the attempt boundary.
+ * A directory with tracked files is committed source, such as recorded test
+ * evidence, so it is left untouched and reported instead of being moved.
  */
 export async function resetGeneratedOutputs(worktreePath, testOutputDirectory) {
     const worktreeRoot = await fs.realpath(path.resolve(worktreePath));
@@ -36,17 +57,21 @@ export async function resetGeneratedOutputs(worktreePath, testOutputDirectory) {
     const candidates = await findGeneratedDirectories(worktreeRoot);
     const quarantineDirectory = path.join(outputRoot, "preflight-reset");
     const quarantinedPaths = [];
+    const retainedPaths = [];
     for (const candidate of candidates) {
         const relativePath = path.relative(worktreeRoot, candidate);
         if (!relativePath || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
             throw new Error("generated_output_reset_invalid: generated output escaped the source worktree.");
         }
-        await assertUntrackedGeneratedDirectory(worktreeRoot, relativePath);
+        if (await containsTrackedFiles(worktreeRoot, relativePath)) {
+            retainedPaths.push(relativePath.split(path.sep).join("/"));
+            continue;
+        }
         await fs.mkdir(quarantineDirectory, { recursive: true, mode: 0o700 });
         const digest = createHash("sha256").update(relativePath).digest("hex").slice(0, 12);
         const destination = path.join(quarantineDirectory, `${digest}-${randomUUID()}-${path.basename(candidate)}`);
         try {
-            await fs.rename(candidate, destination);
+            await quarantineGeneratedDirectory(candidate, destination);
         }
         catch (error) {
             const code = error.code ?? "unknown";
@@ -57,7 +82,38 @@ export async function resetGeneratedOutputs(worktreePath, testOutputDirectory) {
     if (quarantinedPaths.length > 0) {
         await fs.writeFile(path.join(quarantineDirectory, "manifest.json"), `${JSON.stringify({ schemaVersion: 1, worktreePath: worktreeRoot, quarantinedPaths }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
     }
-    return { quarantineDirectory, quarantinedPaths };
+    return { quarantineDirectory, quarantinedPaths, retainedPaths };
+}
+async function quarantineGeneratedDirectory(source, destination) {
+    try {
+        await fs.rename(source, destination);
+        return;
+    }
+    catch (error) {
+        if (error.code !== "EXDEV")
+            throw error;
+    }
+    // Windows installations commonly keep repositories on a data volume while
+    // the short per-user attempt root remains on the system volume. rename(2)
+    // cannot cross that boundary, so stage a complete copy on the destination
+    // volume, publish it there atomically, and only then remove the untracked
+    // source directory. A failed copy leaves the source untouched.
+    const staging = `${destination}.copying`;
+    try {
+        await fs.cp(source, staging, {
+            recursive: true,
+            force: false,
+            errorOnExist: true,
+            dereference: false,
+            verbatimSymlinks: true,
+        });
+        await fs.rename(staging, destination);
+        await fs.rm(source, { recursive: true, force: false });
+    }
+    catch (error) {
+        await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
 }
 async function findGeneratedDirectories(root) {
     const candidates = [];
@@ -71,7 +127,7 @@ async function findGeneratedDirectories(root) {
             if (skippedDirectoryNames.has(entry.name))
                 continue;
             const candidate = path.join(current, entry.name);
-            if (generatedDirectoryNames.has(entry.name)) {
+            if (isGeneratedOutputDirectoryName(entry.name)) {
                 const realCandidate = await fs.realpath(candidate);
                 if (!isContainedPath(root, realCandidate)) {
                     throw new Error("generated_output_reset_invalid: generated output resolves outside the source worktree.");
@@ -84,7 +140,7 @@ async function findGeneratedDirectories(root) {
     }
     return candidates.sort((left, right) => left.localeCompare(right));
 }
-async function assertUntrackedGeneratedDirectory(worktreeRoot, relativePath) {
+async function containsTrackedFiles(worktreeRoot, relativePath) {
     const pathspec = relativePath.split(path.sep).join("/");
     let stdout;
     try {
@@ -93,9 +149,7 @@ async function assertUntrackedGeneratedDirectory(worktreeRoot, relativePath) {
     catch (error) {
         throw new Error(`generated_output_reset_unverified: git could not verify ${pathspec}.`, { cause: error });
     }
-    if (stdout.length > 0) {
-        throw new Error(`generated_output_reset_unsafe: ${pathspec} contains tracked files and was not changed.`);
-    }
+    return stdout.length > 0;
 }
 function isContainedPath(root, candidate) {
     const relative = path.relative(root, candidate);

package/dist/runtime/host-database-capability-boundary.d.ts

@@ -0,0 +1,16 @@
+export declare const hostDatabaseCapabilityEnvironmentNames: readonly ["FORGE_TEST_POSTGRES_ADMIN_CONNECTION_STRING", "FORGE_TEST_POSTGRES_CONNECTION_STRING"];
+export interface HostDatabaseCapabilityBoundaryOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly processEnvironment?: NodeJS.ProcessEnv;
+    readonly inspectWindowsUserEnvironment?: boolean;
+    readonly windowsUserCapabilityPresent?: () => boolean;
+}
+/**
+ * Fails before untrusted host work can start when a PostgreSQL administrator
+ * capability is reachable through either the process or Windows User scope.
+ * The default Windows probe returns only presence; it never reads the value
+ * into JavaScript or emits it in diagnostics.
+ */
+export declare function assertHostDatabaseCapabilityBoundary(options?: HostDatabaseCapabilityBoundaryOptions): void;
+/** Establishes the production Bridge boundary and enables per-launch rechecks. */
+export declare function establishHostDatabaseCapabilityBoundary(): void;

package/dist/runtime/host-database-capability-boundary.js

@@ -0,0 +1,62 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export const hostDatabaseCapabilityEnvironmentNames = [
+    "FORGE_TEST_POSTGRES_ADMIN_CONNECTION_STRING",
+    "FORGE_TEST_POSTGRES_CONNECTION_STRING",
+];
+const boundaryAttestationEnvironment = "FORGE_HOST_DATABASE_CAPABILITY_BOUNDARY";
+const boundaryAttestationValue = "user_store_clear";
+/**
+ * Fails before untrusted host work can start when a PostgreSQL administrator
+ * capability is reachable through either the process or Windows User scope.
+ * The default Windows probe returns only presence; it never reads the value
+ * into JavaScript or emits it in diagnostics.
+ */
+export function assertHostDatabaseCapabilityBoundary(options = {}) {
+    const processEnvironment = options.processEnvironment ?? process.env;
+    const reserved = new Set(hostDatabaseCapabilityEnvironmentNames.map(name => name.toLowerCase()));
+    const processCapabilityPresent = Object.entries(processEnvironment).some(([name, value]) => reserved.has(name.toLowerCase()) && typeof value === "string" && value.trim().length > 0);
+    if (processCapabilityPresent) {
+        throw boundaryError("process");
+    }
+    if ((options.platform ?? process.platform) !== "win32")
+        return;
+    const inspectWindowsUserEnvironment = options.inspectWindowsUserEnvironment
+        ?? processEnvironment[boundaryAttestationEnvironment] === boundaryAttestationValue;
+    if (!inspectWindowsUserEnvironment)
+        return;
+    const windowsUserCapabilityPresent = options.windowsUserCapabilityPresent
+        ?? inspectWindowsUserCapabilityPresence;
+    if (windowsUserCapabilityPresent()) {
+        throw boundaryError("Windows User");
+    }
+}
+/** Establishes the production Bridge boundary and enables per-launch rechecks. */
+export function establishHostDatabaseCapabilityBoundary() {
+    assertHostDatabaseCapabilityBoundary({ inspectWindowsUserEnvironment: true });
+    process.env[boundaryAttestationEnvironment] = boundaryAttestationValue;
+}
+function inspectWindowsUserCapabilityPresence() {
+    const systemRoot = process.env.SystemRoot?.trim() || process.env.WINDIR?.trim();
+    const executable = systemRoot
+        ? path.win32.join(systemRoot, "System32", "reg.exe")
+        : "reg.exe";
+    for (const name of hostDatabaseCapabilityEnvironmentNames) {
+        const result = spawnSync(executable, ["query", "HKCU\\Environment", "/v", name], {
+            stdio: "ignore",
+            timeout: 10_000,
+            windowsHide: true,
+        });
+        if (result.status === 0)
+            return true;
+        // reg.exe uses exit code 1 for a missing value. Any other result is an
+        // unverifiable boundary and must fail closed without exposing registry data.
+        if (result.status !== 1 || result.signal || result.error) {
+            throw new Error("host_database_capability_boundary_unverified: the Windows User environment could not be inspected safely.", { cause: result.error });
+        }
+    }
+    return false;
+}
+function boundaryError(scope) {
+    return new Error(`host_database_capability_forbidden: a PostgreSQL administrative capability is present in ${scope} scope; Forge-managed host execution is container-only until an isolated provisioning broker is available.`);
+}

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

@@ -0,0 +1,11 @@
+import type { PinnedDirectoryIdentity } from "./pinned-directory-process.js";
+export interface HostDiagnosticsRetentionOptions {
+    /** Test-only shortening; production callers cannot extend the safety deadline. */
+    readonly deadlineMs?: number;
+}
+export declare class HostDiagnosticsBudgetError extends Error {
+    constructor(message: string);
+}
+/** Runner-local evidence, never web-served; browser-profile, cache and temporary directories are excluded. */
+export declare function retainHostDiagnostics(stateRoot: string, attemptRoot: string, attemptId: string, expectedAttemptRootIdentity: PinnedDirectoryIdentity | null, attemptOwnerRoot?: string, options?: HostDiagnosticsRetentionOptions): Promise<string>;
+export declare function assertHostAttemptRootIdentity(attemptRoot: string, expected: PinnedDirectoryIdentity): Promise<void>;