@loucompanion/forge-bridge 0.1.3-dev.ba7d36726eda → 0.1.3-dev.bca7d0ccee53

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

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 const terminalChildStatuses = new Set(["exited", "failed"]);
+const defaultMetadataReadyTimeoutMs = process.platform === "win32" ? 60_000 : 10_000;
 /**
  * Owns the independently supervised process trees that belong to one host
  * dispatch attempt. Each named child gets a distinct Windows Job Object or
@@ -23,7 +24,7 @@ export class AttemptProcessSupervisor {
     constructor(identity, runner, options = {}) {
         this.runner = runner;
         this.identity = validateIdentity(identity);
-        this.metadataReadyTimeoutMs = boundedInteger(options.metadataReadyTimeoutMs ?? 10_000, 100, 120_000, "metadataReadyTimeoutMs");
+        this.metadataReadyTimeoutMs = boundedInteger(options.metadataReadyTimeoutMs ?? defaultMetadataReadyTimeoutMs, 100, 120_000, "metadataReadyTimeoutMs");
         this.ledgerPath = path.join(this.identity.logDirectory, "attempt-process-supervisor.json");
         if (options.signal?.aborted) {
             this.status = "stopping";
@@ -111,6 +112,36 @@ export class AttemptProcessSupervisor {
             stop: async (fencingToken) => await this.stopChild(name, generation, fencingToken),
         };
     }
+    /**
+     * Starts a child and proves that the OS process tree is supervised before
+     * returning it to the caller. A launch that settles before producing its
+     * provider-ready supervision record is safe to retry: the raw runner only
+     * persists that record after the actual provider child has started, before
+     * Forge announces the provider as active.
+     */
+    async startChildReady(name, request, handlers = {}, signal, options = {}) {
+        const maxStartAttempts = boundedInteger(options.maxStartAttempts ?? 1, 1, 5, "maxStartAttempts");
+        const retryDelayMs = boundedInteger(options.retryDelayMs ?? 100, 0, 5_000, "retryDelayMs");
+        let lastError;
+        for (let attempt = 1; attempt <= maxStartAttempts; attempt += 1) {
+            const child = await this.startChild(name, request, handlers, signal);
+            try {
+                await child.ready;
+                return child;
+            }
+            catch (error) {
+                lastError = error;
+                await child.result.catch(() => undefined);
+                if (!isRetryableStartFailure(error) || attempt === maxStartAttempts)
+                    throw error;
+                if (signal?.aborted)
+                    throw cancellationError(signal);
+                if (retryDelayMs > 0)
+                    await wait(retryDelayMs * attempt);
+            }
+        }
+        throw lastError;
+    }
     async stopChild(name, generation, fencingToken, reason = "Forge stopped the supervised child.") {
         this.assertFence(fencingToken);
         const record = this.currentByName.get(name);
@@ -126,16 +157,19 @@ export class AttemptProcessSupervisor {
     }
     async stopAll(fencingToken, reason = "Forge stopped the supervised attempt.") {
         this.assertFence(fencingToken);
+        // The durable terminal ledger is part of the stop operation's contract.
+        // Join an in-flight stop before inspecting terminal state so lease cleanup
+        // cannot remove the log directory underneath its final persistence.
+        if (this.stopOperation)
+            return await this.stopOperation;
         if (this.status === "stopped")
             return;
-        if (!this.stopOperation) {
-            const operation = this.performStopAll(reason);
-            this.stopOperation = operation;
-            void operation.catch(() => undefined).finally(() => {
-                if (this.stopOperation === operation && this.status !== "stopped")
-                    this.stopOperation = null;
-            });
-        }
+        const operation = this.performStopAll(reason);
+        this.stopOperation = operation;
+        void operation.catch(() => undefined).finally(() => {
+            if (this.stopOperation === operation && this.status !== "stopped")
+                this.stopOperation = null;
+        });
         return await this.stopOperation;
     }
     async performStopAll(reason) {
@@ -147,8 +181,13 @@ export class AttemptProcessSupervisor {
         await this.persist();
         const results = await Promise.allSettled(active.map(record => record.result));
         const rejected = results.filter((result) => result.status === "rejected");
-        this.status = rejected.length > 0 || this.persistenceFailure !== undefined ? "degraded" : "stopped";
-        await this.persist();
+        const terminalStatus = rejected.length > 0 || this.persistenceFailure !== undefined ? "degraded" : "stopped";
+        await this.persist({
+            ...this.snapshot(),
+            status: terminalStatus,
+            updatedAt: new Date().toISOString(),
+        });
+        this.status = terminalStatus;
         if (rejected.length > 0) {
             throw new AggregateError(rejected.map(result => result.reason), "attempt_process_supervisor_cleanup_degraded");
         }
@@ -188,12 +227,14 @@ export class AttemptProcessSupervisor {
                 return;
             }
             if (terminalChildStatuses.has(record.status)) {
-                throw new Error(`attempt_process_supervisor_start_failed: child '${record.childId}' exited before supervision metadata was produced.`);
+                const detail = await childStartFailureDetail(record);
+                throw new Error(`attempt_process_supervisor_start_failed: child '${record.childId}' exited before supervision metadata was produced${detail ? `: ${detail}` : "."}`);
             }
             await wait(25);
         }
         record.controller.abort("Supervised child metadata was not produced before the readiness deadline.");
-        throw new Error(`attempt_process_supervisor_start_timeout: child '${record.childId}' did not become supervised.`);
+        const detail = await childStartFailureDetail(record);
+        throw new Error(`attempt_process_supervisor_start_timeout: child '${record.childId}' did not become supervised${detail ? `: ${detail}` : "."}`);
     }
     async settleChild(record, status, exitCode, failure) {
         record.status = status;
@@ -210,8 +251,7 @@ export class AttemptProcessSupervisor {
             throw new Error("attempt_process_supervisor_fenced: fencing token does not own this attempt.");
         }
     }
-    persist() {
-        const snapshot = this.snapshot();
+    persist(snapshot = this.snapshot()) {
         const operation = this.persistTail.then(async () => {
             await ensurePrivateDirectory(this.identity.logDirectory);
             const temporary = `${this.ledgerPath}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
@@ -274,6 +314,26 @@ function boundedFailure(error) {
     const message = error instanceof Error ? error.message : String(error);
     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);
+        return stderr
+            ? `exit ${result.exitCode}; stderr: ${stderr}`
+            : `exit ${result.exitCode}`;
+    }
+    catch (error) {
+        return boundedFailure(error);
+    }
+}
+function boundedDiagnostic(value) {
+    return value.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:"));
+}
 function cancellationError(signal) {
     return new Error(String(signal.reason ?? "Supervised child launch was cancelled."));
 }

package/dist/runtime/generated-output-reset.d.ts

@@ -0,0 +1,10 @@
+export interface GeneratedOutputResetResult {
+    readonly quarantineDirectory: string;
+    readonly quarantinedPaths: readonly string[];
+}
+/**
+ * Moves only known, untracked test-output directories out of a worktree before
+ * a managed attempt starts. The quarantine lives in the attempt-owned output
+ * directory, so cleanup is recoverable and cannot cross the attempt boundary.
+ */
+export declare function resetGeneratedOutputs(worktreePath: string, testOutputDirectory: string): Promise<GeneratedOutputResetResult>;

package/dist/runtime/generated-output-reset.js

@@ -0,0 +1,103 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const generatedDirectoryNames = new Set(["TestResults", "test-results", "playwright-report"]);
+const skippedDirectoryNames = new Set([
+    ".git",
+    ".forge",
+    ".idea",
+    ".next",
+    ".pnpm",
+    ".vs",
+    ".vscode",
+    "bin",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "obj",
+    "target",
+    "vendor",
+]);
+/**
+ * Moves only known, untracked test-output directories out of a worktree before
+ * a managed attempt starts. The quarantine lives in the attempt-owned output
+ * directory, so cleanup is recoverable and cannot cross the attempt boundary.
+ */
+export async function resetGeneratedOutputs(worktreePath, testOutputDirectory) {
+    const worktreeRoot = await fs.realpath(path.resolve(worktreePath));
+    const outputRoot = await fs.realpath(path.resolve(testOutputDirectory));
+    if (isContainedPath(worktreeRoot, outputRoot)) {
+        throw new Error("generated_output_reset_invalid: attempt output must be outside the source worktree.");
+    }
+    const candidates = await findGeneratedDirectories(worktreeRoot);
+    const quarantineDirectory = path.join(outputRoot, "preflight-reset");
+    const quarantinedPaths = [];
+    for (const candidate of candidates) {
+        const relativePath = path.relative(worktreeRoot, candidate);
+        if (!relativePath || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
+            throw new Error("generated_output_reset_invalid: generated output escaped the source worktree.");
+        }
+        await assertUntrackedGeneratedDirectory(worktreeRoot, relativePath);
+        await fs.mkdir(quarantineDirectory, { recursive: true, mode: 0o700 });
+        const digest = createHash("sha256").update(relativePath).digest("hex").slice(0, 12);
+        const destination = path.join(quarantineDirectory, `${digest}-${randomUUID()}-${path.basename(candidate)}`);
+        try {
+            await fs.rename(candidate, destination);
+        }
+        catch (error) {
+            const code = error.code ?? "unknown";
+            throw new Error(`generated_output_reset_failed: could not quarantine ${relativePath} (${code}).`, { cause: error });
+        }
+        quarantinedPaths.push(relativePath.split(path.sep).join("/"));
+    }
+    if (quarantinedPaths.length > 0) {
+        await fs.writeFile(path.join(quarantineDirectory, "manifest.json"), `${JSON.stringify({ schemaVersion: 1, worktreePath: worktreeRoot, quarantinedPaths }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    return { quarantineDirectory, quarantinedPaths };
+}
+async function findGeneratedDirectories(root) {
+    const candidates = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const entries = await fs.readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            if (skippedDirectoryNames.has(entry.name))
+                continue;
+            const candidate = path.join(current, entry.name);
+            if (generatedDirectoryNames.has(entry.name)) {
+                const realCandidate = await fs.realpath(candidate);
+                if (!isContainedPath(root, realCandidate)) {
+                    throw new Error("generated_output_reset_invalid: generated output resolves outside the source worktree.");
+                }
+                candidates.push(realCandidate);
+                continue;
+            }
+            pending.push(candidate);
+        }
+    }
+    return candidates.sort((left, right) => left.localeCompare(right));
+}
+async function assertUntrackedGeneratedDirectory(worktreeRoot, relativePath) {
+    const pathspec = relativePath.split(path.sep).join("/");
+    let stdout;
+    try {
+        ({ stdout } = await execFileAsync("git", ["-C", worktreeRoot, "ls-files", "-z", "--", pathspec], { encoding: "utf8", windowsHide: true, maxBuffer: 4 * 1024 * 1024 }));
+    }
+    catch (error) {
+        throw new Error(`generated_output_reset_unverified: git could not verify ${pathspec}.`, { cause: error });
+    }
+    if (stdout.length > 0) {
+        throw new Error(`generated_output_reset_unsafe: ${pathspec} contains tracked files and was not changed.`);
+    }
+}
+function isContainedPath(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative.length > 0 && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}

package/dist/runtime/host-listener-inspector.d.ts

@@ -16,9 +16,25 @@ export declare class HostListenerInspector {
     private readonly platform;
     constructor(commands?: HostInspectionCommandRunner, platform?: NodeJS.Platform);
     inspect(child: AttemptProcessChildHandle, reservation: HostPortReservation, owner: HostPortLeaseOwner): Promise<HostListenerOwnership>;
+    /** Returns loopback TCP ports opened by one exact supervised child process tree. */
+    inspectOwnedLoopbackListeners(child: AttemptProcessChildHandle, owner: HostPortLeaseOwner): Promise<readonly number[]>;
     private inspectWindows;
+    private inspectAllWindows;
     private inspectUnix;
+    private inspectAllUnix;
 }
+export declare function parseWindowsLoopbackListeners(output: string): readonly {
+    pid: number;
+    port: number;
+}[];
+export declare function parseLsofLoopbackListeners(output: string): readonly {
+    pid: number;
+    port: number;
+}[];
+export declare function parseSsLoopbackListeners(output: string): readonly {
+    pid: number;
+    port: number;
+}[];
 export declare class ExecFileInspectionCommandRunner implements HostInspectionCommandRunner {
     run(command: string, args: readonly string[]): Promise<HostInspectionCommandResult>;
 }

package/dist/runtime/host-listener-inspector.js

@@ -25,6 +25,16 @@ export class HostListenerInspector {
         }
         return await this.inspectUnix(metadata.rootPid, reservation.hostPort);
     }
+    /** Returns loopback TCP ports opened by one exact supervised child process tree. */
+    async inspectOwnedLoopbackListeners(child, owner) {
+        const metadata = await loadMetadata(child.metadataPath);
+        if (!metadata || !matchesOwner(metadata, child, owner)) {
+            throw new Error("host_listener_inspection_invalid: supervised provider ownership metadata is unavailable.");
+        }
+        return this.platform === "win32"
+            ? await this.inspectAllWindows(metadata.rootPid)
+            : await this.inspectAllUnix(metadata.rootPid);
+    }
     async inspectWindows(rootPid, port) {
         const netstat = await this.commands.run("netstat.exe", ["-ano", "-p", "TCP"]);
         if (netstat.exitCode !== 0) {
@@ -59,6 +69,43 @@ export class HostListenerInspector {
         const values = Array.isArray(parsed) ? parsed : [parsed];
         return values.length === listenerPids.length && values.every(value => value === true) ? "owned" : "foreign";
     }
+    async inspectAllWindows(rootPid) {
+        const netstat = await this.commands.run("netstat.exe", ["-ano", "-p", "TCP"]);
+        if (netstat.exitCode !== 0)
+            throw commandError("netstat", netstat);
+        const listeners = parseWindowsLoopbackListeners(netstat.stdout);
+        if (listeners.length === 0)
+            return [];
+        const pids = [...new Set(listeners.map(listener => listener.pid))];
+        const ownership = await this.commands.run(windowsPowerShellPath(), [
+            "-NoLogo",
+            "-NoProfile",
+            "-NonInteractive",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-File",
+            windowsListenerOwnerPath,
+            "-RootProcessId",
+            String(rootPid),
+            "-ListenerProcessIds",
+            pids.join(","),
+        ]);
+        if (ownership.exitCode !== 0)
+            throw commandError("Windows process ancestry", ownership);
+        let parsed;
+        try {
+            parsed = JSON.parse(ownership.stdout.trim());
+        }
+        catch (error) {
+            throw new Error("host_listener_inspection_failed: Windows ancestry output was invalid.", { cause: error });
+        }
+        const values = Array.isArray(parsed) ? parsed : [parsed];
+        if (values.length !== pids.length || values.some(value => typeof value !== "boolean")) {
+            throw new Error("host_listener_inspection_failed: Windows ancestry output was incomplete.");
+        }
+        const ownedPids = new Set(pids.filter((_pid, index) => values[index] === true));
+        return uniqueSorted(listeners.filter(listener => ownedPids.has(listener.pid)).map(listener => listener.port));
+    }
     async inspectUnix(rootPid, port) {
         let listenerPids = null;
         const lsof = await this.commands.run("lsof", [
@@ -93,13 +140,84 @@ export class HostListenerInspector {
         const groups = parseProcessGroups(processGroups.stdout);
         return listenerPids.every(pid => groups.get(pid) === rootPid) ? "owned" : "foreign";
     }
+    async inspectAllUnix(rootPid) {
+        const lsof = await this.commands.run("lsof", [
+            "-nP",
+            "-a",
+            "-iTCP@127.0.0.1",
+            "-sTCP:LISTEN",
+            "-Fpn",
+        ]);
+        let listeners;
+        if (lsof.exitCode === 0 || lsof.exitCode === 1) {
+            listeners = parseLsofLoopbackListeners(lsof.stdout);
+        }
+        else if (lsof.errorCode === "ENOENT") {
+            const ss = await this.commands.run("ss", ["-H", "-ltnp"]);
+            if (ss.exitCode !== 0)
+                throw commandError("ss", ss);
+            listeners = parseSsLoopbackListeners(ss.stdout);
+        }
+        else {
+            throw commandError("lsof", lsof);
+        }
+        if (listeners.length === 0)
+            return [];
+        const pids = [...new Set(listeners.map(listener => listener.pid))];
+        const processGroups = await this.commands.run("ps", ["-o", "pid=,pgid=", "-p", pids.join(",")]);
+        if (processGroups.exitCode !== 0)
+            throw commandError("ps", processGroups);
+        const groups = parseProcessGroups(processGroups.stdout);
+        return uniqueSorted(listeners
+            .filter(listener => groups.get(listener.pid) === rootPid)
+            .map(listener => listener.port));
+    }
+}
+export function parseWindowsLoopbackListeners(output) {
+    return uniqueListeners(output.split(/\r?\n/u).flatMap(line => {
+        const fields = line.trim().split(/\s+/u);
+        if (fields.length < 5 || fields[0]?.toUpperCase() !== "TCP" || fields[3]?.toUpperCase() !== "LISTENING")
+            return [];
+        const endpoint = parseIpv4LoopbackEndpoint(fields[1]);
+        const pids = validPid(fields[4]);
+        return endpoint && pids.length === 1 ? [{ pid: pids[0], port: endpoint }] : [];
+    }));
+}
+export function parseLsofLoopbackListeners(output) {
+    const listeners = [];
+    let pid = null;
+    for (const line of output.split(/\r?\n/u)) {
+        if (line.startsWith("p"))
+            pid = validPid(line.slice(1))[0] ?? null;
+        if (!line.startsWith("n") || pid === null)
+            continue;
+        const port = parseIpv4LoopbackEndpoint(line.slice(1));
+        if (port !== null)
+            listeners.push({ pid, port });
+    }
+    return uniqueListeners(listeners);
+}
+export function parseSsLoopbackListeners(output) {
+    return uniqueListeners(output.split(/\r?\n/u).flatMap(line => {
+        const endpoint = line.match(/127\.0\.0\.1:(\d+)/u)?.[1];
+        const port = endpoint ? Number.parseInt(endpoint, 10) : 0;
+        if (!Number.isSafeInteger(port) || port < 1 || port > 65535)
+            return [];
+        return [...line.matchAll(/pid=(\d+)/gu)].flatMap(match => {
+            const pid = validPid(match[1])[0];
+            return pid ? [{ pid, port }] : [];
+        });
+    }));
 }
 export class ExecFileInspectionCommandRunner {
     run(command, args) {
         return new Promise(resolve => {
-            execFile(command, args, {
+            const executable = process.platform === "win32" && command.toLowerCase() === "netstat.exe"
+                ? windowsSystemExecutable("netstat.exe")
+                : command;
+            execFile(executable, args, {
                 windowsHide: true,
-                timeout: 5_000,
+                timeout: 15_000,
                 maxBuffer: 4 * 1024 * 1024,
             }, (error, stdout, stderr) => {
                 const processError = error;
@@ -175,11 +293,32 @@ function validPid(value) {
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left - right);
 }
+function parseIpv4LoopbackEndpoint(value) {
+    const match = value?.match(/^127\.0\.0\.1:(\d+)$/u);
+    if (!match)
+        return null;
+    const port = Number.parseInt(match[1], 10);
+    return Number.isSafeInteger(port) && port >= 1 && port <= 65535 ? port : null;
+}
+function uniqueListeners(values) {
+    const seen = new Set();
+    return values.filter(value => {
+        const key = `${value.pid}:${value.port}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    }).sort((left, right) => left.port - right.port || left.pid - right.pid);
+}
 function commandError(label, result) {
     const detail = result.stderr.replaceAll(/[\r\n\t]+/gu, " ").trim().slice(0, 512);
-    return new Error(`host_listener_inspection_failed: ${label} exited ${result.exitCode}${detail ? `: ${detail}` : ""}.`);
+    const code = result.errorCode ? ` (${result.errorCode})` : "";
+    return new Error(`host_listener_inspection_failed: ${label} exited ${result.exitCode}${code}${detail ? `: ${detail}` : ""}.`);
 }
 function windowsPowerShellPath() {
+    return path.win32.join(path.dirname(windowsSystemExecutable("netstat.exe")), "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+function windowsSystemExecutable(name) {
     const systemRoot = process.env.SystemRoot?.trim() || "C:\\Windows";
-    return path.win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    return path.win32.join(systemRoot, "System32", name);
 }

package/dist/runtime/host-runtime-contract.d.ts

@@ -5,6 +5,7 @@ export interface HostRuntimeLaunchConfig {
     readonly command: string;
     readonly args: readonly string[];
     readonly workingDirectory: string;
+    readonly environment?: Readonly<Record<string, string>>;
 }
 export interface HostRuntimePortConfig {
     readonly name: string;
@@ -31,7 +32,14 @@ export interface HostRuntimeContract {
 }
 export interface LoadedHostRuntimeContract {
     readonly contract: HostRuntimeContract;
-    readonly source: "default" | "project";
+    readonly source: "default" | "project" | "derived";
+    readonly discovery?: HostRuntimeDiscovery | null;
+}
+export interface HostRuntimeDiscovery {
+    readonly status: "derived" | "ambiguous" | "unsupported";
+    readonly reasonCode: string;
+    readonly summary: string;
+    readonly candidateFingerprint?: string | null;
 }
 export declare function loadHostRuntimeContract(worktreePath: string): Promise<LoadedHostRuntimeContract>;
 export declare function defaultHostRuntimeContract(): HostRuntimeContract;