fraim-hub 2.0.241 → 2.0.243

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

@@ -1092,6 +1092,13 @@ function appendHostMessage(run, hostId, event, channel) {
         return;
     run.messages.push((0, hosts_1.createHubMessage)('employee', displayMessage));
 }
+function isCodexMissingReasoningResumeError(run) {
+    return (run.events || []).some((event) => {
+        const text = String(event.text || '');
+        return text.includes("provided without its required 'reasoning' item") ||
+            text.includes('provided without its required "reasoning" item');
+    });
+}
 // Apply a parsed seekMentoring tool-use signal from the host stream to
 // the run state. Returns the updated currentPhase.
 function applySeekMentoringSignal(run, signal) {
@@ -1437,6 +1444,19 @@ function ensureDirectoryPath(projectPath) {
     }
     return resolved;
 }
+function readRunScope(raw) {
+    return raw === 'manager' || raw === 'company' ? raw : 'project';
+}
+// Working directory for a project-independent run when no project exists: the user-level
+// FRAIM home (where org/manager onboarding artifacts live), or the process cwd as a
+// last resort. This is an execution anchor only — it is deliberately NOT recorded as the
+// Hub's active project (#866: the launch/fallback dir must not masquerade as a project).
+function projectIndependentWorkingDir() {
+    const userFraim = (0, project_fraim_paths_1.getUserFraimDirPath)();
+    if (directoryExists(userFraim))
+        return path_1.default.resolve(userFraim);
+    return process.cwd();
+}
 function normalizedDirectoryPath(projectPath) {
     const resolved = path_1.default.resolve(projectPath);
     return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
@@ -1534,6 +1554,30 @@ function recoveryBackoffMs(attempt) {
     const base = 600 * Math.pow(2, attempt - 1); // 600, 1200, 2400ms
     return base + Math.floor(0.2 * base); // +20% deterministic jitter
 }
+function buildHubRecoveryContinueMessage(run, exitCode, attempt) {
+    return [
+        '[FRAIM Hub system recovery]',
+        'The FRAIM Hub is automatically recovering this interrupted run.',
+        'This is not a manager-authored instruction. Do not say the manager asked you to continue.',
+        `Run id: ${run.id}`,
+        `Session id: ${run.sessionId || 'unknown'}`,
+        `Recovery attempt: ${attempt}/${MAX_RECOVERY_ATTEMPTS}`,
+        `Prior exit code: ${exitCode ?? 'unknown'}`,
+        'Resume only if the tracked FRAIM phase is non-terminal and not waiting for human review or approval.',
+    ].join('\n');
+}
+function createHubRecoveryEvent(run, exitCode, attempt) {
+    return (0, hosts_1.createHubEvent)('system', `Hub auto-recovery attempt ${attempt}/${MAX_RECOVERY_ATTEMPTS} for run ${run.id} session ${run.sessionId || 'unknown'} after exit ${exitCode ?? 'unknown'}.`);
+}
+function isHumanActionGate(run) {
+    if (run.stoppedByUser)
+        return true;
+    if (run.reviewHandoff?.reviewRequired)
+        return true;
+    const phaseHistory = run.phaseHistory || [];
+    const lastEntry = phaseHistory.length > 0 ? phaseHistory[phaseHistory.length - 1] : null;
+    return lastEntry?.latestStatus === 'incomplete' || lastEntry?.latestStatus === 'failure';
+}
 function restartRecoveryBucketOwnershipReason(conversation, bucketKey) {
     if (!bucketKey)
         return null;
@@ -1588,8 +1632,11 @@ function classifyExit(run, exitCode) {
         return { action: 'error', pauseReason: 'error' };
     }
     // Clean exit (code 0).
-    if (run.reviewHandoff?.reviewRequired) {
-        return { action: 'park', pauseReason: 'awaiting_review' };
+    if (isHumanActionGate(run)) {
+        if (run.reviewHandoff?.reviewRequired) {
+            return { action: 'park', pauseReason: 'awaiting_review' };
+        }
+        return { action: 'park', pauseReason: 'awaiting_user' };
     }
     // FRAIM job: use the phase signal the server already tracks.
     const phaseHistory = run.phaseHistory || [];
@@ -1839,6 +1886,18 @@ class AiHubServer {
         // (#866 R2). Never falls back to cwd.
         return resolveInitialHubProjectPath(this.preferencesStore) || this.projectPath;
     }
+    // Issue #892: resolve the working directory for a run start/resume. Project-scoped
+    // runs require an existing project directory (unchanged — an empty path still throws
+    // "Project path is required."). Project-independent runs (manager/company) fall back
+    // to the user-level FRAIM home when no project has been selected, so Company/Manager
+    // onboarding can run before any project exists. defaultProjectPath() is left untouched.
+    resolveRunProjectPath(bodyProjectPath, scope) {
+        const requested = (bodyProjectPath || this.defaultProjectPath() || '').trim();
+        if (!requested && scope !== 'project') {
+            return projectIndependentWorkingDir();
+        }
+        return ensureDirectoryPath(requested);
+    }
     async start(port) {
         this.httpPort = port;
         await new Promise((resolve, reject) => {
@@ -2177,7 +2236,8 @@ class AiHubServer {
         return { ok: true, continuityDecision: 'same_continuity' };
     }
     resolveImplicitResumeConversation(options) {
-        const candidates = this.conversationStore.loadProject(options.projectPath).conversations.filter((conversation) => {
+        const bucketKey = (0, conversation_store_1.conversationScopeKey)(options.scope, options.projectPath);
+        const candidates = this.conversationStore.loadProject(bucketKey).conversations.filter((conversation) => {
             if (conversation.jobId !== options.jobId)
                 return false;
             const existingAgentId = this.configuredAgentIdForConversation(conversation, options.employees);
@@ -2297,6 +2357,64 @@ class AiHubServer {
         this.pendingConversationWrites.delete(run.id);
         this.persistRunConversationNow(run, activeId);
     }
+    startFreshCodexReviewApprovalFallback(runId, managerNote) {
+        const run = this.runRegistry.get(runId);
+        if (!run)
+            return;
+        const conversation = this.conversationStore.loadConversation((0, conversation_store_1.conversationScopeKey)(run.scope, run.projectPath), run.conversationId || run.id);
+        const handoffSummary = conversation
+            ? buildAgentSwitchHandoffSummary(conversation)
+            : null;
+        const freshPayload = handoffSummary
+            ? this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, renderAgentSwitchHandoffPrompt(handoffSummary, managerNote))
+            : this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, managerNote);
+        this.runRegistry.update(run.id, (current) => {
+            current.status = 'running';
+            current.sessionId = undefined;
+            current.recoveryAttempts = 0;
+            current.pauseReason = 'working';
+            current.events.push((0, hosts_1.createHubEvent)('system', 'Codex resume failed because the saved session was missing a required reasoning item; starting a fresh handoff-backed turn from Hub conversation context.'));
+        });
+        const startedFresh = this.runRegistry.get(run.id);
+        if (startedFresh)
+            this.persistRunConversation(startedFresh, startedFresh.conversationId || startedFresh.id);
+        this.runRegistry.create(run, {});
+        const freshLaunch = this.resolveLaunchAgent(run.configuredAgentId, run.hostId);
+        const freshChild = this.hostRuntime.startRun(run.hostId, run.projectPath, freshPayload.message, {
+            onEvent: (event, channel) => {
+                this.runRegistry.update(run.id, (current) => {
+                    if (event.sessionId) {
+                        current.sessionId = event.sessionId;
+                        current.resumeCommand = (0, hosts_1.buildInteractiveResumeCommand)(run.hostId, event.sessionId);
+                    }
+                    appendHostMessage(current, run.hostId, event, channel);
+                    if (event.raw) {
+                        current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                        applyReviewProjection(current, event.raw);
+                    }
+                    if (event.agentIdentity)
+                        applyAgentIdentitySignal(current, event.agentIdentity);
+                    if (event.fraimJob)
+                        this.applyFraimJobSignalToRun(current, event.fraimJob);
+                    if (event.seekMentoring)
+                        this.applySeekMentoringSignalToRun(current, event.seekMentoring);
+                    if (event.usage)
+                        applyUsageSignal(current, event.usage);
+                });
+                const updated = this.runRegistry.get(run.id);
+                if (updated) {
+                    this.maybeStartDelegatedChildRuns(updated);
+                    this.scheduleRunConversationPersistence(updated, updated.conversationId || updated.id);
+                }
+            },
+            onExit: (exitCode) => {
+                this.handleRunExit(run.id, exitCode, (updated) => {
+                    this.maybeStartDelegatedChildRuns(updated);
+                });
+            },
+        }, startSessionSeedForHost(run.hostId, run.id), freshLaunch.launchContext);
+        this.runRegistry.attachChildIfRunning(run.id, freshChild);
+    }
     scheduleRunConversationPersistence(run, activeId) {
         this.pendingConversationWrites.set(run.id, { run, activeId });
         if (this.conversationFlushTimer)
@@ -4363,15 +4481,10 @@ class AiHubServer {
         });
         this.app.post('/api/ai-hub/runs', (req, res) => {
             try {
-                const rawJobId = req.body.jobId;
-                const resolvedRaw = req.body.projectPath || this.defaultProjectPath();
-                // Machine-level jobs (#892) operate on ~/.fraim/ and must be launchable
-                // even when no project has been selected yet. Fall back to the home dir
-                // so ensureDirectoryPath always receives a valid, existing path.
-                const projectPathRaw = (!resolvedRaw && typeof rawJobId === 'string' && MACHINE_LEVEL_JOB_IDS.has(rawJobId))
-                    ? os_1.default.homedir()
-                    : resolvedRaw;
-                const projectPath = ensureDirectoryPath(projectPathRaw);
+                // Issue #892: project-independent (manager/company) runs resolve a working dir
+                // even with no project; project runs still require an existing project directory.
+                const scope = readRunScope(req.body.scope);
+                const projectPath = this.resolveRunProjectPath(req.body.projectPath, scope);
                 const requestedHostId = req.body.hostId;
                 const instructions = (req.body.instructions || '').trim();
                 const legacyMessage = (req.body.message || '').trim();
@@ -4435,6 +4548,10 @@ class AiHubServer {
                     totals: emptyTotals(),
                     lastStatusChangeAt: startTimestamp,
                     personaKey: jobMetadata?.personaKey ?? getHubPersonaForJob(jobId),
+                    // Issue #892: persist the invocation scope so the run is routed to the right
+                    // conversation bucket (manager/company get a project-independent home) and so
+                    // the resolved fallback working dir is never mistaken for the active project.
+                    scope,
                     // Issue #442: mark this as the FRAIM side of an A/B pair when applicable.
                     ...(compareMode === 'ab' ? { runRole: 'fraim' } : {}),
                     // #0: trigger source — defaults to 'manager' when not provided by the caller.
@@ -4548,10 +4665,14 @@ class AiHubServer {
                     }, startSessionSeedForHost(hostId, directRun.id), launchContext);
                     this.runRegistry.attachChildIfRunning(directRun.id, directChild);
                 }
-                const existingPreferences = this.preferencesStore.load(projectPath);
+                // Issue #892/#866: a project-independent run must NOT stamp its fallback working
+                // dir (~/.fraim) as the Hub's active project. Keep the recorded active project
+                // untouched for manager/company runs; still record recent-job history.
+                const isProjectIndependentRun = scope !== 'project';
+                const existingPreferences = this.preferencesStore.load(isProjectIndependentRun ? '' : projectPath);
                 this.preferencesStore.remember({
                     ...existingPreferences,
-                    projectPath,
+                    projectPath: isProjectIndependentRun ? existingPreferences.projectPath : projectPath,
                     employeeId: hostId,
                     recentJobIds: existingPreferences.recentJobIds,
                 }, jobId, typeof instructions === 'string' ? instructions : undefined);
@@ -4658,6 +4779,7 @@ class AiHubServer {
                 }
                 // No resumable session — start fresh using a handoff prompt so the agent
                 // picks up from the preserved conversation state + manager coaching.
+                const reviewApprovalSystemEventText = buildReviewApprovalSystemEventText(prepared.display || message);
                 if (!run.sessionId) {
                     if (run.humanCoachingDisabled) {
                         return res.status(403).json({ error: 'Human coaching is disabled for this delegated workstream. Coach the parent manager run instead.' });
@@ -4669,14 +4791,13 @@ class AiHubServer {
                     const freshPayload = handoffSummary
                         ? this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, renderAgentSwitchHandoffPrompt(handoffSummary, prepared.display || message))
                         : this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, prepared.display || message);
-                    const reviewApprovalSystemEventTextFresh = buildReviewApprovalSystemEventText(prepared.display || message);
                     this.runRegistry.update(run.id, (current) => {
                         current.status = 'running';
                         current.sessionId = undefined;
                         current.messages.push((0, hosts_1.createHubMessage)('manager', prepared.display || message));
-                        if (reviewApprovalSystemEventTextFresh)
-                            current.events.push((0, hosts_1.createHubEvent)('system', reviewApprovalSystemEventTextFresh));
-                        current.events.push((0, hosts_1.createHubEvent)('system', 'No resumable session — starting a fresh agent turn from conversation context.'));
+                        if (reviewApprovalSystemEventText)
+                            current.events.push((0, hosts_1.createHubEvent)('system', reviewApprovalSystemEventText));
+                        current.events.push((0, hosts_1.createHubEvent)('system', 'No resumable session - starting a fresh agent turn from conversation context.'));
                     });
                     const startedFresh = this.runRegistry.get(run.id);
                     if (startedFresh)
@@ -4720,7 +4841,6 @@ class AiHubServer {
                     const refreshedFresh = this.runRegistry.get(run.id);
                     return res.json(refreshedFresh ? this.enrichRunForResponse(refreshedFresh) : refreshedFresh);
                 }
-                const reviewApprovalSystemEventText = buildReviewApprovalSystemEventText(prepared.display || message);
                 this.runRegistry.update(run.id, (current) => {
                     current.status = 'running';
                     // #521: bubble shows the manager's words; the agent gets the full message.
@@ -4761,6 +4881,11 @@ class AiHubServer {
                         }
                     },
                     onExit: (exitCode) => {
+                        const exited = this.runRegistry.get(run.id);
+                        if (exitCode !== 0 && run.hostId === 'codex' && reviewApprovalSystemEventText && exited && isCodexMissingReasoningResumeError(exited)) {
+                            this.startFreshCodexReviewApprovalFallback(run.id, prepared.display || message);
+                            return;
+                        }
                         this.handleRunExit(run.id, exitCode, (updated) => {
                             this.maybeStartDelegatedChildRuns(updated);
                         });
@@ -4781,7 +4906,10 @@ class AiHubServer {
         this.app.post('/api/ai-hub/runs/resume', (req, res) => {
             try {
                 const body = (req.body ?? {});
-                const projectPath = ensureDirectoryPath(body.projectPath || this.defaultProjectPath());
+                // Issue #892: a mid-flight project-independent onboarding (manager/company) must
+                // resume even with no project (e.g. after a Hub restart).
+                const scope = readRunScope(body.scope);
+                const projectPath = this.resolveRunProjectPath(body.projectPath, scope);
                 const requestedHostId = body.hostId;
                 const sessionId = (body.sessionId || '').trim();
                 const jobId = (body.jobId || '').trim();
@@ -4798,12 +4926,13 @@ class AiHubServer {
                 const requestedConversationId = typeof body.conversationId === 'string' && body.conversationId.trim()
                     ? body.conversationId.trim()
                     : undefined;
+                const conversationBucketKey = (0, conversation_store_1.conversationScopeKey)(scope, projectPath);
                 const inferredConversation = requestedConversationId
                     ? null
-                    : this.resolveImplicitResumeConversation({ projectPath, jobId, requestedAgent: configuredAgent, employees });
+                    : this.resolveImplicitResumeConversation({ projectPath, scope, jobId, requestedAgent: configuredAgent, employees });
                 const conversationId = requestedConversationId || inferredConversation?.id;
                 const persistedConversation = requestedConversationId
-                    ? this.conversationStore.loadProject(projectPath).conversations.find((entry) => entry.id === requestedConversationId)
+                    ? this.conversationStore.loadProject(conversationBucketKey).conversations.find((entry) => entry.id === requestedConversationId)
                     : inferredConversation ?? undefined;
                 const persistedRun = readPersistedRunProjection(persistedConversation);
                 const now = new Date().toISOString();
@@ -4813,6 +4942,9 @@ class AiHubServer {
                     conversationTitle: typeof body.conversationTitle === 'string' && body.conversationTitle.trim() ? body.conversationTitle.trim() : undefined,
                     jobTitle: typeof body.jobTitle === 'string' && body.jobTitle.trim() ? body.jobTitle.trim() : jobId,
                     jobId, hostId, configuredAgentId: configuredAgent.id, configuredAgentLabel: configuredAgent.label, baseHostId: configuredAgent.baseHostId, projectPath, status: 'running', sessionId,
+                    // Issue #892: keep the invocation scope so a resumed manager/company run stays
+                    // in its project-independent conversation bucket.
+                    scope,
                     createdAt: now, updatedAt: now, messages: [],
                     events: [(0, hosts_1.createHubEvent)('system', `Resuming ${configuredAgent.label} (${hostId}) session ${sessionId} in ${projectPath}`)],
                     // Only carry phase state forward when the prior run was interrupted mid-job
@@ -5679,7 +5811,7 @@ class AiHubServer {
                 current.recoveryAttempts = (current.recoveryAttempts ?? 0) + 1;
                 current.lastRecoveryAt = new Date().toISOString();
                 current.pauseReason = 'working';
-                current.events.push((0, hosts_1.createHubEvent)('system', `Run exited (code ${exitCode ?? 'unknown'}); auto-resuming (attempt ${current.recoveryAttempts}/${MAX_RECOVERY_ATTEMPTS}).`));
+                current.events.push(createHubRecoveryEvent(current, exitCode, current.recoveryAttempts));
             });
             const refreshed = this.runRegistry.get(runId);
             if (!refreshed?.sessionId) {
@@ -5700,7 +5832,7 @@ class AiHubServer {
                 const current = this.runRegistry.get(runId);
                 if (!current || current.status !== 'running')
                     return;
-                const message = 'Continue where you left off.';
+                const message = buildHubRecoveryContinueMessage(current, exitCode, attempt);
                 const child = this.hostRuntime.continueRun(current.hostId, current.projectPath, current.sessionId, message, {
                     onEvent: (event, channel) => {
                         this.runRegistry.update(runId, (r) => {

package/dist/src/cli/setup/ide-invocation-surfaces.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CODEX_SKILL_FRONTMATTER = exports.FRAIM_INVOCATION_BODY = exports.FRAIM_DEFERRED_TOOL_PRELOAD = exports.CURSOR_MDC_FRONTMATTER = exports.FRAIM_LAUNCH_PHRASE = void 0;
+exports.CODEX_SKILL_FRONTMATTER = exports.FRAIM_INVOCATION_BODY = exports.FRAIM_MCP_UNAVAILABLE_MANAGER_GUIDANCE = exports.FRAIM_DEFERRED_TOOL_PRELOAD = exports.CURSOR_MDC_FRONTMATTER = exports.FRAIM_LAUNCH_PHRASE = void 0;
 exports.buildFraimInvocationBody = buildFraimInvocationBody;
 exports.buildClaudeSkillContent = buildClaudeSkillContent;
 exports.buildClaudeCommandShimContent = buildClaudeCommandShimContent;
@@ -25,6 +25,12 @@ exports.FRAIM_DEFERRED_TOOL_PRELOAD = [
     'get_fraim_file',
     'seekMentoring'
 ];
+exports.FRAIM_MCP_UNAVAILABLE_MANAGER_GUIDANCE = [
+    'If required FRAIM MCP tools remain unavailable after the deferred-tool preload/retry step, stop the FRAIM job.',
+    'Do not continue from memory, local stubs, cached instructions, or prior context.',
+    'In the blocker sentence, state only the work-focused blocker and what outcome is blocked; do not narrate ToolSearch/tool_search, individual tool names, server internals, or retry mechanics.',
+    'Always help troubleshoot the unavailable FRAIM MCP connection: tell the user to reconnect or enable the FRAIM MCP server in their IDE/agent, restart or refresh the agent session, retry the FRAIM job, and if it still fails run `fraim doctor --test-mcp` and share the failing check output.'
+].join(' ');
 function buildDeferredToolBootstrapSection(profile) {
     if (profile === 'none') {
         return '';
@@ -72,6 +78,7 @@ ${buildDeferredToolBootstrapSection(profile)}1. **Confirm FRAIM activation**:
 5. **Execute**:
    - For jobs, follow the phased instructions and use \`seekMentoring\` when the job requires phase transitions.
    - For skills, apply the skill steps directly to the user's current context.
+   - ${exports.FRAIM_MCP_UNAVAILABLE_MANAGER_GUIDANCE}
 `;
 }
 exports.FRAIM_INVOCATION_BODY = buildFraimInvocationBody();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.241",
+  "version": "2.0.243",
   "description": "FRAIM Hub local companion package.",
   "bin": {
     "fraim-hub": "bin/fraim-hub.js",
@@ -161,7 +161,7 @@
     "electron": "^41.2.2",
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
-    "fraim": "2.0.241",
+    "fraim": "2.0.243",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",

package/public/ai-hub/script.js

@@ -4249,11 +4249,14 @@ function syncSendButton() {
   // coach mid-run (which is exactly what /api/ai-hub/runs/:id/messages
   // is for; the server only requires sessionId).
   const resumable = !!(conv && conv.sessionId);
+  // A stopped/failed run with no session (agent crashed, Hub restarted) can
+  // also accept coaching — the server will fire a fresh startRun from context.
+  const canRestartWithCoaching = !!(conv && !conv.sessionId && conv.status !== 'running' && !isManagedDelegationChild(conv));
   // A pending coaching job (set by quick-coach buttons or template picker)
   // is enough to enable Send even with an empty textarea — the user just
   // wants to fire that coaching directive, optionally with added context.
   const hasPendingJob = !!state.pendingCoachingJobId;
-  els['send'].disabled = !((hasText || hasPendingJob) && resumable);
+  els['send'].disabled = !((hasText || hasPendingJob) && (resumable || canRestartWithCoaching));
 }
 
 function defaultCoachNote(conv) {
@@ -4272,6 +4275,9 @@ function defaultCoachNote(conv) {
   if (conv && conv.status === 'running') {
     return 'The employee is still working. Add coaching here to tighten the next step without losing context.';
   }
+  if (conv && !conv.sessionId && conv.status !== 'running') {
+    return 'The session is gone (agent crashed or Hub restarted). Send coaching to restart a fresh session from the preserved conversation context.';
+  }
   return 'The employee is waiting on you. Send the next instruction to continue this run.';
 }
 
@@ -6783,6 +6789,9 @@ async function startRun(job, instructions, employeeId, preassignedConvId, invoke
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
         projectPath: state.projectPath,
+        // Issue #892: send the run scope so project-independent runs (Company/Manager
+        // onboarding) can start with no project selected.
+        scope: conv.scope,
         hostId: baseHostIdForAgent(employeeId),
         configuredAgentId: employeeId,
         jobId: job.id,
@@ -6903,6 +6912,9 @@ async function continueRun(text, options) {
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({
             projectPath: state.projectPath,
+            // Issue #892: carry the scope so a project-independent onboarding resumes
+            // with no project (e.g. after a Hub restart).
+            scope: convScope(conv),
             hostId: baseHostIdForAgent(conversationAgentName(conv) || state.selectedEmployeeId || 'claude'),
             configuredAgentId: conversationAgentName(conv) || state.selectedEmployeeId || 'claude',
             jobId: conv.jobId,