Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-7790 Fix cross-device managed runtime installs (#3198)

mike-inkeepc05cbf4b2349
diff --git a/.changeset/managed-runtime-cross-device.md b/.changeset/managed-runtime-cross-device.md
new file mode 100644
index 000000000..53ff42a3f
--- /dev/null
+++ b/.changeset/managed-runtime-cross-device.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Managed Node.js and uv runtimes now install correctly when the temporary directory and OpenKnowledge home are on different filesystems. Runtime archives are staged beside their destination for an atomic same-filesystem rename, and concurrent launches adopt an already completed install instead of removing it.
diff --git a/packages/server/src/acp/managed-runtime-flow.integration.test.ts b/packages/server/src/acp/managed-runtime-flow.integration.test.ts
index ebc64cf63..80cef0567 100644
--- a/packages/server/src/acp/managed-runtime-flow.integration.test.ts
+++ b/packages/server/src/acp/managed-runtime-flow.integration.test.ts
@@ -13,7 +13,15 @@
import { execFileSync } from 'node:child_process';
import { createHash } from 'node:crypto';
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ utimesSync,
+ writeFileSync,
+} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type {
@@ -23,7 +31,7 @@ import type {
import { afterEach, describe, expect, test } from 'vitest';
import type { AgentSessionManager } from '../agent-sessions.ts';
import { getLogger } from '../logger.ts';
-import { findManagedRuntime, readRuntimeConsent } from './managed-runtime.ts';
+import { ensureManagedRuntime, findManagedRuntime, readRuntimeConsent } from './managed-runtime.ts';
import { AcpPermissionStore } from './permissions.ts';
import { AcpRegistry } from './registry.ts';
import { AcpThreadManager } from './thread-manager.ts';
@@ -150,6 +158,33 @@ function findConsentRequest(
}
describe('managed-runtime consent + download flow', () => {
+ test('normal launch cleans stale staging after a runtime is installed', async () => {
+ const contentDir = tmp();
+ const localDir = tmp();
+ const runtimeRoot = tmp();
+ const consentHome = tmp();
+ const stage = tmp();
+ const { bytes, sha } = fakeNodeTarball(stage);
+ const fetchImpl = fakeNodeFetch(bytes, sha);
+ await ensureManagedRuntime('node', log, { root: runtimeRoot, fetchImpl });
+
+ const staleDir = join(runtimeRoot, 'node', '.install-v24.18.0-orphaned');
+ mkdirSync(staleDir, { recursive: true });
+ const staleTime = new Date(Date.now() - 25 * 60 * 60 * 1_000);
+ utimesSync(staleDir, staleTime, staleTime);
+
+ const manager = makeManager({
+ contentDir,
+ localDir,
+ runtimeRoot,
+ consentHome,
+ fetchImpl,
+ });
+ await manager.createThread({ agent: { source: 'registry', id: 'npxagent' } });
+
+ await waitFor(() => !existsSync(staleDir), 3_000, 'stale runtime staging cleanup');
+ });
+
test('grant → download → install + persist consent', async () => {
const contentDir = tmp();
const localDir = tmp();
diff --git a/packages/server/src/acp/managed-runtime.test.ts b/packages/server/src/acp/managed-runtime.test.ts
index 89264aa23..e868fe797 100644
--- a/packages/server/src/acp/managed-runtime.test.ts
+++ b/packages/server/src/acp/managed-runtime.test.ts
@@ -8,7 +8,16 @@
import { execFileSync } from 'node:child_process';
import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ utimesSync,
+ writeFileSync,
+} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, describe, expect, test } from 'vitest';
@@ -43,6 +52,7 @@ function buildTarball(
dir: string,
innerDir: string,
files: string[],
+ label?: string,
): { bytes: Buffer; sha: string } {
const treeRoot = join(dir, `tree-${innerDir}`);
const inner = join(treeRoot, innerDir);
@@ -50,7 +60,7 @@ function buildTarball(
for (const f of files) {
const path = join(inner, f);
mkdirSync(join(path, '..'), { recursive: true });
- writeFileSync(path, `#!/bin/sh\necho ${f}\n`, { mode: 0o755 });
+ writeFileSync(path, `#!/bin/sh\necho ${label ?? f}\n`, { mode: 0o755 });
}
const tarPath = join(dir, `${innerDir}.tar.gz`);
execFileSync('tar', ['-czf', tarPath, '-C', treeRoot, innerDir]);
@@ -151,6 +161,122 @@ describe('ensureManagedRuntime', () => {
expect(found?.npxBin).toBe(runtime.npxBin);
});
+ test('stages the install beside the destination before downloading', async () => {
+ const stage = tmp();
+ const root = tmp();
+ const { bytes, sha } = buildTarball(stage, 'node-vTEST', ['bin/node', 'bin/npx']);
+ const baseFetch = makeFetch(bytes, sha);
+ let observedStagingDir: string | undefined;
+ const inspectingFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+ observedStagingDir = readdirSync(join(root, 'node')).find((name) =>
+ name.startsWith('.install-'),
+ );
+ return baseFetch(input, init);
+ }) as typeof fetch;
+
+ await ensureManagedRuntime('node', log, { root, fetchImpl: inspectingFetch });
+
+ expect(observedStagingDir).toBeDefined();
+ expect(readdirSync(join(root, 'node'))).not.toContain(observedStagingDir);
+ });
+
+ test('removes crash-orphaned staging directories on the next install', async () => {
+ const stage = tmp();
+ const root = tmp();
+ const staleDir = join(root, 'node', '.install-v24.18.0-orphaned');
+ mkdirSync(staleDir, { recursive: true });
+ writeFileSync(join(staleDir, 'partial-archive'), 'partial');
+ const staleTime = new Date(Date.now() - 25 * 60 * 60 * 1_000);
+ utimesSync(staleDir, staleTime, staleTime);
+ const { bytes, sha } = buildTarball(stage, 'node-vTEST', ['bin/node', 'bin/npx']);
+
+ await ensureManagedRuntime('node', log, { root, fetchImpl: makeFetch(bytes, sha) });
+
+ expect(existsSync(staleDir)).toBe(false);
+ });
+
+ test('concurrent installers adopt the first completed runtime', async () => {
+ const firstStage = tmp();
+ const secondStage = tmp();
+ const root = tmp();
+ const first = buildTarball(firstStage, 'node-vFIRST', ['bin/node', 'bin/npx'], 'first');
+ const second = buildTarball(secondStage, 'node-vSECOND', ['bin/node', 'bin/npx'], 'second');
+ let arrivals = 0;
+ let releaseCommit!: () => void;
+ const commitGate = new Promise<void>((resolve) => {
+ releaseCommit = resolve;
+ });
+ const beforeCommit = async () => {
+ arrivals += 1;
+ if (arrivals === 2) releaseCommit();
+ await commitGate;
+ };
+ const installAndReadLauncher = async (archive: typeof first) => {
+ const runtime = await ensureManagedRuntime('node', log, {
+ root,
+ fetchImpl: makeFetch(archive.bytes, archive.sha),
+ beforeCommit,
+ });
+ if (runtime.kind !== 'node') throw new Error('unreachable');
+ return readFileSync(runtime.npxBin, 'utf8');
+ };
+
+ const launchers = await Promise.all([
+ installAndReadLauncher(first),
+ installAndReadLauncher(second),
+ ]);
+
+ expect(arrivals).toBe(2);
+ expect(launchers[0]).toBe(launchers[1]);
+ expect(await findManagedRuntime('node', root)).not.toBeNull();
+ });
+
+ test('adopts a completed runtime when the commit lock times out', async () => {
+ const stage = tmp();
+ const root = tmp();
+ const versionDir = join(root, 'node', describeRuntime('node').version);
+ const { bytes, sha } = buildTarball(stage, 'node-vTEST', ['bin/node', 'bin/npx']);
+
+ const runtime = await ensureManagedRuntime('node', log, {
+ root,
+ fetchImpl: makeFetch(bytes, sha),
+ commitLockTimeoutMs: 100,
+ beforeCommit: async () => {
+ const binDir = join(versionDir, 'winner', 'bin');
+ mkdirSync(binDir, { recursive: true });
+ writeFileSync(join(binDir, 'npx'), '#!/bin/sh\n', { mode: 0o755 });
+ writeFileSync(`${versionDir}.install.lock`, 'held');
+ const future = new Date(Date.now() + 60_000);
+ utimesSync(`${versionDir}.install.lock`, future, future);
+ },
+ });
+
+ expect(runtime.kind).toBe('node');
+ if (runtime.kind !== 'node') throw new Error('unreachable');
+ expect(runtime.npxBin).toBe(join(versionDir, 'winner', 'bin', 'npx'));
+ });
+
+ test('throws when the commit lock times out without an installed winner', async () => {
+ const stage = tmp();
+ const root = tmp();
+ const versionDir = join(root, 'node', describeRuntime('node').version);
+ const { bytes, sha } = buildTarball(stage, 'node-vTEST', ['bin/node', 'bin/npx']);
+
+ const error = await ensureManagedRuntime('node', log, {
+ root,
+ fetchImpl: makeFetch(bytes, sha),
+ commitLockTimeoutMs: 100,
+ beforeCommit: async () => {
+ writeFileSync(`${versionDir}.install.lock`, 'held');
+ const future = new Date(Date.now() + 60_000);
+ utimesSync(`${versionDir}.install.lock`, future, future);
+ },
+ }).catch((err: unknown) => err);
+
+ expect(error).toBeInstanceOf(RuntimeInstallError);
+ expect(error).toHaveProperty('message', expect.stringContaining('Could not acquire file lock'));
+ });
+
test('downloads and installs uv via its per-asset .sha256', async () => {
const stage = tmp();
const root = tmp();
diff --git a/packages/server/src/acp/managed-runtime.ts b/packages/server/src/acp/managed-runtime.ts
index 537c83ff2..17866fa5f 100644
--- a/packages/server/src/acp/managed-runtime.ts
+++ b/packages/server/src/acp/managed-runtime.ts
@@ -26,10 +26,12 @@
* agent path via `archive.ts`.
*/
+import { randomUUID } from 'node:crypto';
import { access, constants, readdir, stat } from 'node:fs/promises';
-import { arch, homedir, platform, tmpdir } from 'node:os';
+import { arch, homedir, platform } from 'node:os';
import { dirname, join } from 'node:path';
import { OK_DIR } from '@inkeep/open-knowledge-core';
+import { FileLockTimeoutError, withFileLock } from '@inkeep/open-knowledge-core/server';
import { tracedMkdir, tracedRename, tracedRm, tracedWriteFile } from '../fs-traced.ts';
import type { PinoLogger } from '../logger.ts';
import {
@@ -58,6 +60,9 @@ const UV_RELEASE_BASE = 'https://github.com/astral-sh/uv/releases/download';
/** Approximate compressed download sizes (MB), for the consent prompt only. */
const APPROX_SIZE_MB: Record<ManagedRuntimeKind, number> = { node: 45, uv: 20 };
+const STALE_STAGING_AGE_MS = 24 * 60 * 60 * 1_000;
+const INSTALL_COMMIT_LOCK_TIMEOUT_MS = 60_000;
+
interface ManagedNode {
kind: 'node';
/** Prepended to PATH so `npx`/`npm` resolve their sibling `node`. */
@@ -272,6 +277,10 @@ export interface EnsureRuntimeOptions {
signal?: AbortSignal;
/** Test seam — defaults to global `fetch`. */
fetchImpl?: typeof fetch;
+ /** Test seam for synchronizing concurrent installers immediately before commit. */
+ beforeCommit?: () => Promise<void>;
+ /** Test seam — defaults to the production commit-lock timeout. */
+ commitLockTimeoutMs?: number;
}
export class RuntimeInstallError extends Error {
@@ -281,12 +290,46 @@ export class RuntimeInstallError extends Error {
}
}
+async function cleanupStaleStagingDirs(kindDir: string, log: PinoLogger): Promise<void> {
+ let entries: import('node:fs').Dirent[];
+ try {
+ entries = await readdir(kindDir, { withFileTypes: true });
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+ log.warn({ err }, '[managed-runtime] could not read staging dir for cleanup');
+ }
+ return;
+ }
+
+ const cutoff = Date.now() - STALE_STAGING_AGE_MS;
+ for (const entry of entries) {
+ if (!entry.isDirectory() || !entry.name.startsWith('.install-')) continue;
+ const path = join(kindDir, entry.name);
+ try {
+ if ((await stat(path)).mtimeMs >= cutoff) continue;
+ await tracedRm(path, { recursive: true, force: true });
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') continue;
+ log.warn({ err }, '[managed-runtime] stale staging cleanup failed');
+ }
+ }
+}
+
+export async function cleanupManagedRuntimeStaging(
+ kind: ManagedRuntimeKind,
+ log: PinoLogger,
+ root: string = defaultRuntimeRoot(),
+): Promise<void> {
+ await cleanupStaleStagingDirs(join(root, kind), log);
+}
+
/**
* Download + verify + install a managed runtime once per pinned version;
* later launches reuse the extracted tree. Verified against the publisher's
- * SHA-256 before it is trusted. Extraction lands in a temp dir and is renamed
- * into place so a crash mid-install never leaves a half-tree that the
- * fast-path check would accept.
+ * SHA-256 before it is trusted. Extraction lands beside the destination and
+ * is renamed into place so the atomic commit stays on one filesystem and a
+ * crash mid-install never leaves a half-tree that the fast-path check would
+ * accept.
*
* The CALLER is responsible for consent — this only runs once told to.
*/
@@ -296,16 +339,25 @@ export async function ensureManagedRuntime(
opts: EnsureRuntimeOptions = {},
): Promise<ManagedRuntime> {
const root = opts.root ?? defaultRuntimeRoot();
+ const versionDir = join(root, kind, sanitizeSegment(versionOf(kind)));
+ const kindDir = dirname(versionDir);
const existing = await findManagedRuntime(kind, root);
- if (existing !== null) return existing;
+ if (existing !== null) {
+ await cleanupStaleStagingDirs(kindDir, log);
+ return existing;
+ }
const spec = artifactFor(kind);
if (spec === null) {
throw new RuntimeInstallError(`no ${kind} build for ${platform()}-${arch()}`);
}
- const versionDir = join(root, kind, sanitizeSegment(versionOf(kind)));
- const stagingDir = join(tmpdir(), `ok-runtime-${kind}-${process.pid}-${Date.now()}`);
+ await tracedMkdir(kindDir, { recursive: true });
+ await cleanupStaleStagingDirs(kindDir, log);
+ const stagingDir = join(
+ kindDir,
+ `.install-${sanitizeSegment(versionOf(kind))}-${process.pid}-${randomUUID()}`,
+ );
await tracedMkdir(stagingDir, { recursive: true });
const archivePath = join(stagingDir, spec.archiveName);
log.info(
@@ -344,16 +396,47 @@ export async function ensureManagedRuntime(
// drop our copy rather than racing on the rename.
const raced = await findManagedRuntime(kind, root);
if (raced !== null) return raced;
-
- await tracedMkdir(join(root, kind), { recursive: true });
- await tracedRm(versionDir, { recursive: true, force: true });
- await tracedRename(extractDir, versionDir);
- log.info({ kind, version: versionOf(kind), versionDir }, '[managed-runtime] runtime installed');
- const installed = await findManagedRuntime(kind, root);
- if (installed === null) {
- throw new RuntimeInstallError(`installed ${kind} runtime not found after extract`);
+ await opts.beforeCommit?.();
+
+ try {
+ return await withFileLock(
+ `${versionDir}.install.lock`,
+ async () => {
+ // Only the commit is serialized: concurrent launches may download in
+ // parallel, but none can remove a complete tree installed by another.
+ const winner = await findManagedRuntime(kind, root);
+ if (winner !== null) return winner;
+
+ await tracedRm(versionDir, { recursive: true, force: true });
+ await tracedRename(extractDir, versionDir);
+ log.info(
+ { kind, version: versionOf(kind), versionDir },
+ '[managed-runtime] runtime installed',
+ );
+ const installed = await findManagedRuntime(kind, root);
+ if (installed === null) {
+ throw new RuntimeInstallError(`installed ${kind} runtime not found after extract`);
+ }
+ return installed;
+ },
+ {
+ timeoutMs: opts.commitLockTimeoutMs ?? INSTALL_COMMIT_LOCK_TIMEOUT_MS,
+ onWarn: (message, context) => {
+ log.warn({ ...context, kind }, `[managed-runtime] ${message}`);
+ },
+ },
+ );
+ } catch (err) {
+ if (err instanceof FileLockTimeoutError) {
+ const winner = await findManagedRuntime(kind, root);
+ if (winner !== null) return winner;
+ log.warn(
+ { kind, lockPath: err.lockPath, timeoutMs: err.timeoutMs },
+ '[managed-runtime] commit lock timed out with no winner installed',
+ );
+ }
+ throw err;
}
- return installed;
} catch (err) {
if (err instanceof RuntimeInstallError) throw err;
throw new RuntimeInstallError(
diff --git a/packages/server/src/acp/thread-manager.ts b/packages/server/src/acp/thread-manager.ts
index 146d2d526..7f459d2ba 100644
--- a/packages/server/src/acp/thread-manager.ts
+++ b/packages/server/src/acp/thread-manager.ts
@@ -81,6 +81,7 @@ import {
terminateAgentTree,
} from './launch.ts';
import {
+ cleanupManagedRuntimeStaging,
describeRuntime,
ensureManagedRuntime,
findManagedRuntime,
@@ -814,6 +815,7 @@ export class AcpThreadManager {
runtimeKind: ManagedRuntimeKind,
): Promise<ManagedRuntime | null> {
const root = this.opts.runtimeInstall?.root;
+ await cleanupManagedRuntimeStaging(runtimeKind, this.opts.log, root);
const existing = await findManagedRuntime(runtimeKind, root).catch(() => null);
if (existing !== null) return existing;