fraim 2.0.322 → 2.0.323

package/dist/src/cli/doctor/checks/agent-cli-health-checks.js

@@ -14,6 +14,7 @@ exports.checkAgentCliHealthByCommand = checkAgentCliHealthByCommand;
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
 const managed_agent_paths_1 = require("../../utils/managed-agent-paths");
+const machine_path_1 = require("../../utils/machine-path");
 const command_resolution_1 = require("../../mcp/command-resolution");
 // CLIs with a managed-install fallback (npm install -g into FRAIM's portable
 // Node when no system install is found). Add gemini/copilot here when their
@@ -57,18 +58,14 @@ function probeVersion(commandPath) {
 // shell already open before the fix landed still uses) — issue #1285's
 // exact "update said success but --version looked wrong" ambiguity.
 // Windows-only; there is no equivalent persisted-PATH registry on macOS/Linux.
+// Issue #1748: this used to shell out to PowerShell for HKCU Environment Path on its own,
+// a second independently-written Windows registry PATH reader. Two implementations of the
+// same read drift apart, and a parsing fix applied to one is easy to miss on the other,
+// which is the same PATH-resolution-drift bug class this check exists to report. Delegates
+// to the shared reader instead, which also covers HKLM rather than only the user hive and
+// expands REG_EXPAND_SZ references.
 function readPersistedUserPath() {
-    if (process.platform !== 'win32')
-        return null;
-    try {
-        const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', "[Environment]::GetEnvironmentVariable('PATH','User')"], { encoding: 'utf8', timeout: 5000 });
-        if (result.status !== 0 || result.error)
-            return null;
-        return (result.stdout || '').trim() || null;
-    }
-    catch {
-        return null;
-    }
+    return (0, machine_path_1.resolveMachinePathCached)();
 }
 async function runAgentCliHealthCheck(cli) {
     // "Ambient" is this process's own raw, unmodified PATH — exactly what a
@@ -83,7 +80,16 @@ async function runAgentCliHealthCheck(cli) {
     // is system-PATH-first for launch purposes and would silently agree with
     // a stale ambient entry instead of surfacing the drift this check exists
     // to catch.
-    const ambientPath = (0, command_resolution_1.getSystemCommandPath)(cli.command);
+    // Issue #1748: process.env.PATH no longer carries FRAIM's managed bin dirs (the
+    // module-load mutation that put them there was the defect). Without a fallback,
+    // `ambientPath` is null whenever the only install is FRAIM-managed, and both clauses
+    // of `versionMismatch` below short-circuit on it, so this check would return
+    // "consistent" while the #1285 stale-shim drift it exists to catch went unreported.
+    // The machine PATH is what a newly opened shell resolves, which is the notion of
+    // "ambient" this check actually wants once the process is no longer self-mutating.
+    const machinePathForAmbient = (0, machine_path_1.resolveMachinePathCached)();
+    const ambientPath = (0, command_resolution_1.getSystemCommandPath)(cli.command)
+        || (machinePathForAmbient ? (0, command_resolution_1.getSystemCommandPath)(cli.command, machinePathForAmbient) : null);
     const managedSearchPath = (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH);
     const managedPath = (0, command_resolution_1.getSystemCommandPath)(cli.command, managedSearchPath);
     if (!ambientPath && !managedPath) {

package/dist/src/cli/mcp/command-resolution.js

@@ -87,8 +87,13 @@ const resolveManagedCommand = (command) => {
     // path and the status-check path. Fall back to the FRAIM-managed portable
     // copy only when no system install is found by either check. Last resort:
     // bare command name.
-    return (0, exports.getSystemCommandPath)(command)
-        || (0, exports.getSystemCommandPath)(command, (0, managed_agent_paths_1.buildRecoveredSystemPath)(process.env.PATH))
+    // Issue #1748: resolve ONLY against the recovered system PATH. The previous first tier
+    // scanned this process's ambient PATH, which carries FRAIM's own managed dirs (registered
+    // on the machine PATH at install, and formerly appended again at module load), so a
+    // FRAIM-managed binary was returned as if it were a system install and the tiers below
+    // never ran. buildRecoveredSystemPath() re-reads the machine PATH and excludes the managed
+    // dirs, so FRAIM's bundled copy is reachable only through the explicit tier below.
+    return (0, exports.getSystemCommandPath)(command, (0, managed_agent_paths_1.buildRecoveredSystemPath)(process.env.PATH))
         || (0, exports.getPortableManagedCommandPath)(command)
         || command;
 };

package/dist/src/cli/setup/ide-invocation-surfaces.js

@@ -72,7 +72,7 @@ ${buildDeferredToolBootstrapSection(profile)}1. **Confirm FRAIM activation**:
    If local FRAIM job stubs are present in the workspace, inspect those first and match the request locally. Also inspect \`fraim/personalized-employee/jobs/\` for local overrides or repo-specific jobs. If local files are missing or you cannot inspect workspace files, call \`list_fraim_jobs()\` to view the full catalog, including any proxy-discoverable personalized jobs.
 
 3. **Find the match**:
-   If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, ask once: "No catalog job matches. Would you like to run this as an ad-hoc task?" On confirmation, call \`get_fraim_job({ job: "adhoc-prompt" })\` and execute it with the user's instructions as the task input — do not pick the nearest catalog job. Do not ask again if the user already provided instructions.
+   If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, call \`get_fraim_job({ job: "adhoc-prompt" })\` directly and execute it with the user's instructions as the task input — no confirmation question, and do not pick the nearest catalog job.
 
 4. **Load the full content**:
    - For jobs, call \`get_fraim_job({ job: "<matched-job-name>" })\`.

package/dist/src/cli/utils/machine-path.js

@@ -0,0 +1,165 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRegQueryPathValue = parseRegQueryPathValue;
+exports.expandWindowsEnvRefs = expandWindowsEnvRefs;
+exports.composeMachinePath = composeMachinePath;
+exports.resolveMachinePathCached = resolveMachinePathCached;
+exports.clearMachinePathCache = clearMachinePathCache;
+exports.setMachinePathResolver = setMachinePathResolver;
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+// ─── Issue #1748: Windows machine-PATH recovery ─────────────────────────────
+//
+// A Windows process inherits its environment at creation and never observes later
+// registry changes (Node/Electron do not handle WM_SETTINGCHANGE). A Hub running for
+// hours therefore holds the PATH as of its launch. When a user installs an agent CLI
+// after that (Claude Code's native installer adding ~/.local/bin, say), the Hub cannot
+// see it while a freshly opened terminal can, so the Hub falls through to FRAIM's own
+// managed copy and runs a different CLI than the user installed and signed into.
+//
+// `defaultResolveLoginShellPath()` in managed-agent-paths.ts returns null on win32 (there
+// is no login-shell PATH concept there), so before this the only recovery on Windows was
+// the npm-prefix lookup: nothing re-read HKLM/HKCU. This module is the win32 counterpart
+// to that POSIX recovery. Ask the OS what the PATH is now, rather than trusting the
+// snapshot this process was handed.
+//
+// Lives in its own module rather than inside managed-agent-paths.ts so that file stays
+// under the 500-line architecture threshold, and because "read the OS environment" is a
+// distinct concern from "compose the PATH FRAIM resolves agents against". The dependency
+// runs one way only (managed-agent-paths imports this), so there is no import cycle.
+// Per-read ceiling. Both registry reads run sequentially (spawnSync is synchronous by
+// definition, so they cannot overlap without making the whole resolution path async,
+// which every caller is sync today), so the worst case is twice this. Measured cost is
+// ~25ms per read, so 2s is already ~80x headroom while bounding a pathological stall at
+// 4s rather than 10s.
+const MACHINE_PATH_TIMEOUT_MS = 2000;
+// The machine PATH changes when the user installs or moves a CLI, which is exactly the
+// case this issue exists to handle, so this cache must expire rather than live for the
+// life of the process. A Hub can run for days; a permanent cache would mean "install a
+// CLI, then use it" still required a restart. Bounded by a TTL rather than an explicit
+// invalidation call because the install that matters most is the one made OUTSIDE FRAIM
+// (a vendor installer adding ~/.local/bin), which FRAIM never observes and so cannot
+// invalidate on. Measured cost of a refresh on Windows is ~50ms for both registry reads,
+// far below the blocking-spawn budget issue #1010 set (the POSIX login-shell read it sits
+// beside costs 1-3s and is cached for the whole process).
+const MACHINE_PATH_CACHE_TTL_MS = 60_000;
+let machinePathResolverOverride = null;
+let cachedMachinePath;
+let cachedMachinePathAtMs = 0;
+// The two registry values Windows itself composes a process PATH from, in the order it
+// composes them: Machine first, then User.
+const WINDOWS_PATH_REGISTRY_KEYS = [
+    [String.raw `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment`, 'Path'],
+    [String.raw `HKCU\Environment`, 'Path'],
+];
+// Resolve reg.exe by absolute path rather than letting the OS search PATH for it. This
+// module's whole purpose is to stop a PATH entry from deciding which binary FRAIM runs,
+// so invoking its own helper by bare name through that same untrusted PATH would undercut
+// the control it implements. Falls back to the bare name only if SystemRoot is unset,
+// which on a real Windows install it is not.
+function resolveRegExePath() {
+    const systemRoot = process.env.SystemRoot || process.env.SYSTEMROOT;
+    return systemRoot ? path_1.default.join(systemRoot, 'System32', 'reg.exe') : 'reg';
+}
+// `reg query` prints a line shaped like "    Path    REG_EXPAND_SZ    C:\foo;C:\bar".
+// Split on the value type rather than on whitespace, because a PATH entry may itself
+// contain spaces (C:\Program Files\...).
+function parseRegQueryPathValue(stdout) {
+    for (const line of (stdout || '').split(/\r?\n/)) {
+        const match = line.match(/\s+(?:REG_EXPAND_SZ|REG_SZ)\s+(.*)$/);
+        if (match && match[1] !== undefined) {
+            const value = match[1].trim();
+            if (value)
+                return value;
+        }
+    }
+    return null;
+}
+// REG_EXPAND_SZ keeps %VAR% references verbatim; Windows expands them when it builds a
+// process environment. Reading the raw value means expanding them here too, or an entry
+// like %USERPROFILE%\.local\bin never resolves. Unknown variables are left as written
+// rather than blanked, so a failed expansion cannot silently collapse an entry into a
+// different directory.
+function expandWindowsEnvRefs(value, env = process.env) {
+    return value.replace(/%([^%]+)%/g, (whole, name) => {
+        const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase());
+        const resolved = key === undefined ? undefined : env[key];
+        return resolved === undefined ? whole : resolved;
+    });
+}
+// Composition is separated from the registry I/O so the ordering contract can be tested
+// without spawning reg.exe: Machine entries precede User entries, because that is the
+// order Windows itself composes a process PATH in, and %VAR% references are expanded
+// before splitting so an expanded value containing a delimiter still splits correctly.
+function composeMachinePath(rawValues, env = process.env) {
+    const parts = [];
+    for (const raw of rawValues) {
+        if (!raw)
+            continue;
+        for (const entry of expandWindowsEnvRefs(raw, env).split(path_1.default.delimiter)) {
+            const trimmed = entry.trim();
+            if (trimmed)
+                parts.push(trimmed);
+        }
+    }
+    // Not de-duplicated here: every consumer composes this through appendBinDirsToPath,
+    // which already collapses repeats. A second dedupe would be duplicated logic.
+    return parts.length > 0 ? parts.join(path_1.default.delimiter) : null;
+}
+function defaultResolveMachinePath() {
+    if (process.platform !== 'win32')
+        return null;
+    // Issue #1692 established that a sandboxed test run must never WRITE the real,
+    // registry-backed Windows User PATH. Reading it is the same isolation break in the
+    // other direction: it lets whatever agent CLIs happen to be installed on the build
+    // machine shadow a test's own isolated fixtures, which is the cross-contamination
+    // hazard already documented on resolveNpmGlobalBinDirsCached. Tests that need
+    // machine-PATH behavior inject it through __setMachinePathResolverForTests.
+    if (process.env.FRAIM_TEST_SANDBOX === '1')
+        return null;
+    const rawValues = WINDOWS_PATH_REGISTRY_KEYS.map(([key, valueName]) => {
+        const result = (0, child_process_1.spawnSync)(resolveRegExePath(), ['query', key, '/v', valueName], {
+            encoding: 'utf8',
+            timeout: MACHINE_PATH_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        if (result.status !== 0 || result.error)
+            return null;
+        return parseRegQueryPathValue(result.stdout || '');
+    });
+    return composeMachinePath(rawValues);
+}
+function resolveMachinePathUncached() {
+    if (machinePathResolverOverride)
+        return machinePathResolverOverride();
+    return defaultResolveMachinePath();
+}
+/**
+ * The PATH the machine reports, read fresh instead of inherited, memoized for
+ * `MACHINE_PATH_CACHE_TTL_MS`. `nowMs` is injectable so a test can prove the entry expires
+ * without sleeping.
+ */
+function resolveMachinePathCached(nowMs = Date.now()) {
+    if (cachedMachinePath !== undefined && nowMs - cachedMachinePathAtMs < MACHINE_PATH_CACHE_TTL_MS) {
+        return cachedMachinePath;
+    }
+    try {
+        cachedMachinePath = resolveMachinePathUncached();
+    }
+    catch {
+        cachedMachinePath = null;
+    }
+    cachedMachinePathAtMs = nowMs;
+    return cachedMachinePath;
+}
+function clearMachinePathCache() {
+    cachedMachinePath = undefined;
+    cachedMachinePathAtMs = 0;
+}
+function setMachinePathResolver(resolver) {
+    machinePathResolverOverride = resolver;
+    clearMachinePathCache();
+}

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

@@ -112,6 +112,11 @@ async function installManagedAgent(option, systemPath, deps) {
             NPM_CONFIG_PREFIX: undefined,
         });
         const standardVersion = deps.commandVersion(option.launchCommand, undefined, systemPath);
+        // Only look up npm global bin dirs when the CLI was NOT already runnable: that lookup
+        // is a blocking npm-prefix subprocess, and on the success path there is nothing to find.
+        // (Commit 16cea56ac made this unconditional so the caller could persist the directory onto
+        // process.env.PATH; issue #1748 removed that in-process PATH write, so the unconditional
+        // lookup has no consumer and only costs the happy path a blocking subprocess.)
         const npmGlobalBinDirs = standardVersion
             ? []
             : (0, managed_agent_paths_1.resolveNpmGlobalBinDirs)(systemPath, {
@@ -123,7 +128,7 @@ async function installManagedAgent(option, systemPath, deps) {
                 ? deps.commandVersion(option.launchCommand, npmGlobalBinDirs, systemPath)
                 : null);
         if (standardVersionWithNpmBin) {
-            return { outcome: 'standard', npmGlobalBinDirs };
+            return { outcome: 'standard' };
         }
         standardInstallError = `${option.label} standard install completed, but the CLI is not runnable from the user PATH.`;
     }

package/dist/src/cli/utils/managed-agent-paths.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.resolveMachinePathCached = exports.expandWindowsEnvRefs = exports.parseRegQueryPathValue = void 0;
 exports.getManagedNodeRoot = getManagedNodeRoot;
 exports.getPortableNodeBinPath = getPortableNodeBinPath;
 exports.getManagedAgentBinDirs = getManagedAgentBinDirs;
@@ -13,10 +14,11 @@ exports.appendBinDirsToPath = appendBinDirsToPath;
 exports.getNpmGlobalBinDirsFromPrefix = getNpmGlobalBinDirsFromPrefix;
 exports.resolveNpmGlobalBinDirs = resolveNpmGlobalBinDirs;
 exports.buildPathWithManagedAgentBins = buildPathWithManagedAgentBins;
-exports.appendManagedAgentBinDirsToProcessPath = appendManagedAgentBinDirsToProcessPath;
 exports.__setLoginShellPathResolverForTests = __setLoginShellPathResolverForTests;
 exports.resolveLoginShellPathCached = resolveLoginShellPathCached;
 exports.__clearLoginShellPathCacheForTests = __clearLoginShellPathCacheForTests;
+exports.invalidateMachinePathCache = invalidateMachinePathCache;
+exports.__setMachinePathResolverForTests = __setMachinePathResolverForTests;
 exports.buildRecoveredSystemPath = buildRecoveredSystemPath;
 exports.buildRecoveredAgentPath = buildRecoveredAgentPath;
 exports.versionFromProbeOutput = versionFromProbeOutput;
@@ -24,6 +26,13 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const script_sync_utils_1 = require("./script-sync-utils");
+const machine_path_1 = require("./machine-path");
+// Re-exported so the machine-PATH surface stays reachable from this module, which is
+// where every other PATH helper already lives.
+var machine_path_2 = require("./machine-path");
+Object.defineProperty(exports, "parseRegQueryPathValue", { enumerable: true, get: function () { return machine_path_2.parseRegQueryPathValue; } });
+Object.defineProperty(exports, "expandWindowsEnvRefs", { enumerable: true, get: function () { return machine_path_2.expandWindowsEnvRefs; } });
+Object.defineProperty(exports, "resolveMachinePathCached", { enumerable: true, get: function () { return machine_path_2.resolveMachinePathCached; } });
 function getManagedNodeRoot() {
     return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
 }
@@ -185,9 +194,6 @@ function resolveNpmGlobalBinDirs(basePath, env) {
 function buildPathWithManagedAgentBins(basePath) {
     return appendBinDirsToPath(stripManagedAgentBinDirsFromPath(basePath), getManagedAgentBinDirs());
 }
-function appendManagedAgentBinDirsToProcessPath() {
-    process.env.PATH = buildPathWithManagedAgentBins(process.env.PATH);
-}
 // ─── Issue #1256 (slice a): location-agnostic PATH recovery ─────────────────
 //
 // A Hub launched from Launchpad/Finder/a Windows shortcut inherits the OS's minimal
@@ -350,17 +356,55 @@ function resolveNpmGlobalBinDirsCached(basePath) {
 // — resolve against this path for the system-install check, then consult
 // `getPortableManagedCommandPath()` (never the flat dir) as an explicit,
 // separate fallback tier.
+// Issue #1748: the win32 machine-PATH read lives in ./machine-path so this file stays
+// under the 500-line architecture threshold. These wrappers exist because changing the
+// machine PATH also invalidates npm-global dirs, which are resolved against the PATH
+// derived from it and cached here. Callers get one call that keeps both caches coherent
+// rather than having to remember to clear a second one.
+function invalidateMachinePathCache() {
+    (0, machine_path_1.clearMachinePathCache)();
+    cachedNpmGlobalBinDirsForRecovery.clear();
+}
+function __setMachinePathResolverForTests(resolver) {
+    (0, machine_path_1.setMachinePathResolver)(resolver);
+    cachedNpmGlobalBinDirsForRecovery.clear();
+}
 function buildRecoveredSystemPath(basePath) {
     const withoutManaged = stripManagedAgentBinDirsFromPath(basePath);
-    const withoutProjectBins = stripProjectLocalNodeBinDirs(withoutManaged);
+    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(withoutProjectBins, loginShellEntries)
-        : withoutProjectBins;
-    const withLoginShellClean = stripProjectLocalNodeBinDirs(withLoginShell);
-    const npmGlobalBinDirs = resolveNpmGlobalBinDirsCached(withLoginShellClean);
-    return appendBinDirsToPath(withLoginShellClean, npmGlobalBinDirs);
+        ? 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);
 }
 function buildRecoveredAgentPath(basePath) {
     return appendBinDirsToPath(buildRecoveredSystemPath(basePath), getManagedAgentBinDirs());

package/dist/src/first-run/session-service.js

@@ -89,11 +89,18 @@ function ensureOutputDirs() {
     fs_1.default.mkdirSync((0, script_sync_utils_1.getUserFraimDir)(), { recursive: true });
     fs_1.default.mkdirSync(path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'last-install'), { recursive: true });
 }
-// Append the portable Node bin dir to process PATH once at module load so
-// every spawnSync call (detection, login probe, change-agent) finds binaries
-// installed there without shadowing user/system installs.
+// Issue #1748: this no longer touches process.env.PATH. It used to append FRAIM's
+// managed bin dirs here so spawnSync callers would find them, but desktop-main imports
+// this module, so every Hub inherited them and command resolution could no longer tell
+// a user install from FRAIM's bundled copy. Anything that needs to find a managed
+// binary must route through buildRecoveredAgentPath()/resolveManagedCommand() rather
+// than relying on ambient process.env.PATH. What remains here is shim cleanup only.
 (function bootstrapFraimNodeBin() {
-    (0, managed_agent_paths_1.appendManagedAgentBinDirsToProcessPath)();
+    // Issue #1748: this used to call appendManagedAgentBinDirsToProcessPath(), putting FRAIM's
+    // managed dirs on this process's own PATH. desktop-main imports this module, so every Hub
+    // inherited that, and command resolution could no longer tell a user install from FRAIM's
+    // bundled copy. Resolution now re-reads the machine PATH instead, and FRAIM's directory is
+    // reachable there because persistShellPath registers it with the OS at install time.
     // Issue #1285 (Implementation Strategy §3): remove any managed-agent shim
     // orphaned in the legacy flat directory by an older FRAIM version, so it
     // can no longer shadow the current versioned build.
@@ -914,9 +921,6 @@ class FirstRunSessionService {
             });
             const pathWithNpm = (0, managed_agent_paths_1.appendBinDirsToPath)(systemPath, [npm.binDir]);
             const outcome = await (0, managed_agent_install_1.installManagedAgent)({ label: option.label, installPackage: option.installPackage, launchCommand: option.launchCommand }, pathWithNpm, { runProcess, commandVersion });
-            if (outcome.outcome === 'standard' && outcome.npmGlobalBinDirs.length > 0) {
-                process.env.PATH = (0, managed_agent_paths_1.appendBinDirsToPath)(pathWithNpm, outcome.npmGlobalBinDirs);
-            }
             this.setAgentInstallStatus(agentId, 'needs-sign-in', `Sign in to ${option.label} to activate it.`);
             appendInstallLog(outcome.outcome === 'standard' ? `agent-installed-standard ${agentId}` : `agent-installed-managed ${agentId}`);
             this.persist();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.322",
+  "version": "2.0.323",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {