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

package/dist/runtime/playwright-host-runtime-adapter.js

@@ -0,0 +1,268 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { assertCanonicalDirectory, createPrivateCanonicalDirectory } from "./attempt-private-directory.js";
+import { readCanonicalSourceFile } from "./canonical-source-file.js";
+import { runAttemptPathOperation } from "./attempt-path-operation.js";
+const maximumConfigBytes = 1024 * 1024;
+/**
+ * Prepares a finite Playwright test boundary for a managed-host attempt.
+ * The generated overlay points tests at Forge's verified listener, disables
+ * Playwright-managed web servers, and keeps writable artifacts attempt-local.
+ */
+export class PlaywrightHostRuntimeAdapter {
+    async prepare(config, context) {
+        const worktreePath = path.resolve(context.worktreePath);
+        const sourceConfig = path.resolve(worktreePath, config.config);
+        const [realWorktree, realSource] = await Promise.all([
+            fs.realpath(worktreePath),
+            fs.realpath(sourceConfig),
+        ]);
+        assertContained(realWorktree, realSource, "project Playwright config");
+        const sourceBytes = await readCanonicalSourceFile(sourceConfig, maximumConfigBytes);
+        if (sourceBytes.length < 1) {
+            throw new Error(`playwright_runtime_adapter_invalid: project config must be a regular 1-${maximumConfigBytes} byte file.`);
+        }
+        const sourceConfigText = sourceBytes.toString("utf8");
+        const projectNames = [...sourceConfigText.matchAll(/\bname\s*:\s*["']([^"']+)["']/gu)]
+            .map(match => match[1])
+            .filter((name, index, names) => names.indexOf(name) === index);
+        await ensureAttemptWritableDirectories([
+            context.temporaryDirectory,
+            context.testOutputDirectory,
+            context.browserProfileDirectory,
+        ], realWorktree);
+        const temporaryDirectory = await realContainedDirectory(context.temporaryDirectory, realWorktree, "temporary directory");
+        const testOutputDirectory = await realContainedDirectory(context.testOutputDirectory, realWorktree, "test output directory");
+        const browserProfileDirectory = await realContainedDirectory(context.browserProfileDirectory, realWorktree, "browser profile directory");
+        const attemptRoot = path.dirname(temporaryDirectory);
+        if (path.dirname(testOutputDirectory) !== attemptRoot || path.dirname(browserProfileDirectory) !== attemptRoot) {
+            throw new Error("playwright_runtime_adapter_invalid: writable directories must belong to the same attempt root.");
+        }
+        const baseUrl = loopbackHttpUrl(context.baseUrl);
+        if (!/^[0-9a-f]{32}$/u.test(context.ownershipToken)) {
+            throw new Error("playwright_runtime_adapter_invalid: ownership token must be a normalized dispatch attempt UUID.");
+        }
+        const overlayPath = path.join(temporaryDirectory, "forge.playwright.config.mjs");
+        const browserCache = await resolvePlaywrightBrowserCache(attemptRoot);
+        const browserInstallCommand = await resolvePlaywrightBrowserInstallCommand(context.worktreePath, path.dirname(realSource));
+        await writeAttemptOverlay(overlayPath, renderOverlay({
+            projectConfigUrl: pathToFileURL(realSource).href,
+            projectConfigDirectory: path.dirname(realSource),
+            testOutputDirectory,
+            baseUrl,
+            workers: config.workers,
+            projectNames,
+        }));
+        return {
+            configPath: overlayPath,
+            environment: {
+                FORGE_PLAYWRIGHT_CONFIG: overlayPath,
+                FORGE_PLAYWRIGHT_BASE_URL: baseUrl,
+                FORGE_E2E_WEB_URL: baseUrl,
+                FORGE_E2E_OWNERSHIP_MODE: "attempt",
+                FORGE_E2E_OWNERSHIP_TOKEN: context.ownershipToken,
+                FORGE_PLAYWRIGHT_BROWSER_READY: browserCache.ready ? "true" : "false",
+                FORGE_PLAYWRIGHT_BROWSER_INSTALL_COMMAND: browserInstallCommand,
+                PLAYWRIGHT_BROWSERS_PATH: browserCache.path,
+                PLAYWRIGHT_HTML_OUTPUT_DIR: path.join(testOutputDirectory, "html-report"),
+                PLAYWRIGHT_BLOB_OUTPUT_DIR: path.join(testOutputDirectory, "blob-report"),
+                PLAYWRIGHT_JUNIT_OUTPUT_NAME: path.join(testOutputDirectory, "results.xml"),
+                PLAYWRIGHT_JSON_OUTPUT_NAME: path.join(testOutputDirectory, "results.json"),
+                FORGE_BROWSER_PROFILE_DIR: browserProfileDirectory,
+                FORGE_TEST_OUTPUT_DIR: testOutputDirectory,
+            },
+        };
+    }
+}
+async function ensureAttemptWritableDirectories(targets, realWorktree) {
+    const resolvedTargets = targets.map(target => path.resolve(target));
+    const attemptRoots = new Set(resolvedTargets.map(target => path.dirname(target)));
+    if (attemptRoots.size !== 1) {
+        throw new Error("playwright_runtime_adapter_invalid: writable directories must belong to the same attempt root.");
+    }
+    const attemptRoot = [...attemptRoots][0];
+    if (!attemptRoot || attemptRoot === realWorktree || isContained(realWorktree, attemptRoot)) {
+        throw new Error("playwright_runtime_adapter_invalid: writable directories must be attempt-private and outside the worktree.");
+    }
+    await assertCanonicalDirectory(attemptRoot, true);
+    for (const target of resolvedTargets) {
+        if (target === realWorktree || isContained(realWorktree, target)) {
+            throw new Error("playwright_runtime_adapter_invalid: writable directories must be attempt-private and outside the worktree.");
+        }
+        await assertCanonicalDirectory(target, true);
+    }
+    await createPrivateCanonicalDirectory(attemptRoot);
+    for (const target of resolvedTargets)
+        await createPrivateCanonicalDirectory(target);
+}
+async function writeAttemptOverlay(target, content) {
+    const parent = path.dirname(target);
+    const identity = await assertCanonicalDirectory(parent);
+    if (!identity)
+        throw new Error("playwright_runtime_adapter_invalid: overlay parent is missing.");
+    await runAttemptPathOperation(parent, identity, { kind: "overlay", name: path.basename(target), content });
+}
+async function resolvePlaywrightBrowserInstallCommand(worktreePath, configDirectory) {
+    const relativeDirectory = path.relative(worktreePath, configDirectory).replaceAll(path.sep, "/") || ".";
+    if (await isFile(path.join(configDirectory, "pnpm-lock.yaml"))) {
+        return `pnpm --dir ${quoteCommandArgument(relativeDirectory)} exec playwright install chromium`;
+    }
+    if (await isFile(path.join(configDirectory, "yarn.lock"))) {
+        return `yarn --cwd ${quoteCommandArgument(relativeDirectory)} playwright install chromium`;
+    }
+    return `npm --prefix ${quoteCommandArgument(relativeDirectory)} exec playwright install chromium`;
+}
+async function isFile(candidate) {
+    try {
+        return (await fs.stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function quoteCommandArgument(value) {
+    return /[\s"']/u.test(value) ? JSON.stringify(value) : value;
+}
+async function resolvePlaywrightBrowserCache(attemptRoot) {
+    const candidates = [
+        process.env.PLAYWRIGHT_BROWSERS_PATH,
+        process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, "ms-playwright") : null,
+        path.join(os.homedir(), ".cache", "ms-playwright"),
+    ].filter((candidate) => Boolean(candidate?.trim()));
+    for (const candidate of [...new Set(candidates.map(candidate => path.resolve(candidate)))]) {
+        if (await hasChromiumExecutable(candidate)) {
+            return { path: candidate, ready: true };
+        }
+    }
+    const attemptCache = path.join(attemptRoot, "cache", "ms-playwright");
+    await createPrivateCanonicalDirectory(attemptCache);
+    return { path: attemptCache, ready: false };
+}
+async function hasChromiumExecutable(cachePath) {
+    let entries;
+    try {
+        entries = await fs.readdir(cachePath, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    const executableSuffixes = process.platform === "win32"
+        ? [path.join("chrome-win64", "chrome.exe"), path.join("chrome-win", "chrome.exe")]
+        : process.platform === "darwin"
+            ? [path.join("chrome-mac", "Chromium.app", "Contents", "MacOS", "Chromium")]
+            : [path.join("chrome-linux", "chrome"), path.join("chrome-linux64", "chrome")];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith("chromium-"))
+            continue;
+        for (const suffix of executableSuffixes) {
+            try {
+                const stat = await fs.stat(path.join(cachePath, entry.name, suffix));
+                if (stat.isFile())
+                    return true;
+            }
+            catch {
+                // Continue through known Playwright layouts.
+            }
+        }
+    }
+    return false;
+}
+function renderOverlay(values) {
+    return [
+        "// Generated by forge-bridge for one fenced host attempt.",
+        `// forge-playwright-projects: ${JSON.stringify(values.projectNames)}`,
+        "import path from \"node:path\";",
+        `import projectConfig from ${JSON.stringify(values.projectConfigUrl)};`,
+        `const projectConfigDirectory = ${JSON.stringify(values.projectConfigDirectory)};`,
+        "const resolveConfigPath = value => typeof value === \"string\" && !path.isAbsolute(value)",
+        "  ? path.resolve(projectConfigDirectory, value)",
+        "  : value;",
+        "const resolveModulePath = value => typeof value === \"string\" && value.startsWith(\".\")",
+        "  ? path.resolve(projectConfigDirectory, value)",
+        "  : value;",
+        "const resolveUse = use => ({",
+        "  ...(use ?? {}),",
+        "  storageState: typeof use?.storageState === \"string\" ? resolveConfigPath(use.storageState) : use?.storageState,",
+        "  baseURL: " + JSON.stringify(values.baseUrl) + ",",
+        "});",
+        "const forgeUse = resolveUse(projectConfig.use);",
+        "const forgeProjects = Array.isArray(projectConfig.projects)",
+        "  ? projectConfig.projects.map(project => ({",
+        "      ...project,",
+        "      testDir: resolveConfigPath(project.testDir),",
+        "      snapshotDir: resolveConfigPath(project.snapshotDir),",
+        "      use: resolveUse(project.use),",
+        "    }))",
+        "  : projectConfig.projects;",
+        "const forgeReporter = Array.isArray(projectConfig.reporter)",
+        "  ? projectConfig.reporter.map(reporter => Array.isArray(reporter)",
+        "      ? [resolveModulePath(reporter[0]), ...reporter.slice(1)]",
+        "      : resolveModulePath(reporter))",
+        "  : resolveModulePath(projectConfig.reporter);",
+        "const forgeProviderOnlySpecs = (() => {",
+        "  try {",
+        "    const parsed = JSON.parse(process.env.FORGE_CI_REPAIR_PROVIDER_ONLY_SPECS ?? '[]');",
+        "    return Array.isArray(parsed) ? parsed.filter(value => typeof value === 'string' && value.length > 0) : [];",
+        "  } catch {",
+        "    return [];",
+        "  }",
+        "})();",
+        "const forgeTestIgnore = forgeProviderOnlySpecs.length === 0",
+        "  ? projectConfig.testIgnore",
+        "  : [...(Array.isArray(projectConfig.testIgnore) ? projectConfig.testIgnore : projectConfig.testIgnore ? [projectConfig.testIgnore] : []), ...forgeProviderOnlySpecs];",
+        "export default {",
+        "  ...projectConfig,",
+        "  testDir: resolveConfigPath(projectConfig.testDir),",
+        "  snapshotDir: resolveConfigPath(projectConfig.snapshotDir),",
+        "  globalSetup: resolveModulePath(projectConfig.globalSetup),",
+        "  globalTeardown: resolveModulePath(projectConfig.globalTeardown),",
+        "  reporter: forgeReporter,",
+        "  testIgnore: forgeTestIgnore,",
+        `  outputDir: ${JSON.stringify(values.testOutputDirectory)},`,
+        `  workers: ${values.workers},`,
+        "  webServer: undefined,",
+        "  use: forgeUse,",
+        "  projects: forgeProjects,",
+        "};",
+        "",
+    ].join("\n");
+}
+async function realContainedDirectory(target, realWorktree, label) {
+    await assertCanonicalDirectory(target);
+    const realTarget = await fs.realpath(path.resolve(target));
+    if (realTarget === realWorktree || isContained(realWorktree, realTarget)) {
+        throw new Error(`playwright_runtime_adapter_invalid: ${label} must be attempt-private and outside the worktree.`);
+    }
+    const stat = await fs.stat(realTarget);
+    if (!stat.isDirectory())
+        throw new Error(`playwright_runtime_adapter_invalid: ${label} must be a directory.`);
+    return realTarget;
+}
+function assertContained(parent, child, label) {
+    if (!isContained(parent, child)) {
+        throw new Error(`playwright_runtime_adapter_invalid: ${label} must stay inside the prepared worktree.`);
+    }
+}
+function isContained(parent, child) {
+    const relative = path.relative(parent, child);
+    return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function loopbackHttpUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("playwright_runtime_adapter_invalid: base URL must be an HTTP loopback URL.");
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:")
+        || url.hostname !== "127.0.0.1"
+        || !url.port
+        || url.username
+        || url.password) {
+        throw new Error("playwright_runtime_adapter_invalid: base URL must be an HTTP loopback URL.");
+    }
+    return url.href.replace(/\/$/u, "");
+}

package/dist/runtime/prepared-runtime-identity.d.ts

@@ -0,0 +1,6 @@
+import { type HostParallelProofIdentity } from "./host-runtime-promotion.js";
+export interface PreparedRuntimeIdentityDiagnostics {
+    readonly entries: Map<string, string>;
+}
+/** Bind evidence to the prepared source, including unstaged replacements, not just HEAD. */
+export declare function preparedRuntimeIdentity(worktreePath: string, signal?: AbortSignal, diagnostics?: PreparedRuntimeIdentityDiagnostics): Promise<HostParallelProofIdentity>;

package/dist/runtime/prepared-runtime-identity.js

@@ -0,0 +1,218 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GitClient } from "../shared/git/git.js";
+import { hostRuntimeContractPath, loadHostRuntimeContract } from "./host-runtime-contract.js";
+import { hostRuntimeContractFingerprint } from "./host-runtime-promotion.js";
+import { readCanonicalSourceFile } from "./canonical-source-file.js";
+import { assertCanonicalDirectory } from "./attempt-private-directory.js";
+import { generatedOutputRootForPath } from "./generated-output-reset.js";
+import { readPinnedSourceDirectory } from "./pinned-source-directory.js";
+/** Bind evidence to the prepared source, including unstaged replacements, not just HEAD. */
+export async function preparedRuntimeIdentity(worktreePath, signal, diagnostics) {
+    diagnostics?.entries.clear();
+    const root = await fs.realpath(worktreePath);
+    const rootIdentity = (await assertCanonicalDirectory(root));
+    const sourceKey = (target) => process.platform === "win32" ? target.toLowerCase() : target;
+    const expectedEntries = new Map();
+    const directories = new Map();
+    const containedRelative = (target) => {
+        const relative = path.relative(root, path.resolve(target));
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw new Error("host_runtime_source_invalid: source path escapes the worktree.");
+        }
+        return relative.replaceAll("\\", "/");
+    };
+    const directorySnapshot = async (target) => {
+        const resolved = path.resolve(target);
+        containedRelative(resolved);
+        const key = sourceKey(resolved);
+        let captured = directories.get(key);
+        if (!captured) {
+            captured = (async () => {
+                let identity;
+                if (key === sourceKey(root))
+                    identity = rootIdentity;
+                else {
+                    const parent = await expectedEntry(resolved);
+                    if (!parent || parent.kind !== "directory") {
+                        throw new Error("host_runtime_source_changed: discovery directory identity changed.");
+                    }
+                    identity = parent.identity;
+                }
+                const entries = await readPinnedSourceDirectory(resolved, identity);
+                for (const entry of entries)
+                    expectedEntries.set(sourceKey(path.join(resolved, entry.name)), entry);
+                return { path: resolved, identity, entries };
+            })();
+            directories.set(key, captured);
+        }
+        return (await captured).entries.map(entry => ({
+            name: entry.name,
+            isDirectory: entry.kind === "directory",
+            isFile: entry.kind === "file",
+        }));
+    };
+    const expectedEntry = async (target) => {
+        const resolved = path.resolve(target);
+        containedRelative(resolved);
+        if (sourceKey(resolved) === sourceKey(root)) {
+            return { name: path.basename(root), kind: "directory", identity: rootIdentity, size: 0n };
+        }
+        const parentPath = path.dirname(resolved);
+        if (sourceKey(parentPath) !== sourceKey(root)) {
+            const parent = await expectedEntry(parentPath);
+            if (!parent)
+                return undefined;
+            if (parent.kind !== "directory") {
+                throw new Error("host_runtime_source_changed: discovery ancestor is not a directory.");
+            }
+        }
+        await directorySnapshot(parentPath);
+        return expectedEntries.get(sourceKey(resolved));
+    };
+    // Pin the worktree before Git or discovery uses it. Every child directory is
+    // subsequently reached through an identity captured from its pinned parent.
+    await directorySnapshot(root);
+    const git = new GitClient();
+    const head = (await git.run(root, ["rev-parse", "HEAD"])).trim();
+    const inventory = async () => {
+        const included = (name) => name && (!name.startsWith(".forge/") || name === ".forge/forge.runtime.yml");
+        // ls-files --deleted loses a deletion once staged. HEAD-relative tombstones
+        // keep the same prepared source identity before and after git add -u.
+        const deleted = [...new Set((await git.run(root, ["ls-files", "-z", "--deleted"]))
+                .split("\0").concat((await git.run(root, ["diff", "--name-only", "--diff-filter=D", "-z", "HEAD", "--"]))
+                .split("\0")).filter(included))].sort();
+        const tracked = (await git.run(root, ["ls-files", "-z", "--cached"]))
+            .split("\0").filter(included);
+        const untracked = (await git.run(root, ["ls-files", "-z", "--others", "--exclude-standard"]))
+            .split("\0").filter(included);
+        const generatedRoots = [...new Set(untracked
+                .map(generatedOutputRootForPath)
+                .filter((candidate) => candidate !== null))];
+        const comparisonKey = (value) => process.platform === "win32" ? value.toLowerCase() : value;
+        const containedBy = (name, candidate) => {
+            const key = comparisonKey(name);
+            const rootKey = comparisonKey(candidate);
+            return key === rootKey || key.startsWith(`${rootKey}/`);
+        };
+        // resetGeneratedOutputs only quarantines a generated directory when Git
+        // confirms it contains no tracked files. Mirror that boundary here so the
+        // cleanup performed by runtime.start cannot invalidate its own foreground
+        // proof, while tracked or mixed-content directories remain source-bound.
+        const resettableRoots = generatedRoots.filter(candidate => !tracked.some(name => containedBy(name, candidate)));
+        const names = [...new Set(tracked.concat(untracked.filter(name => !resettableRoots.some(candidate => containedBy(name, candidate))), deleted, hostRuntimeContractPath).filter(included))].sort();
+        return { names, deleted };
+    };
+    const source = await inventory();
+    const { names } = source;
+    if (names.length > 100_000)
+        throw new Error("host_runtime_source_invalid: source inventory exceeds the file limit.");
+    const deleted = new Set(source.deleted);
+    const hash = createHash("sha256");
+    const snapshot = new Map();
+    const additional = new Map();
+    let discoveryCapture = Promise.resolve();
+    let bytes = 0;
+    for (const name of names) {
+        signal?.throwIfAborted();
+        const target = path.resolve(root, name);
+        const relative = path.relative(root, target);
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw new Error("host_runtime_source_invalid: source path escapes the worktree.");
+        }
+        hash.update(JSON.stringify(name));
+        try {
+            const expected = await expectedEntry(target);
+            if (!expected || expected.kind !== "file") {
+                throw Object.assign(new Error("host_runtime_source_changed: source inventory no longer names an ordinary file."), { code: "ENOENT" });
+            }
+            const sourceBytes = await readCanonicalSourceFile(target, 256 * 1024 * 1024 - bytes, expected.identity);
+            bytes += sourceBytes.length;
+            const digest = createHash("sha256").update(sourceBytes).digest();
+            hash.update(digest);
+            diagnostics?.entries.set(name, digest.toString("hex"));
+            snapshot.set(sourceKey(target), Promise.resolve(sourceBytes));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || (!deleted.has(name) && name !== hostRuntimeContractPath))
+                throw error;
+            const disposition = deleted.has(name) ? "deleted" : "absent";
+            hash.update(disposition);
+            diagnostics?.entries.set(name, disposition);
+            snapshot.set(sourceKey(target), Promise.resolve(null));
+        }
+    }
+    const contract = await loadHostRuntimeContract(root, target => {
+        const key = sourceKey(path.resolve(target));
+        const captured = snapshot.get(key);
+        if (captured)
+            return captured;
+        // Discovery also consumes ignored lockfiles and launch metadata. Capture
+        // those once, too; omission from Git's inventory must not change discovery.
+        const capture = discoveryCapture.then(async () => {
+            signal?.throwIfAborted();
+            const relative = path.relative(root, target).replaceAll("\\", "/");
+            if (relative.startsWith("..") || path.isAbsolute(relative)) {
+                throw new Error("host_runtime_source_invalid: discovery input escapes the worktree.");
+            }
+            let sourceBytes;
+            try {
+                const expected = await expectedEntry(target);
+                if (!expected)
+                    sourceBytes = null;
+                else if (expected.kind !== "file") {
+                    throw new Error("host_runtime_source_changed: discovery input is not an ordinary file.");
+                }
+                else {
+                    sourceBytes = await readCanonicalSourceFile(target, 256 * 1024 * 1024 - bytes, expected.identity);
+                }
+                if (sourceBytes !== null) {
+                    bytes += sourceBytes.length;
+                    if (bytes > 256 * 1024 * 1024)
+                        throw new Error("host_runtime_source_invalid: discovery exceeds the byte limit.");
+                }
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                sourceBytes = null;
+            }
+            additional.set(relative, sourceBytes);
+            return sourceBytes;
+        });
+        // Discovery walks in parallel, but reads share one total byte budget.
+        discoveryCapture = capture.then(() => undefined, () => undefined);
+        snapshot.set(key, capture);
+        return capture;
+    }, directorySnapshot);
+    for (const [name, sourceBytes] of [...additional].sort(([left], [right]) => left.localeCompare(right))) {
+        hash.update(JSON.stringify(["runtime-discovery", name]));
+        const digest = sourceBytes === null
+            ? null
+            : createHash("sha256").update(sourceBytes).digest();
+        hash.update(digest ?? "absent");
+        diagnostics?.entries.set(`runtime-discovery:${name}`, digest?.toString("hex") ?? "absent");
+    }
+    if (head !== (await git.run(root, ["rev-parse", "HEAD"])).trim()
+        || JSON.stringify(source) !== JSON.stringify(await inventory())) {
+        throw new Error("host_runtime_source_changed: prepared source changed during verification.");
+    }
+    for (const captured of await Promise.all([...directories.values()])) {
+        const current = await readPinnedSourceDirectory(captured.path, captured.identity);
+        if (directoryInventory(current) !== directoryInventory(captured.entries)) {
+            throw new Error("host_runtime_source_changed: runtime discovery inventory changed during verification.");
+        }
+    }
+    return {
+        inputCommitSha: head,
+        runtimeContractFingerprint: hostRuntimeContractFingerprint(contract),
+        sourceFingerprint: `sha256:${hash.digest("hex")}`,
+    };
+}
+function directoryInventory(entries) {
+    return JSON.stringify(entries.map(entry => ({
+        name: entry.name,
+        kind: entry.kind,
+    })));
+}

package/dist/runtime/prepared-runtime-readiness.d.ts

@@ -0,0 +1,30 @@
+import type { RunOnceDispatchPacket } from "../session/session.types.js";
+import type { HostRuntimeAdmissionCheckpointHandler, HostRuntimeLeaseRuntime } from "./host-runtime-lease.js";
+import { HostParallelPromotionStore, type HostParallelProofIdentity } from "./host-runtime-promotion.js";
+export interface PreparedRuntimePendingSnapshot {
+    readonly repoId: string;
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly probeDispatchAttemptId?: string;
+    readonly probeFencingToken?: string;
+}
+/** Foreground barrier: prepare a wave, verify its exact runtimes, then release agents. */
+export declare class PreparedRuntimeReadiness {
+    private readonly runtime;
+    private readonly store;
+    private readonly releasePreparation;
+    private readonly admissionExpired;
+    private readonly preparations;
+    private readonly draining;
+    constructor(runtime: HostRuntimeLeaseRuntime, store: HostParallelPromotionStore, releasePreparation: (id: string, fence: string) => Promise<unknown>, admissionExpired: () => Error);
+    acquire(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
+    has(id: string): boolean;
+    hasPending(): boolean;
+    pendingSnapshots(): readonly PreparedRuntimePendingSnapshot[];
+    verify(dispatch: RunOnceDispatchPacket, worktree: string, checkpoint?: HostRuntimeAdmissionCheckpointHandler): Promise<HostParallelProofIdentity | undefined>;
+    renew(id: string, fence: string, expiresAt: string): Promise<void>;
+    cancel(id: string, fence: string, reason?: Error): void;
+    private drain;
+    private scheduleDeadline;
+    private check;
+}