agentroam 0.2.0-preview.7 → 0.2.0-preview.9

package/dist/node-runtime-manager.js

@@ -0,0 +1,251 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { access, chmod, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, } from "node:fs/promises";
+import { get as httpsGet } from "node:https";
+import { resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const NODE_DOWNLOAD_BASE_URL = "https://nodejs.org/dist/v22.22.0";
+const DEFAULT_DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
+const DEFAULT_LOCK_WAIT_MS = 12 * 60_000;
+const DEFAULT_STALE_LOCK_MS = 15 * 60_000;
+const MAX_REDIRECTS = 5;
+export const MANAGED_NODE_VERSION = "22.22.0";
+export const NODE_RUNTIME_ASSETS = {
+    "darwin-arm64": {
+        archive: "node-v22.22.0-darwin-arm64.tar.xz",
+        sha256: "2bd596bbfc4a275ceb8721a5954ee97daea5ebe673e96a185ebd732f6fb023ac",
+        archiveRoot: "node-v22.22.0-darwin-arm64",
+    },
+    "windows-amd64": {
+        archive: "node-v22.22.0-win-x64.zip",
+        sha256: "c97fa376d2becdc8863fcd3ca2dd9a83a9f3468ee7ccf7a6d076ec66a645c77a",
+        archiveRoot: "node-v22.22.0-win-x64",
+    },
+};
+const defaultDependencies = {
+    download: downloadFile,
+    sha256: sha256File,
+    async run(command, args, timeoutMs) {
+        const { stdout, stderr } = await execFileAsync(command, args, {
+            encoding: "utf8",
+            timeout: timeoutMs,
+            maxBuffer: 4 * 1024 * 1024,
+            windowsHide: true,
+        });
+        return { stdout, stderr };
+    },
+    sleep: (delayMs) => new Promise((resolveDelay) => setTimeout(resolveDelay, delayMs)),
+    now: () => Date.now(),
+};
+export function detectNodeRuntimeTarget(platform = process.platform, arch = process.arch) {
+    if (platform === "darwin" && arch === "arm64")
+        return "darwin-arm64";
+    if (platform === "win32" && arch === "x64")
+        return "windows-amd64";
+    throw Object.assign(new Error(`managed Node.js is unsupported on ${platform}-${arch}`), {
+        exitCode: 2,
+    });
+}
+export function managedNodeExecutable(dataDir, target) {
+    const root = resolve(dataDir, "runtimes", "node", MANAGED_NODE_VERSION);
+    return target === "windows-amd64" ? resolve(root, "node.exe") : resolve(root, "bin", "node");
+}
+export function managedNodeNpmCli(dataDir, target) {
+    const root = resolve(dataDir, "runtimes", "node", MANAGED_NODE_VERSION);
+    return target === "windows-amd64"
+        ? resolve(root, "node_modules", "npm", "bin", "npm-cli.js")
+        : resolve(root, "lib", "node_modules", "npm", "bin", "npm-cli.js");
+}
+export async function ensureManagedNode(options) {
+    const target = options.target ?? detectNodeRuntimeTarget(options.platform, options.arch);
+    const dependencies = { ...defaultDependencies, ...options.dependencies };
+    const cached = await validateManagedNode(options.dataDir, target, dependencies);
+    if (cached)
+        return cached;
+    const parent = resolve(options.dataDir, "runtimes", "node");
+    const runtimeRoot = resolve(parent, MANAGED_NODE_VERSION);
+    const lockPath = `${runtimeRoot}.lock`;
+    await mkdir(parent, { recursive: true });
+    const lock = await acquireLock({
+        lockPath,
+        dataDir: options.dataDir,
+        target,
+        dependencies,
+        waitMs: options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS,
+        staleMs: options.staleLockMs ?? DEFAULT_STALE_LOCK_MS,
+    });
+    if (lock.completed)
+        return lock.completed;
+    let temporaryRoot = null;
+    try {
+        const afterLock = await validateManagedNode(options.dataDir, target, dependencies);
+        if (afterLock)
+            return afterLock;
+        const asset = NODE_RUNTIME_ASSETS[target];
+        temporaryRoot = await mkdtemp(resolve(parent, `.${MANAGED_NODE_VERSION}-${process.pid}-`));
+        const archivePath = resolve(temporaryRoot, asset.archive);
+        const extractRoot = resolve(temporaryRoot, "extract");
+        await mkdir(extractRoot);
+        options.onProgress?.(`Downloading Node.js ${MANAGED_NODE_VERSION} for ${target}...`);
+        await dependencies.download(`${NODE_DOWNLOAD_BASE_URL}/${asset.archive}`, archivePath, options.downloadTimeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS);
+        const actualSha256 = await dependencies.sha256(archivePath);
+        if (actualSha256 !== asset.sha256) {
+            throw new Error(`Node.js archive checksum mismatch: expected ${asset.sha256}, got ${actualSha256}`);
+        }
+        options.onProgress?.(`Extracting Node.js ${MANAGED_NODE_VERSION}...`);
+        await extractArchive(target, archivePath, extractRoot, dependencies);
+        const entries = await readdir(extractRoot);
+        if (entries.length !== 1 || entries[0] !== asset.archiveRoot) {
+            throw new Error(`unexpected Node.js archive root: ${entries.join(", ") || "empty archive"}`);
+        }
+        const extractedRuntime = resolve(extractRoot, asset.archiveRoot);
+        const staged = await validateRuntimeRoot(extractedRuntime, target, dependencies);
+        if (!staged)
+            throw new Error("Node.js runtime validation failed after extraction");
+        await rm(runtimeRoot, { recursive: true, force: true });
+        await rename(extractedRuntime, runtimeRoot);
+        const installed = await validateManagedNode(options.dataDir, target, dependencies);
+        if (!installed)
+            throw new Error("Node.js runtime validation failed after activation");
+        return installed;
+    }
+    catch (error) {
+        const concurrent = await validateManagedNode(options.dataDir, target, dependencies);
+        if (concurrent)
+            return concurrent;
+        throw new Error(`Unable to install managed Node.js ${MANAGED_NODE_VERSION}: ${describeError(error)}`, {
+            cause: error,
+        });
+    }
+    finally {
+        if (temporaryRoot)
+            await rm(temporaryRoot, { recursive: true, force: true });
+        await lock.handle.close().catch(() => undefined);
+        await releaseOwnedLock(lockPath, lock.token);
+    }
+}
+async function validateManagedNode(dataDir, target, dependencies) {
+    return validateRuntimeRoot(resolve(dataDir, "runtimes", "node", MANAGED_NODE_VERSION), target, dependencies);
+}
+async function validateRuntimeRoot(runtimeRoot, target, dependencies) {
+    const executable = target === "windows-amd64"
+        ? resolve(runtimeRoot, "node.exe")
+        : resolve(runtimeRoot, "bin", "node");
+    const npmCli = target === "windows-amd64"
+        ? resolve(runtimeRoot, "node_modules", "npm", "bin", "npm-cli.js")
+        : resolve(runtimeRoot, "lib", "node_modules", "npm", "bin", "npm-cli.js");
+    if (!(await pathExists(executable)) || !(await pathExists(npmCli)))
+        return null;
+    try {
+        if (target === "darwin-arm64")
+            await chmod(executable, 0o755);
+        const result = await dependencies.run(executable, ["--version"], 5_000);
+        if (`${result.stdout}\n${result.stderr}`.trim() !== `v${MANAGED_NODE_VERSION}`)
+            return null;
+        return { executable, npmCli, version: MANAGED_NODE_VERSION, source: "managed" };
+    }
+    catch {
+        return null;
+    }
+}
+async function extractArchive(target, archivePath, extractRoot, dependencies) {
+    if (target === "darwin-arm64") {
+        await dependencies.run("/usr/bin/tar", ["-xJf", archivePath, "-C", extractRoot], 120_000);
+        return;
+    }
+    const script = "& { param($archive, $destination) Expand-Archive -LiteralPath $archive -DestinationPath $destination -Force }";
+    await dependencies.run("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script, archivePath, extractRoot], 120_000);
+}
+async function acquireLock(options) {
+    const deadline = options.dependencies.now() + options.waitMs;
+    while (true) {
+        const token = `${process.pid}:${randomUUID()}`;
+        try {
+            const handle = await open(options.lockPath, "wx", 0o600);
+            await handle.writeFile(`${token}\n${options.dependencies.now()}\n`);
+            return { handle, token };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const completed = await validateManagedNode(options.dataDir, options.target, options.dependencies);
+            if (completed)
+                return { completed };
+            try {
+                const details = await stat(options.lockPath);
+                if (options.dependencies.now() - details.mtimeMs > options.staleMs) {
+                    await rm(options.lockPath, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (options.dependencies.now() >= deadline) {
+                throw new Error(`Timed out waiting for Node.js install lock: ${options.lockPath}`);
+            }
+            await options.dependencies.sleep(Math.min(250, Math.max(1, deadline - options.dependencies.now())));
+        }
+    }
+}
+async function releaseOwnedLock(lockPath, token) {
+    try {
+        if ((await readFile(lockPath, "utf8")).split("\n", 1)[0] === token) {
+            await rm(lockPath, { force: true });
+        }
+    }
+    catch {
+        // A missing or replaced lock no longer belongs to this installer.
+    }
+}
+async function downloadFile(url, destination, timeoutMs) {
+    await new Promise((resolveDownload, rejectDownload) => {
+        const request = (currentUrl, redirects) => {
+            const responseRequest = httpsGet(currentUrl, { headers: { "user-agent": "agentroam-node-bootstrap" } }, (response) => {
+                const status = response.statusCode ?? 0;
+                if (status >= 300 && status < 400 && response.headers.location) {
+                    response.resume();
+                    if (redirects >= MAX_REDIRECTS)
+                        return rejectDownload(new Error("too many Node.js download redirects"));
+                    const redirectUrl = new URL(response.headers.location, currentUrl);
+                    if (redirectUrl.protocol !== "https:") {
+                        rejectDownload(new Error(`refusing non-HTTPS Node.js redirect: ${redirectUrl.protocol}`));
+                        return;
+                    }
+                    request(redirectUrl.toString(), redirects + 1);
+                    return;
+                }
+                if (status !== 200) {
+                    response.resume();
+                    rejectDownload(new Error(`Node.js download failed: HTTP ${status}`));
+                    return;
+                }
+                pipeline(response, createWriteStream(destination, { mode: 0o600 }))
+                    .then(resolveDownload, rejectDownload);
+            });
+            responseRequest.setTimeout(timeoutMs, () => responseRequest.destroy(new Error("Node.js download timed out")));
+            responseRequest.once("error", rejectDownload);
+        };
+        request(url, 0);
+    });
+}
+async function sha256File(path) {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(path), hash);
+    return hash.digest("hex");
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/node-runtime-manager.test.js

@@ -0,0 +1,184 @@
+import { mkdir, mkdtemp, readFile, readdir, rm, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { MANAGED_NODE_VERSION, NODE_RUNTIME_ASSETS, detectNodeRuntimeTarget, ensureManagedNode, managedNodeExecutable, managedNodeNpmCli, } from "./node-runtime-manager.js";
+const temporaryDirectories = [];
+afterEach(async () => {
+    await Promise.all(temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true })));
+});
+describe("managed Node.js runtime", () => {
+    it("uses the exact official manifest", () => {
+        expect(MANAGED_NODE_VERSION).toBe("22.22.0");
+        expect(NODE_RUNTIME_ASSETS["darwin-arm64"]).toEqual({
+            archive: "node-v22.22.0-darwin-arm64.tar.xz",
+            sha256: "2bd596bbfc4a275ceb8721a5954ee97daea5ebe673e96a185ebd732f6fb023ac",
+            archiveRoot: "node-v22.22.0-darwin-arm64",
+        });
+        expect(NODE_RUNTIME_ASSETS["windows-amd64"].archive).toBe("node-v22.22.0-win-x64.zip");
+    });
+    it("selects only supported managed targets", () => {
+        expect(detectNodeRuntimeTarget("darwin", "arm64")).toBe("darwin-arm64");
+        expect(detectNodeRuntimeTarget("win32", "x64")).toBe("windows-amd64");
+        expect(() => detectNodeRuntimeTarget("darwin", "x64")).toThrow("unsupported");
+        expect(() => detectNodeRuntimeTarget("linux", "x64")).toThrow("unsupported");
+    });
+    it("reuses a validated cached runtime", async () => {
+        const dataDir = await temporaryRoot();
+        await fakeRuntime(dataDir, "darwin-arm64");
+        const download = vi.fn();
+        const resolution = await ensureManagedNode({
+            dataDir,
+            target: "darwin-arm64",
+            dependencies: { download, run: versionRunner() },
+        });
+        expect(resolution.executable).toBe(managedNodeExecutable(dataDir, "darwin-arm64"));
+        expect(resolution.npmCli).toBe(managedNodeNpmCli(dataDir, "darwin-arm64"));
+        expect(download).not.toHaveBeenCalled();
+    });
+    it("downloads, extracts, validates, and atomically activates a runtime", async () => {
+        const dataDir = await temporaryRoot();
+        const download = vi.fn(async (_url, destination) => writeFile(destination, "archive"));
+        const run = extractionRunner("darwin-arm64");
+        const resolution = await ensureManagedNode({
+            dataDir,
+            target: "darwin-arm64",
+            dependencies: {
+                download,
+                sha256: async () => NODE_RUNTIME_ASSETS["darwin-arm64"].sha256,
+                run,
+            },
+        });
+        expect(download).toHaveBeenCalledWith("https://nodejs.org/dist/v22.22.0/node-v22.22.0-darwin-arm64.tar.xz", expect.any(String), 10 * 60_000);
+        expect(resolution.version).toBe(MANAGED_NODE_VERSION);
+        expect(await readFile(resolution.npmCli, "utf8")).toBe("npm");
+    });
+    it("rejects a checksum mismatch and cleans temporary state", async () => {
+        const dataDir = await temporaryRoot();
+        await expect(ensureManagedNode({
+            dataDir,
+            target: "darwin-arm64",
+            dependencies: {
+                download: async (_url, destination) => writeFile(destination, "bad"),
+                sha256: async () => "bad-checksum",
+            },
+        })).rejects.toThrow("checksum mismatch");
+        expect(await readdir(resolve(dataDir, "runtimes", "node"))).toEqual([]);
+    });
+    it("rejects an unexpected archive root", async () => {
+        const dataDir = await temporaryRoot();
+        await expect(ensureManagedNode({
+            dataDir,
+            target: "darwin-arm64",
+            dependencies: {
+                download: async (_url, destination) => writeFile(destination, "archive"),
+                sha256: async () => NODE_RUNTIME_ASSETS["darwin-arm64"].sha256,
+                run: async (command, args) => {
+                    if (command === "/usr/bin/tar")
+                        await mkdir(resolve(args[args.indexOf("-C") + 1], "wrong-root"));
+                    return { stdout: "", stderr: "" };
+                },
+            },
+        })).rejects.toThrow("unexpected Node.js archive root");
+    });
+    it("rejects a runtime that reports the wrong version", async () => {
+        const dataDir = await temporaryRoot();
+        const run = extractionRunner("darwin-arm64", "v22.21.0");
+        await expect(ensureManagedNode({
+            dataDir,
+            target: "darwin-arm64",
+            dependencies: {
+                download: async (_url, destination) => writeFile(destination, "archive"),
+                sha256: async () => NODE_RUNTIME_ASSETS["darwin-arm64"].sha256,
+                run,
+            },
+        })).rejects.toThrow("validation failed");
+    });
+    it("serializes concurrent installs", async () => {
+        const dataDir = await temporaryRoot();
+        let downloads = 0;
+        const dependencies = {
+            download: async (_url, destination) => {
+                downloads += 1;
+                await new Promise((resolveDelay) => setTimeout(resolveDelay, 30));
+                await writeFile(destination, "archive");
+            },
+            sha256: async () => NODE_RUNTIME_ASSETS["darwin-arm64"].sha256,
+            run: extractionRunner("darwin-arm64"),
+        };
+        const [first, second] = await Promise.all([
+            ensureManagedNode({ dataDir, target: "darwin-arm64", dependencies }),
+            ensureManagedNode({ dataDir, target: "darwin-arm64", dependencies }),
+        ]);
+        expect(downloads).toBe(1);
+        expect(second.executable).toBe(first.executable);
+    });
+    it("recovers a stale lock", async () => {
+        const dataDir = await temporaryRoot();
+        const lockPath = resolve(dataDir, "runtimes", "node", `${MANAGED_NODE_VERSION}.lock`);
+        await mkdir(dirname(lockPath), { recursive: true });
+        await writeFile(lockPath, "stale");
+        await utimes(lockPath, new Date(0), new Date(0));
+        const resolution = await ensureManagedNode({
+            dataDir,
+            target: "darwin-arm64",
+            staleLockMs: 1,
+            dependencies: {
+                download: async (_url, destination) => writeFile(destination, "archive"),
+                sha256: async () => NODE_RUNTIME_ASSETS["darwin-arm64"].sha256,
+                run: extractionRunner("darwin-arm64"),
+            },
+        });
+        expect(resolution.version).toBe(MANAGED_NODE_VERSION);
+    });
+    it("uses the Windows executable and npm layout", async () => {
+        const dataDir = await temporaryRoot();
+        await fakeRuntime(dataDir, "windows-amd64");
+        await expect(ensureManagedNode({
+            dataDir,
+            target: "windows-amd64",
+            dependencies: { run: versionRunner() },
+        })).resolves.toMatchObject({
+            executable: managedNodeExecutable(dataDir, "windows-amd64"),
+            npmCli: managedNodeNpmCli(dataDir, "windows-amd64"),
+        });
+    });
+});
+async function temporaryRoot() {
+    const root = await mkdtemp(resolve(tmpdir(), "agentroam-node-runtime-"));
+    temporaryDirectories.push(root);
+    return root;
+}
+async function fakeRuntime(dataDir, target) {
+    const executable = managedNodeExecutable(dataDir, target);
+    const npmCli = managedNodeNpmCli(dataDir, target);
+    await mkdir(dirname(executable), { recursive: true });
+    await mkdir(dirname(npmCli), { recursive: true });
+    await writeFile(executable, "node");
+    await writeFile(npmCli, "npm");
+}
+function versionRunner(version = `v${MANAGED_NODE_VERSION}`) {
+    return async () => ({ stdout: `${version}\n`, stderr: "" });
+}
+function extractionRunner(target, version = `v${MANAGED_NODE_VERSION}`) {
+    return vi.fn(async (command, args) => {
+        if (command === "/usr/bin/tar" || command === "powershell.exe") {
+            const extractRoot = command === "/usr/bin/tar"
+                ? args[args.indexOf("-C") + 1]
+                : args.at(-1);
+            const archiveRoot = resolve(extractRoot, NODE_RUNTIME_ASSETS[target].archiveRoot);
+            const executable = target === "windows-amd64"
+                ? resolve(archiveRoot, "node.exe")
+                : resolve(archiveRoot, "bin", "node");
+            const npmCli = target === "windows-amd64"
+                ? resolve(archiveRoot, "node_modules", "npm", "bin", "npm-cli.js")
+                : resolve(archiveRoot, "lib", "node_modules", "npm", "bin", "npm-cli.js");
+            await mkdir(dirname(executable), { recursive: true });
+            await mkdir(dirname(npmCli), { recursive: true });
+            await writeFile(executable, "node");
+            await writeFile(npmCli, "npm");
+            return { stdout: "", stderr: "" };
+        }
+        return { stdout: `${version}\n`, stderr: "" };
+    });
+}

package/dist/opencode-runtime-manager.js

@@ -0,0 +1,207 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access, chmod, mkdir, mkdtemp, open, rename, rm, stat } from "node:fs/promises";
+import { delimiter, isAbsolute, relative, resolve, win32 } from "node:path";
+import { promisify } from "node:util";
+import { resolveNpmExecutor } from "./codex-runtime-manager.js";
+const execFileAsync = promisify(execFile);
+export const OPENCODE_RUNTIME_VERSION = "1.18.27";
+const OPENCODE_PACKAGE = `opencode-ai@${OPENCODE_RUNTIME_VERSION}`;
+const NPM_REGISTRY = "https://registry.npmjs.org";
+const defaults = {
+    async run(command, args, timeoutMs) {
+        try {
+            const { stdout, stderr } = await execFileAsync(command, args, {
+                encoding: "utf8",
+                timeout: timeoutMs,
+                maxBuffer: 4 * 1024 * 1024,
+                windowsHide: true,
+            });
+            return { stdout, stderr };
+        }
+        catch (error) {
+            const value = error;
+            throw new Error([value.message, value.stderr, value.stdout].filter(Boolean).join(": "), { cause: error });
+        }
+    },
+    sleep: (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms)),
+    now: () => Date.now(),
+};
+export async function resolveOpenCodeRuntime(options) {
+    const environment = options.environment ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const dependencies = { ...defaults, ...options.dependencies };
+    const explicit = environment.AGENT_OPENCODE_BIN?.trim();
+    if (explicit) {
+        const absolute = platform === "win32" ? win32.isAbsolute(explicit) : isAbsolute(explicit);
+        if (!absolute)
+            throw new Error("AGENT_OPENCODE_BIN must be an absolute path");
+        return validate(explicit, "explicit", platform, dependencies);
+    }
+    const global = await findGlobal(environment.PATH, platform, dependencies);
+    if (global)
+        return global;
+    const managedRoot = resolve(options.dataDir, "runtimes", "opencode", OPENCODE_RUNTIME_VERSION);
+    const managed = await validateManaged(managedRoot, platform, dependencies);
+    if (managed)
+        return managed;
+    options.onProgress?.(`Installing managed OpenCode ${OPENCODE_RUNTIME_VERSION}...`);
+    return install({ ...options, environment, platform, dependencies, managedRoot });
+}
+export function parseOpenCodeVersion(output) {
+    return output.match(/(?:^|\s)(\d+\.\d+\.\d+)(?:\s|$)/)?.[1] ?? null;
+}
+export function managedOpenCodeBinaryCandidates(root, platform) {
+    return platform === "win32"
+        ? [
+            resolve(root, "node_modules", "opencode-ai", "bin", "opencode.exe"),
+            resolve(root, "node_modules", ".bin", "opencode.cmd"),
+            resolve(root, "node_modules", ".bin", "opencode.exe"),
+        ]
+        : [
+            resolve(root, "node_modules", "opencode-ai", "bin", "opencode.exe"),
+            resolve(root, "node_modules", ".bin", "opencode"),
+        ];
+}
+async function findGlobal(pathValue, platform, dependencies) {
+    const names = platform === "win32" ? ["opencode.exe", "opencode.cmd", "opencode"] : ["opencode"];
+    const separator = platform === "win32" ? ";" : delimiter;
+    for (const directory of (pathValue ?? "").split(separator).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = platform === "win32" ? win32.resolve(directory, name) : resolve(directory, name);
+            if (!(await accessible(candidate, platform !== "win32")))
+                continue;
+            try {
+                return await validate(candidate, "global", platform, dependencies);
+            }
+            catch {
+                // Leave incompatible user installations untouched and use managed OpenCode.
+            }
+        }
+    }
+    return null;
+}
+async function install(options) {
+    const parent = resolve(options.dataDir, "runtimes", "opencode");
+    const lockPath = `${options.managedRoot}.lock`;
+    await mkdir(parent, { recursive: true });
+    const lock = await acquireLock(lockPath, options.managedRoot, options.platform, options.dependencies, options.lockWaitMs ?? 190_000, options.staleLockMs ?? 300_000);
+    if (lock.completed)
+        return lock.completed;
+    let temporary = null;
+    try {
+        const existing = await validateManaged(options.managedRoot, options.platform, options.dependencies);
+        if (existing)
+            return existing;
+        temporary = await mkdtemp(resolve(parent, `.${OPENCODE_RUNTIME_VERSION}-${process.pid}-`));
+        const npm = await resolveNpmExecutor({
+            environment: options.environment,
+            platform: options.platform,
+            nodeExecutable: options.nodeExecutable,
+        });
+        await options.dependencies.run(npm.command, [
+            ...npm.argsPrefix,
+            "install",
+            "--no-audit",
+            "--no-fund",
+            `--registry=${NPM_REGISTRY}`,
+            "--prefix",
+            temporary,
+            OPENCODE_PACKAGE,
+        ], 180_000);
+        const validated = await validateManaged(temporary, options.platform, options.dependencies);
+        if (!validated)
+            throw new Error(`validation failed after installing ${OPENCODE_PACKAGE}`);
+        await rename(temporary, options.managedRoot);
+        temporary = null;
+        const activated = await validateManaged(options.managedRoot, options.platform, options.dependencies);
+        if (!activated)
+            throw new Error("validation failed after activation");
+        return activated;
+    }
+    catch (error) {
+        const concurrent = await validateManaged(options.managedRoot, options.platform, options.dependencies);
+        if (concurrent)
+            return concurrent;
+        throw new Error(`Unable to install managed OpenCode ${OPENCODE_RUNTIME_VERSION}: ${describe(error)}`, { cause: error });
+    }
+    finally {
+        if (temporary)
+            await rm(temporary, { recursive: true, force: true });
+        await lock.handle.close().catch(() => undefined);
+        await rm(lockPath, { force: true });
+    }
+}
+async function acquireLock(lockPath, managedRoot, platform, dependencies, waitMs, staleMs) {
+    const deadline = dependencies.now() + waitMs;
+    while (true) {
+        try {
+            const handle = await open(lockPath, "wx", 0o600);
+            await handle.writeFile(`${process.pid}\n${dependencies.now()}\n`);
+            return { handle };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const completed = await validateManaged(managedRoot, platform, dependencies);
+            if (completed)
+                return { completed };
+            try {
+                if (dependencies.now() - (await stat(lockPath)).mtimeMs > staleMs) {
+                    await rm(lockPath, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (dependencies.now() >= deadline)
+                throw new Error(`Timed out waiting for OpenCode runtime install lock: ${lockPath}`);
+            await dependencies.sleep(Math.min(250, Math.max(1, deadline - dependencies.now())));
+        }
+    }
+}
+async function validateManaged(root, platform, dependencies) {
+    for (const executable of managedOpenCodeBinaryCandidates(root, platform)) {
+        if (!within(root, executable) || !(await accessible(executable)))
+            continue;
+        try {
+            if (platform !== "win32")
+                await chmod(executable, 0o755);
+            return await validate(executable, "managed", platform, dependencies);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+async function validate(executable, source, _platform, dependencies) {
+    if (!(await accessible(executable)))
+        throw new Error(`OpenCode executable not found: ${executable}`);
+    const result = await dependencies.run(executable, ["--version"], 5_000);
+    const version = parseOpenCodeVersion(`${result.stdout}\n${result.stderr}`);
+    if (!version)
+        throw new Error(`Unable to parse OpenCode version from ${executable}`);
+    if (version !== OPENCODE_RUNTIME_VERSION) {
+        throw new Error(`OpenCode ${version} at ${executable} is incompatible; AgentRoam requires ${OPENCODE_RUNTIME_VERSION}`);
+    }
+    await dependencies.run(executable, ["serve", "--help"], 5_000);
+    return { executable, version, source };
+}
+async function accessible(path, executable = false) {
+    try {
+        await access(path, executable ? constants.X_OK : constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function within(root, path) {
+    const value = relative(resolve(root), resolve(path));
+    return value !== "" && !value.startsWith("..") && !isAbsolute(value);
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}