fraim 2.0.277 → 2.0.279

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/dist/src/mcp/tool-schemas.js

@@ -0,0 +1,376 @@
+"use strict";
+/**
+ * MCP Tool Definitions
+ *
+ * This file contains the JSON schemas for all tools exposed by the FRAIM MCP Server.
+ * Centralizing these definitions improves readability and maintainability of the McpService.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getToolDefinitions = void 0;
+const readOnlyClosedWorldAnnotations = {
+    readOnlyHint: true,
+    openWorldHint: false,
+    destructiveHint: false,
+};
+const writeClosedWorldAnnotations = {
+    readOnlyHint: false,
+    openWorldHint: false,
+    destructiveHint: false,
+};
+const readOnlyOpenWorldAnnotations = {
+    readOnlyHint: true,
+    openWorldHint: true,
+    destructiveHint: false,
+};
+const writeOpenWorldAnnotations = {
+    readOnlyHint: false,
+    openWorldHint: true,
+    destructiveHint: false,
+};
+const getToolDefinitions = (options = {}) => {
+    const surface = options.surface ?? 'local-proxy';
+    const isLocalProxySurface = surface === 'local-proxy';
+    const sessionIdProperty = isLocalProxySurface
+        ? {
+            sessionId: {
+                type: 'string',
+                description: 'Active FRAIM session ID. Required on local-proxy runtime calls.'
+            }
+        }
+        : {};
+    const requiredWithSession = (fields) => isLocalProxySurface
+        ? ['sessionId', ...fields]
+        : fields;
+    const fraimConnectDescription = isLocalProxySurface
+        ? `Bootstrap and initialize a FRAIM session and obtain the sessionId used by active FRAIM workflow tools. Use this after explicit FRAIM activation: the user invoked FRAIM, named a FRAIM job, asked for FRAIM job recommendations, or the active surface selected a FRAIM job. Must be called before any FRAIM workflow tool calls. For ordinary requests, do not start a FRAIM session or scan the catalog.
+
+Example:
+{
+  "agent": {"name": "Claude", "model": "claude-3.5-sonnet"}
+}`
+        : `Bootstrap and initialize a FRAIM session and obtain the sessionId used by active FRAIM workflow tools. Use this after explicit FRAIM activation: the user invoked FRAIM, named a FRAIM job, asked for FRAIM job recommendations, or the active surface selected a FRAIM job. Must be called before any FRAIM workflow tool calls. For ordinary requests, do not start a FRAIM session or scan the catalog.
+
+Hosted marketplace clients may call this with only agent information. If machine or repository context is omitted, FRAIM creates a hosted marketplace session context automatically.
+
+Example:
+{
+  "agent": {"name": "ChatGPT", "model": "gpt-5"}
+}`;
+    return [
+        {
+            name: 'fraim_connect',
+            description: fraimConnectDescription,
+            annotations: writeClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    agent: {
+                        type: 'object',
+                        description: 'Agent identification',
+                        properties: {
+                            name: {
+                                type: 'string',
+                                description: 'Agent name (e.g., "Claude", "Cursor", "Kiro", "Windsurf", "Antigravity", "Grok")',
+                                examples: ['Claude', 'Cursor', 'Kiro', 'Windsurf', 'Antigravity', 'Grok']
+                            },
+                            model: {
+                                type: 'string',
+                                description: 'Model name/version (e.g., "claude-3.5-sonnet", "gpt-4", "cursor-small")',
+                                examples: ['claude-3.5-sonnet', 'gpt-4', 'cursor-small', 'kiro-agent']
+                            },
+                            version: {
+                                type: 'string',
+                                description: 'Agent version if available',
+                                examples: ['1.0.0', '2024.12.1']
+                            }
+                        },
+                        required: ['name', 'model'],
+                        additionalProperties: true
+                    },
+                    ...(isLocalProxySurface
+                        ? {}
+                        : {
+                            machine: {
+                                type: 'object',
+                                description: 'Optional machine specifications. Hosted marketplace sessions default this when omitted.',
+                                properties: {
+                                    hostname: {
+                                        type: 'string',
+                                        description: 'Machine hostname'
+                                    },
+                                    platform: {
+                                        type: 'string',
+                                        description: 'Platform (win32, darwin, linux)'
+                                    },
+                                    memory: {
+                                        type: 'number',
+                                        description: 'Total memory in bytes (auto-detected by local proxy)'
+                                    },
+                                    cpus: {
+                                        type: 'number',
+                                        description: 'CPU count (auto-detected by local proxy)'
+                                    }
+                                },
+                                required: ['hostname', 'platform', 'memory', 'cpus'],
+                                additionalProperties: true
+                            },
+                            repo: {
+                                type: 'object',
+                                description: 'Optional repository context. Hosted marketplace sessions default to FRAIM public catalog context when omitted.',
+                                properties: {
+                                    url: {
+                                        type: 'string',
+                                        description: 'Git repository URL'
+                                    },
+                                    owner: {
+                                        type: 'string',
+                                        description: 'Repository owner'
+                                    },
+                                    namespace: {
+                                        type: 'string',
+                                        description: 'Repository namespace (GitLab group/subgroup path)'
+                                    },
+                                    name: {
+                                        type: 'string',
+                                        description: 'Repository name'
+                                    },
+                                    projectPath: {
+                                        type: 'string',
+                                        description: 'Repository project path (GitLab, for example group/subgroup/repo)'
+                                    },
+                                    branch: {
+                                        type: 'string',
+                                        description: 'Current branch'
+                                    }
+                                },
+                                required: ['url'],
+                                additionalProperties: true
+                            }
+                        }),
+                    issueTracking: {
+                        type: 'object',
+                        description: 'Optional issue tracking context for split-provider setups (for example Jira + GitHub)',
+                        properties: {
+                            provider: {
+                                type: 'string',
+                                description: 'Issue tracking provider',
+                                enum: ['jira', 'github', 'ado', 'linear', 'gitlab']
+                            },
+                            owner: {
+                                type: 'string',
+                                description: 'Issue tracking owner (GitHub)'
+                            },
+                            name: {
+                                type: 'string',
+                                description: 'Issue tracking repository or project name'
+                            },
+                            organization: {
+                                type: 'string',
+                                description: 'Issue tracking organization (ADO)'
+                            },
+                            project: {
+                                type: 'string',
+                                description: 'Issue tracking project (ADO)'
+                            },
+                            namespace: {
+                                type: 'string',
+                                description: 'Issue tracking namespace (GitLab group/subgroup path)'
+                            },
+                            projectPath: {
+                                type: 'string',
+                                description: 'Issue tracking project path (GitLab, for example group/subgroup/repo)'
+                            },
+                            baseUrl: {
+                                type: 'string',
+                                description: 'Base URL for issue tracker (for example myorg.atlassian.net)'
+                            },
+                            projectKey: {
+                                type: 'string',
+                                description: 'Project key or namespace for issue IDs'
+                            }
+                        },
+                        required: ['provider'],
+                        additionalProperties: true
+                    }
+                },
+                required: ['agent']
+            }
+        },
+        {
+            name: 'get_fraim_file',
+            description: `Get a specific skill, rule, or reference file from the FRAIM registry by path.
+
+For running FRAIM jobs, use get_fraim_job instead — do NOT call get_fraim_file for job execution.
+
+Examples:
+- get_fraim_file({ path: "skills/communication/active-listening.md" })
+- get_fraim_file({ path: "rules/local-development.md" })`,
+            annotations: readOnlyClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    path: {
+                        type: 'string',
+                        description: 'Path to the file (e.g., skills/communication/active-listening.md, rules/local-development.md, templates/specs/FEATURESPEC-TEMPLATE.md)'
+                    },
+                    raw: {
+                        type: 'boolean',
+                        description: 'If true, returns the raw unparsed content without any MCP headers or parsing.'
+                    }
+                },
+                required: requiredWithSession(['path'])
+            }
+        },
+        {
+            name: 'get_fraim_job',
+            description: `Execute a named FRAIM job after explicit FRAIM activation. Call this tool whenever the user asks to run, start, or execute a named FRAIM job. Returns phased instructions — follow each phase and call seekMentoring to advance phases.
+
+Do NOT use get_fraim_file to load job content. Always use get_fraim_job for job execution.
+
+Examples:
+- get_fraim_job({ job: "feature-specification" })
+- get_fraim_job({ job: "technical-design" })
+- get_fraim_job({ job: "feature-implementation" })`,
+            annotations: readOnlyClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    job: {
+                        type: 'string',
+                        description: 'Job name (e.g., "feature-implementation", "technical-design", "feature-specification")'
+                    },
+                    raw: {
+                        type: 'boolean',
+                        description: 'If true, returns the raw unparsed markdown content of the job.'
+                    }
+                },
+                required: requiredWithSession(['job'])
+            }
+        },
+        {
+            name: 'list_fraim_jobs',
+            description: `List the FRAIM job catalog. Use this when the user asks what FRAIM jobs are available, asks for FRAIM job recommendations, or after explicit FRAIM activation when local stubs are unavailable. Do not use this for ordinary requests. If no exact or high-confidence job match exists, do not pick the nearest job; continue normally or ask one concise clarification.`,
+            annotations: readOnlyClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty
+                },
+                required: requiredWithSession([])
+            }
+        },
+        {
+            name: 'file_fraim_github_issue',
+            description: `Create a GitHub issue in the FRAIM repository.
+      
+Use this tool when you need to report a bug, request a feature from FRAIM. Do not use this tool to file issues in other repositories.
+Supports dry-run mode to preview the operation.
+
+This tool accepts text only. If visual evidence is needed, upload images to a stable shared HTTPS URL first and include those URLs in the issue body as markdown images or plain links. Do not include local file paths or base64-encoded image data in the issue body.`,
+            annotations: writeOpenWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    title: {
+                        type: 'string',
+                        description: 'Title of the issue'
+                    },
+                    body: {
+                        type: 'string',
+                        description: 'Body/Content of the issue. If visual evidence is needed, include shared HTTPS image URLs in the body; do not include local file paths or base64 image data.'
+                    },
+                    labels: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of labels to apply'
+                    },
+                    dryRun: {
+                        type: 'boolean',
+                        description: 'If true, simulates the creation without actually notifying GitHub'
+                    }
+                },
+                required: requiredWithSession(['title', 'body'])
+            }
+        },
+        {
+            name: 'list_my_fraim_github_issues',
+            description: `List issues the current FRAIM user filed into the FRAIM GitHub repository.
+
+This tool is the read-side companion to file_fraim_github_issue. Use it when you need a simple list of issues filed by the current FRAIM user into the FRAIM repository.
+
+Returns only:
+- issue number
+- title
+- status
+- created date
+
+Do not use this tool for other repositories or external project issue trackers.`,
+            annotations: readOnlyOpenWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    limit: {
+                        type: 'integer',
+                        description: 'Optional maximum number of issues to return. Defaults to 20 and is capped at 100.'
+                    }
+                },
+                required: requiredWithSession([])
+            }
+        },
+        {
+            name: 'seekMentoring',
+            description: `Get the instructions for the current FRAIM phase, advance to the next phase, or ask for help on the active phase after fraim_connect starts the session.`,
+            annotations: writeClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    jobName: {
+                        type: 'string',
+                        description: 'Name of the job you are following',
+                    },
+                    jobId: {
+                        type: 'string',
+                        description: 'Job ID returned by get_fraim_job. Required for tracking job execution and completion.'
+                    },
+                    issueNumber: {
+                        type: 'string',
+                        description: 'Issue number or Task ID you are working on'
+                    },
+                    currentPhase: {
+                        type: 'string',
+                        description: 'The phase you are currently in or have just finished (e.g., "implement-scoping"). For initial workflow start, use "starting".'
+                    },
+                    status: {
+                        type: 'string',
+                        description: 'Status of your work in the current phase',
+                        enum: ['starting', 'complete', 'incomplete', 'failure']
+                    },
+                    findings: {
+                        type: 'object',
+                        description: 'Your findings, summaries, or results from the current phase (required for status="complete")',
+                        properties: {
+                            uncertainties: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Any unclear aspects that need clarification'
+                            }
+                        },
+                        additionalProperties: true
+                    },
+                    evidence: {
+                        type: 'object',
+                        description: 'Structured evidence or data collected (e.g., prospect counts, test results). Submit phases should put review artifacts in evidence.reviewHandoff rather than printing raw JSON to the user. Retrospective phases may put follow-on job recommendations in evidence.nextJobRecommendations (array of { jobId, label, reason?, contextSummary? }, max 3) so the work surface can offer them as next steps.',
+                        additionalProperties: true
+                    }
+                },
+                required: requiredWithSession(['jobName', 'jobId', 'issueNumber', 'currentPhase', 'status'])
+            }
+        }
+    ];
+};
+exports.getToolDefinitions = getToolDefinitions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.277",
+  "version": "2.0.279",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {
@@ -19,8 +19,9 @@
     "dist/src/services/",
     "dist/src/api/",
     "dist/src/middleware/",
-    "dist/src/models/",
-    "dist/src/types/",
+    "dist/src/models/",
+    "dist/src/mcp/",
+    "dist/src/types/",
     "dist/src/utils/",
     "bin/fraim.js",
     "public/first-run/",