@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.1ff37038366e

package/dist/runtime/canonical-source-file.js

@@ -0,0 +1,54 @@
+import { constants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+/** Keep the validated source inode open: reopening a checked pathname can follow a replacement. */
+export async function readCanonicalSourceFile(target, maximumBytes, expectedIdentity) {
+    const resolved = path.resolve(target);
+    const pathBefore = await canonicalStat(resolved);
+    if (expectedIdentity && !sameFile(pathBefore, expectedIdentity)) {
+        throw new Error("host_runtime_source_changed: source identity changed before reading.");
+    }
+    const handle = await fs.open(resolved, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)
+        | (constants.O_NONBLOCK ?? 0));
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile() || before.nlink !== 1n || !sameFile(pathBefore, before) || before.size > BigInt(maximumBytes)) {
+            throw new Error("host_runtime_source_invalid: source changed or exceeds the byte bound.");
+        }
+        if (!sameFile(before, await canonicalStat(resolved))) {
+            throw new Error("host_runtime_source_changed: source changed before reading.");
+        }
+        const bytes = Buffer.alloc(Number(before.size));
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = await handle.read(bytes, offset, bytes.length - offset, offset);
+            if (!read.bytesRead)
+                throw new Error("host_runtime_source_changed: incomplete source read.");
+            offset += read.bytesRead;
+        }
+        const after = await handle.stat({ bigint: true });
+        const pathAfter = await canonicalStat(resolved);
+        if (after.nlink !== 1n || !sameFile(before, after) || !sameFile(after, pathAfter) || before.size !== after.size
+            || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs) {
+            throw new Error("host_runtime_source_changed: source changed while reading.");
+        }
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function canonicalStat(target) {
+    const stat = await fs.lstat(target, { bigint: true });
+    const real = await fs.realpath(target);
+    const realStat = await fs.lstat(real, { bigint: true });
+    const samePath = process.platform === "win32" ? real.toLowerCase() === target.toLowerCase() : real === target;
+    if (!samePath || !stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1n || !realStat.isFile()
+        || realStat.isSymbolicLink() || realStat.nlink !== 1n || !sameFile(stat, realStat)) {
+        throw new Error("host_runtime_source_invalid: source must be a canonical regular file.");
+    }
+    return realStat;
+}
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}

package/dist/runtime/docker-engine-probe.d.ts

@@ -0,0 +1,90 @@
+import type { CommandRunner } from "../sandbox/sandbox.types.js";
+export interface DockerEngineCapabilitySnapshot {
+    readonly available: boolean;
+    readonly sampledAt: string;
+    readonly runtimeVersion: string | null;
+    readonly operatingSystem: string | null;
+    readonly context: string;
+    readonly unavailableCode: string | null;
+    readonly unavailableReason: string | null;
+}
+export interface DockerEngineProbeOptions {
+    readonly dockerExecutable?: string;
+    readonly dockerContext?: string;
+    readonly recovery?: DockerEngineRecoveryPolicy;
+    readonly recoveryExecutor?: DockerEngineRecoveryExecutor;
+    readonly platform?: NodeJS.Platform;
+    readonly dockerHost?: string;
+    readonly now?: () => number;
+    readonly wait?: (delayMs: number) => Promise<void>;
+    readonly onStatus?: (message: string) => void;
+}
+export interface DockerEngineRecoveryPolicy {
+    readonly enabled: boolean;
+    readonly failureThreshold?: number;
+    readonly confirmationDelayMs?: number;
+    readonly cooldownMs?: number;
+    readonly startupTimeoutMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly canRecover?: () => boolean;
+}
+export interface DockerEngineRecoveryResult {
+    readonly started: boolean;
+    readonly reason?: string;
+}
+export interface DockerEngineRecoveryExecutor {
+    restart(): Promise<DockerEngineRecoveryResult>;
+}
+/**
+ * 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 declare class DockerEngineProbe {
+    private readonly commands;
+    private readonly cacheMs;
+    private cached;
+    private sampledAtMs;
+    private inFlight;
+    private requiredWorkRecoveryInFlight;
+    private consecutiveFailures;
+    private lastRecoveryAttemptAtMs;
+    private readonly docker;
+    private readonly context;
+    private readonly platform;
+    private readonly dockerHost;
+    private readonly now;
+    private readonly wait;
+    private readonly recovery;
+    private readonly recoveryExecutor;
+    private readonly onStatus;
+    constructor(options?: DockerEngineProbeOptions, commands?: CommandRunner, cacheMs?: number);
+    current(): DockerEngineCapabilitySnapshot | null;
+    refresh(force?: boolean): Promise<DockerEngineCapabilitySnapshot>;
+    /**
+     * 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.
+     */
+    ensureAvailableForRequiredWork(): Promise<DockerEngineCapabilitySnapshot>;
+    private inspectSafely;
+    private recoverIfEligible;
+    private isLocalDockerDesktopContext;
+    private inspect;
+}
+/**
+ * Restarts only the local Docker Desktop installation. It never targets a
+ * remote daemon and is used only behind the explicit bridge recovery policy.
+ */
+export declare class WindowsDockerDesktopRecoveryExecutor implements DockerEngineRecoveryExecutor {
+    private readonly platform;
+    private readonly commands;
+    private readonly programFiles;
+    private readonly wait;
+    constructor(platform?: NodeJS.Platform, commands?: CommandRunner, programFiles?: string, wait?: (delayMs: number) => Promise<void>);
+    restart(): Promise<DockerEngineRecoveryResult>;
+    private readProcessState;
+    private cleanupOrphanedCompanions;
+    private startDesktop;
+}

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

@@ -0,0 +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

@@ -0,0 +1,157 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const generatedDirectoryNames = new Set(["TestResults", "test-results", "playwright-report"]);
+const skippedDirectoryNames = new Set([
+    ".git",
+    ".forge",
+    ".idea",
+    ".next",
+    ".pnpm",
+    ".vs",
+    ".vscode",
+    "bin",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "obj",
+    "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));
+    const outputRoot = await fs.realpath(path.resolve(testOutputDirectory));
+    if (isContainedPath(worktreeRoot, outputRoot)) {
+        throw new Error("generated_output_reset_invalid: attempt output must be outside the source worktree.");
+    }
+    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.");
+        }
+        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 quarantineGeneratedDirectory(candidate, destination);
+        }
+        catch (error) {
+            const code = error.code ?? "unknown";
+            throw new Error(`generated_output_reset_failed: could not quarantine ${relativePath} (${code}).`, { cause: error });
+        }
+        quarantinedPaths.push(relativePath.split(path.sep).join("/"));
+    }
+    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, 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 = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const entries = await fs.readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            if (skippedDirectoryNames.has(entry.name))
+                continue;
+            const candidate = path.join(current, 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.");
+                }
+                candidates.push(realCandidate);
+                continue;
+            }
+            pending.push(candidate);
+        }
+    }
+    return candidates.sort((left, right) => left.localeCompare(right));
+}
+async function containsTrackedFiles(worktreeRoot, relativePath) {
+    const pathspec = relativePath.split(path.sep).join("/");
+    let stdout;
+    try {
+        ({ stdout } = await execFileAsync("git", ["-C", worktreeRoot, "ls-files", "-z", "--", pathspec], { encoding: "utf8", windowsHide: true, maxBuffer: 4 * 1024 * 1024 }));
+    }
+    catch (error) {
+        throw new Error(`generated_output_reset_unverified: git could not verify ${pathspec}.`, { cause: error });
+    }
+    return stdout.length > 0;
+}
+function isContainedPath(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative.length > 0 && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}

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;