fraim 2.0.360 → 2.0.361-next.0

package/dist/src/cli/utils/managed-agent-paths.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveMachinePathCached = exports.expandWindowsEnvRefs = exports.parseRegQueryPathValue = void 0;
 exports.getManagedNodeRoot = getManagedNodeRoot;
+exports.isOwnedManagedAgentTarget = isOwnedManagedAgentTarget;
 exports.getPortableNodeBinPath = getPortableNodeBinPath;
 exports.getManagedAgentBinDirs = getManagedAgentBinDirs;
 exports.stripProjectLocalNodeBinDirs = stripProjectLocalNodeBinDirs;
@@ -18,10 +19,13 @@ exports.__setLoginShellPathResolverForTests = __setLoginShellPathResolverForTest
 exports.resolveLoginShellPathCached = resolveLoginShellPathCached;
 exports.__clearLoginShellPathCacheForTests = __clearLoginShellPathCacheForTests;
 exports.invalidateMachinePathCache = invalidateMachinePathCache;
+exports.invalidateAgentCommandRecovery = invalidateAgentCommandRecovery;
 exports.__setMachinePathResolverForTests = __setMachinePathResolverForTests;
 exports.buildRecoveredSystemPath = buildRecoveredSystemPath;
+exports.buildRecoveredAgentPathAsync = buildRecoveredAgentPathAsync;
 exports.buildRecoveredAgentPath = buildRecoveredAgentPath;
 exports.versionFromProbeOutput = versionFromProbeOutput;
+const operation_scope_1 = require("./operation-scope");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
@@ -36,6 +40,18 @@ Object.defineProperty(exports, "resolveMachinePathCached", { enumerable: true, g
 function getManagedNodeRoot() {
     return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
 }
+/** Repair authority requires the real launcher to remain under the real FRAIM Node root. */
+function isOwnedManagedAgentTarget(target) {
+    try {
+        const root = fs_1.default.realpathSync(getManagedNodeRoot());
+        const real = fs_1.default.realpathSync(target);
+        const relative = path_1.default.relative(root, real);
+        return Boolean(relative && !relative.startsWith('..') && !path_1.default.isAbsolute(relative));
+    }
+    catch {
+        return false;
+    }
+}
 function getPortableNodeBinPath(platform = process.platform, arch = process.arch) {
     const nodeRoot = getManagedNodeRoot();
     if (platform === 'win32') {
@@ -228,9 +244,7 @@ function buildPathWithManagedAgentBins(basePath) {
 // win32 rather than attempting a login-shell equivalent that doesn't exist.
 const LOGIN_SHELL_PATH_TIMEOUT_MS = 3000;
 const LOGIN_SHELL_PATH_CACHE_TTL_MS = 60_000;
-function defaultResolveLoginShellPath() {
-    if (process.platform === 'win32')
-        return null;
+function loginShellInvocation() {
     const shell = process.env.SHELL || '/bin/bash';
     const marker = `__fraim_1256_shell_path_${process.pid}__`;
     // `-lc`, not `-ilc`: login + command, deliberately NOT interactive (SOC 2 CC6.1 / ISO 27001
@@ -248,6 +262,20 @@ function defaultResolveLoginShellPath() {
         'echo',
         `echo "${marker}"`,
     ].join('; ');
+    return { shell, marker, script };
+}
+function parseLoginShellOutput(output, marker) {
+    const first = output.indexOf(marker);
+    if (first < 0)
+        return null;
+    const rest = output.slice(first + marker.length);
+    const end = rest.indexOf(marker);
+    return (end < 0 ? rest : rest.slice(0, end)).trim() || null;
+}
+function defaultResolveLoginShellPath() {
+    if (process.platform === 'win32')
+        return null;
+    const { shell, marker, script } = loginShellInvocation();
     try {
         const result = (0, child_process_1.spawnSync)(shell, ['-lc', script], {
             encoding: 'utf8',
@@ -259,13 +287,7 @@ function defaultResolveLoginShellPath() {
         if (result.status !== 0 || result.error)
             return null;
         const output = result.stdout || '';
-        const firstIdx = output.indexOf(marker);
-        if (firstIdx === -1)
-            return null;
-        const afterFirst = output.slice(firstIdx + marker.length);
-        const secondIdx = afterFirst.indexOf(marker);
-        const section = (secondIdx === -1 ? afterFirst : afterFirst.slice(0, secondIdx)).trim();
-        return section || null;
+        return parseLoginShellOutput(output, marker);
     }
     catch {
         return null;
@@ -312,6 +334,7 @@ function resolveLoginShellPathCached() {
 }
 /** Test seam only. Clears the memoized login-shell PATH so the next call recomputes. */
 function __clearLoginShellPathCacheForTests() {
+    recoveryGeneration++;
     cachedLoginShellPath = undefined;
     cachedLoginShellPathAtMs = 0;
     cachedNpmGlobalBinDirsForRecovery.clear();
@@ -392,47 +415,78 @@ function resolveNpmGlobalBinDirsCached(basePath) {
 function invalidateMachinePathCache() {
     (0, machine_path_1.clearMachinePathCache)();
     cachedNpmGlobalBinDirsForRecovery.clear();
+    recoveryGeneration++;
+}
+/** Refresh all discovery inputs after an explicit installation or setup retry. */
+function invalidateAgentCommandRecovery() {
+    invalidateMachinePathCache();
+    cachedLoginShellPath = undefined;
+    cachedLoginShellPathAtMs = 0;
+    recoveryGeneration++;
 }
 function __setMachinePathResolverForTests(resolver) {
     (0, machine_path_1.setMachinePathResolver)(resolver);
     cachedNpmGlobalBinDirsForRecovery.clear();
 }
+function composeRecoveredSystemInputs(basePath, machinePath, loginPath) {
+    const inherited = stripProjectLocalNodeBinDirs(stripManagedAgentBinDirsFromPath(basePath));
+    const machine = machinePath ? appendBinDirsToPath(machinePath, inherited.split(path_1.default.delimiter).filter(Boolean)) : inherited;
+    const login = loginPath ? appendBinDirsToPath(machine, loginPath.split(path_1.default.delimiter).filter(Boolean)) : machine;
+    return stripManagedAgentBinDirsFromPath(stripProjectLocalNodeBinDirs(login));
+}
 function buildRecoveredSystemPath(basePath) {
-    const withoutManaged = stripManagedAgentBinDirsFromPath(basePath);
-    const inherited = stripProjectLocalNodeBinDirs(withoutManaged);
-    // Issue #1748 (win32 only): the PATH the machine reports right now. This process may
-    // predate the user's install, so its own inherited PATH is a stale copy of the same
-    // registry. Machine entries go FIRST, because entries present in both would otherwise
-    // keep their stale relative position and an entry existing only on the machine PATH
-    // would land last, which is how resolution picked a different install than the one a
-    // fresh terminal resolves.
-    //
-    // Deliberately NOT applied to the POSIX login-shell tier below, which keeps its
-    // original append semantics. The staleness this reorders around is a Windows
-    // registry-snapshot problem; on POSIX a GUI-launched process has a minimal inherited
-    // PATH that carries no competing entry to out-order, so appending already resolves it.
-    // Promoting login-shell entries above inherited ones there would let the login shell
-    // silently override a directory a wrapper deliberately prepended for that launch,
-    // which is the same class of "wrong binary launched" bug this change exists to fix.
-    const machinePath = process.platform === 'win32' ? (0, machine_path_1.resolveMachinePathCached)() : null;
-    const machineEntries = machinePath ? machinePath.split(path_1.default.delimiter).filter(Boolean) : [];
-    const withMachine = machineEntries.length > 0
-        ? appendBinDirsToPath(machineEntries.join(path_1.default.delimiter), inherited.split(path_1.default.delimiter).filter(Boolean))
-        : inherited;
-    const loginShellPath = resolveLoginShellPathCached();
-    const loginShellEntries = loginShellPath ? loginShellPath.split(path_1.default.delimiter).filter(Boolean) : [];
-    const withLoginShell = loginShellEntries.length > 0
-        ? appendBinDirsToPath(withMachine, loginShellEntries)
-        : withMachine;
-    const cleaned = stripProjectLocalNodeBinDirs(withLoginShell);
-    // Strip managed dirs a second time. FRAIM registers its own directory on the machine
-    // PATH at install (persistShellPath), so the recovered PATH legitimately contains it,
-    // but this helper's contract is "what the real machine provides, excluding FRAIM's
-    // bundled copy" - which is what lets callers tell a user install apart from FRAIM's
-    // fallback. Without this the machine read would smuggle the managed dir back in.
-    const systemOnly = stripManagedAgentBinDirsFromPath(cleaned);
-    const npmGlobalBinDirs = resolveNpmGlobalBinDirsCached(systemOnly);
-    return appendBinDirsToPath(systemOnly, npmGlobalBinDirs);
+    const system = composeRecoveredSystemInputs(basePath, process.platform === 'win32' ? (0, machine_path_1.resolveMachinePathCached)() : null, resolveLoginShellPathCached());
+    return appendBinDirsToPath(system, resolveNpmGlobalBinDirsCached(system));
+}
+let recoveryGeneration = 0;
+async function resolveLoginShellPathCachedAsync(signal) {
+    signal.throwIfAborted();
+    if (cachedLoginShellPath !== undefined && Date.now() - cachedLoginShellPathAtMs < LOGIN_SHELL_PATH_CACHE_TTL_MS)
+        return cachedLoginShellPath;
+    if (loginShellPathResolverOverride || process.platform === 'win32')
+        return resolveLoginShellPathCached();
+    const generation = recoveryGeneration;
+    const { captureAgentCommand } = require('./agent-command-probe');
+    const invocation = loginShellInvocation();
+    const output = await captureAgentCommand(invocation.shell, ['-lc', invocation.script], { env: { ...process.env }, signal, timeoutMs: LOGIN_SHELL_PATH_TIMEOUT_MS });
+    signal.throwIfAborted();
+    const value = output === null ? null : parseLoginShellOutput(output, invocation.marker);
+    if (generation === recoveryGeneration) {
+        cachedLoginShellPath = value;
+        cachedLoginShellPathAtMs = Date.now();
+        cachedNpmGlobalBinDirsForRecovery.clear();
+    }
+    return value;
+}
+const recoveredPaths = new operation_scope_1.SharedOperations();
+async function buildRecoveredAgentPathAsync(basePath, options = {}) {
+    const generation = recoveryGeneration;
+    const key = JSON.stringify([basePath ?? process.env.PATH, (0, script_sync_utils_1.getUserFraimDir)(), generation]);
+    return (0, operation_scope_1.withOperation)(options, 30000, signal => recoveredPaths.run(key, async (owner) => {
+        // All children settle before cancellation releases the recovery owner.
+        const results = await Promise.allSettled([(0, machine_path_1.resolveMachinePathCachedAsync)(owner), resolveLoginShellPathCachedAsync(owner)]);
+        owner.throwIfAborted();
+        for (const result of results)
+            if (result.status === 'rejected')
+                throw result.reason;
+        const [machine, login] = results.map(result => result.value);
+        const system = composeRecoveredSystemInputs(basePath, machine, login);
+        let dirs = cachedNpmGlobalBinDirsForRecovery.get(system);
+        if (!dirs) {
+            const { getSystemCommandPath } = require('../mcp/command-resolution');
+            const { captureAgentCommand } = require('./agent-command-probe');
+            const npm = getSystemCommandPath('npm', system);
+            const output = npm ? await captureAgentCommand(npm, ['prefix', '-g'], { env: { ...process.env, PATH: system, Path: system }, signal: owner, timeoutMs: 5000 }) : null;
+            owner.throwIfAborted();
+            dirs = output && path_1.default.isAbsolute(output.trim()) ? getNpmGlobalBinDirsFromPrefix(output.trim()) : [];
+            if (generation === recoveryGeneration) {
+                if (cachedNpmGlobalBinDirsForRecovery.size >= NPM_GLOBAL_RECOVERY_CACHE_MAX_ENTRIES)
+                    cachedNpmGlobalBinDirsForRecovery.clear();
+                cachedNpmGlobalBinDirsForRecovery.set(system, dirs);
+            }
+        }
+        return appendBinDirsToPath(appendBinDirsToPath(system, dirs), getManagedAgentBinDirs());
+    }, signal));
 }
 function buildRecoveredAgentPath(basePath) {
     return appendBinDirsToPath(buildRecoveredSystemPath(basePath), getManagedAgentBinDirs());

package/dist/src/cli/utils/managed-node-runtime.js

@@ -14,8 +14,12 @@ exports.ensureManagedNpm = ensureManagedNpm;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
-const https_1 = __importDefault(require("https"));
+const promises_1 = require("node:stream/promises");
+const node_stream_1 = require("node:stream");
+const node_worker_threads_1 = require("node:worker_threads");
+const operation_scope_1 = require("./operation-scope");
 const crypto_1 = __importDefault(require("crypto"));
+const agent_command_probe_1 = require("./agent-command-probe");
 const managed_agent_paths_1 = require("./managed-agent-paths");
 // Desktop-only users may have no working system npm/npx. Installer setup, Hub
 // materialization, first-run setup, and agent installation share this managed
@@ -58,7 +62,12 @@ function findExecutableOnPath(name, pathValue = process.env.PATH) {
 }
 /** Whether `dir` already has a real, runnable node+npm — any version; this function's job is "a working npm", not "this exact one". */
 function hasWorkingNodeAndNpm(dir, platform = process.platform) {
-    return fs_1.default.existsSync(path_1.default.join(dir, npmExecutableName(platform))) && fs_1.default.existsSync(path_1.default.join(dir, nodeExecutableName(platform)));
+    if (platform !== process.platform)
+        return false;
+    const runtimePath = [dir, process.env.SystemRoot ? path_1.default.join(process.env.SystemRoot, 'System32') : '/usr/bin'].join(path_1.default.delimiter);
+    const env = { ...process.env, PATH: runtimePath, Path: runtimePath };
+    return Boolean((0, agent_command_probe_1.selectAgentCommandSync)(path_1.default.join(dir, nodeExecutableName(platform)), { env })
+        && (0, agent_command_probe_1.selectAgentCommandSync)(path_1.default.join(dir, npmExecutableName(platform)), { env }));
 }
 function nodeBinDir(root, platform) {
     return platform === 'win32' ? root : path_1.default.join(root, 'bin');
@@ -108,55 +117,38 @@ function nodeArchiveFileName(request) {
 function nodeDistBaseUrl(version) {
     return `https://nodejs.org/dist/v${version}`;
 }
-function httpsGetBuffer(url) {
-    return new Promise((resolve, reject) => {
-        https_1.default.get(url, { headers: { 'user-agent': 'fraim-hub-managed-node-runtime' } }, (res) => {
-            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-                httpsGetBuffer(res.headers.location).then(resolve, reject);
-                return;
-            }
-            if (res.statusCode !== 200) {
-                res.resume();
-                reject(new Error(`GET ${url} failed: HTTP ${res.statusCode}`));
-                return;
-            }
-            const chunks = [];
-            res.on('data', (chunk) => chunks.push(chunk));
-            res.on('end', () => resolve(Buffer.concat(chunks)));
-            res.on('error', reject);
-        }).on('error', reject);
-    });
+async function httpsGetBuffer(url, signal) {
+    const response = await fetch(url, { signal, headers: { 'user-agent': 'fraim-hub-managed-node-runtime' } });
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error('Node release checksum download failed');
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of node_stream_1.Readable.fromWeb(response.body)) {
+        size += chunk.length;
+        if (size > 1024 * 1024)
+            throw new Error('Node checksum response exceeded its limit');
+        chunks.push(chunk);
+    }
+    signal?.throwIfAborted();
+    return Buffer.concat(chunks);
 }
-function httpsDownloadToFile(url, destPath) {
-    return new Promise((resolve, reject) => {
-        const file = fs_1.default.createWriteStream(destPath);
-        https_1.default.get(url, { headers: { 'user-agent': 'fraim-hub-managed-node-runtime' } }, (res) => {
-            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-                file.close();
-                httpsDownloadToFile(res.headers.location, destPath).then(resolve, reject);
-                return;
-            }
-            if (res.statusCode !== 200) {
-                res.resume();
-                file.close();
-                reject(new Error(`GET ${url} failed: HTTP ${res.statusCode}`));
-                return;
-            }
-            res.pipe(file);
-            file.on('finish', () => file.close(() => resolve()));
-        }).on('error', (err) => {
-            file.close();
-            reject(err);
-        });
-    });
+async function httpsDownloadToFile(url, destPath, signal) {
+    const response = await fetch(url, { signal, headers: { 'user-agent': 'fraim-hub-managed-node-runtime' } });
+    if (!response.ok || !response.body) {
+        await response.body?.cancel();
+        throw new Error('Node runtime download failed');
+    }
+    await (0, promises_1.pipeline)(node_stream_1.Readable.fromWeb(response.body), fs_1.default.createWriteStream(destPath), { signal });
 }
 /**
  * Verify `filePath` against the sha256 line naming `fileName` in the release's own
  * `SHASUMS256.txt` — the same integrity check `@electron/get` performs for Electron zips
  * (`electron-dist.ts`), applied to Node's own equivalent publishing convention.
  */
-async function verifyNodeArchiveChecksum(filePath, fileName, version) {
-    const shasums = (await httpsGetBuffer(`${nodeDistBaseUrl(version)}/SHASUMS256.txt`)).toString('utf8');
+async function verifyNodeArchiveChecksum(filePath, fileName, version, signal) {
+    const shasums = (await httpsGetBuffer(`${nodeDistBaseUrl(version)}/SHASUMS256.txt`, signal)).toString('utf8');
     const line = shasums.split('\n').find((entry) => entry.trim().endsWith(fileName));
     if (!line) {
         throw new Error(`SHASUMS256.txt for Node v${version} has no entry for ${fileName}; refusing to trust an unverified download`);
@@ -171,9 +163,9 @@ const defaultDownloadNodeArchive = async (request) => {
     const fileName = nodeArchiveFileName(request);
     const url = `${nodeDistBaseUrl(request.version)}/${fileName}`;
     const tempPath = path_1.default.join(os_1.default.tmpdir(), `fraim-managed-node-${process.pid}-${Date.now()}-${fileName}`);
-    await httpsDownloadToFile(url, tempPath);
     try {
-        await verifyNodeArchiveChecksum(tempPath, fileName, request.version);
+        await httpsDownloadToFile(url, tempPath, request.signal);
+        await verifyNodeArchiveChecksum(tempPath, fileName, request.version, request.signal);
     }
     catch (error) {
         fs_1.default.rmSync(tempPath, { force: true });
@@ -182,16 +174,34 @@ const defaultDownloadNodeArchive = async (request) => {
     return tempPath;
 };
 const defaultExtractNodeArchive = async (archivePath, destDir, request) => {
-    if (request.platform === 'win32') {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const extract = require('extract-zip');
-        await extract(archivePath, { dir: destDir });
-    }
-    else {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const tar = require('tar');
-        await tar.x({ file: archivePath, cwd: destDir });
-    }
+    request.signal?.throwIfAborted();
+    // Extraction owns file handles. A worker lets cancellation wait for their closure
+    // before removing the staging directory; a timer racing an extraction cannot do that.
+    await new Promise((resolve, reject) => {
+        const zip = request.platform === 'win32';
+        const worker = new node_worker_threads_1.Worker(`
+      const { workerData } = require('node:worker_threads');
+      const extractor = require(workerData.modulePath);
+      Promise.resolve(workerData.zip ? extractor(workerData.archivePath, { dir: workerData.destDir })
+        : extractor.x({ file: workerData.archivePath, cwd: workerData.destDir }))
+        .catch(error => { throw error; });
+    `, { eval: true, workerData: { zip, archivePath, destDir, modulePath: require.resolve(zip ? 'extract-zip' : 'tar') } });
+        let failure;
+        const abort = () => { void worker.terminate(); };
+        request.signal?.addEventListener('abort', abort, { once: true });
+        worker.once('error', error => { failure = error; });
+        worker.once('exit', code => {
+            request.signal?.removeEventListener('abort', abort);
+            if (request.signal?.aborted)
+                reject(request.signal.reason);
+            else if (failure || code !== 0)
+                reject(failure || new Error('Node extraction failed'));
+            else
+                resolve();
+        });
+        if (request.signal?.aborted)
+            abort();
+    });
 };
 /**
  * Download and extract Node v`request.version` into `nodeRoot/<node-vX.Y.Z-platform-arch>/`,
@@ -211,24 +221,27 @@ async function downloadAndPromoteVersionedNodeDir(args) {
         // tar requires an existing cwd. Each invocation owns a separate directory,
         // including simultaneous requests within the same process.
         stagingDir = fs_1.default.mkdtempSync(`${destDir}.staging-${process.pid}-`);
+        request.signal?.throwIfAborted();
         await extractArchive(archivePath, stagingDir, request);
+        request.signal?.throwIfAborted();
         // Official tar and ZIP archives preserve their top-level distribution folder.
         // Also accept a flattened root from a supplied extractor.
         const nestedCandidate = path_1.default.join(stagingDir, nodeVersionedDirName(request));
         const extractedRoot = fs_1.default.existsSync(nestedCandidate) ? nestedCandidate : stagingDir;
         fs_1.default.writeFileSync(path_1.default.join(extractedRoot, 'fraim-managed-node-version'), request.version, 'utf8');
-        if (!isManagedNodeVersionComplete(extractedRoot, request.version, request.platform)) {
+        if (!(await hasWorkingNodeAndNpmAsync(nodeBinDir(extractedRoot, request.platform), request.platform, request.signal))) {
             throw new Error(`extracted Node v${request.version} is missing ${npmExecutableName(request.platform)}/${nodeExecutableName(request.platform)}; refusing to promote an incomplete install`);
         }
         // A concurrent launch may have finished downloading the same version already; the winner
         // keeps its copy rather than being clobbered by this one.
-        if (!isManagedNodeVersionComplete(destDir, request.version, request.platform)) {
+        if (!(await hasWorkingNodeAndNpmAsync(nodeBinDir(destDir, request.platform), request.platform, request.signal))) {
+            request.signal?.throwIfAborted();
             fs_1.default.rmSync(destDir, { recursive: true, force: true });
             try {
                 fs_1.default.renameSync(extractedRoot, destDir);
             }
             catch (error) {
-                if (!isManagedNodeVersionComplete(destDir, request.version, request.platform))
+                if (!(await hasWorkingNodeAndNpmAsync(nodeBinDir(destDir, request.platform), request.platform, request.signal)))
                     throw error;
             }
         }
@@ -248,18 +261,24 @@ async function downloadAndPromoteVersionedNodeDir(args) {
  * this launch," not a hard failure — never for "nothing found," which falls through to download.
  */
 async function ensureManagedNpm(options = {}) {
+    return (0, operation_scope_1.withOperation)(options, 90000, signal => ensureManagedNpmCore({ ...options, signal }));
+}
+async function ensureManagedNpmCore(options) {
     const version = options.version ?? exports.MANAGED_NODE_VERSION;
     const platform = options.platform ?? process.platform;
     const arch = options.arch ?? process.arch;
-    const systemNpm = findExecutableOnPath(npmExecutableName(platform), options.systemPath ?? process.env.PATH);
-    if (systemNpm) {
-        return { npmPath: systemNpm, binDir: path_1.default.dirname(systemNpm), source: 'system' };
+    const systemPath = options.systemPath ?? process.env.PATH ?? '';
+    const env = { ...process.env, PATH: systemPath, Path: systemPath };
+    const systemNpm = platform === process.platform ? await (0, agent_command_probe_1.selectAgentCommand)('npm', { env, signal: options.signal }) : null;
+    if (systemNpm && await (0, agent_command_probe_1.selectAgentCommand)('node', { env, signal: options.signal })) {
+        return { npmPath: systemNpm.target, binDir: path_1.default.dirname(systemNpm.target), source: 'system' };
     }
     const existingBinDir = (0, managed_agent_paths_1.getPortableNodeBinPath)(platform, arch);
-    if (hasWorkingNodeAndNpm(existingBinDir, platform)) {
+    options.signal?.throwIfAborted();
+    if (await hasWorkingNodeAndNpmAsync(existingBinDir, platform, options.signal)) {
         return { npmPath: path_1.default.join(existingBinDir, npmExecutableName(platform)), binDir: existingBinDir, source: 'managed-existing' };
     }
-    const request = { version, platform, arch };
+    const request = { version, platform, arch, signal: options.signal };
     options.onProgress?.('Preparing FRAIM\'s bundled Node.js runtime (one-time, ~30MB)...');
     const binDir = await downloadAndPromoteVersionedNodeDir({
         nodeRoot: (0, managed_agent_paths_1.getManagedNodeRoot)(),
@@ -270,3 +289,14 @@ async function ensureManagedNpm(options = {}) {
     options.onProgress?.('FRAIM Node.js runtime ready.');
     return { npmPath: path_1.default.join(binDir, npmExecutableName(platform)), binDir, source: 'managed-downloaded' };
 }
+async function hasWorkingNodeAndNpmAsync(dir, platform, signal) {
+    signal?.throwIfAborted();
+    if (platform !== process.platform)
+        return false;
+    const runtimePath = [dir, process.env.SystemRoot ? path_1.default.join(process.env.SystemRoot, 'System32') : '/usr/bin'].join(path_1.default.delimiter);
+    const env = { ...process.env, PATH: runtimePath, Path: runtimePath };
+    const working = Boolean(await (0, agent_command_probe_1.selectAgentCommand)(path_1.default.join(dir, nodeExecutableName(platform)), { env, signal })
+        && await (0, agent_command_probe_1.selectAgentCommand)(path_1.default.join(dir, npmExecutableName(platform)), { env, signal }));
+    signal?.throwIfAborted();
+    return working;
+}

package/dist/src/cli/utils/operation-scope.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SharedOperations = void 0;
+exports.cancellationError = cancellationError;
+exports.withOperation = withOperation;
+function cancellationError(signal) {
+    return signal?.reason instanceof Error ? signal.reason : new Error('Operation cancelled');
+}
+async function withOperation(options, defaultTimeoutMs, task) {
+    options.signal?.throwIfAborted();
+    const owner = new AbortController();
+    const abort = () => owner.abort(cancellationError(options.signal));
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => owner.abort(new Error('Operation exceeded its deadline')), options.timeoutMs ?? defaultTimeoutMs);
+    if ((options.timeoutMs ?? defaultTimeoutMs) <= 0)
+        owner.abort(new Error('Operation exceeded its deadline'));
+    try {
+        owner.signal.throwIfAborted();
+        const value = await task(owner.signal);
+        owner.signal.throwIfAborted();
+        return value;
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', abort);
+    }
+}
+/** Subscribers own a lease. Only the last cancellation terminates shared work. */
+class SharedOperations {
+    constructor() {
+        this.active = new Map();
+    }
+    async run(key, task, signal) {
+        signal?.throwIfAborted();
+        let work = this.active.get(key);
+        if (work?.controller.signal.aborted) {
+            // Do not overlap a replacement with the preceding owner's cleanup.
+            await work.promise.catch(() => undefined);
+            return this.run(key, task, signal);
+        }
+        if (!work) {
+            const controller = new AbortController();
+            work = { controller, subscribers: 0, promise: undefined };
+            const entry = work;
+            // Invoke synchronously, as existing coalescer callers expect.
+            try {
+                work.promise = task(controller.signal);
+            }
+            catch (error) {
+                work.promise = Promise.reject(error);
+            }
+            work.promise = work.promise.finally(() => { if (this.active.get(key) === entry)
+                this.active.delete(key); });
+            this.active.set(key, work);
+        }
+        const entry = work;
+        entry.subscribers++;
+        return new Promise((resolve, reject) => {
+            let released = false;
+            const release = () => {
+                if (released)
+                    return false;
+                released = true;
+                entry.subscribers--;
+                signal?.removeEventListener('abort', abort);
+                return true;
+            };
+            const abort = () => {
+                if (!release())
+                    return;
+                const error = cancellationError(signal);
+                if (entry.subscribers === 0) {
+                    entry.controller.abort(error);
+                    entry.promise.then(() => reject(error), reject);
+                }
+                else
+                    reject(error);
+            };
+            signal?.addEventListener('abort', abort, { once: true });
+            entry.promise.then(value => { if (release())
+                resolve(value); }, error => { if (release())
+                reject(error); });
+            if (signal?.aborted)
+                abort();
+        });
+    }
+}
+exports.SharedOperations = SharedOperations;

package/dist/src/cli/utils/pack-home.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePackArtifactPaths = resolvePackArtifactPaths;
 exports.packsDir = packsDir;
 exports.defaultCloneDir = defaultCloneDir;
 exports.resolvePackHome = resolvePackHome;
@@ -36,6 +37,7 @@ const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const artifact_paths_1 = require("../../../registry/scripts/artifact-paths");
+const local_runtime_1 = require("../../../registry/scripts/learning-usage/local-runtime");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const user_config_1 = require("./user-config");
 /**
@@ -48,6 +50,37 @@ const user_config_1 = require("./user-config");
 function absolutize(p) {
     return path_1.default.isAbsolute(p) ? p : path_1.default.resolve((0, project_fraim_paths_1.getUserFraimDirPath)(), p);
 }
+/**
+ * Resolve artifact paths for a home, reading artifact path overrides from the
+ * machine-level config (`~/.fraim/config.json`) for Manager and Org homes.
+ *
+ * For Manager/Org homes the config path (overrides) and the artifact root
+ * (storage location) are separate concerns: overrides always live in the
+ * machine-level config while artifacts resolve relative to the synced homeRoot.
+ * `resolveArtifactPaths` handles Project homes correctly on its own; this helper
+ * is only needed for Manager/Org to avoid reading a non-existent synced config.
+ */
+function resolvePackArtifactPaths(home) {
+    const layer = 'layer' in home ? home.layer : 'level' in home ? home.level.toLowerCase() : 'project';
+    if (layer === 'manager' || layer === 'org') {
+        const machineConfigPath = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'config.json');
+        // readJsonIfObject returns {} for ENOENT in strict mode; non-ENOENT errors propagate.
+        const machineConfig = (0, local_runtime_1.readJsonIfObject)(machineConfigPath, { strict: true });
+        const sectionKey = layer === 'manager' ? 'managerArtifactPaths' : 'orgArtifactPaths';
+        // Use property-presence check: an explicitly invalid value (false, null, "") must reach
+        // resolveArtifactPaths so it can be validated and rejected there, not silently replaced.
+        const artifactPaths = sectionKey in machineConfig
+            ? machineConfig[sectionKey]
+            : 'artifactPaths' in machineConfig
+                ? machineConfig.artifactPaths
+                : undefined;
+        return (0, artifact_paths_1.resolveArtifactPaths)(home.root, home.contentRoot, machineConfigPath, artifactPaths !== undefined ? { artifactPaths } : {});
+    }
+    // Project OwnerHome carries artifactRoot = <project> while root = <project>/fraim.
+    // Use artifactRoot when present so paths like docs/evidence resolve relative to the project root.
+    const homeRoot = ('artifactRoot' in home && home.artifactRoot !== undefined) ? home.artifactRoot : home.root;
+    return (0, artifact_paths_1.resolveArtifactPaths)(homeRoot, home.contentRoot);
+}
 /** FRAIM-managed directory for pack copies that have no user-chosen location. */
 function packsDir() {
     return path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'packs');
@@ -86,7 +119,7 @@ function migrateOrgFlatContent(orgRoot) {
     const dest = path_1.default.join(orgRoot, 'personalized-employee');
     try {
         // Root-relative output trees are authoritative, even when their names resemble legacy capabilities.
-        const artifacts = (0, artifact_paths_1.resolveArtifactPaths)(orgRoot, dest);
+        const artifacts = resolvePackArtifactPaths({ level: 'Org', root: orgRoot, contentRoot: dest });
         const protectedDirectories = [artifacts.evidence, artifacts.raw, artifacts.retrospectives, path_1.default.dirname(artifacts.archiveRaw)];
         const contains = (root, target) => {
             const relative = path_1.default.relative(root, target);