fraim-hub 2.0.349 → 2.0.351

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

@@ -213,6 +213,7 @@ function summarizeProject(projectPath) {
             path: '',
             exists: false,
             hasFraim: false,
+            isOnboarded: false,
             message: 'Choose a project path to load FRAIM jobs.',
         };
     }
@@ -221,17 +222,20 @@ function summarizeProject(projectPath) {
             path: projectPath,
             exists: false,
             hasFraim: false,
+            isOnboarded: (0, project_fraim_paths_1.workspaceOnboardingReady)(projectPath),
             message: 'Project path does not exist on this machine.',
         };
     }
     const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath);
     const hasFraim = fs_1.default.existsSync(fraimDir);
+    const isOnboarded = (0, project_fraim_paths_1.workspaceOnboardingReady)(projectPath);
     if (!hasFraim) {
         return {
             path: projectPath,
             exists: true,
             hasFraim: false,
-            needsOnboarding: true,
+            isOnboarded,
+            needsOnboarding: isOnboarded === false,
             message: 'This folder has not been set up with FRAIM yet. Onboarding will get your AI employee started.',
         };
     }
@@ -239,6 +243,8 @@ function summarizeProject(projectPath) {
         path: projectPath,
         exists: true,
         hasFraim: true,
+        isOnboarded,
+        needsOnboarding: isOnboarded === false,
     };
 }
 function resolveLayerRoot(projectPath, layer) {

package/dist/src/ai-hub/desktop-installer-setup.js

@@ -16,7 +16,6 @@ const auto_mcp_setup_1 = require("../cli/setup/auto-mcp-setup");
 const fraim_mcp_latest_launcher_1 = require("../cli/mcp/fraim-mcp-latest-launcher");
 const managed_node_runtime_1 = require("../cli/utils/managed-node-runtime");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
-const hub_app_materializer_1 = require("./hub-app-materializer");
 function isDesktopRuntimeComplete() {
     if (![(0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)(), (0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)(), (0, fraim_mcp_latest_launcher_1.getFraimNpxShimPath)(), (0, fraim_mcp_latest_launcher_1.getFraimMcpLatestLauncherPath)()]
         .every(file => fs_1.default.existsSync(file)))
@@ -68,19 +67,11 @@ async function repairInstallerIdeMcpEntries(options = {}) {
             process.env.FRAIM_NON_INTERACTIVE = previousNonInteractive;
     }
 }
-async function warmInstallerCliCache() {
-    const cliShim = (0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)();
-    const result = await (0, hub_app_materializer_1.runNpmInstall)(cliShim, ['--version']);
-    if (result.status !== 0) {
-        throw new Error(`FRAIM CLI bootstrap exited with code ${result.status ?? 'unknown'}.`);
-    }
-}
 async function runDesktopRuntimeSetup(logger = console) {
     await (0, managed_node_runtime_1.ensureManagedNpm)({
         onProgress: (message) => logger.log(`[fraim-installer-setup] ${message}`),
     });
     (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
-    await warmInstallerCliCache();
 }
 async function runDesktopInstallerSetup(logger = console) {
     await runDesktopRuntimeSetup(logger);

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

@@ -2398,36 +2398,63 @@ function detectCodexCompactTaskFailure(line) {
     }
     return null;
 }
+const CODEX_PERMANENT_REFRESH_FAILURES = new Set([
+    'Your access token could not be refreshed because your refresh token was already used. Please log out and sign in again.',
+    'Your access token could not be refreshed because your refresh token has expired. Please log out and sign in again.',
+    'Your access token could not be refreshed because your refresh token was revoked. Please log out and sign in again.',
+    'Your access token could not be refreshed. Please log out and sign in again.',
+    'Your access token could not be refreshed because you have since logged out or signed in to another account. Please sign in again.',
+]);
+// Exec has no typed auth code. Scope transport 401s to Codex's own OpenAI
+// Responses endpoints; tools, MCP servers and custom relays can also return 401.
+function isCodexProviderAuthFailure(message) {
+    if (typeof message !== 'string')
+        return false;
+    if (message === 'workspace routing discovery unauthorized (401)')
+        return true;
+    const transport = /^unexpected status 401 Unauthorized: [\s\S]*?, url: ([^\s,]+)(?:, [\s\S]*)?$/.exec(message);
+    if (!transport)
+        return false;
+    try {
+        const endpoint = new URL(transport[1]);
+        if (!['https:', 'wss:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.port || endpoint.hash)
+            return false;
+        const responsePath = endpoint.hostname === 'api.openai.com' ? '/v1/responses'
+            : endpoint.hostname === 'chatgpt.com' ? '/backend-api/codex/responses' : null;
+        return responsePath !== null && (endpoint.pathname === responsePath || endpoint.pathname === `${responsePath}/compact`);
+    }
+    catch {
+        return false;
+    }
+}
 function wireHostProcess(hostId, child, handlers, spawnCwd) {
-    // Exec's JSON error has no auth code. Refresh failures need corroborating
-    // stderr; workspace-routing 401 needs the exact terminal provider event.
-    // Both require a failed process exit; never scan tool/prose text.
-    const codexRefreshFailure = 'Your access token could not be refreshed because your refresh token was already used. Please log out and sign in again.';
-    const codexWorkspaceRoutingFailure = 'workspace routing discovery unauthorized (401)';
-    let codexAuthDiagnostic = false;
-    let codexTerminalAuthFailure = false;
-    let codexTerminalWorkspaceAuthFailure = false;
+    // Refresh failures need matching auth-manager stderr. Provider 401s need a
+    // terminal turn.failed. Both require normal failed exit; never scan prose.
+    const codexAuthDiagnostics = new Set();
+    let codexTerminalRefreshFailure = null;
+    let codexTerminalProviderFailure = null;
     const observeCodexAuth = (line, channel) => {
         if (hostId !== 'codex')
             return;
         if (channel === 'stderr') {
             const clean = line.replace(/\x1b\[[0-9;]*m/g, '').trim();
             const diagnostic = clean.match(/^(?:\d{4}-\d{2}-\d{2}T[\d:.]+Z\s+)?ERROR\s+codex_login::auth::manager:\s+Failed to refresh token: (.+)$/);
-            if (diagnostic?.[1] === codexRefreshFailure)
-                codexAuthDiagnostic = true;
+            if (diagnostic && CODEX_PERMANENT_REFRESH_FAILURES.has(diagnostic[1]))
+                codexAuthDiagnostics.add(diagnostic[1]);
             return;
         }
         try {
             const event = JSON.parse(line);
             if (event.type === 'turn.failed') {
-                codexTerminalWorkspaceAuthFailure = event.error?.message === codexWorkspaceRoutingFailure;
+                codexTerminalProviderFailure = isCodexProviderAuthFailure(event.error?.message) ? event.error.message : null;
             }
             if (event.type === 'turn.failed' || event.type === 'error') {
-                codexTerminalAuthFailure = (event.type === 'turn.failed' ? event.error?.message : event.message) === codexRefreshFailure;
+                const message = event.type === 'turn.failed' ? event.error?.message : event.message;
+                codexTerminalRefreshFailure = CODEX_PERMANENT_REFRESH_FAILURES.has(message) ? message : null;
             }
             else if (event.type === 'turn.started' || event.type === 'turn.completed') {
-                codexTerminalAuthFailure = false;
-                codexTerminalWorkspaceAuthFailure = false;
+                codexTerminalRefreshFailure = null;
+                codexTerminalProviderFailure = null;
             }
         }
         catch { /* Plain stdout cannot establish authentication failure. */ }
@@ -2481,8 +2508,8 @@ function wireHostProcess(hostId, child, handlers, spawnCwd) {
     // `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) => {
-        if (!signal && code !== null && code !== 0 && ((codexAuthDiagnostic && codexTerminalAuthFailure) || codexTerminalWorkspaceAuthFailure)) {
-            const failure = codexTerminalWorkspaceAuthFailure ? codexWorkspaceRoutingFailure : codexRefreshFailure;
+        const failure = codexTerminalProviderFailure || (codexTerminalRefreshFailure && codexAuthDiagnostics.has(codexTerminalRefreshFailure) ? codexTerminalRefreshFailure : null);
+        if (!signal && code !== null && code !== 0 && failure) {
             handlers.onEvent({ hostAuthenticationRequired: true, hostError: failure, raw: failure }, 'system');
         }
         handlers.onExit(signal ? -1 : code);

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

@@ -383,20 +383,21 @@ function directoryExists(projectPath) {
 // project list. This deliberately never falls back to process.cwd() — the launch
 // directory must not masquerade as a project.
 //
-// Issue #1253: existence alone is not validity. Eligibility is a positive rule —
-// a recorded path qualifies only if it IS a FRAIM project. The temp/Home/Desktop/
-// Downloads filters narrow that rule further; they do not define it. Framing
-// eligibility as an exclusion list is what let C:\Windows stay pinned forever:
-// it was simply not on the list, and such a list is unbounded by construction.
+// A recorded folder must be a discoverable FRAIM project or a deliberately added
+// project list entry. The latter remains selectable before onboarding (#2039).
+// Existing temporary/Home/Desktop/Downloads safeguards still apply; a stale bare
+// recorded path is not enough to turn an arbitrary directory into a project.
 function resolveHubProjectPath(preferencesStore, options = {}) {
-    const recorded = preferencesStore.load('').projectPath;
+    const preferences = preferencesStore.load('');
+    const recorded = preferences.projectPath;
     if (typeof recorded === 'string' && recorded.trim().length > 0) {
         const resolved = path_1.default.resolve(recorded);
         const allowedTemporary = options.allowTemporaryRelatedTo
             ? isRelatedTemporaryProjectPath(resolved, options.allowTemporaryRelatedTo)
             : false;
         if (!isLikelyTemporaryProjectPath(resolved) || allowedTemporary) {
-            if (directoryExists(resolved) && (0, project_fraim_paths_1.workspaceFraimExists)(resolved))
+            const explicitlyAdded = preferences.projects?.some((project) => sameDirectoryPath(project.folderPath, resolved));
+            if (directoryExists(resolved) && ((0, project_fraim_paths_1.workspaceFraimExists)(resolved) || explicitlyAdded))
                 return { projectPath: resolved };
             // A missing folder can be a moved project. Report it separately from a
             // non-FRAIM folder so the Hub can show the rehome path instead of leaving
@@ -419,10 +420,15 @@ function resolveHubProjectPath(preferencesStore, options = {}) {
  * handed to `preferencesStore.save()`.
  */
 function decorateProjectsWithFraimStatus(projects) {
-    return projects.map((project) => ({
-        ...project,
-        hasFraim: !!project.folderPath && (0, project_fraim_paths_1.workspaceFraimExists)(path_1.default.resolve(project.folderPath)),
-    }));
+    return projects.map((project) => {
+        const isOnboarded = project.folderPath ? (0, project_fraim_paths_1.workspaceOnboardingReady)(path_1.default.resolve(project.folderPath)) : false;
+        return {
+            ...project,
+            hasFraim: !!project.folderPath && (0, project_fraim_paths_1.workspaceFraimExists)(path_1.default.resolve(project.folderPath)),
+            isOnboarded,
+            needsOnboarding: isOnboarded === false,
+        };
+    });
 }
 class AiHubRunRegistry {
     constructor() {
@@ -2411,6 +2417,18 @@ function normalizedDirectoryPath(projectPath) {
 function sameDirectoryPath(left, right) {
     return normalizedDirectoryPath(left) === normalizedDirectoryPath(right);
 }
+function onboardingConversationIsActive(conversation) {
+    if (conversation.status === 'running')
+        return true;
+    if (conversation.pauseReason === 'done' || conversation.reviewApproved === true)
+        return false;
+    const handoff = normalizeReviewHandoff(conversation.reviewHandoff);
+    if (handoff)
+        return handoff.reviewRequired;
+    if (conversation.pauseReason === 'awaiting_review')
+        return false;
+    return conversation.status === 'completed' && (conversation.artifacts || []).some((artifact) => Boolean(artifact.path || artifact.url || (('where' in artifact) && artifact.where && artifact.name)));
+}
 function isPathInsideDirectory(candidatePath, parentPath) {
     const relative = path_1.default.relative(path_1.default.resolve(parentPath), path_1.default.resolve(candidatePath));
     return relative === '' || (!!relative && !relative.startsWith('..') && !path_1.default.isAbsolute(relative));
@@ -2480,8 +2498,9 @@ function resolveApiKey() {
 }
 // Read persisted Get-started step states from ~/.fraim/install-state.json
 // (architecture §3.5) and ~/.fraim/preferences.json. Returns a partial — any
-// missing key falls back to derivation. Persisted `true` is sticky so the rail
-// never re-shows once a step is completed (R13.4).
+// missing key falls back to derivation. Persisted `true` is sticky for install,
+// company, and hire (R13.4). computeFirstRun ignores the legacy project flag:
+// project readiness is derived live from the selected project's config presence.
 function readPersistedFirstRun() {
     const out = {};
     const apply = (source) => {
@@ -3000,6 +3019,7 @@ class AiHubServer {
     constructor(options = {}) {
         this.app = (0, express_1.default)();
         this.runRegistry = new AiHubRunRegistry();
+        this.projectSelectionGeneration = 0;
         this.activeAvailabilityWarnings = new Set();
         // Issue #925: the last identity successfully resolved from the hosted authority,
         // keyed by the exact apiKey it was resolved for. When the authority is transiently
@@ -3584,10 +3604,26 @@ class AiHubServer {
             this.conversationStore.moveProjectBucket(oldProjectPath, newProjectPath);
         }
     }
-    async bootstrapResponse(projectPath) {
+    async bootstrapResponse(projectPath, explicitSelection = false) {
         // #866 R2: guard against path.resolve('') === cwd; '' means "no active project".
         const activeProjectPath = projectPath || this.projectPath;
         const normalizedProjectPath = activeProjectPath ? path_1.default.resolve(activeProjectPath) : '';
+        if (explicitSelection) {
+            this.projectSelectionGeneration += 1;
+            // Record the chosen directory before slow employee/persona reads. A
+            // pathless refresh during that work must already resolve this selection.
+            if (directoryExists(normalizedProjectPath)) {
+                const selectedPreferences = this.preferencesStore.load('');
+                this.preferencesStore.save({
+                    ...selectedPreferences,
+                    projectPath: normalizedProjectPath,
+                    projects: (0, preferences_1.normalizeAiHubProjectList)(selectedPreferences.projects || [], normalizedProjectPath, {
+                        removedProjectPaths: selectedPreferences.removedProjectPaths || [],
+                    }),
+                });
+            }
+        }
+        const selectionGeneration = this.projectSelectionGeneration;
         // Issue #1010: prefer the non-blocking parallel probe on the first-paint path. On a
         // cache miss the synchronous form would spawnSync per agent (~2.7s) and freeze the
         // event loop, making every concurrent request wait. Falls back to the sync form for
@@ -3616,7 +3652,8 @@ class AiHubServer {
             const firstAvailable = employees.find((e) => e.available);
             if (firstAvailable) {
                 preferences = { ...preferences, employeeId: firstAvailable.id };
-                this.preferencesStore.save(preferences);
+                if (selectionGeneration === this.projectSelectionGeneration)
+                    this.preferencesStore.save(preferences);
             }
         }
         const project = (0, catalog_1.summarizeProject)(normalizedProjectPath);
@@ -3682,7 +3719,8 @@ class AiHubServer {
         // shell is visible.
         const projects = this.knownProjects(normalizedProjectPath, [], { includeConversationProjects: false });
         preferences = { ...preferences, projectPath: normalizedProjectPath, projects };
-        this.preferencesStore.save(preferences);
+        if (selectionGeneration === this.projectSelectionGeneration)
+            this.preferencesStore.save(preferences);
         // Issue #1253: `hasFraim` is decorated AFTER the save above, never before. The
         // line that persists `preferences` takes whatever list it is handed, so a
         // derived field attached upstream of it silently becomes persisted state. See
@@ -5174,8 +5212,7 @@ class AiHubServer {
         const companyDone = tc.orgContext.present || tc.managerContext.present || tc.orgRules.present || tc.managerRules.present;
         // hire = any persona hired (entitlement active).
         const hireDone = personas.some((p) => p.status === 'hired');
-        // project = a project brief exists OR the workspace has FRAIM jobs set up.
-        const projectDone = tc.projectContext.present || tc.projectBrief.present || tc.projectRules.present || tc.projectQa.present || jobCount > 0;
+        const projectDone = (0, project_fraim_paths_1.workspaceOnboardingReady)(projectPath) === true;
         const derived = {
             install: true, // the Hub is running, so the toolchain install step is satisfied.
             company: companyDone,
@@ -5187,7 +5224,7 @@ class AiHubServer {
             install: persisted.install ?? derived.install,
             company: persisted.company || derived.company,
             hire: persisted.hire || derived.hire,
-            project: persisted.project || derived.project,
+            project: derived.project,
         };
     }
     // Issue #512 (S3, R3) — presence + display paths of the three-layer context
@@ -5722,7 +5759,7 @@ class AiHubServer {
             }
             // #719 / local Hub package: a bare reload must land on the user-level saved
             // Hub project, not whatever directory happened to launch the process.
-            res.json(await this.bootstrapResponse(projectPath || this.defaultProjectPath()));
+            res.json(await this.bootstrapResponse(projectPath || this.defaultProjectPath(), !!projectPath));
         });
         this.app.get('/api/ai-hub/personas', async (req, res) => {
             const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
@@ -6540,7 +6577,7 @@ class AiHubServer {
                     .filter((id) => id.length > 0));
                 const retainedProjects = this.knownProjects(projectPath).filter((project) => !(project.id && incomingProjectIds.has(project.id)));
                 const projects = this.preferencesStore.saveProjects(projectPath, [...retainedProjects, ...body.projects], { reviveRemovedPaths: Array.isArray(body.reviveRemovedPaths) ? body.reviveRemovedPaths : [] });
-                return res.json({ projectPath, projects, source: 'disk' });
+                return res.json({ projectPath, projects: decorateProjectsWithFraimStatus(projects), source: 'disk' });
             }
             catch (error) {
                 return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not persist projects.' });
@@ -7160,6 +7197,35 @@ class AiHubServer {
                 if (!jobId) {
                     throw new Error('Choose a FRAIM job before starting a run.');
                 }
+                // A project has one active onboarding workflow, including review gates.
+                // Disk records cover review after restart; optimistic records without a
+                // run id cannot block their own first launch.
+                if (jobId === 'project-onboarding' && scope === 'project') {
+                    const conversations = this.conversationStore.loadProject(projectPath).conversations;
+                    const liveRun = this.runRegistry.all().find((run) => {
+                        if (run.jobId !== jobId || run.scope === 'manager' || run.scope === 'company'
+                            || !sameDirectoryPath(run.projectPath, projectPath))
+                            return false;
+                        const stored = conversations.find((conversation) => conversation.id === (run.conversationId || run.id));
+                        return onboardingConversationIsActive({
+                            ...run,
+                            reviewApproved: stored?.reviewApproved,
+                            pauseReason: stored?.pauseReason === 'done' ? 'done' : run.pauseReason,
+                        });
+                    });
+                    const existing = conversations.find((conversation) => !!conversation.runId
+                        && conversation.jobId === jobId && conversation.scope !== 'manager' && conversation.scope !== 'company'
+                        && !!conversation.projectPath && sameDirectoryPath(conversation.projectPath, projectPath)
+                        && onboardingConversationIsActive(conversation));
+                    if (liveRun || existing) {
+                        return res.status(409).json({
+                            code: 'project_onboarding_active',
+                            error: 'Project onboarding is already in progress.',
+                            existingConversationId: liveRun ? (liveRun.conversationId || liveRun.id) : existing.id,
+                            existingRunId: liveRun?.id || existing?.runId,
+                        });
+                    }
+                }
                 // #1394: Dedup guard — return an already-running identical run rather than spawning a second
                 // process. Key includes managerDisplay (messages[0].text) so runs for different issues are
                 // never blocked even when they share the same jobId + hostId + projectPath.

package/dist/src/cli/mcp/fraim-mcp-latest-launcher.js

@@ -232,9 +232,26 @@ function runPackage(plan, cacheDir) {
 const plan = resolvePackage();
 const versionCacheDir = path.join(CACHE_ROOT, plan.packageName + '-' + plan.version.replace(/[^a-zA-Z0-9._-]/g, '_'));
 pruneCaches(versionCacheDir, Date.now());
+
+/**
+ * True when npx materialized the package into this cache. A non-zero exit from a package
+ * that DID install is the CLI's own result, not a cache problem, and must be returned verbatim.
+ */
+function packageMaterialized(cacheDir) {
+  try {
+    const npxDir = path.join(cacheDir, '_npx');
+    return fs.readdirSync(npxDir).some(function (entry) {
+      return fs.existsSync(path.join(npxDir, entry, 'node_modules', plan.packageName));
+    });
+  } catch (error) {
+    return false;
+  }
+}
+
 let status = runPackage(plan, versionCacheDir);
 
-if (status !== 0 && process.platform === 'win32') {
+// Retry ONLY when npx could not materialize the package: the corrupt-cache case this exists for.
+if (status !== 0 && process.platform === 'win32' && !packageMaterialized(versionCacheDir)) {
   const retryCache = path.join(CACHE_ROOT, 'retry-' + Date.now() + '-' + process.pid);
   console.error('[fraim-mcp-launcher] Package execution failed; retrying once with a fresh npm cache.');
   status = runPackage(plan, retryCache);

package/dist/src/cli/setup/user-level-sync.js

@@ -70,6 +70,8 @@ const script_sync_utils_1 = require("../utils/script-sync-utils");
 const USER_LEVEL_RUNTIME_DEPS = {
     'node-edge-tts': '*', // used by scripts/author-audio.js
     'adm-zip': '^0.6.0', // used by scripts/communication/*.js (DOCX review layer) — matches root/packages/* manifests
+    'fast-glob': '^3.3.3', // used by scripts/exec-with-timeout.ts (Issue #1839)
+    'tree-kill': '^1.2.2', // used by scripts/exec-with-timeout.ts (Issue #1839)
 };
 /**
  * Ensure the user-level FRAIM directory structure exists.

package/dist/src/core/utils/project-fraim-paths.js

@@ -7,6 +7,7 @@ exports.WORKSPACE_SYNCED_CONTENT_DIRS = exports.WORKSPACE_FRAIM_DIRNAME = void 0
 exports.getWorkspaceFraimDir = getWorkspaceFraimDir;
 exports.workspaceFraimExists = workspaceFraimExists;
 exports.getWorkspaceConfigPath = getWorkspaceConfigPath;
+exports.workspaceOnboardingReady = workspaceOnboardingReady;
 exports.getWorkspaceFraimPath = getWorkspaceFraimPath;
 exports.assertWorkspaceFraimRoot = assertWorkspaceFraimRoot;
 exports.assertWorkspaceFraimPath = assertWorkspaceFraimPath;
@@ -75,6 +76,19 @@ function workspaceFraimExists(projectRoot = process.cwd()) {
 function getWorkspaceConfigPath(projectRoot = process.cwd()) {
     return (0, path_1.join)(getWorkspaceFraimDir(projectRoot), 'config.json');
 }
+/** Config presence is readiness; unreadable filesystem state is not absence. */
+function workspaceOnboardingReady(projectRoot) {
+    if (!projectRoot)
+        return false;
+    try {
+        (0, fs_1.statSync)(getWorkspaceConfigPath(projectRoot));
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        return code === 'ENOENT' || code === 'ENOTDIR' ? false : null;
+    }
+}
 function getWorkspaceFraimPath(projectRoot = process.cwd(), ...parts) {
     return (0, path_1.join)(getWorkspaceFraimDir(projectRoot), ...parts);
 }