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

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/runtime/workspace-resource-estimator.d.ts

@@ -0,0 +1,17 @@
+export declare const minimumWorkspaceEstimateBytes: number;
+export declare const architectMinimumWorkspaceEstimateBytes: number;
+export interface RepositoryWorkspaceFootprint {
+    readonly sourceBytes: number;
+    readonly hasNode: boolean;
+    readonly hasDotNet: boolean;
+    readonly hasBrowser: boolean;
+    readonly serviceCount: number;
+}
+export interface WorkspaceEstimateHints {
+    readonly role?: string | null;
+    readonly serviceCount?: number;
+    readonly browser?: boolean;
+}
+export declare function estimateWorkspaceBytesFromRepo(repoPath: string, hints?: WorkspaceEstimateHints): Promise<number>;
+export declare function calculateWorkspaceBytes(footprint: RepositoryWorkspaceFootprint, role?: string | null): number;
+export declare function measureRepositoryWorkspace(repoPath: string): Promise<RepositoryWorkspaceFootprint>;

package/dist/runtime/workspace-resource-estimator.js

@@ -0,0 +1,174 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+const GiB = 1024 ** 3;
+const alignmentBytes = 512 * 1024 ** 2;
+export const minimumWorkspaceEstimateBytes = 2 * GiB;
+export const architectMinimumWorkspaceEstimateBytes = GiB;
+const maximumBytes = 100 * GiB;
+const footprintCacheLifetimeMs = 5 * 60_000;
+const excludedDirectories = new Set([
+    ".git",
+    ".artifacts",
+    ".forge-worktrees",
+    ".local",
+    ".next",
+    ".nuget",
+    ".pnpm-store",
+    ".tmp",
+    ".turbo",
+    "artifacts",
+    "bin",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "obj",
+    "testresults",
+]);
+const footprintCache = new Map();
+export async function estimateWorkspaceBytesFromRepo(repoPath, hints = {}) {
+    const cacheKey = path.resolve(repoPath);
+    const cached = footprintCache.get(cacheKey);
+    const footprint = cached && Date.now() - cached.measuredAt < footprintCacheLifetimeMs
+        ? cached.footprint
+        : await measureRepositoryWorkspace(cacheKey);
+    if (!cached || cached.footprint !== footprint) {
+        footprintCache.set(cacheKey, { measuredAt: Date.now(), footprint });
+    }
+    return calculateWorkspaceBytes({
+        ...footprint,
+        hasBrowser: footprint.hasBrowser || hints.browser === true,
+        serviceCount: Math.max(footprint.serviceCount, Math.max(0, hints.serviceCount ?? 0)),
+    }, hints.role);
+}
+export function calculateWorkspaceBytes(footprint, role) {
+    const normalizedRole = role?.trim().toLowerCase() ?? "";
+    if (normalizedRole === "architect") {
+        // Architect owns a checkout and planning artifacts, not dependencies,
+        // build outputs, browser state, services, or application runtime output.
+        const estimate = architectMinimumWorkspaceEstimateBytes
+            + Math.max(0, footprint.sourceBytes) * 2;
+        return Math.min(maximumBytes, Math.max(architectMinimumWorkspaceEstimateBytes, alignUp(estimate, alignmentBytes)));
+    }
+    let estimate = 2 * GiB + Math.max(0, footprint.sourceBytes) * 3;
+    if (footprint.hasNode)
+        estimate += 3 * GiB;
+    if (footprint.hasDotNet)
+        estimate += 2 * GiB;
+    if (footprint.hasBrowser)
+        estimate += 1536 * 1024 ** 2;
+    estimate += Math.max(0, footprint.serviceCount) * GiB;
+    if (["qa", "ci_repair", "pr_fix"].includes(normalizedRole)) {
+        estimate += GiB;
+    }
+    return Math.min(maximumBytes, Math.max(minimumWorkspaceEstimateBytes, alignUp(estimate, alignmentBytes)));
+}
+export async function measureRepositoryWorkspace(repoPath) {
+    return await measureGitWorkspace(repoPath) ?? await measureFilesystemFallback(repoPath);
+}
+async function measureGitWorkspace(repoPath) {
+    let sourceBytes = 0;
+    let hasNode = false;
+    let hasDotNet = false;
+    let hasBrowser = false;
+    let serviceCount = 0;
+    const child = spawn("git", ["-c", "core.quotepath=false", "ls-files", "--cached", "--others", "--exclude-standard"], {
+        cwd: repoPath,
+        env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        stdio: ["ignore", "pipe", "ignore"],
+        windowsHide: true,
+    });
+    const closed = new Promise((resolve) => {
+        child.once("close", resolve);
+        child.once("error", () => resolve(null));
+    });
+    try {
+        const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+        for await (const relativePath of lines) {
+            if (!relativePath.trim())
+                continue;
+            const file = await inspectWorkspaceFile(path.join(repoPath, relativePath));
+            if (!file)
+                continue;
+            sourceBytes += file.bytes;
+            hasNode ||= file.hasNode;
+            hasDotNet ||= file.hasDotNet;
+            hasBrowser ||= file.hasBrowser;
+            serviceCount = Math.max(serviceCount, file.serviceCount);
+        }
+        return await closed === 0 ? { sourceBytes, hasNode, hasDotNet, hasBrowser, serviceCount } : null;
+    }
+    catch {
+        child.kill();
+        await closed;
+        return null;
+    }
+}
+async function measureFilesystemFallback(repoPath) {
+    let sourceBytes = 0;
+    let hasNode = false;
+    let hasDotNet = false;
+    let hasBrowser = false;
+    let serviceCount = 0;
+    const pending = [path.resolve(repoPath)];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const entryPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (!excludedDirectories.has(entry.name.toLowerCase()))
+                    pending.push(entryPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const file = await inspectWorkspaceFile(entryPath);
+            if (!file)
+                continue;
+            sourceBytes += file.bytes;
+            hasNode ||= file.hasNode;
+            hasDotNet ||= file.hasDotNet;
+            hasBrowser ||= file.hasBrowser;
+            serviceCount = Math.max(serviceCount, file.serviceCount);
+        }
+    }
+    return { sourceBytes, hasNode, hasDotNet, hasBrowser, serviceCount };
+}
+async function inspectWorkspaceFile(filePath) {
+    const stat = await fs.stat(filePath).catch(() => null);
+    if (!stat?.isFile())
+        return null;
+    const name = path.basename(filePath).toLowerCase();
+    const sandbox = name === "forge.sandbox.yml" || name === "forge.sandbox.yaml";
+    return {
+        bytes: stat.size,
+        hasNode: ["package.json", "pnpm-lock.yaml", "package-lock.json", "yarn.lock"].includes(name),
+        hasDotNet: name.endsWith(".sln") || name.endsWith(".csproj") || name.endsWith(".fsproj"),
+        hasBrowser: name.startsWith("playwright.config"),
+        serviceCount: sandbox
+            ? countSandboxServices(await fs.readFile(filePath, "utf8").catch(() => ""))
+            : 0,
+    };
+}
+function countSandboxServices(yaml) {
+    let inServices = false;
+    let count = 0;
+    for (const rawLine of yaml.split(/\r?\n/gu)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (!/^\s/u.test(rawLine)) {
+            inServices = line.toLowerCase() === "services:";
+            continue;
+        }
+        if (inServices && line.startsWith("-"))
+            count += 1;
+    }
+    return count;
+}
+function alignUp(value, alignment) {
+    return Math.ceil(value / alignment) * alignment;
+}

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 {
@@ -15,26 +19,66 @@ export declare class DockerPreflight {
     private readonly cacheMs;
     private generation;
     private cached;
-    private cacheAt;
+    private fullPreflightAt;
+    private staticPreflight;
+    private inspectionInFlight;
+    private lastCapacitySample;
     private readonly options;
     private readonly docker;
     private readonly ownership;
     private diskPressureLatched;
+    private readonly memoryAvailability;
     constructor(options?: DockerPreflightOptions | string, commands?: CommandRunner, cacheMs?: number);
+    private unavailable;
+    private memoryReserveBytes;
+    private defaultAdmissionMemoryBytes;
     current(): SandboxPreflightResult | null;
     refresh(): Promise<SandboxPreflightResult>;
     release(): Promise<void>;
     run(force?: boolean): Promise<SandboxPreflightResult>;
+    /**
+     * 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.
+     */
+    refreshCapacity(): Promise<SandboxPreflightResult>;
+    /**
+     * 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.
+     */
+    refreshCapacityForAdmission(): Promise<SandboxPreflightResult>;
+    private startInspection;
     private inspect;
+    private inspectCapacity;
 }
+/**
+ * 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 declare function resolveSandboxHostMemoryReserveBytes(totalMemoryBytes: number, explicitBytes?: number, environment?: NodeJS.ProcessEnv): number;
 export declare function canRunDockerMaintenance(preflight: {
     readonly healthy: boolean;
     readonly unavailableCode?: string | null;
 }): boolean;
 export declare function evaluateDiskPressure(availableBytes: number, totalBytes: number, minimumAvailableBytes: number, highWatermarkPercent: number, lowWatermarkPercent: number, pressureLatched: boolean): boolean;
+export declare function requiredAvailableBytesToClearDiskPressure(totalBytes: number, minimumAvailableBytes: number, lowWatermarkPercent: number): number;
 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 {};