@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.04a1e5b9e484

package/dist/runtime/attempt-private-directory.js

@@ -0,0 +1,54 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runAttemptPathOperation } from "./attempt-path-operation.js";
+/** Validate every existing ancestor before creating anything through a pathname. */
+export async function assertCanonicalDirectory(target, allowMissing = false) {
+    const resolved = path.resolve(target);
+    const parent = path.dirname(resolved);
+    if (parent !== resolved)
+        await assertCanonicalDirectory(parent, allowMissing);
+    try {
+        const stat = await fs.lstat(resolved, { bigint: true });
+        const real = await fs.realpath(resolved);
+        const realStat = await fs.lstat(real, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isDirectory() || !samePath(real, resolved)
+            || stat.dev !== realStat.dev || stat.ino !== realStat.ino) {
+            throw new Error("playwright_runtime_adapter_invalid: writable paths must be canonical, link-free directories.");
+        }
+        return realStat;
+    }
+    catch (error) {
+        if (allowMissing && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+export async function createCanonicalDirectory(target) {
+    if (await assertCanonicalDirectory(target, true))
+        return;
+    const resolved = path.resolve(target);
+    let parent = path.dirname(resolved);
+    let identity = await assertCanonicalDirectory(parent, true);
+    while (!identity) {
+        parent = path.dirname(parent);
+        identity = await assertCanonicalDirectory(parent, true);
+    }
+    await runAttemptPathOperation(parent, identity, { kind: "mkdir", segments: path.relative(parent, resolved).split(path.sep) });
+    await assertCanonicalDirectory(resolved);
+}
+export async function createPrivateCanonicalDirectory(target) {
+    await createCanonicalDirectory(target);
+    await restorePrivateDirectoryMode(target);
+}
+export async function restorePrivateDirectoryMode(target) {
+    if (process.platform === "win32")
+        return;
+    const resolved = path.resolve(target);
+    const parent = path.dirname(resolved);
+    const identity = await assertCanonicalDirectory(parent);
+    await runAttemptPathOperation(parent, identity, { kind: "private-directory-mode", segments: [path.basename(resolved)] });
+    await assertCanonicalDirectory(resolved);
+}
+function samePath(left, right) {
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}

package/dist/runtime/attempt-process-supervisor.d.ts

@@ -19,6 +19,10 @@ export interface AttemptProcessChildLedgerEntry {
     readonly settledAt?: string;
     readonly exitCode?: number;
     readonly failure?: string;
+    readonly peakMemoryBytes?: number;
+    readonly memorySampleCount?: number;
+    readonly memorySource?: string;
+    readonly memoryObservedAt?: string;
 }
 export interface AttemptProcessSupervisorLedger {
     readonly schemaVersion: 1;
@@ -42,6 +46,8 @@ export interface AttemptProcessChildHandle {
 export interface AttemptProcessSupervisorOptions {
     readonly metadataReadyTimeoutMs?: number;
     readonly signal?: AbortSignal;
+    readonly replaceLedgerFile?: (temporaryPath: string, ledgerPath: string) => Promise<void>;
+    readonly ledgerReplaceRetryMs?: number;
 }
 export interface AttemptProcessChildReadyOptions {
     readonly maxStartAttempts?: number;
@@ -58,6 +64,8 @@ export declare class AttemptProcessSupervisor {
     readonly ledgerPath: string;
     private readonly identity;
     private readonly metadataReadyTimeoutMs;
+    private readonly replaceLedgerFile;
+    private readonly ledgerReplaceRetryMs;
     private readonly records;
     private readonly currentByName;
     private readonly attemptController;
@@ -79,8 +87,16 @@ export declare class AttemptProcessSupervisor {
     stopAll(fencingToken: string, reason?: unknown): Promise<void>;
     private performStopAll;
     snapshot(): AttemptProcessSupervisorLedger;
+    providerMemoryTelemetry(): AttemptProcessTreeMemoryTelemetry | null;
     private observeChildReady;
     private settleChild;
+    private replaceLedger;
     private assertFence;
     private persist;
 }
+export interface AttemptProcessTreeMemoryTelemetry {
+    readonly peakMemoryBytes: number;
+    readonly sampleCount: number;
+    readonly source: string;
+    readonly observedAt: string;
+}

package/dist/runtime/attempt-process-supervisor.js

@@ -1,8 +1,15 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { ForgeFailureError, sanitizeFailureError } from "../session/session.types.js";
+import { monotonicNowMs } from "../shared/time/monotonic.js";
 const terminalChildStatuses = new Set(["exited", "failed"]);
 const defaultMetadataReadyTimeoutMs = process.platform === "win32" ? 60_000 : 10_000;
+// Windows refuses to replace a file another process (a scanner or indexer) briefly holds
+// open. One such refusal must not degrade the attempt, so the ledger replace is retried.
+const ledgerReplaceAttempts = 40;
+const defaultLedgerReplaceRetryMs = 25;
+const transientLedgerReplaceCodes = new Set(["EPERM", "EACCES", "EBUSY"]);
 /**
  * Owns the independently supervised process trees that belong to one host
  * dispatch attempt. Each named child gets a distinct Windows Job Object or
@@ -14,6 +21,8 @@ export class AttemptProcessSupervisor {
     ledgerPath;
     identity;
     metadataReadyTimeoutMs;
+    replaceLedgerFile;
+    ledgerReplaceRetryMs;
     records = [];
     currentByName = new Map();
     attemptController = new AbortController();
@@ -25,6 +34,8 @@ export class AttemptProcessSupervisor {
         this.runner = runner;
         this.identity = validateIdentity(identity);
         this.metadataReadyTimeoutMs = boundedInteger(options.metadataReadyTimeoutMs ?? defaultMetadataReadyTimeoutMs, 100, 120_000, "metadataReadyTimeoutMs");
+        this.replaceLedgerFile = options.replaceLedgerFile ?? ((temporaryPath, ledgerPath) => fs.rename(temporaryPath, ledgerPath));
+        this.ledgerReplaceRetryMs = options.ledgerReplaceRetryMs ?? defaultLedgerReplaceRetryMs;
         this.ledgerPath = path.join(this.identity.logDirectory, "attempt-process-supervisor.json");
         if (options.signal?.aborted) {
             this.status = "stopping";
@@ -32,9 +43,11 @@ export class AttemptProcessSupervisor {
         }
         else {
             options.signal?.addEventListener("abort", () => {
-                void this.stopAll(this.identity.fencingToken, options.signal?.reason).catch(error => {
-                    this.persistenceFailure ??= error;
-                });
+                // stopAll already persists a degraded terminal snapshot when a child
+                // rejects during cancellation. Do not relabel that process failure as
+                // a persistence failure: doing so poisons every later cleanup retry,
+                // even after all supervised processes have exited.
+                void this.stopAll(this.identity.fencingToken, options.signal?.reason).catch(() => undefined);
             }, { once: true });
         }
     }
@@ -57,8 +70,10 @@ export class AttemptProcessSupervisor {
         const combinedSignal = signal
             ? AbortSignal.any([this.attemptController.signal, controller.signal, signal])
             : AbortSignal.any([this.attemptController.signal, controller.signal]);
+        const failureRedactionValues = [...new Set((request.failureRedactionValues ?? []).filter(value => value.length > 0))];
+        const { failureRedactionValues: _failureRedactionValues, ...executableRequest } = request;
         const childRequest = {
-            ...request,
+            ...executableRequest,
             env: {
                 ...request.env,
                 FORGE_RUNTIME_MODE: "host",
@@ -82,6 +97,7 @@ export class AttemptProcessSupervisor {
             processSupervisorId,
             metadataPath,
             controller,
+            failureRedactionValues,
             startedAt,
             status: "starting",
             result: Promise.resolve({ exitCode: 1, stdout: "", stderr: "not started" }),
@@ -90,7 +106,7 @@ export class AttemptProcessSupervisor {
         this.currentByName.set(name, record);
         const result = this.runner.run(childRequest, handlers, combinedSignal);
         record.result = result;
-        void result.then(value => this.settleChild(record, "exited", value.exitCode), error => this.settleChild(record, "failed", undefined, error));
+        void result.then(value => this.settleChild(record, "exited", value.exitCode, undefined, value), error => this.settleChild(record, "failed", undefined, error));
         try {
             await this.persist();
         }
@@ -180,7 +196,9 @@ export class AttemptProcessSupervisor {
             record.status = "stopping";
         await this.persist();
         const results = await Promise.allSettled(active.map(record => record.result));
-        const rejected = results.filter((result) => result.status === "rejected");
+        const rejected = results.flatMap((result, index) => result.status === "rejected"
+            ? [sanitizeFailureError(result.reason, active[index].failureRedactionValues)]
+            : []);
         const terminalStatus = rejected.length > 0 || this.persistenceFailure !== undefined ? "degraded" : "stopped";
         await this.persist({
             ...this.snapshot(),
@@ -189,7 +207,7 @@ export class AttemptProcessSupervisor {
         });
         this.status = terminalStatus;
         if (rejected.length > 0) {
-            throw new AggregateError(rejected.map(result => result.reason), "attempt_process_supervisor_cleanup_degraded");
+            throw new AggregateError(rejected, "attempt_process_supervisor_cleanup_degraded");
         }
         if (this.persistenceFailure !== undefined)
             throw this.persistenceFailure;
@@ -213,12 +231,35 @@ export class AttemptProcessSupervisor {
                 ...(record.settledAt ? { settledAt: record.settledAt } : {}),
                 ...(record.exitCode === undefined ? {} : { exitCode: record.exitCode }),
                 ...(record.failure ? { failure: record.failure } : {}),
+                ...(record.peakMemoryBytes === undefined ? {} : { peakMemoryBytes: record.peakMemoryBytes }),
+                ...(record.memorySampleCount === undefined ? {} : { memorySampleCount: record.memorySampleCount }),
+                ...(record.memorySource ? { memorySource: record.memorySource } : {}),
+                ...(record.memoryObservedAt ? { memoryObservedAt: record.memoryObservedAt } : {}),
             })),
         };
     }
+    providerMemoryTelemetry() {
+        const observations = this.records
+            .filter(record => record.name === "provider"
+            && record.peakMemoryBytes !== undefined
+            && record.peakMemoryBytes > 0
+            && record.memorySampleCount !== undefined
+            && record.memorySampleCount > 0
+            && record.memorySource
+            && record.memoryObservedAt);
+        if (observations.length === 0)
+            return null;
+        const peak = observations.reduce((current, candidate) => (candidate.peakMemoryBytes ?? 0) > (current.peakMemoryBytes ?? 0) ? candidate : current);
+        return {
+            peakMemoryBytes: peak.peakMemoryBytes,
+            sampleCount: observations.reduce((total, candidate) => total + (candidate.memorySampleCount ?? 0), 0),
+            source: peak.memorySource,
+            observedAt: peak.memoryObservedAt,
+        };
+    }
     async observeChildReady(record) {
-        const deadline = Date.now() + this.metadataReadyTimeoutMs;
-        while (Date.now() <= deadline) {
+        const deadline = monotonicNowMs() + this.metadataReadyTimeoutMs;
+        while (monotonicNowMs() <= deadline) {
             if (await fileExists(record.metadataPath)) {
                 if (record.status === "starting") {
                     record.status = "running";
@@ -228,24 +269,51 @@ export class AttemptProcessSupervisor {
             }
             if (terminalChildStatuses.has(record.status)) {
                 const detail = await childStartFailureDetail(record);
-                throw new Error(`attempt_process_supervisor_start_failed: child '${record.childId}' exited before supervision metadata was produced${detail ? `: ${detail}` : "."}`);
+                throw new ForgeFailureError("attempt_process_supervisor_start_failed", `attempt_process_supervisor_start_failed: child '${record.childId}' exited before supervision metadata was produced${detail ? `: ${detail}` : "."}`, "bridge");
             }
             await wait(25);
         }
         record.controller.abort("Supervised child metadata was not produced before the readiness deadline.");
         const detail = await childStartFailureDetail(record);
-        throw new Error(`attempt_process_supervisor_start_timeout: child '${record.childId}' did not become supervised${detail ? `: ${detail}` : "."}`);
+        throw new ForgeFailureError("attempt_process_supervisor_start_timeout", `attempt_process_supervisor_start_timeout: child '${record.childId}' did not become supervised${detail ? `: ${detail}` : "."}`, "bridge");
     }
-    async settleChild(record, status, exitCode, failure) {
+    async settleChild(record, status, exitCode, failure, result) {
         record.status = status;
         record.settledAt = new Date().toISOString();
         record.exitCode = exitCode;
-        record.failure = failure === undefined ? undefined : boundedFailure(failure);
+        record.failure = failure === undefined
+            ? undefined
+            : boundedFailure(failure, record.failureRedactionValues);
+        if (result?.peakMemoryBytes !== undefined
+            && result.peakMemoryBytes > 0
+            && result.memorySampleCount !== undefined
+            && result.memorySampleCount > 0
+            && result.memorySource
+            && result.memoryObservedAt) {
+            record.peakMemoryBytes = result.peakMemoryBytes;
+            record.memorySampleCount = result.memorySampleCount;
+            record.memorySource = result.memorySource;
+            record.memoryObservedAt = result.memoryObservedAt;
+        }
         await this.persist().catch(error => {
             this.persistenceFailure ??= error;
             this.status = "degraded";
         });
     }
+    async replaceLedger(temporary) {
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await this.replaceLedgerFile(temporary, this.ledgerPath);
+                return;
+            }
+            catch (error) {
+                const code = error.code;
+                if (attempt >= ledgerReplaceAttempts || !code || !transientLedgerReplaceCodes.has(code))
+                    throw error;
+                await wait(this.ledgerReplaceRetryMs);
+            }
+        }
+    }
     assertFence(fencingToken) {
         if (fencingToken !== this.identity.fencingToken) {
             throw new Error("attempt_process_supervisor_fenced: fencing token does not own this attempt.");
@@ -264,7 +332,7 @@ export class AttemptProcessSupervisor {
                 finally {
                     await handle.close();
                 }
-                await fs.rename(temporary, this.ledgerPath);
+                await this.replaceLedger(temporary);
             }
             catch (error) {
                 await fs.rm(temporary, { force: true }).catch(() => undefined);
@@ -310,29 +378,32 @@ function boundedInteger(value, minimum, maximum, name) {
     }
     return value;
 }
-function boundedFailure(error) {
-    const message = error instanceof Error ? error.message : String(error);
+function boundedFailure(error, exactSecrets = []) {
+    const message = sanitizeFailureError(error, exactSecrets).message;
     return message.replaceAll(/[\r\n\t]+/gu, " ").slice(0, 512);
 }
 async function childStartFailureDetail(record) {
     try {
         const result = await record.result;
-        const stderr = boundedDiagnostic(result.stderr);
+        const stderr = boundedDiagnostic(result.stderr, record.failureRedactionValues);
         return stderr
             ? `exit ${result.exitCode}; stderr: ${stderr}`
             : `exit ${result.exitCode}`;
     }
     catch (error) {
-        return boundedFailure(error);
+        return boundedFailure(error, record.failureRedactionValues);
     }
 }
-function boundedDiagnostic(value) {
-    return value.replaceAll(/[\r\n\t]+/gu, " ").trim().slice(0, 512);
+function boundedDiagnostic(value, exactSecrets = []) {
+    return sanitizeFailureError(value, exactSecrets).message
+        .replaceAll(/[\r\n\t]+/gu, " ")
+        .trim()
+        .slice(0, 512);
 }
 function isRetryableStartFailure(error) {
-    return error instanceof Error
-        && (error.message.startsWith("attempt_process_supervisor_start_failed:")
-            || error.message.startsWith("attempt_process_supervisor_start_timeout:"));
+    return error instanceof ForgeFailureError
+        && (error.failureCode === "attempt_process_supervisor_start_failed"
+            || error.failureCode === "attempt_process_supervisor_start_timeout");
 }
 function cancellationError(signal) {
     return new Error(String(signal.reason ?? "Supervised child launch was cancelled."));

package/dist/runtime/canonical-source-file.d.ts

@@ -0,0 +1,3 @@
+import type { PinnedDirectoryIdentity } from "./pinned-directory-process.js";
+/** Keep the validated source inode open: reopening a checked pathname can follow a replacement. */
+export declare function readCanonicalSourceFile(target: string, maximumBytes: number, expectedIdentity?: PinnedDirectoryIdentity): Promise<Buffer>;

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

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

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

@@ -0,0 +1,90 @@
+import type { CommandRunner } from "../sandbox/sandbox.types.js";
+export interface DockerEngineCapabilitySnapshot {
+    readonly available: boolean;
+    readonly sampledAt: string;
+    readonly runtimeVersion: string | null;
+    readonly operatingSystem: string | null;
+    readonly context: string;
+    readonly unavailableCode: string | null;
+    readonly unavailableReason: string | null;
+}
+export interface DockerEngineProbeOptions {
+    readonly dockerExecutable?: string;
+    readonly dockerContext?: string;
+    readonly recovery?: DockerEngineRecoveryPolicy;
+    readonly recoveryExecutor?: DockerEngineRecoveryExecutor;
+    readonly platform?: NodeJS.Platform;
+    readonly dockerHost?: string;
+    readonly now?: () => number;
+    readonly wait?: (delayMs: number) => Promise<void>;
+    readonly onStatus?: (message: string) => void;
+}
+export interface DockerEngineRecoveryPolicy {
+    readonly enabled: boolean;
+    readonly failureThreshold?: number;
+    readonly confirmationDelayMs?: number;
+    readonly cooldownMs?: number;
+    readonly startupTimeoutMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly canRecover?: () => boolean;
+}
+export interface DockerEngineRecoveryResult {
+    readonly started: boolean;
+    readonly reason?: string;
+}
+export interface DockerEngineRecoveryExecutor {
+    restart(): Promise<DockerEngineRecoveryResult>;
+}
+/**
+ * Probes ordinary Docker-daemon access for host-run Testcontainers and project
+ * services. This is deliberately independent from the stricter Forge sandbox
+ * preflight: a usable Docker Desktop engine may satisfy docker_engine even
+ * when it is not approved to host an agent sandbox.
+ */
+export declare class DockerEngineProbe {
+    private readonly commands;
+    private readonly cacheMs;
+    private cached;
+    private sampledAtMs;
+    private inFlight;
+    private requiredWorkRecoveryInFlight;
+    private consecutiveFailures;
+    private lastRecoveryAttemptAtMs;
+    private readonly docker;
+    private readonly context;
+    private readonly platform;
+    private readonly dockerHost;
+    private readonly now;
+    private readonly wait;
+    private readonly recovery;
+    private readonly recoveryExecutor;
+    private readonly onStatus;
+    constructor(options?: DockerEngineProbeOptions, commands?: CommandRunner, cacheMs?: number);
+    current(): DockerEngineCapabilitySnapshot | null;
+    refresh(force?: boolean): Promise<DockerEngineCapabilitySnapshot>;
+    /**
+     * Establishes a fresh daemon fence for work that declares Docker as a hard
+     * prerequisite. This remains bounded, cooldown protected and single-flight;
+     * it never contacts Docker unless a caller explicitly invokes this method.
+     */
+    ensureAvailableForRequiredWork(): Promise<DockerEngineCapabilitySnapshot>;
+    private inspectSafely;
+    private recoverIfEligible;
+    private isLocalDockerDesktopContext;
+    private inspect;
+}
+/**
+ * Restarts only the local Docker Desktop installation. It never targets a
+ * remote daemon and is used only behind the explicit bridge recovery policy.
+ */
+export declare class WindowsDockerDesktopRecoveryExecutor implements DockerEngineRecoveryExecutor {
+    private readonly platform;
+    private readonly commands;
+    private readonly programFiles;
+    private readonly wait;
+    constructor(platform?: NodeJS.Platform, commands?: CommandRunner, programFiles?: string, wait?: (delayMs: number) => Promise<void>);
+    restart(): Promise<DockerEngineRecoveryResult>;
+    private readProcessState;
+    private cleanupOrphanedCompanions;
+    private startDesktop;
+}