nexus-prime 7.0.1 → 7.1.1

package/README.md

@@ -137,8 +137,6 @@ That's it. Memory, budgeting, and safe execution are already on.
 
 Prefer one-liner installs? `curl -fsSL https://nexus-prime.cfd/install.sh | bash`
 
-Your agent calls `nexus_session_bootstrap` + `nexus_orchestrate` automatically. Auto-bootstrap runs on first non-bootstrap call, so you never have to wire the packet by hand.
-
 ---
 
 ## Features
@@ -255,12 +253,6 @@ Or just wire everything: **`nexus-prime setup all`**
 
 ---
 
-## Competitive position
-
-Nexus Prime is the only control plane that remembers the repo, budgets the tokens, and ghost-passes every mutation — locally, in one process. Compare head-to-head on [nexus-prime.cfd/comparison.html](https://nexus-prime.cfd/comparison.html) or read the full docs on [nexus-prime.cfd/knowledge-base.html](https://nexus-prime.cfd/knowledge-base.html).
-
----
-
 ## What users see
 
 Numbers from real users running real workflows on their own machines:

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

@@ -2,24 +2,5 @@ export type McpToolDefinition = {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
-    /**
-     * When true, this tool is a legacy alias. Callers should migrate to
-     * `deprecatedReplacement`. The tool continues to work; a telemetry event
-     * `nexus.deprecation.used` is emitted on each call.
-     */
-    deprecated?: true;
-    /**
-     * MCP tool name or CLI command that replaces this deprecated tool.
-     * Surfaced by nexus_describe_tool.
-     */
-    deprecatedReplacement?: string;
 };
-/**
- * Tools in this set are first-class primitives — they are the canonical API
- * surface for the Nexus Prime MCP adapter. All other tools are surfaced as
- * deprecated (they continue to work but callers should migrate).
- *
- * PR4+5 W6: shrink surface from 93 tools to ~16 first-class + deprecated rest.
- */
-export declare const FIRST_CLASS_TOOLS: Set<string>;
 export declare function buildMcpToolDefinitions(): McpToolDefinition[];

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

@@ -1,39 +1,8 @@
 import { synapseToolDefinitions } from '../../../synapse/index.js';
 import { architectsToolDefinitions } from '../../../architects/index.js';
 import { getGstackBridge } from '../../../engines/gstack-bridge.js';
-/**
- * Tools in this set are first-class primitives — they are the canonical API
- * surface for the Nexus Prime MCP adapter. All other tools are surfaced as
- * deprecated (they continue to work but callers should migrate).
- *
- * PR4+5 W6: shrink surface from 93 tools to ~16 first-class + deprecated rest.
- */
-export const FIRST_CLASS_TOOLS = new Set([
-    // Session lifecycle
-    'nexus_session_bootstrap',
-    'nexus_orchestrate',
-    'nexus_session_dna',
-    // Memory
-    'nexus_store_memory',
-    'nexus_recall_memory',
-    'nexus_memory_stats',
-    // Context + governance
-    'nexus_optimize_tokens',
-    'nexus_mindkit_check',
-    'nexus_ghost_pass',
-    // Discovery
-    'nexus_describe_tool',
-    'nexus_search',
-    // Health + status
-    'nexus_runtime_health',
-    'nexus_run_status',
-    // Kernel execution primitives (bare kernel_ prefix — not nexus_)
-    'kernel_run_step',
-    'kernel_run_verify',
-    'kernel_run_merge',
-]);
 export function buildMcpToolDefinitions() {
-    const tools = [
+    return [
         // ── Memory ────────────────────────────────────────────────────────
         {
             name: 'nexus_store_memory',
@@ -1079,74 +1048,7 @@ export function buildMcpToolDefinitions() {
                 },
             },
         },
-        // ── Kernel Execution (PR 2: step / verify / merge) ───────────────
-        {
-            name: 'kernel_run_step',
-            description: 'Run a mutation step inside an isolated git worktree and record it in the kernel ledger. Returns worktreeRef, commitSha, changedFiles. Merge requires a subsequent kernel_run_verify.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    runId: { type: 'string' },
-                    stepId: { type: 'string' },
-                    task: { type: 'string' },
-                    intent: { type: 'string' },
-                    baseRef: { type: 'string', description: 'Ref/branch/sha to branch off. Defaults to HEAD.' },
-                    worktreeHintRef: { type: 'string', description: 'Optional branch label override.' },
-                    mutations: {
-                        type: 'array',
-                        items: {
-                            type: 'object',
-                            properties: {
-                                kind: { type: 'string', enum: ['write_file', 'append_file', 'delete_file', 'run_command'] },
-                                path: { type: 'string' },
-                                content: { type: 'string' },
-                                command: { type: 'string' },
-                                cwd: { type: 'string' },
-                            },
-                            required: ['kind'],
-                        },
-                    },
-                    metadata: { type: 'object' },
-                },
-                required: ['runId', 'stepId', 'task'],
-            },
-        },
-        {
-            name: 'kernel_run_verify',
-            description: 'Hash the files changed by a kernel step and optionally run registered verifiers. Records the snapshot used to detect stale-verify at merge time.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    runId: { type: 'string' },
-                    stepId: { type: 'string' },
-                    verifierIds: { type: 'array', items: { type: 'string' } },
-                    metadata: { type: 'object' },
-                },
-                required: ['runId', 'stepId'],
-            },
-        },
-        {
-            name: 'kernel_run_merge',
-            description: 'Fast-forward targetRef to a verified kernel step. Rejects when verify is missing, failed, or stale (worktree drifted after verify).',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    runId: { type: 'string' },
-                    stepId: { type: 'string' },
-                    verifyId: { type: 'string', description: 'Explicit verify pin. If omitted, latest passed verify is used.' },
-                    targetRef: { type: 'string' },
-                    reason: { type: 'string' },
-                    metadata: { type: 'object' },
-                },
-                required: ['runId', 'stepId', 'targetRef'],
-            },
-        },
         // ── Embedded capabilities (auto-detected from installed skills) ──
         ...getGstackBridge().getToolDefinitions(),
     ];
-    // Mark every non-first-class tool deprecated so agents using
-    // nexus_describe_tool can identify the canonical surface.
-    return tools.map(t => FIRST_CLASS_TOOLS.has(t.name)
-        ? t
-        : { ...t, deprecated: true, deprecatedReplacement: t.deprecatedReplacement ?? 'nexus_orchestrate' });
 }

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

@@ -14,13 +14,11 @@ import { handleRuntimeGroup } from './handlers/runtime.js';
 import { handleDiscoveryGroup } from './handlers/discovery.js';
 import { handleMiscGroup } from './handlers/misc.js';
 import { handleWorkforceGroup } from './handlers/workforce.js';
-import { handleKernelExecutionGroup } from './handlers/kernel-execution.js';
 import { nexusEventBus } from '../../../engines/event-bus.js';
 import { recordToolInvocation } from './tool-health.js';
 import { withAsyncGate } from './async-gate.js';
 import { getCircuitManager, checkBackpressure } from './circuit.js';
 import { createRun } from '../../../engines/orchestrator/store.js';
-import { FIRST_CLASS_TOOLS } from './definitions.js';
 /** Tools that may exceed the MCP client timeout (~60s). Wrap in async gate. */
 const SLOW_TOOLS = new Set([
     'nexus_orchestrate',
@@ -58,7 +56,6 @@ export async function dispatchMcpToolCall(hctx, request, args, ctx) {
             handleRuntimeGroup,
             handleDiscoveryGroup,
             handleWorkforceGroup,
-            handleKernelExecutionGroup,
             handleMiscGroup,
         ];
         for (const group of groups) {
@@ -150,9 +147,6 @@ export async function dispatchMcpToolCall(hctx, request, args, ctx) {
             circuit.recordComplete(toolName, durationMs, true);
             recordToolInvocation(toolName, durationMs, 'ok');
             nexusEventBus.emit('tool.invocation', { toolName, durationMs, status: 'ok' });
-            if (!FIRST_CLASS_TOOLS.has(toolName)) {
-                nexusEventBus.emit('nexus.deprecation.used', { toolName });
-            }
         }
         return rawResult;
     }

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

@@ -3,10 +3,10 @@
  * graph_query, hypertune_max.
  * Extracted from mcp.ts (Phase 3 split).
  */
-import { formatBullets, formatJsonDetails, getGraphEngine, getTraversalEngine, getHybridRetriever, } from '../helpers.js';
+import { formatBullets, formatJsonDetails, getTokenEngine, getGraphEngine, getTraversalEngine, getHybridRetriever, } from '../helpers.js';
 import { nexusEventBus } from '../../../../engines/event-bus.js';
-import { formatBrandedResponse } from '../../../../adapters/shared/formatters/branded-response.js';
-import { formatReadingPlan, getKernelContextService } from '../../../../kernel/index.js';
+import { formatBrandedResponse } from '../../../../engines/nexus-brand.js';
+import { formatReadingPlan } from '../../../../engines/token-supremacy.js';
 import { ContextAssembler } from '../../../../engines/context-assembler.js';
 import { pLimit } from '../../../../engines/util/p-limit.js';
 import { promises as fsPromises, statSync } from 'fs';
@@ -289,7 +289,7 @@ export async function handleGovernanceGroup(toolName, hctx, request, args, ctx)
                     return { path: resolved, sizeBytes: 0 };
                 }
             })))).filter((f) => f.sizeBytes > 0);
-            const { plan, assembly, budgetConfig } = getKernelContextService().hypertuneMax(task, files);
+            const { plan, assembly, budgetConfig } = getTokenEngine().hypertuneMax(task, files);
             const planText = formatReadingPlan(plan);
             const assemblyText = ContextAssembler.format(assembly, budgetConfig);
             const savings = plan.savings;

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

@@ -3,12 +3,12 @@
  * mindkit_check, ghost_pass, spawn_workers, session_dna, plan_execution.
  * Extracted from mcp.ts (Phase 3 split).
  */
-import { normalizeDetailLevel, normalizeBootstrapDepth, normalizeResponseIntent, normalizeResponseTopology, buildWorkspaceEnvelope, formatBullets, formatJsonDetails, getGuardrailEngine, truncateText, } from '../helpers.js';
+import { normalizeDetailLevel, normalizeBootstrapDepth, normalizeResponseIntent, normalizeResponseTopology, buildWorkspaceEnvelope, formatBullets, formatJsonDetails, getTokenEngine, getGuardrailEngine, truncateText, } from '../helpers.js';
 import { nexusEventBus } from '../../../../engines/event-bus.js';
-import { formatBrandedResponse, getRandomQuote } from '../../../../adapters/shared/formatters/branded-response.js';
+import { formatBrandedResponse, getRandomQuote } from '../../../../engines/nexus-brand.js';
 import { hasValidBootstrapReceipt } from '../../../../engines/bootstrap/index.js';
 import { resolveWorkspaceContext, resolveWorkspaceStateRoot } from '../../../../engines/workspace-resolver.js';
-import { formatReadingPlan, kernel, getKernelContextService, KernelContextService, } from '../../../../kernel/index.js';
+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';
@@ -39,9 +39,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                 try {
                     await Promise.race([
                         hctx.nexusRef.awaitReady(),
-                        new Promise((_, reject) => {
-                            AbortSignal.timeout(8000).addEventListener('abort', () => reject(new Error('nexus_startup_timeout')));
-                        }),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('nexus_startup_timeout')), 8000)),
                     ]);
                 }
                 catch {
@@ -295,7 +293,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                             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'),
                     }],
@@ -352,24 +350,13 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                             return { path: resolved, sizeBytes: 0 };
                         }
                     })));
-                    const upfrontPack = await kernel.run.compileContext({
-                        runId: `orchestrate-preflight-${Date.now()}`,
-                        host: 'mcp',
-                        model: 'unknown',
-                        task: prompt,
-                        files: fileRefs.map((f) => f.path),
-                    });
-                    const savings = upfrontPack.tokenPlan.savings ?? 0;
-                    if (savings > 0) {
-                        const totalInput = upfrontPack.tokenPlan.estimatedInputTokens;
-                        const pct = totalInput > 0
-                            ? Math.round(savings / (totalInput + savings) * 100)
+                    const upfrontPlan = await getTokenEngine().plan(prompt, fileRefs);
+                    if (upfrontPlan.savings > 0) {
+                        const pct = upfrontPlan.totalEstimatedTokens > 0
+                            ? Math.round(upfrontPlan.savings / (upfrontPlan.totalEstimatedTokens + upfrontPlan.savings) * 100)
                             : 0;
-                        const fullReads = upfrontPack.selectedFiles.filter((f) => f.mode === 'full').length;
-                        const outlines = upfrontPack.selectedFiles.filter((f) => f.mode === 'outline').length;
-                        const skipped = upfrontPack.omittedFiles.length;
-                        upfrontTokenNote = `Token plan: ${fullReads} full reads, ${outlines} outlines, ${skipped} skipped. ~${savings.toLocaleString()} tokens saved (${pct}%). `;
-                        nexusEventBus.emit('tokens.optimized', { savings, pct, source: 'orchestrate-preflight' });
+                        upfrontTokenNote = `Token plan: ${upfrontPlan.files.filter(a => a.action === 'full').length} full reads, ${upfrontPlan.files.filter(a => a.action === 'outline').length} outlines, ${upfrontPlan.files.filter(a => a.action === 'skip').length} skipped. ~${upfrontPlan.savings.toLocaleString()} tokens saved (${pct}%). `;
+                        nexusEventBus.emit('tokens.optimized', { savings: upfrontPlan.savings, pct, source: 'orchestrate-preflight' });
                     }
                 }
                 catch {
@@ -511,7 +498,6 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                                     `Crew: ${execution.plannerState?.selectedCrew?.name || 'baseline path'}`,
                                     `Verification: ${verifiedWorkers}/${execution.workerResults.length} worker(s) verified`,
                                     `Tokens: saved ${Number(execution.tokenTelemetry?.savedTokens || 0).toLocaleString()} · compression ${Number(execution.tokenTelemetry?.compressionPct || 0)}%`,
-                                    `Payload ref: ${workspace.stateKey} · ${detailLevel}`,
                                     autoTokenApplyNote || null,
                                     ...(detailLevel === 'debug' ? [
                                         `Specialists: ${execution.plannerState?.selectedSpecialists.map((specialist) => specialist.name).slice(0, 4).join(', ') || 'none selected'}`,
@@ -526,7 +512,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                                     ] : []),
                                 ]),
                                 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'),
                         }],
@@ -582,23 +568,11 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                 }
             })));
             // Differential: files unchanged since last session cost 0 tokens (cross-session dedup)
-            const kernelCtx = getKernelContextService();
-            const lastSession = await kernelCtx.loadLatestSessionSummary();
-            const delta = lastSession ? kernelCtx.differential(lastSession, files) : null;
+            const engine = getTokenEngine();
+            const lastSession = await engine.loadLatestSessionSummary();
+            const delta = lastSession ? engine.differential(lastSession, files) : null;
             const planFiles = delta ? [...delta.added, ...delta.changed] : files;
-            const pack = await kernelCtx.compileContext({
-                runId: `token-${Date.now()}`,
-                host: 'mcp',
-                model: 'unknown',
-                task,
-                files: planFiles.map(f => f.path),
-            });
-            const plan = KernelContextService.extractReadingPlan(pack) ?? {
-                task,
-                files: [],
-                savings: 0,
-                totalEstimatedTokens: 0,
-            };
+            const plan = await engine.plan(task, planFiles);
             // Inject unchanged files as cached-skip entries; add their token cost to savings
             const dedupTokens = delta
                 ? delta.unchanged.reduce((sum, f) => sum + Math.ceil(f.sizeBytes / 4), 0)

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

@@ -5,6 +5,7 @@
  * These are pure functions and lazy-singleton getters shared by the
  * handler files and by MCPAdapter itself.
  */
+import { TokenSupremacyEngine } from '../../../engines/token-supremacy.js';
 import { GuardrailEngine } from '../../../engines/guardrails-bridge.js';
 import { ContinuousAttentionStream, createKVBridge, OrchestratorEngine } from '../../../engines/index.js';
 import { FederationEngine } from '../../../engines/federation.js';
@@ -13,6 +14,7 @@ import { GraphTraversalEngine } from '../../../engines/graph-traversal.js';
 import { HybridRetriever } from '../../../engines/hybrid-retriever.js';
 import type { WorkspaceContext } from '../../../engines/workspace-resolver.js';
 import type { SubAgentRuntime } from '../../../phantom/index.js';
+export declare function getTokenEngine(): TokenSupremacyEngine;
 export declare function getGuardrailEngine(): GuardrailEngine;
 export declare function getCasEngine(): ContinuousAttentionStream;
 export declare function getKvBridge(): ReturnType<typeof createKVBridge>;
@@ -23,8 +25,8 @@ export declare function getHybridRetriever(): HybridRetriever;
 export declare function getFallbackRuntime(workspace: WorkspaceContext): SubAgentRuntime;
 export declare function getFallbackOrchestrator(workspace: WorkspaceContext): OrchestratorEngine;
 import type { ResponseDetailLevel, ResponseIntent, ResponseTopology } from './types.js';
-export { formatBullets } from '../../../adapters/shared/formatters/bullets.js';
-export { formatJsonDetails } from '../../../adapters/shared/formatters/json-details.js';
+export declare function formatBullets(lines: Array<string | null | undefined>): string;
+export declare function formatJsonDetails(label: string, value: unknown): string;
 export declare function normalizeDetailLevel(value: unknown): ResponseDetailLevel;
 export declare function normalizeBootstrapDepth(value: unknown, detailLevel: ResponseDetailLevel): 'fast' | 'deep';
 export declare function normalizeResponseIntent(value: unknown): ResponseIntent;

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

@@ -7,6 +7,7 @@
  */
 import { statSync, readdirSync } from 'fs';
 import * as path from 'path';
+import { TokenSupremacyEngine } from '../../../engines/token-supremacy.js';
 import { GuardrailEngine } from '../../../engines/guardrails-bridge.js';
 import { ContinuousAttentionStream, createKVBridge, OrchestratorEngine, } from '../../../engines/index.js';
 import { FederationEngine } from '../../../engines/federation.js';
@@ -15,6 +16,7 @@ import { GraphTraversalEngine } from '../../../engines/graph-traversal.js';
 import { HybridRetriever } from '../../../engines/hybrid-retriever.js';
 import { createSubAgentRuntime } from '../../../phantom/index.js';
 // ─── Lazy-init engine singletons ─────────────────────────────────────────────
+let _tokenEngine;
 let _guardrailEngine;
 let _casEngine;
 let _kvBridge;
@@ -22,6 +24,11 @@ let _federation;
 let _graphEngine = null;
 let _traversalEngine = null;
 let _hybridRetriever = null;
+export function getTokenEngine() {
+    if (!_tokenEngine)
+        _tokenEngine = new TokenSupremacyEngine();
+    return _tokenEngine;
+}
 export function getGuardrailEngine() {
     if (!_guardrailEngine)
         _guardrailEngine = new GuardrailEngine();
@@ -82,10 +89,12 @@ export function getFallbackOrchestrator(workspace) {
     }
     return instance;
 }
-// PR4+5: formatters moved to src/adapters/shared/formatters. Re-exported here
-// so existing handler imports keep working while the adapter migration lands.
-export { formatBullets } from '../../../adapters/shared/formatters/bullets.js';
-export { formatJsonDetails } from '../../../adapters/shared/formatters/json-details.js';
+export function formatBullets(lines) {
+    return lines.filter(Boolean).map((line) => `- ${line}`).join('\n');
+}
+export function formatJsonDetails(label, value) {
+    return `\n\n${label}\n\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
+}
 export function normalizeDetailLevel(value) {
     const normalized = String(value ?? 'compact').toLowerCase();
     if (normalized === 'standard' || normalized === 'debug')

package/dist/architects/bootstrap.d.ts

@@ -3,6 +3,12 @@ interface InitArchitectsOptions {
     repoRoot: string;
     requestedStorageRoot?: string;
     storageRoot?: string;
+    /**
+     * When true, bypass the opt-in `ArchitectsConfig.enabled` gate. Used by the
+     * lazy-init path so the first explicit Architects tool call is itself the
+     * opt-in that causes the DB to be created.
+     */
+    forceEnable?: boolean;
 }
 export declare function initArchitects(options: InitArchitectsOptions): ArchitectsRuntime | null;
 export {};

package/dist/architects/bootstrap.js

@@ -28,7 +28,7 @@ function parseTimestamp(value) {
     return 0;
 }
 export function initArchitects(options) {
-    if (!ArchitectsConfig.enabled)
+    if (!ArchitectsConfig.enabled && !options.forceEnable)
         return null;
     let opened;
     const requestedStorageRoot = options.requestedStorageRoot ?? options.repoRoot;

package/dist/cli/cleanup.d.ts

@@ -0,0 +1,25 @@
+import { type SweepReport } from '../install/fs-purge.js';
+export interface CleanupOptions {
+    dryRun: boolean;
+    fix: boolean;
+    repoRoot?: string;
+}
+export interface CleanupBudget {
+    ttlMs: number;
+    maxCount: number;
+    maxBytes: number;
+}
+export interface CleanupReport {
+    worktrees: SweepReport[];
+    runs: SweepReport[];
+    orphans: {
+        paths: string[];
+        bytesReclaimed: number;
+    };
+    totalBytesReclaimed: number;
+    totalEntriesRemoved: number;
+    dryRun: boolean;
+}
+export declare function resolveWorktreeBudget(): CleanupBudget;
+export declare function resolveRunsBudget(): CleanupBudget;
+export declare function runCleanup(options: CleanupOptions): Promise<CleanupReport>;

package/dist/cli/cleanup.js

@@ -0,0 +1,114 @@
+/**
+ * nexus cleanup — bound the growth of worktree + runs directories.
+ *
+ * Different from `uninstall`: this never touches persistent state. It enforces
+ * TTL / count / bytes budgets over transient scratch dirs so local disk usage
+ * can't balloon without an operator noticing.
+ *
+ * Defaults chosen to be loose enough that a busy day of work doesn't trip them:
+ *   - TTL:       12h per worktree, 6h per run
+ *   - maxCount:  32 worktrees, 64 runs
+ *   - maxBytes:  2 GiB across worktrees, 1 GiB across runs
+ *
+ * Override with env: NEXUS_WORKTREE_TTL_MS, NEXUS_WORKTREE_MAX_COUNT,
+ * NEXUS_WORKTREE_MAX_BYTES, NEXUS_RUNS_TTL_MS, NEXUS_RUNS_MAX_COUNT,
+ * NEXUS_RUNS_MAX_BYTES.
+ */
+import * as path from 'path';
+import { formatBytes, sweepDirectory, sweepOrphanWorktrees, } from '../install/fs-purge.js';
+import { getNexusStateDir, getWorktreeRoots, getRuntimeTmpRoots, } from '../install/state-locator.js';
+function parseIntEnv(name, fallback) {
+    const raw = process.env[name];
+    const parsed = Number.parseInt(raw ?? '', 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+export function resolveWorktreeBudget() {
+    return {
+        ttlMs: parseIntEnv('NEXUS_WORKTREE_TTL_MS', 12 * 60 * 60 * 1000),
+        maxCount: parseIntEnv('NEXUS_WORKTREE_MAX_COUNT', 32),
+        maxBytes: parseIntEnv('NEXUS_WORKTREE_MAX_BYTES', 2 * 1024 * 1024 * 1024),
+    };
+}
+export function resolveRunsBudget() {
+    return {
+        ttlMs: parseIntEnv('NEXUS_RUNS_TTL_MS', 6 * 60 * 60 * 1000),
+        maxCount: parseIntEnv('NEXUS_RUNS_MAX_COUNT', 64),
+        maxBytes: parseIntEnv('NEXUS_RUNS_MAX_BYTES', 1024 * 1024 * 1024),
+    };
+}
+export async function runCleanup(options) {
+    const dryRun = options.dryRun || !options.fix;
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const worktreeBudget = resolveWorktreeBudget();
+    const runsBudget = resolveRunsBudget();
+    const report = {
+        worktrees: [],
+        runs: [],
+        orphans: { paths: [], bytesReclaimed: 0 },
+        totalBytesReclaimed: 0,
+        totalEntriesRemoved: 0,
+        dryRun,
+    };
+    const label = dryRun ? '[dry-run]' : '[cleanup]';
+    console.log(`\n${label} Nexus cleanup — repo: ${repoRoot}`);
+    // Worktree roots
+    for (const root of getWorktreeRoots()) {
+        const sweep = sweepDirectory(root, {
+            maxAgeMs: worktreeBudget.ttlMs,
+            maxCount: worktreeBudget.maxCount,
+            maxBytes: worktreeBudget.maxBytes,
+            dryRun,
+            keepRoot: true,
+        });
+        report.worktrees.push(sweep);
+        report.totalBytesReclaimed += sweep.removed.reduce((s, r) => s + r.bytes, 0);
+        report.totalEntriesRemoved += sweep.removed.length;
+        if (sweep.entriesBefore > 0 || sweep.removed.length > 0) {
+            console.log(`  worktree: ${root}`);
+            console.log(`    before: ${sweep.entriesBefore} entries, ${formatBytes(sweep.totalBytesBefore)}`);
+            console.log(`    removed: ${sweep.removed.length} entries, ${formatBytes(sweep.removed.reduce((s, r) => s + r.bytes, 0))}`);
+            for (const r of sweep.removed) {
+                console.log(`      - ${r.path}  (${formatBytes(r.bytes)}, reason=${r.reason})`);
+            }
+        }
+    }
+    // Runs roots
+    for (const root of [path.join(getNexusStateDir(), 'runs'), ...getRuntimeTmpRoots()]) {
+        const sweep = sweepDirectory(root, {
+            maxAgeMs: runsBudget.ttlMs,
+            maxCount: runsBudget.maxCount,
+            maxBytes: runsBudget.maxBytes,
+            dryRun,
+            keepRoot: true,
+        });
+        report.runs.push(sweep);
+        report.totalBytesReclaimed += sweep.removed.reduce((s, r) => s + r.bytes, 0);
+        report.totalEntriesRemoved += sweep.removed.length;
+        if (sweep.entriesBefore > 0 || sweep.removed.length > 0) {
+            console.log(`  runs: ${root}`);
+            console.log(`    before: ${sweep.entriesBefore} entries, ${formatBytes(sweep.totalBytesBefore)}`);
+            console.log(`    removed: ${sweep.removed.length} entries, ${formatBytes(sweep.removed.reduce((s, r) => s + r.bytes, 0))}`);
+        }
+    }
+    // Orphan worktrees (dir exists on disk but `git worktree list` forgot about it)
+    try {
+        const orphanReport = await sweepOrphanWorktrees(repoRoot, { dryRun });
+        report.orphans.paths = orphanReport.ops.filter((op) => op.kind !== 'missing').map((op) => op.path);
+        report.orphans.bytesReclaimed = orphanReport.totalBytesRemoved;
+        report.totalBytesReclaimed += orphanReport.totalBytesRemoved;
+        report.totalEntriesRemoved += report.orphans.paths.length;
+        if (report.orphans.paths.length > 0) {
+            console.log(`  orphans: ${report.orphans.paths.length} worktree dir(s) not tracked by git`);
+            for (const p of report.orphans.paths)
+                console.log(`      - ${p}`);
+        }
+    }
+    catch (err) {
+        console.log(`  ! orphan sweep skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    console.log(`\n${label} reclaimed ${formatBytes(report.totalBytesReclaimed)} across ${report.totalEntriesRemoved} entries.`);
+    if (dryRun) {
+        console.log('  Preview only — re-run with --fix to apply.');
+    }
+    return report;
+}

package/dist/cli/doctor-storage.d.ts

@@ -0,0 +1,19 @@
+import type { StateScope } from '../install/state-locator.js';
+export interface DoctorReport {
+    stateDir: string;
+    totals: Record<StateScope, number>;
+    entries: Array<{
+        path: string;
+        scope: StateScope;
+        bytes: number;
+        present: boolean;
+    }>;
+    flags: Array<{
+        scope: StateScope;
+        reason: string;
+        actual: number;
+        limit: number;
+    }>;
+    suggestCleanup: boolean;
+}
+export declare function runDoctorStorage(): DoctorReport;