nexus-prime 4.8.2 → 4.9.0

package/README.md

@@ -630,15 +630,26 @@ Inventory Snapshot: 109 skills · 64 workflows · 9 hooks · 5 automations · 7
 ## 📜 Release History
 
 <details open>
-<summary><b>v4.8.0</b> · 2026-03-31 · Seamless Intelligence Upgrade — smarter runtime routing, durable memory controls, and governed work graphs</summary>
+<summary><b>v4.9.0</b> · 2026-04-01 · Release QA Hardening — repo-root upgrade safety, truthful degraded startup, and deterministic ship gates</summary>
 
-- **Bootstrap truth for Codex and MCP clients**: Managed docs and bootstrap detection now describe `nexus_session_bootstrap` and `nexus_orchestrate` as MCP tool invocations, not shell commands.
-- **Runtime intelligence surfaces**: Scheduled automations, execution presets, session search, and governed skill distribution/promotion now extend the operator control plane.
-- **Durable control-plane governance**: Work claims, scoped approvals, and scoped budgets now preserve ancestry and lease semantics across missions and operatives.
-- **Memory control upgrades**: Actor-scoped memory CRUD, history, feedback, and retention hints now complement the existing project-aware memory engine.
-- **Channel ingress contract**: Slack, Telegram, and Feishu/Lark mappings now have a normalized gateway surface for thread identity, artifacts, and status exchange.
+- **Repo-root upgrade safety**: Synapse and Architects now follow the resolved runtime storage plan, migrate stale schemas in place when possible, and quarantine broken local DBs into workspace-scoped fallback storage instead of crashing startup.
+- **Truthful degraded diagnostics**: `nexus_runtime_health`, `nexus_doctor`, `nexus_autofix`, `nexus-prime status`, and the terminal cockpit now surface requested vs active engine roots, fallback state, and quarantine paths consistently.
+- **Bounded operator reads**: Runtime run artifacts are workspace-scoped, so `status`, `doctor`, and dashboard health no longer inherit slow global temp history from unrelated runs.
+- **Deterministic release QA**: Release smoke now covers stale-schema repo boots, broken-engine degraded doctor paths, corrupt vocabulary repair, and dashboard startup after fallback using isolated fixtures.
 
-Full notes: [releases/v4.8.0.md](./releases/v4.8.0.md) · Full history: [CHANGELOG.md](./CHANGELOG.md)
+Full notes: [releases/v4.9.0.md](./releases/v4.9.0.md) · Full history: [CHANGELOG.md](./CHANGELOG.md)
+</details>
+
+<details>
+<summary><b>v4.8.2</b> · 2026-04-01 · Runtime Truth Stabilization — unified health, safer bootstrap state, and operator repair flows</summary>
+
+- **Unified runtime truth**: Dashboard health, MCP diagnostics, and the terminal cockpit now read from the same runtime envelope instead of maintaining split compatibility logic.
+- **Workspace-safe bootstrap state**: Bootstrap manifests, instruction packets, and engine fallback paths now resolve from the workspace context instead of drifting to ambient cwd or first-run `/tmp` state.
+- **Operator repair surfaces**: `nexus_runtime_health`, `nexus_doctor`, `nexus_autofix`, `nexus_memory_hygiene`, plus matching CLI commands now expose safer diagnostics and self-healing flows.
+- **Dashboard contract hardening**: Creator-only investor telemetry stays permission-gated, unknown routes stay JSON-safe, compatible listeners reuse correctly, and idle Architects worklists render explicitly.
+- **Control-plane resilience**: Synapse ledger storage now follows the same fallback root as the DB, and code-review gates no longer fail a good run just because one verifier worktree went stale.
+
+Full notes: [releases/v4.8.2.md](./releases/v4.8.2.md) · Full history: [CHANGELOG.md](./CHANGELOG.md)
 </details>
 
 <details>

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

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/agents/adapters/mcp.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAuF5C,KAAK,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAE5C,KAAK,iBAAiB,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAAC;AA2TF,qBAAa,UAAW,YAAW,OAAO;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAG,KAAK,CAAU;IACtB,SAAS,UAAS;IAClB,MAAM,EAAE,MAAM,EAAE,CAAM;IAEtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,oBAAoB,CAAgG;IAC5H,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,kBAAkB,CAAqB;IAE/C,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,oBAAoB;IAsB5B,OAAO,CAAC,eAAe;IAqEvB,OAAO,CAAC,GAAG;;IAqBX,OAAO,CAAC,gBAAgB;IA4BxB,WAAW,CAAC,KAAK,EAAE,UAAU;IAI7B,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,yBAAyB;IAqFjC,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,4BAA4B;IAWpC,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,yBAAyB;IA2CjC,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,YAAY;YAON,mBAAmB;IA0DjC,OAAO,CAAC,+BAA+B;IAMvC,OAAO,CAAC,uBAAuB;IA0B/B,OAAO,CAAC,2BAA2B;IAqBnC,OAAO,CAAC,uBAAuB;IAkC/B,cAAc,CAAC,OAAO,GAAE,cAAsC,GAAG,iBAAiB,EAAE;IAIpF,OAAO,CAAC,oBAAoB;IAu8B5B,OAAO,CAAC,iBAAiB;YAyGX,cAAc;IAsuE5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAItC,OAAO,CAAC,IAAI;IAmBN,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlD,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;CAOzC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/agents/adapters/mcp.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AA+F5C,KAAK,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAE5C,KAAK,iBAAiB,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAAC;AAmVF,qBAAa,UAAW,YAAW,OAAO;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAG,KAAK,CAAU;IACtB,SAAS,UAAS;IAClB,MAAM,EAAE,MAAM,EAAE,CAAM;IAEtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,oBAAoB,CAAgG;IAC5H,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,kBAAkB,CAAqB;IAE/C,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,oBAAoB;IAsB5B,OAAO,CAAC,eAAe;IAqEvB,OAAO,CAAC,GAAG;;IAqBX,OAAO,CAAC,gBAAgB;IA4BxB,WAAW,CAAC,KAAK,EAAE,UAAU;IAI7B,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,yBAAyB;IAqFjC,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,4BAA4B;IAWpC,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,yBAAyB;IA2CjC,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,YAAY;YAON,mBAAmB;IA0DjC,OAAO,CAAC,+BAA+B;IAMvC,OAAO,CAAC,uBAAuB;IA0B/B,OAAO,CAAC,2BAA2B;IAqBnC,OAAO,CAAC,uBAAuB;IAkC/B,cAAc,CAAC,OAAO,GAAE,cAAsC,GAAG,iBAAiB,EAAE;IAIpF,OAAO,CAAC,oBAAoB;IAu+B5B,OAAO,CAAC,iBAAiB;YAsGX,cAAc;IA+2E5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAItC,OAAO,CAAC,IAAI;IAmBN,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlD,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;CAOzC"}

package/dist/agents/adapters/mcp.js

@@ -30,6 +30,8 @@ import { getGstackBridge } from '../../engines/gstack-bridge.js';
 import { getSharedContextDiscovery } from '../../engines/context-discovery.js';
 import { MiddlewarePipeline } from '../../engines/middleware-pipeline.js';
 import { applyExecutionPreset, listExecutionPresets, resolveExecutionPreset } from '../../engines/execution-presets.js';
+import { ensureBootstrap } from '../../engines/client-bootstrap.js';
+import { resolveWorkspaceContext } from '../../engines/workspace-resolver.js';
 import { synapseToolDefinitions, handleSynapseToolCall } from '../../synapse/index.js';
 import { architectsToolDefinitions, handleArchitectsToolCall } from '../../architects/index.js';
 const tokenEngine = new TokenSupremacyEngine();
@@ -42,8 +44,13 @@ const federation = new FederationEngine();
 // Lazy-initialized fallback runtime to avoid leaking a phantom runtime at module load
 let _fallbackRuntime = null;
 function getFallbackRuntime() {
-    if (!_fallbackRuntime)
-        _fallbackRuntime = createSubAgentRuntime({ repoRoot: process.cwd() });
+    if (!_fallbackRuntime) {
+        const workspace = resolveWorkspaceContext();
+        _fallbackRuntime = createSubAgentRuntime({
+            repoRoot: workspace.repoRoot,
+            artifactsRoot: path.join(workspace.stateRoot, 'runs'),
+        });
+    }
     return _fallbackRuntime;
 }
 // Lazy-initialized Graph Engine (separate DB from core memory)
@@ -98,6 +105,11 @@ const AUTONOMOUS_TOOL_ORDER = [
     'nexus_list_crews',
     'nexus_federation_status',
     'nexus_run_status',
+    'nexus_runtime_health',
+    'nexus_doctor',
+    'nexus_autofix',
+    'nexus_memory_hygiene',
+    'nexus_selection_ledger',
 ];
 const AUTONOMOUS_TOOL_SET = new Set(AUTONOMOUS_TOOL_ORDER);
 const MANUAL_OR_DIAGNOSTIC_TOOLS = new Set([
@@ -149,6 +161,16 @@ const MANUAL_OR_DIAGNOSTIC_TOOLS = new Set([
     'nexus_knowledge_provenance',
     'nexus_openclaw_memory_sync',
 ]);
+const PRE_BOOTSTRAP_ALLOWED_TOOLS = new Set([
+    'nexus_session_bootstrap',
+    'nexus_memory_stats',
+    'nexus_runtime_health',
+    'nexus_doctor',
+    'nexus_autofix',
+    'nexus_describe_tool',
+    'nexus_federation_status',
+    'nexus_status',
+]);
 /** Session-level telemetry tracker */
 class SessionTelemetry {
     startTime = Date.now();
@@ -165,6 +187,7 @@ class SessionTelemetry {
     callsSinceOrchestrate = 0;
     fileIntentPaths = new Set();
     tokenAutoApplied = false;
+    stickyTokenOptimization = false;
     bootstrapped = false;
     recordCall() {
         this.callCount++;
@@ -200,8 +223,15 @@ class SessionTelemetry {
         this.lifecyclePhase = nextPhase;
         if (nextPhase === 'bootstrapped' || nextPhase === 'orchestrated') {
             this.resetFileIntentTracking();
-            this.optimizeTokensCalled = false;
-            this.tokenAutoApplied = false;
+            if (this.stickyTokenOptimization) {
+                this.optimizeTokensCalled = true;
+                this.tokenAutoApplied = true;
+                this.stickyTokenOptimization = false;
+            }
+            else {
+                this.optimizeTokensCalled = false;
+                this.tokenAutoApplied = false;
+            }
         }
         if (nextPhase === 'orchestrated') {
             this.mindkitCheckCalled = false;
@@ -271,6 +301,7 @@ class SessionTelemetry {
     markTokenAutoApplied() {
         this.tokenAutoApplied = true;
         this.optimizeTokensCalled = true;
+        this.stickyTokenOptimization = true;
     }
     needsStoreMemory(currentToolName) {
         if (currentToolName === 'nexus_store_memory')
@@ -1043,6 +1074,38 @@ export class MCPAdapter {
                     required: ['id'],
                 },
             },
+            {
+                name: 'nexus_runtime_health',
+                description: 'Return the unified runtime health envelope shared by MCP, dashboard, and terminal cockpit surfaces.',
+                inputSchema: { type: 'object', properties: {}, required: [] },
+            },
+            {
+                name: 'nexus_doctor',
+                description: 'Run a structured runtime doctor pass covering workspace resolution, client bootstrap drift, mandatory engine readiness, and worktree health.',
+                inputSchema: { type: 'object', properties: {}, required: [] },
+            },
+            {
+                name: 'nexus_autofix',
+                description: 'Apply safe self-healing steps: refresh bootstrap state, compact noisy memory, and report any remaining runtime issues.',
+                inputSchema: { type: 'object', properties: {}, required: [] },
+            },
+            {
+                name: 'nexus_memory_hygiene',
+                description: 'Summarize and optionally run memory hygiene so duplicate, quarantined, and low-signal memories do not pollute active recall surfaces.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        apply: { type: 'boolean', description: 'When true, run memory maintenance before returning the hygiene report' },
+                        limit: { type: 'number', description: 'Optional audit sample size (default 80)' },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: 'nexus_selection_ledger',
+                description: 'Inspect the latest selection ledger: candidate assets, chosen assets, rejected assets, and execution-ledger reasoning.',
+                inputSchema: { type: 'object', properties: {}, required: [] },
+            },
             {
                 name: 'nexus_session_bootstrap',
                 description: 'Read-only session-start summary. Returns current client identity, memory recall summary, memory stats, recommended next step, recommended execution mode, shortlist recommendations, and whether token optimization will be required.',
@@ -1870,11 +1933,8 @@ export class MCPAdapter {
             const args = request.params.arguments ?? (request.params.arguments = {});
             // Gate: block non-bootstrap tools BEFORE executing them to avoid wasted work and side effects
             if (!this.telemetry.bootstrapped &&
-                toolName !== 'nexus_session_bootstrap' &&
-                toolName !== 'nexus_memory_stats' &&
-                !toolName.startsWith('nexus_list_') &&
-                toolName !== 'nexus_federation_status' &&
-                toolName !== 'nexus_status') {
+                !PRE_BOOTSTRAP_ALLOWED_TOOLS.has(toolName) &&
+                !toolName.startsWith('nexus_list_')) {
                 return {
                     content: [{
                             type: 'text',
@@ -2023,7 +2083,7 @@ export class MCPAdapter {
                 }
                 // Auto-generate a project-scoped memory on bootstrap so dashboard always has something to show
                 try {
-                    this.nexusRef.storeMemory(`Session bootstrap: ${bootstrapGoal || 'interactive session'}. Memory: prefrontal=${bootstrap.memoryStats?.prefrontal ?? 0}, hippocampus=${bootstrap.memoryStats?.hippocampus ?? 0}, cortex=${bootstrap.memoryStats?.cortex ?? 0}.`, 0.5, ['#session-start', '#auto', '#project']);
+                    this.nexusRef.storeMemory(`Session bootstrap: ${bootstrapGoal || 'interactive session'}. Memory: prefrontal=${bootstrap.memoryStats?.prefrontal ?? 0}, hippocampus=${bootstrap.memoryStats?.hippocampus ?? 0}, cortex=${bootstrap.memoryStats?.cortex ?? 0}.`, 0.22, ['#session-start', '#auto', '#system-hidden']);
                 }
                 catch { /* best-effort */ }
                 const payload = {
@@ -2154,7 +2214,7 @@ export class MCPAdapter {
                     // Auto-store run summary memory so dashboard and future sessions can see what happened
                     try {
                         const modifiedFiles = execution.workerResults.flatMap((w) => w.modifiedFiles);
-                        this.nexusRef.storeMemory(`Run ${execution.runId} ${execution.state}: ${summarizeExecution(execution)}. Workers: ${verifiedWorkers}/${execution.workerResults.length} verified. Files modified: ${modifiedFiles.slice(0, 5).join(', ') || 'none'}.`, 0.7, ['#run-summary', '#auto', '#project']);
+                        this.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 */ }
                     execution.activeSkills.forEach((skill) => this.sessionDNA.recordSkill(skill.name));
@@ -2604,6 +2664,138 @@ export class MCPAdapter {
                         }],
                 };
             }
+            case 'nexus_runtime_health': {
+                const envelope = this.nexusRef.getRuntimeHealthEnvelope();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: [
+                                `Runtime health: ${envelope.status}`,
+                                formatBullets([
+                                    `Workspace: ${envelope.workspace.workspaceRoot}`,
+                                    `Repo root: ${envelope.workspace.repoRoot}`,
+                                    `Synapse: ${envelope.engines.synapse.mode} (${envelope.engines.synapse.storageRoot || 'n/a'})`,
+                                    `Architects: ${envelope.engines.architects.mode} (${envelope.engines.architects.storageRoot || 'n/a'})`,
+                                    `Primary client: ${envelope.clients.primaryClientId || 'none'}`,
+                                ]),
+                                formatJsonDetails('Structured details', envelope),
+                            ].join('\n\n'),
+                        }],
+                };
+            }
+            case 'nexus_doctor': {
+                const envelope = this.nexusRef.getRuntimeHealthEnvelope();
+                const bootstrap = this.getRuntime().getUsageSnapshot()?.bootstrapManifestStatus;
+                const issues = [
+                    ...envelope.degradedReasons,
+                    ...(bootstrap?.clients ?? [])
+                        .filter((client) => client.state !== 'installed')
+                        .map((client) => `${client.label}: ${client.summary}`),
+                ];
+                return {
+                    content: [{
+                            type: 'text',
+                            text: [
+                                `Runtime doctor ${issues.length ? 'found issues' : 'reports nominal state'}.`,
+                                formatBullets([
+                                    `Status: ${envelope.status}`,
+                                    `Workspace source: ${envelope.workspace.source}`,
+                                    `Issues: ${issues.length}`,
+                                    `Synapse storage: ${envelope.engines.synapse.requestedStorageRoot || 'n/a'} -> ${envelope.engines.synapse.storageRoot || 'n/a'}`,
+                                    `Architects storage: ${envelope.engines.architects.requestedStorageRoot || 'n/a'} -> ${envelope.engines.architects.storageRoot || 'n/a'}`,
+                                ]),
+                                formatJsonDetails('Structured details', {
+                                    envelope,
+                                    issues,
+                                    remediation: [
+                                        'Refresh workspace bootstrap artifacts with nexus_autofix or nexus-prime bootstrap runtime.',
+                                        'Inspect runtime health storage paths if Synapse or Architects are degraded.',
+                                        'Keep bootstrap/orchestrate as the first MCP sequence before manual tool use.',
+                                    ],
+                                }),
+                            ].join('\n\n'),
+                        }],
+                };
+            }
+            case 'nexus_autofix': {
+                const manifest = ensureBootstrap({
+                    packageRoot: PROJECT_ROOT,
+                    workspaceRoot: this.nexusRef.getWorkspaceContext().workspaceRoot,
+                    phase: 'runtime',
+                    silent: true,
+                });
+                const memoryMaintenance = this.nexusRef.maintainMemory();
+                this.getRuntime().recordBootstrapManifestStatus?.(manifest);
+                const envelope = this.nexusRef.getRuntimeHealthEnvelope();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: [
+                                'Autofix completed.',
+                                formatBullets([
+                                    `Bootstrap clients tracked: ${manifest.clients.length}`,
+                                    `Memory expired: ${Number(memoryMaintenance?.expired || 0)}`,
+                                    `Memory quarantined: ${Number(memoryMaintenance?.quarantined || 0)}`,
+                                    `Runtime status: ${envelope.status}`,
+                                ]),
+                                formatJsonDetails('Structured details', {
+                                    manifest,
+                                    memoryMaintenance,
+                                    envelope,
+                                }),
+                            ].join('\n\n'),
+                        }],
+                };
+            }
+            case 'nexus_memory_hygiene': {
+                const limit = Number(request.params.arguments?.limit ?? 80);
+                const apply = Boolean(request.params.arguments?.apply);
+                const maintenance = apply ? this.nexusRef.maintainMemory() : null;
+                const audit = this.getRuntime().auditMemory(limit) ?? { scanned: 0, quarantined: [], findings: [] };
+                const health = this.getRuntime().getMemoryHealth();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: [
+                                'Memory hygiene report ready.',
+                                formatBullets([
+                                    `Scanned: ${Number(audit.scanned || 0)}`,
+                                    `Quarantined: ${Number(audit.quarantined?.length || 0)}`,
+                                    `Promoted: ${Number(health.promoted || 0)}`,
+                                    `Shared: ${Number(health.shared || 0)}`,
+                                ]),
+                                formatJsonDetails('Structured details', {
+                                    applied: apply,
+                                    maintenance,
+                                    audit,
+                                    health,
+                                }),
+                            ].join('\n\n'),
+                        }],
+                };
+            }
+            case 'nexus_selection_ledger': {
+                const usage = this.getRuntime().getUsageSnapshot();
+                const payload = {
+                    selectionAudit: usage?.artifactSelectionAudit ?? { selected: [], rejected: [], summary: 'No selection audit recorded yet.' },
+                    executionLedger: usage?.executionLedger ?? null,
+                    instructionPacket: usage?.instructionPacket ?? null,
+                };
+                return {
+                    content: [{
+                            type: 'text',
+                            text: [
+                                'Selection ledger ready.',
+                                formatBullets([
+                                    `Selected assets: ${payload.selectionAudit.selected?.length || 0}`,
+                                    `Rejected assets: ${payload.selectionAudit.rejected?.length || 0}`,
+                                    `Ledger present: ${payload.executionLedger ? 'yes' : 'no'}`,
+                                ]),
+                                formatJsonDetails('Structured details', payload),
+                            ].join('\n\n'),
+                        }],
+                };
+            }
             case 'nexus_describe_tool': {
                 const requestedTool = String(request.params.arguments?.tool_name ?? '');
                 if (!requestedTool) {