nexus-prime 6.0.0 → 6.1.0

package/dist/agents/adapters/ide-compat.d.ts

@@ -5,6 +5,7 @@
  * Supported: VS Code (Claude Code ext), JetBrains, Cursor, Windsurf, Zed, Continue.dev, Aider, Cline, Codex
  */
 export type IDEId = 'claude-code' | 'cursor' | 'windsurf' | 'continue' | 'cline' | 'zed' | 'codex';
+export type CallerIDEId = 'claude-code' | 'cursor' | 'windsurf' | 'continue' | 'zed' | 'codex';
 export interface McpConfigOutput {
     /** Absolute path where the config should be written */
     configPath: string | null;
@@ -13,6 +14,8 @@ export interface McpConfigOutput {
     /** If true, attempt to merge into existing file rather than overwrite */
     merge: boolean;
 }
+export declare function resetDetectedCallerIDECache(): void;
+export declare function detectCallerIDE(): CallerIDEId | null;
 /** Detect which IDEs are present in the workspace or home directory. */
 export declare function detectInstalledIDEs(workspaceRoot: string): IDEId[];
 /** Get the MCP config content and target path for a given IDE. */

package/dist/agents/adapters/ide-compat.js

@@ -6,7 +6,8 @@
  */
 import { existsSync } from 'fs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { dirname, join, resolve } from 'path';
+let callerIDECache;
 /** Nexus Prime MCP server entry (stdio transport). */
 function nexusMcpServerEntry(workspaceRoot) {
     return {
@@ -15,6 +16,58 @@ function nexusMcpServerEntry(workspaceRoot) {
         env: {},
     };
 }
+function hasAnyEnvPrefix(prefix) {
+    return Object.keys(process.env).some((key) => key.startsWith(prefix));
+}
+function detectCallerIDEFromEnv() {
+    if (process.env.CLAUDECODE || process.env.CLAUDE_CODE || process.env.CLAUDE_SESSION_ID || process.env.CLAUDE_PROJECT_DIR) {
+        return 'claude-code';
+    }
+    if (process.env.CURSOR_TRACE_ID || hasAnyEnvPrefix('CURSOR_')) {
+        return 'cursor';
+    }
+    if (process.env.CODEX_HOME || hasAnyEnvPrefix('CODEX_')) {
+        return 'codex';
+    }
+    if (hasAnyEnvPrefix('WINDSURF_')) {
+        return 'windsurf';
+    }
+    if (hasAnyEnvPrefix('CONTINUE_')) {
+        return 'continue';
+    }
+    if (hasAnyEnvPrefix('ZED_')) {
+        return 'zed';
+    }
+    return null;
+}
+function detectCallerIDEFromFilesystem(startDir) {
+    let current = resolve(startDir);
+    for (;;) {
+        if (existsSync(join(current, '.cursor')))
+            return 'cursor';
+        if (existsSync(join(current, '.continue')))
+            return 'continue';
+        if (existsSync(join(current, '.windsurf')))
+            return 'windsurf';
+        if (existsSync(join(current, '.zed')))
+            return 'zed';
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+export function resetDetectedCallerIDECache() {
+    callerIDECache = undefined;
+}
+export function detectCallerIDE() {
+    if (callerIDECache !== undefined) {
+        return callerIDECache;
+    }
+    callerIDECache = detectCallerIDEFromEnv() ?? detectCallerIDEFromFilesystem(process.cwd());
+    return callerIDECache;
+}
 /** Detect which IDEs are present in the workspace or home directory. */
 export function detectInstalledIDEs(workspaceRoot) {
     const detected = [];

package/dist/agents/adapters/mcp/dispatch.js

@@ -13,6 +13,8 @@ import { handleGovernanceGroup } from './handlers/governance.js';
 import { handleRuntimeGroup } from './handlers/runtime.js';
 import { handleDiscoveryGroup } from './handlers/discovery.js';
 import { handleMiscGroup } from './handlers/misc.js';
+import { nexusEventBus } from '../../../engines/event-bus.js';
+import { recordToolInvocation } from './tool-health.js';
 /**
  * Route a tool call to the appropriate handler group.
  *
@@ -22,11 +24,24 @@ import { handleMiscGroup } from './handlers/misc.js';
  */
 export async function dispatchMcpToolCall(hctx, request, args, ctx) {
     const toolName = String(request.params?.name ?? '');
-    // Try each group in priority order. Groups return undefined for unknown tools.
-    return (await handleOrchestrationGroup(toolName, hctx, request, args, ctx) ??
-        await handleMemoryGroup(toolName, hctx, request, args, ctx) ??
-        await handleGovernanceGroup(toolName, hctx, request, args, ctx) ??
-        await handleRuntimeGroup(toolName, hctx, request, args, ctx) ??
-        await handleDiscoveryGroup(toolName, hctx, request, args, ctx) ??
-        await handleMiscGroup(toolName, hctx, request, args, ctx));
+    const startedAt = Date.now();
+    try {
+        // Try each group in priority order. Groups return undefined for unknown tools.
+        const result = (await handleOrchestrationGroup(toolName, hctx, request, args, ctx) ??
+            await handleMemoryGroup(toolName, hctx, request, args, ctx) ??
+            await handleGovernanceGroup(toolName, hctx, request, args, ctx) ??
+            await handleRuntimeGroup(toolName, hctx, request, args, ctx) ??
+            await handleDiscoveryGroup(toolName, hctx, request, args, ctx) ??
+            await handleMiscGroup(toolName, hctx, request, args, ctx));
+        const durationMs = Date.now() - startedAt;
+        recordToolInvocation(toolName, durationMs, 'ok');
+        nexusEventBus.emit('tool.invocation', { toolName, durationMs, status: 'ok' });
+        return result;
+    }
+    catch (err) {
+        const durationMs = Date.now() - startedAt;
+        recordToolInvocation(toolName, durationMs, 'error');
+        nexusEventBus.emit('tool.invocation', { toolName, durationMs, status: 'error' });
+        throw err;
+    }
 }

package/dist/agents/adapters/mcp/envelope.d.ts

@@ -0,0 +1,50 @@
+/**
+ * HandlerEnvelope — unified success/error shape for all MCP tool handlers.
+ *
+ * Lifted out of runHandler.ts so any module (middleware, handlers, tests,
+ * dashboard routes) can import the type without pulling in the full
+ * runHandler runtime.  runHandler.ts re-exports these for back-compat.
+ */
+export type HandlerErrorCode = 'timeout' | 'sqlite-busy' | 'runtime-cold' | 'input-invalid' | 'nested-dispatch-refused' | 'internal';
+export interface HandlerEnvelope<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: {
+        code: HandlerErrorCode;
+        message: string;
+        retriable: boolean;
+        hint?: string;
+    };
+    meta: {
+        toolName: string;
+        durationMs: number;
+        attempts: number;
+        runtimeHotAt: number | null;
+    };
+}
+export interface RunHandlerOptions {
+    /** Override the per-client default timeout. */
+    timeoutMs?: number;
+    /** Max retries for transient errors (SQLite-busy, runtime-cold). Default 1. */
+    retries?: number;
+    /** Caller name for per-client timeout selection. */
+    callerName?: string;
+    /** Timestamp (ms) when the runtime became hot. Passed through into meta. */
+    runtimeHotAt?: number | null;
+}
+/**
+ * Convert a HandlerEnvelope into the MCP tool-call response shape.
+ *
+ * On success, if `envelope.data` is already a ToolResult
+ * (`{ content: Array<...> }`), it is returned directly so we never
+ * double-wrap handler output.  Any other value is JSON-stringified into a
+ * single text content block.
+ *
+ * On error, a structured JSON error block is produced.
+ */
+export declare function envelopeToMcpResponse<T>(envelope: HandlerEnvelope<T>): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};

package/dist/agents/adapters/mcp/envelope.js

@@ -0,0 +1,45 @@
+/**
+ * HandlerEnvelope — unified success/error shape for all MCP tool handlers.
+ *
+ * Lifted out of runHandler.ts so any module (middleware, handlers, tests,
+ * dashboard routes) can import the type without pulling in the full
+ * runHandler runtime.  runHandler.ts re-exports these for back-compat.
+ */
+// ─── Serialisation helper ─────────────────────────────────────────────────────
+/**
+ * Convert a HandlerEnvelope into the MCP tool-call response shape.
+ *
+ * On success, if `envelope.data` is already a ToolResult
+ * (`{ content: Array<...> }`), it is returned directly so we never
+ * double-wrap handler output.  Any other value is JSON-stringified into a
+ * single text content block.
+ *
+ * On error, a structured JSON error block is produced.
+ */
+export function envelopeToMcpResponse(envelope) {
+    if (envelope.ok) {
+        const data = envelope.data;
+        // Pass-through: handler already returned a ToolResult-shaped object.
+        if (data !== null &&
+            data !== undefined &&
+            typeof data === 'object' &&
+            Array.isArray(data.content)) {
+            return data;
+        }
+        const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+        return { content: [{ type: 'text', text }] };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    status: 'error',
+                    code: envelope.error.code,
+                    message: envelope.error.message,
+                    retriable: envelope.error.retriable,
+                    hint: envelope.error.hint,
+                    meta: envelope.meta,
+                }, null, 2),
+            }],
+    };
+}

package/dist/agents/adapters/mcp/handlers/discovery.js

@@ -5,8 +5,12 @@
  */
 import { formatBullets, formatJsonDetails, collectFolderFiles, } from '../helpers.js';
 import { listExecutionPresets } from '../../../../engines/execution-presets.js';
+import { requireRuntime } from '../util/require-runtime.js';
 import * as path from 'path';
 export async function handleDiscoveryGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     switch (toolName) {
         case 'nexus_list_execution_presets': {
             const presets = listExecutionPresets();

package/dist/agents/adapters/mcp/handlers/governance.js

@@ -17,9 +17,15 @@ import { ensureBootstrap } from '../../../../engines/client-bootstrap.js';
 import { HybridRetriever } from '../../../../engines/hybrid-retriever.js';
 import { GraphTraversalEngine } from '../../../../engines/graph-traversal.js';
 import { fileURLToPath } from 'url';
+import { requireRuntime } from '../util/require-runtime.js';
+import { getAllPerfStats } from '../../../../engines/perf-history.js';
+import { getTTVSnapshot } from '../../../../engines/telemetry.js';
 const _gfile = fileURLToPath(import.meta.url);
 const PROJECT_ROOT = path.resolve(path.dirname(_gfile), '..', '..', '..', '..', '..');
 export async function handleGovernanceGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     switch (toolName) {
         case 'nexus_runtime_health': {
             const envelope = hctx.nexusRef.getRuntimeHealthEnvelope();
@@ -78,6 +84,30 @@ export async function handleGovernanceGroup(toolName, hctx, request, args, ctx)
                     : []),
             ];
             const allLive = deadSubsystems.length === 0;
+            // ── perfProfile: p50/p90/p99 per tool + TTV snapshot ─────────
+            const [perfStats, ttvSnap] = await Promise.all([
+                getAllPerfStats().catch(() => []),
+                Promise.resolve(getTTVSnapshot()),
+            ]);
+            const perfProfile = {
+                tools: perfStats.map((s) => ({
+                    tool: s.tool,
+                    count: s.count,
+                    p50ms: s.p50,
+                    p90ms: s.p90,
+                    p99ms: s.p99,
+                    budget: s.budget ?? null,
+                    slow: s.budget ? s.p99 > s.budget.fail : false,
+                })),
+                ttv: {
+                    daemonStartAt: ttvSnap.daemonStartAt,
+                    firstBootstrapMs: ttvSnap.firstBootstrapAt != null ? ttvSnap.firstBootstrapAt - ttvSnap.daemonStartAt : null,
+                    firstMemoryMs: ttvSnap.firstMemoryAt != null ? ttvSnap.firstMemoryAt - ttvSnap.daemonStartAt : null,
+                    firstInteractionMs: ttvSnap.firstInteractionAt != null ? ttvSnap.firstInteractionAt - ttvSnap.daemonStartAt : null,
+                    firstMissionMs: ttvSnap.firstMissionCompleteAt != null ? ttvSnap.firstMissionCompleteAt - ttvSnap.daemonStartAt : null,
+                },
+            };
+            const slowTools = perfProfile.tools.filter((t) => t.slow).map((t) => t.tool);
             return {
                 content: [{
                         type: 'text',
@@ -94,6 +124,7 @@ export async function handleGovernanceGroup(toolName, hctx, request, args, ctx)
                                 `Workspace: ${envelope.workspace.source}`,
                                 `Issues: ${issues.length}`,
                                 `Ngram index: ${ngramOversized ? 'oversized' : 'ok'} (${Math.round(ngramSizeBytes / 1024 / 1024)}MB)`,
+                                ...(slowTools.length > 0 ? [`\u26A0\uFE0F Slow tools (p99 > budget): ${slowTools.join(', ')}`] : []),
                             ]),
                             issues.length > 0 ? formatBullets(issues.map((issue) => `\u26A0\uFE0F ${issue}`)) : '',
                             (() => {
@@ -115,6 +146,7 @@ export async function handleGovernanceGroup(toolName, hctx, request, args, ctx)
                                     oversized: ngramOversized,
                                 },
                                 securityAudit: getSharedAuditLog().getSummary(),
+                                perfProfile,
                             }),
                         ].filter(Boolean).join('\n\n'),
                     }],

package/dist/agents/adapters/mcp/handlers/memory.js

@@ -8,7 +8,12 @@ import { formatBullets, formatJsonDetails } from '../helpers.js';
 import { nexusEventBus } from '../../../../engines/event-bus.js';
 import { getOperativeJournal } from '../../../../engines/operative-journal.js';
 import { storeToolSummary } from '../util/auto-memory.js';
+import { requireRuntime } from '../util/require-runtime.js';
+import { recordFirstMemory } from '../../../../engines/telemetry.js';
 export async function handleMemoryGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     switch (toolName) {
         case 'nexus_store_memory': {
             const content = String(request.params.arguments?.content ?? '');
@@ -19,6 +24,7 @@ export async function handleMemoryGroup(toolName, hctx, request, args, ctx) {
             const verbatim = Boolean(request.params.arguments?.verbatim ?? false);
             const id = hctx.nexusRef.storeMemory(content, priority, tags, undefined, undefined, { verbatim });
             hctx.telemetry.recordStore();
+            void recordFirstMemory().catch(() => { });
             hctx.sessionDNA.recordMemoryStore();
             const nudge = hctx.telemetry.planningNudge('store', { priority });
             if (ctx) {
@@ -170,7 +176,7 @@ export async function handleMemoryGroup(toolName, hctx, request, args, ctx) {
             };
         }
         case 'nexus_memory_import': {
-            const result = hctx.nexusRef.importMemoryBundle({
+            const result = await hctx.nexusRef.importMemoryBundle({
                 path: request.params.arguments?.path ? String(request.params.arguments.path) : undefined,
                 bundle: request.params.arguments?.bundle,
             });
@@ -232,7 +238,7 @@ export async function handleMemoryGroup(toolName, hctx, request, args, ctx) {
                 ]);
             }
             else if (action === 'syncFrom') {
-                const result = bridge.syncFrom(sourceDir || bridge.getBridgeDir());
+                const result = await bridge.syncFrom(sourceDir || bridge.getBridgeDir());
                 detail = formatBullets([
                     `Success: ${result.success}`,
                     `Imported: ${result.imported}`,

package/dist/agents/adapters/mcp/handlers/orchestration.js

@@ -12,12 +12,18 @@ import { formatReadingPlan } from '../../../../engines/token-supremacy.js';
 import { GhostPass, summarizeExecution } from '../../../../phantom/index.js';
 import { applyExecutionPreset, resolveExecutionPreset } from '../../../../engines/execution-presets.js';
 import { pLimit } from '../../../../engines/util/p-limit.js';
-import { promises as fsPromises, statSync } from 'fs';
+import { promises as fsPromises } from 'fs';
 import { getSharedLicenseManager } from '../../../../licensing/index.js';
 import { SessionDNAManager } from '../../../../engines/session-dna.js';
 import { getSharedTelemetry } from '../../../../engines/telemetry-remote.js';
 import { storeToolSummary } from '../util/auto-memory.js';
+import { requireRuntime } from '../util/require-runtime.js';
+import { ensureCrGraphBuilt } from '../../../../engines/code-review-graph-client.js';
+import { recordFirstBootstrap } from '../../../../engines/telemetry.js';
 export async function handleOrchestrationGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     // Variables computed in the original handleToolCall preamble and used by these cases
     const detailLevel = normalizeDetailLevel(args.detailLevel);
     const requestedIntent = normalizeResponseIntent(args.intent);
@@ -117,7 +123,9 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                     remoteTelemetry.trackTokenSavings(Number(bootstrap.tokenOptimization.planMetrics.savings));
                 }
             }
-            catch { /* best-effort telemetry */ }
+            catch (err) {
+                nexusEventBus.emit('mcp.handler.best-effort-failed', { toolName, stage: 'track-session-start', error: err instanceof Error ? err.message : String(err) });
+            }
             if (ctx) {
                 ctx.meta.tokenSavings = Number(bootstrap.tokenOptimization?.planMetrics?.savings ?? 0);
                 ctx.meta.projectMemoryBootstrapCount = Number(bootstrap.projectMemoryBootstrap?.count ?? 0);
@@ -133,7 +141,20 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
             try {
                 storeToolSummary(hctx, 'nexus_session_bootstrap', `Session bootstrap: ${bootstrapGoal || 'interactive session'}. Memory: prefrontal=${bootstrap.memoryStats?.prefrontal ?? 0}, hippocampus=${bootstrap.memoryStats?.hippocampus ?? 0}, cortex=${bootstrap.memoryStats?.cortex ?? 0}.`);
             }
+            catch (err) {
+                nexusEventBus.emit('mcp.handler.best-effort-failed', { toolName, stage: 'persist-session-summary', error: err instanceof Error ? err.message : String(err) });
+            }
+            // Non-blocking: ensure cr-graph is fresh after bootstrap. Fires after the handler
+            // returns so the response is not delayed. Any failure is silently swallowed.
+            try {
+                const crRepoRoot = hctx.nexusRef.getWorkspaceContext().repoRoot;
+                if (crRepoRoot) {
+                    setImmediate(() => { void ensureCrGraphBuilt(crRepoRoot); });
+                }
+            }
             catch { /* best-effort */ }
+            // TTV telemetry: record first successful bootstrap (fire-and-forget).
+            void recordFirstBootstrap().catch(() => { });
             const timings = {
                 totalMs: Date.now() - callStartedAt,
             };
@@ -232,28 +253,11 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                             formatBullets([
                                 `Workspace: ${workspace.repoName} (${workspace.workspaceSource})`,
                                 `Client: ${bootstrap.client?.displayName || bootstrap.client?.clientId || 'unknown'} (${bootstrap.client?.state || 'unknown'})`,
-                                `Bootstrap depth: ${bootstrap.depth || bootstrapDepth}`,
                                 `Memory recall: ${bootstrap.memoryRecall?.count ?? 0} result(s)`,
                                 `Memory stats: prefrontal ${bootstrap.memoryStats?.prefrontal ?? 0} · hippocampus ${bootstrap.memoryStats?.hippocampus ?? 0} · cortex ${bootstrap.memoryStats?.cortex ?? 0}`,
                                 `Recommended next step: ${bootstrap.recommendedNextStep || 'nexus_orchestrate'}`,
-                                `Execution mode: ${bootstrap.recommendedExecutionMode || 'autonomous'}`,
                                 `Token optimization: ${bootstrap.tokenOptimization?.autoApplied ? `auto-applied — saved ${Number(bootstrap.tokenOptimization?.planMetrics?.savings ?? 0).toLocaleString()} tokens (${bootstrap.tokenOptimization?.planMetrics?.pct ?? 0}% reduction)` : (bootstrap.tokenOptimization?.required ? 'required before broad reading' : 'not required yet')}`,
                                 `Catalog health: ${bootstrap.catalogHealth?.overall || 'unknown'} · selected ${bootstrap.artifactSelectionAudit?.selected?.length || 0}`,
-                                `Shortlist: ${bootstrap.shortlist?.skills?.slice(0, 3).join(', ') || 'none'} (skills), ${bootstrap.shortlist?.specialists?.slice(0, 3).join(', ') || 'none'} (specialists)`,
-                                `Knowledge fabric: ${bootstrap.sourceMixRecommendation?.dominantSource || bootstrap.knowledgeFabric?.dominantSource || 'awaiting source mix'}`,
-                                `RAG: ${bootstrap.ragCandidateStatus?.attachedCollections || 0} attached · ${bootstrap.ragCandidateStatus?.retrievedChunks || 0} retrieved`,
-                                `Task graph: ${bootstrap.taskGraphPreview?.phases?.length || 0} phases · ${bootstrap.taskGraphPreview?.independentBranches || 0} branches`,
-                                `Worker plan: ${bootstrap.workerPlanPreview?.totalWorkers || 0} workers planned`,
-                                bootstrap.needsDeepBootstrap ? 'Deep preparation: still recommended before risky or cross-file work' : 'Deep preparation: not currently required',
-                                `Payload ref: ${workspace.stateKey} · ${detailLevel}`,
-                                `Session summary: ${bootstrap.sessionSummaryBootstrap?.savedTokens ? `reused ${Number(bootstrap.sessionSummaryBootstrap.savedTokens || 0).toLocaleString()} tokens from the previous visit` : 'none available yet'}`,
-                                bootstrap.projectMemoryBootstrap?.count
-                                    ? `Project memory: recovered ${bootstrap.projectMemoryBootstrap.count} prior project memories`
-                                    : 'Project memory: no prior project memories recovered',
-                                bootstrap.autoGhostPass?.applied
-                                    ? `Auto ghost-pass: ${bootstrap.autoGhostPass.riskAreas.length} risk area(s) · ${bootstrap.autoGhostPass.workerApproaches} approach(es)`
-                                    : `Auto ghost-pass: skipped`,
-                                `Bootstrap status: ${bootstrap.clientBootstrapStatus?.clients?.length || 0} client manifests tracked`,
                                 (() => {
                                     try {
                                         const _lic = getSharedLicenseManager().getStatus();
@@ -266,11 +270,30 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                                         return '';
                                     }
                                 })(),
+                                ...(detailLevel === 'debug' ? [
+                                    `Bootstrap depth: ${bootstrap.depth || bootstrapDepth}`,
+                                    `Execution mode: ${bootstrap.recommendedExecutionMode || 'autonomous'}`,
+                                    `Shortlist: ${bootstrap.shortlist?.skills?.slice(0, 3).join(', ') || 'none'} (skills), ${bootstrap.shortlist?.specialists?.slice(0, 3).join(', ') || 'none'} (specialists)`,
+                                    `Knowledge fabric: ${bootstrap.sourceMixRecommendation?.dominantSource || bootstrap.knowledgeFabric?.dominantSource || 'awaiting source mix'}`,
+                                    `RAG: ${bootstrap.ragCandidateStatus?.attachedCollections || 0} attached · ${bootstrap.ragCandidateStatus?.retrievedChunks || 0} retrieved`,
+                                    `Task graph: ${bootstrap.taskGraphPreview?.phases?.length || 0} phases · ${bootstrap.taskGraphPreview?.independentBranches || 0} branches`,
+                                    `Worker plan: ${bootstrap.workerPlanPreview?.totalWorkers || 0} workers planned`,
+                                    bootstrap.needsDeepBootstrap ? 'Deep preparation: still recommended before risky or cross-file work' : 'Deep preparation: not currently required',
+                                    `Payload ref: ${workspace.stateKey} · ${detailLevel}`,
+                                    `Session summary: ${bootstrap.sessionSummaryBootstrap?.savedTokens ? `reused ${Number(bootstrap.sessionSummaryBootstrap.savedTokens || 0).toLocaleString()} tokens from the previous visit` : 'none available yet'}`,
+                                    bootstrap.projectMemoryBootstrap?.count
+                                        ? `Project memory: recovered ${bootstrap.projectMemoryBootstrap.count} prior project memories`
+                                        : 'Project memory: no prior project memories recovered',
+                                    bootstrap.autoGhostPass?.applied
+                                        ? `Auto ghost-pass: ${bootstrap.autoGhostPass.riskAreas.length} risk area(s) · ${bootstrap.autoGhostPass.workerApproaches} approach(es)`
+                                        : `Auto ghost-pass: skipped`,
+                                    `Bootstrap status: ${bootstrap.clientBootstrapStatus?.clients?.length || 0} client manifests tracked`,
+                                ] : []),
                             ]),
                             detailLevel === 'debug' && bootstrap.tokenOptimization?.autoApplied && bootstrap.tokenOptimization?.plan
                                 ? `Auto token plan\n\`\`\`txt\n${bootstrap.tokenOptimization.plan}\n\`\`\``
                                 : '',
-                            formatJsonDetails('Structured details', payload),
+                            detailLevel === 'debug' ? formatJsonDetails('Structured details', payload) : '',
                             hctx.formatProtocolChecklist(),
                         ].filter(Boolean).join('\n\n'),
                     }],
@@ -350,7 +373,9 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                     const modifiedFiles = execution.workerResults.flatMap((w) => w.modifiedFiles);
                     hctx.nexusRef.storeMemory(`Run ${execution.runId} ${execution.state}: ${summarizeExecution(execution)}. Workers: ${verifiedWorkers}/${execution.workerResults.length} verified. Files modified: ${modifiedFiles.slice(0, 5).join(', ') || 'none'}.`, 0.34, ['#run-summary', '#auto', '#system-hidden']);
                 }
-                catch { /* best-effort */ }
+                catch (err) {
+                    nexusEventBus.emit('mcp.handler.best-effort-failed', { toolName, stage: 'auto-memory-store', error: err instanceof Error ? err.message : String(err) });
+                }
                 execution.activeSkills.forEach((skill) => hctx.sessionDNA.recordSkill(skill.name));
                 execution.workerResults.forEach((result) => {
                     result.modifiedFiles.forEach((file) => hctx.sessionDNA.recordFileModified(file));
@@ -440,21 +465,23 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                                     `Run ID: ${execution.runId}`,
                                     `Summary: ${summarizeExecution(execution)}`,
                                     `Crew: ${execution.plannerState?.selectedCrew?.name || 'baseline path'}`,
-                                    `Specialists: ${execution.plannerState?.selectedSpecialists.map((specialist) => specialist.name).slice(0, 4).join(', ') || 'none selected'}`,
-                                    `Assets: ${(execution.activeSkills || []).length} skills · ${(execution.activeWorkflows || []).length} workflows · ${(runtimeUsage.artifactSelectionAudit?.selected?.length || 0)} audited selections`,
-                                    `Task graph: ${runtimeUsage.taskGraph?.phases?.length || execution.taskGraph?.phases?.length || 0} phases · ${runtimeUsage.workerPlan?.totalWorkers || execution.workerPlan?.totalWorkers || 0} workers`,
-                                    `Catalog health: ${runtimeUsage.catalogHealth?.overall || 'unknown'}`,
-                                    preset ? `Preset: ${preset.name} (${preset.id})` : null,
                                     `Verification: ${verifiedWorkers}/${execution.workerResults.length} worker(s) verified`,
-                                    `Worktrees: ${runtimeUsage.worktreeHealth?.overall || 'unknown'} · repaired ${runtimeUsage.worktreeHealth?.repairedEntries || 0} · broken ${runtimeUsage.worktreeHealth?.brokenEntries || 0}`,
-                                    `Tokens: saved ${Number(execution.tokenTelemetry?.savedTokens || 0).toLocaleString()} · compression ${Number(execution.tokenTelemetry?.compressionPct || 0)}% · dominant ${runtimeUsage.sourceAwareTokenBudget?.dominantSource || execution.knowledgeFabric?.sourceMix?.dominantSource || 'repo'}`,
+                                    `Tokens: saved ${Number(execution.tokenTelemetry?.savedTokens || 0).toLocaleString()} · compression ${Number(execution.tokenTelemetry?.compressionPct || 0)}%`,
                                     autoTokenApplyNote || null,
-                                    `RAG: ${(runtimeUsage.ragUsageSummary?.attachedCollections || execution.knowledgeFabric?.rag.attachedCollections.length || 0)} attached · ${(runtimeUsage.ragUsageSummary?.retrievedChunks || execution.knowledgeFabric?.rag.hits.length || 0)} retrieved`,
-                                    `Memory scopes: ${Object.entries(runtimeUsage.memoryScopeUsage?.byScope || execution.memoryScopeUsage?.byScope || {}).map(([scope, count]) => `${scope}:${count}`).join(' · ') || 'awaiting shared/session reads'}`,
-                                    `Payload ref: ${workspace.stateKey} · ${detailLevel}`,
+                                    ...(detailLevel === 'debug' ? [
+                                        `Specialists: ${execution.plannerState?.selectedSpecialists.map((specialist) => specialist.name).slice(0, 4).join(', ') || 'none selected'}`,
+                                        `Assets: ${(execution.activeSkills || []).length} skills · ${(execution.activeWorkflows || []).length} workflows · ${(runtimeUsage.artifactSelectionAudit?.selected?.length || 0)} audited selections`,
+                                        `Task graph: ${runtimeUsage.taskGraph?.phases?.length || execution.taskGraph?.phases?.length || 0} phases · ${runtimeUsage.workerPlan?.totalWorkers || execution.workerPlan?.totalWorkers || 0} workers`,
+                                        `Catalog health: ${runtimeUsage.catalogHealth?.overall || 'unknown'}`,
+                                        preset ? `Preset: ${preset.name} (${preset.id})` : null,
+                                        `Worktrees: ${runtimeUsage.worktreeHealth?.overall || 'unknown'} · repaired ${runtimeUsage.worktreeHealth?.repairedEntries || 0} · broken ${runtimeUsage.worktreeHealth?.brokenEntries || 0}`,
+                                        `RAG: ${(runtimeUsage.ragUsageSummary?.attachedCollections || execution.knowledgeFabric?.rag.attachedCollections.length || 0)} attached · ${(runtimeUsage.ragUsageSummary?.retrievedChunks || execution.knowledgeFabric?.rag.hits.length || 0)} retrieved`,
+                                        `Memory scopes: ${Object.entries(runtimeUsage.memoryScopeUsage?.byScope || execution.memoryScopeUsage?.byScope || {}).map(([scope, count]) => `${scope}:${count}`).join(' · ') || 'awaiting shared/session reads'}`,
+                                        `Payload ref: ${workspace.stateKey} · ${detailLevel}`,
+                                    ] : []),
                                 ]),
                                 detailLevel === 'debug' && execution.result ? `Result\n\`\`\`\n${execution.result}\n\`\`\`` : `Result preview\n\`\`\`\n${truncateText(execution.result || summarizeExecution(execution), 900)}\n\`\`\``,
-                                formatJsonDetails('Structured details', payload),
+                                detailLevel === 'debug' ? formatJsonDetails('Structured details', payload) : '',
                                 hctx.formatRemainingProtocolSteps(),
                             ].filter(Boolean).join('\n\n'),
                         }],
@@ -509,7 +536,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                     return { path: resolved, sizeBytes: 0 };
                 }
             })));
-            const plan = getTokenEngine().plan(task, files);
+            const plan = await getTokenEngine().plan(task, files);
             const formatted = formatReadingPlan(plan);
             // Persist the decision
             hctx.nexusRef.storeMemory(`Token plan for "${task.slice(0, 80)}": ` +
@@ -557,16 +584,16 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
             const rawFiles = Array.isArray(request.params.arguments?.files)
                 ? request.params.arguments.files.map(String)
                 : [];
-            const files = rawFiles.map(p => {
+            const files = await Promise.all(rawFiles.map(async (p) => {
                 const resolved = hctx.resolveToolPath(p, request.params.arguments ?? {});
                 try {
-                    const stat = statSync(resolved);
+                    const stat = await fsPromises.stat(resolved);
                     return { path: resolved, sizeBytes: stat.size, lastModified: stat.mtimeMs };
                 }
                 catch {
                     return { path: resolved, sizeBytes: 0 };
                 }
-            });
+            }));
             const ghost = new GhostPass(hctx.getWorkspace(request.params.arguments ?? {}).repoRoot);
             const report = await ghost.analyze(goal, files);
             hctx.nexusRef.storeMemory(`Ghost pass for "${goal.slice(0, 80)}": ${report.riskAreas.length} risks identified.`, 0.6, ['#ghost-pass']);
@@ -650,7 +677,9 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
             try {
                 storeToolSummary(hctx, 'nexus_spawn_workers', `Worker plan: "${goal.slice(0, 100)}" — ${workersCount} workers, ${rawFiles.length} files.`);
             }
-            catch { /* best-effort */ }
+            catch (err) {
+                nexusEventBus.emit('mcp.handler.best-effort-failed', { toolName, stage: 'worker-plan-summary', error: err instanceof Error ? err.message : String(err) });
+            }
             const execution = await hctx.getRuntime().run(applyExecutionPreset({
                 goal,
                 files: rawFiles,

package/dist/agents/adapters/mcp/handlers/runtime.js

@@ -8,7 +8,11 @@ import { formatBullets, formatJsonDetails, } from '../helpers.js';
 import { nexusEventBus } from '../../../../engines/event-bus.js';
 import { getSharedLicenseManager, snapshotPCU, formatPCUStatus } from '../../../../licensing/index.js';
 import { TokenAnalyticsEngine } from '../../../../engines/token-analytics.js';
+import { requireRuntime } from '../util/require-runtime.js';
 export async function handleRuntimeGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     switch (toolName) {
         case 'nexus_license_usage': {
             const fmt = String(request.params.arguments?.format ?? 'summary');
@@ -220,7 +224,7 @@ export async function handleRuntimeGroup(toolName, hctx, request, args, ctx) {
         }
         case 'nexus_run_status': {
             const runId = String(request.params.arguments?.runId ?? '');
-            const run = hctx.getRuntime().getRun(runId);
+            const run = await hctx.getRuntime().getRun(runId);
             if (!run) {
                 return { content: [{ type: 'text', text: `❌ Run not found: ${runId}` }] };
             }

package/dist/agents/adapters/mcp/runHandler.d.ts

@@ -8,34 +8,14 @@
  *
  * Per-client timeouts (AI Lead refinement):
  *   Codex 90 s · Claude Code 60 s · Cursor 30 s · default 25 s
+ *
+ * Types and `envelopeToMcpResponse` are canonical in ./envelope.ts;
+ * re-exported from here for backward compatibility.
  */
-export type HandlerErrorCode = 'timeout' | 'sqlite-busy' | 'runtime-cold' | 'input-invalid' | 'nested-dispatch-refused' | 'internal';
-export interface HandlerEnvelope<T = unknown> {
-    ok: boolean;
-    data?: T;
-    error?: {
-        code: HandlerErrorCode;
-        message: string;
-        retriable: boolean;
-        hint?: string;
-    };
-    meta: {
-        toolName: string;
-        durationMs: number;
-        attempts: number;
-        runtimeHotAt: number | null;
-    };
-}
-export interface RunHandlerOptions {
-    /** Override the per-client default timeout. */
-    timeoutMs?: number;
-    /** Max retries for transient errors (SQLite-busy, runtime-cold). Default 1. */
-    retries?: number;
-    /** Caller name for per-client timeout selection. */
-    callerName?: string;
-    /** Timestamp (ms) when the runtime became hot. Passed through into meta. */
-    runtimeHotAt?: number | null;
-}
+import type { RunHandlerOptions } from './envelope.js';
+import type { HandlerEnvelope } from './envelope.js';
+export type { HandlerErrorCode, HandlerEnvelope, RunHandlerOptions } from './envelope.js';
+export { envelopeToMcpResponse } from './envelope.js';
 /**
  * Run a handler function with timeout, retry, and structured envelope.
  *
@@ -46,10 +26,3 @@ export interface RunHandlerOptions {
  * }, { callerName: hctx.adapterName });
  */
 export declare function runHandler<T>(toolName: string, fn: () => Promise<T>, opts?: RunHandlerOptions): Promise<HandlerEnvelope<T>>;
-/** Convert a HandlerEnvelope into the MCP tool-call response shape. */
-export declare function envelopeToMcpResponse<T>(envelope: HandlerEnvelope<T>): {
-    content: Array<{
-        type: 'text';
-        text: string;
-    }>;
-};