@loucompanion/forge-bridge 0.1.3-dev.b3bce6ba65a6 → 0.1.3-dev.ba293ccf876b

package/dist/runtime/docker-engine-probe.js

@@ -0,0 +1,300 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BoundedCommandRunner } from "../sandbox/command-runner.js";
+/**
+ * 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 class DockerEngineProbe {
+    commands;
+    cacheMs;
+    cached = null;
+    sampledAtMs = 0;
+    inFlight = null;
+    consecutiveFailures = 0;
+    lastRecoveryAttemptAtMs = null;
+    docker;
+    context;
+    platform;
+    dockerHost;
+    now;
+    wait;
+    recovery;
+    recoveryExecutor;
+    onStatus;
+    constructor(options = {}, commands = new BoundedCommandRunner(), cacheMs = 15_000) {
+        this.commands = commands;
+        this.cacheMs = cacheMs;
+        this.docker = options.dockerExecutable ?? process.env.FORGE_DOCKER_EXECUTABLE ?? "docker";
+        this.context = options.dockerContext?.trim() || process.env.DOCKER_CONTEXT?.trim() || "default";
+        this.platform = options.platform ?? process.platform;
+        this.dockerHost = options.dockerHost ?? process.env.DOCKER_HOST?.trim() ?? "";
+        this.now = options.now ?? Date.now;
+        this.wait = options.wait ?? (delayMs => new Promise(resolve => setTimeout(resolve, delayMs)));
+        this.recovery = {
+            enabled: options.recovery?.enabled ?? false,
+            failureThreshold: positiveInteger(options.recovery?.failureThreshold, 3),
+            confirmationDelayMs: positiveInteger(options.recovery?.confirmationDelayMs, 30_000),
+            cooldownMs: positiveInteger(options.recovery?.cooldownMs, 10 * 60_000),
+            startupTimeoutMs: positiveInteger(options.recovery?.startupTimeoutMs, 2 * 60_000),
+            pollIntervalMs: positiveInteger(options.recovery?.pollIntervalMs, 2_000),
+            canRecover: options.recovery?.canRecover,
+        };
+        this.recoveryExecutor = options.recoveryExecutor ?? new WindowsDockerDesktopRecoveryExecutor(this.platform, commands);
+        this.onStatus = options.onStatus ?? (() => undefined);
+    }
+    current() {
+        return this.cached;
+    }
+    async refresh(force = false) {
+        if (!force && this.cached && this.now() - this.sampledAtMs < this.cacheMs) {
+            return this.cached;
+        }
+        if (this.inFlight)
+            return await this.inFlight;
+        const operation = this.inspectSafely()
+            .then(result => this.recoverIfEligible(result))
+            .then((result) => {
+            this.cached = result;
+            this.sampledAtMs = this.now();
+            return result;
+        })
+            .finally(() => {
+            if (this.inFlight === operation)
+                this.inFlight = null;
+        });
+        this.inFlight = operation;
+        return await operation;
+    }
+    async inspectSafely() {
+        return await this.inspect().catch((error) => unavailable(this.context, "docker_engine_unreachable", error instanceof Error ? error.message : String(error)));
+    }
+    async recoverIfEligible(snapshot) {
+        if (snapshot.available) {
+            this.consecutiveFailures = 0;
+            return snapshot;
+        }
+        this.consecutiveFailures += 1;
+        if (!this.recovery.enabled
+            || !this.isLocalDockerDesktopContext()
+            || this.consecutiveFailures < this.recovery.failureThreshold
+            || this.recovery.canRecover?.() === false) {
+            return snapshot;
+        }
+        const now = this.now();
+        if (this.lastRecoveryAttemptAtMs !== null
+            && now - this.lastRecoveryAttemptAtMs < this.recovery.cooldownMs) {
+            return snapshot;
+        }
+        this.onStatus(`Docker engine remained unavailable for ${this.consecutiveFailures} consecutive probes; waiting for one fresh confirmation before recovery.`);
+        await this.wait(this.recovery.confirmationDelayMs);
+        const confirmed = await this.inspectSafely();
+        if (confirmed.available) {
+            this.consecutiveFailures = 0;
+            this.onStatus("Docker engine recovered during the confirmation window; skipped Docker Desktop recovery.");
+            return confirmed;
+        }
+        if (this.recovery.canRecover?.() === false) {
+            this.onStatus("Docker Desktop recovery was deferred because runner work became active during confirmation.");
+            return confirmed;
+        }
+        this.consecutiveFailures += 1;
+        this.lastRecoveryAttemptAtMs = this.now();
+        this.onStatus(`Docker engine remained unavailable after confirmation; starting one bounded Docker Desktop recovery.`);
+        const recovery = await this.recoveryExecutor.restart().catch((error) => ({
+            started: false,
+            reason: error instanceof Error ? error.message : String(error),
+        }));
+        if (!recovery.started) {
+            const reason = recovery.reason?.trim() || "Docker Desktop recovery could not be started.";
+            this.onStatus(`Docker Desktop recovery failed to start: ${singleLine(reason)}`);
+            return unavailable(this.context, "docker_engine_recovery_failed", reason);
+        }
+        const deadline = this.now() + this.recovery.startupTimeoutMs;
+        while (this.now() < deadline) {
+            await this.wait(Math.min(this.recovery.pollIntervalMs, Math.max(1, deadline - this.now())));
+            const verified = await this.inspectSafely();
+            if (verified.available) {
+                this.consecutiveFailures = 0;
+                this.onStatus("Docker Desktop recovery completed and the engine passed a fresh daemon probe.");
+                return verified;
+            }
+        }
+        this.onStatus("Docker Desktop recovery timed out before the engine became reachable; cooldown is active.");
+        return unavailable(this.context, "docker_engine_recovery_timeout", "Docker Desktop restart was requested, but the engine did not become reachable before the recovery timeout.");
+    }
+    isLocalDockerDesktopContext() {
+        return this.platform === "win32"
+            && !this.dockerHost
+            && (this.context === "default" || this.context === "desktop-linux");
+    }
+    async inspect() {
+        const dockerArgs = this.context === "default" ? [] : ["--context", this.context];
+        const result = await this.commands.run(this.docker, [...dockerArgs, "info", "--format", "{{json .}}"], { timeoutMs: 10_000, maxOutputBytes: 512 * 1024 });
+        if (result.exitCode !== 0) {
+            return unavailable(this.context, "docker_engine_unreachable", result.stderr || result.stdout || "Docker daemon is unreachable.");
+        }
+        let info;
+        try {
+            const parsed = JSON.parse(result.stdout.trim());
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error("not an object");
+            info = parsed;
+        }
+        catch {
+            return unavailable(this.context, "docker_engine_invalid_response", "Docker returned an invalid info document.");
+        }
+        const version = clean(info.ServerVersion);
+        return {
+            available: true,
+            sampledAt: new Date().toISOString(),
+            runtimeVersion: version ? `docker/${version}` : "docker/unknown",
+            operatingSystem: clean(info.OSType)?.toLowerCase() ?? null,
+            context: this.context,
+            unavailableCode: null,
+            unavailableReason: null,
+        };
+    }
+}
+/**
+ * Restarts only the local Docker Desktop installation. It never targets a
+ * remote daemon and is used only behind the explicit bridge recovery policy.
+ */
+export class WindowsDockerDesktopRecoveryExecutor {
+    platform;
+    commands;
+    programFiles;
+    wait;
+    constructor(platform = process.platform, commands = new BoundedCommandRunner(), programFiles = process.env.ProgramFiles ?? "C:\\Program Files", wait = delayMs => new Promise(resolve => setTimeout(resolve, delayMs))) {
+        this.platform = platform;
+        this.commands = commands;
+        this.programFiles = programFiles;
+        this.wait = wait;
+    }
+    async restart() {
+        if (this.platform !== "win32") {
+            return { started: false, reason: "Automatic Docker Desktop recovery is supported only on Windows." };
+        }
+        const installRoot = path.join(this.programFiles, "Docker", "Docker");
+        const desktopExecutable = path.join(installRoot, "Docker Desktop.exe");
+        if (!fs.existsSync(desktopExecutable)) {
+            return { started: false, reason: "Docker Desktop executable was not found in the standard installation directory." };
+        }
+        const processState = await this.readProcessState();
+        if (processState === "unknown") {
+            return { started: false, reason: "Docker Desktop process state could not be determined safely." };
+        }
+        if (processState === "stopped") {
+            if (!await this.cleanupOrphanedCompanions()) {
+                return { started: false, reason: "Orphaned Docker Desktop companion processes could not be verified and cleaned safely." };
+            }
+            await this.wait(1_000);
+            return await this.startDesktop(desktopExecutable);
+        }
+        const dockerCli = path.join(installRoot, "DockerCli.exe");
+        if (fs.existsSync(dockerCli)) {
+            await this.commands.run(dockerCli, ["-Shutdown"], {
+                timeoutMs: 15_000,
+                maxOutputBytes: 64 * 1024,
+            }).catch(() => undefined);
+        }
+        const stopScript = [
+            "$ErrorActionPreference = 'SilentlyContinue'",
+            "Get-Process | Where-Object { $_.ProcessName -in @('Docker Desktop', 'com.docker.backend') } | Stop-Process -Force",
+        ].join("; ");
+        await this.commands.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", stopScript], {
+            timeoutMs: 15_000,
+            maxOutputBytes: 64 * 1024,
+        }).catch(() => undefined);
+        await this.commands.run("wsl.exe", ["--terminate", "docker-desktop"], {
+            timeoutMs: 15_000,
+            maxOutputBytes: 64 * 1024,
+        }).catch(() => undefined);
+        await this.wait(5_000);
+        const stoppedState = await this.readProcessState();
+        if (stoppedState !== "stopped") {
+            return {
+                started: false,
+                reason: stoppedState === "running"
+                    ? "Docker Desktop processes did not stop before relaunch."
+                    : "Docker Desktop shutdown state could not be verified safely.",
+            };
+        }
+        if (!await this.cleanupOrphanedCompanions()) {
+            return { started: false, reason: "Orphaned Docker Desktop companion processes could not be verified and cleaned safely." };
+        }
+        await this.wait(1_000);
+        return await this.startDesktop(desktopExecutable);
+    }
+    async readProcessState() {
+        const script = [
+            "$ErrorActionPreference = 'Stop'",
+            "$processes = @(Get-Process -Name 'Docker Desktop','com.docker.backend' -ErrorAction SilentlyContinue)",
+            "if ($processes.Count -gt 0) { Write-Output 'running' } else { Write-Output 'stopped' }",
+        ].join("; ");
+        const result = await this.commands.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { timeoutMs: 5_000, maxOutputBytes: 16 * 1024 }).catch(() => null);
+        if (!result || result.exitCode !== 0)
+            return "unknown";
+        const state = result.stdout.trim().toLowerCase();
+        return state === "running" || state === "stopped" ? state : "unknown";
+    }
+    async cleanupOrphanedCompanions() {
+        const dockerRoot = path.join(this.programFiles, "Docker").replaceAll("'", "''");
+        const script = [
+            "$ErrorActionPreference = 'Stop'",
+            `$dockerRoot = [System.IO.Path]::GetFullPath('${dockerRoot}').TrimEnd('\\') + '\\'`,
+            "$names = @('com.docker.build.exe','docker-sandbox.exe','docker-agent.exe','local-sandboxesd.exe','docker-sandboxd.exe')",
+            "$candidates = @(Get-CimInstance Win32_Process | Where-Object { $_.Name -in $names -and $_.ExecutablePath -and [System.IO.Path]::GetFullPath($_.ExecutablePath).StartsWith($dockerRoot, [System.StringComparison]::OrdinalIgnoreCase) })",
+            "foreach ($candidate in $candidates) { $parent = Get-CimInstance Win32_Process -Filter ('ProcessId=' + $candidate.ParentProcessId) -ErrorAction SilentlyContinue; $parentIsDockerBackend = $null -ne $parent -and $parent.Name -eq 'com.docker.backend.exe' -and $parent.ExecutablePath -and [System.IO.Path]::GetFullPath($parent.ExecutablePath).StartsWith($dockerRoot, [System.StringComparison]::OrdinalIgnoreCase); if (-not $parentIsDockerBackend) { Stop-Process -Id $candidate.ProcessId -Force -ErrorAction Stop } }",
+        ].join("; ");
+        const result = await this.commands.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { timeoutMs: 10_000, maxOutputBytes: 32 * 1024 }).catch(() => null);
+        return result?.exitCode === 0;
+    }
+    async startDesktop(desktopExecutable) {
+        const quotedDesktop = desktopExecutable.replaceAll("'", "''");
+        let lastReason = "Docker Desktop failed to start.";
+        for (let attempt = 1; attempt <= 3; attempt += 1) {
+            const startScript = [
+                "$ErrorActionPreference = 'Stop'",
+                `$desktop = Start-Process -FilePath '${quotedDesktop}' -WindowStyle Hidden -PassThru`,
+                "Start-Sleep -Seconds 3",
+                "if ($desktop.HasExited) { Write-Error ('Docker Desktop exited during startup with code ' + $desktop.ExitCode); exit 1 }",
+            ].join("; ");
+            const start = await this.commands.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", startScript], { timeoutMs: 15_000, maxOutputBytes: 64 * 1024 }).catch((error) => ({
+                exitCode: 1,
+                stdout: "",
+                stderr: error instanceof Error ? error.message : String(error),
+            }));
+            if (start.exitCode === 0)
+                return { started: true };
+            lastReason = start.stderr || start.stdout || lastReason;
+            if (attempt < 3)
+                await this.wait(5_000);
+        }
+        return { started: false, reason: singleLine(lastReason) };
+    }
+}
+function unavailable(context, code, reason) {
+    return {
+        available: false,
+        sampledAt: new Date().toISOString(),
+        runtimeVersion: null,
+        operatingSystem: null,
+        context,
+        unavailableCode: code,
+        unavailableReason: singleLine(reason),
+    };
+}
+function clean(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function singleLine(value) {
+    return value.replace(/[\r\n\t]+/gu, " ").trim().slice(0, 1000);
+}
+function positiveInteger(value, fallback) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.floor(value);
+}

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-diagnostics.d.ts

@@ -0,0 +1,4 @@
+import type { PinnedDirectoryIdentity } from "./pinned-directory-process.js";
+/** Runner-local evidence, never web-served; browser-profile, cache and temporary directories are excluded. */
+export declare function retainHostDiagnostics(stateRoot: string, attemptRoot: string, attemptId: string, expectedAttemptRootIdentity: PinnedDirectoryIdentity | null): Promise<string>;
+export declare function assertHostAttemptRootIdentity(attemptRoot: string, expected: PinnedDirectoryIdentity): Promise<void>;

package/dist/runtime/host-diagnostics.js

@@ -0,0 +1,95 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { readCanonicalSourceFile } from "./canonical-source-file.js";
+import { assertCanonicalDirectory, createCanonicalDirectory } from "./attempt-private-directory.js";
+import { runAttemptArchiveOperation } from "./attempt-path-operation.js";
+import { readPinnedSourceDirectory } from "./pinned-source-directory.js";
+const maximumEvidenceBytes = 200 * 1024 * 1024;
+/** Runner-local evidence, never web-served; browser-profile, cache and temporary directories are excluded. */
+export async function retainHostDiagnostics(stateRoot, attemptRoot, attemptId, expectedAttemptRootIdentity) {
+    const identity = attemptId.replaceAll("-", "").toLowerCase();
+    if (!/^[0-9a-f]{32}$/u.test(identity)
+        || path.resolve(attemptRoot) !== path.resolve(stateRoot, "host-attempts", identity)) {
+        throw new Error("host_diagnostics_invalid_owner: refusing an unowned attempt path.");
+    }
+    const attemptStat = await fs.lstat(attemptRoot).catch(error => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (attemptStat) {
+        if (!expectedAttemptRootIdentity) {
+            throw new Error("host_diagnostics_invalid_owner: original attempt-root identity is unavailable.");
+        }
+        await assertHostAttemptRootIdentity(attemptRoot, expectedAttemptRootIdentity);
+    }
+    const target = path.join(stateRoot, "diagnostics", "host", identity);
+    const manifestPath = path.join(target, "manifest.json");
+    await assertCanonicalDirectory(stateRoot);
+    await createCanonicalDirectory(target);
+    const priorManifest = await fs.lstat(manifestPath).catch(error => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (priorManifest && (!priorManifest.isFile() || priorManifest.isSymbolicLink()))
+        throw new Error("host_diagnostics_unsafe_path: manifest is not an ordinary file.");
+    if (priorManifest && !attemptStat) {
+        const saved = JSON.parse((await readCanonicalSourceFile(manifestPath, maximumEvidenceBytes)).toString("utf8"));
+        if (saved.attemptId !== attemptId)
+            throw new Error("host_diagnostics_invalid_owner: archive identity mismatch.");
+        return target;
+    }
+    const files = [];
+    let bytes = 0;
+    let entries = 0;
+    const walk = async (relative, entry) => {
+        if (++entries > 10000)
+            throw new Error("host_diagnostics_budget: evidence inventory exceeds retention budget.");
+        const source = path.join(attemptRoot, relative);
+        if (entry.kind === "symlink")
+            throw new Error("host_diagnostics_unsafe_path: evidence contains a symlink.");
+        if (entry.kind === "directory") {
+            await createCanonicalDirectory(path.join(target, relative));
+            for (const child of await readPinnedSourceDirectory(source, entry.identity)) {
+                await walk(path.join(relative, child.name), child);
+            }
+            return;
+        }
+        if (entry.kind !== "file")
+            throw new Error("host_diagnostics_unsafe_path: evidence is not an ordinary file.");
+        if (files.length >= 5000 || entry.size > BigInt(maximumEvidenceBytes - bytes))
+            throw new Error("host_diagnostics_budget: evidence exceeds retention budget; original attempt retained for recovery.");
+        const destination = path.join(target, relative);
+        const contents = await readCanonicalSourceFile(source, maximumEvidenceBytes - bytes, entry.identity);
+        bytes += contents.length;
+        const sha256 = createHash("sha256").update(contents).digest("hex");
+        await writeArchiveFile(destination, contents, sha256);
+        files.push({ path: relative, bytes: contents.length, sha256 });
+    };
+    if (attemptStat) {
+        await assertHostAttemptRootIdentity(attemptRoot, expectedAttemptRootIdentity);
+        const rootEntries = await readPinnedSourceDirectory(attemptRoot, expectedAttemptRootIdentity);
+        for (const directory of ["logs", "test-output"]) {
+            const entry = rootEntries.find(candidate => candidate.name === directory);
+            if (entry)
+                await walk(directory, entry);
+        }
+    }
+    // Only owned relative evidence paths and hashes go into the public-facing manifest.
+    const manifest = Buffer.from(JSON.stringify({ schemaVersion: 1, attemptId, retainedAt: new Date().toISOString(), files }, null, 2));
+    await writeArchiveFile(manifestPath, manifest, createHash("sha256").update(manifest).digest("hex"));
+    return target;
+}
+export async function assertHostAttemptRootIdentity(attemptRoot, expected) {
+    const current = await assertCanonicalDirectory(attemptRoot);
+    if (!current || current.dev !== expected.dev || current.ino !== expected.ino) {
+        throw new Error("host_diagnostics_invalid_owner: attempt-root identity changed.");
+    }
+}
+async function writeArchiveFile(target, bytes, sha256) {
+    const parent = path.dirname(path.resolve(target));
+    const identity = (await assertCanonicalDirectory(parent));
+    await runAttemptArchiveOperation(parent, identity, { name: path.basename(target), bytes, sha256 });
+}

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

@@ -0,0 +1,46 @@
+import type { AttemptProcessChildHandle } from "./attempt-process-supervisor.js";
+import type { HostPortLeaseOwner, HostPortReservation } from "./host-port-broker.js";
+import type { HostListenerOwnership } from "./node-host-runtime-adapter.js";
+export interface HostInspectionCommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly errorCode?: string;
+}
+export interface HostInspectionCommandRunner {
+    run(command: string, args: readonly string[]): Promise<HostInspectionCommandResult>;
+}
+/** Proves that a loopback listener belongs to one exact supervised child. */
+export declare class HostListenerInspector {
+    private readonly commands;
+    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[]>;
+    /** Snapshots loopback TCP ports that predate a supervised child launch. */
+    inspectLoopbackListeners(): 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>;
+}
+export declare function parseWindowsListenerPids(output: string, port: number): readonly number[];
+export declare function parseLsofPids(output: string): readonly number[];
+export declare function parseSsPids(output: string, port: number): readonly number[];
+export declare function parseProcessGroups(output: string): ReadonlyMap<number, number>;