Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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;