@mono-agent/agent-app 0.8.0 → 0.9.1

package/dist/sandbox-manager.js

@@ -1,7 +1,7 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { chmod, copyFile, lstat, mkdir, mkdtemp, open, opendir, readFile, realpath, rename, rm, stat, unlink, } from "node:fs/promises";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, open, opendir, readFile, realpath, rename, rm, stat, } from "node:fs/promises";
 import { createServer } from "node:http";
 import { homedir, tmpdir } from "node:os";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
@@ -10,14 +10,21 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { CodedError } from "@mono-agent/agent-contracts";
 import { createSandboxPolicy, createSrtSandboxEngine, MANAGED_SRT_TREE_SHA256, } from "@mono-agent/runtime-adapter";
+import { currentProcessIncarnation, isSameProcessIncarnation as matchesProcessIncarnation, processIncarnationFromJson, } from "./process-incarnation.js";
 const execFileAsync = promisify(execFile);
 export const MANAGED_SRT_PACKAGE = "@anthropic-ai/sandbox-runtime";
 export const MANAGED_SRT_VERSION = "0.0.64";
 export const MANAGED_SRT_LOCK_SHA256 = "0f34561ddc700ad43c31f254beb0e1e4b87bae61795acac5d7fa890dd5890924";
 export const MANAGED_SRT_MARKER = ".mono-agent-srt.json";
 const MANAGED_SRT_RESOURCE_ROOT = fileURLToPath(new URL("../resources/srt", import.meta.url));
+const INSTALL_GUARD_NAME = ".install.guard";
 const INSTALL_LOCK_NAME = ".install.lock";
+const INSTALL_LOCK_OWNER_NAME = "owner.json";
 const INSTALL_LOCK_WAIT_MS = 150_000;
+const INSTALL_LOCK_POLL_MS = 100;
+const INSTALL_LOCK_OWNERLESS_GRACE_MS = 5 * 60_000;
+const INSTALL_LOCK_RECORD_MAX_BYTES = 4 * 1024;
+const INSTALL_GUARD_TIMEOUT_EXIT = 75;
 export class SandboxManagerError extends CodedError {
 }
 export function managedSrtInstallRoot(options = {}) {
@@ -98,76 +105,102 @@ export async function setupManagedSrt(options = {}) {
         throw new SandboxManagerError("managed_srt_corrupt", `Managed SRT cache or install resources are unsafe: ${errorMessage(error)}`, { cause: errorMessage(error) });
     }
     const installRoot = managedSrtInstallRoot(options);
-    let initial = await inspectManagedOnly(options);
-    if (initial.state === "ready") {
-        const check = options.verify === false ? undefined : await checkSandboxRuntime(options);
-        return { installed: false, repaired: false, status: initial, ...(check === undefined ? {} : { check }) };
-    }
-    const heldLock = await acquireInstallLock(options);
+    const heldGuard = await acquireInstallGuard(options);
+    let heldLock;
     let stagingRoot;
-    let repaired = false;
+    let result;
+    let primaryError;
     try {
-        throwIfAborted(options.signal);
-        await cleanupStaleStaging(managedSrtVersionRoot(options));
-        initial = await inspectManagedOnly(options);
+        let initial = await inspectManagedOnly(options);
         if (initial.state === "ready") {
             const check = options.verify === false ? undefined : await checkSandboxRuntime(options);
-            return { installed: false, repaired: false, status: initial, ...(check === undefined ? {} : { check }) };
-        }
-        if (initial.state === "corrupt") {
-            await quarantineManagedInstall(installRoot);
-            repaired = true;
-        }
-        stagingRoot = resolve(managedSrtVersionRoot(options), `.${MANAGED_SRT_LOCK_SHA256}.staging.${process.pid}.${randomUUID()}`);
-        await mkdir(stagingRoot, { mode: 0o700 });
-        await stageInstallResources(options.resourceRoot ?? MANAGED_SRT_RESOURCE_ROOT, stagingRoot);
-        throwIfAborted(options.signal);
-        if (options.hooks?.installDependencies !== undefined) {
-            await options.hooks.installDependencies(stagingRoot, options.signal);
+            result = { installed: false, repaired: false, status: initial, ...(check === undefined ? {} : { check }) };
         }
         else {
-            await runNpmCi(stagingRoot, options);
-        }
-        throwIfAborted(options.signal);
-        await rm(resolve(stagingRoot, "node_modules", ".bin"), { recursive: true, force: true });
-        await makeTreePrivateAndRejectLinks(stagingRoot);
-        await writeInstallMarker(stagingRoot, options);
-        await verifyManagedInstall(stagingRoot, options);
-        try {
-            await rename(stagingRoot, installRoot);
-            stagingRoot = undefined;
-        }
-        catch (error) {
-            if (!isNodeError(error, "EEXIST") && !isNodeError(error, "ENOTEMPTY")) {
-                throw error;
+            heldLock = await acquireInstallLock(options);
+            let repaired = false;
+            throwIfAborted(options.signal);
+            await cleanupStaleStaging(managedSrtVersionRoot(options));
+            initial = await inspectManagedOnly(options);
+            if (initial.state === "ready") {
+                const check = options.verify === false ? undefined : await checkSandboxRuntime(options);
+                result = { installed: false, repaired: false, status: initial, ...(check === undefined ? {} : { check }) };
+            }
+            else {
+                if (initial.state === "corrupt") {
+                    await quarantineManagedInstall(installRoot);
+                    repaired = true;
+                }
+                stagingRoot = resolve(managedSrtVersionRoot(options), `.${MANAGED_SRT_LOCK_SHA256}.staging.${process.pid}.${randomUUID()}`);
+                await mkdir(stagingRoot, { mode: 0o700 });
+                await stageInstallResources(options.resourceRoot ?? MANAGED_SRT_RESOURCE_ROOT, stagingRoot);
+                throwIfAborted(options.signal);
+                if (options.hooks?.installDependencies !== undefined) {
+                    await options.hooks.installDependencies(stagingRoot, options.signal);
+                }
+                else {
+                    await runNpmCi(stagingRoot, options);
+                }
+                throwIfAborted(options.signal);
+                await rm(resolve(stagingRoot, "node_modules", ".bin"), { recursive: true, force: true });
+                await makeTreePrivateAndRejectLinks(stagingRoot);
+                await writeInstallMarker(stagingRoot, options);
+                await verifyManagedInstall(stagingRoot, options);
+                try {
+                    await rename(stagingRoot, installRoot);
+                    stagingRoot = undefined;
+                }
+                catch (error) {
+                    if (!isNodeError(error, "EEXIST") && !isNodeError(error, "ENOTEMPTY")) {
+                        throw error;
+                    }
+                    // A legacy actor can only win this race by bypassing our v0.9 guard.
+                    // Accept its result solely if it independently passes the integrity check.
+                    await verifyManagedInstall(installRoot, options);
+                }
+                const status = await inspectManagedOnly(options);
+                if (status.state !== "ready") {
+                    throw new SandboxManagerError("managed_srt_install_failed", `Managed SRT did not validate after atomic installation: ${status.message}`, { installRoot });
+                }
+                const check = options.verify === false ? undefined : await checkSandboxRuntime(options);
+                result = { installed: true, repaired, status, ...(check === undefined ? {} : { check }) };
             }
-            // Another actor can only win this race by bypassing our lock. Accept its
-            // result solely if it independently passes the full integrity check.
-            await verifyManagedInstall(installRoot, options);
-        }
-        const status = await inspectManagedOnly(options);
-        if (status.state !== "ready") {
-            throw new SandboxManagerError("managed_srt_install_failed", `Managed SRT did not validate after atomic installation: ${status.message}`, { installRoot });
         }
-        const check = options.verify === false ? undefined : await checkSandboxRuntime(options);
-        return { installed: true, repaired, status, ...(check === undefined ? {} : { check }) };
     }
     catch (error) {
-        if (error instanceof SandboxManagerError) {
-            throw error;
-        }
-        throw new SandboxManagerError("managed_srt_install_failed", `Managed SRT installation failed without changing PATH or system packages: ${errorMessage(error)}`, { installRoot, cause: errorMessage(error) });
+        primaryError = managedSrtSetupFailure(error, installRoot);
     }
-    finally {
+    const completionErrors = [];
+    if (primaryError !== undefined)
+        completionErrors.push(primaryError);
+    if (stagingRoot !== undefined) {
         try {
-            if (stagingRoot !== undefined) {
-                await rm(stagingRoot, { recursive: true, force: true });
-            }
+            await options.hooks?.beforeInstallStagingCleanup?.(stagingRoot);
+            await rm(stagingRoot, { recursive: true, force: true });
         }
-        finally {
+        catch (error) {
+            completionErrors.push(error);
+        }
+    }
+    if (heldLock !== undefined) {
+        try {
             await releaseInstallLock(heldLock);
         }
+        catch (error) {
+            completionErrors.push(error);
+        }
+    }
+    try {
+        await closeInstallGuard(heldGuard);
     }
+    catch (error) {
+        completionErrors.push(error);
+    }
+    throwCompletionErrors(completionErrors);
+    if (result === undefined) {
+        throw new Error("Managed SRT setup completed without a result.");
+    }
+    return result;
 }
 export async function checkSandboxRuntime(options = {}) {
     const status = await sandboxRuntimeStatus(options);
@@ -542,128 +575,641 @@ async function cleanupStaleStaging(versionRoot) {
         await rm(path, { recursive: true, force: true });
     }
 }
+async function acquireInstallGuard(options) {
+    const guardPath = resolve(managedSrtVersionRoot(options), INSTALL_GUARD_NAME);
+    const timeoutMs = options.hooks?.installGuardTimeoutMs ?? INSTALL_LOCK_WAIT_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw installLockUnsafe(guardPath, "Install-guard timeout must be a non-negative finite duration.");
+    }
+    let handle;
+    try {
+        handle = await open(guardPath, fsConstants.O_RDWR | fsConstants.O_CREAT | (fsConstants.O_NOFOLLOW ?? 0), 0o600);
+        const beforeHandle = await handle.stat({ bigint: true });
+        assertPrivateInstallGuardDetails(beforeHandle, guardPath);
+        const identity = installLockIdentity(beforeHandle);
+        const beforePath = await lstat(guardPath, { bigint: true });
+        assertPrivateInstallGuardDetails(beforePath, guardPath);
+        if (!sameInstallLockIdentity(beforePath, identity)) {
+            throw installLockUnsafe(guardPath, "Install-guard path did not identify the opened file before locking.");
+        }
+        await options.hooks?.beforeInstallGuardAcquire?.(guardPath);
+        await acquireInstallGuardOsLock(handle, guardPath, timeoutMs, options);
+        const afterHandle = await handle.stat({ bigint: true });
+        assertPrivateInstallGuardDetails(afterHandle, guardPath);
+        if (!sameInstallLockIdentity(afterHandle, identity)) {
+            throw installLockUnsafe(guardPath, "Opened install-guard identity changed while acquiring its OS lock.");
+        }
+        const afterPath = await lstat(guardPath, { bigint: true });
+        assertPrivateInstallGuardDetails(afterPath, guardPath);
+        if (!sameInstallLockIdentity(afterPath, identity)) {
+            throw installLockUnsafe(guardPath, "Install-guard path changed while its OS lock was acquired.");
+        }
+        await options.hooks?.afterInstallGuardAcquired?.(guardPath);
+        return {
+            path: guardPath,
+            handle,
+            identity,
+            ...(options.hooks?.beforeInstallGuardClose === undefined
+                ? {}
+                : { beforeClose: options.hooks.beforeInstallGuardClose }),
+        };
+    }
+    catch (error) {
+        const primary = error instanceof SandboxManagerError || error instanceof AggregateError
+            ? error
+            : installLockUnsafe(guardPath, errorMessage(error));
+        if (handle === undefined) {
+            throw primary;
+        }
+        try {
+            await handle.close();
+        }
+        catch (closeError) {
+            throw aggregateFailures([primary, stageFailure("Install-guard handle close failed", closeError)], "Managed SRT install-guard acquisition and handle close both failed.");
+        }
+        throw primary;
+    }
+}
+async function acquireInstallGuardOsLock(handle, guardPath, timeoutMs, options) {
+    const startedAt = process.hrtime.bigint();
+    const elapsedMs = () => Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+    // These helpers provide advisory descriptor locks for the local user cache.
+    // Network filesystems with non-local flock semantics are deliberately unsupported.
+    const helper = process.platform === "darwin"
+        ? { command: "/usr/bin/lockf", args: ["-s", "-t", "0", "3"] }
+        : process.platform === "linux"
+            ? { command: "/usr/bin/flock", args: ["-E", String(INSTALL_GUARD_TIMEOUT_EXIT), "-x", "-n", "3"] }
+            : undefined;
+    if (helper === undefined) {
+        throw installLockUnsafe(guardPath, `No supported install-guard helper exists on ${process.platform}.`);
+    }
+    while (true) {
+        throwIfAborted(options.signal);
+        const outcome = await runInstallGuardHelperAttempt(handle, helper);
+        if (outcome.code === 0) {
+            throwIfAborted(options.signal);
+            return;
+        }
+        if (outcome.code !== INSTALL_GUARD_TIMEOUT_EXIT) {
+            throw installLockUnsafe(guardPath, `Install-guard helper failed (${outcome.signal ?? `exit ${String(outcome.code)}`}): ${outcome.stderr.trim() || "no diagnostic output"}`, { helper: helper.command, exitCode: outcome.code, signal: outcome.signal });
+        }
+        throwIfAborted(options.signal);
+        const elapsed = elapsedMs();
+        if (elapsed >= timeoutMs) {
+            throw installLockUnsafe(guardPath, `Timed out waiting ${timeoutMs} milliseconds for the managed SRT install guard.`, { helper: helper.command, exitCode: outcome.code });
+        }
+        await abortableSleep(Math.min(INSTALL_LOCK_POLL_MS, Math.max(0, timeoutMs - elapsed)), options.signal);
+    }
+}
+async function runInstallGuardHelperAttempt(handle, helper) {
+    return await new Promise((resolvePromise, reject) => {
+        const child = spawn(helper.command, helper.args, {
+            stdio: ["ignore", "ignore", "pipe", handle.fd],
+        });
+        let stderr = "";
+        let spawnError;
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            if (stderr.length < INSTALL_LOCK_RECORD_MAX_BYTES) {
+                stderr += chunk.slice(0, INSTALL_LOCK_RECORD_MAX_BYTES - stderr.length);
+            }
+        });
+        child.once("error", (error) => { spawnError = error; });
+        child.once("close", (code, childSignal) => {
+            if (spawnError !== undefined) {
+                reject(spawnError);
+            }
+            else {
+                resolvePromise({ code, signal: childSignal, stderr });
+            }
+        });
+    });
+}
+async function closeInstallGuard(guard) {
+    const errors = [];
+    try {
+        await guard.beforeClose?.(guard.path);
+    }
+    catch (error) {
+        errors.push(error);
+    }
+    try {
+        const handleDetails = await guard.handle.stat({ bigint: true });
+        assertPrivateInstallGuardDetails(handleDetails, guard.path);
+        const pathDetails = await lstat(guard.path, { bigint: true });
+        assertPrivateInstallGuardDetails(pathDetails, guard.path);
+        if (!sameInstallLockIdentity(handleDetails, guard.identity)
+            || !sameInstallLockIdentity(pathDetails, guard.identity)) {
+            throw installLockUnsafe(guard.path, "Install-guard identity changed while the guarded operation was active.");
+        }
+    }
+    catch (error) {
+        errors.push(error instanceof SandboxManagerError
+            ? error
+            : installLockUnsafe(guard.path, errorMessage(error)));
+    }
+    try {
+        await guard.handle.close();
+    }
+    catch (error) {
+        errors.push(error);
+    }
+    throwCompletionErrors(errors, "Managed SRT install-guard validation or close failed.");
+}
+function assertPrivateInstallGuardDetails(details, path) {
+    if (!details.isFile()
+        || details.isSymbolicLink()
+        || details.nlink !== 1n
+        || (details.mode & 63n) !== 0n) {
+        throw new Error(`install guard ${path} must be an owner-only single-link regular file`);
+    }
+    if (process.getuid !== undefined && details.uid !== BigInt(process.getuid())) {
+        throw new Error(`install guard ${path} is not owned by the current user`);
+    }
+}
 async function acquireInstallLock(options) {
     const lockPath = resolve(managedSrtVersionRoot(options), INSTALL_LOCK_NAME);
-    const deadline = Date.now() + INSTALL_LOCK_WAIT_MS;
+    const now = options.hooks?.now ?? Date.now;
+    const ownerlessGraceMs = options.hooks?.ownerlessGraceMs ?? INSTALL_LOCK_OWNERLESS_GRACE_MS;
+    if (!Number.isFinite(ownerlessGraceMs) || ownerlessGraceMs < 0) {
+        throw new SandboxManagerError("managed_srt_lock_unsafe", "Managed SRT install-lock ownerless grace must be a non-negative finite duration.", { ownerlessGraceMs });
+    }
+    const deadline = now() + INSTALL_LOCK_WAIT_MS;
+    const incarnation = await (options.hooks?.currentProcessIncarnation ?? currentProcessIncarnation)();
+    const isSameProcess = options.hooks?.isSameProcessIncarnation ?? matchesProcessIncarnation;
     while (true) {
         throwIfAborted(options.signal);
         const token = randomUUID();
-        let handle;
+        let createdIdentity;
         try {
-            handle = await open(lockPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY | (fsConstants.O_NOFOLLOW ?? 0), 0o600);
+            await mkdir(lockPath, { mode: 0o700 });
+            const created = await assertPrivateInstallLockDirectory(lockPath);
+            createdIdentity = installLockIdentity(created);
+            await options.hooks?.afterInstallLockDirectoryCreated?.(lockPath);
+            await assertSamePrivateInstallLockDirectory(lockPath, createdIdentity);
             const record = {
-                schemaVersion: 1,
+                schemaVersion: 2,
                 pid: process.pid,
                 uid: process.getuid?.() ?? null,
                 token,
-                startedAt: new Date().toISOString(),
+                startedAt: new Date(now()).toISOString(),
+                incarnation,
+            };
+            const owner = await publishInstallLockOwner(lockPath, createdIdentity, record);
+            await syncPrivateInstallLockDirectory(lockPath, createdIdentity);
+            await assertSamePrivateInstallLockDirectory(lockPath, createdIdentity);
+            return {
+                path: lockPath,
+                identity: createdIdentity,
+                owner,
+                ...(options.hooks?.beforeInstallLockReleaseRename === undefined
+                    ? {}
+                    : { beforeRelease: options.hooks.beforeInstallLockReleaseRename }),
             };
-            await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
-            await handle.sync();
-            const lockStat = await handle.stat({ bigint: true });
-            await handle.close();
-            return { path: lockPath, token, dev: lockStat.dev, ino: lockStat.ino };
         }
         catch (error) {
-            await handle?.close().catch(() => undefined);
+            if (createdIdentity !== undefined) {
+                try {
+                    await abandonCreatedInstallLock(lockPath, createdIdentity);
+                }
+                catch (cleanupError) {
+                    throw aggregateFailures([error, stageFailure("Failed install-lock acquisition cleanup", cleanupError)], `Managed SRT install-lock acquisition and cleanup both failed at ${lockPath}.`);
+                }
+            }
             if (!isNodeError(error, "EEXIST")) {
                 throw error;
             }
         }
-        let existing;
-        try {
-            existing = await readSecureInstallLock(lockPath);
-        }
-        catch (error) {
-            if (isNodeError(error, "ENOENT")) {
+        const existing = await inspectExistingInstallLock(lockPath);
+        if (existing === undefined)
+            continue;
+        await options.hooks?.afterInstallLockInspected?.(lockPath, existing.kind);
+        if (existing.kind === "ownerless") {
+            if (now() - existing.mtimeMs >= ownerlessGraceMs) {
+                await quarantineStaleInstallLock(lockPath, existing, options);
                 continue;
             }
-            throw error;
+            if (now() >= deadline) {
+                throw installLockUnsafe(lockPath, "Another installer left a fresh ownerless SRT install lock in its bounded publication window.");
+            }
         }
-        const liveness = options.hooks?.processIsAlive?.(existing.record.pid) ?? processLiveness(existing.record.pid);
-        if (liveness === "dead") {
+        else if (existing.kind === "owned") {
+            let sameOwner;
             try {
-                await unlinkLockIfUnchanged(lockPath, existing);
+                sameOwner = await isSameProcess(existing.owner.record.pid, existing.owner.record.incarnation);
             }
             catch (error) {
-                if (!isNodeError(error, "ENOENT")) {
-                    throw error;
-                }
+                throw installLockUnsafe(lockPath, `Cannot prove the SRT install lock owner's process incarnation: ${errorMessage(error)}`);
+            }
+            if (!sameOwner) {
+                await quarantineStaleInstallLock(lockPath, existing, options);
+                continue;
+            }
+            if (now() >= deadline) {
+                throw installLockUnsafe(lockPath, `Another live process incarnation (PID ${existing.owner.record.pid}) still owns the SRT install lock.`, { pid: existing.owner.record.pid });
             }
-            continue;
         }
-        if (liveness === "unknown") {
-            throw new SandboxManagerError("managed_srt_lock_unsafe", `Cannot prove whether SRT install lock owner PID ${existing.record.pid} is alive; refusing to remove it.`, { lockPath, pid: existing.record.pid });
+        else if (existing.kind === "legacy-publishing") {
+            if (now() >= deadline) {
+                throw installLockUnsafe(lockPath, "A legacy SRT installer did not finish publishing its lock record; the incomplete lock was left untouched.");
+            }
         }
-        if (Date.now() >= deadline) {
-            throw new SandboxManagerError("managed_srt_lock_unsafe", `Another live process (PID ${existing.record.pid}) still owns the SRT install lock.`, { lockPath, pid: existing.record.pid });
+        else {
+            const liveness = options.hooks?.processIsAlive?.(existing.record.pid)
+                ?? processLiveness(existing.record.pid);
+            if (liveness === "dead") {
+                await quarantineStaleInstallLock(lockPath, existing, options);
+                continue;
+            }
+            if (liveness === "unknown") {
+                throw installLockUnsafe(lockPath, `Cannot prove whether legacy SRT install lock owner PID ${existing.record.pid} is alive; refusing to remove it.`, { pid: existing.record.pid });
+            }
+            if (now() >= deadline) {
+                throw installLockUnsafe(lockPath, `Another live legacy process (PID ${existing.record.pid}) still owns the SRT install lock.`, { pid: existing.record.pid });
+            }
         }
-        await (options.hooks?.sleep ?? abortableSleep)(100, options.signal);
+        await (options.hooks?.sleep ?? abortableSleep)(INSTALL_LOCK_POLL_MS, options.signal);
     }
 }
-async function readSecureInstallLock(lockPath) {
-    let handle;
+async function inspectExistingInstallLock(lockPath) {
     try {
-        handle = await open(lockPath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
-        const lockStat = await handle.stat({ bigint: true });
-        if (!lockStat.isFile() || lockStat.nlink !== 1n || (lockStat.mode & 63n) !== 0n) {
-            throw new Error("lock is not an owner-only single-link regular file");
-        }
-        if (process.getuid !== undefined && lockStat.uid !== BigInt(process.getuid())) {
-            throw new Error("lock owner differs from the current user");
-        }
-        const content = await handle.readFile("utf8");
-        const record = JSON.parse(content);
-        if (record.schemaVersion !== 1
-            || !Number.isSafeInteger(record.pid)
-            || record.pid <= 0
-            || typeof record.token !== "string"
-            || !/^[a-f0-9-]{36}$/iu.test(record.token)
-            || typeof record.startedAt !== "string"
-            || (record.uid !== null && !Number.isSafeInteger(record.uid))
-            || (process.getuid !== undefined && record.uid !== process.getuid())) {
-            throw new Error("lock record is malformed or belongs to another user");
-        }
-        return { record, content, dev: lockStat.dev, ino: lockStat.ino };
+        const details = await lstat(lockPath, { bigint: true });
+        if (details.isSymbolicLink()) {
+            throw new Error("lock path must not be a symbolic link");
+        }
+        assertInstallLockOwned(details, lockPath);
+        const identity = installLockIdentity(details);
+        if (details.isDirectory()) {
+            assertPrivateInstallLockDirectoryDetails(details, lockPath);
+            const owner = await readSecureInstallLockOwner(resolve(lockPath, INSTALL_LOCK_OWNER_NAME));
+            if (owner === "detached")
+                return undefined;
+            const current = await samePrivateInstallLockDirectory(lockPath, identity);
+            if (!current)
+                return undefined;
+            if (owner === undefined) {
+                const ownerlessDetails = await assertSamePrivateInstallLockDirectory(lockPath, identity);
+                return { kind: "ownerless", identity, mtimeMs: Number(ownerlessDetails.mtimeMs) };
+            }
+            return { kind: "owned", identity, owner };
+        }
+        if (details.isFile()) {
+            return await readSecureLegacyInstallLock(lockPath, identity);
+        }
+        throw new Error("lock path must be a private directory or a legacy regular file");
     }
     catch (error) {
-        if (isNodeError(error, "ENOENT")) {
+        if (isNodeError(error, "ENOENT"))
+            return undefined;
+        if (error instanceof SandboxManagerError)
             throw error;
+        throw installLockUnsafe(lockPath, errorMessage(error));
+    }
+}
+async function publishInstallLockOwner(lockPath, identity, record) {
+    const ownerPath = resolve(lockPath, INSTALL_LOCK_OWNER_NAME);
+    const temporaryPath = resolve(lockPath, `.owner.${process.pid}.${record.token}.tmp`);
+    const handle = await open(temporaryPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY | (fsConstants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+        await handle.sync();
+        assertPrivateInstallLockOwnerDetails(await handle.stat({ bigint: true }), temporaryPath);
+    }
+    finally {
+        await handle.close();
+    }
+    await assertSamePrivateInstallLockDirectory(lockPath, identity);
+    await rename(temporaryPath, ownerPath);
+    await assertSamePrivateInstallLockDirectory(lockPath, identity);
+    const owner = await readSecureInstallLockOwner(ownerPath);
+    if (owner === undefined || owner === "detached" || owner.record.token !== record.token) {
+        throw installLockUnsafe(lockPath, "The atomically published owner record could not be verified.");
+    }
+    return owner;
+}
+async function readSecureInstallLockOwner(ownerPath) {
+    let handle;
+    try {
+        handle = await open(ownerPath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (before.nlink === 0n)
+            return "detached";
+        assertPrivateInstallLockOwnerDetails(before, ownerPath);
+        const content = await readBoundedInstallLockRecord(handle, ownerPath);
+        const after = await handle.stat({ bigint: true });
+        if (after.nlink === 0n)
+            return "detached";
+        assertPrivateInstallLockOwnerDetails(after, ownerPath);
+        if (!sameInstallLockIdentity(after, installLockIdentity(before))) {
+            throw new Error("owner record identity changed while it was read");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (error) {
+            throw new Error(`owner record JSON is malformed: ${errorMessage(error)}`);
+        }
+        const incarnation = processIncarnationFromJson(parsed.incarnation);
+        if (!validInstallLockRecordFields(parsed, 2) || incarnation === undefined) {
+            throw new Error("owner record is malformed or belongs to another user");
+        }
+        const valid = parsed;
+        return {
+            record: {
+                schemaVersion: 2,
+                pid: valid.pid,
+                uid: valid.uid,
+                token: valid.token,
+                startedAt: valid.startedAt,
+                incarnation,
+            },
+            content,
+            identity: installLockIdentity(after),
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readSecureLegacyInstallLock(lockPath, observedIdentity) {
+    let handle;
+    try {
+        handle = await open(lockPath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+        const before = await handle.stat({ bigint: true });
+        if (!sameInstallLockIdentity(before, observedIdentity) || before.nlink === 0n)
+            return undefined;
+        assertPrivateLegacyInstallLockDetails(before, lockPath);
+        const content = await readBoundedInstallLockRecord(handle, lockPath);
+        const after = await handle.stat({ bigint: true });
+        if (after.nlink === 0n)
+            return undefined;
+        assertPrivateLegacyInstallLockDetails(after, lockPath);
+        if (!sameInstallLockIdentity(after, observedIdentity))
+            return undefined;
+        if (!content.endsWith("\n")) {
+            if (!(await sameInstallLockPathIdentity(lockPath, observedIdentity)))
+                return undefined;
+            return {
+                kind: "legacy-publishing",
+                identity: observedIdentity,
+                content,
+            };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
         }
-        throw new SandboxManagerError("managed_srt_lock_unsafe", `SRT install lock is unsafe and was left untouched: ${errorMessage(error)}`, { lockPath, cause: errorMessage(error) });
+        catch (error) {
+            throw new Error(`legacy lock JSON is incomplete or malformed: ${errorMessage(error)}`);
+        }
+        if (!validInstallLockRecordFields(parsed, 1)) {
+            throw new Error("legacy lock record is malformed or belongs to another user");
+        }
+        const valid = parsed;
+        if (!(await sameInstallLockPathIdentity(lockPath, observedIdentity)))
+            return undefined;
+        return {
+            kind: "legacy",
+            identity: observedIdentity,
+            record: {
+                schemaVersion: 1,
+                pid: valid.pid,
+                uid: valid.uid,
+                token: valid.token,
+                startedAt: valid.startedAt,
+            },
+            content,
+        };
     }
     finally {
         await handle?.close().catch(() => undefined);
     }
 }
-async function unlinkLockIfUnchanged(lockPath, expected) {
-    const current = await readSecureInstallLock(lockPath);
-    if (current.dev !== expected.dev
-        || current.ino !== expected.ino
-        || current.content !== expected.content
-        || current.record.token !== expected.record.token) {
-        throw new SandboxManagerError("managed_srt_lock_unsafe", "SRT install lock changed during stale-lock verification; it was left untouched.", { lockPath });
+async function readBoundedInstallLockRecord(handle, path) {
+    const buffer = Buffer.alloc(INSTALL_LOCK_RECORD_MAX_BYTES + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+        if (bytesRead === 0)
+            break;
+        offset += bytesRead;
+    }
+    if (offset > INSTALL_LOCK_RECORD_MAX_BYTES) {
+        throw new Error(`lock record ${path} exceeds ${INSTALL_LOCK_RECORD_MAX_BYTES} bytes`);
+    }
+    return buffer.subarray(0, offset).toString("utf8");
+}
+function validInstallLockRecordFields(record, schemaVersion) {
+    return record.schemaVersion === schemaVersion
+        && typeof record.pid === "number"
+        && Number.isSafeInteger(record.pid)
+        && record.pid > 0
+        && typeof record.token === "string"
+        && /^[a-f0-9-]{36}$/iu.test(record.token)
+        && typeof record.startedAt === "string"
+        && Number.isFinite(Date.parse(record.startedAt))
+        && (record.uid === null || (typeof record.uid === "number" && Number.isSafeInteger(record.uid)))
+        && (process.getuid === undefined || record.uid === process.getuid());
+}
+async function quarantineStaleInstallLock(lockPath, expected, options) {
+    await options.hooks?.beforeStaleInstallLockRename?.(lockPath);
+    const current = await inspectExistingInstallLock(lockPath);
+    if (current === undefined)
+        return false;
+    if (!sameExistingInstallLock(current, expected)) {
+        throw installLockUnsafe(lockPath, "SRT install lock changed during stale-lock verification; the replacement was left untouched.");
+    }
+    const quarantinePath = `${lockPath}.stale.${process.pid}.${randomUUID()}`;
+    try {
+        await rename(lockPath, quarantinePath);
     }
-    await unlink(lockPath);
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+    const moved = await inspectExistingInstallLock(quarantinePath);
+    if (moved === undefined || !sameExistingInstallLock(moved, expected)) {
+        throw installLockUnsafe(lockPath, `The stale lock changed across quarantine and was retained at ${quarantinePath}.`, { quarantinePath });
+    }
+    await rm(quarantinePath, { recursive: true, force: true });
+    return true;
 }
 async function releaseInstallLock(lock) {
-    if (!(await pathExists(lock.path))) {
-        return;
+    const expected = {
+        kind: "owned",
+        identity: lock.identity,
+        owner: lock.owner,
+    };
+    const observed = await inspectExistingInstallLock(lock.path);
+    if (observed === undefined || !sameExistingInstallLock(observed, expected)) {
+        throw installLockUnsafe(lock.path, "SRT install lock identity or owner changed before release; another lock was left untouched.");
     }
-    let current;
+    await lock.beforeRelease?.(lock.path);
+    const current = await inspectExistingInstallLock(lock.path);
+    if (current === undefined || !sameExistingInstallLock(current, expected)) {
+        throw installLockUnsafe(lock.path, "SRT install lock changed at the release boundary; the replacement was left untouched.");
+    }
+    const releasedPath = `${lock.path}.released.${process.pid}.${randomUUID()}`;
     try {
-        current = await readSecureInstallLock(lock.path);
+        await rename(lock.path, releasedPath);
     }
     catch (error) {
         if (isNodeError(error, "ENOENT")) {
-            return;
+            throw installLockUnsafe(lock.path, "SRT install lock disappeared during release.");
         }
         throw error;
     }
-    if (current.dev !== lock.dev || current.ino !== lock.ino || current.record.token !== lock.token) {
-        throw new SandboxManagerError("managed_srt_lock_unsafe", "SRT install lock identity changed; refusing to remove another process's lock.", { lockPath: lock.path });
+    const moved = await inspectExistingInstallLock(releasedPath);
+    if (moved === undefined || !sameExistingInstallLock(moved, expected)) {
+        throw installLockUnsafe(lock.path, `SRT install lock changed across release and was retained at ${releasedPath}.`, { releasedPath });
+    }
+    await rm(releasedPath, { recursive: true, force: true });
+}
+async function abandonCreatedInstallLock(lockPath, identity) {
+    if (!(await samePrivateInstallLockDirectory(lockPath, identity)))
+        return;
+    const abandonedPath = `${lockPath}.abandoned.${process.pid}.${randomUUID()}`;
+    try {
+        await rename(lockPath, abandonedPath);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return;
+        throw error;
+    }
+    const moved = await lstat(abandonedPath, { bigint: true });
+    if (!sameInstallLockIdentity(moved, identity)) {
+        throw installLockUnsafe(lockPath, `A failed acquisition changed across quarantine and was retained at ${abandonedPath}.`, { abandonedPath });
+    }
+    await rm(abandonedPath, { recursive: true, force: true });
+}
+async function assertPrivateInstallLockDirectory(path) {
+    const details = await lstat(path, { bigint: true });
+    assertPrivateInstallLockDirectoryDetails(details, path);
+    return details;
+}
+function assertPrivateInstallLockDirectoryDetails(details, path) {
+    if (!details.isDirectory() || details.isSymbolicLink()) {
+        throw new Error("lock path must be a real directory");
+    }
+    assertInstallLockOwned(details, path);
+    if ((details.mode & 63n) !== 0n) {
+        throw new Error("lock directory must be owner-only (mode 0700)");
     }
-    await unlink(lock.path);
+}
+function assertPrivateInstallLockOwnerDetails(details, path) {
+    if (!details.isFile() || details.isSymbolicLink() || details.nlink !== 1n || (details.mode & 63n) !== 0n) {
+        throw new Error(`lock owner ${path} must be an owner-only single-link regular file`);
+    }
+    assertInstallLockOwned(details, path);
+}
+function assertPrivateLegacyInstallLockDetails(details, path) {
+    if (!details.isFile() || details.isSymbolicLink() || details.nlink !== 1n || (details.mode & 63n) !== 0n) {
+        throw new Error(`legacy lock ${path} must be an owner-only single-link regular file`);
+    }
+    assertInstallLockOwned(details, path);
+}
+function assertInstallLockOwned(details, path) {
+    if (process.getuid !== undefined && details.uid !== BigInt(process.getuid())) {
+        throw new Error(`lock path ${path} is not owned by the current user`);
+    }
+}
+async function assertSamePrivateInstallLockDirectory(path, identity) {
+    const details = await assertPrivateInstallLockDirectory(path);
+    if (!sameInstallLockIdentity(details, identity)) {
+        throw installLockUnsafe(path, "SRT install lock directory identity changed.");
+    }
+    return details;
+}
+async function samePrivateInstallLockDirectory(path, identity) {
+    try {
+        return sameInstallLockIdentity(await assertPrivateInstallLockDirectory(path), identity);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+async function sameInstallLockPathIdentity(path, identity) {
+    try {
+        return sameInstallLockIdentity(await lstat(path, { bigint: true }), identity);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+async function syncPrivateInstallLockDirectory(path, identity) {
+    const handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_DIRECTORY ?? 0) | (fsConstants.O_NOFOLLOW ?? 0));
+    try {
+        const details = await handle.stat({ bigint: true });
+        assertPrivateInstallLockDirectoryDetails(details, path);
+        if (!sameInstallLockIdentity(details, identity)) {
+            throw installLockUnsafe(path, "SRT install lock changed before its owner publication was synced.");
+        }
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function installLockIdentity(details) {
+    return { dev: details.dev, ino: details.ino };
+}
+function sameInstallLockIdentity(details, identity) {
+    return details.dev === identity.dev && details.ino === identity.ino;
+}
+function sameExistingInstallLock(left, right) {
+    if (left.kind !== right.kind || !sameInstallLockIdentity(left.identity, right.identity))
+        return false;
+    if (left.kind === "ownerless" && right.kind === "ownerless")
+        return true;
+    if (left.kind === "owned" && right.kind === "owned") {
+        return left.owner.record.token === right.owner.record.token
+            && left.owner.content === right.owner.content
+            && sameInstallLockIdentity(left.owner.identity, right.owner.identity);
+    }
+    if (left.kind === "legacy" && right.kind === "legacy") {
+        return left.record.token === right.record.token && left.content === right.content;
+    }
+    return left.kind === "legacy-publishing"
+        && right.kind === "legacy-publishing"
+        && left.content === right.content;
+}
+function installLockUnsafe(lockPath, cause, details = {}) {
+    return new SandboxManagerError("managed_srt_lock_unsafe", `SRT install lock is unsafe and was left untouched: ${cause}`, { lockPath, cause, ...details });
+}
+function managedSrtSetupFailure(error, installRoot) {
+    if (error instanceof SandboxManagerError || error instanceof AggregateError)
+        return error;
+    return new SandboxManagerError("managed_srt_install_failed", `Managed SRT installation failed without changing PATH or system packages: ${errorMessage(error)}`, { installRoot, cause: errorMessage(error) });
+}
+function stageFailure(stage, error) {
+    return new Error(`${stage}: ${errorMessage(error)}`, { cause: error });
+}
+function throwCompletionErrors(errors, message = "Managed SRT setup and one or more cleanup or release stages failed.") {
+    if (errors.length === 0)
+        return;
+    if (errors.length === 1)
+        throw errors[0];
+    throw aggregateFailures(errors, message);
+}
+function aggregateFailures(errors, message) {
+    const summary = errors
+        .map((error) => errorMessage(error).replace(/\s+/gu, " ").slice(0, 500))
+        .join(" | ");
+    return new AggregateError(errors, `${message} Failures: ${summary}`);
 }
 function processLiveness(pid) {
     try {