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

package/dist/sandbox/process.js

@@ -1,5 +1,13 @@
 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) => {
@@ -14,10 +22,15 @@ export async function runSandboxProcess(request) {
         let stderr = Buffer.alloc(0);
         let truncated = false;
         let settled = false;
+        let terminating = false;
+        let discardStdoutLineCallbacks = false;
         let stdoutText = "";
         const stdoutDecoder = new StringDecoder("utf8");
         let stdoutLineChain = Promise.resolve();
         let stdoutLineError = null;
+        let timeout = null;
+        let sigkillTimer = null;
+        let forcedSettleTimer = null;
         const append = (current, chunk) => {
             if (current.length >= limit) {
                 truncated = true;
@@ -31,9 +44,87 @@ export async function runSandboxProcess(request) {
             }
             return Buffer.concat([current, chunk.subarray(0, remaining)]);
         };
-        child.stdout.on("data", (chunk) => {
+        const appendStderrLine = (line) => {
+            stderr = append(stderr, Buffer.from(`\n${line}\n`));
+        };
+        const cleanup = () => {
+            if (timeout)
+                clearTimeout(timeout);
+            if (sigkillTimer)
+                clearTimeout(sigkillTimer);
+            if (forcedSettleTimer)
+                clearTimeout(forcedSettleTimer);
+            child.stdout.removeListener("data", onStdoutData);
+            child.stderr.removeListener("data", onStderrData);
+            child.removeListener("error", onProcessError);
+            child.removeListener("close", onProcessClose);
+            request.signal?.removeEventListener("abort", abort);
+        };
+        const settle = async (code, force) => {
+            if (settled)
+                return;
+            settled = true;
+            discardStdoutLineCallbacks = force;
+            cleanup();
+            if (stdoutLineError) {
+                reject(stdoutLineError);
+                return;
+            }
+            if (!force) {
+                if (request.onStdoutLine)
+                    stdoutText += stdoutDecoder.end();
+                if (request.onStdoutLine && stdoutText) {
+                    stdoutLineChain = stdoutLineChain.then(() => request.onStdoutLine(stdoutText));
+                }
+                await stdoutLineChain.catch(error => { stdoutLineError ??= error; });
+                if (stdoutLineError) {
+                    reject(stdoutLineError);
+                    return;
+                }
+            }
+            resolve({
+                exitCode: code ?? 1,
+                stdout: stdout.toString("utf8"),
+                stderr: stderr.toString("utf8"),
+                truncated
+            });
+        };
+        const forceSettle = (reason) => {
+            if (settled)
+                return;
+            appendStderrLine(reason);
+            void settle(1, true);
+        };
+        const killChild = (signal) => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            try {
+                child.kill(signal);
+            }
+            catch {
+                // The process may have exited between timeout/abort and close. Still let the
+                // supervisor timers settle if close never arrives.
+            }
+        };
+        const terminate = (reason) => {
+            if (settled || terminating)
+                return;
+            terminating = true;
+            appendStderrLine(reason);
+            killChild("SIGTERM");
+            sigkillTimer = setTimeout(() => {
+                killChild("SIGKILL");
+                forcedSettleTimer = setTimeout(() => forceSettle("process did not close after SIGKILL; forcing supervisor settlement"), forcedCloseSettleDelayMs);
+                forcedSettleTimer.unref?.();
+            }, terminationSigkillDelayMs);
+            sigkillTimer.unref?.();
+        };
+        const abort = () => terminate(String(request.signal?.reason ?? "process aborted"));
+        const onStdoutData = (chunk) => {
+            if (settled)
+                return;
             stdout = append(stdout, chunk);
-            if (!request.onStdoutLine)
+            if (!request.onStdoutLine || settled)
                 return;
             stdoutText += stdoutDecoder.write(chunk);
             if (Buffer.byteLength(stdoutText, "utf8") > 1024 * 1024 && !stdoutText.includes("\n")) {
@@ -48,6 +139,8 @@ export async function runSandboxProcess(request) {
             child.stdout.pause();
             for (const line of lines) {
                 stdoutLineChain = stdoutLineChain.then(async () => {
+                    if (discardStdoutLineCallbacks)
+                        return;
                     if (Buffer.byteLength(line, "utf8") > 1024 * 1024)
                         throw new Error("sandbox process emitted an oversized stdout line");
                     await request.onStdoutLine(line);
@@ -62,57 +155,49 @@ export async function runSandboxProcess(request) {
                 if (!settled)
                     child.stdout.resume();
             });
-        });
-        child.stderr.on("data", (chunk) => { stderr = append(stderr, chunk); });
-        child.on("error", (error) => {
+        };
+        const onStderrData = (chunk) => {
+            if (!settled)
+                stderr = append(stderr, chunk);
+        };
+        const onProcessError = (error) => {
             if (!settled) {
                 settled = true;
+                cleanup();
                 reject(error);
             }
-        });
-        const terminate = (reason) => {
-            if (child.exitCode !== null)
+        };
+        const onStdinError = (error) => {
+            if (isExpectedStdinCloseError(error))
                 return;
-            child.kill("SIGTERM");
-            setTimeout(() => child.kill("SIGKILL"), 5_000).unref?.();
-            if (!settled) {
-                // Completion is still resolved by close so stderr remains available.
-                stderr = append(stderr, Buffer.from(`\n${reason}\n`));
-            }
+            onProcessError(error);
         };
-        const timeout = request.timeoutMs
+        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;
         timeout?.unref?.();
-        const abort = () => terminate(String(request.signal?.reason ?? "process aborted"));
         request.signal?.addEventListener("abort", abort, { once: true });
-        if (request.input !== undefined) {
-            child.stdin.end(request.input);
+        if (request.signal?.aborted) {
+            abort();
         }
-        child.on("close", async (code) => {
-            if (settled)
-                return;
-            settled = true;
-            if (timeout)
-                clearTimeout(timeout);
-            request.signal?.removeEventListener("abort", abort);
-            if (request.onStdoutLine)
-                stdoutText += stdoutDecoder.end();
-            if (request.onStdoutLine && stdoutText) {
-                stdoutLineChain = stdoutLineChain.then(() => request.onStdoutLine(stdoutText));
+        if (request.input !== undefined) {
+            try {
+                child.stdin.end(request.input);
             }
-            await stdoutLineChain.catch(error => { stdoutLineError ??= error; });
-            if (stdoutLineError) {
-                reject(stdoutLineError);
-                return;
+            catch (error) {
+                onStdinError(error instanceof Error ? error : new Error(String(error)));
             }
-            resolve({
-                exitCode: code ?? 1,
-                stdout: stdout.toString("utf8"),
-                stderr: stderr.toString("utf8"),
-                truncated
-            });
-        });
+        }
     });
 }
 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);
 }

package/dist/sandbox/runtime.d.ts

@@ -2,6 +2,7 @@ import type { BridgeServiceConfig } from "../bridge/bridge.types.js";
 import type { SessionEventSink } from "../session/session.base.js";
 import { type RunOnceDispatchPacket, type RunOnceResultPacket } from "../session/session.types.js";
 import type { SandboxService, ValidatedSandboxContract } from "./sandbox.types.js";
+import { type RuntimeIsolationLease } from "../runtime/runtime-isolation-lease.js";
 export interface SandboxRuntime {
     runOnce(dispatch: RunOnceDispatchPacket, sink: SessionEventSink, signal?: AbortSignal): Promise<RunOnceResultPacket>;
     reap(options?: SandboxReapOptions): Promise<void>;
@@ -41,6 +42,28 @@ export interface SandboxRuntimeSnapshot {
     readonly active: number;
     readonly degraded: number;
 }
+export interface SandboxContainerMemoryPeak {
+    readonly containerId: string;
+    readonly name: string;
+    readonly role: string;
+    readonly peakMemoryBytes: number;
+}
+export interface SandboxPeakMemoryTelemetry {
+    readonly schemaVersion: 1;
+    readonly source: "docker_stats_sampled";
+    readonly sampleIntervalMs: number;
+    readonly sampleCount: number;
+    readonly failedSampleCount: number;
+    readonly peakMemoryBytes: number;
+    readonly firstSampledAt: string;
+    readonly lastSampledAt: string;
+    readonly containers: readonly SandboxContainerMemoryPeak[];
+}
+export interface DockerStatsMemorySample {
+    readonly containerId: string;
+    readonly name: string;
+    readonly memoryBytes: number;
+}
 export interface SandboxPublicationGrantRequest {
     readonly dispatchAttemptId: string;
     readonly leaseId: string;
@@ -84,6 +107,7 @@ export declare class DockerSandboxRuntime implements SandboxRuntime {
     private buildImageCore;
     private runBuildStage;
     private ensureBuildxBuilder;
+    private stopBuildxBuilder;
     private initializeVolumes;
     private inspectContainerState;
     private initializeServiceSecrets;
@@ -102,9 +126,12 @@ export declare class DockerSandboxRuntime implements SandboxRuntime {
     private readImageCacheRecord;
     private collectExpiredImages;
     private purgeRestrictedAuditArtifacts;
+    private inspectImageMetadata;
+    private startPeakMemorySampler;
     private docker;
     private dockerArgs;
 }
+export declare function managedBranchUpdateExpectedValue(current: string, expectedInput: string, imported: string): string;
 export declare function publicationPushArgs(branch: string, resultCommitSha: string, inputCommitSha: string, remoteCommitSha: string, remote?: string): string[] | null;
 export declare function validatePublicationCredential(credential: SandboxPublicationCredential, nowMs?: number): void;
 export declare function publicationCredentialEnvironment(credential: SandboxPublicationCredential, environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
@@ -129,6 +156,7 @@ export declare function selectSandboxConfigRefs(executionPolicy: string, configu
     readonly refs: readonly string[];
     readonly approvedSha: string | null;
 };
+export declare function selectSandboxInputRefs(worktreeKey: string, baseBranch: string): readonly string[];
 export declare function sandboxTimeLimits(environment?: NodeJS.ProcessEnv): {
     readonly hardWallMs: number;
     readonly idleMs: number;
@@ -144,8 +172,10 @@ export interface ImageCacheRecord {
     readonly overlayTag: string;
     readonly imageDigest: string;
     readonly helperImageDigest: string;
+    readonly bridgeRuntimeDigest?: string;
     readonly policyDigest: string;
 }
+export declare function sandboxWorkerFailureMessage(exitCode: number, stderr: string, containerError: string | null): string;
 interface ResourceNames {
     prefix: string;
     container: string;
@@ -162,18 +192,30 @@ interface SandboxRuntimeVolume {
     readonly name: string;
     readonly role: string;
 }
+export declare function parseDockerMemoryBytes(value: string): number | null;
+export declare function parseDockerStatsMemorySample(output: string): DockerStatsMemorySample[];
 interface ActiveSandbox {
     dispatchAttemptId: string;
     fencingToken: string;
     expiresAt: string;
     controller: AbortController;
     phase: "starting" | "active";
+    runtimeLease: RuntimeIsolationLease;
     ledger: SandboxLedger | null;
     leaseControlKey: string;
 }
 export declare function assertSandboxImportCurrent(expected: Pick<ActiveSandbox, "dispatchAttemptId" | "fencingToken" | "expiresAt">, current: Pick<ActiveSandbox, "dispatchAttemptId" | "fencingToken"> | undefined, signal: AbortSignal, nowMs?: number): void;
 interface SandboxLedger {
-    schemaVersion: 1;
+    schemaVersion: 3;
+    runtimeLease: RuntimeIsolationLease;
+    resources: ResourceNames;
+    labels: Record<string, string>;
+    includeCredentials?: boolean;
+    peakMemory?: SandboxPeakMemoryTelemetry;
+}
+interface LegacySandboxLedger {
+    schemaVersion: 2;
+    resourceLeaseId: string;
     dispatchAttemptId: string;
     fencingToken: string;
     runnerInstanceId: string;
@@ -181,13 +223,18 @@ interface SandboxLedger {
     resources: ResourceNames;
     labels: Record<string, string>;
     includeCredentials?: boolean;
+    peakMemory?: SandboxPeakMemoryTelemetry;
 }
+export declare function validSandboxLedger(value: unknown): boolean;
+export declare function normalizeSandboxLedger(value: unknown): SandboxLedger | null;
 export declare function resourceNames(attemptHex: string, perAttemptCaches?: readonly string[]): ResourceNames;
 export declare function dockerObjectId(output: string, kind: "container" | "network"): string;
 export declare function sandboxRuntimeVolumes(resources: ResourceNames, includeEgressPolicy?: boolean, includeCredentials?: boolean): SandboxRuntimeVolume[];
 export declare function sandboxRuntimeCleanupVolumeNames(resources: ResourceNames, includeCredentials?: boolean): string[];
+export declare function sandboxResourceLabels(dispatch: RunOnceDispatchPacket, image: string, contract: string): Record<string, string>;
 export declare function mayReapManagedResource(labels: Readonly<Record<string, string>>, runnerId: string, liveAttempts: ReadonlySet<string>): boolean;
-export declare function shouldReapSandboxLedger(ledger: Readonly<Pick<SandboxLedger, "dispatchAttemptId" | "fencingToken" | "runnerInstanceId" | "expiresAt">>, currentRunnerInstanceId: string, serverAttempt: SandboxAttemptSnapshot | undefined, snapshotAvailable: boolean, nowMs?: number): boolean;
+export declare function shouldReapSandboxLedger(ledger: Readonly<Pick<SandboxLedger, "runtimeLease">> | Readonly<Pick<LegacySandboxLedger, "dispatchAttemptId" | "fencingToken" | "runnerInstanceId" | "expiresAt">>, currentRunnerInstanceId: string, serverAttempt: SandboxAttemptSnapshot | undefined, snapshotAvailable: boolean, nowMs?: number): boolean;
+export declare function bridgeRuntimeCacheMatches(record: Pick<ImageCacheRecord, "bridgeRuntimeDigest"> | null | undefined, expectedDigest: string, imageLabels: readonly (Readonly<Record<string, string>> | null | undefined)[]): boolean;
 export declare function prepareOverlayBuildRoot(overlayRoot: string): Promise<void>;
 export declare function extractOciLayoutArchive(archivePath: string, destination: string, signal?: AbortSignal): Promise<void>;
 export declare function ociLayoutContextRef(layoutPath: string): string;
@@ -200,6 +247,20 @@ export declare function readOciLayoutImageDigest(layoutRoot: string): Promise<st
 export declare function removeExtractedOciLayout(layoutRoot: string): Promise<void>;
 export declare function ociLayoutScanTarget(layoutPath: string): string;
 export declare function agentOverlayDockerignore(): string;
+export interface SandboxImageCacheKeyInput {
+    readonly contextDigest: string;
+    readonly contractDigest: string;
+    readonly platform: string;
+    readonly architecture: string;
+    readonly bridgeVersion: string;
+    readonly bridgeRuntimeDigest: string;
+    readonly toolingImage: string;
+    readonly codexVersion: string;
+    readonly policy: string;
+    readonly policyConfigurationDigest: string;
+}
+export declare function sandboxImageCacheKey(input: SandboxImageCacheKeyInput): string;
+export declare function bridgeRuntimeContentDigest(packageRoot: string): Promise<string>;
 export declare function agentOverlayDockerfile(toolingImage: string, projectContextName: string, installMode: BridgePackageInstallMode, codexVersion: string): string;
 export type BridgePackageInstallMode = "ci" | "install";
 export declare function copyBridgePackageManifests(packageRoot: string, bridgeRoot: string): Promise<BridgePackageInstallMode>;
@@ -211,17 +272,19 @@ export declare function buildResourcePolicy(environment?: NodeJS.ProcessEnv): {
     readonly nofile: number;
     readonly sharedMemory: string;
     readonly builderPidsLimit: number;
+    readonly builderMemoryBytes: number;
 };
 export declare function dedicatedBuildxBuilderName(runnerId: string, dockerContext: string | null | undefined): string;
 export declare function dedicatedBuildxBuilderContainerName(builder: string): string;
 export declare function selectImageGcCandidates(records: readonly ImageCacheRecord[], keepPerProject: number, ttlMs: number, nowMs: number): ImageCacheRecord[];
 export declare function workerCreateArgs(dispatch: RunOnceDispatchPacket, contract: ValidatedSandboxContract, resources: ResourceNames, labels: Record<string, string>, image: string, securityOptions?: readonly string[]): string[];
+export declare function validateSandboxMemoryReservation(dispatch: RunOnceDispatchPacket, contract: ValidatedSandboxContract): void;
 export declare function cacheVolumeArgs(contract: ValidatedSandboxContract, resources: ResourceNames): string[];
 export declare function proxyEnvironmentArgs(dispatch: RunOnceDispatchPacket, contract: ValidatedSandboxContract, resources: ResourceNames): string[];
 export declare function egressProxyConfig(allowedHosts: readonly string[]): string;
 export declare function serviceContainerArgs(service: SandboxService, image: string, resources: ResourceNames, labels: Record<string, string>, securityOptions: readonly string[], environment?: NodeJS.ProcessEnv): string[];
 export declare function resolveSandboxSecurityOptions(executionPolicy: string, environment?: NodeJS.ProcessEnv): string[];
-export declare function networkCreateArgs(dispatch: RunOnceDispatchPacket, environment?: NodeJS.ProcessEnv): string[];
+export declare function networkCreateArgs(dispatch: RunOnceDispatchPacket, environment?: NodeJS.ProcessEnv, allowOpenPublicSandbox?: boolean): string[];
 export declare function classifySandboxRuntimeFailure(value: string): {
     readonly code: string;
     readonly phase: string;