fraim-hub 2.0.349 → 2.0.350

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/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/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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.349",
+  "version": "2.0.350",
   "description": "FRAIM Hub local companion package.",
   "author": "Sid Mathur <sid.mathur@gmail.com>",
   "homepage": "https://github.com/mathursrus/FRAIM#readme",
@@ -246,7 +246,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.349",
+    "fraim": "2.0.350",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",

package/public/ai-hub/script.js

@@ -289,6 +289,7 @@ async function requestJson(url, options, timeoutMs) {
     // #719: callers branch on the HTTP status (e.g. DELETE 404 already-removed vs
     // 409 sequencing error) — carry it on the thrown error.
     error.status = response.status;
+    error.payload = payload;
     throw error;
   }
   return payload;
@@ -434,7 +435,7 @@ function applyBootstrap(bootstrap, docUrl) {
   }
   // Render header project name + status line.
   els['project-name'].textContent = friendlyProjectName(bootstrap.project.path);
-  if (!bootstrap.project.exists || !bootstrap.project.hasFraim) showStatus(bootstrap.project.message, true);
+  if (bootstrap.project.path && !bootstrap.project.exists) showStatus(bootstrap.project.message, true);
   // Update the compact project label shown in task-pane surface rail.
   const tpLabel = document.getElementById('tp-project-label');
   if (tpLabel) {
@@ -1748,6 +1749,8 @@ async function hydrateConversationsFromServer() {
       .filter((conv) => conv && !deletedConversationIds.has(conv.id));
     const mergedHeaders = mergeConversationListHeaders(state.conversations[projectPath] || [], headers);
     state.conversations[projectPath] = mergedHeaders;
+    state._projectConversationFacts = state._projectConversationFacts || {};
+    state._projectConversationFacts[tfCanonicalProjectPath(projectPath)] = true;
     pickActive(mergedHeaders, headerPayload.activeId);
     state.conversationDiskAvailable = true;
     state.conversationBodiesPending = projectPath;
@@ -1769,6 +1772,8 @@ async function hydrateProjectConversationHeaders(projectPath) {
   const incoming = (Array.isArray(payload.conversations) ? payload.conversations : [])
     .filter((conv) => conv && !deletedConversationIds.has(conv.id));
   const existing = state.conversations[projectPath] || [];
+  state._projectConversationFacts = state._projectConversationFacts || {};
+  state._projectConversationFacts[tfCanonicalProjectPath(projectPath)] = true;
   const merged = mergeConversationListHeaders(existing, incoming);
   const changed = existing.length !== merged.length
     || merged.some((conv, index) => conversationProjectionChanged(existing[index], conv));
@@ -2994,21 +2999,37 @@ function appendEmployeeGroupWithActions(container, details) {
 function renderRail() {
   renderTeamRoster();
   renderScopeEmployees(els['conv-list'], 'projects');
+  tfRenderProjectOnboardingAction();
 }
 
 // Availability is a projection of the same readiness used by each Info view.
 // It gates rail assignment only; historical work and onboarding stay reachable.
+function projectOnboardingReadiness(conversations = projectConversations()) {
+  const projectKey = tfCanonicalProjectPath(state.projectPath);
+  const project = state.bootstrap && state.bootstrap.project;
+  const current = project && tfCanonicalProjectPath(project.path) === projectKey;
+  const known = !!(current && typeof project.isOnboarded === 'boolean');
+  const pending = conversations.find(c => c && c.jobId === 'project-onboarding'
+    && convScope(c) === 'project' && tfCanonicalProjectPath(c.projectPath) === projectKey
+    && (c.status === 'running' || convAwaitingReview(c)));
+  const ready = known && project.isOnboarded;
+  const runsKnown = !!(state._projectConversationFacts && state._projectConversationFacts[projectKey]);
+  return {
+    ready, pending, known, runsKnown,
+    needsSetup: known && !ready && runsKnown && !pending,
+    message: ready ? '' : pending ? 'Project onboarding is in progress'
+      : known ? 'Project onboarding needs to be run' : 'Project onboarding status is unavailable',
+  };
+}
+
 function employeeRailReadiness(area, conversations) {
-  const scopeName = area === 'projects' ? 'Project' : area === 'company' ? 'Company' : 'Manager';
+  if (area === 'projects') return projectOnboardingReadiness(conversations);
+  const scopeName = area === 'company' ? 'Company' : 'Manager';
   const key = area === 'company' ? 'org' : 'manager';
-  const project = state.bootstrap && state.bootstrap.project;
-  const context = area === 'projects' ? null : tfCtxCache()[key];
-  const currentProject = project && tfCanonicalProjectPath(project.path) === tfCanonicalProjectPath(state.projectPath);
-  const ready = area === 'projects'
-    ? currentProject && project.hasFraim && !project.needsOnboarding
-    : context && context.present;
+  const context = tfCtxCache()[key];
+  const ready = context && context.present;
   if (ready) return { ready: true, message: '' };
-  const jobId = area === 'projects' ? 'project-onboarding' : area === 'company' ? 'organization-onboarding' : 'manager-agreements';
+  const jobId = area === 'company' ? 'organization-onboarding' : 'manager-agreements';
   const pending = conversations.find(c => c.jobId === jobId && (c.status === 'running' || convAwaitingReview(c)));
   return { ready: false, message: scopeName + ' onboarding is incomplete.', pending };
 }
@@ -3018,6 +3039,12 @@ function renderScopeEmployees(host, area) {
   if (!host) return;
   const isProject = area === 'projects';
   const activeRailProjectKey = isProject ? (tf.activeProjectId || state.projectPath || 'current') : area;
+  const focusedSummary = isProject && host.contains(document.activeElement)
+    && document.activeElement.matches('summary.conv-employee-tab') ? document.activeElement : null;
+  const focusedGroup = focusedSummary && focusedSummary.closest('details');
+  const focusedKey = focusedGroup && focusedGroup.dataset.projectKey === activeRailProjectKey
+    ? focusedGroup.dataset.employeeKey : null;
+  const tooltipWasVisible = focusedSummary && focusedSummary.querySelector('.employee-readiness-tooltip:not([hidden])');
   const employeeGroupOpenState = new Map();
   host.querySelectorAll('details.conv-employee-group[data-employee-key]').forEach((details) => {
     const key = details.dataset ? details.dataset.employeeKey : '';
@@ -3209,7 +3236,7 @@ function renderScopeEmployees(host, area) {
   }
   host.appendChild(inProgressSec);
   const readinessId = 'employee-readiness-' + area;
-  if (!readiness.ready && sortedDoneGroups.some(group => !group.unowned)) {
+  if (!isProject && !readiness.ready && sortedDoneGroups.some(group => !group.unowned)) {
     const note = document.createElement('p');
     note.id = readinessId;
     note.className = 'employee-readiness-note';
@@ -3239,13 +3266,39 @@ function renderScopeEmployees(host, area) {
     const details = document.createElement('details');
     details.className = 'conv-employee-group';
     if (group.unowned) details.classList.add('conv-employee-group--adhoc');
-    else if (!readiness.ready) details.classList.add('conv-employee-group--unavailable');
+    else if (!readiness.ready) {
+      details.classList.add('conv-employee-group--unavailable');
+      if (isProject) details.classList.add('conv-employee-group--project-unavailable');
+    }
     details.dataset.employeeKey = group.key;
     details.dataset.projectKey = activeRailProjectKey;
     details.open = preservedEmployeeGroupOpen(group.key, !!group.unowned);
     const summary = document.createElement('summary');
     summary.className = 'conv-employee-tab';
-    if (!group.unowned && !readiness.ready) summary.title = readiness.message;
+    if (!group.unowned && !readiness.ready) {
+      if (isProject) {
+        const tip = document.createElement('span');
+        tip.id = readinessId + '-' + sortedDoneGroups.indexOf(group);
+        tip.className = 'employee-readiness-tooltip';
+        tip.setAttribute('role', 'tooltip');
+        tip.textContent = readiness.message;
+        tip.hidden = true;
+        summary.setAttribute('aria-describedby', tip.id);
+        const show = () => {
+          tip.hidden = false;
+          const rect = summary.getBoundingClientRect();
+          tip.style.left = Math.max(8, Math.min(rect.left, window.innerWidth - tip.offsetWidth - 8)) + 'px';
+          tip.style.top = Math.max(8, Math.min(rect.bottom, window.innerHeight - tip.offsetHeight - 8)) + 'px';
+        };
+        const hide = () => { tip.hidden = true; };
+        summary.addEventListener('mouseenter', show);
+        summary.addEventListener('focus', show);
+        summary.addEventListener('mouseleave', () => { if (document.activeElement !== summary) hide(); });
+        summary.addEventListener('blur', hide);
+        summary.addEventListener('keydown', (event) => { if (event.key === 'Escape') { hide(); event.stopPropagation(); } });
+        summary.appendChild(tip);
+      } else summary.title = readiness.message;
+    }
     const avatar = group.unowned ? buildNoFraimEmployeeAvatar('conv-employee-avatar') : buildConversationEmployeeAvatar(group.sample, 'conv-employee-avatar');
     const copy = document.createElement('span');
     copy.className = 'conv-employee-tab-copy';
@@ -3274,7 +3327,8 @@ function renderScopeEmployees(host, area) {
       if (!readiness.ready) {
         addBtn.title = readiness.message;
         addBtn.setAttribute('aria-disabled', 'true');
-        addBtn.setAttribute('aria-describedby', readinessId);
+        if (isProject) { addBtn.disabled = true; addBtn.tabIndex = -1; }
+        else addBtn.setAttribute('aria-describedby', readinessId);
       }
       addBtn.addEventListener('click', (e) => {
         e.preventDefault();
@@ -3358,6 +3412,15 @@ function renderScopeEmployees(host, area) {
   if (runsSection) runsSection.hidden = false;
   // #824: re-attach an open run-delete confirm that this rebuild would otherwise drop.
   tfReopenPendingRunDelete(host);
+  if (focusedKey) {
+    const replacement = [...host.querySelectorAll('details[data-employee-key]')]
+      .find(details => details.dataset.employeeKey === focusedKey)?.querySelector(':scope > summary');
+    if (replacement) {
+      replacement.focus({ preventScroll: true });
+      const tooltip = replacement.querySelector('.employee-readiness-tooltip');
+      if (tooltip && !tooltipWasVisible) tooltip.hidden = true;
+    }
+  }
 }
 
 function statusLabel(s) {
@@ -9206,8 +9269,10 @@ async function checkAgentReady(hubId) {
 }
 
 async function refreshEmployees() {
+  const projectPath = state.projectPath;
   try {
-    const bootstrap = await requestJson(`/api/ai-hub/bootstrap?projectPath=${encodeURIComponent(state.projectPath)}`);
+    const bootstrap = await requestJson(`/api/ai-hub/bootstrap?projectPath=${encodeURIComponent(projectPath)}`);
+    if (tfCanonicalProjectPath(state.projectPath) !== tfCanonicalProjectPath(projectPath)) return;
     applyBootstrap(bootstrap);
     renderCpAgentPicker();
     // Issue #1256 (slice b): re-render the install panel + status cards too, not just the
@@ -9280,6 +9345,14 @@ async function startRun(job, instructions, employeeId, preassignedConvId, invoke
   // looking at. stubPath resolution and FRAIM invocation are now server-side.
   const effectiveInstructions = await withWordContext(instructions);
 
+  // Repeated onboarding starts open the same project-owned work, including a
+  // locally queued request that has not received its server run id yet.
+  if (job.id === 'project-onboarding' && context.area === 'projects'
+      && tfCanonicalProjectPath(context.projectPath) === tfCanonicalProjectPath(state.projectPath)) {
+    const pending = projectOnboardingReadiness().pending;
+    if (pending) { await switchToConversation(pending.id); return { ok: true }; }
+  }
+
   const assignedPersonaKey = assignedPersonaKeyForJob(job);
   const assignedPersona = assignedPersonaKey && assignedPersonaKey.startsWith('custom:')
     ? (typeof tfPersonaByKey === 'function' ? tfPersonaByKey(assignedPersonaKey) : null)
@@ -9331,7 +9404,7 @@ async function startRun(job, instructions, employeeId, preassignedConvId, invoke
       return (a === 'manager' || a === 'company') ? a : 'project';
     })(),
   };
-  upsertConversation(conv);
+  upsertConversation(conv, { disk: job.id !== 'project-onboarding' });
   state.activeId = conv.id;
   tf.areaSelection[tfAreaSelectionKey(context.area)] = conv.id;
   persistActiveConversationSelection(conv.id);
@@ -9383,6 +9456,14 @@ async function startRun(job, instructions, employeeId, preassignedConvId, invoke
     }
     return { ok: true, conversation: conv, run };
   } catch (error) {
+    if (job.id === 'project-onboarding' && error.status === 409
+        && error.payload?.code === 'project_onboarding_active' && error.payload.existingConversationId) {
+      const key = convBucketKey(conv);
+      const bucket = state.conversations[key];
+      if (Array.isArray(bucket)) state.conversations[key] = bucket.filter(c => c.id !== conv.id);
+      await openExistingProjectOnboarding(error.payload.existingConversationId, conv.projectPath);
+      return { ok: true };
+    }
     const message = error && error.message ? error.message : 'Could not start the run.';
     conv.status = 'failed';
     conv.events.push({ channel: 'system', text: message });
@@ -11093,59 +11174,13 @@ function beginHirePendingPoll() {
 }
 
 async function autoOnboardProject() {
-  const employeeId = state.selectedEmployeeId || 'claude';
-  const onboardingMessage = "Your AI employee is onboarding to this project. They'll explore the codebase, learn how it's structured, and may ask a few questions so they can contribute meaningfully.";
-  const job = (state.bootstrap && state.bootstrap.jobs || []).find((j) => j.id === 'project-onboarding');
-  if (job) {
-    await startRun(job, onboardingMessage, employeeId);
-    return;
-  }
-  // Fallback: project-onboarding job not in catalog (fraim/ doesn't exist yet) — POST directly.
-  try {
-    const conversationId = newConversationId();
-    const run = await requestJson('/api/ai-hub/runs', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        projectPath: state.projectPath,
-        hostId: baseHostIdForAgent(employeeId),
-        configuredAgentId: employeeId,
-        jobId: 'project-onboarding',
-        jobTitle: 'Project Onboarding',
-        conversationId,
-        conversationTitle: 'Project Onboarding',
-        message: onboardingMessage,
-      }),
-    });
-    const startedAt = Date.now();
-    const conv = {
-      id: conversationId,
-      projectPath: state.projectPath,
-      title: 'Project Onboarding',
-      jobId: 'project-onboarding',
-      jobTitle: 'Project Onboarding',
-      agentName: employeeId,
-      configuredAgentId: employeeId,
-      configuredAgentLabel: configuredAgentLabel(employeeId),
-      baseHostId: baseHostIdForAgent(employeeId),
-      runId: run.id,
-      sessionId: run.sessionId || null,
-      status: 'running',
-      messages: [{ role: 'manager', text: onboardingMessage, at: Date.now() }],
-      events: [],
-      artifacts: [],
-      createdAt: startedAt,
-      lastUpdatedAt: startedAt,
-    };
-    foldRunIntoConversation(conv, run);
-    upsertConversation(conv);
-    state.activeId = conv.id;
-    persistActiveConversationSelection(conv.id);
-    renderRail();
-    renderActive();
-    startPolling();
-  } catch (err) {
-    showStatus(err.message, true);
+  return tfStartProjectOnboarding();
+}
+
+async function openExistingProjectOnboarding(conversationId, projectPath) {
+  await hydrateProjectConversationHeaders(projectPath);
+  if (tfCanonicalProjectPath(state.projectPath) === tfCanonicalProjectPath(projectPath)) {
+    await switchToConversation(conversationId);
   }
 }
 
@@ -11257,57 +11292,10 @@ function renderFirstRunLanding(mode) {
       }
       return;
     }
-    // Legacy first-run path: auto-start project-onboarding.
-    startBtn.textContent = 'Starting…';
-    renderActive();
-    const job = (state.bootstrap && state.bootstrap.jobs || []).find((j) => j.id === 'project-onboarding');
-    const employeeId = state.selectedEmployeeId || 'claude';
-    if (job) {
-      await startRun(job, 'Onboard this project', employeeId);
-    } else {
-      try {
-        const run = await requestJson('/api/ai-hub/runs', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({
-            projectPath: state.projectPath,
-            hostId: baseHostIdForAgent(employeeId),
-            configuredAgentId: employeeId,
-            jobId: 'project-onboarding',
-            message: 'Onboard this project',
-          }),
-        });
-        const startedAt = Date.now();
-        const conv = {
-          id: newConversationId(),
-          projectPath: state.projectPath,
-          title: 'Project Onboarding',
-          jobId: 'project-onboarding',
-          jobTitle: 'Project Onboarding',
-          agentName: employeeId,
-          configuredAgentId: employeeId,
-          configuredAgentLabel: configuredAgentLabel(employeeId),
-          baseHostId: baseHostIdForAgent(employeeId),
-          runId: run.id,
-          sessionId: run.sessionId || null,
-          status: 'running',
-          messages: [{ role: 'manager', text: 'Onboard this project', at: Date.now() }],
-          events: [],
-          artifacts: [],
-          createdAt: startedAt,
-          lastUpdatedAt: startedAt,
-        };
-        foldRunIntoConversation(conv, run);
-        upsertConversation(conv);
-        state.activeId = conv.id;
-        persistActiveConversationSelection(conv.id);
-        renderRail();
-        renderActive();
-        startPolling();
-      } catch (err) {
-        showStatus(err.message, true);
-      }
-    }
+    const selected = tfEnsureCurrentProject();
+    tfShowArea('projects');
+    await tfSelectProjectView('workspace', selected && selected.id, { confirmSetup: false });
+    await tfStartProjectOnboarding();
   });
   card.appendChild(startBtn);
 
@@ -12128,11 +12116,10 @@ function tfNormalizeProject(raw, fallbackPath) {
     // Roster is derived from hired personas at render time (tfProjectTeamKeys),
     // never stored per machine. Any legacy `team` on stored state is dropped.
     updatedAt: raw.updatedAt || undefined,
-    // Issue #1253: the server's response-only marker for whether this folder is
-    // actually a FRAIM project. `undefined` means the server did not say — only an
-    // explicit false marks an entry as not set up, so a locally minted entry is
-    // never mistaken for one.
+    // Discovery and onboarding readiness are separate response-only facts.
+    // Undefined means the server did not provide a known result.
     hasFraim: typeof raw.hasFraim === 'boolean' ? raw.hasFraim : undefined,
+    isOnboarded: typeof raw.isOnboarded === 'boolean' ? raw.isOnboarded : undefined,
   };
 }
 
@@ -12157,21 +12144,9 @@ function tfProjectForPath(folderPath) {
   return tf.projects.find((project) => tfCanonicalProjectPath(project.folderPath || project.path || project.folder) === key) || null;
 }
 
-/**
- * Issue #1253: is this LISTED project a FRAIM project?
- *
- * Tri-state on purpose. `hasFraim` is a response-only decoration, so `undefined`
- * means "the server did not say" — a locally minted entry, or a list from before the
- * field existed — and must NOT read as "not set up". Only an explicit `false` does.
- * Writing `!project.hasFraim` inline instead would quietly mark every undecorated
- * entry as unset, which is why this is a named predicate rather than a comparison
- * repeated at each site.
- *
- * Note this takes a project-list ENTRY. `bootstrap.project` is a different shape
- * (`AiHubProjectSummary`), where `hasFraim` is a required boolean.
- */
+// Listed readiness is response-only. Unknown facts do not label a project unset.
 function tfProjectIsSetUp(project) {
-  return !project || project.hasFraim !== false;
+  return !project || project.isOnboarded !== false;
 }
 
 /**
@@ -12186,6 +12161,7 @@ function tfProjectIsSetUp(project) {
 function tfAskProjectSetup(folderPath) {
   const modal = document.getElementById('setup-project-modal');
   if (!modal) return Promise.resolve('cancel');
+  const previousFocus = document.activeElement;
   const folder = document.getElementById('spm-folder');
   if (folder) folder.textContent = folderPath || '';
   modal.hidden = false;
@@ -12194,8 +12170,17 @@ function tfAskProjectSetup(folderPath) {
     const finish = (choice) => {
       modal.hidden = true;
       for (const [el, handler] of wired) el.removeEventListener('click', handler);
+      document.removeEventListener('keydown', onEscape, true);
+      if (previousFocus && previousFocus.isConnected) previousFocus.focus({ preventScroll: true });
       resolve(choice);
     };
+    const onEscape = (event) => {
+      if (event.key !== 'Escape') return;
+      event.preventDefault();
+      event.stopPropagation();
+      finish('cancel');
+    };
+    document.addEventListener('keydown', onEscape, true);
     const bind = (id, choice) => {
       const el = document.getElementById(id);
       if (!el) return;
@@ -12207,24 +12192,25 @@ function tfAskProjectSetup(folderPath) {
     bind('spm-choose', 'choose');
     bind('spm-cancel', 'cancel');
     bind('spm-close', 'cancel');
+    document.getElementById('spm-cancel')?.focus();
   });
 }
 
 /**
  * Issue #1253 R3: the single place that decides whether to scaffold a folder.
  *
- * `needsOnboarding` is the server's own `exists && !hasFraim`, so this fires on every
- * path that lands on such a bootstrap — the page load, and a project switch from the
- * Overview or a project tab — rather than being duplicated per entry point. Nothing
- * is written unless the user chooses Set up; Cancel and dismissal both leave the
- * folder exactly as it was.
- *
+ * Config presence and same-project active work come from the same readiness
+ * projection as the employee rail. Refresh run headers before offering setup;
+ * missing facts defer the dialog. Cancel preserves the selected folder.
  * Returns true when setup was started.
  */
 async function tfMaybeConfirmProjectSetup() {
-  const project = (state.bootstrap && state.bootstrap.project) || null;
-  if (!project || !project.needsOnboarding || !state.projectPath) return false;
-  const choice = await tfAskProjectSetup(state.projectPath);
+  const projectPath = state.projectPath;
+  if (!projectPath) return false;
+  try { await hydrateProjectConversationHeaders(projectPath); } catch (_) { return false; }
+  if (state.projectPath !== projectPath || !projectOnboardingReadiness().needsSetup) return false;
+  const choice = await tfAskProjectSetup(projectPath);
+  if (state.projectPath !== projectPath) return false;
   if (choice === 'setup') {
     await autoOnboardProject();
     return true;
@@ -12566,7 +12552,7 @@ function tfShowArea(area) {
   window.scrollTo(0, 0);
 }
 
-async function tfSelectProjectView(view, projectId) {
+async function tfSelectProjectView(view, projectId, options) {
   tf.projectView = view;
   if (projectId) tf.activeProjectId = projectId;
   // Always return to the conversation when changing views.
@@ -12593,13 +12579,14 @@ async function tfSelectProjectView(view, projectId) {
     if (folderPath && tfCanonicalProjectPath(folderPath) !== tfCanonicalProjectPath(state.projectPath)) {
       try {
         tfSetProjectSwitching(true, proj);
-        await tfSwitchProjectFolder(folderPath);
+        await tfSwitchProjectFolder(folderPath, options);
       } catch (e) {
         console.warn('[512] tfSwitchProjectFolder failed:', e);
       } finally {
         tfSetProjectSwitching(false);
       }
     }
+    if (folderPath && tfCanonicalProjectPath(folderPath) !== tfCanonicalProjectPath(state.projectPath)) return;
     // #521 fix: invalidate the project-scoped context cache whenever the active
     // project changes — covers new-project creation (where state.projectPath is
     // already updated, so tfSwitchProjectFolder's guard skips its own clear) and
@@ -13348,45 +13335,14 @@ function tfSelectAssignmentConversation(assignment) {
 // conversation pane — always present, individually collapsible — replacing the
 // old over-conversation panels. The editable brief rows and the learnings list
 // are unchanged; only their home moved.
-// #521: state of the project-onboarding run for THIS project — drives the
-// "team is processing / here's their understanding" framing in the Brief.
-function tfProjectOnboardingRun() {
-  let running = null, awaiting = null;
-  for (const c of projectConversations()) {
-    if (!c || c.jobId !== 'project-onboarding') continue;
-    if (c.status === 'running') running = c;
-    else if (typeof convAwaitingReview === 'function' && convAwaitingReview(c)) awaiting = c;
-  }
-  return { running, awaiting };
-}
-
 function tfRenderProjectContextTop() {
   const heading = document.getElementById('project-info-heading');
   const project = tf.projects.find((entry) => entry.id === tf.activeProjectId);
   if (heading) heading.textContent = project ? project.name : ((state.projectPath || '').split(/[\\/]/).filter(Boolean).pop() || 'Project');
   // Issue #1198: which folder this project points at, always on screen.
   tfRenderProjectFolderRow();
-  // Onboarding loop framing renders ABOVE the accordions (#proj-onboarding-banner)
-  // so it's visible even when the Brief is collapsed — collapsing the Brief by
-  // default is what gives the conversation thread room to breathe.
   const obBannerHost = document.getElementById('proj-onboarding-banner');
-  if (obBannerHost) {
-    obBannerHost.innerHTML = '';
-    const ob = tfProjectOnboardingRun();
-    if (ob.running || ob.awaiting) {
-      const banner = document.createElement('div');
-      banner.className = 'ob-brief-banner' + (ob.awaiting ? ' ob-review' : ' ob-processing');
-      if (ob.awaiting) {
-        // #521: the run + Approve now live in the conversation view (open the
-        // Project Onboarding run from the sidebar). This page is for reviewing
-        // and editing the captured context — edits save to the project.
-        banner.innerHTML = '<span class="obb-ico">✅</span><div><strong>Onboarding finished.</strong> Review the captured context below and edit anything that\'s off. Your edits save to the project. Then open the <strong>Project Onboarding</strong> run in the sidebar to <strong>Approve</strong> (or request changes).</div>';
-      } else {
-        banner.innerHTML = '<span class="obb-ico">🤝</span><div><strong>Your FRAIM team is processing the project context.</strong> They\'ll fill in the Brief below for you to review and correct. Track progress in the <strong>Project Onboarding</strong> run in the sidebar.</div>';
-      }
-      obBannerHost.appendChild(banner);
-    }
-  }
+  if (obBannerHost) obBannerHost.replaceChildren();
   const briefHost = document.getElementById('proj-brief-profile');
   if (briefHost) tfRenderBriefProfile(briefHost);
   const learnHost = document.getElementById('project-learnings');
@@ -13397,7 +13353,7 @@ function tfRenderProjectContextTop() {
   // #693 R1: the retired "Project Updates" section's actions now live where their
   // output lands — Run Project Onboarding in the Brief section, Sleep on learnings
   // in the Learnings section.
-  tfEnsureAccAction('proj-brief-acc', '🚀', 'Run Project Onboarding', () => tfOpenOnboardInput('run'));
+  tfRenderProjectOnboardingAction();
   tfEnsureAccActions('proj-learnings-acc', [
     { ico: '🧠', label: 'Sleep on learnings', onClick: () => tfRunShareLearnings('project') },
     { ico: '↑', label: 'Share with others', onClick: () => {
@@ -13416,6 +13372,16 @@ function tfRenderProjectContextTop() {
 // #693 R1: insert (idempotently) a single lifecycle-action button at the top of a
 // ctx accordion's body. Used to place onboarding/sleep actions inside the Brief,
 // Learnings, and Company/Manager context sections they populate.
+function tfRenderProjectOnboardingAction() {
+  const onboarding = projectOnboardingReadiness();
+  const label = onboarding.pending ? 'Continue onboarding' : onboarding.ready ? 'Reprocess project onboarding' : 'Run Project Onboarding';
+  tfEnsureAccAction('proj-brief-acc', '', label, () => {
+    const current = projectOnboardingReadiness();
+    if (current.pending) switchToConversation(current.pending.id);
+    else tfOpenOnboardInput(current.ready ? 'reprocess' : 'run');
+  });
+}
+
 function tfEnsureAccAction(accId, ico, label, onClick) {
   tfEnsureAccActions(accId, [{ ico, label, onClick }]);
 }
@@ -13446,12 +13412,11 @@ function tfEnsureAccActions(accId, actions) {
   }
 }
 
-// #521: the Brief section is the project's real captured context + rules — the two
-// files Project Onboarding writes (project_context.md, project_rules.md). There is
-// no separate "brief" row (it was redundant with context). When neither file has
-// content yet, show a single "Run Project Onboarding" call-to-action instead of
-// empty rows; once there is content, show the rows + a quiet "Re-run".
+// Brief renders project-owned context and rules; the action row is shared with
+// readiness updates so its single CTA remains current while runs change state.
 async function tfRenderBriefProfile(host) {
+  const projectPath = tfCanonicalProjectPath(state.projectPath);
+  const renderId = host._briefRenderId = (host._briefRenderId || 0) + 1;
   host.innerHTML = '';
   const loading = document.createElement('div');
   loading.className = 'ctx-loading';
@@ -13464,42 +13429,27 @@ async function tfRenderBriefProfile(host) {
     return c ? Promise.resolve(c) : tfFetchContext(key).catch(() => null);
   };
   const [ctx, rules] = await Promise.all([getCtx('projectContext'), getCtx('projectRules')]);
-  if (!host.isConnected) return; // re-rendered while awaiting
+  if (!host.isConnected || host._briefRenderId !== renderId || projectPath !== tfCanonicalProjectPath(state.projectPath)) return;
   host.innerHTML = '';
 
   const has = (d) => !!(d && d.present && d.content && String(d.content).trim());
   if (!has(ctx) && !has(rules)) {
-    // Nothing captured yet → just the Run Project Onboarding CTA (shared .ctx-cta
-    // shape so the Brief and Learnings empty states look identical).
     const cta = document.createElement('div');
     cta.className = 'ctx-cta';
     const msg = document.createElement('div');
     msg.className = 'ctx-cta-msg';
-    msg.textContent = "Nothing captured yet. Run Project Onboarding and your team will explore the project and fill in its context and rules here.";
-    const btn = document.createElement('button');
-    btn.className = 'ctx-cta-btn';
-    btn.type = 'button';
-    btn.textContent = '🚀 Run Project Onboarding';
-    btn.addEventListener('click', () => { tfOpenOnboardInput('run'); });
-    cta.appendChild(msg); cta.appendChild(btn);
+    const onboarding = projectOnboardingReadiness();
+    msg.textContent = onboarding.pending ? 'Your team is processing the project context. Continue onboarding to see progress or review the work.'
+      : onboarding.ready ? 'No project context or rules have been captured yet.'
+      : 'Nothing captured yet. Run Project Onboarding to fill in this project’s context and rules.';
+    cta.appendChild(msg);
     host.appendChild(cta);
     return;
   }
 
-  // Have real content → show Context + Rules (the cache is warm, so these render
-  // immediately), plus a quiet Re-run for when the project changes.
+  // Captured context and rules remain directly editable.
   host.appendChild(tfContextRow('projectContext', 'Context', 'No context captured yet. Run Project Onboarding, or click Edit to write it yourself.', null));
   host.appendChild(tfContextRow('projectRules', 'Rules', 'No rules captured yet. Run Project Onboarding, or click Edit to add them yourself.', null));
-  const foot = document.createElement('div');
-  foot.className = 'syn-row ctx-rerun-row';
-  const rerun = document.createElement('button');
-  rerun.className = 'syn-edit';
-  rerun.type = 'button';
-  rerun.textContent = 'Reprocess project onboarding';
-  rerun.title = 'Re-run onboarding: your team reads the current context & rules (including your edits) and refines them';
-  rerun.addEventListener('click', () => { tfOpenOnboardInput('reprocess'); });
-  foot.appendChild(rerun);
-  host.appendChild(foot);
 }
 // Back-compat shims: the brief/learnings now live in always-present top sections.
 // Expand the relevant section if asked; the old "hide panels" call is a no-op.
@@ -17456,14 +17406,32 @@ function tfStartOrgLearningSynthesis() {
   );
 }
 
-async function tfStartProjectOnboarding(userInput) {
+async function tfStartProjectOnboarding(userInput, mode = 'run') {
+  const projectPath = state.projectPath;
+  if (!projectPath) { showStatus('Choose a project folder before starting onboarding.', true); return; }
+  try {
+    // Project selection already fetched these facts. Reuse them without a second
+    // background fetch; the launch guard and job sync recheck authoritative state.
+    await Promise.all([loadBootstrap(projectPath, '', { preferCache: true, backgroundRefresh: false }), hydrateProjectConversationHeaders(projectPath)]);
+  } catch (error) { showStatus(error.message, true); return; }
+  if (state.projectPath !== projectPath) return;
+  const readiness = projectOnboardingReadiness();
+  if (readiness.pending) return switchToConversation(readiness.pending.id);
+  if (!readiness.known) {
+    showStatus('Project onboarding status is unavailable. Check access to the project folder and try again.', true);
+    return;
+  }
+  if (readiness.ready && mode !== 'reprocess') {
+    showStatus('Project is already onboarded. Use Reprocess project onboarding in the Brief to update it.');
+    return;
+  }
   // The project's captured context/rules live in real files (project_context.md,
   // project_rules.md) and the Brief section edits them directly. So onboarding is
   // seeded from those files — the job reads them and preserves manager edits,
   // refining/extending rather than regenerating. We don't pass stale in-memory
   // intent/outcome here; the files are the source of truth.
   const parts = [
-    'Onboard this project.',
+    mode === 'reprocess' ? 'Reprocess project onboarding.' : 'Onboard this project.',
     'Read the existing fraim/personalized-employee/context/project_context.md and fraim/personalized-employee/rules/project_rules.md if they are present, and treat them as the source of truth. Preserve everything I have already written there (including any URLs or constraints I added by hand).',
     'Then capture or refine durable project context and project rules and write the updated project_context.md and project_rules.md (a superset of the existing content, never a regeneration from scratch).',
   ];
@@ -17472,14 +17440,18 @@ async function tfStartProjectOnboarding(userInput) {
   if (userInput && userInput.trim()) {
     parts.push('My direction for this onboarding pass:\n' + userInput.trim());
   }
-  await tfStartOnboardingJob('project-onboarding', parts.join('\n\n'), 'projects');
+  const job = ((state.bootstrap && state.bootstrap.jobs) || []).find(j => j.id === 'project-onboarding')
+    || { id: 'project-onboarding', title: 'Project Onboarding' };
+  await startRun(job, parts.join('\n\n'), state.selectedEmployeeId || 'claude', undefined, 'projects');
 }
 
 // #594 R7: #onboard-input-modal retired. tfOpenOnboardInput now opens #np-modal
 // with the folder pre-filled and locked so the manager can only supply a direction
 // message (the intent field) before starting the re-run.
-function tfOpenOnboardInput() {
-  tfOpenNewProjectRerun();
+function tfOpenOnboardInput(mode = 'run') {
+  const readiness = projectOnboardingReadiness();
+  if (readiness.pending) { switchToConversation(readiness.pending.id); return; }
+  tfOpenNewProjectRerun(mode);
 }
 function tfCloseOnboardInput() {
   tfCloseNewProject();
@@ -17487,12 +17459,13 @@ function tfCloseOnboardInput() {
 function tfSubmitOnboardInput() {
   const intent = document.getElementById('np-intent');
   const val = intent ? intent.value : '';
+  const mode = document.getElementById('np-modal')?.dataset.onboardingMode || 'run';
   tfCloseNewProject();
-  tfStartProjectOnboarding(val);
+  tfStartProjectOnboarding(val, mode);
 }
-function tfOpenNewProjectRerun() {
+function tfOpenNewProjectRerun(mode = 'run') {
   const modal = document.getElementById('np-modal');
-  if (!modal) { tfStartProjectOnboarding(); return; }
+  if (!modal) { tfStartProjectOnboarding('', mode); return; }
   const name = document.getElementById('np-name');
   const folder = document.getElementById('np-folder');
   const np1Next = document.getElementById('np1-next');
@@ -17528,6 +17501,7 @@ function tfOpenNewProjectRerun() {
   const np1Hint = document.querySelector('#np1 .np-field-hint');
   if (np1Hint) { np1Hint.dataset.originalText = np1Hint.textContent; np1Hint.textContent = 'This project folder is already set. Only the direction below will change.'; }
   modal.dataset.rerun = '1';
+  modal.dataset.onboardingMode = mode;
   tfNpGo(1);
   modal.hidden = false;
   if (np1Next) setTimeout(() => np1Next.focus(), 0);
@@ -17561,7 +17535,7 @@ function tfOpenNewProject() {
 }
 function tfCloseNewProject() {
   const m = document.getElementById('np-modal');
-  if (m) { m.hidden = true; delete m.dataset.rerun; }
+  if (m) { m.hidden = true; delete m.dataset.rerun; delete m.dataset.onboardingMode; }
   const disc = document.getElementById('np-discard');
   if (disc) disc.hidden = true;
   tf._npPendingClose = null;
@@ -17698,6 +17672,10 @@ function tfRenderNpSummary() {
   host.appendChild(note);
 }
 async function tfCreateProject() {
+  if (document.getElementById('np-modal')?.dataset.rerun === '1') {
+    tfSubmitOnboardInput();
+    return;
+  }
   const val = (id) => ((document.getElementById(id) || {}).value || '').trim();
   const folderPath = val('np-folder');
   if (!folderPath) { alert('Please choose a project folder first.'); return; }
@@ -17740,7 +17718,9 @@ async function tfCreateProject() {
   // new-project wizard, which IS the consent, and this function starts onboarding
   // itself a few lines below. Asking again would be a second prompt for a decision
   // already made.
-  await tfSwitchProjectFolder(folderPath, { confirmSetup: false });
+  tfShowArea('projects');
+  await tfSelectProjectView('workspace', savedProject.id, { confirmSetup: false });
+  if (tfCanonicalProjectPath(state.projectPath) !== tfCanonicalProjectPath(folderPath)) return;
   const currentProject = tfProjectForPath(folderPath) || savedProject;
   if (currentProject) {
     tf.activeProjectId = currentProject.id;
@@ -17767,14 +17747,8 @@ async function tfCreateProject() {
     `Team: ${tfProjectTeamKeys().join(', ') || 'no employees assigned yet'}`,
   ].filter(Boolean).join('\n\n');
 
-  if (onboardingContext) {
-    const job = ((state.bootstrap && state.bootstrap.jobs) || []).find((j) => j.id === 'project-onboarding')
-      || { id: 'project-onboarding', intent: 'Onboard this project.' };
-    try {
-      await startRun(job, onboardingContext || 'Set up this project.', state.selectedEmployeeId || 'claude');
-    } catch (e) {
-      console.warn('[512] project-onboarding start failed (non-blocking):', e);
-    }
+  if (tfCanonicalProjectPath(state.projectPath) === tfCanonicalProjectPath(folderPath)) {
+    await tfStartProjectOnboarding(onboardingContext);
   }
 }
 
@@ -17799,6 +17773,9 @@ async function tfSwitchProjectFolder(folderPath, options) {
     return;
   }
   state.projectPath = normalized.folderPath;
+  const switchPath = normalized.folderPath;
+  const selectedProject = tfProjectForPath(switchPath);
+  if (selectedProject) tf.activeProjectId = selectedProject.id;
   tfInvalidateRejections();
   // Cross-project leak fix (docs/rca/hub-conversation-cross-project-leak.md): drop the previous
   // project's active conversation on switch. Otherwise the just-finished run stays state.activeId
@@ -17813,40 +17790,22 @@ async function tfSwitchProjectFolder(folderPath, options) {
   // re-fetch for this folder; org/manager keys are user-level and stay.
   const cache = tfCtxCache();
   for (const k of ['projectContext', 'projectBrief', 'projectRules']) delete cache[k];
+  // Clear old rendered context synchronously, before a setup modal can open.
+  tfRenderProjectTabs();
+  tfRenderProjectContextTop();
   // loadBootstrap sends projectPath as a query param — the server records it
   // in its preferences store so this folder becomes the default on next load.
-  const cachedConversations = Array.isArray(state.conversations[normalized.folderPath]);
-  const conversationsPromise = cachedConversations ? null : hydrateConversationsFromServer();
+  const conversationsPromise = hydrateConversationsFromServer();
   await loadBootstrap(normalized.folderPath, undefined, { preferCache: true });
-  if (cachedConversations) {
-    renderRail();
-    renderActive();
-    hydrateConversationsFromServer().catch((error) =>
-      console.warn('[512] Could not refresh project conversations:', error)
-    );
-  } else {
-    await conversationsPromise;
-  }
+  await conversationsPromise;
+  if (state.projectPath !== switchPath) return;
   tfAdoptServerProjects(state.bootstrap && Array.isArray(state.bootstrap.projects) ? state.bootstrap.projects : []);
   const currentProject = tfEnsureCurrentProject();
   if (currentProject) tf.activeProjectId = currentProject.id;
   tfRefreshAfterBootstrap();
-  // Issue #1253 R3: entering a folder with no fraim/ is what starts scaffolding it,
-  // so the same confirmation the page load uses fires here. Declining leaves the
-  // folder untouched and returns to the Overview rather than parking the user in a
-  // workspace with nothing in it.
+  // Setup is optional for this valid selection; cancelling leaves it selected.
   if (confirmSetup && state.bootstrap && state.bootstrap.project && state.bootstrap.project.needsOnboarding) {
-    const started = await tfMaybeConfirmProjectSetup();
-    if (!started) {
-      // The switch above already recorded this folder server-side. Declining must
-      // undo that, not just navigate away: a folder the user declined to set up is
-      // exactly the kind of value #1253 is about, and leaving it recorded would put
-      // it back in front of them on the next launch.
-      state.projectPath = '';
-      tf.activeProjectId = null;
-      await loadBootstrap('');
-      await tfSelectProjectView('overview');
-    }
+    await tfMaybeConfirmProjectSetup();
   }
 }
 
@@ -18594,6 +18553,7 @@ function tfWireShell() {
   ];
   document.addEventListener('keydown', (e) => {
     if (e.key !== 'Escape') return;
+    document.querySelectorAll('.employee-readiness-tooltip').forEach(tip => { tip.hidden = true; });
     // When the discard confirm is up, Escape means "keep editing" — dismiss it,
     // never fall through and re-trigger it on the wizard beneath.
     const npDiscardEl = document.getElementById('np-discard');

package/public/ai-hub/styles.css

@@ -658,6 +658,38 @@ img.conv-employee-avatar {
 .employee-readiness-note { margin: 8px 4px; color: var(--muted); font-size: 11px; line-height: 1.45; }
 .employee-readiness-note .ctx-acc-action { display: flex; margin-top: 6px; max-width: 100%; white-space: normal; text-align: left; color: var(--accent-strong); }
 .employee-readiness-note .ctx-acc-action:hover { background: var(--accent-strong); color: var(--surface); }
+.conv-employee-group--project-unavailable > summary {
+  background: var(--line);
+  color: var(--muted);
+  border-radius: 7px;
+}
+.conv-employee-group--project-unavailable > summary .conv-employee-avatar {
+  background: var(--soft);
+  color: var(--muted);
+  filter: grayscale(1);
+}
+.conv-employee-group--project-unavailable > summary .conv-employee-tab-label { font-weight: 500; }
+.conv-employee-group--project-unavailable .taught-badge { background: transparent; color: var(--muted); border-color: var(--line); }
+.conv-employee-row:has(.conv-employee-group--project-unavailable) .conv-employee-add:disabled { opacity: .55; }
+.employee-readiness-tooltip {
+  position: fixed;
+  z-index: 10000;
+  width: 260px;
+  max-width: calc(100vw - 16px);
+  padding: 10px 12px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface);
+  color: var(--text);
+  box-shadow: var(--shadow-lg);
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 1.5;
+  white-space: normal;
+  text-transform: none;
+  letter-spacing: normal;
+}
+.employee-readiness-tooltip[hidden] { display: none; }
 .conv-employee-tab-detail {
   font-size: 10px;
   font-weight: 500;
@@ -6098,6 +6130,9 @@ img.eh-av { object-fit: cover; background: var(--surface); }
   border: 1px solid rgba(0,113,227,.2);
 }
 .ctx-acc-action:hover { background: var(--accent); color: #fff; }
+#proj-brief-acc .ctx-acc-action,
+#proj-brief-acc .syn-edit { color: var(--accent-strong); }
+#proj-brief-acc .ctx-acc-action:hover { background: var(--accent-strong); color: var(--surface); }
 .ctx-acc-action .caa-ico { font-size: 14px; line-height: 1; }
 
 /* #693.2 — consolidated New Assignment dialog: segmented Scheduled/Triggered. */