fraim 2.0.278 → 2.0.280

package/dist/src/cli/commands/doctor.js

@@ -15,6 +15,7 @@ const workflow_checks_1 = require("../doctor/checks/workflow-checks");
 const ide_config_checks_1 = require("../doctor/checks/ide-config-checks");
 const mcp_connectivity_checks_1 = require("../doctor/checks/mcp-connectivity-checks");
 const scripts_checks_1 = require("../doctor/checks/scripts-checks");
+const agent_cli_health_checks_1 = require("../doctor/checks/agent-cli-health-checks");
 const add_ide_1 = require("./add-ide");
 // Read version from package.json
 const getFramVersion = () => {
@@ -58,7 +59,8 @@ function getAllChecks() {
         ...(0, workflow_checks_1.getJobChecks)(),
         ...(0, ide_config_checks_1.getIDEConfigChecks)(),
         ...(0, mcp_connectivity_checks_1.getMCPConnectivityChecks)(),
-        ...(0, scripts_checks_1.getScriptsChecks)()
+        ...(0, scripts_checks_1.getScriptsChecks)(),
+        ...(0, agent_cli_health_checks_1.getAgentCliHealthChecks)()
     ];
 }
 async function runFixMcpRepair(options, repair = add_ide_1.runAddIDE) {

package/dist/src/cli/doctor/check-runner.js

@@ -10,6 +10,10 @@ const CHECK_TIMEOUT = 2000; // 2 seconds per check
 // Issue #532: stdio MCP servers need up to 15s for handshake + npm version resolution
 // on first call via fraim-mcp-latest-launcher; 20s gives a 5s buffer.
 const MCP_CHECK_TIMEOUT = 20000; // 20 seconds for MCP connectivity checks
+// Issue #1285: this check shells out to `npm prefix -g`, up to three CLI
+// `--version` probes, and (Windows) a PowerShell registry read — more real
+// process spawns than the default budget comfortably covers.
+const AGENT_CLI_HEALTH_CHECK_TIMEOUT = 10000; // 10 seconds for agent CLI health checks
 const TOTAL_TIMEOUT = 30000; // 30 seconds total
 // Simple logger for doctor command (optional, falls back to no-op)
 const logger = {
@@ -39,8 +43,12 @@ const trackMetric = (name, value) => {
  */
 async function runCheckWithTimeout(check, timeout = CHECK_TIMEOUT) {
     const checkStartTime = Date.now();
-    // Use longer timeout for MCP connectivity checks
-    const effectiveTimeout = check.category === 'mcpConnectivity' ? MCP_CHECK_TIMEOUT : timeout;
+    // Use longer timeouts for checks that shell out to real CLI/registry probes.
+    const effectiveTimeout = check.category === 'mcpConnectivity'
+        ? MCP_CHECK_TIMEOUT
+        : check.category === 'agentCliHealth'
+            ? AGENT_CLI_HEALTH_CHECK_TIMEOUT
+            : timeout;
     try {
         logger.debug(`Running check: ${check.name}`, { category: check.category });
         const result = await Promise.race([
@@ -132,7 +140,8 @@ async function runChecks(checks, options, version) {
         jobs: { checks: [] },
         ideConfiguration: { checks: [] },
         mcpConnectivity: { checks: [] },
-        scripts: { checks: [] }
+        scripts: { checks: [] },
+        agentCliHealth: { checks: [] }
     };
     let passed = 0;
     let warnings = 0;

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

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Agent CLI PATH/version health checks for FRAIM doctor command
+ * Issue #1284/#1285: detect drift between FRAIM's own managed-PATH resolution,
+ * the ambient shell PATH, and the actual npm-global install for agent CLIs
+ * FRAIM installs through its managed-Node fallback.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAgentCliHealthChecks = getAgentCliHealthChecks;
+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 command_resolution_1 = require("../../mcp/command-resolution");
+// Codex is FRAIM's first Hub-compatible CLI with a managed-install fallback
+// (npm install -g into FRAIM's portable Node when no system install is
+// found). Extend this list as claude/gemini/copilot gain the same fallback.
+const MANAGED_CLIS = [
+    { id: 'codex', label: 'Codex', command: 'codex' },
+];
+// Windows cannot CreateProcess a `.cmd`/`.bat` file directly (spawnSync on a
+// resolved absolute `.cmd` path throws EINVAL) — it must go through cmd.exe,
+// matching the same wrapping `hosts.ts`'s `resolveHostInvocation()` and
+// `server.ts`'s `hubCommandVersion()` already use. Duplicated here (not
+// imported from `hosts.ts`) because `src/cli` is a pure layer that cannot
+// import the server-layer `src/ai-hub` module (`scripts/validate-purity.ts`).
+function quoteWindowsArg(value) {
+    if (value.length === 0)
+        return '""';
+    return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, '$1$1')}"`;
+}
+function escapeWindowsArg(value) {
+    return /[\s"]/u.test(value) ? quoteWindowsArg(value) : value;
+}
+function probeVersion(commandPath) {
+    try {
+        const executable = process.platform === 'win32' ? 'cmd.exe' : commandPath;
+        const args = process.platform === 'win32'
+            ? ['/d', '/s', '/c', `${escapeWindowsArg(commandPath)} --version`]
+            : ['--version'];
+        const result = (0, child_process_1.spawnSync)(executable, args, { encoding: 'utf8', timeout: 5000 });
+        if (result.status !== 0 || result.error)
+            return null;
+        return (result.stdout || result.stderr || '').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+// The persisted Windows User PATH (what a brand-new terminal reads) can
+// disagree with this process's own inherited `process.env.PATH` (what a
+// 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.
+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;
+    }
+}
+async function runAgentCliHealthCheck(cli) {
+    // "Ambient" is this process's own raw, unmodified PATH — exactly what a
+    // shell already open before a PATH fix landed still sees (issue #1285's
+    // "any shell the user already has open keeps its own stale in-memory copy
+    // until restarted" applies to the process running this check too, not
+    // only the user's terminal). "Managed" strips any stale managed directory
+    // already sitting on that ambient PATH and re-appends FRAIM's current,
+    // correctly-ordered managed dirs — so it always reflects the current
+    // versioned build, independent of whatever the ambient PATH happens to
+    // still contain. Deliberately NOT `resolveManagedCommand()`: that helper
+    // 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);
+    const managedSearchPath = (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH);
+    const managedPath = (0, command_resolution_1.getSystemCommandPath)(cli.command, managedSearchPath);
+    if (!ambientPath && !managedPath) {
+        return {
+            status: 'passed',
+            message: `${cli.label} is not installed; nothing to check.`,
+        };
+    }
+    const ambientVersion = ambientPath ? probeVersion(ambientPath) : null;
+    const managedVersion = !managedPath
+        ? null
+        : managedPath === ambientPath
+            ? ambientVersion
+            : probeVersion(managedPath);
+    const npmGlobalBinDirs = (0, managed_agent_paths_1.resolveNpmGlobalBinDirs)();
+    const npmGlobalPath = npmGlobalBinDirs.length > 0
+        ? (0, command_resolution_1.getSystemCommandPath)(cli.command, npmGlobalBinDirs.join(path_1.default.delimiter))
+        : null;
+    const npmGlobalVersion = npmGlobalPath ? probeVersion(npmGlobalPath) : null;
+    // Drift means either: the ambient shell resolves a different version than
+    // the actual npm-global install, or this process's own ambient PATH
+    // resolves a *different file* than FRAIM's freshly-recomputed managed-dir
+    // resolution would — the exact "stale shim still shadows the current one"
+    // signature from #1285.
+    const versionMismatch = Boolean((ambientVersion && npmGlobalVersion && ambientVersion !== npmGlobalVersion)
+        || (ambientPath && managedPath && ambientPath !== managedPath));
+    if (!versionMismatch) {
+        return {
+            status: 'passed',
+            message: `${cli.label} is consistent (${ambientVersion || managedVersion || 'unknown version'}).`,
+            details: { ambientPath, managedPath, npmGlobalPath },
+        };
+    }
+    const persistedUserPath = readPersistedUserPath();
+    const persistedResolved = persistedUserPath ? (0, command_resolution_1.getSystemCommandPath)(cli.command, persistedUserPath) : null;
+    const persistedVersion = persistedResolved ? probeVersion(persistedResolved) : null;
+    const persistedMatchesManaged = Boolean(persistedResolved && managedPath && persistedResolved === managedPath);
+    const suggestion = persistedUserPath === null
+        ? `Restart your terminal, then run "${cli.command} --version" again to confirm.`
+        : persistedMatchesManaged
+            ? `Your saved PATH is already correct — open a new terminal window so it takes effect, then run "${cli.command} --version" again.`
+            : `Your saved PATH still resolves the old ${cli.label} build. Run "${cli.command} update" (or reinstall ${cli.label}), then open a new terminal.`;
+    return {
+        status: 'warning',
+        message: `${cli.label} PATH drift detected: ambient ${ambientVersion || 'not found'} vs managed ${managedVersion || 'not found'} vs npm-global ${npmGlobalVersion || 'not found'}.`,
+        suggestion,
+        details: {
+            ambientPath, ambientVersion,
+            managedPath, managedVersion,
+            npmGlobalPath, npmGlobalVersion,
+            persistedUserPathResolvedTo: persistedResolved,
+            persistedUserPathVersion: persistedVersion,
+        },
+    };
+}
+function agentCliHealthCheck(cli) {
+    return {
+        name: `${cli.label} PATH/version health`,
+        category: 'agentCliHealth',
+        critical: false,
+        run: () => runAgentCliHealthCheck(cli),
+    };
+}
+function getAgentCliHealthChecks() {
+    return MANAGED_CLIS.map(agentCliHealthCheck);
+}
+// Reused by the Hub's `/api/ai-hub/check-agent` route (issue #1285 §4) so a
+// manager who clicks "Check if Ready" right after `codex update` sees PATH
+// drift immediately instead of a bare pass/fail. Returns null for a CLI this
+// module does not track.
+async function checkAgentCliHealthByCommand(command) {
+    const cli = MANAGED_CLIS.find((entry) => entry.command === command);
+    if (!cli)
+        return null;
+    try {
+        return await runAgentCliHealthCheck(cli);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/cli/doctor/reporters/console-reporter.js

@@ -16,7 +16,8 @@ const CATEGORY_NAMES = {
     jobs: 'Jobs',
     ideConfiguration: 'IDE Configuration',
     mcpConnectivity: 'MCP Server Connectivity',
-    scripts: 'Scripts'
+    scripts: 'Scripts',
+    agentCliHealth: 'Agent CLI Health'
 };
 function getStatusIcon(status) {
     switch (status) {

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

@@ -3,47 +3,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveManagedCommand = exports.getSystemCommandPath = exports.getPortableNpxCommand = void 0;
+exports.resolveManagedCommand = exports.getPortableManagedCommandPath = exports.getSystemCommandPath = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
-const getPortableNodeRoot = () => path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'node');
-const getPortableNpxCandidates = () => {
-    const nodeRoot = getPortableNodeRoot();
-    if (process.platform === 'win32') {
-        const candidates = [path_1.default.join(nodeRoot, 'npx.cmd')];
-        if (fs_1.default.existsSync(nodeRoot)) {
-            const extractedDirs = fs_1.default.readdirSync(nodeRoot, { withFileTypes: true })
-                .filter((entry) => entry.isDirectory() && entry.name.startsWith('node-v'))
-                .sort((a, b) => b.name.localeCompare(a.name));
-            for (const entry of extractedDirs) {
-                candidates.push(path_1.default.join(nodeRoot, entry.name, 'npx.cmd'));
-            }
-        }
-        return candidates;
-    }
-    return [
-        path_1.default.join(nodeRoot, 'bin', 'npx'),
-        path_1.default.join(nodeRoot, 'npx')
-    ];
-};
-const getPortableNpxCommand = () => {
-    for (const candidate of getPortableNpxCandidates()) {
-        if (fs_1.default.existsSync(candidate)) {
-            return candidate;
-        }
-    }
-    return null;
-};
-exports.getPortableNpxCommand = getPortableNpxCommand;
-const getPathEntries = () => {
-    const rawPath = process.env.PATH || '';
+const managed_agent_paths_1 = require("../utils/managed-agent-paths");
+// Issue #1284/#1285 (Implementation Strategy §0): commands FRAIM resolves
+// fresh at launch time instead of trusting a persisted PATH string. Started
+// as `npx`-only; generalized to every agent CLI FRAIM itself launches
+// (Hub-driven runs, version probes, install/check-agent routes) so those
+// launches are immune to PATH-order drift structurally.
+const MANAGED_COMMANDS = new Set(['npx', 'codex', 'claude', 'gemini', 'copilot']);
+const getPathEntries = (basePath) => {
+    const rawPath = (0, managed_agent_paths_1.stripProjectLocalNodeBinDirs)(basePath ?? process.env.PATH ?? '');
     return rawPath
         .split(path_1.default.delimiter)
         .map((entry) => entry.trim())
         .filter(Boolean);
 };
-const getSystemCommandCandidates = (command) => {
+const getSystemCommandCandidates = (command, basePath) => {
     if (!command || path_1.default.isAbsolute(command)) {
         return command ? [command] : [];
     }
@@ -52,10 +29,14 @@ const getSystemCommandCandidates = (command) => {
             ? [command]
             : [command, `${command}.cmd`, `${command}.exe`, `${command}.bat`, `${command}.com`]
         : [command];
-    return getPathEntries().flatMap((entry) => commandNames.map((name) => path_1.default.join(entry, name)));
+    return getPathEntries(basePath).flatMap((entry) => commandNames.map((name) => path_1.default.join(entry, name)));
 };
-const getSystemCommandPath = (command) => {
-    for (const candidate of getSystemCommandCandidates(command)) {
+// `basePath` defaults to the current process PATH; pass an explicit PATH
+// string to resolve a command against a different candidate list (e.g. the
+// npm-global bin dirs computed by `resolveNpmGlobalBinDirs`) without mutating
+// `process.env.PATH`.
+const getSystemCommandPath = (command, basePath) => {
+    for (const candidate of getSystemCommandCandidates(command, basePath)) {
         try {
             const stats = fs_1.default.statSync(candidate);
             if (stats.isFile()) {
@@ -69,13 +50,32 @@ const getSystemCommandPath = (command) => {
     return null;
 };
 exports.getSystemCommandPath = getSystemCommandPath;
+// Mirrors the shape of the old `getPortableNpxCandidates()`, but checks only
+// the current versioned `getPortableNodeBinPath()` directory — never the
+// legacy flat directory — so a shim orphaned there (Defect A) can never be
+// selected here regardless of what's on disk.
+const getPortableManagedCommandCandidates = (command) => {
+    const versionedDir = (0, managed_agent_paths_1.getPortableNodeBinPath)();
+    if (process.platform === 'win32') {
+        return [`${command}.cmd`, `${command}.exe`].map((name) => path_1.default.join(versionedDir, name));
+    }
+    return [path_1.default.join(versionedDir, command)];
+};
+const getPortableManagedCommandPath = (command) => {
+    for (const candidate of getPortableManagedCommandCandidates(command)) {
+        if (fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+};
+exports.getPortableManagedCommandPath = getPortableManagedCommandPath;
 const resolveManagedCommand = (command) => {
-    if (command !== 'npx') {
+    if (!MANAGED_COMMANDS.has(command))
         return command;
-    }
-    // Prefer system-installed npx so we don't install our own Node when the
-    // machine already has one. Fall back to the FRAIM-managed portable copy
-    // only when no system npx is found. Last resort: bare command name.
-    return (0, exports.getSystemCommandPath)(command) || (0, exports.getPortableNpxCommand)() || command;
+    // Prefer a system-installed CLI so FRAIM doesn't install its own copy when
+    // the machine already has one. Fall back to the FRAIM-managed portable copy
+    // only when no system install is found. Last resort: bare command name.
+    return (0, exports.getSystemCommandPath)(command) || (0, exports.getPortableManagedCommandPath)(command) || command;
 };
 exports.resolveManagedCommand = resolveManagedCommand;

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

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installManagedAgent = installManagedAgent;
+const fs_1 = __importDefault(require("fs"));
+const managed_agent_paths_1 = require("./managed-agent-paths");
+// Issue #1284/#1285 (Implementation Strategy §2): the exact "standard npm
+// global install, then fall back to FRAIM's managed prefix" sequence used to
+// be duplicated verbatim in `server.ts` (Hub's install-agent route) and
+// `session-service.ts` (first-run's installAgent), including Defect A — both
+// pointed `npm_config_prefix` at the flat `nodeRoot` dir instead of the
+// versioned dir that actually contains the Node/npm binaries running the
+// install. Extracted so the prefix fix (and any future fix to this sequence)
+// lives in one place. Callers are responsible for the "already installed"
+// check before invoking this — it only covers the install-then-fallback path.
+async function installManagedAgent(option, systemPath, deps) {
+    let standardInstallError = null;
+    try {
+        await deps.runProcess('npm', ['install', '-g', option.installPackage], {
+            PATH: systemPath,
+            npm_config_prefix: undefined,
+            NPM_CONFIG_PREFIX: undefined,
+        });
+        const standardVersion = deps.commandVersion(option.launchCommand, undefined, systemPath);
+        const npmGlobalBinDirs = standardVersion
+            ? []
+            : (0, managed_agent_paths_1.resolveNpmGlobalBinDirs)(systemPath, {
+                npm_config_prefix: undefined,
+                NPM_CONFIG_PREFIX: undefined,
+            });
+        const standardVersionWithNpmBin = standardVersion
+            || (npmGlobalBinDirs.length > 0
+                ? deps.commandVersion(option.launchCommand, npmGlobalBinDirs, systemPath)
+                : null);
+        if (standardVersionWithNpmBin) {
+            return { outcome: 'standard', npmGlobalBinDirs };
+        }
+        standardInstallError = `${option.label} standard install completed, but the CLI is not runnable from the user PATH.`;
+    }
+    catch (error) {
+        standardInstallError = error instanceof Error ? error.message : 'Unknown error';
+    }
+    // Defect A fix: co-locate npm-global shims with the node.exe/npm.cmd that
+    // actually runs the install, instead of the flat legacy directory.
+    const prefix = (0, managed_agent_paths_1.getPortableNodeBinPath)();
+    fs_1.default.mkdirSync(prefix, { recursive: true });
+    await deps.runProcess('npm', ['install', '-g', option.installPackage], { npm_config_prefix: prefix });
+    const ver = deps.commandVersion(option.launchCommand, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
+    if (!ver) {
+        throw new Error(`${option.label} install completed, but the CLI is not runnable from FRAIM's managed PATH. Standard install failure: ${standardInstallError}`);
+    }
+    return { outcome: 'managed' };
+}

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

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getManagedNodeRoot = getManagedNodeRoot;
 exports.getPortableNodeBinPath = getPortableNodeBinPath;
 exports.getManagedAgentBinDirs = getManagedAgentBinDirs;
+exports.stripProjectLocalNodeBinDirs = stripProjectLocalNodeBinDirs;
+exports.cleanupOrphanedManagedShims = cleanupOrphanedManagedShims;
 exports.stripManagedAgentBinDirsFromPath = stripManagedAgentBinDirsFromPath;
 exports.appendBinDirsToPath = appendBinDirsToPath;
 exports.getNpmGlobalBinDirsFromPrefix = getNpmGlobalBinDirsFromPrefix;
@@ -37,11 +39,62 @@ function getPortableNodeBinPath() {
 function getManagedAgentBinDirs() {
     const nodeRoot = getManagedNodeRoot();
     const portableNodeBin = getPortableNodeBinPath();
+    // The current versioned Node directory must outrank the legacy flat directory:
+    // a shim orphaned in the flat directory by an older FRAIM version must never
+    // shadow a newer bundled build (issue #1285). uniquePathEntries'/Set-based dedup
+    // collapses this to a single entry when no versioned subfolder exists yet.
     const candidates = process.platform === 'win32'
-        ? [nodeRoot, portableNodeBin]
-        : [nodeRoot, path_1.default.join(nodeRoot, 'bin'), portableNodeBin];
+        ? [portableNodeBin, nodeRoot]
+        : [portableNodeBin, nodeRoot, path_1.default.join(nodeRoot, 'bin')];
     return [...new Set(candidates.filter(Boolean))];
 }
+// Issue #1284/#1285: strips PATH entries that point at a project-local
+// `node_modules/.bin` directory. Relocated from `src/ai-hub/hosts.ts` (Defect D)
+// so the pure `src/cli` layer (which `command-resolution.ts` belongs to, and
+// which cannot import from the server-layer `hosts.ts`) can apply the same
+// filtering when resolving a managed command, not just when probing agent
+// versions. A devDependency's own CLI shim (e.g. a stale `@openai/codex-sdk`
+// pulled in transitively) must never shadow the real global install.
+function stripProjectLocalNodeBinDirs(basePath) {
+    return (basePath ?? '')
+        .split(path_1.default.delimiter)
+        .filter(Boolean)
+        .filter((entry) => {
+        const normalized = path_1.default.normalize(entry).toLowerCase();
+        return !normalized.endsWith(`${path_1.default.sep}node_modules${path_1.default.sep}.bin`);
+    })
+        .join(path_1.default.delimiter);
+}
+// Issue #1285 (Implementation Strategy §3): after (re)ordering the managed
+// candidates above, nothing new is ever written to the flat, legacy `nodeRoot`
+// directory — but installs made before this fix left real shims sitting there.
+// Scoped strictly to filenames npm itself would have generated for a managed
+// agent CLI install (never a wildcard sweep), so this can run unconditionally
+// and idempotently on every FRAIM startup.
+const MANAGED_AGENT_COMMANDS = ['codex', 'claude', 'gemini', 'copilot'];
+function cleanupOrphanedManagedShims() {
+    const nodeRoot = getManagedNodeRoot();
+    const versionedDir = getPortableNodeBinPath();
+    if (versionedDir === nodeRoot || !fs_1.default.existsSync(nodeRoot))
+        return [];
+    const basenames = process.platform === 'win32'
+        ? MANAGED_AGENT_COMMANDS.flatMap((command) => [`${command}.cmd`, `${command}.ps1`])
+        : MANAGED_AGENT_COMMANDS;
+    const removed = [];
+    for (const basename of basenames) {
+        const candidate = path_1.default.join(nodeRoot, basename);
+        try {
+            if (fs_1.default.statSync(candidate).isFile()) {
+                fs_1.default.unlinkSync(candidate);
+                removed.push(candidate);
+            }
+        }
+        catch {
+            // Not present or inaccessible — nothing to clean up.
+        }
+    }
+    return removed;
+}
 function normalizePathEntry(entry) {
     const resolved = path_1.default.resolve(entry.trim());
     return process.platform === 'win32' ? resolved.toLowerCase() : resolved;

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

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FIRST_RUN_ROW_IDS = exports.FirstRunSessionService = void 0;
+exports.buildPersistShellPathWindowsCommand = buildPersistShellPathWindowsCommand;
 exports.buildFirstRunHubLaunchArgs = buildFirstRunHubLaunchArgs;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
@@ -49,6 +50,7 @@ const auto_mcp_setup_1 = require("../cli/setup/auto-mcp-setup");
 const setup_1 = require("../cli/commands/setup");
 const script_sync_utils_1 = require("../cli/utils/script-sync-utils");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
+const managed_agent_install_1 = require("../cli/utils/managed-agent-install");
 const types_1 = require("./types");
 Object.defineProperty(exports, "FIRST_RUN_ROW_IDS", { enumerable: true, get: function () { return types_1.FIRST_RUN_ROW_IDS; } });
 const install_state_1 = require("./install-state");
@@ -89,26 +91,40 @@ function ensureOutputDirs() {
 // installed there without shadowing user/system installs.
 (function bootstrapFraimNodeBin() {
     (0, managed_agent_paths_1.appendManagedAgentBinDirsToProcessPath)();
+    // 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.
+    const removedShims = (0, managed_agent_paths_1.cleanupOrphanedManagedShims)();
+    if (removedShims.length > 0) {
+        appendInstallLog(`orphaned-managed-shims-removed ${removedShims.join(', ')}`);
+    }
 })();
+// Issue #1285: pure command-string builder extracted from persistShellPath()
+// so the generated PowerShell command's directory order (the current
+// versioned dir added before the legacy flat dir, per `bins`' own order —
+// see getManagedAgentBinDirs()) can be asserted directly, without mutating
+// the real registry-backed Windows User PATH in a test.
+function buildPersistShellPathWindowsCommand(bins) {
+    const assignments = bins.map((entry, index) => `$bin${index} = '${entry.replace(/'/g, "''")}'`);
+    const removals = bins.map((_, index) => `$parts = @($parts | Where-Object { $_ -ne $bin${index} })`);
+    const additions = bins.map((_, index) => `$parts += $bin${index}`);
+    return [
+        ...assignments,
+        `$cur = [Environment]::GetEnvironmentVariable('PATH', 'User')`,
+        `$parts = @($cur -split ';' | Where-Object { $_ })`,
+        ...removals,
+        ...additions,
+        `$cur = ($parts | Select-Object -Unique) -join ';'`,
+        `[Environment]::SetEnvironmentVariable('PATH', $cur, 'User')`,
+    ].join('; ');
+}
 function persistShellPath() {
     const marker = '# FRAIM managed binaries';
     const legacyExportLine = 'export PATH="$HOME/.fraim/node/bin:$PATH"';
     const exportLine = 'export PATH="$PATH:$HOME/.fraim/node/bin"';
     const stanza = `\n${marker}\n${exportLine}\n`;
     if (process.platform === 'win32') {
-        const bins = (0, managed_agent_paths_1.getManagedAgentBinDirs)();
-        const assignments = bins.map((entry, index) => `$bin${index} = '${entry.replace(/'/g, "''")}'`);
-        const removals = bins.map((_, index) => `$parts = @($parts | Where-Object { $_ -ne $bin${index} })`);
-        const additions = bins.map((_, index) => `$parts += $bin${index}`);
-        const psCmd = [
-            ...assignments,
-            `$cur = [Environment]::GetEnvironmentVariable('PATH', 'User')`,
-            `$parts = @($cur -split ';' | Where-Object { $_ })`,
-            ...removals,
-            ...additions,
-            `$cur = ($parts | Select-Object -Unique) -join ';'`,
-            `[Environment]::SetEnvironmentVariable('PATH', $cur, 'User')`,
-        ].join('; ');
+        const psCmd = buildPersistShellPathWindowsCommand((0, managed_agent_paths_1.getManagedAgentBinDirs)());
         (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8' });
         return;
     }
@@ -782,53 +798,12 @@ class FirstRunSessionService {
                     loginHint: `Sign in to ${option.label} to activate it. A terminal window will open with the sign-in command — complete sign-in there, then return here and click "Check if Ready".`,
                 };
             }
-            let standardInstallError = null;
-            try {
-                await runProcess('npm', ['install', '-g', option.installPackage], {
-                    PATH: systemPath,
-                    npm_config_prefix: undefined,
-                    NPM_CONFIG_PREFIX: undefined,
-                });
-                const standardVersion = commandVersion(option.launchCommand, undefined, systemPath);
-                const npmGlobalBinDirs = standardVersion
-                    ? []
-                    : (0, managed_agent_paths_1.resolveNpmGlobalBinDirs)(systemPath, {
-                        npm_config_prefix: undefined,
-                        NPM_CONFIG_PREFIX: undefined,
-                    });
-                const standardVersionWithNpmBin = standardVersion
-                    || (npmGlobalBinDirs.length > 0
-                        ? commandVersion(option.launchCommand, npmGlobalBinDirs, systemPath)
-                        : null);
-                if (standardVersionWithNpmBin) {
-                    if (npmGlobalBinDirs.length > 0) {
-                        process.env.PATH = (0, managed_agent_paths_1.appendBinDirsToPath)(systemPath, npmGlobalBinDirs);
-                    }
-                    this.setAgentInstallStatus(agentId, 'needs-sign-in', `Sign in to ${option.label} to activate it.`);
-                    appendInstallLog(`agent-installed-standard ${agentId}`);
-                    this.persist();
-                    return {
-                        ok: true,
-                        message: `${option.label} installed successfully.`,
-                        needsLogin: true,
-                        loginCommand: option.loginCommand,
-                        loginHint: `Sign in to ${option.label} to activate it. A terminal window will open with the sign-in command — complete sign-in there, then return here and click "Check if Ready".`,
-                    };
-                }
-                standardInstallError = `${option.label} standard install completed, but the CLI is not runnable from the user PATH.`;
-            }
-            catch (error) {
-                standardInstallError = error instanceof Error ? error.message : 'Unknown error';
-            }
-            const prefix = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
-            fs_1.default.mkdirSync(prefix, { recursive: true });
-            await runProcess('npm', ['install', '-g', option.installPackage], { npm_config_prefix: prefix });
-            const ver = commandVersion(option.launchCommand, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
-            if (!ver) {
-                throw new Error(`${option.label} install completed, but the CLI is not runnable from FRAIM's managed PATH. Standard install failure: ${standardInstallError}`);
+            const outcome = await (0, managed_agent_install_1.installManagedAgent)({ label: option.label, installPackage: option.installPackage, launchCommand: option.launchCommand }, systemPath, { runProcess, commandVersion });
+            if (outcome.outcome === 'standard' && outcome.npmGlobalBinDirs.length > 0) {
+                process.env.PATH = (0, managed_agent_paths_1.appendBinDirsToPath)(systemPath, outcome.npmGlobalBinDirs);
             }
             this.setAgentInstallStatus(agentId, 'needs-sign-in', `Sign in to ${option.label} to activate it.`);
-            appendInstallLog(`agent-installed-managed ${agentId}`);
+            appendInstallLog(outcome.outcome === 'standard' ? `agent-installed-standard ${agentId}` : `agent-installed-managed ${agentId}`);
             this.persist();
             return {
                 ok: true,

package/package.json

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