@loucompanion/forge-bridge 0.1.3-dev.9d8f2e7e5241 → 0.1.3-dev.a58d7cd1092f

package/dist/sandbox/preflight.js

@@ -1,7 +1,10 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { formatBytes } from "../shared/format/format-bytes.js";
+import { captureHostProcessIdentity } from "../shared/process/host-process-supervisor.js";
+import { RecoveryStabilizedMemory, resolveAdaptiveMemoryReserveBytes } from "../runtime/memory-capacity.js";
 import { BoundedCommandRunner } from "./command-runner.js";
 const minimumWorkspaceBytes = 10 * 1024 * 1024 * 1024;
 export class DockerPreflight {
@@ -9,17 +12,35 @@ export class DockerPreflight {
     cacheMs;
     generation = 0;
     cached = null;
-    cacheAt = 0;
+    fullPreflightAt = 0;
+    staticPreflight = null;
+    inspectionInFlight = null;
+    lastCapacitySample = null;
     options;
     docker;
     ownership = new DockerContextOwnershipLock();
     diskPressureLatched = false;
+    memoryAvailability = new RecoveryStabilizedMemory();
     constructor(options = {}, commands = new BoundedCommandRunner(), cacheMs = 30_000) {
         this.commands = commands;
         this.cacheMs = cacheMs;
         this.options = typeof options === "string" ? { dockerExecutable: options } : options;
         this.docker = this.options.dockerExecutable ?? process.env.FORGE_DOCKER_EXECUTABLE ?? "docker";
     }
+    unavailable(code, reason, features) {
+        const totalMemoryBytes = os.totalmem();
+        this.memoryAvailability.observe(0);
+        return unavailable(this.generation, code, reason, this.memoryReserveBytes(totalMemoryBytes), this.defaultAdmissionMemoryBytes(), totalMemoryBytes, features);
+    }
+    memoryReserveBytes(totalMemoryBytes) {
+        return resolveSandboxHostMemoryReserveBytes(totalMemoryBytes, this.options.hostMemoryReserveBytes);
+    }
+    defaultAdmissionMemoryBytes() {
+        const workerMemoryLimitBytes = positiveInteger(this.options.defaultWorkerMemoryLimitBytes, 2 * 1024 ** 3);
+        const serviceMemoryLimitBytes = nonNegativeInteger(this.options.defaultServiceMemoryLimitBytes, 0);
+        const runtimeOverheadBytes = Math.max(128 * 1024 ** 2, nonNegativeInteger(this.options.runtimeOverheadBytes, 128 * 1024 ** 2));
+        return workerMemoryLimitBytes + serviceMemoryLimitBytes + runtimeOverheadBytes;
+    }
     current() {
         return this.cached;
     }
@@ -35,25 +56,97 @@ export class DockerPreflight {
         await this.ownership.release();
     }
     async run(force = false) {
-        if (!force && this.cached && Date.now() - this.cacheAt < this.cacheMs)
+        const inFlight = this.inspectionInFlight;
+        if (inFlight) {
+            const result = await inFlight.promise;
+            if (inFlight.kind === "full" || (!force && Date.now() - this.fullPreflightAt < this.cacheMs)) {
+                return result;
+            }
+            return await this.run(force);
+        }
+        if (!force && this.cached && Date.now() - this.fullPreflightAt < this.cacheMs)
             return this.cached;
+        return await this.startInspection("full", () => this.inspect().catch((error) => this.unavailable("docker_unreachable", error instanceof Error ? error.message : String(error))), true);
+    }
+    /**
+     * Refreshes only the admission inputs that change while the daemon's static
+     * capability snapshot remains valid. Heartbeats use this path so periodic
+     * liveness reporting does not wake Docker/WSL to rerun feature probes.
+     */
+    async refreshCapacity() {
+        if (this.inspectionInFlight) {
+            return await this.inspectionInFlight.promise;
+        }
+        const staticPreflight = this.staticPreflight;
+        if (!staticPreflight || !this.cached || !canRunDockerMaintenance(this.cached)) {
+            return this.cached ?? this.unavailable("docker_preflight_required", "Docker capability preflight has not completed.");
+        }
+        return await this.startInspection("capacity", () => this.inspectCapacity(staticPreflight).catch((error) => this.unavailable("docker_capacity_unavailable", error instanceof Error ? error.message : String(error), staticPreflight.features)), false);
+    }
+    /**
+     * When the cached static preflight remains usable, produces a capacity sample
+     * that began after this admission request. An older inspection is awaited,
+     * not preempted or reused. Later admission callers may share the next sample
+     * only when it began after they entered this method. Without a usable static
+     * snapshot, the existing fail-closed result is returned without probing.
+     */
+    async refreshCapacityForAdmission() {
+        const generationAtRequest = this.generation;
+        while (true) {
+            const inFlight = this.inspectionInFlight;
+            if (inFlight) {
+                if (inFlight.kind === "capacity" && inFlight.generation > generationAtRequest) {
+                    return await inFlight.promise;
+                }
+                await inFlight.promise;
+                continue;
+            }
+            const lastCapacitySample = this.lastCapacitySample;
+            if (lastCapacitySample
+                && lastCapacitySample.generation > generationAtRequest
+                && lastCapacitySample.generation === this.generation
+                && lastCapacitySample.result === this.cached) {
+                return lastCapacitySample.result;
+            }
+            const staticPreflight = this.staticPreflight;
+            if (!staticPreflight || !this.cached || !canRunDockerMaintenance(this.cached)) {
+                return this.cached ?? this.unavailable("docker_preflight_required", "Docker capability preflight has not completed.");
+            }
+            return await this.startInspection("capacity", () => this.inspectCapacity(staticPreflight).catch((error) => this.unavailable("docker_capacity_unavailable", error instanceof Error ? error.message : String(error), staticPreflight.features)), false);
+        }
+    }
+    startInspection(kind, inspect, full) {
         this.generation += 1;
-        const result = await this.inspect().catch((error) => unavailable(this.generation, "docker_unreachable", error instanceof Error ? error.message : String(error)));
-        this.cached = result;
-        this.cacheAt = Date.now();
-        return result;
+        const generation = this.generation;
+        const operation = Promise.resolve()
+            .then(inspect)
+            .then((result) => {
+            this.cached = result;
+            if (kind === "capacity")
+                this.lastCapacitySample = { generation, result };
+            if (full)
+                this.fullPreflightAt = Date.now();
+            return result;
+        })
+            .finally(() => {
+            if (this.inspectionInFlight?.promise === operation) {
+                this.inspectionInFlight = null;
+            }
+        });
+        this.inspectionInFlight = { kind, generation, promise: operation };
+        return operation;
     }
     async inspect() {
         if (!new Set(["linux", "darwin", "win32"]).has(process.platform)) {
-            return unavailable(this.generation, "platform_unsupported", `Docker sandboxes are not supported on ${process.platform}.`);
+            return this.unavailable("platform_unsupported", `Docker sandboxes are not supported on ${process.platform}.`);
         }
         const dockerArgs = this.options.dockerContext ? ["--context", this.options.dockerContext] : [];
         const infoResult = await this.commands.run(this.docker, [...dockerArgs, "info", "--format", "{{json .}}"], { timeoutMs: 10_000, maxOutputBytes: 512 * 1024 });
         if (infoResult.exitCode !== 0)
-            return unavailable(this.generation, "docker_unreachable", singleLine(infoResult.stderr || infoResult.stdout || "Docker daemon is unreachable."));
+            return this.unavailable("docker_unreachable", singleLine(infoResult.stderr || infoResult.stdout || "Docker daemon is unreachable."));
         const info = parseInfo(infoResult.stdout);
         if (String(info.OSType ?? "").toLowerCase() !== "linux")
-            return unavailable(this.generation, "docker_linux_required", "Forge sandbox images require a Linux Docker daemon.");
+            return this.unavailable("docker_linux_required", "Forge sandbox images require a Linux Docker daemon.");
         const securityOptions = strings(info.SecurityOptions).map((value) => value.toLowerCase());
         const rootless = securityOptions.some((value) => value.includes("rootless"));
         const userNamespaces = rootless || securityOptions.some((value) => value.includes("userns"));
@@ -65,7 +158,7 @@ export class DockerPreflight {
         const desktopDeveloperMode = process.platform !== "linux" && process.env.FORGE_ALLOW_DOCKER_DESKTOP_SANDBOX === "true";
         const requireRootless = this.options.requireRootless ?? process.env.FORGE_SANDBOX_REQUIRE_ROOTLESS !== "false";
         if (!rootless && !desktopDeveloperMode && requireRootless) {
-            return unavailable(this.generation, "docker_rootless_required", "Docker daemon is reachable but is not running rootless.", {
+            return this.unavailable("docker_rootless_required", "Docker daemon is reachable but is not running rootless.", {
                 rootless, userNamespaces, cgroupV2, seccomp, lsm, storageQuota, storagePolicy: false, compose: false, internalNetwork: true, buildkit: false, imagePolicy: false, securityProfile: false, egressProxy: false
             });
         }
@@ -81,7 +174,7 @@ export class DockerPreflight {
             && buildxPruneHelp?.exitCode === 0
             && ["--max-used-space", "--min-free-space", "--reserved-space"].every(flag => buildxPruneHelp.stdout.includes(flag))
             && containerUpdateHelp?.exitCode === 0
-            && containerUpdateHelp.stdout.includes("--pids-limit");
+            && ["--pids-limit", "--memory", "--memory-swap"].every(flag => containerUpdateHelp.stdout.includes(flag));
         const imagePolicy = process.env.FORGE_SANDBOX_IMAGE_POLICY_ENFORCED === "true"
             && Boolean(process.env.FORGE_SANDBOX_SBOM_EXECUTABLE?.trim())
             && Boolean(process.env.FORGE_SANDBOX_VULNERABILITY_EXECUTABLE?.trim())
@@ -99,50 +192,154 @@ export class DockerPreflight {
         const dockerRoot = process.platform === "linux" && typeof info.DockerRootDir === "string" && path.isAbsolute(info.DockerRootDir)
             ? info.DockerRootDir
             : configuredStateRoot;
-        const disk = await diskSpace(dockerRoot);
+        const dockerDesktop = process.platform !== "linux"
+            && String(info.OperatingSystem ?? "").toLowerCase().includes("docker desktop");
+        const reportedDockerMemoryBytes = Number(info.MemTotal);
+        const features = { rootless, userNamespaces, cgroupV2, seccomp, lsm, storageQuota, storagePolicy, compose, internalNetwork: true, buildkit, imagePolicy, securityProfile, egressProxy };
+        const staticPreflight = {
+            dockerArgs,
+            dockerRoot,
+            dockerDesktop,
+            dockerMemoryBytes: Number.isFinite(reportedDockerMemoryBytes) && reportedDockerMemoryBytes > 0
+                ? reportedDockerMemoryBytes
+                : null,
+            runtimeVersion: `docker/${String(info.ServerVersion ?? "unknown")}${rootless ? "-rootless" : "-desktop"}`,
+            features,
+        };
+        this.staticPreflight = staticPreflight;
+        return await this.inspectCapacity(staticPreflight);
+    }
+    async inspectCapacity(staticPreflight) {
+        const disk = await diskSpace(staticPreflight.dockerRoot);
         const requiredWorkspaceBytes = this.options.minimumWorkspaceBytes ?? minimumWorkspaceBytes;
         const highWatermark = Math.min(99, Math.max(1, this.options.diskHighWatermarkPercent ?? 90));
         const lowWatermark = Math.min(highWatermark - 1, Math.max(0, this.options.diskLowWatermarkPercent ?? highWatermark - 10));
         const diskLow = evaluateDiskPressure(disk.available, disk.total, requiredWorkspaceBytes, highWatermark, lowWatermark, this.diskPressureLatched);
         this.diskPressureLatched = diskLow;
-        const availableMemoryBytes = os.freemem();
+        const requiredAvailableBytes = requiredAvailableBytesToClearDiskPressure(disk.total, requiredWorkspaceBytes, lowWatermark);
+        const rawHostAvailableMemoryBytesBefore = Math.max(0, os.freemem());
+        const hostTotalMemoryBytes = os.totalmem();
+        let totalMemoryBytes = hostTotalMemoryBytes;
+        // Native Docker shares the host capacity domain. Docker Desktop has a
+        // second VM/daemon domain, so neither domain may be treated as a substitute
+        // for the other when deciding whether new committed memory is safe.
+        let rawDaemonAvailableMemoryBytes = rawHostAvailableMemoryBytesBefore;
+        let daemonMemorySampleFailure = null;
+        if (staticPreflight.dockerDesktop) {
+            rawDaemonAvailableMemoryBytes = null;
+            if (staticPreflight.dockerMemoryBytes) {
+                totalMemoryBytes = staticPreflight.dockerMemoryBytes;
+                const stats = await this.commands.run(this.docker, [...staticPreflight.dockerArgs, "stats", "--no-stream", "--format", "{{.MemUsage}}"], { timeoutMs: 10_000, maxOutputBytes: 512 * 1024 }).catch(() => null);
+                if (stats?.exitCode === 0) {
+                    let dockerUsedMemoryBytes = 0;
+                    for (const line of stats.stdout.split(/\r?\n/gu).map(value => value.trim()).filter(Boolean)) {
+                        const usage = tryParseDockerMemoryUsage(line);
+                        if (usage === null) {
+                            daemonMemorySampleFailure = "Docker returned an invalid memory-usage sample.";
+                            break;
+                        }
+                        dockerUsedMemoryBytes += usage;
+                    }
+                    if (daemonMemorySampleFailure === null) {
+                        rawDaemonAvailableMemoryBytes = Math.max(0, staticPreflight.dockerMemoryBytes - dockerUsedMemoryBytes);
+                    }
+                }
+                else {
+                    daemonMemorySampleFailure = singleLine(stats?.stderr || stats?.stdout || "Docker Desktop memory capacity could not be sampled.");
+                }
+            }
+            else {
+                daemonMemorySampleFailure = "Docker Desktop did not report a valid memory-capacity limit.";
+            }
+        }
+        const rawHostAvailableMemoryBytesAfter = Math.max(0, os.freemem());
+        const rawHostAvailableMemoryBytes = Math.min(rawHostAvailableMemoryBytesBefore, rawHostAvailableMemoryBytesAfter);
+        if (!staticPreflight.dockerDesktop) {
+            rawDaemonAvailableMemoryBytes = rawHostAvailableMemoryBytes;
+        }
+        const sampledAt = new Date().toISOString();
+        const rawAvailableMemoryBytes = rawDaemonAvailableMemoryBytes === null
+            ? 0
+            : Math.min(rawHostAvailableMemoryBytes, rawDaemonAvailableMemoryBytes);
+        const availableMemoryBytes = this.memoryAvailability.observe(rawAvailableMemoryBytes);
         const cpuCount = Math.max(1, os.availableParallelism?.() ?? os.cpus().length);
         const availableCpuMillis = Math.max(0, (cpuCount - 1) * 1000);
-        const memoryReserveBytes = 2 * 1024 ** 3;
-        const sandboxMemoryBytes = 2 * 1024 ** 3;
+        // The reserve protects the physical host and its control plane. Docker
+        // Desktop's VM total remains the independent daemon commitment ceiling,
+        // but must not shrink the reserve derived from the Windows host.
+        const memoryReserveBytes = this.memoryReserveBytes(hostTotalMemoryBytes);
+        const workerMemoryLimitBytes = positiveInteger(this.options.defaultWorkerMemoryLimitBytes, 2 * 1024 ** 3);
+        const serviceMemoryLimitBytes = nonNegativeInteger(this.options.defaultServiceMemoryLimitBytes, 0);
+        const runtimeOverheadBytes = Math.max(128 * 1024 ** 2, nonNegativeInteger(this.options.runtimeOverheadBytes, 128 * 1024 ** 2));
+        const sandboxMemoryBytes = workerMemoryLimitBytes + serviceMemoryLimitBytes + runtimeOverheadBytes;
+        const minimumAdmissionMemoryBytes = 128 * 1024 ** 2 + Math.max(128 * 1024 ** 2, runtimeOverheadBytes);
         const sandboxCpuMillis = 2_000;
-        const memorySlots = Math.max(0, Math.floor((availableMemoryBytes - memoryReserveBytes) / sandboxMemoryBytes));
         const cpuSlots = Math.max(0, Math.floor(availableCpuMillis / sandboxCpuMillis));
         const configuredMax = positiveInteger(this.options.maxConcurrentSandboxes, positiveInteger(process.env.FORGE_MAX_CONCURRENT_SANDBOXES, 3));
-        const capacityLowCode = !diskLow && memorySlots <= 0 ? "docker_memory_low" : !diskLow && cpuSlots <= 0 ? "docker_cpu_low" : null;
-        const maxConcurrentSandboxes = diskLow || capacityLowCode ? 0 : Math.min(3, configuredMax, cpuSlots, memorySlots);
+        const availableForAdmissionBytes = Math.max(0, availableMemoryBytes - memoryReserveBytes);
+        const capacityLowCode = !diskLow && rawDaemonAvailableMemoryBytes === null
+            ? "docker_memory_sample_unavailable"
+            : !diskLow && availableForAdmissionBytes < minimumAdmissionMemoryBytes
+                ? "docker_memory_low"
+                : !diskLow && cpuSlots <= 0
+                    ? "docker_cpu_low"
+                    : null;
+        const maxConcurrentSandboxes = diskLow || capacityLowCode ? 0 : Math.min(3, configuredMax, cpuSlots);
         const unavailableCode = diskLow ? "docker_disk_low" : capacityLowCode;
         const unavailableReason = diskLow
-            ? `Docker workspace has only ${disk.available} bytes available.`
-            : unavailableCode === "docker_memory_low"
-                ? `Docker host has ${availableMemoryBytes} bytes free; at least ${memoryReserveBytes + sandboxMemoryBytes} bytes are needed for one sandbox plus reserve.`
-                : unavailableCode === "docker_cpu_low"
-                    ? `Docker host has ${availableCpuMillis} available CPU millis; at least ${sandboxCpuMillis} are needed for one sandbox.`
-                    : null;
-        const features = { rootless, userNamespaces, cgroupV2, seccomp, lsm, storageQuota, storagePolicy, compose, internalNetwork: true, buildkit, imagePolicy, securityProfile, egressProxy };
+            ? `Docker workspace has ${formatBytes(disk.available)} available · ${formatBytes(requiredAvailableBytes)} required to clear disk pressure.`
+            : unavailableCode === "docker_memory_sample_unavailable"
+                ? `Docker Desktop memory capacity is unavailable (${daemonMemorySampleFailure ?? "unknown sampler failure"}); the host reports ${formatBytes(rawHostAvailableMemoryBytes)} free, but Forge will not admit a sandbox until both memory domains are known.`
+                : unavailableCode === "docker_memory_low"
+                    ? `${staticPreflight.dockerDesktop
+                        ? `The host reports ${formatBytes(rawHostAvailableMemoryBytes)} free and the Docker domain reports ${formatBytes(rawDaemonAvailableMemoryBytes ?? 0)} free; Forge uses the conservative ${formatBytes(rawAvailableMemoryBytes)} bound`
+                        : `Docker reports ${formatBytes(rawAvailableMemoryBytes)} free`} and reserves ${formatBytes(memoryReserveBytes)} for the host, leaving ${formatBytes(availableForAdmissionBytes)} for admission; the smallest supported sandbox requires ${formatBytes(minimumAdmissionMemoryBytes)}. Exact attempt memory is calculated dynamically from its worker profile, sidecars, and runtime helpers.`
+                    : unavailableCode === "docker_cpu_low"
+                        ? `Docker host has ${availableCpuMillis} available CPU millis; at least ${sandboxCpuMillis} are needed for one sandbox.`
+                        : null;
         const capacityAvailable = unavailableCode === null;
         return {
             available: capacityAvailable,
             healthy: capacityAvailable,
             generation: this.generation,
-            runtimeVersion: `docker/${String(info.ServerVersion ?? "unknown")}${rootless ? "-rootless" : "-desktop"}`,
+            sampledAt,
+            runtimeVersion: staticPreflight.runtimeVersion,
             maxConcurrentSandboxes,
+            totalMemoryBytes,
+            rawHostAvailableMemoryBytes,
+            rawDaemonAvailableMemoryBytes,
+            rawAvailableMemoryBytes,
             availableMemoryBytes,
+            hostReserveBytes: memoryReserveBytes,
+            admissionMemoryBytes: sandboxMemoryBytes,
             availableCpuMillis,
             availableWorkspaceBytes: disk.available,
             diskLow,
             unavailableCode,
             unavailableReason,
-            features,
+            features: staticPreflight.features,
         };
     }
 }
-const dockerMaintenanceUnavailableCodes = new Set(["docker_disk_low", "docker_memory_low", "docker_cpu_low"]);
+/**
+ * Uses the same reviewed reserve vector as host-runtime admission. The input
+ * is always the physical host total; Docker Desktop's VM total is tracked as
+ * a separate daemon commitment domain.
+ */
+export function resolveSandboxHostMemoryReserveBytes(totalMemoryBytes, explicitBytes, environment = process.env) {
+    return resolveAdaptiveMemoryReserveBytes(totalMemoryBytes, {
+        explicitBytes,
+        floorBytes: positiveInteger(environment.FORGE_SANDBOX_HOST_MEMORY_RESERVE_FLOOR_BYTES, 1024 ** 3),
+        ceilingBytes: positiveInteger(environment.FORGE_SANDBOX_HOST_MEMORY_RESERVE_CEILING_BYTES, 4 * 1024 ** 3),
+        percent: positiveNumber(environment.FORGE_SANDBOX_HOST_MEMORY_RESERVE_PERCENT, 12.5),
+    });
+}
+const dockerMaintenanceUnavailableCodes = new Set([
+    "docker_disk_low",
+    "docker_memory_low",
+    "docker_memory_sample_unavailable",
+    "docker_cpu_low",
+]);
 export function canRunDockerMaintenance(preflight) {
     return preflight.healthy || dockerMaintenanceUnavailableCodes.has(preflight.unavailableCode ?? "");
 }
@@ -156,39 +353,59 @@ export function evaluateDiskPressure(availableBytes, totalBytes, minimumAvailabl
         return true;
     return pressureLatched && usedPercent > lowWatermarkPercent;
 }
+export function requiredAvailableBytesToClearDiskPressure(totalBytes, minimumAvailableBytes, lowWatermarkPercent) {
+    const watermarkBytes = totalBytes > 0
+        ? Math.ceil(totalBytes * (1 - Math.min(100, Math.max(0, lowWatermarkPercent)) / 100))
+        : 0;
+    return Math.max(0, minimumAvailableBytes, watermarkBytes);
+}
 export function storagePolicyAvailable(storageQuota, environment = process.env) {
     return storageQuota || environment.FORGE_SANDBOX_DEDICATED_DISK === "true";
 }
 export class DockerContextOwnershipLock {
     lockPath = null;
+    lockToken = null;
     async acquire(contextName) {
         if (this.lockPath)
             return;
         contextName = contextName?.trim() || process.env.DOCKER_CONTEXT?.trim() || process.env.DOCKER_HOST?.trim() || "default";
         const key = createHash("sha256").update(contextName).digest("hex").slice(0, 24);
         const lockPath = path.join(os.tmpdir(), `forge-docker-context-${key}.lock`);
+        const token = randomUUID();
         await fs.mkdir(path.dirname(lockPath), { recursive: true });
         try {
             const handle = await fs.open(lockPath, "wx", 0o600);
-            await handle.writeFile(JSON.stringify({ pid: process.pid, contextName, acquiredAt: new Date().toISOString() }));
+            await handle.writeFile(JSON.stringify({
+                schemaVersion: 2,
+                token,
+                pid: process.pid,
+                processIdentity: captureHostProcessIdentity(process.pid),
+                contextName,
+                acquiredAt: new Date().toISOString(),
+            }));
             await handle.sync();
             await handle.close();
         }
         catch (error) {
             const owner = await readLock(lockPath);
-            if (owner?.pid && !processExists(owner.pid)) {
+            if (!dockerContextOwnerIsActive(owner)) {
                 await fs.rm(lockPath, { force: true });
                 return await this.acquire(contextName);
             }
             throw new Error(`docker_context_owned: Docker context '${contextName}' is already owned by Forge runner pid ${owner?.pid ?? "unknown"}.`, { cause: error });
         }
         this.lockPath = lockPath;
+        this.lockToken = token;
     }
     async release() {
         if (!this.lockPath)
             return;
-        await fs.rm(this.lockPath, { force: true });
+        const owner = await readLock(this.lockPath);
+        if (owner?.token === this.lockToken) {
+            await fs.rm(this.lockPath, { force: true });
+        }
         this.lockPath = null;
+        this.lockToken = null;
     }
 }
 function parseInfo(stdout) {
@@ -202,16 +419,24 @@ function parseInfo(stdout) {
         throw new Error("Docker returned an invalid info document.", { cause: error });
     }
 }
-function unavailable(generation, code, reason, features = {
+function unavailable(generation, code, reason, hostReserveBytes, admissionMemoryBytes, totalMemoryBytes, features = {
     rootless: false, userNamespaces: false, cgroupV2: false, seccomp: false, lsm: false, storageQuota: false, storagePolicy: false, compose: false, internalNetwork: false, buildkit: false, imagePolicy: false, securityProfile: false, egressProxy: false
 }) {
+    const rawHostAvailableMemoryBytes = Math.max(0, os.freemem());
     return {
         available: false,
         healthy: false,
         generation,
+        sampledAt: new Date().toISOString(),
         runtimeVersion: null,
         maxConcurrentSandboxes: 0,
-        availableMemoryBytes: os.freemem(),
+        totalMemoryBytes,
+        rawHostAvailableMemoryBytes,
+        rawDaemonAvailableMemoryBytes: null,
+        rawAvailableMemoryBytes: rawHostAvailableMemoryBytes,
+        availableMemoryBytes: rawHostAvailableMemoryBytes,
+        hostReserveBytes,
+        admissionMemoryBytes,
         availableCpuMillis: Math.max(0, (os.availableParallelism?.() ?? os.cpus().length) * 1000),
         availableWorkspaceBytes: 0,
         diskLow: code === "docker_disk_low",
@@ -242,9 +467,49 @@ function positiveInteger(value, fallback) {
 function singleLine(value) {
     return value.replace(/[\r\n\t]+/gu, " ").trim().slice(0, 1000);
 }
+function nonNegativeInteger(value, fallback) {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+function positiveNumber(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function tryParseDockerMemoryUsage(value) {
+    const usage = value.split("/", 1)[0]?.trim().replaceAll(" ", "") ?? "";
+    const match = /^(\d+(?:\.\d+)?)(b|kib|mib|gib|tib)$/iu.exec(usage);
+    if (!match)
+        return null;
+    const amount = Number(match[1]);
+    const multiplier = { b: 1, kib: 1024, mib: 1024 ** 2, gib: 1024 ** 3, tib: 1024 ** 4 }[match[2].toLowerCase()];
+    return Number.isFinite(amount) ? Math.round(amount * multiplier) : null;
+}
+export function parseDockerMemoryUsage(value) {
+    return tryParseDockerMemoryUsage(value) ?? 0;
+}
 async function readLock(lockPath) {
     return await fs.readFile(lockPath, "utf8").then((value) => JSON.parse(value)).catch(() => null);
 }
+export function dockerContextOwnerIsActive(owner) {
+    if (!owner || !Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0 || !processExists(owner.pid)) {
+        return false;
+    }
+    const liveIdentity = captureHostProcessIdentity(owner.pid);
+    if (owner.processIdentity) {
+        // A live but unverifiable process must remain protected. Windows and Linux
+        // normally provide a birth marker, so a mismatch is positive PID-reuse proof.
+        return !liveIdentity || liveIdentity === owner.processIdentity;
+    }
+    if (process.platform === "win32" && liveIdentity?.startsWith("win32:") && owner.acquiredAt) {
+        const ticks = Number(liveIdentity.slice("win32:".length));
+        const acquiredAt = Date.parse(owner.acquiredAt);
+        const processStartedAt = ticks / 10_000 - 62_135_596_800_000;
+        if (Number.isFinite(processStartedAt) && Number.isFinite(acquiredAt) && processStartedAt > acquiredAt) {
+            return false;
+        }
+    }
+    return true;
+}
 function processExists(pid) {
     try {
         process.kill(pid, 0);

package/dist/sandbox/process.js

@@ -2,6 +2,12 @@ import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
 const terminationSigkillDelayMs = 5_000;
 const forcedCloseSettleDelayMs = 5_000;
+const expectedStdinCloseErrorCodes = new Set(["EPIPE", "ECONNRESET", "ERR_STREAM_DESTROYED"]);
+function isExpectedStdinCloseError(error) {
+    return "code" in error
+        && typeof error.code === "string"
+        && expectedStdinCloseErrorCodes.has(error.code);
+}
 export async function runSandboxProcess(request) {
     const limit = Math.max(1024, request.maxOutputBytes ?? 1024 * 1024);
     return await new Promise((resolve, reject) => {
@@ -161,12 +167,21 @@ export async function runSandboxProcess(request) {
                 reject(error);
             }
         };
+        const onStdinError = (error) => {
+            if (isExpectedStdinCloseError(error))
+                return;
+            onProcessError(error);
+        };
         const onProcessClose = (code) => {
             void settle(code, false);
         };
         child.stdout.on("data", onStdoutData);
         child.stderr.on("data", onStderrData);
         child.on("error", onProcessError);
+        child.on("close", onProcessClose);
+        // Keep this listener for the lifetime of stdin. A pipe error can be emitted
+        // after the child close event has settled the supervisor promise.
+        child.stdin?.on("error", onStdinError);
         timeout = request.timeoutMs
             ? setTimeout(() => terminate(`process timeout after ${request.timeoutMs}ms`), request.timeoutMs)
             : null;
@@ -176,9 +191,13 @@ export async function runSandboxProcess(request) {
             abort();
         }
         if (request.input !== undefined) {
-            child.stdin.end(request.input);
+            try {
+                child.stdin.end(request.input);
+            }
+            catch (error) {
+                onStdinError(error instanceof Error ? error : new Error(String(error)));
+            }
         }
-        child.on("close", onProcessClose);
     });
 }
 export async function requireSandboxProcess(request) {

package/dist/sandbox/repository-lock.js

@@ -1,14 +1,19 @@
 import { createHash, randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { resolvePathIdentity } from "../shared/path/path.js";
+const LOCK_HEARTBEAT_INTERVAL_MS = 30_000;
+const LOCK_STALE_AFTER_MS = 2 * 60_000;
 export class RepositoryCoordinatorLock {
     stateRoot;
     constructor(stateRoot) {
         this.stateRoot = stateRoot;
     }
     async withLock(repoPath, action, signal) {
-        const resolved = path.resolve(repoPath);
-        const key = createHash("sha256").update(resolved.toLowerCase()).digest("hex");
+        const resolved = await resolvePathIdentity(repoPath);
+        const keyInput = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+        const key = createHash("sha256").update(keyInput).digest("hex");
         const root = path.join(this.stateRoot, "repo-locks");
         const target = path.join(root, `${key}.lock`);
         const token = randomUUID();
@@ -41,10 +46,12 @@ export class RepositoryCoordinatorLock {
                 await abortableDelay(50, signal);
             }
         }
+        const heartbeat = startHeartbeat(target, token);
         try {
             return await action();
         }
         finally {
+            clearInterval(heartbeat);
             const owner = await readOwner(target);
             if (owner?.token === token)
                 await fs.rm(target, { force: true });
@@ -58,7 +65,7 @@ async function staleLock(target) {
     const owner = await readOwner(target);
     if (!owner || typeof owner.pid !== "number" || !Number.isInteger(owner.pid) || owner.pid <= 0)
         return true;
-    if (Date.now() - stat.mtimeMs > 10 * 60_000)
+    if (Date.now() - stat.mtimeMs >= LOCK_STALE_AFTER_MS)
         return true;
     try {
         process.kill(owner.pid, 0);
@@ -68,6 +75,37 @@ async function staleLock(target) {
         return true;
     }
 }
+function startHeartbeat(target, token) {
+    let refreshing = false;
+    const timer = setInterval(() => {
+        if (refreshing)
+            return;
+        refreshing = true;
+        void refreshHeartbeat(target, token).finally(() => { refreshing = false; });
+    }, LOCK_HEARTBEAT_INTERVAL_MS);
+    timer.unref?.();
+    return timer;
+}
+async function refreshHeartbeat(target, token) {
+    let handle = null;
+    try {
+        handle = await fs.open(target, fsConstants.O_RDWR | fsConstants.O_NOFOLLOW);
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > 16 * 1024)
+            return;
+        const owner = await handle.readFile("utf8").then(value => JSON.parse(value)).catch(() => null);
+        if (owner?.token !== token)
+            return;
+        const now = new Date();
+        await handle.utimes(now, now);
+    }
+    catch {
+        // A missing or replaced lock is no longer owned by this action.
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
 async function readOwner(target) {
     return await fs.readFile(target, "utf8").then(value => JSON.parse(value)).catch(() => null);
 }