fraim 2.0.301 → 2.0.302

package/README.md

@@ -312,7 +312,7 @@ Use these defaults:
 - `feature-specification` when the request is still fuzzy or needs clarified requirements, UX, or acceptance criteria.
 - `technical-design` after the spec is approved and you need the implementation plan, file touchpoints, and risk handling.
 - `feature-implementation` for code changes, bug fixes, and documentation updates that should be executed and validated.
-- `test-execution` when you need reproduction coverage, missing tests, or stronger regression protection before implementation.
+- `test-authoring` when you need reproduction coverage, missing tests, or stronger regression protection before implementation.
 - `browser-application-validation` or `ui-polish-validation` after user-facing UI changes or when the ask is explicitly browser validation.
 - `implementation-feature-review` when you need to verify the delivered behavior matches the feature spec.
 - `implementation-design-review` when you need to verify the code matches the approved technical design.

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

@@ -45,7 +45,8 @@ function probeVersion(commandPath) {
         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;
+        // Issue #1256 (AC-D1/D2): only stdout counts as a version — see versionFromProbeOutput.
+        return (0, managed_agent_paths_1.versionFromProbeOutput)(result.stdout, result.stderr);
     }
     catch {
         return null;
@@ -86,9 +87,32 @@ async function runAgentCliHealthCheck(cli) {
     const managedSearchPath = (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH);
     const managedPath = (0, command_resolution_1.getSystemCommandPath)(cli.command, managedSearchPath);
     if (!ambientPath && !managedPath) {
+        // Issue #1256 (AC-A3): before concluding the CLI is absent, try the same shared
+        // location-agnostic recovery the Hub's version probe and check-agent route use. This
+        // only changes the answer for a CLI this process's raw/managed PATH cannot see at all
+        // (e.g. doctor itself invoked from a PATH-truncated context) — it never overrides a
+        // drift verdict computed from a real ambient/managed hit above.
+        const recoveredSearchPath = (0, managed_agent_paths_1.buildRecoveredAgentPath)(process.env.PATH);
+        const recoveredPath = (0, command_resolution_1.getSystemCommandPath)(cli.command, recoveredSearchPath);
+        if (!recoveredPath) {
+            return {
+                status: 'passed',
+                message: `${cli.label} is not installed; nothing to check.`,
+            };
+        }
+        const recoveredVersion = probeVersion(recoveredPath);
+        if (!recoveredVersion) {
+            return {
+                status: 'error',
+                message: `${cli.label} is installed at ${recoveredPath} but failed to run (\`${cli.command} --version\` produced no output).`,
+                suggestion: `Reinstall ${cli.label}, then run "${cli.command} --version" again to confirm it's fixed.`,
+                details: { recoveredPath },
+            };
+        }
         return {
             status: 'passed',
-            message: `${cli.label} is not installed; nothing to check.`,
+            message: `${cli.label} is consistent (${recoveredVersion}).`,
+            details: { recoveredPath, recoveredVersion },
         };
     }
     const ambientVersion = ambientPath ? probeVersion(ambientPath) : null;

package/dist/src/cli/setup/ide-detector.js

@@ -3,12 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.expandPath = exports.findIDEByName = exports.getAllSupportedIDEs = exports.detectInstalledIDEs = exports.CLI_PROBE_CONFIGTYPES = exports.IDE_CONFIGS = void 0;
+exports.expandPath = exports.findIDEByName = exports.getAllSupportedIDEs = exports.detectInstalledIDEs = exports.CLI_PROBE_CONFIGTYPES = exports.IDE_CONFIGS = exports.detectCodexDesktop = exports.CODEX_DESKTOP_DOWNLOAD_URL = exports.CODEX_DESKTOP_BUNDLE_ID = void 0;
 exports.getAdapterConfigType = getAdapterConfigType;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const child_process_1 = require("child_process");
+const managed_agent_paths_1 = require("../utils/managed-agent-paths");
 /** Returns the configType to use for adapter file filtering. Falls back to configType when adapterConfigType is not set. */
 function getAdapterConfigType(ide) {
     return ide.adapterConfigType ?? ide.configType;
@@ -78,10 +79,12 @@ const guiAppDetect = (configSurfaceCheck, appName, options = {}) => {
 const availableByVersionProbe = (command) => {
     if (process.env.FRAIM_DETECT_DISABLE_CLI_PROBES === '1')
         return false;
+    const recoveredPath = (0, managed_agent_paths_1.buildRecoveredAgentPath)(process.env.PATH ?? process.env.Path);
+    const env = { ...process.env, PATH: recoveredPath, Path: recoveredPath };
     const result = process.platform === 'win32'
-        ? (0, child_process_1.spawnSync)('cmd.exe', ['/d', '/s', '/c', `${command} --version`], { encoding: 'utf8', timeout: 1500 })
-        : (0, child_process_1.spawnSync)(command, ['--version'], { encoding: 'utf8', timeout: 1500 });
-    return result.status === 0;
+        ? (0, child_process_1.spawnSync)('cmd.exe', ['/d', '/s', '/c', `${command} --version`], { encoding: 'utf8', timeout: 1500, env })
+        : (0, child_process_1.spawnSync)(command, ['--version'], { encoding: 'utf8', timeout: 1500, env });
+    return result.status === 0 && !result.error && (0, managed_agent_paths_1.versionFromProbeOutput)(result.stdout, result.stderr) !== null;
 };
 const detectClaude = () => {
     const paths = [
@@ -151,6 +154,73 @@ const detectCodexSurface = () => {
     ];
     return checkMultiplePaths(paths);
 };
+// Issue #1478: OpenAI folded the standalone Codex desktop app into the unified
+// ChatGPT desktop app (Codex is now a view inside it). That app has no CLI
+// config folder to detect and, unlike Claude Desktop, no local MCP config
+// file for FRAIM to bootstrap — so it is intentionally NOT an IDE_CONFIGS
+// entry. Adding it there would flow into ~13 other detectInstalledIDEs()
+// consumers (auto-mcp-setup, doctor checks, add-ide, sync, init-project) that
+// all assume every catalog entry is MCP-configurable, producing a false
+// "Unsupported config type" failure for a product that was never meant to
+// have one. Detection here is standalone; callers splice its result directly
+// into the surfaces/rows that need it (see session-service.ts).
+//
+// Detection matches a stable package/bundle identity, not a display name or
+// guessed path — openai/codex#32631 documents the Codex CLI's own equivalent
+// bug (searching for the old name `Codex.app`, broken by the rename to
+// `ChatGPT.app`) as the live precedent for why name/path matching fails.
+exports.CODEX_DESKTOP_BUNDLE_ID = 'com.openai.codex';
+// detectCodexDesktop() runs on every platform, so this row renders for
+// macOS/Windows/Linux users alike — a platform-specific doc page (e.g. the
+// Windows-only install guide) would be wrong for everyone else. Use OpenAI's
+// own universal download page, matching every sibling IDE_CONFIGS entry's
+// convention of linking the vendor's own top-level product/download page,
+// not a platform subpage (e.g. `claude.ai/download`, `cursor.com`).
+exports.CODEX_DESKTOP_DOWNLOAD_URL = 'https://chatgpt.com/download/';
+const detectCodexDesktopMac = () => {
+    if (process.env.FRAIM_DETECT_DISABLE_PROCESS_CHECK === '1')
+        return false;
+    const result = (0, child_process_1.spawnSync)('mdfind', [`kMDItemCFBundleIdentifier == '${exports.CODEX_DESKTOP_BUNDLE_ID}'`], { encoding: 'utf8', timeout: 2000 });
+    return result.status === 0 && Boolean((result.stdout || '').trim());
+};
+const detectCodexDesktopWindows = () => {
+    if (process.env.FRAIM_DETECT_DISABLE_PROCESS_CHECK === '1')
+        return false;
+    // The exact PackageFamilyName for the ChatGPT desktop app's MSIX package
+    // (Store ProductId 9PLM9XGG6VKS) is not yet confirmed against a real install
+    // (spec Open Question #2) — Get-AppxPackage's own `Name` property (a fixed
+    // publisher-assigned identifier, distinct from the mutable Start-menu
+    // display name) is queried by a name pattern as the best-available proxy.
+    const psCmd = `(Get-AppxPackage | Where-Object { $_.Name -like '*ChatGPT*' } | Select-Object -First 1).PackageFamilyName`;
+    const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8', timeout: 3000 });
+    return result.status === 0 && Boolean((result.stdout || '').trim());
+};
+const detectCodexDesktopOverride = () => {
+    const value = process.env.FRAIM_DETECT_CODEX_DESKTOP_OVERRIDE;
+    if (value === '1')
+        return true;
+    if (value === '0')
+        return false;
+    return null;
+};
+/**
+ * Issue #1478 R1: detects the Codex view inside OpenAI's ChatGPT desktop app,
+ * independent of IDE_CONFIGS (see comment above). Linux is not yet
+ * implemented — the app is a public preview (Aug 2026) with no confirmed
+ * package identity (spec Open Question #1); this is a deliberate, documented
+ * scope boundary, not an oversight.
+ */
+const detectCodexDesktop = () => {
+    const override = detectCodexDesktopOverride();
+    if (override !== null)
+        return override;
+    if (process.platform === 'darwin')
+        return detectCodexDesktopMac();
+    if (process.platform === 'win32')
+        return detectCodexDesktopWindows();
+    return false;
+};
+exports.detectCodexDesktop = detectCodexDesktop;
 const detectGrokSurface = () => {
     const paths = [
         '~/.grok',

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

@@ -14,6 +14,11 @@ exports.getNpmGlobalBinDirsFromPrefix = getNpmGlobalBinDirsFromPrefix;
 exports.resolveNpmGlobalBinDirs = resolveNpmGlobalBinDirs;
 exports.buildPathWithManagedAgentBins = buildPathWithManagedAgentBins;
 exports.appendManagedAgentBinDirsToProcessPath = appendManagedAgentBinDirsToProcessPath;
+exports.__setLoginShellPathResolverForTests = __setLoginShellPathResolverForTests;
+exports.resolveLoginShellPathCached = resolveLoginShellPathCached;
+exports.__clearLoginShellPathCacheForTests = __clearLoginShellPathCacheForTests;
+exports.buildRecoveredAgentPath = buildRecoveredAgentPath;
+exports.versionFromProbeOutput = versionFromProbeOutput;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
@@ -151,9 +156,15 @@ function buildChildEnv(env) {
     return childEnv;
 }
 function resolveNpmGlobalBinDirs(basePath, env) {
+    // Issue #1256: set both PATH and Path when overriding. Node's process.env is a
+    // case-insensitive view on win32, but a plain object built from `{...process.env}` can
+    // carry both casings as distinct own keys — overriding only `PATH` risks leaving a
+    // stale `Path` (with the pre-override value) also present in the child's environment
+    // block, which environment-lookup on Windows may prefer over the intended override.
+    // Mirrors the same defensive pattern hosts.ts's versionProbeEnv() already uses.
     const childEnv = buildChildEnv({
         ...env,
-        ...(basePath === undefined ? {} : { PATH: basePath }),
+        ...(basePath === undefined ? {} : { PATH: basePath, Path: basePath }),
     });
     const executable = process.platform === 'win32' ? 'cmd.exe' : 'npm';
     const args = process.platform === 'win32'
@@ -176,3 +187,174 @@ function buildPathWithManagedAgentBins(basePath) {
 function appendManagedAgentBinDirsToProcessPath() {
     process.env.PATH = buildPathWithManagedAgentBins(process.env.PATH);
 }
+// ─── Issue #1256 (slice a): location-agnostic PATH recovery ─────────────────
+//
+// A Hub launched from Launchpad/Finder/a Windows shortcut inherits the OS's minimal
+// GUI-launch PATH, not the user's shell PATH. `resolveNpmGlobalBinDirs()` above already
+// recovers the npm-global case, but it is structurally blind to anything installed outside
+// npm — Claude Code's native macOS installer (`~/.local/bin/claude`), Homebrew, or a vendor
+// installer like Antigravity's `agy` (no npm package at all, `src/first-run/types.ts`
+// `installPackage: ''`). Per the 2026-08-27 product decision, recovery must be
+// location-agnostic: it finds whatever the user's own login shell would find, not a list of
+// known install roots (which fails the next vendor's convention by construction).
+//
+// Mechanism: spawn the user's login shell non-interactively (`-lc`, explicitly sourcing the
+// common rc files itself rather than asking the shell to behave interactively — see
+// defaultResolveLoginShellPath) and read back `$PATH` between two markers, so any prompt/
+// motd/rc-file noise on stdout cannot be mistaken for the PATH itself. VS Code's own
+// `resolveShellEnv` uses `-ilc`; this repo's compliance requirement (SOC 2 CC6.1 / ISO 27001
+// A.8.19) is stricter and asks for non-interactive, so this achieves the same practical
+// coverage (PATH exports in `~/.bashrc`/`~/.zshrc`) without it. POSIX only — Windows GUI
+// launches already inherit the registry-composed PATH, so this returns null immediately on
+// win32 rather than attempting a login-shell equivalent that doesn't exist.
+const LOGIN_SHELL_PATH_TIMEOUT_MS = 3000;
+function defaultResolveLoginShellPath() {
+    if (process.platform === 'win32')
+        return null;
+    const shell = process.env.SHELL || '/bin/bash';
+    const marker = `__fraim_1256_shell_path_${process.pid}__`;
+    // `-lc`, not `-ilc`: login + command, deliberately NOT interactive (SOC 2 CC6.1 / ISO 27001
+    // A.8.19 — the spec's compliance section requires a non-interactive invocation). A plain
+    // `-lc` alone would still miss PATH exports that live in `~/.bashrc`/`~/.zshrc` — bash/zsh
+    // source those only for an interactive shell by design, which is what `-i` exists for. This
+    // command explicitly sources both common rc files itself (a no-op if a file doesn't exist or
+    // its syntax doesn't apply to the running shell — errors are swallowed, never abort the
+    // script) instead of asking the shell to behave interactively to get the same effect. That
+    // keeps the shell itself non-interactive while still recovering the common real-world case.
+    const script = [
+        'for rc in "$HOME/.bashrc" "$HOME/.zshrc"; do [ -f "$rc" ] && . "$rc" >/dev/null 2>&1; done',
+        `echo "${marker}"`,
+        'printf \'%s\' "$PATH"',
+        'echo',
+        `echo "${marker}"`,
+    ].join('; ');
+    try {
+        const result = (0, child_process_1.spawnSync)(shell, ['-lc', script], {
+            encoding: 'utf8',
+            timeout: LOGIN_SHELL_PATH_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        // Bounded and best-effort (AC-A5): any failure, non-zero exit, or timeout degrades to
+        // "no recovery" rather than throwing or blocking the caller's own PATH resolution.
+        if (result.status !== 0 || result.error)
+            return null;
+        const output = result.stdout || '';
+        const firstIdx = output.indexOf(marker);
+        if (firstIdx === -1)
+            return null;
+        const afterFirst = output.slice(firstIdx + marker.length);
+        const secondIdx = afterFirst.indexOf(marker);
+        const section = (secondIdx === -1 ? afterFirst : afterFirst.slice(0, secondIdx)).trim();
+        return section || null;
+    }
+    catch {
+        return null;
+    }
+}
+let loginShellPathResolverOverride = null;
+/**
+ * Test seam only. Injects a fake login-shell PATH resolver so AC-A2/AC-A6 are provable
+ * without a real POSIX shell or real rc files — including on Windows CI, where the real
+ * mechanism is a no-op. Pass null to restore the real resolver. Also clears the memoized
+ * result so the next call recomputes under the injected resolver.
+ */
+function __setLoginShellPathResolverForTests(resolver) {
+    loginShellPathResolverOverride = resolver;
+    cachedLoginShellPath = undefined;
+    cachedNpmGlobalBinDirsForRecovery = undefined;
+}
+let cachedLoginShellPath;
+/**
+ * Resolves and memoizes the PATH the user's own login shell would produce. Computed at most
+ * once per process (AC-A5: bounded, fixed cost) — this feeds every agent-resolution call, so
+ * recomputing per call would multiply one shell spawn by the number of agents probed.
+ */
+function resolveLoginShellPathCached() {
+    if (cachedLoginShellPath !== undefined)
+        return cachedLoginShellPath;
+    const resolver = loginShellPathResolverOverride ?? defaultResolveLoginShellPath;
+    // AC-A5: a resolver failing must degrade to "no recovery", never propagate. The default
+    // resolver already guards its own spawnSync internally; this also protects against an
+    // injected test resolver (or any future resolver) that throws instead of returning null.
+    try {
+        cachedLoginShellPath = resolver();
+    }
+    catch {
+        cachedLoginShellPath = null;
+    }
+    return cachedLoginShellPath;
+}
+/** Test seam only. Clears the memoized login-shell PATH so the next call recomputes. */
+function __clearLoginShellPathCacheForTests() {
+    cachedLoginShellPath = undefined;
+}
+let cachedNpmGlobalBinDirsForRecovery;
+/**
+ * Memoized wrapper around resolveNpmGlobalBinDirs(), scoped to buildRecoveredAgentPath()'s
+ * own use only — NOT a change to resolveNpmGlobalBinDirs() itself, which fraim doctor and the
+ * install route still call directly and must keep getting a fresh, uncached answer (doctor's
+ * whole purpose is detecting drift after a `codex update`; a stale cached answer would defeat
+ * that).
+ *
+ * Bug this fixes (issue #1256, AC-A5): buildRecoveredAgentPath() is called once PER AGENT
+ * inside detectEmployeesAsync()'s concurrent probe round (hosts.ts). Without this cache,
+ * resolveNpmGlobalBinDirs()'s spawnSync (bounded at 5s) re-ran synchronously for every agent,
+ * and because each call sits inside a Promise executor that runs synchronously up to its own
+ * spawnSync, the "concurrent" probes actually serialized behind it — up to 5 agents × 5s of
+ * blocking spawnSync is exactly the event-loop-freezing regression issue #1010 eliminated,
+ * reintroduced one layer deeper. Memoizing once per process (like resolveLoginShellPathCached
+ * above) restores the bound this repo's own #1010 postmortem requires.
+ */
+function resolveNpmGlobalBinDirsCached(basePath) {
+    if (cachedNpmGlobalBinDirsForRecovery !== undefined)
+        return cachedNpmGlobalBinDirsForRecovery;
+    try {
+        cachedNpmGlobalBinDirsForRecovery = resolveNpmGlobalBinDirs(basePath);
+    }
+    catch {
+        cachedNpmGlobalBinDirsForRecovery = [];
+    }
+    return cachedNpmGlobalBinDirsForRecovery;
+}
+/**
+ * Issue #1256 (AC-A3): the single shared PATH-recovery helper every agent-resolution call
+ * site routes through — the version probe (`hosts.ts`), the install route's existing-version
+ * check and `check-agent` (`server.ts`), and `fraim doctor`'s health check
+ * (`agent-cli-health-checks.ts`). One implementation means a CLI resolved by any one of these
+ * is resolved by all of them; four independent reimplementations is exactly how #1375 shipped
+ * a Windows-only PATH bug that stayed invisible on POSIX.
+ *
+ * Order: strip FRAIM's managed dirs and any project-local `node_modules/.bin` (AC-A4) →
+ * layer in the recovered login-shell PATH (AC-A2/AC-A6, location-agnostic by construction) →
+ * strip project-local bins again (a hostile/unusual shell rc could reintroduce one) → layer
+ * in npm-global bin dirs resolved against that recovered PATH (covers the npm case even where
+ * a login shell is unavailable) → append FRAIM's managed agent bins last, unconditionally.
+ */
+function buildRecoveredAgentPath(basePath) {
+    const withoutManaged = stripManagedAgentBinDirsFromPath(basePath);
+    const withoutProjectBins = stripProjectLocalNodeBinDirs(withoutManaged);
+    const loginShellPath = resolveLoginShellPathCached();
+    const loginShellEntries = loginShellPath ? loginShellPath.split(path_1.default.delimiter).filter(Boolean) : [];
+    const withLoginShell = loginShellEntries.length > 0
+        ? appendBinDirsToPath(withoutProjectBins, loginShellEntries)
+        : withoutProjectBins;
+    const withLoginShellClean = stripProjectLocalNodeBinDirs(withLoginShell);
+    const npmGlobalBinDirs = resolveNpmGlobalBinDirsCached(withLoginShellClean);
+    const withNpmGlobal = appendBinDirsToPath(withLoginShellClean, npmGlobalBinDirs);
+    return appendBinDirsToPath(withNpmGlobal, getManagedAgentBinDirs());
+}
+// ─── Issue #1256 (slice d): trust stdout, not stderr, for a version answer ───
+//
+// GitHub Copilot CLI's current failure mode is `--version` exiting 0 while printing an error
+// to stderr. `(stdout || stderr || '').trim()` — the pattern this replaces, previously
+// duplicated in hosts.ts, server.ts, and agent-cli-health-checks.ts — read that stderr text
+// as a version string and reported the agent ready. Only stdout counts as a version. This is
+// the mirror image of #1355's `isResumableBackgroundTaskType`, which fails OPEN on an ABSENT
+// field (silence is a reporting gap, not evidence). stderr output on exit 0 is not silence —
+// it is positive evidence the CLI is broken — so this fails CLOSED. The two rules are
+// consistent: infer nothing from an absent signal, believe an error when you get one.
+function versionFromProbeOutput(stdout, stderr) {
+    void stderr; // never trusted as a version string — kept as a parameter so call sites read as before, not silently dropping a value
+    const version = (stdout || '').trim();
+    return version || null;
+}

package/dist/src/config/persona-capability-bundles.js

@@ -71,8 +71,8 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
     qasm: {
         personaKey: 'qasm',
         bundleId: 'persona-qasm-core',
-        catalogMetadata: buildCatalogMetadata('qasm', ['test-execution', 'browser-application-validation', 'ui-polish-validation']),
-        protectedJobs: ['test-execution', 'browser-application-validation', 'ui-polish-validation', 'code-quality-assessment', 'test-quality-assessment', 'user-testing-and-bug-bash', 'broken-windows-detection-and-remediation', 'iterative-quality-improvement', 'accessibility-audit', 'api-testing', 'performance-benchmarking'],
+        catalogMetadata: buildCatalogMetadata('qasm', ['test-authoring', 'browser-application-validation', 'ui-polish-validation']),
+        protectedJobs: ['test-authoring', 'browser-application-validation', 'ui-polish-validation', 'code-quality-assessment', 'test-quality-assessment', 'user-testing-and-bug-bash', 'broken-windows-detection-and-remediation', 'iterative-quality-improvement', 'accessibility-audit', 'api-testing', 'performance-benchmarking'],
         protectedAliases: ['qa', 'quality-assurance'],
         defaultHireMode: 'job',
         lockCopy: 'Hire QAsm to unlock QA validation for this request.'

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.commandVersion = commandVersion;
 exports.buildPersistShellPathWindowsCommand = buildPersistShellPathWindowsCommand;
 exports.buildFirstRunHubLaunchArgs = buildFirstRunHubLaunchArgs;
 const fs_1 = __importDefault(require("fs"));
@@ -71,18 +72,18 @@ function commandVersion(command, extraBinDirs, basePath) {
         ? ['/d', '/s', '/c', `${command} --version`]
         : ['--version'];
     const pathValue = extraBinDirs && extraBinDirs.length > 0
-        ? (0, managed_agent_paths_1.appendBinDirsToPath)(basePath ?? process.env.PATH, extraBinDirs)
+        ? (0, managed_agent_paths_1.appendBinDirsToPath)(basePath ?? process.env.PATH ?? process.env.Path, extraBinDirs)
         : basePath;
-    const env = pathValue === undefined ? undefined : { ...process.env, PATH: pathValue };
+    const recoveredPath = (0, managed_agent_paths_1.buildRecoveredAgentPath)(pathValue ?? process.env.PATH ?? process.env.Path);
+    const env = { ...process.env, PATH: recoveredPath, Path: recoveredPath };
     const result = (0, child_process_1.spawnSync)(executable, args, {
         encoding: 'utf8',
         timeout: 5000,
-        ...(env ? { env } : {}),
+        env,
     });
-    if (result.status !== 0)
+    if (result.status !== 0 || result.error)
         return null;
-    const text = `${result.stdout || ''}${result.stderr || ''}`.split(/\r?\n/)[0]?.trim() || null;
-    return text;
+    return (0, managed_agent_paths_1.versionFromProbeOutput)(result.stdout, result.stderr);
 }
 function ensureOutputDirs() {
     fs_1.default.mkdirSync((0, script_sync_utils_1.getUserFraimDir)(), { recursive: true });
@@ -259,12 +260,25 @@ function buildRunnableAgentSurfaces() {
     const cliRunnableTypes = new Set((0, ide_detector_1.detectInstalledIDEs)('cli-runnable').map((ide) => ide.configType));
     const ides = configSurface.filter((ide) => !ide_detector_1.CLI_PROBE_CONFIGTYPES.has(ide.configType) || cliRunnableTypes.has(ide.configType));
     const hints = (0, ide_global_integration_1.describeOnboardingInvocationSurfaces)(ides);
-    return ides.map((ide, index) => ({
+    const surfaces = ides.map((ide, index) => ({
         id: ide.configType,
         name: ide.name,
         invocationHint: hints[index] || '/fraim onboard this project',
         status: 'configured',
     }));
+    // Issue #1478 R1/R1.2: Codex Desktop is detected standalone (not an
+    // IDE_CONFIGS entry — see ide-detector.ts) and spliced in here so it flows
+    // straight to detectedAgentCount() without ever touching the
+    // CLI_PROBE_CONFIGTYPES gate above.
+    if ((0, ide_detector_1.detectCodexDesktop)()) {
+        surfaces.push({
+            id: 'codex-desktop',
+            name: 'Codex Desktop',
+            invocationHint: 'Codex Desktop: onboard this project',
+            status: 'configured',
+        });
+    }
+    return surfaces;
 }
 function surfaceForAgent(option) {
     return {
@@ -523,12 +537,28 @@ class FirstRunSessionService {
         this.detectRowsOnLoad();
         this.persist();
         const detectedNames = new Set((this.state.setupResult?.configuredSurfaces ?? []).map((s) => s.name));
+        // Issue #1478 R2: one unified list. `agentOptionId` is set when this
+        // product also has a working Set up flow (matched by exact label against
+        // FIRST_RUN_AGENT_OPTIONS) — the client renders "Set up" instead of
+        // "Download" for those rows, which is what lets the old two-section split
+        // ("Supported AI tools and IDEs" + "Hub-ready CLI agents") retire into one.
         const supportedAgents = ide_detector_1.IDE_CONFIGS
             .map((ide) => ({
             name: ide.name,
             detected: detectedNames.has(ide.name),
             downloadUrl: ide.downloadUrl ?? null,
+            agentOptionId: types_1.FIRST_RUN_AGENT_OPTIONS.find((option) => option.label === ide.name)?.id ?? null,
         }));
+        // Codex Desktop is not an IDE_CONFIGS entry (see ide-detector.ts) but must
+        // still appear as a peer row; insert it next to "Codex" per the approved
+        // mock's row order.
+        const codexIndex = supportedAgents.findIndex((agent) => agent.name === 'Codex');
+        supportedAgents.splice(codexIndex === -1 ? supportedAgents.length : codexIndex + 1, 0, {
+            name: 'Codex Desktop',
+            detected: detectedNames.has('Codex Desktop'),
+            downloadUrl: ide_detector_1.CODEX_DESKTOP_DOWNLOAD_URL,
+            agentOptionId: null,
+        });
         return {
             state: this.state,
             rows: this.state.rows,

package/dist/src/local-mcp-server/stdio-server.js

@@ -1527,6 +1527,18 @@ class FraimLocalMCPServer {
             if (typeof jobId !== 'string' || !jobId.trim())
                 continue;
             const normalizedJobId = jobId.trim();
+            // Issue #1504: a category-qualified jobId (e.g. "ai-employee/product-building/x")
+            // can resolve through getJobOverview -> LocalRegistryResolver.getJob's lenient
+            // local-override/remote fallback, even though every real catalog job id is a bare
+            // filename slug (src/ai-hub/catalog.ts: `id: fileName`) and the Hub UI's
+            // resolveNextJobFromCatalog() only ever matches that bare slug with strict equality
+            // (public/ai-hub/script.js). Reject the path-qualified shape directly, before
+            // trusting the resolver, so this class of malformed jobId cannot pass here and then
+            // silently render as a disabled chip in the Hub.
+            if (normalizedJobId.includes('/') || normalizedJobId.includes('\\')) {
+                errors.push(`evidence.nextJobRecommendations[${i}].jobId must be the bare job slug from the catalog (e.g. "feature-implementation"), not a category-qualified path (got "${normalizedJobId}")`);
+                continue;
+            }
             const job = await mentor.getJobOverview(normalizedJobId);
             if (!job) {
                 errors.push(`evidence.nextJobRecommendations[${i}].jobId must reference a known FRAIM job (got "${normalizedJobId}")`);

package/dist/src/middleware/auth.js

@@ -198,7 +198,16 @@ class AuthMiddleware {
         const strictTestAuth = typeof authMode === 'string' && authMode.toLowerCase() === 'strict';
         const isTestBypass = process.env.NODE_ENV === 'test' && !this.skipTestBypass && !strictTestAuth && apiKey !== 'invalid-key';
         const isLocalDev = apiKey === 'local-dev' && process.env.NODE_ENV !== 'production';
-        if (isLocalDev || isTestBypass) {
+        let testSeededApiKeyData = null;
+        if (isTestBypass) {
+            try {
+                testSeededApiKeyData = await this.dbService.verifyApiKey(apiKey);
+            }
+            catch {
+                testSeededApiKeyData = null;
+            }
+        }
+        if (isLocalDev || (isTestBypass && !testSeededApiKeyData)) {
             req.apiKeyData = {
                 key: apiKey,
                 userId: isLocalDev ? 'local-dev-user' : 'test-user',

package/package.json

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

package/public/first-run/script.js

@@ -92,12 +92,8 @@
     return String(name || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
   }
 
-  function isAgentReady(opt) {
-    const installState = state.session && state.session.state && state.session.state.agentInstalls
-      ? state.session.state.agentInstalls[opt.id]
-      : null;
-    if (installState && installState.status === 'ready') return true;
-    return configuredSurfaces().some((surface) => surface && (surface.id === opt.id || surface.name === opt.label));
+  function findAgentOptionById(agentOptionId) {
+    return (state.session && state.session.agentOptions || []).find((opt) => opt.id === agentOptionId) || null;
   }
 
   function detectedAgentCount() {
@@ -244,7 +240,7 @@
 
     const catalogCopy = document.createElement('p');
     catalogCopy.className = 'pane-copy';
-    catalogCopy.textContent = 'FRAIM can configure every supported local agent or IDE it detects. Download links stay available for tools not installed yet.';
+    catalogCopy.textContent = 'FRAIM can configure every supported local agent or IDE it detects. "Set up" installs it for you; "Download" opens the developer\'s own install page.';
     pane.appendChild(catalogCopy);
 
     const list = document.createElement('ul');
@@ -271,6 +267,15 @@
         badge.setAttribute('data-testid', `supported-agent-installed-${slug}`);
         badge.textContent = 'Installed';
         actionSpan.appendChild(badge);
+      } else if (agent.agentOptionId) {
+        // Issue #1478 R2: this product also has a working install/sign-in/check
+        // flow — route to it instead of a static Download link so there is no
+        // row left that could dead-end.
+        const opt = findAgentOptionById(agent.agentOptionId);
+        const setupBtn = button('Set up', 'secondary');
+        setupBtn.setAttribute('data-testid', `supported-agent-setup-${agent.agentOptionId}`);
+        setupBtn.addEventListener('click', () => { if (opt) openAgentModal(opt); });
+        actionSpan.appendChild(setupBtn);
       } else if (agent.downloadUrl) {
         const link = document.createElement('a');
         link.className = 'agent-download-link';
@@ -303,52 +308,15 @@
     });
     pane.appendChild(rescanBtn);
 
-    const hubHeading = document.createElement('h3');
-    hubHeading.className = 'agent-section-heading';
-    hubHeading.textContent = 'Hub-ready CLI agents';
-    pane.appendChild(hubHeading);
-
-    const hubCopy = document.createElement('p');
-    hubCopy.className = 'pane-copy';
-    hubCopy.textContent = 'FRAIM Hub runs jobs through CLI agents. Set up at least one of these if you plan to launch jobs in Hub.';
-    pane.appendChild(hubCopy);
-
-    const grid = document.createElement('div');
-    grid.className = 'agent-grid';
-    const agentOptions = state.session.agentOptions || [];
-    for (const opt of agentOptions) {
-      const card = document.createElement('div');
-      card.className = 'user-type-card recruit-card';
-      card.setAttribute('data-agent-id', opt.id);
-      card.setAttribute('data-testid', `agent-card-${opt.id}`);
-      const agentReady = isAgentReady(opt);
-
-      const title = document.createElement('strong');
-      title.className = 'card-title';
-      title.textContent = opt.label;
-
-      const desc = document.createElement('p');
-      desc.className = 'card-desc';
-      desc.textContent = agentReady
-        ? 'Already installed and ready for FRAIM.'
-        : `Available to set up: install, sign in, and verify ${opt.label}.`;
-
-      const action = button(agentReady ? 'Ready' : 'Set up', 'secondary');
-      action.disabled = agentReady;
-      action.setAttribute('data-testid', `install-${opt.id}`);
-      action.addEventListener('click', () => openAgentModal(opt));
-
-      card.appendChild(title);
-      card.appendChild(desc);
-      card.appendChild(action);
-      grid.appendChild(card);
-    }
-
+    // Issue #1478 R2: the old "Hub-ready CLI agents" heading/copy/card-grid is
+    // retired — every product it used to list (Claude Code, Codex, Gemini CLI,
+    // GitHub Copilot CLI) now renders as a "Set up" row in the unified list
+    // above via agent.agentOptionId, with the identical install/sign-in/check
+    // modal. Bring Your Own Agent still renders, now standalone.
     const byoa = document.createElement('div');
     byoa.className = 'user-type-card recruit-card byoa-card';
-    byoa.innerHTML = '<strong class="card-title">Bring Your Own Agent</strong><p class="card-desc">Use Cursor, Windsurf, Kiro, VS Code, or another supported local AI tool. If you install a new agent later and want FRAIM to use it, run this command from your project.</p><div class="cmd-block">npx fraim add-ide</div>';
-    grid.appendChild(byoa);
-    pane.appendChild(grid);
+    byoa.innerHTML = '<strong class="card-title">Bring Your Own Agent</strong><p class="card-desc">Use Windsurf, Kiro, or another supported local AI tool not listed above. If you install a new agent later and want FRAIM to use it, run this command from your project.</p><div class="cmd-block">npx fraim add-ide</div>';
+    pane.appendChild(byoa);
 
     const done = button('Next', 'primary');
     done.setAttribute('data-testid', 'done-installing-agents');