fraim-hub 2.0.286 → 2.0.288

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

@@ -82,6 +82,22 @@ function parseSeekMentoringSignal(line) {
                 return sig;
         }
     }
+    // Copilot CLI shape (issue #1399): { type: 'tool.execution_start', data: {
+    // mcpServerName, mcpToolName, arguments } }. Live-verified via a direct
+    // spike against the installed CLI under --output-format json (see
+    // docs/rfcs/1399-copilot-host-chattiness-technical-design.md) — Copilot
+    // reports the MCP server and tool name as separate, unambiguous fields
+    // rather than a qualifier string, so this reads data.mcpToolName directly
+    // instead of going through canonicalToolName's __/./: splitting.
+    if (obj.type === 'tool.execution_start' && typeof obj.data === 'object' && obj.data !== null) {
+        const data = obj.data;
+        if (isFraimTool(data.mcpToolName, 'seekMentoring')) {
+            const args = normalizeToolArgs(data.arguments) || undefined;
+            const sig = extractSignalFromArgs(args);
+            if (sig)
+                return sig;
+        }
+    }
     // Claude Code shape: tool_use blocks live inside parsed.message.content.
     // The name is MCP-prefixed (e.g. 'mcp__fraim__seekMentoring').
     const candidates = [obj];
@@ -133,6 +149,16 @@ function parseFraimJobLoadSignal(line) {
                 return sig;
         }
     }
+    // Copilot CLI shape (issue #1399): see parseSeekMentoringSignal's Copilot
+    // block above for the field-shape rationale.
+    if (obj.type === 'tool.execution_start' && typeof obj.data === 'object' && obj.data !== null) {
+        const data = obj.data;
+        if (isFraimTool(data.mcpToolName, 'get_fraim_job')) {
+            const sig = readFraimJobFromArgs(data.arguments);
+            if (sig)
+                return sig;
+        }
+    }
     // Claude Code shape: tool_use blocks live inside message.content with
     // an MCP-prefixed name such as mcp__fraim__get_fraim_job.
     const candidates = [obj];
@@ -289,6 +315,14 @@ function parseAgentIdentitySignal(line) {
             return readAgentFromArgs(normalizeToolArgs(item.arguments) || undefined);
         }
     }
+    // Copilot CLI shape (issue #1399): see parseSeekMentoringSignal's Copilot
+    // block for the field-shape rationale.
+    if (obj.type === 'tool.execution_start' && typeof obj.data === 'object' && obj.data !== null) {
+        const data = obj.data;
+        if (isFraimTool(data.mcpToolName, 'fraim_connect')) {
+            return readAgentFromArgs(normalizeToolArgs(data.arguments) || undefined);
+        }
+    }
     // Claude Code shape.
     const candidates = [obj];
     if (typeof obj.message === 'object' && obj.message !== null) {
@@ -1434,7 +1468,12 @@ function buildStartPlan(hostId, message, sessionId) {
         const browser = sharedBrowserHostConfig('copilot');
         return {
             command: COPILOT_BINARY,
-            args: ['--yolo', ...browser.args],
+            // Issue #1399: request Copilot's structured JSONL output mode
+            // (one JSON object per line) instead of its default human-
+            // readable terminal rendering, so parseHostLine can classify
+            // tool calls/results/deltas separately from genuine reply text
+            // instead of pattern-matching rendered chrome characters.
+            args: ['--yolo', '--output-format', 'json', ...browser.args],
             stdin: transformHeadlessFraimMessage(message, 'start'),
             env: browser.env,
         };
@@ -1495,7 +1534,8 @@ function buildContinuePlan(hostId, sessionId, message) {
         const browser = sharedBrowserHostConfig('copilot');
         return {
             command: COPILOT_BINARY,
-            args: ['--yolo', '--resume', sessionId, ...browser.args],
+            // Issue #1399: see buildStartPlan's copilot branch for rationale.
+            args: ['--yolo', '--output-format', 'json', '--resume', sessionId, ...browser.args],
             stdin: transformHeadlessFraimMessage(message, 'continue'),
             env: browser.env,
         };
@@ -1562,9 +1602,10 @@ function buildDirectStartPlan(hostId, message, sessionId) {
     }
     if (hostId === 'copilot') {
         // Direct (A/B) mode for Copilot: headless, no FRAIM MCP wiring.
+        // Issue #1399: --output-format json for the same reason as buildStartPlan.
         return {
             command: COPILOT_BINARY,
-            args: ['--yolo'],
+            args: ['--yolo', '--output-format', 'json'],
             stdin: DIRECT_PREAMBLE + message,
         };
     }
@@ -1608,9 +1649,10 @@ function buildDirectContinuePlan(hostId, sessionId, message) {
     }
     if (hostId === 'copilot') {
         // Direct continue mode for Copilot: resume session, no FRAIM MCP wiring.
+        // Issue #1399: --output-format json for the same reason as buildStartPlan.
         return {
             command: COPILOT_BINARY,
-            args: ['--yolo', '--resume', sessionId],
+            args: ['--yolo', '--output-format', 'json', '--resume', sessionId],
             stdin: DIRECT_PREAMBLE + message,
         };
     }
@@ -1723,31 +1765,69 @@ function parseHostLine(hostId, line) {
     if (hostId === 'antigravity') {
         return withSignal({ raw: trimmed });
     }
-    // GitHub Copilot CLI output: JSON stream where each event carries a `type`
-    // field. Known event shapes (from the agentic CLI stream):
-    //   { "type": "session.started", "session_id": "..." }  — session id
-    //   { "type": "message", "role": "assistant", "content": "..." }  — reply text
-    //   { "type": "turn.completed", "usage": { ... } }  — token usage (same shape as Codex)
-    // For any JSON event not matching the above, signal scanning (seekMentoring,
-    // agent identity) still runs because withSignal is applied to every parsed result.
-    // Non-JSON lines from Copilot are treated as plain-text employee messages.
+    // GitHub Copilot CLI output (issue #1399): Hub invokes Copilot with
+    // --output-format json (see buildStartPlan's copilot branch), which
+    // reports every event as one JSON object per line. Two shapes from the
+    // original #531 integration are kept as defensive fallbacks — never
+    // confirmed against real traffic, but harmless to keep recognizing if a
+    // future CLI version or mode emits them:
+    //   { "type": "session.started", "session_id": "..." }
+    //   { "type": "message", "role": "assistant", "content": "..." }
+    // The real vocabulary below was captured via a live spike against the
+    // installed CLI binary (see "Spike Findings" in
+    // docs/rfcs/1399-copilot-host-chattiness-technical-design.md):
+    //   { "type": "assistant.message", "data": { "content": "...", "toolRequests": [...] } }
+    //     — the genuine reply. data.content is the message text; toolRequests
+    //     is metadata about an about-to-run tool call, not display text.
+    //   { "type": "result", "sessionId": "...", "exitCode": 0, "usage": {...} }
+    //     — terminal turn/session summary. This is the only place sessionId
+    //     was observed in a single-shot run (no early session-id event fired).
+    //   { "type": "tool.execution_start" | "tool.execution_complete", "data": {...} },
+    //   { "type": "model.tool_execution", "data": {...} }
+    //     — tool invocation and result. Diagnostic only, never a message.
+    //     seekMentoring/get_fraim_job/fraim_connect signal extraction (via
+    //     withSignal below) reads the call arguments off tool.execution_start's
+    //     data.arguments/data.mcpServerName/data.mcpToolName.
+    //   { "type": "assistant.message_delta" | "assistant.tool_call_delta", ...,
+    //     "ephemeral": true }
+    //     — streaming deltas. The CLI's own schema marks these ephemeral, an
+    //     explicit signal (not a heuristic) that they are safe to drop.
+    //   session.*/model.*/user.message/assistant.turn_*/assistant.idle
+    //     — setup, bookkeeping, and input-echo diagnostics.
+    // Any other/unrecognized type, and any line that fails JSON.parse entirely,
+    // fails CLOSED (raw only) — matching Codex's and Claude's existing
+    // fail-closed default. This replaces the prior fail-OPEN catch-all that
+    // promoted arbitrary unrecognized Copilot text (in practice, ~80% of a
+    // real run's lines — the CLI's own tool-call/result terminal rendering) to
+    // a manager-visible message.
     if (hostId === 'copilot') {
+        let parsed;
         try {
-            const parsed = JSON.parse(trimmed);
-            if (parsed.type === 'session.started' && typeof parsed.session_id === 'string' && parsed.session_id.length > 0) {
-                return withSignal({ sessionId: parsed.session_id, raw: trimmed });
-            }
-            if (parsed.type === 'message' && parsed.role === 'assistant' && typeof parsed.content === 'string') {
-                return withSignal({ message: parsed.content, raw: trimmed });
-            }
-            // All other JSON events: apply signal scanning and surface as raw.
-            return withSignal({ raw: trimmed });
+            parsed = JSON.parse(trimmed);
         }
         catch {
-            // Non-JSON line from Copilot: treat as a plain-text employee message,
-            // same pattern as Gemini CLI's non-JSON output.
-            return withSignal({ message: trimmed, raw: trimmed });
+            return withSignal({ raw: trimmed });
+        }
+        if (!parsed || typeof parsed !== 'object')
+            return withSignal({ raw: trimmed });
+        if (parsed.type === 'session.started' && typeof parsed.session_id === 'string' && parsed.session_id.length > 0) {
+            return withSignal({ sessionId: parsed.session_id, raw: trimmed });
+        }
+        if (parsed.type === 'message' && parsed.role === 'assistant' && typeof parsed.content === 'string') {
+            return withSignal({ message: parsed.content, raw: trimmed });
+        }
+        if (parsed.type === 'assistant.message') {
+            const content = typeof parsed.data?.content === 'string' ? parsed.data.content : undefined;
+            return content ? withSignal({ message: content, raw: trimmed }) : withSignal({ raw: trimmed });
         }
+        if (parsed.type === 'result') {
+            const sessionId = typeof parsed.sessionId === 'string' && parsed.sessionId.length > 0 ? parsed.sessionId : undefined;
+            return withSignal({ sessionId, raw: trimmed });
+        }
+        // tool.execution_start/complete, model.tool_execution, the *_delta
+        // events, and session/model/user/turn bookkeeping all fall here:
+        // diagnostic-only, but still signal-scanned by withSignal above.
+        return withSignal({ raw: trimmed });
     }
     try {
         const parsed = JSON.parse(trimmed);

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

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findAvailablePortExcluding = exports.findAvailablePort = exports.AiHubServer = exports.HubConnectorStatusStore = exports.HostConfigStore = exports.DeploymentStore = void 0;
+exports.selfHealBrokenManagedAgents = selfHealBrokenManagedAgents;
 exports.configureFraimForHubAgent = configureFraimForHubAgent;
 exports.hubCommandVersion = hubCommandVersion;
 exports.buildOpenFileInvocation = buildOpenFileInvocation;
@@ -1699,6 +1700,35 @@ function hubAgentOption(hubId) {
     const frId = HUB_TO_FIRST_RUN_ID[hubId];
     return frId ? types_1.FIRST_RUN_AGENT_OPTIONS.find((o) => o.id === frId) : undefined;
 }
+const defaultSelfHealDeps = {
+    checkHealth: agent_cli_health_checks_1.checkAgentCliHealthByCommand,
+    install: (option, systemPath) => (0, managed_agent_install_1.installManagedAgent)(option, systemPath, { runProcess: hubRunProcess, commandVersion: hubCommandVersion }),
+    invalidateCache: hosts_1.invalidateEmployeeDetectionCache,
+};
+async function selfHealBrokenManagedAgents(deps = defaultSelfHealDeps) {
+    for (const hubId of ['claude', 'codex']) {
+        try {
+            const health = await deps.checkHealth(hubId);
+            if (!health || health.status !== 'error')
+                continue;
+            const details = health.details;
+            if (!details?.managedPath || details.managedVersion)
+                continue;
+            const option = hubAgentOption(hubId);
+            if (!option || !option.installPackage)
+                continue;
+            console.warn(`[ai-hub] self-heal: ${option.label}'s FRAIM-managed install is broken (${health.message}) — attempting automatic reinstall`);
+            const systemPath = (0, managed_agent_paths_1.stripManagedAgentBinDirsFromPath)(process.env.PATH);
+            await deps.install({ label: option.label, installPackage: option.installPackage, launchCommand: option.launchCommand }, systemPath);
+            deps.invalidateCache();
+            const verified = await deps.checkHealth(hubId);
+            console.warn(`[ai-hub] self-heal: ${option.label} reinstall ${verified?.status === 'error' ? 'did NOT fix it — manual reinstall needed' : 'succeeded'}`);
+        }
+        catch (error) {
+            console.warn(`[ai-hub] self-heal check failed for ${hubId}:`, error instanceof Error ? error.message : String(error));
+        }
+    }
+}
 /**
  * Issue #747: after the Hub installs an agent CLI, run the `add-ide` command for that agent so the
  * FRAIM MCP (plus slash commands / rules) is wired into its config and its first run works.
@@ -1916,6 +1946,24 @@ function buildManagedLoginCommand(command) {
 function getUserHubDir() {
     return path_1.default.join(os_1.default.homedir(), '.fraim');
 }
+// Issue #1345: recursively find first file matching name under dir.
+function findFileRecursive(dir, filename) {
+    try {
+        for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+            const full = path_1.default.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                const hit = findFileRecursive(full, filename);
+                if (hit)
+                    return hit;
+            }
+            else if (entry.isFile() && entry.name === filename) {
+                return full;
+            }
+        }
+    }
+    catch { /* ignore unreadable dirs */ }
+    return null;
+}
 function ensureDirectoryPath(projectPath) {
     const trimmed = (projectPath || '').trim();
     if (!trimmed) {
@@ -2681,6 +2729,17 @@ class AiHubServer {
         void (0, hosts_1.detectEmployeesAsync)({ force: true }).catch((error) => {
             console.warn('[ai-hub] agent availability priming failed:', error?.message || error);
         });
+        // Issue #1412: fire-and-forget self-heal of any broken FRAIM-managed CLI
+        // install (e.g. an interrupted Claude Code/Codex update left a
+        // non-executable launcher). Never blocks or fails startup. Skipped in
+        // NODE_ENV=test so the test suite's many short-lived Hub instances never
+        // trigger a real `npm install -g`, matching this file's existing
+        // NODE_ENV-gated test-safety pattern (see hubCommandVersion/hubRunProcess).
+        if (process.env.NODE_ENV !== 'test') {
+            void selfHealBrokenManagedAgents().catch((error) => {
+                console.warn('[ai-hub] self-heal pass failed:', error?.message || error);
+            });
+        }
         // Issue #578: rehydrate active scheduled deployments from disk. Test and preview
         // servers that inject a fake host but not a deployment store should not run the
         // user's real scheduled deployments from the default store.
@@ -3242,6 +3301,7 @@ class AiHubServer {
             // so completed conversations render "What's next?" chips after reload.
             nextJobRecommendations: run.nextJobRecommendations || null,
             issueNumber: run.issueNumber ?? null,
+            executionMode: run.executionMode || null,
             managedByRunId: run.managedByRunId || null,
             managedByPersonaKey: run.managedByPersonaKey || null,
             humanCoachingDisabled: run.humanCoachingDisabled || false,
@@ -5686,6 +5746,25 @@ class AiHubServer {
                 return res.status(404).json({ error: 'Configured agent not found.' });
             return res.json((0, configured_agents_1.checkConfiguredAgentReadiness)(agent, employees));
         });
+        // Issue #1345: accept executionMode forwarded from get_fraim_job response by the local proxy.
+        // The proxy parses the Execution Mode Context block and POSTs here; Hub script reads from run poll.
+        this.app.post('/api/ai-hub/runs/by-session/:sessionId/execution-mode', (req, res) => {
+            if (!this.requireTrustedHubOrigin(req, res))
+                return;
+            const { sessionId } = req.params;
+            const { mode, completedRuns } = req.body;
+            if (!sessionId)
+                return res.status(400).json({ error: 'sessionId required' });
+            const normalizedMode = mode === 'trusted' ? 'trusted' : 'coached';
+            const normalizedRuns = typeof completedRuns === 'number' ? completedRuns : 0;
+            const run = this.runRegistry.all().find((r) => r.sessionId === sessionId);
+            if (!run)
+                return res.status(404).json({ error: 'Run not found for session.' });
+            this.runRegistry.update(run.id, (current) => {
+                current.executionMode = { mode: normalizedMode, completedRuns: normalizedRuns };
+            });
+            return res.json({ ok: true });
+        });
         this.app.post('/api/ai-hub/runs', (req, res) => {
             try {
                 // Issue #892: project-independent (manager/company) runs resolve a working dir
@@ -5726,6 +5805,26 @@ class AiHubServer {
                 if (!jobId) {
                     throw new Error('Choose a FRAIM job before starting a run.');
                 }
+                // #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.
+                // Window of 300 ms: UI race duplicates arrive within ~100 ms (React render cycle);
+                // sequential test runs with the same params are separated by 600 ms+ (test body +
+                // beforeEach page.goto), so the window never fires across test boundaries.
+                const MANAGER_DEDUP_WINDOW_MS = 300;
+                if ((req.body.sourceTrigger ?? 'manager') === 'manager') {
+                    const now = Date.now();
+                    const activeRun = this.runRegistry.all().find((r) => r.status === 'running'
+                        && r.projectPath === projectPath
+                        && r.jobId === jobId
+                        && r.hostId === hostId
+                        && r.messages[0]?.text === managerDisplay
+                        && now - Date.parse(r.createdAt) < MANAGER_DEDUP_WINDOW_MS);
+                    if (activeRun) {
+                        console.warn('[ai-hub] hub.duplicate_run_blocked', { projectPath, jobId, hostId, existingRunId: activeRun.id });
+                        return res.json(this.enrichRunForResponse(activeRun));
+                    }
+                }
                 const startTimestamp = new Date().toISOString();
                 const jobMetadata = this.resolveHubJob(projectPath, jobId);
                 const fallbackJobTitle = typeof req.body.jobTitle === 'string' && req.body.jobTitle.trim()
@@ -5765,7 +5864,9 @@ class AiHubServer {
                     phaseVisits: [],
                     totals: emptyTotals(),
                     lastStatusChangeAt: startTimestamp,
-                    personaKey: jobMetadata?.personaKey ?? getHubPersonaForJob(jobId),
+                    // Issue #1357: fall back to custom persona resolution before the catalog lookup
+                    // so custom employee owners (e.g. SidCoder for feature-implementation) are used.
+                    personaKey: jobMetadata?.personaKey ?? getCustomPersonaForJob(projectPath, jobId) ?? 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.
@@ -6023,6 +6124,13 @@ class AiHubServer {
                         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.'));
+                        // Issue #1373 (Defect 2): nextJobRecommendations can only be stale
+                        // here — it is only ever set at retrospective (issue #848), and a
+                        // job that just received coaching has not reached retrospective
+                        // again yet. Clear it at send-time so a coached Done job stops
+                        // offering next-job recommendations immediately, not only once the
+                        // resumed session's next seekMentoring signal arrives.
+                        current.nextJobRecommendations = null;
                     });
                     const startedFresh = this.runRegistry.get(run.id);
                     if (startedFresh)
@@ -6079,6 +6187,9 @@ class AiHubServer {
                     current.messages.push((0, hosts_1.createHubMessage)('manager', prepared.display || message, deliveryStatus));
                     if (reviewApprovalSystemEventText)
                         current.events.push((0, hosts_1.createHubEvent)('system', reviewApprovalSystemEventText));
+                    // Issue #1373 (Defect 2): see the no-session branch above for why
+                    // this can only be stale at coaching-send time.
+                    current.nextJobRecommendations = null;
                 });
                 const started = this.runRegistry.get(run.id);
                 if (started)
@@ -6221,17 +6332,28 @@ class AiHubServer {
                     messages: persistedConversation ? persistedMessagesForRun(persistedConversation) : [],
                     events: resumeEvents,
                     eventLogRefs: persistedConversation?.eventLogRefs || [],
-                    // Only carry phase state forward when the prior run was interrupted mid-job
-                    // (status !== 'completed'). A completed conversation is a finished run;
-                    // resuming the session starts a fresh job, so the tracker must be blank.
-                    currentPhase: persistedConversation?.status !== 'completed' ? (persistedRun?.currentPhase || null) : null,
-                    phaseHistory: persistedConversation?.status !== 'completed' ? (persistedRun?.phaseHistory || []) : [],
-                    phaseVisits: persistedConversation?.status !== 'completed' ? (persistedRun?.phaseVisits || []) : [],
+                    // Issue #1373: a conversation is permanently scoped to one job for its
+                    // lifetime, including after that job's conversation is marked
+                    // 'completed' — a coaching turn sent to a Done job resumes the SAME
+                    // job's phase history, it does not start unrelated new work. Always
+                    // carry the persisted run projection forward regardless of the
+                    // conversation's prior status. If the resumed session genuinely has
+                    // nothing left to do, it simply reaches the same completed state
+                    // again on its own the next time seekMentoring reports its phase.
+                    currentPhase: persistedRun?.currentPhase || null,
+                    phaseHistory: persistedRun?.phaseHistory || [],
+                    phaseVisits: persistedRun?.phaseVisits || [],
                     totals: persistedRun?.totals || emptyTotals(),
                     lastStatusChangeAt: now,
-                    runDiscriminant: persistedConversation?.status !== 'completed' ? (persistedRun?.runDiscriminant || undefined) : undefined,
-                    personaKey: getHubPersonaForJob(jobId),
+                    runDiscriminant: persistedRun?.runDiscriminant || undefined,
+                    // Issue #1357: consult custom persona owner before falling back to catalog.
+                    personaKey: getCustomPersonaForJob(projectPath, jobId) ?? getHubPersonaForJob(jobId),
                     continuityDecision: conversationId ? 'same_continuity' : 'new_conversation',
+                    // Issue #1373 (Defect 2): nextJobRecommendations are only ever set at
+                    // retrospective/completion (issue #848); a resumed run has not reached
+                    // retrospective, so this is always null here. Explicit for readability
+                    // and to make the invariant visible next to the Defect 1 fix above.
+                    nextJobRecommendations: null,
                 };
                 host_session_state_1.hostSessionState.applySession(run, { configuredAgentId: configuredAgent.id, baseHostId: hostId }, sessionId, { sourceRunId: run.id, status: resolvedHostSession?.status || 'suspect' });
                 // Continue-turn message (FRAIM invocation for the job + instructions) plus
@@ -7025,7 +7147,8 @@ class AiHubServer {
                     phaseVisits: [],
                     totals: emptyTotals(),
                     lastStatusChangeAt: startTimestamp,
-                    personaKey: getHubPersonaForJob(jobName),
+                    // Issue #1357: consult custom persona owner before falling back to catalog.
+                    personaKey: getCustomPersonaForJob(projectPath, jobName) ?? getHubPersonaForJob(jobName),
                 };
                 // Register the run before spawning so onEvent/onExit callbacks can
                 // safely call update() even if they fire synchronously (FakeHostRuntime).
@@ -7178,7 +7301,8 @@ class AiHubServer {
             phaseVisits: [],
             totals: emptyTotals(),
             lastStatusChangeAt: startTimestamp,
-            personaKey: jobMetadata?.personaKey ?? getHubPersonaForJob(jobId),
+            // Issue #1357: fall back to custom persona resolution before the catalog lookup.
+            personaKey: jobMetadata?.personaKey ?? getCustomPersonaForJob(deployment.projectPath, jobId) ?? getHubPersonaForJob(jobId),
         };
         // Pre-register before startRun so synchronous onEvent calls (e.g. FakeHostRuntime)
         // can call runRegistry.update without "Run not found" throws.

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

@@ -97,6 +97,27 @@ async function runAgentCliHealthCheck(cli) {
         : managedPath === ambientPath
             ? ambientVersion
             : probeVersion(managedPath);
+    // Issue #1412: a resolved file that fails to execute at all (e.g. an
+    // interrupted update left a non-executable fallback launcher) is a harder
+    // failure than drift — `getSystemCommandPath()` only proves the file
+    // exists, not that it can run. Without this check, a single broken install
+    // with nothing else on PATH to disagree with (ambientPath === managedPath,
+    // both versions null) falls straight through the mismatch check below and
+    // reads as "consistent". Check this before computing npm-global/drift
+    // details that don't matter once the CLI can't run at all.
+    const brokenPath = ambientPath && !ambientVersion
+        ? ambientPath
+        : managedPath && !managedVersion
+            ? managedPath
+            : null;
+    if (brokenPath) {
+        return {
+            status: 'error',
+            message: `${cli.label} is installed at ${brokenPath} but failed to run (\`${cli.command} --version\` produced no output). An interrupted or partial update may have left a non-functional launcher.`,
+            suggestion: `Reinstall ${cli.label}, then run "${cli.command} --version" again to confirm it's fixed.`,
+            details: { ambientPath, ambientVersion, managedPath, managedVersion },
+        };
+    }
     const npmGlobalBinDirs = (0, managed_agent_paths_1.resolveNpmGlobalBinDirs)();
     const npmGlobalPath = npmGlobalBinDirs.length > 0
         ? (0, command_resolution_1.getSystemCommandPath)(cli.command, npmGlobalBinDirs.join(path_1.default.delimiter))

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

@@ -29,7 +29,10 @@ 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.'
+    '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.',
+    'Exception — troubleshooting FRAIM itself: if the user\'s request is to diagnose or fix a FRAIM issue and FRAIM MCP is unavailable, do NOT stop.',
+    'Instead, read `~/.fraim/docs/TROUBLESHOOTING.md` directly from disk (it is always synced in full by `fraim sync` and is available without MCP) and follow its guidance to diagnose the issue.',
+    'After completing the local diagnosis, prompt the user to re-run `fraim sync` and restart their agent session, then offer to run the `troubleshoot-fraim` FRAIM job for a structured investigation once MCP is restored.'
 ].join(' ');
 function buildDeferredToolBootstrapSection(profile) {
     if (profile === 'none') {

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

@@ -291,10 +291,20 @@ for (const bundle of Object.values(exports.PERSONA_CAPABILITY_BUNDLES)) {
 // named specialist persona. They resolve through ownership (never short-circuited
 // as "free") so the Hub attributes them to FRAIMworker, but they are never
 // hire-gated because FRAIMworker is not a purchasable persona.
+//
+// Issue #1398: manager-agreements / organization-onboarding / organizational-learning-
+// synthesis are Manager/Company area-level jobs, not tied to a named specialist — they
+// were falling through to DEFAULT_UNASSIGNED_PERSONA_KEY ('mandy'), which misattributed
+// them to an employee who never runs them and left them outside the Manager/Company
+// employee rail's FRAIMworker group.
 const GENERIC_WORKER_OWNED_JOBS = new Set([
     'contribute-to-fraim',
     'file-fraim-issue',
     'praise-fraim',
+    'troubleshoot-fraim',
+    'manager-agreements',
+    'organization-onboarding',
+    'organizational-learning-synthesis',
 ]);
 function getPersonaCapabilityBundle(personaKey) {
     return exports.PERSONA_CAPABILITY_BUNDLES[personaKey];

package/dist/src/fraim/db-service.js

@@ -170,6 +170,8 @@ class FraimDbService {
         // Issue #563 — shared organization context (FRAIM-cloud backend).
         this.orgArtifactsCollection = this.db.collection('fraim_org_artifacts');
         this.orgAuditCollection = this.db.collection('fraim_org_audit');
+        // Issue #1345 — job execution modes (Coached/Trusted).
+        this.jobExecutionModesCollection = this.db.collection('fraim_job_execution_modes');
     }
     async initializeIndexes() {
         if (!this.db)
@@ -199,6 +201,7 @@ class FraimDbService {
         // requirement — swallow failures like the other Cosmos-sensitive indexes above.
         await this.orgArtifactsCollection.createIndex({ orgId: 1, relativePath: 1 }, { unique: true }).catch(() => { });
         await this.orgAuditCollection.createIndex({ orgId: 1, at: -1 }).catch(() => { });
+        await this.jobExecutionModesCollection.createIndex({ userId: 1, jobName: 1 }, { unique: true }).catch(() => { });
         await this.pendingVerificationsCollection.createIndex({ email: 1 });
         // Compound index covers `findOne({email}, { sort: { createdAt: -1 } })` —
         // the request-access flow's lookup of the most-recent pending row per
@@ -286,6 +289,36 @@ class FraimDbService {
             throw new Error('DB not connected');
         return await this.orgAuditCollection.find({ orgId }).sort({ at: -1 }).toArray();
     }
+    async getJobExecutionMode(userId, jobName) {
+        if (!this.jobExecutionModesCollection)
+            return null;
+        return await this.jobExecutionModesCollection.findOne({ userId, jobName }) ?? null;
+    }
+    async upsertJobExecutionMode(userId, update) {
+        if (!this.jobExecutionModesCollection)
+            return;
+        const jobName = String(update['jobName'] ?? '');
+        if (!jobName)
+            return;
+        const existing = await this.jobExecutionModesCollection.findOne({ userId, jobName });
+        let completedRuns = typeof existing?.completedRuns === 'number' ? existing.completedRuns : 0;
+        if (update['incrementRun'] === true)
+            completedRuns += 1;
+        const record = {
+            userId,
+            jobName,
+            mode: (update['mode'] === 'trusted' || update['mode'] === 'coached')
+                ? update['mode']
+                : (existing?.mode ?? 'coached'),
+            completedRuns,
+            trustedSince: typeof update['trustedSince'] === 'string' ? update['trustedSince'] : existing?.trustedSince,
+            trustedAtRun: typeof update['trustedAtRun'] === 'number' ? update['trustedAtRun'] : existing?.trustedAtRun,
+            lastGraduationOfferRun: typeof update['lastGraduationOfferRun'] === 'number' ? update['lastGraduationOfferRun'] : existing?.lastGraduationOfferRun,
+            graduationSuppressedUntilRun: typeof update['graduationSuppressedUntilRun'] === 'number' ? update['graduationSuppressedUntilRun'] : existing?.graduationSuppressedUntilRun,
+            updatedAt: new Date(),
+        };
+        await this.jobExecutionModesCollection.replaceOne({ userId, jobName }, record, { upsert: true });
+    }
     async verifyApiKey(key) {
         if (!this.keysCollection)
             throw new Error('DB not connected');

package/package.json

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

package/public/ai-hub/index.html

@@ -827,8 +827,10 @@
   </div>
 
   <!-- #1351: unified Add Agent dialog — add a configured profile directly, or delegate
-       setup to FRAIM. Replaces the separate "Add AI agent" button + "setup another tool"
-       disclosure both opening the same generic onboarding modal with no manual option. -->
+       setup to FRAIM. This is the single entry point for agent setup: the toolbar's
+       "Add AI agent" button and, on #1390, the per-tool quick-picks inside the Delegate
+       tab (which replaced the old standalone "setup another tool" disclosure) both open
+       this same dialog. -->
   <div id="add-agent-modal" class="modal-overlay" role="dialog" aria-modal="true" aria-labelledby="aam-title" hidden>
     <div class="modal-card">
       <div class="modal-hdr">
@@ -845,6 +847,11 @@
       <div class="modal-body">
         <div id="aam-manual-pane"></div>
         <div id="aam-delegate-pane" hidden>
+          <div id="aam-delegate-quickpicks" class="aam-delegate-quickpicks" data-testid="aam-delegate-quickpicks" hidden>
+            <p class="aam-delegate-quickpicks-label">Not set up yet on this machine:</p>
+            <div id="aam-delegate-quickpicks-list" class="aam-delegate-quickpicks-list"></div>
+            <p id="aam-delegate-quickpick-caption" class="aam-delegate-quickpick-caption" data-testid="aam-delegate-quickpick-caption" hidden></p>
+          </div>
           <div class="np-field">
             <label for="aam-delegate-context">Any specific direction for this run? <span class="np-optional">(optional, leave blank to start with defaults)</span></label>
             <textarea id="aam-delegate-context" rows="4" data-testid="add-agent-delegate-context" placeholder="e.g. Configure a CLI, a cloud-credit route, or a custom profile."></textarea>