@mono-agent/agent-app 0.11.2 → 0.11.4

package/dist/background-runtime.js

@@ -1,17 +1,19 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { chmod, cp, lstat, mkdir, open, readFile, readlink, readdir, realpath, rename, rm, stat, symlink, writeFile, } from "node:fs/promises";
+import { chmod, cp, lstat, mkdir, open, readFile, readlink, readdir, realpath, rename, rm, symlink, writeFile, } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import process from "node:process";
 import { accountHomeDirectory } from "./account-home.js";
 import { isBackgroundOperationalEnvName } from "./background-environment.js";
 import { currentProcessIncarnation, isSameProcessIncarnation as matchesProcessIncarnation, processIncarnationFromJson, } from "./process-incarnation.js";
+import { acquireOwnerPrivateLock } from "./owner-private-lock.js";
 const PACKAGE_NAME = "@mono-agent/agent-app";
 export const MANAGED_BACKGROUND_WORKER_ENV = "MONO_AGENT_MANAGED_WORKER";
 const LOCK_WAIT_TIMEOUT_MS = 30_000;
 const LOCK_STALE_AFTER_MS = 5 * 60_000;
 const LOCK_POLL_INTERVAL_MS = 200;
 const PROVISIONAL_RUNTIME_INSTALLED_AT = "1970-01-01T00:00:00.000Z";
+const MAX_RUNTIME_MARKER_BYTES = 16 * 1024;
 export function defaultManagedBackgroundRuntimeDeps() {
     return {
         now: () => Date.now(),
@@ -173,7 +175,86 @@ export async function ensureManagedBackgroundRuntime(input, deps = defaultManage
         return runtimeResult(layout, identity, input.nodePath);
     }
     finally {
-        await removeSameRuntimeLockDirectory(layout.lockDir, acquired).catch(() => undefined);
+        await acquired.release().catch(() => undefined);
+    }
+}
+/**
+ * Canonically verify the installed package, freshly recomputed execution
+ * closure/filesystem proof, and coherent current manifest behind a provenance
+ * marker. This intentionally does not install, repair, or compare against a
+ * deploy checkout; it only validates the managed snapshot executing the caller.
+ */
+export async function verifyManagedRuntimeClosureForProvenance(input, deps = {}) {
+    try {
+        if (!isExactVersion(input.packageVersion)
+            || !/^[0-9a-f]{64}$/u.test(input.cliSha256)
+            || !/^[0-9a-f]{64}$/u.test(input.sourceClosureSha256)
+            || !/^[0-9a-f]{64}$/u.test(input.closureManifestSha256)
+            || !/^[0-9a-f]{64}$/u.test(input.executionProofSha256)) {
+            return false;
+        }
+        const packageRoot = resolve(input.packageRoot);
+        const installRoot = dirname(dirname(dirname(packageRoot)));
+        if (join(installRoot, "node_modules", "@mono-agent", "agent-app") !== packageRoot)
+            return false;
+        const identity = {
+            packageVersion: input.packageVersion,
+            cliSha256: input.cliSha256,
+            sourceClosureSha256: input.sourceClosureSha256,
+            nodeAbi: input.nodeAbi,
+            platform: input.platform,
+            arch: input.arch,
+        };
+        const appRuntimeRoot = dirname(dirname(dirname(installRoot)));
+        const home = dirname(dirname(dirname(appRuntimeRoot)));
+        const layout = runtimeLayout(home, identity, "provenance", 0);
+        if (layout.installRoot !== installRoot || layout.cliPath !== join(packageRoot, "dist", "cli.js"))
+            return false;
+        if (!(await verifyPrivateRuntimeAncestors(home, layout.versionAbiDir)))
+            return false;
+        const expectedMarker = {
+            schema: "mono-agent.managed-runtime.v4",
+            packageName: PACKAGE_NAME,
+            closureManifestSha256: input.closureManifestSha256,
+            executionProofSha256: input.executionProofSha256,
+            ...identity,
+            installedAt: input.installedAt,
+        };
+        const markerInitial = await verifiedRuntimeMarker(layout, identity);
+        if (markerInitial === undefined || !sameRuntimeMarker(markerInitial, expectedMarker))
+            return false;
+        const additionalPackages = await managedRuntimeAdditionalPackages(layout);
+        if (additionalPackages === undefined)
+            return false;
+        const closureInitial = await matchingRuntimeClosureCapture(layout, identity, markerInitial, additionalPackages);
+        if (closureInitial === undefined)
+            return false;
+        await deps.afterInitialClosureCapture?.();
+        const closureFinal = await matchingRuntimeClosureCapture(layout, identity, markerInitial, additionalPackages, deps.afterFinalRootCapture === undefined
+            ? {}
+            : { afterRootCapture: deps.afterFinalRootCapture });
+        if (closureFinal === undefined
+            || closureFinal.sourceClosureSha256 !== closureInitial.sourceClosureSha256
+            || closureFinal.sourceProofSha256 !== closureInitial.sourceProofSha256
+            || closureFinal.filesystemProofSha256 !== closureInitial.filesystemProofSha256) {
+            return false;
+        }
+        const markerFinal = await readRuntimeMarker(layout.markerPath, identity);
+        if (markerFinal === undefined
+            || !sameRuntimeMarker(markerFinal, markerInitial)
+            || !sameRuntimeMarker(markerFinal, expectedMarker)
+            || !(await verifyClosureManifest(layout, markerFinal.closureManifestSha256, deps.beforeFinalManifestProof === undefined
+                ? {}
+                : { beforeFinalProof: deps.beforeFinalManifestProof }))) {
+            return false;
+        }
+        const markerAfterManifest = await readRuntimeMarker(layout.markerPath, identity);
+        return markerAfterManifest !== undefined
+            && sameRuntimeMarker(markerAfterManifest, markerInitial)
+            && sameRuntimeMarker(markerAfterManifest, expectedMarker);
+    }
+    catch {
+        return false;
     }
 }
 /**
@@ -353,11 +434,12 @@ async function materializeExactExecutionClosure(input) {
         throw new Error("The managed runtime package closure changed while it was staged.");
     }
 }
-async function captureExecutionClosure(packageSource, additionalPackages, filesystemProofRoot) {
+async function captureExecutionClosure(packageSource, additionalPackages, filesystemProofRoot, deps = {}) {
     const nodes = [];
     const bySourceRoot = new Map();
     const proofs = new Map();
     const dependencyProofs = [];
+    const dependencyProofPaths = [];
     const resolutionPathProof = filesystemProofRoot === undefined
         ? undefined
         : await createResolutionPathProof(filesystemProofRoot);
@@ -400,13 +482,20 @@ async function captureExecutionClosure(packageSource, additionalPackages, filesy
                 throw new Error(`Installed dependency ${dependencyName} changed while its execution closure was inspected.`);
             }
             dependencyProofs.push({ ownerId: id, dependencyName, proof: dependencyProofAfter });
+            dependencyProofPaths.push({
+                path: dependency.candidatePath,
+                logicalPath: dependencyName,
+                proof: dependencyProofAfter,
+            });
             node.dependencies.set(dependencyName, dependencyNodeId);
         }
         return id;
     };
     await visit(packageSource);
+    await deps.afterRootCapture?.();
     const additionalRoots = [];
     const additionalProofs = [];
+    const additionalProofPaths = [];
     for (const additional of additionalPackages) {
         const additionalProof = await captureFilesystemPathProof(additional.packageSource, additional.packageName);
         const nodeId = await visit(additional.packageSource);
@@ -423,9 +512,18 @@ async function captureExecutionClosure(packageSource, additionalPackages, filesy
             throw new Error(`Additional managed runtime package ${additional.packageName} changed while its execution closure was inspected.`);
         }
         additionalProofs.push({ packageName: additional.packageName, proof: additionalProofAfter });
+        additionalProofPaths.push({
+            path: additional.packageSource,
+            logicalPath: additional.packageName,
+            proof: additionalProofAfter,
+        });
         additionalRoots.push({ packageName: additional.packageName, nodeId });
     }
     const closure = nodes;
+    await revalidateExecutionClosureProofs(closure, proofs, [
+        ...dependencyProofPaths,
+        ...additionalProofPaths,
+    ]);
     const resolutionPaths = await resolutionPathProof?.finalize() ?? [];
     const stable = {
         schema: "mono-agent.source-execution-closure.v1",
@@ -473,6 +571,30 @@ async function captureExecutionClosure(packageSource, additionalPackages, filesy
         filesystemProofSha256: sha256(Buffer.from(JSON.stringify(filesystemProof), "utf8")),
     };
 }
+/**
+ * Final identity pass for every package entry and link captured above. Per-file
+ * reads are descriptor-stable, but without this pass an early file could be
+ * overwritten while a later large file was still being hashed.
+ */
+async function revalidateExecutionClosureProofs(closure, proofs, links) {
+    for (const node of closure) {
+        for (const expected of requiredMapValue(proofs, node.id, "source package proof")) {
+            const path = expected.path === "."
+                ? node.sourceRoot
+                : join(node.sourceRoot, ...expected.path.split("/"));
+            const current = await captureFilesystemPathProof(path, expected.path);
+            if (!sameSourceProofEntry(expected, current)) {
+                throw new Error(`Managed runtime source package entry ${expected.path} changed during closure capture.`);
+            }
+        }
+    }
+    for (const link of links) {
+        const current = await captureFilesystemPathProof(link.path, link.logicalPath);
+        if (!sameSourceProofEntry(link.proof, current)) {
+            throw new Error(`Managed runtime package link ${link.logicalPath} changed during closure capture.`);
+        }
+    }
+}
 async function canonicalAdditionalPackages(packages) {
     const byName = new Map();
     for (const entry of packages) {
@@ -660,6 +782,7 @@ function sourceProofEntry(path, type, details, target) {
         type,
         dev: details.dev.toString(),
         ino: details.ino.toString(),
+        nlink: details.nlink.toString(),
         mode: details.mode.toString(),
         size: details.size.toString(),
         mtimeNs: details.mtimeNs.toString(),
@@ -672,6 +795,7 @@ function sameSourceIdentity(left, right) {
 }
 function sameSourceStats(left, right) {
     return sameSourceIdentity(left, right)
+        && left.nlink === right.nlink
         && left.mode === right.mode
         && left.size === right.size
         && left.mtimeNs === right.mtimeNs
@@ -960,127 +1084,40 @@ function runtimeLayoutForRoot(layout, root) {
     };
 }
 async function acquireRuntimeLock(layout, identity, additionalPackages, deps) {
-    const deadline = deps.now() + LOCK_WAIT_TIMEOUT_MS;
     const incarnation = await (deps.currentProcessIncarnation ?? currentProcessIncarnation)();
-    const isSameProcess = deps.isSameProcessIncarnation ?? matchesProcessIncarnation;
-    for (;;) {
-        let createdIdentity;
-        try {
-            await mkdir(layout.lockDir, { mode: 0o700 });
-            createdIdentity = runtimeLockIdentity(await assertPrivateRuntimeLockDirectory(layout.lockDir));
-            await writePrivateJson(join(layout.lockDir, "owner.json"), {
-                pid: process.pid,
-                createdAt: new Date(deps.now()).toISOString(),
-                incarnation,
-                ...identity,
-            });
-            if (!(await sameRuntimeLockDirectory(layout.lockDir, createdIdentity))) {
-                throw new Error(`Managed runtime lock ${layout.lockDir} changed while its owner record was written.`);
-            }
-            return createdIdentity;
-        }
-        catch (error) {
-            if (createdIdentity !== undefined) {
-                await removeSameRuntimeLockDirectory(layout.lockDir, createdIdentity).catch(() => undefined);
-            }
-            if (!isErrno(error, "EEXIST"))
-                throw error;
-        }
-        if (await verifyRuntime(layout, identity, additionalPackages))
-            return undefined;
-        let stale = false;
-        try {
-            const lockDetails = await assertPrivateRuntimeLockDirectory(layout.lockDir);
-            const observedIdentity = runtimeLockIdentity(lockDetails);
-            const owner = await runtimeLockOwner(join(layout.lockDir, "owner.json"));
-            stale = owner === undefined
-                ? deps.now() - (await stat(layout.lockDir)).mtimeMs >= LOCK_STALE_AFTER_MS
-                : !(await isSameProcess(owner.pid, owner.incarnation));
-            if (!(await sameRuntimeLockDirectory(layout.lockDir, observedIdentity)))
-                continue;
-            if (stale) {
-                const staleLock = `${layout.quarantineDir}-stale-lock`;
-                await mkdir(dirname(staleLock), { recursive: true, mode: 0o700 });
-                try {
-                    await rename(layout.lockDir, staleLock);
-                }
-                catch (error) {
-                    if (isErrno(error, "ENOENT") || isErrno(error, "EEXIST"))
-                        continue;
-                    throw error;
-                }
-                const moved = await lstat(staleLock);
-                if (!sameRuntimeLockIdentity(moved, observedIdentity)) {
-                    await rename(staleLock, layout.lockDir).catch(() => undefined);
-                    return undefined;
-                }
-                continue;
-            }
-        }
-        catch (error) {
-            if (isErrno(error, "ENOENT"))
-                continue;
-            throw error;
-        }
-        if (deps.now() >= deadline)
-            return undefined;
-        await deps.sleep(LOCK_POLL_INTERVAL_MS);
-    }
-}
-async function runtimeLockOwner(path) {
-    try {
-        const owner = JSON.parse(await readFile(path, "utf8"));
-        const incarnation = processIncarnationFromJson(owner.incarnation);
-        return typeof owner.pid === "number"
-            && Number.isSafeInteger(owner.pid)
-            && owner.pid > 0
-            && incarnation !== undefined
-            ? { pid: owner.pid, incarnation }
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-async function assertPrivateRuntimeLockDirectory(path) {
-    const details = await lstat(path);
-    if (!details.isDirectory() || details.isSymbolicLink() || !ownedPrivately(details)) {
-        throw new Error(`Managed runtime lock ${path} is not a private current-user directory.`);
-    }
-    return details;
-}
-function runtimeLockIdentity(details) {
-    return { dev: details.dev, ino: details.ino };
-}
-function sameRuntimeLockIdentity(details, identity) {
-    return details.dev === identity.dev && details.ino === identity.ino;
-}
-async function sameRuntimeLockDirectory(path, identity) {
-    try {
-        return sameRuntimeLockIdentity(await assertPrivateRuntimeLockDirectory(path), identity);
-    }
-    catch {
-        return false;
-    }
-}
-async function removeSameRuntimeLockDirectory(path, identity) {
-    if (!(await sameRuntimeLockDirectory(path, identity)))
-        return;
-    const released = `${path}.released-${process.pid}-${randomUUID()}`;
-    try {
-        await rename(path, released);
-    }
-    catch (error) {
-        if (isErrno(error, "ENOENT"))
-            return;
-        throw error;
-    }
-    const moved = await lstat(released);
-    if (!sameRuntimeLockIdentity(moved, identity)) {
-        await rename(released, path).catch(() => undefined);
-        throw new Error(`Managed runtime lock ${path} changed while it was released.`);
-    }
-    await rm(released, { recursive: true, force: true });
+    return acquireOwnerPrivateLock({
+        path: layout.lockDir,
+        label: "Managed runtime lock",
+        schemaTag: "mono-agent.managed-runtime-lock.v1",
+        ownerlessGraceMs: LOCK_STALE_AFTER_MS,
+        waitTimeoutMs: LOCK_WAIT_TIMEOUT_MS,
+        pollIntervalMs: LOCK_POLL_INTERVAL_MS,
+        now: deps.now,
+        processIncarnation: incarnation,
+        ...(deps.isSameProcessIncarnation === undefined
+            ? {}
+            : { isSameProcessIncarnation: deps.isSameProcessIncarnation }),
+        ownerFields: () => ({ ...identity }),
+        validateOwnerFields: (record) => Object.entries(identity)
+            .every(([key, value]) => record[key] === value),
+        parseLegacyOwner: (record) => {
+            const legacyIncarnation = processIncarnationFromJson(record.incarnation);
+            return typeof record.pid === "number"
+                && Number.isSafeInteger(record.pid)
+                && record.pid > 0
+                && legacyIncarnation !== undefined
+                ? { pid: record.pid, incarnation: legacyIncarnation }
+                : undefined;
+        },
+        invalidOwner: "ownerless",
+        isSatisfied: () => verifyRuntime(layout, identity, additionalPackages),
+        sleep: deps.sleep,
+        staleRace: "return",
+        beforeStaleRename: async () => {
+            await mkdir(dirname(layout.quarantineDir), { recursive: true, mode: 0o700 });
+        },
+        stalePath: () => `${layout.quarantineDir}-stale-lock`,
+    });
 }
 async function quarantineInvalidRuntime(layout, identity, additionalPackages, deps) {
     try {
@@ -1114,24 +1151,88 @@ async function promoteStaging(layout, staged, identity, additionalPackages) {
         return false;
     }
 }
+async function managedRuntimeAdditionalPackages(layout) {
+    try {
+        const parsed = JSON.parse(await readFile(layout.packageLockPath, "utf8"));
+        if (!isRecord(parsed) || parsed.lockfileVersion !== 3 || !isRecord(parsed.packages))
+            return undefined;
+        const byName = new Map();
+        for (const [path, value] of Object.entries(parsed.packages)) {
+            if (!isRecord(value))
+                return undefined;
+            if (value.link !== true)
+                continue;
+            const segments = path.split("/");
+            if (segments[0] !== "node_modules")
+                return undefined;
+            const nameSegments = segments.slice(1);
+            const packageName = nameSegments.join("/");
+            packageNameSegments(packageName);
+            if (packageName === PACKAGE_NAME
+                || join("node_modules", ...nameSegments).split(sep).join("/") !== path
+                || typeof value.resolved !== "string") {
+                return undefined;
+            }
+            const packageSource = join(layout.installRoot, "node_modules", ...nameSegments);
+            const linkDetails = await lstat(packageSource);
+            if (!linkDetails.isSymbolicLink())
+                return undefined;
+            const target = await readlink(packageSource);
+            if (isAbsolute(target))
+                return undefined;
+            const canonical = await realpath(packageSource);
+            assertPathInsideRoot(layout.installRoot, canonical, `additional package ${packageName}`);
+            if (portableRelativePath(layout.installRoot, canonical) !== value.resolved)
+                return undefined;
+            const existing = byName.get(packageName);
+            if (existing !== undefined && existing !== packageSource)
+                return undefined;
+            byName.set(packageName, packageSource);
+        }
+        return [...byName]
+            .sort(([left], [right]) => compareCodeUnits(left, right))
+            .map(([packageName, packageSource]) => ({ packageName, packageSource }));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function matchingRuntimeClosureCapture(layout, identity, marker, additionalPackages, deps = {}) {
+    const packageSource = dirname(dirname(layout.cliPath));
+    const runtimeAdditionalPackages = additionalPackages.map(({ packageName }) => ({
+        packageName,
+        packageSource: join(layout.installRoot, "node_modules", ...packageNameSegments(packageName)),
+    }));
+    const closure = await captureExecutionClosure(packageSource, runtimeAdditionalPackages, layout.installRoot, deps);
+    return closure.sourceClosureSha256 === identity.sourceClosureSha256
+        && closure.filesystemProofSha256 === marker.executionProofSha256
+        ? closure
+        : undefined;
+}
 async function verifyRuntime(layout, identity, additionalPackages) {
     const marker = await verifiedRuntimeMarker(layout, identity);
     if (marker === undefined)
         return false;
     try {
-        const packageSource = dirname(dirname(layout.cliPath));
-        const runtimeAdditionalPackages = additionalPackages.map(({ packageName }) => ({
-            packageName,
-            packageSource: join(layout.installRoot, "node_modules", ...packageNameSegments(packageName)),
-        }));
-        const closure = await captureExecutionClosure(packageSource, runtimeAdditionalPackages, layout.installRoot);
-        return closure.sourceClosureSha256 === identity.sourceClosureSha256
-            && closure.filesystemProofSha256 === marker.executionProofSha256;
+        return await matchingRuntimeClosureCapture(layout, identity, marker, additionalPackages) !== undefined;
     }
     catch {
         return false;
     }
 }
+function sameRuntimeMarker(left, right) {
+    return left.schema === right.schema
+        && left.packageName === right.packageName
+        && left.closureManifestSha256 === right.closureManifestSha256
+        && left.executionProofSha256 === right.executionProofSha256
+        && left.packageVersion === right.packageVersion
+        && left.cliSha256 === right.cliSha256
+        && left.sourceClosureSha256 === right.sourceClosureSha256
+        && left.nodeAbi === right.nodeAbi
+        && left.platform === right.platform
+        && left.arch === right.arch
+        && left.installedAt === right.installedAt;
+}
 async function verifiedRuntimeMarker(layout, identity) {
     try {
         const root = await lstat(layout.installRoot);
@@ -1139,49 +1240,90 @@ async function verifiedRuntimeMarker(layout, identity) {
             return undefined;
         if (!(await verifyInstalledPackage(layout, identity)))
             return undefined;
-        await assertRegularFile(layout.markerPath, "managed runtime marker");
-        const marker = JSON.parse(await readFile(layout.markerPath, "utf8"));
-        const exactKeys = [
-            "schema",
-            "packageName",
-            "closureManifestSha256",
-            "executionProofSha256",
-            "packageVersion",
-            "cliSha256",
-            "sourceClosureSha256",
-            "nodeAbi",
-            "platform",
-            "arch",
-            "installedAt",
-        ];
-        const installedAtMs = typeof marker.installedAt === "string" ? Date.parse(marker.installedAt) : Number.NaN;
-        const valid = Object.keys(marker).length === exactKeys.length
-            && exactKeys.every((key) => Object.hasOwn(marker, key))
-            && marker.schema === "mono-agent.managed-runtime.v4"
-            && marker.packageName === PACKAGE_NAME
-            && marker.packageVersion === identity.packageVersion
-            && marker.cliSha256 === identity.cliSha256
-            && marker.sourceClosureSha256 === identity.sourceClosureSha256
-            && marker.nodeAbi === identity.nodeAbi
-            && marker.platform === identity.platform
-            && marker.arch === identity.arch
-            && typeof marker.closureManifestSha256 === "string"
-            && /^[0-9a-f]{64}$/u.test(marker.closureManifestSha256)
-            && typeof marker.executionProofSha256 === "string"
-            && /^[0-9a-f]{64}$/u.test(marker.executionProofSha256)
-            && typeof marker.installedAt === "string"
-            && Number.isFinite(installedAtMs)
-            && new Date(installedAtMs).toISOString() === marker.installedAt
-            // Promotion writes this sentinel before the final filesystem proof is
-            // rebound. It must remain unverifiable even when the filesystem records
-            // both writes with indistinguishable timestamp precision.
-            && marker.installedAt !== PROVISIONAL_RUNTIME_INSTALLED_AT
-            && await verifyClosureManifest(layout, marker.closureManifestSha256);
-        return valid ? marker : undefined;
+        const marker = await readRuntimeMarker(layout.markerPath, identity);
+        return marker !== undefined && await verifyClosureManifest(layout, marker.closureManifestSha256)
+            ? marker
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readRuntimeMarker(path, identity) {
+    let handle;
+    try {
+        handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+        const before = await handle.stat({ bigint: true });
+        if (!privateRuntimeMarkerFile(before))
+            return undefined;
+        const bytes = await handle.readFile();
+        const [after, named] = await Promise.all([
+            handle.stat({ bigint: true }),
+            lstat(path, { bigint: true }),
+        ]);
+        if (!privateRuntimeMarkerFile(after)
+            || !privateRuntimeMarkerFile(named)
+            || !sameSourceStats(before, after)
+            || !sameSourceStats(before, named)) {
+            return undefined;
+        }
+        return runtimeMarkerFromJson(JSON.parse(bytes.toString("utf8")), identity);
     }
     catch {
         return undefined;
     }
+    finally {
+        await handle?.close();
+    }
+}
+function privateRuntimeMarkerFile(details) {
+    const owned = typeof process.getuid !== "function" || details.uid === BigInt(process.getuid());
+    return details.isFile()
+        && !details.isSymbolicLink()
+        && details.nlink === 1n
+        && details.size <= BigInt(MAX_RUNTIME_MARKER_BYTES)
+        && (details.mode & 63n) === 0n
+        && owned;
+}
+function runtimeMarkerFromJson(value, identity) {
+    if (!isRecord(value))
+        return undefined;
+    const exactKeys = [
+        "schema",
+        "packageName",
+        "closureManifestSha256",
+        "executionProofSha256",
+        "packageVersion",
+        "cliSha256",
+        "sourceClosureSha256",
+        "nodeAbi",
+        "platform",
+        "arch",
+        "installedAt",
+    ];
+    const installedAtMs = typeof value.installedAt === "string" ? Date.parse(value.installedAt) : Number.NaN;
+    const valid = Object.keys(value).length === exactKeys.length
+        && exactKeys.every((key) => Object.hasOwn(value, key))
+        && value.schema === "mono-agent.managed-runtime.v4"
+        && value.packageName === PACKAGE_NAME
+        && value.packageVersion === identity.packageVersion
+        && value.cliSha256 === identity.cliSha256
+        && value.sourceClosureSha256 === identity.sourceClosureSha256
+        && value.nodeAbi === identity.nodeAbi
+        && value.platform === identity.platform
+        && value.arch === identity.arch
+        && typeof value.closureManifestSha256 === "string"
+        && /^[0-9a-f]{64}$/u.test(value.closureManifestSha256)
+        && typeof value.executionProofSha256 === "string"
+        && /^[0-9a-f]{64}$/u.test(value.executionProofSha256)
+        && typeof value.installedAt === "string"
+        && Number.isFinite(installedAtMs)
+        && new Date(installedAtMs).toISOString() === value.installedAt
+        // Promotion writes this sentinel before the final filesystem proof is
+        // rebound. It must remain unverifiable even when the filesystem records
+        // both writes with indistinguishable timestamp precision.
+        && value.installedAt !== PROVISIONAL_RUNTIME_INSTALLED_AT;
+    return valid ? value : undefined;
 }
 async function verifyInstalledPackage(layout, identity) {
     try {
@@ -1226,37 +1368,45 @@ async function writeClosureManifest(layout) {
     await chmod(layout.closureManifestPath, 0o600);
     return sha256(Buffer.from(contents, "utf8"));
 }
-async function verifyClosureManifest(layout, expectedSha256) {
+async function verifyClosureManifest(layout, expectedSha256, deps = {}) {
     try {
         await assertRegularFile(layout.closureManifestPath, "managed runtime closure manifest");
-        const contents = await readFile(layout.closureManifestPath);
-        if (sha256(contents) !== expectedSha256)
+        const stored = await fingerprintClosureFile(layout.closureManifestPath, ".mono-agent-closure.json");
+        if (stored.sha256 !== expectedSha256)
             return false;
-        const parsed = JSON.parse(contents.toString("utf8"));
+        const parsed = JSON.parse(stored.bytes.toString("utf8"));
         if (parsed.schema !== "mono-agent.execution-closure.v1" || !Array.isArray(parsed.entries))
             return false;
-        const current = await captureRuntimeClosureManifest(layout);
-        return JSON.stringify(parsed) === JSON.stringify(current);
+        const current = await captureRuntimeClosureManifest(layout, deps);
+        const storedAfter = await captureFilesystemPathProof(layout.closureManifestPath, ".mono-agent-closure.json");
+        return sameSourceProofEntry(stored.proof, storedAfter)
+            && JSON.stringify(parsed) === JSON.stringify(current);
     }
     catch {
         return false;
     }
 }
-async function captureRuntimeClosureManifest(layout) {
+async function captureRuntimeClosureManifest(layout, deps = {}) {
     const entries = [];
+    const proofs = [];
     const excluded = new Set([resolve(layout.closureManifestPath), resolve(layout.markerPath)]);
-    const visit = async (directory) => {
-        const children = await readdir(directory, { withFileTypes: true });
-        children.sort((left, right) => compareCodeUnits(left.name, right.name));
-        for (const child of children) {
-            const path = join(directory, child.name);
+    const visit = async (directory, logicalPath) => {
+        const before = await captureFilesystemPathProof(directory, logicalPath);
+        if (before.type !== "directory") {
+            throw new Error(`Managed runtime closure directory ${logicalPath} changed type.`);
+        }
+        const childNames = (await readdir(directory)).sort(compareCodeUnits);
+        for (const name of childNames) {
+            const path = join(directory, name);
             if (excluded.has(resolve(path)))
                 continue;
-            const details = await lstat(path);
             const pathRelative = portableRelativePath(layout.installRoot, path);
-            const mode = fileMode(details.mode);
-            if (details.isSymbolicLink()) {
-                const target = await readlink(path);
+            const initial = await captureFilesystemPathProof(path, pathRelative);
+            if (initial.type === "symlink") {
+                const target = initial.target;
+                if (target === undefined) {
+                    throw new Error(`Managed runtime symlink ${pathRelative} has no target proof.`);
+                }
                 if (isAbsolute(target)) {
                     throw new Error(`Managed runtime symlink ${pathRelative} has an absolute target.`);
                 }
@@ -1264,29 +1414,50 @@ async function captureRuntimeClosureManifest(layout) {
                 entries.push({
                     path: pathRelative,
                     type: "symlink",
-                    mode,
-                    target: target.split(sep).join("/"),
+                    mode: fileMode(BigInt(initial.mode)),
+                    target,
                 });
+                proofs.push({ path, logicalPath: pathRelative, proof: initial });
                 continue;
             }
-            if (details.isDirectory()) {
-                entries.push({ path: pathRelative, type: "directory", mode });
-                await visit(path);
+            if (initial.type === "directory") {
+                const proof = await visit(path, pathRelative);
+                entries.push({ path: pathRelative, type: "directory", mode: fileMode(BigInt(proof.mode)) });
                 continue;
             }
-            if (details.isFile()) {
+            if (initial.type === "file") {
+                const captured = await fingerprintClosureFile(path, pathRelative);
                 entries.push({
                     path: pathRelative,
                     type: "file",
-                    mode,
-                    sha256: await fingerprintClosureFile(path, pathRelative),
+                    mode: fileMode(BigInt(captured.proof.mode)),
+                    sha256: captured.sha256,
                 });
+                proofs.push({ path, logicalPath: pathRelative, proof: captured.proof });
                 continue;
             }
             throw new Error(`Managed runtime closure contains unsupported entry ${pathRelative}.`);
         }
+        const [after, childNamesAfter] = await Promise.all([
+            captureFilesystemPathProof(directory, logicalPath),
+            readdir(directory).then((names) => names.sort(compareCodeUnits)),
+        ]);
+        if (after.type !== "directory"
+            || !sameSourceProofEntry(before, after)
+            || JSON.stringify(childNames) !== JSON.stringify(childNamesAfter)) {
+            throw new Error(`Managed runtime closure directory ${logicalPath} changed while it was inspected.`);
+        }
+        proofs.push({ path: directory, logicalPath, proof: after });
+        return after;
     };
-    await visit(layout.installRoot);
+    await visit(layout.installRoot, ".");
+    await deps.beforeFinalProof?.();
+    for (const expected of proofs) {
+        const current = await captureFilesystemPathProof(expected.path, expected.logicalPath);
+        if (!sameSourceProofEntry(expected.proof, current)) {
+            throw new Error(`Managed runtime closure entry ${expected.logicalPath} changed during closure capture.`);
+        }
+    }
     entries.sort((left, right) => compareCodeUnits(left.path, right.path));
     return { schema: "mono-agent.execution-closure.v1", entries };
 }
@@ -1302,24 +1473,31 @@ async function fingerprintClosureFile(path, pathRelative) {
         throw error;
     }
     try {
-        const before = await handle.stat();
+        const before = await handle.stat({ bigint: true });
         if (!before.isFile())
             throw new Error(`Managed runtime entry ${pathRelative} is not a regular file.`);
+        if (before.nlink !== 1n) {
+            throw new Error(`Managed runtime file ${pathRelative} must not have additional hard links.`);
+        }
         const bytes = await handle.readFile();
-        const [after, pathAfter] = await Promise.all([handle.stat(), lstat(path)]);
+        const [after, pathAfter] = await Promise.all([
+            handle.stat({ bigint: true }),
+            lstat(path, { bigint: true }),
+        ]);
         if (!after.isFile()
             || !pathAfter.isFile()
             || pathAfter.isSymbolicLink()
-            || before.dev !== after.dev
-            || before.ino !== after.ino
-            || before.size !== after.size
-            || before.mtimeMs !== after.mtimeMs
-            || before.ctimeMs !== after.ctimeMs
-            || after.dev !== pathAfter.dev
-            || after.ino !== pathAfter.ino) {
+            || after.nlink !== 1n
+            || pathAfter.nlink !== 1n
+            || !sameSourceStats(before, after)
+            || !sameSourceStats(after, pathAfter)) {
             throw new Error(`Managed runtime file ${pathRelative} changed while it was fingerprinted.`);
         }
-        return sha256(bytes);
+        return {
+            sha256: sha256(bytes),
+            proof: sourceProofEntry(pathRelative, "file", after),
+            bytes,
+        };
     }
     finally {
         await handle.close();