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

package/dist/runtime/pinned-source-directory.d.ts

@@ -0,0 +1,17 @@
+import { runPinnedDirectoryProcess, type PinnedDirectoryIdentity } from "./pinned-directory-process.js";
+export interface PinnedSourceEntry {
+    name: string;
+    kind: "directory" | "file" | "symlink" | "other";
+    identity: PinnedDirectoryIdentity;
+    size: bigint;
+}
+type PinnedDirectoryProcessRunner = typeof runPinnedDirectoryProcess;
+export interface PinnedSourceDirectoryReadOptions {
+    /** Production retries are Windows-only; tests may override this explicitly. */
+    readonly maxAttempts?: number;
+    readonly processRunner?: PinnedDirectoryProcessRunner;
+}
+/** Enumerate from a cwd whose inode is checked by the worker, not by reopening a validated pathname. */
+export declare function readPinnedSourceDirectory(directory: string, identity: PinnedDirectoryIdentity, timeoutMs?: number, terminationConfirmationMs?: number, options?: PinnedSourceDirectoryReadOptions): Promise<PinnedSourceEntry[]>;
+export declare function decodePinnedSourceDirectoryInventory(output: string): PinnedSourceEntry[];
+export {};

package/dist/runtime/pinned-source-directory.js

@@ -0,0 +1,94 @@
+import { PinnedDirectoryProcessError, runPinnedDirectoryProcess, } from "./pinned-directory-process.js";
+/** Enumerate from a cwd whose inode is checked by the worker, not by reopening a validated pathname. */
+export async function readPinnedSourceDirectory(directory, identity, timeoutMs = 30_000, terminationConfirmationMs = 2_000, options = {}) {
+    const configuredAttempts = options.maxAttempts ?? (process.platform === "win32" ? 2 : 1);
+    const maxAttempts = Math.max(1, Math.min(3, Math.floor(configuredAttempts), Math.floor(timeoutMs)));
+    const attemptBudgetMs = Math.max(1, Math.floor(timeoutMs / maxAttempts));
+    const attemptTerminationConfirmationMs = Math.min(Math.max(0, terminationConfirmationMs), Math.max(0, attemptBudgetMs - 1));
+    const attemptTimeoutMs = Math.max(1, attemptBudgetMs - attemptTerminationConfirmationMs);
+    const processRunner = options.processRunner ?? runPinnedDirectoryProcess;
+    let lastError;
+    let attemptsStarted = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        attemptsStarted = attempt;
+        try {
+            const output = await processRunner(directory, identity, worker, { kind: "source_inventory" }, undefined, 16 * 1024 * 1024, attemptTimeoutMs, attemptTerminationConfirmationMs);
+            return decodePinnedSourceDirectoryInventory(output);
+        }
+        catch (error) {
+            lastError = error;
+            if (!(error instanceof PinnedDirectoryProcessError)
+                || error.failureKind !== "timeout"
+                || !error.terminationConfirmed
+                || attempt === maxAttempts) {
+                break;
+            }
+        }
+    }
+    {
+        const error = lastError;
+        const detail = error instanceof Error ? error.message : String(error);
+        if (detail.includes("evidence inventory exceeds retention budget")) {
+            throw new Error("host_diagnostics_budget: evidence inventory exceeds retention budget.", { cause: error });
+        }
+        if (detail.includes("source directory identity changed") || detail.includes("invalid operation")) {
+            throw new Error(`host_diagnostics_source_invalid: pinned directory enumeration failed: ${detail}`, { cause: error });
+        }
+        const reason = error instanceof PinnedDirectoryProcessError && error.failureKind === "timeout"
+            ? `pinned directory enumeration timed out after ${attemptsStarted} attempt${attemptsStarted === 1 ? "" : "s"} within ${timeoutMs} ms recovery budget`
+            : "pinned directory enumeration was temporarily unavailable";
+        throw new Error(`host_diagnostics_temporary_unavailable: ${reason}: ${detail}`, { cause: error });
+    }
+}
+export function decodePinnedSourceDirectoryInventory(output) {
+    const decoded = JSON.parse(output);
+    if (!Array.isArray(decoded) || decoded.length > 10000) {
+        throw new Error("host_diagnostics_budget: evidence inventory exceeds retention budget.");
+    }
+    return decoded.map(entry => {
+        if (!isSingleComponent(entry.name) || !["directory", "file", "symlink", "other"].includes(entry.kind)
+            || !isSignedFileIdentity(entry.dev) || !isSignedFileIdentity(entry.ino) || !/^\d+$/u.test(entry.size)) {
+            throw new Error("host_diagnostics_source_invalid: invalid pinned directory inventory.");
+        }
+        return {
+            name: entry.name, kind: entry.kind, identity: { dev: BigInt(entry.dev), ino: BigInt(entry.ino) },
+            size: BigInt(entry.size),
+        };
+    }).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+}
+function isSignedFileIdentity(value) {
+    // Node exposes Windows FILE_ID_128 low words through signed bigint stat fields.
+    // A valid NTFS identity can therefore be negative when its high bit is set.
+    return /^-?\d{1,64}$/u.test(value);
+}
+function isSingleComponent(value) {
+    return Boolean(value) && value !== "." && value !== ".."
+        && !["/", ":", "\\", "\0"].some(character => value.includes(character));
+}
+const worker = String.raw `
+const fs = require('node:fs');
+const input = fs.readFileSync(0);
+const boundary = input.indexOf(10);
+const job = JSON.parse(input.subarray(0, boundary).toString('utf8'));
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const expected = { dev: BigInt(job.dev), ino: BigInt(job.ino) };
+const verify = () => {
+  const current = fs.statSync('.', { bigint: true });
+  if (!current.isDirectory() || !same(current, expected) || !samePath(fs.realpathSync('.'), job.parent))
+    throw new Error('source directory identity changed');
+};
+try {
+  if (job.kind !== 'source_inventory') throw new Error('invalid operation');
+  verify();
+  const entries = fs.readdirSync('.');
+  if (entries.length > 10000) throw new Error('evidence inventory exceeds retention budget');
+  const inventory = entries.map(name => {
+    const stat = fs.lstatSync(name, { bigint: true });
+    const kind = stat.isSymbolicLink() ? 'symlink' : stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'other';
+    return { name, kind, dev: stat.dev.toString(), ino: stat.ino.toString(), size: stat.size.toString() };
+  });
+  verify();
+  process.stdout.write(JSON.stringify(inventory));
+} catch (error) { process.stderr.write(error.message); process.exitCode = 1; }
+`;

package/dist/runtime/playwright-host-runtime-adapter.d.ts

@@ -5,6 +5,7 @@ export interface PlaywrightHostRuntimeContext {
     readonly testOutputDirectory: string;
     readonly browserProfileDirectory: string;
     readonly baseUrl: string;
+    readonly ownershipToken: string;
 }
 export interface PreparedPlaywrightHostRuntime {
     readonly configPath: string;

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

@@ -2,6 +2,9 @@ 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.
@@ -17,10 +20,19 @@ export class PlaywrightHostRuntimeAdapter {
             fs.realpath(sourceConfig),
         ]);
         assertContained(realWorktree, realSource, "project Playwright config");
-        const sourceStat = await fs.stat(realSource);
-        if (!sourceStat.isFile() || sourceStat.size < 1 || sourceStat.size > maximumConfigBytes) {
+        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");
@@ -29,22 +41,28 @@ export class PlaywrightHostRuntimeAdapter {
             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 fs.writeFile(overlayPath, renderOverlay({
+        await writeAttemptOverlay(overlayPath, renderOverlay({
             projectConfigUrl: pathToFileURL(realSource).href,
             projectConfigDirectory: path.dirname(realSource),
             testOutputDirectory,
             baseUrl,
             workers: config.workers,
-        }), { encoding: "utf8", mode: 0o600 });
+            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,
@@ -58,6 +76,34 @@ export class PlaywrightHostRuntimeAdapter {
         };
     }
 }
+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"))) {
@@ -91,7 +137,7 @@ async function resolvePlaywrightBrowserCache(attemptRoot) {
         }
     }
     const attemptCache = path.join(attemptRoot, "cache", "ms-playwright");
-    await fs.mkdir(attemptCache, { recursive: true });
+    await createPrivateCanonicalDirectory(attemptCache);
     return { path: attemptCache, ready: false };
 }
 async function hasChromiumExecutable(cachePath) {
@@ -126,6 +172,7 @@ async function hasChromiumExecutable(cachePath) {
 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)};`,
@@ -183,6 +230,7 @@ function renderOverlay(values) {
     ].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.`);

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;
+}