fraim-hub 2.0.278 → 2.0.280

package/dist/src/ai-hub/bundled-asset-resolver.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBundledAssetPath = resolveBundledAssetPath;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Resolves a bundled asset that ships at a different relative depth depending on how the
+ * Hub is launched (`npx fraim-hub` unpacked, `npm run hub:desktop`, or a packaged app).
+ *
+ * Checks, in order: relative to the current working directory, then relative to
+ * `moduleDir` (pass `__dirname` from the caller) two and three levels up - the depths
+ * `dist/src/ai-hub/` sits at relative to a package root. Returns the first path that
+ * exists on disk, or null if none do, so callers can fall back rather than crash on a
+ * packaging gap.
+ *
+ * No Electron import here on purpose: `electron` resolves to a plain path string outside
+ * an Electron process, so anything that touches it can only run inside one. Keeping this
+ * resolution logic Electron-free is what makes it unit-testable with plain `node:test`.
+ */
+function resolveBundledAssetPath(relativePath, moduleDir, cwd = process.cwd()) {
+    const candidates = [
+        path_1.default.resolve(cwd, relativePath),
+        path_1.default.resolve(moduleDir, '..', '..', relativePath),
+        path_1.default.resolve(moduleDir, '..', '..', '..', relativePath),
+    ];
+    return candidates.find((c) => fs_1.default.existsSync(c)) ?? null;
+}

package/dist/src/ai-hub/desktop-main.js

@@ -15,6 +15,7 @@ const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const version_utils_1 = require("../cli/utils/version-utils");
 const hub_runtime_file_1 = require("./hub-runtime-file");
 const window_open_decision_1 = require("./window-open-decision");
+const bundled_asset_resolver_1 = require("./bundled-asset-resolver");
 // ---------------------------------------------------------------------------
 // State
 // ---------------------------------------------------------------------------
@@ -61,19 +62,22 @@ function applyUserDataOverride() {
     electron_1.app.setPath('userData', userDataDir);
 }
 // ---------------------------------------------------------------------------
-// Tray icon resolution — prefers bundled icon, falls back to a 1×1 empty image
-// so the app never crashes if assets aren't present.
+// App icon — the FRAIM logo (#1329), used for the window/taskbar/dock icon
+// and, downscaled, the system tray. Falls back to Electron's own default
+// (window/dock) or an empty image (tray) so a packaging gap never crashes
+// the app. Path resolution itself lives in bundled-asset-resolver.ts, which
+// has no Electron import and so can be unit-tested directly.
 // ---------------------------------------------------------------------------
+const APP_ICON_RELATIVE_PATH = 'public/ai-hub/fraim-icon.png';
+function resolveAppIcon() {
+    const iconPath = (0, bundled_asset_resolver_1.resolveBundledAssetPath)(APP_ICON_RELATIVE_PATH, __dirname);
+    return iconPath ? electron_1.nativeImage.createFromPath(iconPath) : null;
+}
 function resolveTrayIcon() {
-    const candidates = [
-        path_1.default.resolve(process.cwd(), 'extensions/office-word/icon-64.png'),
-        path_1.default.resolve(__dirname, '..', '..', 'extensions/office-word/icon-64.png'),
-        path_1.default.resolve(__dirname, '..', '..', '..', 'extensions/office-word/icon-64.png'),
-    ];
-    for (const c of candidates) {
-        if (fs_1.default.existsSync(c))
-            return electron_1.nativeImage.createFromPath(c).resize({ width: 16, height: 16 });
-    }
+    const iconPath = (0, bundled_asset_resolver_1.resolveBundledAssetPath)(APP_ICON_RELATIVE_PATH, __dirname)
+        ?? (0, bundled_asset_resolver_1.resolveBundledAssetPath)('extensions/office-word/icon-64.png', __dirname);
+    if (iconPath)
+        return electron_1.nativeImage.createFromPath(iconPath).resize({ width: 16, height: 16 });
     return electron_1.nativeImage.createEmpty();
 }
 // ---------------------------------------------------------------------------
@@ -210,6 +214,7 @@ async function createWindow(url, runtimeId = process.env.FRAIM_HUB_RUNTIME_ID ||
     const isWin = process.platform === 'win32';
     mainWindow = new electron_1.BrowserWindow({
         title: displayName(runtimeId),
+        icon: resolveAppIcon() ?? undefined,
         width,
         height,
         minWidth: 1200,
@@ -407,6 +412,14 @@ async function bootstrap() {
     });
     await electron_1.app.whenReady();
     electron_1.app.setName(displayName(options.runtimeId));
+    // macOS reads the dock icon from the app bundle once packaged, but an
+    // unpackaged `npm run hub:desktop` / `npx fraim-hub` run shows Electron's
+    // own icon there unless we set it explicitly (#1329).
+    if (process.platform === 'darwin') {
+        const dockIcon = resolveAppIcon();
+        if (dockIcon)
+            electron_1.app.dock?.setIcon(dockIcon);
+    }
     // First-launch housekeeping (idempotent, fast on subsequent runs)
     ensureLoginItem();
     configureAutoUpdater();

package/dist/src/ai-hub/hosts.js

@@ -3,11 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createHubEvent = exports.createHubMessage = exports.ScriptedHostRuntime = exports.FakeHostRuntime = exports.CliHostRuntime = void 0;
+exports.createHubEvent = exports.createHubMessage = exports.ScriptedHostRuntime = exports.FakeHostRuntime = exports.CliHostRuntime = exports.COMPACT_TASK_FAILURE_PATTERN = void 0;
 exports.parseSeekMentoringSignal = parseSeekMentoringSignal;
 exports.parseFraimJobLoadSignal = parseFraimJobLoadSignal;
 exports.parseUsageSignal = parseUsageSignal;
 exports.parseAgentIdentitySignal = parseAgentIdentitySignal;
+exports.escapeWindowsArg = escapeWindowsArg;
+exports.resolveHostInvocation = resolveHostInvocation;
 exports.__setAgentAvailabilityPathForTests = __setAgentAvailabilityPathForTests;
 exports.invalidateEmployeeDetectionCache = invalidateEmployeeDetectionCache;
 exports.__clearEmployeeDetectionMemoryCacheForTests = __clearEmployeeDetectionMemoryCacheForTests;
@@ -25,6 +27,9 @@ exports.supportsDirectPath = supportsDirectPath;
 exports.buildDirectStartPlan = buildDirectStartPlan;
 exports.buildDirectContinuePlan = buildDirectContinuePlan;
 exports.parseHostLine = parseHostLine;
+exports.detectCodexCompactTaskFailure = detectCodexCompactTaskFailure;
+exports.describeSpawnError = describeSpawnError;
+exports.buildHostSpawnEnv = buildHostSpawnEnv;
 exports.findGeminiSessionIdForPrompt = findGeminiSessionIdForPrompt;
 const crypto_1 = require("crypto");
 const child_process_1 = require("child_process");
@@ -34,6 +39,7 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const manager_turns_1 = require("./manager-turns");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
+const command_resolution_1 = require("../cli/mcp/command-resolution");
 const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
 const configured_agents_1 = require("./configured-agents");
 const pack_home_1 = require("../cli/utils/pack-home");
@@ -816,32 +822,35 @@ function quoteWindowsArg(value) {
     }
     return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, '$1$1')}"`;
 }
+// Exported for reuse by server.ts's hubCommandVersion(), which builds a
+// similar single cmd.exe command-line string around a resolved absolute path.
 function escapeWindowsArg(value) {
     return /[\s"]/u.test(value) ? quoteWindowsArg(value) : value;
 }
+// Issue #1284/#1285 (Implementation Strategy §0): resolve the real agent CLI
+// binary fresh at every launch instead of handing a bare command name to
+// `spawn`/`cmd.exe` and trusting whatever PATH the process happens to have.
+// Covers every call site that builds an invocation through this function:
+// spawnHostProcess (real job launches) and both version-probe helpers.
+// Exported for direct unit testing.
 function resolveHostInvocation(plan) {
+    const resolvedPlan = { ...plan, command: (0, command_resolution_1.resolveManagedCommand)(plan.command) };
     if (process.platform !== 'win32') {
-        return plan;
+        return resolvedPlan;
     }
-    const [command, ...args] = [plan.command, ...plan.args];
+    const [command, ...args] = [resolvedPlan.command, ...resolvedPlan.args];
+    // Issue #1284/#1285: `command` can now be an absolute path resolved by
+    // resolveManagedCommand() (e.g. a temp/user directory containing a space),
+    // not just a bare command name — it needs the same escaping the args
+    // already get before joining into the single cmd.exe command-line string.
     return {
         command: 'cmd.exe',
-        args: ['/d', '/s', '/c', [command, ...args.map(escapeWindowsArg)].join(' ')],
+        args: ['/d', '/s', '/c', [command, ...args].map(escapeWindowsArg).join(' ')],
     };
 }
-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);
-}
 function buildAgentVersionProbePath(basePath) {
     const withoutManaged = (0, managed_agent_paths_1.stripManagedAgentBinDirsFromPath)(basePath);
-    const withoutProjectBins = stripProjectLocalNodeBinDirs(withoutManaged);
+    const withoutProjectBins = (0, managed_agent_paths_1.stripProjectLocalNodeBinDirs)(withoutManaged);
     return (0, managed_agent_paths_1.appendBinDirsToPath)(withoutProjectBins, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
 }
 // Single source for the probe environment, shared by the sync and async probes so the two
@@ -1795,6 +1804,26 @@ function scrubGeminiAssistantLine(line) {
     const scrubbed = line.replace(/\[Thought:\s*true\]\s*/gi, '').trim();
     return scrubbed.length > 0 ? scrubbed : null;
 }
+// Issue #1284: Codex's own error text for a rejected remote context-compaction
+// call, e.g. "Error running remote compact task: unexpected status 404 Not
+// Found: ...". Exported so `server.ts`'s `classifyExit()` can recognize a
+// repeat of this exact signature from `run.lastHostError` without duplicating
+// the pattern.
+exports.COMPACT_TASK_FAILURE_PATTERN = /Error running remote compact task/;
+// Issue #1284 (Defect C): Codex reports a remote compact-endpoint failure as
+// plain stderr text, not one of the JSON shapes `parseHostLine` understands,
+// so it silently fell through to `{ raw }` with no `hostError`/classification
+// signal at all — the run then retried blindly against the same doomed call.
+// Surfacing it as `hostError` here lets `classifyExit()` recognize and
+// short-circuit a repeat instead of exhausting the retry budget. A pure,
+// directly-testable function, matching the shape of `parseSeekMentoringSignal`
+// et al. rather than inlining this check into `wireHostProcess`'s closure.
+function detectCodexCompactTaskFailure(line) {
+    if (exports.COMPACT_TASK_FAILURE_PATTERN.test(line) && /status 4\d\d/.test(line)) {
+        return { hostError: line, raw: line };
+    }
+    return null;
+}
 function wireHostProcess(hostId, child, handlers) {
     const wire = (buffer, channel) => {
         let pending = '';
@@ -1815,6 +1844,11 @@ function wireHostProcess(hostId, child, handlers) {
                     if (suppressCodexModelRefreshStderr) {
                         continue;
                     }
+                    const compactFailure = detectCodexCompactTaskFailure(line);
+                    if (compactFailure) {
+                        handlers.onEvent(compactFailure, channel);
+                        continue;
+                    }
                 }
                 const parsed = parseHostLine(hostId, line);
                 if (parsed.message || parsed.sessionId || parsed.raw) {
@@ -1833,16 +1867,55 @@ function wireHostProcess(hostId, child, handlers) {
     };
     wire(child.stdout, 'stdout');
     wire(child.stderr, 'stderr');
-    child.on('close', (code) => handlers.onExit(code));
+    // Issue #1327: preserve signal information so SIGSEGV kills (code=null,
+    // signal='SIGSEGV') are NOT treated as clean exits by classifyExit's
+    // `exitCode ?? 0` guard. Pass -1 for any signal-terminated child so the
+    // non-zero branch fires and recovery is attempted.
+    child.on('close', (code, signal) => handlers.onExit(signal ? -1 : code));
+    // Issue #1327: without this listener, an OS-level spawn failure (EAGAIN,
+    // ENOENT, EACCES) fires an 'error' event on the ChildProcess. An unhandled
+    // EventEmitter 'error' throws synchronously and crashes the Hub process.
+    // Surface the failure as a human-readable hostError so the run's terminal
+    // message names the cause. 'close' still fires after 'error' for spawn
+    // failures, so handlers.onExit is called by the close listener above.
+    child.on('error', (err) => {
+        handlers.onEvent({ hostError: describeSpawnError(err) }, 'system');
+    });
     return child;
 }
+function describeSpawnError(err) {
+    if (err.code === 'ENOENT') {
+        return `Agent binary not found${err.path ? ` (${err.path})` : ''}. Ensure the agent CLI is installed and on PATH.`;
+    }
+    if (err.code === 'EACCES') {
+        return `Permission denied starting agent process${err.path ? ` (${err.path})` : ''}. Check executable permissions.`;
+    }
+    if (err.code === 'EAGAIN') {
+        return `Could not start agent process: system resources temporarily unavailable (EAGAIN). The OS process limit may have been reached; try again in a moment.`;
+    }
+    return `Failed to start agent process: ${err.message}`;
+}
+// Issue #1284/#1285 (Defect D): the version-probe path already excludes
+// project-local `node_modules/.bin` shims via `versionProbeEnv()`; the real
+// job-spawn path built `env.PATH` straight from `process.env`/`plan.env` with
+// no such filtering, so a poisoned PATH silently ran the wrong binary on the
+// one path that actually executes jobs. Reuse the exact same construction the
+// probe uses so the two can never disagree again.
+// Exported for direct unit testing of the Defect D fix (issue #1284/#1285):
+// asserting spawnHostProcess's environment construction matches
+// versionProbeEnv()'s filtering without spawning a real child process.
+function buildHostSpawnEnv(plan) {
+    const merged = plan.env ? { ...process.env, ...plan.env } : { ...process.env };
+    const resolvedPath = buildAgentVersionProbePath(merged.PATH ?? merged.Path);
+    return { ...merged, PATH: resolvedPath, Path: resolvedPath };
+}
 function spawnHostProcess(hostId, plan, projectPath, handlers) {
     const invocation = resolveHostInvocation(plan);
     const startedAtMs = Date.now();
     const child = (0, child_process_1.spawn)(invocation.command, invocation.args, {
         cwd: projectPath,
         stdio: ['pipe', 'pipe', 'pipe'],
-        env: plan.env ? { ...process.env, ...plan.env } : process.env,
+        env: buildHostSpawnEnv(plan),
     });
     if (typeof plan.stdin === 'string') {
         child.stdin.write(plan.stdin);

package/dist/src/ai-hub/server.js

@@ -38,6 +38,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findAvailablePortExcluding = exports.findAvailablePort = exports.AiHubServer = exports.HostConfigStore = exports.DeploymentStore = void 0;
 exports.configureFraimForHubAgent = configureFraimForHubAgent;
+exports.hubCommandVersion = hubCommandVersion;
 exports.buildOpenFileInvocation = buildOpenFileInvocation;
 const express_1 = __importDefault(require("express"));
 const path_1 = __importDefault(require("path"));
@@ -55,6 +56,7 @@ const job_visualization_1 = require("../core/job-visualization");
 const custom_employees_1 = require("./custom-employees");
 const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
 const hosts_1 = require("./hosts");
+const command_resolution_1 = require("../cli/mcp/command-resolution");
 const configured_agents_1 = require("./configured-agents");
 const host_session_state_1 = require("./host-session-state");
 const url_safety_1 = require("./url-safety");
@@ -69,6 +71,8 @@ const restart_recovery_policy_1 = require("./restart-recovery-policy");
 const remote_hub_gateway_1 = require("./remote-hub-gateway");
 const managed_browser_1 = require("./managed-browser");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
+const managed_agent_install_1 = require("../cli/utils/managed-agent-install");
+const agent_cli_health_checks_1 = require("../cli/doctor/checks/agent-cli-health-checks");
 const user_config_1 = require("../cli/utils/user-config");
 const version_utils_1 = require("../cli/utils/version-utils");
 const hub_latest_version_1 = require("./hub-latest-version");
@@ -1499,17 +1503,26 @@ async function configureFraimForHubAgent(hubId) {
         return { configured: false, error: e instanceof Error ? e.message : String(e) };
     }
 }
+// Exported for direct unit testing of the Defect D fix (issue #1284/#1285):
+// asserting this resolves via a real system install and skips a poisoned
+// project-local node_modules/.bin entry, without spinning up a full server.
 function hubCommandVersion(command, extraBinDirs, basePath) {
     if (process.env.NODE_ENV === 'test' && process.env.FRAIM_TEST_HUB_COMMAND_VERSION_EMPTY === '1') {
         return null;
     }
-    const executable = process.platform === 'win32' ? 'cmd.exe' : command;
-    const args = process.platform === 'win32'
-        ? ['/d', '/s', '/c', `${command} --version`]
-        : ['--version'];
     const pathValue = extraBinDirs && extraBinDirs.length > 0
         ? (0, managed_agent_paths_1.appendBinDirsToPath)(basePath ?? process.env.PATH, extraBinDirs)
         : basePath;
+    // Issue #1284/#1285 (Defect D, §0): resolve to a real absolute path — with
+    // project-local node_modules/.bin stripped — instead of handing the bare
+    // command name to cmd.exe's own PATH search, which does not exclude those
+    // shims. Falls back to the bare command (today's behavior, resolves to
+    // null below) when no system install is found on the constructed PATH.
+    const resolvedCommand = (0, command_resolution_1.getSystemCommandPath)(command, pathValue ?? process.env.PATH) || command;
+    const executable = process.platform === 'win32' ? 'cmd.exe' : resolvedCommand;
+    const args = process.platform === 'win32'
+        ? ['/d', '/s', '/c', `${(0, hosts_1.escapeWindowsArg)(resolvedCommand)} --version`]
+        : ['--version'];
     const env = pathValue === undefined ? undefined : { ...process.env, PATH: pathValue };
     const result = (0, child_process_1.spawnSync)(executable, args, { encoding: 'utf8', timeout: 5000, ...(env ? { env } : {}) });
     if (result.status !== 0 || result.error)
@@ -1893,6 +1906,22 @@ function isHumanActionGate(run) {
     const lastEntry = phaseHistory.length > 0 ? phaseHistory[phaseHistory.length - 1] : null;
     return lastEntry?.latestStatus === 'incomplete' || lastEntry?.latestStatus === 'failure';
 }
+// Issue #1284 (Defect C): a 404/4xx on Codex's remote context-compaction
+// endpoint means the installed Codex build's compact request is not accepted
+// by the current backend (a version incompatibility) — not a transient
+// failure blind retry can recover from. Reads the most recent host error
+// already captured on the run (recordHostEvent sets `run.lastHostError` from
+// the stderr signal wireHostProcess raises for this exact line).
+function detectCompactFailureSignature(run) {
+    const error = run.lastHostError;
+    if (error && hosts_1.COMPACT_TASK_FAILURE_PATTERN.test(error) && /status 4\d\d/.test(error)) {
+        return 'compact-4xx';
+    }
+    return null;
+}
+const COMPACT_INCOMPATIBLE_NOTE = "Codex's remote context-compaction call was rejected by the backend (404). "
+    + 'This usually means the installed Codex CLI is out of date. Run `codex update`, confirm `codex --version` '
+    + 'matches the latest release, and retry.';
 // #1275: true when the host reported an active local_bash task. These are
 // intentional async continuations — the agent ended its turn knowing bash was
 // running, intending to check results in the next turn. In -p mode Claude Code
@@ -1928,11 +1957,21 @@ function classifyExit(run, exitCode) {
     if (run.stoppedByUser) {
         return { action: 'park', pauseReason: 'stopped' };
     }
-    const code = exitCode ?? 0;
+    // Issue #1327: null exit code means the child was killed by a signal (e.g.
+    // SIGSEGV). wireHostProcess now passes -1 in that case, but guard here too:
+    // any null that reaches classifyExit must not be treated as a clean exit.
+    const code = exitCode ?? -1;
     if (code !== 0) {
+        // Issue #1284: a repeat of the exact same classified-unrecoverable
+        // signature short-circuits to 'error' immediately instead of exhausting
+        // the retry budget against a call that will fail identically every time.
+        const signature = detectCompactFailureSignature(run);
+        if (signature && run.lastRecoverySignature === signature) {
+            return { action: 'error', pauseReason: 'error', systemNote: COMPACT_INCOMPATIBLE_NOTE };
+        }
         const attempts = (run.recoveryAttempts ?? 0);
         if (attempts < MAX_RECOVERY_ATTEMPTS) {
-            return { action: 'resume', pauseReason: 'working' };
+            return { action: 'resume', pauseReason: 'working', matchedSignature: signature ?? undefined };
         }
         return { action: 'error', pauseReason: 'error' };
     }
@@ -2801,15 +2840,28 @@ class AiHubServer {
         appendHostMessage(run, hostId, event, channel);
         // Issue #1221: a real assistant reply proves the host recovered, so a
         // previously recorded error is stale and must not keep haunting the next
-        // exit/recovery message.
+        // exit/recovery message. Issue #1284: a classified recovery signature is
+        // scoped to the same failure recurring; a genuine recovery must not let
+        // it bleed into an unrelated later failure in the same run.
         if (event.message && channel === 'stdout') {
             run.lastHostError = undefined;
+            run.lastRecoverySignature = undefined;
         }
         if (event.raw) {
             applyDelegationLedgerProjection(run, event.raw);
             try {
                 const ref = this.rawEventLogStore.append((0, conversation_store_1.conversationScopeKey)(run.scope, run.projectPath), run.conversationId || run.id, run.id, { channel, text: event.raw });
                 run.eventLogRefs = upsertEventLogRef(run.eventLogRefs, ref);
+                // Issue #1327: if the Hub crashes before the debounced conversation
+                // flush fires, run.eventLogRefs is lost from the store and the raw
+                // event log on disk becomes unreachable. Flush immediately on the
+                // first event so the ref is always on disk within the same synchronous
+                // turn. Subsequent events use the normal debounced path.
+                if (ref.eventCount === 1) {
+                    // Issue #1009: a delegated child's first raw event must not steal the
+                    // active board slot from its parent/orchestrator conversation.
+                    this.persistRunConversationNow(run, run.managedByRunId ? undefined : (run.conversationId || run.id));
+                }
             }
             catch (error) {
                 run.events.push((0, hosts_1.createHubEvent)('system', 'Raw host event logging failed; visible conversation state was preserved.'));
@@ -2993,7 +3045,11 @@ class AiHubServer {
         const run = this.runRegistry.get(runId);
         if (!run)
             return;
-        this.persistRunConversationNow(run, activeId ?? run.conversationId ?? run.id);
+        // Issue #1009: a delegated child run finishing or parking must not steal the
+        // active board slot from its parent/orchestrator conversation. Only a
+        // standalone (non-delegated) run's own finalize should claim activeId.
+        const resolvedActiveId = run.managedByRunId ? undefined : (activeId ?? run.conversationId ?? run.id);
+        this.persistRunConversationNow(run, resolvedActiveId);
         console.info('[ai-hub] hub.conversation_projection.finalized', {
             conversationId: run.conversationId || run.id,
             runId,
@@ -3014,6 +3070,7 @@ class AiHubServer {
             current.status = 'running';
             current.sessionId = undefined;
             current.recoveryAttempts = 0;
+            current.lastRecoverySignature = undefined;
             current.pauseReason = 'working';
             current.events.push((0, hosts_1.createHubEvent)('system', 'Codex resume failed because the saved session was missing a required reasoning item; starting a fresh handoff-backed turn from Hub conversation context.'));
         });
@@ -5174,6 +5231,14 @@ class AiHubServer {
             if (!option)
                 return res.status(400).json({ error: `Unknown agent: ${hubId}` });
             try {
+                // Issue #1285 (Implementation Strategy §3): self-heal any shim orphaned
+                // in the legacy flat managed directory before this run's version checks
+                // consult FRAIM's managed PATH, so a stale build can no longer shadow
+                // the current one. Idempotent; cheap enough to run on every call.
+                const removedShims = (0, managed_agent_paths_1.cleanupOrphanedManagedShims)();
+                if (removedShims.length > 0) {
+                    console.warn(`[ai-hub] install-agent: removed orphaned managed shim(s): ${removedShims.join(', ')}`);
+                }
                 const systemPath = (0, managed_agent_paths_1.stripManagedAgentBinDirsFromPath)(process.env.PATH);
                 const existingVersion = hubCommandVersion(option.launchCommand, undefined, systemPath);
                 if (existingVersion) {
@@ -5200,62 +5265,19 @@ class AiHubServer {
                         loginHint: `Once installed, click "Check if Ready" to verify ${option.label} is on your PATH.`,
                     });
                 }
-                let standardInstallError = null;
-                try {
-                    await hubRunProcess('npm', ['install', '-g', option.installPackage], {
-                        PATH: systemPath,
-                        npm_config_prefix: undefined,
-                        NPM_CONFIG_PREFIX: undefined,
-                    });
-                    const standardVersion = hubCommandVersion(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
-                            ? hubCommandVersion(option.launchCommand, npmGlobalBinDirs, systemPath)
-                            : null);
-                    if (standardVersionWithNpmBin) {
-                        if (npmGlobalBinDirs.length > 0) {
-                            process.env.PATH = (0, managed_agent_paths_1.appendBinDirsToPath)(systemPath, npmGlobalBinDirs);
-                        }
-                        const mcp = await configureFraimForHubAgent(hubId);
-                        if (!mcp.configured) {
-                            console.warn(`[ai-hub] install-agent: FRAIM add-ide did not run for standard ${option.label}: ${mcp.error || 'unknown reason'}`);
-                        }
-                        // Issue #1010: something is now installed that was not before, so the cached
-                        // agent-availability answer is stale. Drop it here rather than waiting out the
-                        // TTL, so the newly installed CLI shows as available immediately.
-                        (0, hosts_1.invalidateEmployeeDetectionCache)();
-                        return res.json({
-                            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 — complete sign-in there, then click "Check if Ready".`,
-                            fraimConfigured: mcp.configured,
-                        });
-                    }
-                    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 = (0, managed_agent_paths_1.getManagedNodeRoot)();
-                fs_1.default.mkdirSync(prefix, { recursive: true });
-                await hubRunProcess('npm', ['install', '-g', option.installPackage], { npm_config_prefix: prefix });
-                const ver = hubCommandVersion(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: hubRunProcess, commandVersion: hubCommandVersion });
+                if (outcome.outcome === 'standard' && outcome.npmGlobalBinDirs.length > 0) {
+                    process.env.PATH = (0, managed_agent_paths_1.appendBinDirsToPath)(systemPath, outcome.npmGlobalBinDirs);
                 }
-                // Issue #747: run `add-ide` for the newly installed agent so the FRAIM MCP is wired in
-                // and its first run works (previously the agent launched with no `fraim` MCP server).
                 const mcp = await configureFraimForHubAgent(hubId);
                 if (!mcp.configured) {
-                    console.warn(`[ai-hub] install-agent: FRAIM add-ide did not run for ${option.label}: ${mcp.error || 'unknown reason'}`);
+                    console.warn(`[ai-hub] install-agent: FRAIM add-ide did not run for ${option.label} (${outcome.outcome} install): ${mcp.error || 'unknown reason'}`);
+                }
+                if (outcome.outcome === 'standard') {
+                    // Issue #1010: something is now installed that was not before, so the cached
+                    // agent-availability answer is stale. Drop it here rather than waiting out the
+                    // TTL, so the newly installed CLI shows as available immediately.
+                    (0, hosts_1.invalidateEmployeeDetectionCache)();
                 }
                 return res.json({
                     ok: true,
@@ -5293,16 +5315,27 @@ class AiHubServer {
                 });
             }
         });
-        this.app.post('/api/ai-hub/check-agent', (req, res) => {
+        this.app.post('/api/ai-hub/check-agent', async (req, res) => {
             const { hubId } = req.body;
             if (!hubId)
                 return res.status(400).json({ error: 'hubId is required.' });
             const option = hubAgentOption(hubId);
             if (!option)
                 return res.status(400).json({ error: `Unknown agent: ${hubId}` });
+            (0, managed_agent_paths_1.cleanupOrphanedManagedShims)();
             const ver = hubCommandVersion(option.launchCommand, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
             if (ver) {
-                return res.json({ ok: true, ready: true, message: `${option.label} is ready.` });
+                // Issue #1285 (§4): a manager who ran `codex update` and clicks "Check
+                // if Ready" should see PATH drift immediately rather than a bare pass.
+                const health = await (0, agent_cli_health_checks_1.checkAgentCliHealthByCommand)(option.launchCommand);
+                return res.json({
+                    ok: true,
+                    ready: true,
+                    message: `${option.label} is ready.`,
+                    ...(health && health.status !== 'passed'
+                        ? { driftWarning: health.message, driftSuggestion: health.suggestion }
+                        : {}),
+                });
             }
             return res.json({
                 ok: true,
@@ -6829,6 +6862,7 @@ class AiHubServer {
                         : createHubRecoveryEvent(current, exitCode, current.recoveryAttempts));
                 }
                 current.lastRecoveryAt = new Date().toISOString();
+                current.lastRecoverySignature = classification.matchedSignature ?? null;
                 current.pauseReason = 'working';
             });
             const refreshed = this.runRegistry.get(runId);

package/dist/src/ai-hub/ui-runtime.js

@@ -18,6 +18,7 @@ const BUNDLED_ASSETS = {
     styles: ['/ai-hub/styles.css', '/ai-hub/review.css'],
     scripts: ['/ai-hub/script.js'],
 };
+const REQUIRED_REMOTE_UI_CAPABILITIES = ['jobs.visualization'];
 function createAiHubBridgeInfo(options) {
     const remoteUiEnabled = options.remoteUiEnabled ?? process.env.FRAIM_HUB_REMOTE_UI === '1';
     return {
@@ -34,6 +35,7 @@ function createAiHubBridgeInfo(options) {
             'office.wordTaskpane': true,
             'customEmployees': true,
             'ui.serverDrivenRuntime': true,
+            'jobs.visualization': true,
         },
     };
 }
@@ -53,6 +55,12 @@ function evaluateHubUiManifestCompatibility(manifest, bridge) {
     if (missing) {
         return { compatible: false, updateRequired: true, reason: `missing-capability:${missing}` };
     }
+    const missingRequired = REQUIRED_REMOTE_UI_CAPABILITIES.find((capability) => {
+        return bridge.capabilities[capability] && !manifest.requiredCapabilities.includes(capability);
+    });
+    if (missingRequired) {
+        return { compatible: false, updateRequired: true, reason: `missing-required-capability:${missingRequired}` };
+    }
     return { compatible: true, updateRequired: false };
 }
 function runtimeAssetsForRelease(releaseId, manifest) {

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.278",
+  "version": "2.0.280",
   "description": "FRAIM Hub local companion package.",
   "bin": {
     "fraim-hub": "bin/fraim-hub.js",
@@ -19,6 +19,7 @@
     "dist/src/cli/api/get-provider-client.js",
     "dist/src/cli/api/provider-client.js",
     "dist/src/cli/commands/add-ide.js",
+    "dist/src/cli/doctor/checks/agent-cli-health-checks.js",
     "dist/src/cli/fraim-hub.js",
     "dist/src/cli/fraim-hub-2.js",
     "dist/src/cli/internal/device-flow-service.js",
@@ -37,6 +38,7 @@
     "dist/src/cli/setup/mcp-config-generator.js",
     "dist/src/cli/setup/provider-prompts.js",
     "dist/src/cli/utils/local-folder-sync.js",
+    "dist/src/cli/utils/managed-agent-install.js",
     "dist/src/cli/utils/managed-agent-paths.js",
     "dist/src/cli/utils/org-publish.js",
     "dist/src/cli/utils/pack-git-publish.js",
@@ -133,6 +135,7 @@
       "repo": "FRAIM"
     },
     "win": {
+      "icon": "build/icon.ico",
       "target": [
         "nsis",
         "portable"
@@ -144,6 +147,7 @@
       "allowToChangeInstallationDirectory": true
     },
     "mac": {
+      "icon": "build/icon.icns",
       "target": [
         "dmg",
         "zip"
@@ -152,6 +156,7 @@
       "gatekeeperAssess": false
     },
     "linux": {
+      "icon": "build/icon.png",
       "target": [
         "AppImage",
         "deb"
@@ -174,7 +179,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.278",
+    "fraim": "2.0.280",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",

package/public/ai-hub/script.js

@@ -3663,9 +3663,21 @@ function renderActive() {
   // this diff (same role/text/timestamp), so the "Queued N" / "Redirecting
   // now" badge would never disappear even after the server clears the field.
   const messageFingerprints = messages.map((message) => `${message.role || ''}\u0000${message.text || ''}\u0000${messageTimestamp(message) || ''}\u0000${message.deliveryStatus ? JSON.stringify(message.deliveryStatus) : ''}`);
-  const messagesMutated =
-    messages.length === renderedMessageCount &&
-    messageFingerprints.some((fingerprint, index) => fingerprint !== renderedMessageFingerprints[index]);
+  // Issue #1309: detect a mutation on any already-rendered row over the
+  // overlapping prefix, not only when the total count is unchanged. A
+  // continuation's first event commonly both clears a queued message's
+  // deliveryStatus AND appends a brand-new employee message in the same
+  // update (server.ts's onEvent runs recordHostEvent, which can push a new
+  // message, before the turnStarted clear-loop). Gating this check on
+  // `messages.length === renderedMessageCount` made that coincidence
+  // invisible: the badge-clearing row's fingerprint changed, but the
+  // guard's length check was false, so the full rebuild that is the only
+  // place a stale "Queued N" badge / data-pending tag gets removed never
+  // ran, orphaning it on that row forever.
+  const overlapCount = Math.min(messages.length, renderedMessageCount);
+  const messagesMutated = messageFingerprints
+    .slice(0, overlapCount)
+    .some((fingerprint, index) => fingerprint !== renderedMessageFingerprints[index]);
   // Issue #1249: capture the pre-reset count so "newly arrived" below reflects
   // genuinely new messages, not every row a messagesMutated full rebuild just
   // re-appended (e.g. an existing message's badge disappearing).
@@ -7373,18 +7385,9 @@ function renderJobCatalog(searchTerm = '') {
         lockBadge.textContent = `🔒 ${persona ? persona.displayName : job.requiredPersonaKey}`;
         btn.appendChild(lockBadge);
       }
-      // Issue #1278 R1/R2/R14: ⓘ button — skip ad-hoc row, stop propagation so job is not selected.
+      // Issue #1278 R1/R2/R14: skip ad-hoc row, stop propagation so job is not selected.
       if (job.id !== '__freeform__') {
-        const vizBtn = document.createElement('button');
-        vizBtn.type = 'button';
-        vizBtn.className = 'job-viz-btn';
-        vizBtn.textContent = 'ⓘ';
-        vizBtn.setAttribute('aria-label', `Visualize ${job.title}`);
-        vizBtn.addEventListener('click', (e) => {
-          e.stopPropagation();
-          tfOpenJobViz(job);
-        });
-        btn.appendChild(vizBtn);
+        btn.appendChild(tfCreateJobVizButton(job));
       }
       btn.addEventListener('click', () => {
         if (isLocked) {
@@ -15123,6 +15126,7 @@ function tfOpenAssignJob(employeeKey) {
     btn.type = 'button';
     btn.textContent = 'Assign';
     btn.addEventListener('click', () => tfAssignJobToEmployee(persona.key, job));
+    if (job.id !== '__freeform__') row.appendChild(tfCreateJobVizButton(job));
     row.appendChild(btn);
     return row;
   };
@@ -15199,8 +15203,23 @@ function tfCloseAssignJob() {
   if (m) m.hidden = true;
 }
 
+function tfCreateJobVizButton(job) {
+  const vizBtn = document.createElement('button');
+  vizBtn.type = 'button';
+  vizBtn.className = 'job-viz-btn';
+  vizBtn.textContent = 'ⓘ';
+  vizBtn.setAttribute('aria-label', `Visualize ${job.title || job.id}`);
+  vizBtn.title = `Visualize ${job.title || job.id}`;
+  vizBtn.addEventListener('click', (e) => {
+    e.stopPropagation();
+    const fromAssignJobModal = !!vizBtn.closest('#assign-job-modal');
+    tfOpenJobViz(job, { returnToAssignJob: fromAssignJobModal });
+  });
+  return vizBtn;
+}
+
 // Issue #1278 — Job Visualization Modal
-function tfOpenJobViz(job) {
+function tfOpenJobViz(job, options) {
   const modal = document.getElementById('job-viz-modal');
   if (!modal) return;
   const titleEl = document.getElementById('jv-title');
@@ -15208,6 +15227,13 @@ function tfOpenJobViz(job) {
   const badgeEl = document.getElementById('jv-badge');
   const phasesEl = document.getElementById('jv-phases');
   if (!phasesEl) return;
+  const assignModal = document.getElementById('assign-job-modal');
+  if (options && options.returnToAssignJob && assignModal && !assignModal.hidden) {
+    modal.dataset.returnToModal = 'assign-job-modal';
+    assignModal.hidden = true;
+  } else {
+    delete modal.dataset.returnToModal;
+  }
   if (titleEl) titleEl.textContent = job.title || job.id;
   if (intentEl) intentEl.textContent = '';
   if (badgeEl) badgeEl.hidden = true;
@@ -15295,8 +15321,16 @@ function tfOpenJobViz(job) {
 }
 function tfCloseJobViz() {
   const m = document.getElementById('job-viz-modal');
-  if (m) m.hidden = true;
+  const returnToModal = m ? m.dataset.returnToModal : '';
+  if (m) {
+    m.hidden = true;
+    delete m.dataset.returnToModal;
+  }
   jvHideTooltip();
+  if (returnToModal === 'assign-job-modal') {
+    const assignModal = document.getElementById('assign-job-modal');
+    if (assignModal) assignModal.hidden = false;
+  }
 }
 
 // Issue #1278 — fixed-position tooltip portal, escapes scroll-container clip

package/public/ai-hub/styles.css

@@ -6435,4 +6435,11 @@ img.eh-av { object-fit: cover; background: var(--surface); }
 }
 .job-viz-btn:hover { background: var(--soft); color: var(--accent); }
 .job-viz-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.job-row .job-viz-btn {
+  grid-column: auto; grid-row: auto;
+  flex-shrink: 0; width: 26px; height: 26px;
+  display: inline-flex; align-items: center; justify-content: center;
+  border: 1px solid var(--line); border-radius: 50%;
+  font-weight: 700;
+}
 /* ─── End Issue #1278 ────────────────────────────────────────────────────── */