@loucompanion/forge-bridge 0.1.3-dev.d46a8e73d03d → 0.1.3-dev.eeefdb0d19c1

package/dist/runtime/playwright-host-runtime-adapter.js

@@ -0,0 +1,220 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+const maximumConfigBytes = 1024 * 1024;
+/**
+ * Prepares a finite Playwright test boundary for a managed-host attempt.
+ * The generated overlay points tests at Forge's verified listener, disables
+ * Playwright-managed web servers, and keeps writable artifacts attempt-local.
+ */
+export class PlaywrightHostRuntimeAdapter {
+    async prepare(config, context) {
+        const worktreePath = path.resolve(context.worktreePath);
+        const sourceConfig = path.resolve(worktreePath, config.config);
+        const [realWorktree, realSource] = await Promise.all([
+            fs.realpath(worktreePath),
+            fs.realpath(sourceConfig),
+        ]);
+        assertContained(realWorktree, realSource, "project Playwright config");
+        const sourceStat = await fs.stat(realSource);
+        if (!sourceStat.isFile() || sourceStat.size < 1 || sourceStat.size > maximumConfigBytes) {
+            throw new Error(`playwright_runtime_adapter_invalid: project config must be a regular 1-${maximumConfigBytes} byte file.`);
+        }
+        const temporaryDirectory = await realContainedDirectory(context.temporaryDirectory, realWorktree, "temporary directory");
+        const testOutputDirectory = await realContainedDirectory(context.testOutputDirectory, realWorktree, "test output directory");
+        const browserProfileDirectory = await realContainedDirectory(context.browserProfileDirectory, realWorktree, "browser profile directory");
+        const attemptRoot = path.dirname(temporaryDirectory);
+        if (path.dirname(testOutputDirectory) !== attemptRoot || path.dirname(browserProfileDirectory) !== attemptRoot) {
+            throw new Error("playwright_runtime_adapter_invalid: writable directories must belong to the same attempt root.");
+        }
+        const baseUrl = loopbackHttpUrl(context.baseUrl);
+        const overlayPath = path.join(temporaryDirectory, "forge.playwright.config.mjs");
+        const browserCache = await resolvePlaywrightBrowserCache(attemptRoot);
+        const browserInstallCommand = await resolvePlaywrightBrowserInstallCommand(context.worktreePath, path.dirname(realSource));
+        await fs.writeFile(overlayPath, renderOverlay({
+            projectConfigUrl: pathToFileURL(realSource).href,
+            projectConfigDirectory: path.dirname(realSource),
+            testOutputDirectory,
+            baseUrl,
+            workers: config.workers,
+        }), { encoding: "utf8", mode: 0o600 });
+        return {
+            configPath: overlayPath,
+            environment: {
+                FORGE_PLAYWRIGHT_CONFIG: overlayPath,
+                FORGE_PLAYWRIGHT_BASE_URL: baseUrl,
+                FORGE_E2E_WEB_URL: baseUrl,
+                FORGE_PLAYWRIGHT_BROWSER_READY: browserCache.ready ? "true" : "false",
+                FORGE_PLAYWRIGHT_BROWSER_INSTALL_COMMAND: browserInstallCommand,
+                PLAYWRIGHT_BROWSERS_PATH: browserCache.path,
+                PLAYWRIGHT_HTML_OUTPUT_DIR: path.join(testOutputDirectory, "html-report"),
+                PLAYWRIGHT_BLOB_OUTPUT_DIR: path.join(testOutputDirectory, "blob-report"),
+                PLAYWRIGHT_JUNIT_OUTPUT_NAME: path.join(testOutputDirectory, "results.xml"),
+                PLAYWRIGHT_JSON_OUTPUT_NAME: path.join(testOutputDirectory, "results.json"),
+                FORGE_BROWSER_PROFILE_DIR: browserProfileDirectory,
+                FORGE_TEST_OUTPUT_DIR: testOutputDirectory,
+            },
+        };
+    }
+}
+async function resolvePlaywrightBrowserInstallCommand(worktreePath, configDirectory) {
+    const relativeDirectory = path.relative(worktreePath, configDirectory).replaceAll(path.sep, "/") || ".";
+    if (await isFile(path.join(configDirectory, "pnpm-lock.yaml"))) {
+        return `pnpm --dir ${quoteCommandArgument(relativeDirectory)} exec playwright install chromium`;
+    }
+    if (await isFile(path.join(configDirectory, "yarn.lock"))) {
+        return `yarn --cwd ${quoteCommandArgument(relativeDirectory)} playwright install chromium`;
+    }
+    return `npm --prefix ${quoteCommandArgument(relativeDirectory)} exec playwright install chromium`;
+}
+async function isFile(candidate) {
+    try {
+        return (await fs.stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function quoteCommandArgument(value) {
+    return /[\s"']/u.test(value) ? JSON.stringify(value) : value;
+}
+async function resolvePlaywrightBrowserCache(attemptRoot) {
+    const candidates = [
+        process.env.PLAYWRIGHT_BROWSERS_PATH,
+        process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, "ms-playwright") : null,
+        path.join(os.homedir(), ".cache", "ms-playwright"),
+    ].filter((candidate) => Boolean(candidate?.trim()));
+    for (const candidate of [...new Set(candidates.map(candidate => path.resolve(candidate)))]) {
+        if (await hasChromiumExecutable(candidate)) {
+            return { path: candidate, ready: true };
+        }
+    }
+    const attemptCache = path.join(attemptRoot, "cache", "ms-playwright");
+    await fs.mkdir(attemptCache, { recursive: true });
+    return { path: attemptCache, ready: false };
+}
+async function hasChromiumExecutable(cachePath) {
+    let entries;
+    try {
+        entries = await fs.readdir(cachePath, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    const executableSuffixes = process.platform === "win32"
+        ? [path.join("chrome-win64", "chrome.exe"), path.join("chrome-win", "chrome.exe")]
+        : process.platform === "darwin"
+            ? [path.join("chrome-mac", "Chromium.app", "Contents", "MacOS", "Chromium")]
+            : [path.join("chrome-linux", "chrome"), path.join("chrome-linux64", "chrome")];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith("chromium-"))
+            continue;
+        for (const suffix of executableSuffixes) {
+            try {
+                const stat = await fs.stat(path.join(cachePath, entry.name, suffix));
+                if (stat.isFile())
+                    return true;
+            }
+            catch {
+                // Continue through known Playwright layouts.
+            }
+        }
+    }
+    return false;
+}
+function renderOverlay(values) {
+    return [
+        "// Generated by forge-bridge for one fenced host attempt.",
+        "import path from \"node:path\";",
+        `import projectConfig from ${JSON.stringify(values.projectConfigUrl)};`,
+        `const projectConfigDirectory = ${JSON.stringify(values.projectConfigDirectory)};`,
+        "const resolveConfigPath = value => typeof value === \"string\" && !path.isAbsolute(value)",
+        "  ? path.resolve(projectConfigDirectory, value)",
+        "  : value;",
+        "const resolveModulePath = value => typeof value === \"string\" && value.startsWith(\".\")",
+        "  ? path.resolve(projectConfigDirectory, value)",
+        "  : value;",
+        "const resolveUse = use => ({",
+        "  ...(use ?? {}),",
+        "  storageState: typeof use?.storageState === \"string\" ? resolveConfigPath(use.storageState) : use?.storageState,",
+        "  baseURL: " + JSON.stringify(values.baseUrl) + ",",
+        "});",
+        "const forgeUse = resolveUse(projectConfig.use);",
+        "const forgeProjects = Array.isArray(projectConfig.projects)",
+        "  ? projectConfig.projects.map(project => ({",
+        "      ...project,",
+        "      testDir: resolveConfigPath(project.testDir),",
+        "      snapshotDir: resolveConfigPath(project.snapshotDir),",
+        "      use: resolveUse(project.use),",
+        "    }))",
+        "  : projectConfig.projects;",
+        "const forgeReporter = Array.isArray(projectConfig.reporter)",
+        "  ? projectConfig.reporter.map(reporter => Array.isArray(reporter)",
+        "      ? [resolveModulePath(reporter[0]), ...reporter.slice(1)]",
+        "      : resolveModulePath(reporter))",
+        "  : resolveModulePath(projectConfig.reporter);",
+        "const forgeProviderOnlySpecs = (() => {",
+        "  try {",
+        "    const parsed = JSON.parse(process.env.FORGE_CI_REPAIR_PROVIDER_ONLY_SPECS ?? '[]');",
+        "    return Array.isArray(parsed) ? parsed.filter(value => typeof value === 'string' && value.length > 0) : [];",
+        "  } catch {",
+        "    return [];",
+        "  }",
+        "})();",
+        "const forgeTestIgnore = forgeProviderOnlySpecs.length === 0",
+        "  ? projectConfig.testIgnore",
+        "  : [...(Array.isArray(projectConfig.testIgnore) ? projectConfig.testIgnore : projectConfig.testIgnore ? [projectConfig.testIgnore] : []), ...forgeProviderOnlySpecs];",
+        "export default {",
+        "  ...projectConfig,",
+        "  testDir: resolveConfigPath(projectConfig.testDir),",
+        "  snapshotDir: resolveConfigPath(projectConfig.snapshotDir),",
+        "  globalSetup: resolveModulePath(projectConfig.globalSetup),",
+        "  globalTeardown: resolveModulePath(projectConfig.globalTeardown),",
+        "  reporter: forgeReporter,",
+        "  testIgnore: forgeTestIgnore,",
+        `  outputDir: ${JSON.stringify(values.testOutputDirectory)},`,
+        `  workers: ${values.workers},`,
+        "  webServer: undefined,",
+        "  use: forgeUse,",
+        "  projects: forgeProjects,",
+        "};",
+        "",
+    ].join("\n");
+}
+async function realContainedDirectory(target, realWorktree, label) {
+    const realTarget = await fs.realpath(path.resolve(target));
+    if (realTarget === realWorktree || isContained(realWorktree, realTarget)) {
+        throw new Error(`playwright_runtime_adapter_invalid: ${label} must be attempt-private and outside the worktree.`);
+    }
+    const stat = await fs.stat(realTarget);
+    if (!stat.isDirectory())
+        throw new Error(`playwright_runtime_adapter_invalid: ${label} must be a directory.`);
+    return realTarget;
+}
+function assertContained(parent, child, label) {
+    if (!isContained(parent, child)) {
+        throw new Error(`playwright_runtime_adapter_invalid: ${label} must stay inside the prepared worktree.`);
+    }
+}
+function isContained(parent, child) {
+    const relative = path.relative(parent, child);
+    return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function loopbackHttpUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("playwright_runtime_adapter_invalid: base URL must be an HTTP loopback URL.");
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:")
+        || url.hostname !== "127.0.0.1"
+        || !url.port
+        || url.username
+        || url.password) {
+        throw new Error("playwright_runtime_adapter_invalid: base URL must be an HTTP loopback URL.");
+    }
+    return url.href.replace(/\/$/u, "");
+}

package/dist/runtime/runtime-isolation-lease.d.ts

@@ -0,0 +1,67 @@
+export declare const runtimeIsolationLeaseStates: readonly ["reserved", "starting", "active", "releasing", "released", "degraded"];
+export type RuntimeIsolationLeaseState = typeof runtimeIsolationLeaseStates[number];
+export type RuntimeIsolationMode = "docker" | "host";
+export interface RuntimeIsolationPort {
+    readonly name: string;
+    readonly protocol: "tcp" | "udp";
+    readonly hostIp: "127.0.0.1" | "::1";
+    readonly hostPort: number;
+    readonly targetPort: number;
+}
+export interface RuntimeIsolationPath {
+    readonly path: string;
+    readonly role: string;
+}
+export interface RuntimeIsolationDockerResource {
+    readonly type: "container" | "network" | "volume";
+    readonly name: string;
+    readonly role: string;
+    readonly id?: string | null;
+}
+export interface RuntimeIsolationResources {
+    readonly memoryReservationBytes: number;
+    readonly cpuMillis: number;
+    readonly pids: number;
+    readonly ports: readonly RuntimeIsolationPort[];
+    readonly paths: readonly RuntimeIsolationPath[];
+    readonly processSupervisorId: string | null;
+    readonly dockerResources: readonly RuntimeIsolationDockerResource[];
+    readonly singletonKeys: readonly string[];
+}
+export interface RuntimeIsolationLease {
+    readonly schemaVersion: 1;
+    readonly leaseId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly worktreeKey: string;
+    readonly worktreePath: string;
+    readonly mode: RuntimeIsolationMode;
+    readonly state: RuntimeIsolationLeaseState;
+    readonly createdAt: string;
+    readonly stateChangedAt: string;
+    readonly expiresAt: string;
+    readonly releasedAt: string | null;
+    readonly resources: RuntimeIsolationResources;
+}
+export interface RuntimeIsolationLeaseInput {
+    readonly leaseId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly worktreeKey: string;
+    readonly worktreePath: string;
+    readonly mode: RuntimeIsolationMode;
+    readonly expiresAt: string;
+    readonly resources: RuntimeIsolationResources;
+    readonly createdAt?: string;
+}
+export declare function createRuntimeIsolationLease(input: RuntimeIsolationLeaseInput): RuntimeIsolationLease;
+export declare function transitionRuntimeIsolationLease(lease: RuntimeIsolationLease, nextState: RuntimeIsolationLeaseState, occurredAt?: string): RuntimeIsolationLease;
+export declare function renewRuntimeIsolationLease(lease: RuntimeIsolationLease, fencingToken: string, expiresAt: string): RuntimeIsolationLease | null;
+export declare function withRuntimeIsolationResources(lease: RuntimeIsolationLease, resources: RuntimeIsolationResources): RuntimeIsolationLease;
+export declare function validRuntimeIsolationLease(value: unknown): value is RuntimeIsolationLease;

package/dist/runtime/runtime-isolation-lease.js

@@ -0,0 +1,158 @@
+export const runtimeIsolationLeaseStates = [
+    "reserved",
+    "starting",
+    "active",
+    "releasing",
+    "released",
+    "degraded",
+];
+const allowedTransitions = {
+    reserved: new Set(["starting", "releasing", "degraded"]),
+    starting: new Set(["active", "releasing", "degraded"]),
+    active: new Set(["releasing", "degraded"]),
+    releasing: new Set(["released", "degraded"]),
+    released: new Set(),
+    degraded: new Set(["releasing"]),
+};
+export function createRuntimeIsolationLease(input) {
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    const lease = {
+        schemaVersion: 1,
+        leaseId: input.leaseId,
+        dispatchAttemptId: input.dispatchAttemptId,
+        executionLeaseId: input.executionLeaseId,
+        fencingToken: input.fencingToken,
+        runnerId: input.runnerId,
+        runnerInstanceId: input.runnerInstanceId,
+        worktreeKey: input.worktreeKey,
+        worktreePath: input.worktreePath,
+        mode: input.mode,
+        state: "reserved",
+        createdAt,
+        stateChangedAt: createdAt,
+        expiresAt: input.expiresAt,
+        releasedAt: null,
+        resources: input.resources,
+    };
+    if (!validRuntimeIsolationLease(lease)) {
+        throw new Error("runtime_lease_invalid: lease identity, lifetime, or resources are invalid.");
+    }
+    return lease;
+}
+export function transitionRuntimeIsolationLease(lease, nextState, occurredAt = new Date().toISOString()) {
+    if (lease.state === nextState)
+        return lease;
+    if (!allowedTransitions[lease.state].has(nextState) || !validTimestamp(occurredAt)) {
+        throw new Error(`runtime_lease_transition_invalid: cannot transition ${lease.state} to ${nextState}.`);
+    }
+    const transitioned = {
+        ...lease,
+        state: nextState,
+        stateChangedAt: occurredAt,
+        releasedAt: nextState === "released" ? occurredAt : null,
+    };
+    if (!validRuntimeIsolationLease(transitioned)) {
+        throw new Error("runtime_lease_invalid: transitioned lease is invalid.");
+    }
+    return transitioned;
+}
+export function renewRuntimeIsolationLease(lease, fencingToken, expiresAt) {
+    if (lease.fencingToken !== fencingToken || lease.state === "released" || !validTimestamp(expiresAt))
+        return null;
+    const renewed = { ...lease, expiresAt };
+    return validRuntimeIsolationLease(renewed) ? renewed : null;
+}
+export function withRuntimeIsolationResources(lease, resources) {
+    if (lease.state === "released") {
+        throw new Error("runtime_lease_transition_invalid: released leases cannot acquire resources.");
+    }
+    const updated = { ...lease, resources };
+    if (!validRuntimeIsolationLease(updated)) {
+        throw new Error("runtime_lease_invalid: resources are invalid.");
+    }
+    return updated;
+}
+export function validRuntimeIsolationLease(value) {
+    if (!isRecord(value)
+        || value.schemaVersion !== 1
+        || !isUuid(value.leaseId)
+        || !isUuid(value.dispatchAttemptId)
+        || !isUuid(value.executionLeaseId)
+        || !isUuid(value.fencingToken)
+        || !isUuid(value.runnerId)
+        || !isUuid(value.runnerInstanceId)
+        || !boundedText(value.worktreeKey, 255)
+        || !boundedText(value.worktreePath, 4096)
+        || (value.mode !== "docker" && value.mode !== "host")
+        || !runtimeIsolationLeaseStates.includes(value.state)
+        || !validTimestamp(value.createdAt)
+        || !validTimestamp(value.stateChangedAt)
+        || !validTimestamp(value.expiresAt)
+        || Date.parse(value.stateChangedAt) < Date.parse(value.createdAt)
+        || Date.parse(value.expiresAt) < Date.parse(value.createdAt)
+        || (value.state === "released") !== validTimestamp(value.releasedAt)) {
+        return false;
+    }
+    if (value.releasedAt !== null && Date.parse(value.releasedAt) < Date.parse(value.createdAt))
+        return false;
+    return validResources(value.resources, value.mode);
+}
+function validResources(value, mode) {
+    if (!isRecord(value)
+        || !nonNegativeInteger(value.memoryReservationBytes)
+        || !nonNegativeInteger(value.cpuMillis)
+        || !nonNegativeInteger(value.pids)
+        || !Array.isArray(value.ports) || value.ports.length > 64
+        || !Array.isArray(value.paths) || value.paths.length > 64
+        || !Array.isArray(value.dockerResources) || value.dockerResources.length > 128
+        || !Array.isArray(value.singletonKeys) || value.singletonKeys.length > 64
+        || (value.processSupervisorId !== null && !boundedText(value.processSupervisorId, 255))) {
+        return false;
+    }
+    if (value.ports.some(port => !validPort(port))
+        || value.paths.some(entry => !isRecord(entry) || !boundedText(entry.path, 4096) || !boundedText(entry.role, 128))
+        || value.singletonKeys.some(key => !boundedText(key, 255))
+        || value.dockerResources.some(resource => !validDockerResource(resource))) {
+        return false;
+    }
+    return mode === "docker" || value.dockerResources.length === 0;
+}
+function validPort(value) {
+    return isRecord(value)
+        && boundedText(value.name, 128)
+        && (value.protocol === "tcp" || value.protocol === "udp")
+        && (value.hostIp === "127.0.0.1" || value.hostIp === "::1")
+        && validPortNumber(value.hostPort)
+        && validPortNumber(value.targetPort);
+}
+function validDockerResource(value) {
+    return isRecord(value)
+        && (value.type === "container" || value.type === "network" || value.type === "volume")
+        && boundedText(value.name, 255)
+        && boundedText(value.role, 128)
+        && (value.id === undefined || value.id === null || boundedText(value.id, 255));
+}
+function validPortNumber(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 1 && Number(value) <= 65535;
+}
+function nonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function validTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function boundedText(value, maximumLength) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= maximumLength
+        && Array.from(value).every((character) => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint > 31 && codePoint !== 127;
+        });
+}
+function isUuid(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu.test(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/sandbox/preflight.d.ts

@@ -8,6 +8,10 @@ export interface DockerPreflightOptions {
     readonly diskHighWatermarkPercent?: number;
     readonly diskLowWatermarkPercent?: number;
     readonly minimumWorkspaceBytes?: number;
+    readonly hostMemoryReserveBytes?: number;
+    readonly defaultWorkerMemoryLimitBytes?: number;
+    readonly defaultServiceMemoryLimitBytes?: number;
+    readonly runtimeOverheadBytes?: number;
     readonly requireRootless?: boolean;
 }
 export declare class DockerPreflight {
@@ -35,6 +39,16 @@ export declare function evaluateDiskPressure(availableBytes: number, totalBytes:
 export declare function storagePolicyAvailable(storageQuota: boolean, environment?: NodeJS.ProcessEnv): boolean;
 export declare class DockerContextOwnershipLock {
     private lockPath;
+    private lockToken;
     acquire(contextName?: string): Promise<void>;
     release(): Promise<void>;
 }
+export declare function parseDockerMemoryUsage(value: string): number;
+interface DockerContextLockOwner {
+    readonly token?: string;
+    readonly pid?: number;
+    readonly processIdentity?: string | null;
+    readonly acquiredAt?: string;
+}
+export declare function dockerContextOwnerIsActive(owner: DockerContextLockOwner | null): boolean;
+export {};

package/dist/sandbox/preflight.js

@@ -1,9 +1,11 @@
 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 { captureHostProcessIdentity } from "../shared/process/host-process-supervisor.js";
 import { BoundedCommandRunner } from "./command-runner.js";
 const minimumWorkspaceBytes = 10 * 1024 * 1024 * 1024;
+const defaultHostMemoryReserveBytes = 2 * 1024 ** 3;
 export class DockerPreflight {
     commands;
     cacheMs;
@@ -81,7 +83,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())
@@ -105,22 +107,46 @@ export class DockerPreflight {
         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 hostAvailableMemoryBytes = os.freemem();
+        let totalMemoryBytes = os.totalmem();
+        let availableMemoryBytes = hostAvailableMemoryBytes;
+        const dockerDesktop = process.platform !== "linux"
+            && String(info.OperatingSystem ?? "").toLowerCase().includes("docker desktop");
+        const dockerMemoryBytes = Number(info.MemTotal);
+        if (dockerDesktop && Number.isFinite(dockerMemoryBytes) && dockerMemoryBytes > 0) {
+            totalMemoryBytes = dockerMemoryBytes;
+            const stats = await this.commands.run(this.docker, [...dockerArgs, "stats", "--no-stream", "--format", "{{.MemUsage}}"], { timeoutMs: 10_000, maxOutputBytes: 512 * 1024 }).catch(() => null);
+            if (stats?.exitCode === 0) {
+                const dockerUsedMemoryBytes = stats.stdout
+                    .split(/\r?\n/gu)
+                    .map(line => parseDockerMemoryUsage(line))
+                    .reduce((total, value) => total + value, 0);
+                availableMemoryBytes = Math.max(0, dockerMemoryBytes - dockerUsedMemoryBytes);
+            }
+        }
         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;
+        const memoryReserveBytes = positiveInteger(this.options.hostMemoryReserveBytes, defaultHostMemoryReserveBytes);
+        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 && 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.`
+                ? `Docker reports ${availableMemoryBytes} bytes available and Forge reserves ${memoryReserveBytes} host bytes, leaving ${availableForAdmissionBytes} bytes for admission; the smallest supported sandbox requires ${minimumAdmissionMemoryBytes} bytes. 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;
@@ -132,7 +158,10 @@ export class DockerPreflight {
             generation: this.generation,
             runtimeVersion: `docker/${String(info.ServerVersion ?? "unknown")}${rootless ? "-rootless" : "-desktop"}`,
             maxConcurrentSandboxes,
+            totalMemoryBytes,
             availableMemoryBytes,
+            hostReserveBytes: memoryReserveBytes,
+            admissionMemoryBytes: sandboxMemoryBytes,
             availableCpuMillis,
             availableWorkspaceBytes: disk.available,
             diskLow,
@@ -161,34 +190,48 @@ export function storagePolicyAvailable(storageQuota, environment = process.env)
 }
 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) {
@@ -211,7 +254,10 @@ function unavailable(generation, code, reason, features = {
         generation,
         runtimeVersion: null,
         maxConcurrentSandboxes: 0,
+        totalMemoryBytes: os.totalmem(),
         availableMemoryBytes: os.freemem(),
+        hostReserveBytes: defaultHostMemoryReserveBytes,
+        admissionMemoryBytes: 2 * 1024 ** 3 + 128 * 1024 ** 2,
         availableCpuMillis: Math.max(0, (os.availableParallelism?.() ?? os.cpus().length) * 1000),
         availableWorkspaceBytes: 0,
         diskLow: code === "docker_disk_low",
@@ -242,9 +288,42 @@ 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;
+}
+export function parseDockerMemoryUsage(value) {
+    const usage = value.split("/", 1)[0]?.trim().replaceAll(" ", "") ?? "";
+    const match = /^(\d+(?:\.\d+)?)(b|kib|mib|gib|tib)$/iu.exec(usage);
+    if (!match)
+        return 0;
+    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) : 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);