nexus-prime 7.1.1 → 7.3.0

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

@@ -293,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\`\`\``
                                 : '',
-                            detailLevel === 'debug' ? formatJsonDetails('Structured details', payload) : '',
+                            formatJsonDetails('Structured details', payload),
                             hctx.formatProtocolChecklist(),
                         ].filter(Boolean).join('\n\n'),
                     }],
@@ -499,6 +499,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                                     `Verification: ${verifiedWorkers}/${execution.workerResults.length} worker(s) verified`,
                                     `Tokens: saved ${Number(execution.tokenTelemetry?.savedTokens || 0).toLocaleString()} · compression ${Number(execution.tokenTelemetry?.compressionPct || 0)}%`,
                                     autoTokenApplyNote || null,
+                                    `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`,
@@ -512,7 +513,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\`\`\``,
-                                detailLevel === 'debug' ? formatJsonDetails('Structured details', payload) : '',
+                                formatJsonDetails('Structured details', payload),
                                 hctx.formatRemainingProtocolSteps(),
                             ].filter(Boolean).join('\n\n'),
                         }],

package/dist/architects/config.js

@@ -7,9 +7,14 @@ function parseInteger(value, fallback) {
     const parsed = Number.parseInt(value ?? '', 10);
     return Number.isFinite(parsed) ? parsed : fallback;
 }
+function clampInteger(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, Math.floor(value)));
+}
 export const ArchitectsConfig = {
     enabled: parseBoolean(process.env.ARCHITECTS_ENABLED, true),
-    maxConcurrent: parseInteger(process.env.ARCHITECTS_MAX_CONCURRENT, -1),
+    maxConcurrent: clampInteger(parseInteger(process.env.ARCHITECTS_MAX_CONCURRENT, 2), 1, 4),
     sentinelPatrolMs: parseInteger(process.env.ARCHITECTS_SENTINEL_PATROL_MS, 120_000),
     wardPatrolMs: parseInteger(process.env.ARCHITECTS_WARD_PATROL_MS, 180_000),
     convergenceStrategy: (process.env.ARCHITECTS_CONVERGENCE_STRATEGY || 'bisecting'),

package/dist/cli/cleanup.js

@@ -1,22 +1,15 @@
 /**
  * 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.
+ * This never touches durable memory. It enforces aggressive defaults because
+ * transient Nexus state must never surprise users with 10GB+ growth. Heavy
+ * artifacts can still be retained by raising env budgets explicitly.
  */
+import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { formatBytes, sweepDirectory, sweepOrphanWorktrees, } from '../install/fs-purge.js';
-import { getNexusStateDir, getWorktreeRoots, getRuntimeTmpRoots, } from '../install/state-locator.js';
+import { getNexusStateDir, getWorktreeRoots, getRuntimeTmpRoots, NEXUS_TMP_GLOB_PREFIXES, } from '../install/state-locator.js';
 function parseIntEnv(name, fallback) {
     const raw = process.env[name];
     const parsed = Number.parseInt(raw ?? '', 10);
@@ -24,18 +17,42 @@ function parseIntEnv(name, 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),
+        ttlMs: parseIntEnv('NEXUS_WORKTREE_TTL_MS', 60 * 60 * 1000),
+        maxCount: parseIntEnv('NEXUS_WORKTREE_MAX_COUNT', 8),
+        maxBytes: parseIntEnv('NEXUS_WORKTREE_MAX_BYTES', 512 * 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),
+        ttlMs: parseIntEnv('NEXUS_RUNS_TTL_MS', 30 * 60 * 1000),
+        maxCount: parseIntEnv('NEXUS_RUNS_MAX_COUNT', 16),
+        maxBytes: parseIntEnv('NEXUS_RUNS_MAX_BYTES', 256 * 1024 * 1024),
     };
 }
+function collectLegacyTmpRoots() {
+    const tmpRoot = os.tmpdir();
+    let entries = [];
+    try {
+        entries = fs.readdirSync(tmpRoot);
+    }
+    catch {
+        return [];
+    }
+    const roots = new Set();
+    for (const entry of entries) {
+        if (!NEXUS_TMP_GLOB_PREFIXES.some((prefix) => entry.startsWith(prefix)))
+            continue;
+        const fullPath = path.join(tmpRoot, entry);
+        try {
+            if (fs.statSync(fullPath).isDirectory())
+                roots.add(fullPath);
+        }
+        catch {
+            // ignore races with concurrently removed tmp dirs
+        }
+    }
+    return [...roots].sort();
+}
 export async function runCleanup(options) {
     const dryRun = options.dryRun || !options.fix;
     const repoRoot = options.repoRoot ?? process.cwd();
@@ -51,7 +68,6 @@ export async function runCleanup(options) {
     };
     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,
@@ -65,6 +81,7 @@ export async function runCleanup(options) {
         report.totalEntriesRemoved += sweep.removed.length;
         if (sweep.entriesBefore > 0 || sweep.removed.length > 0) {
             console.log(`  worktree: ${root}`);
+            console.log(`    budget: ttl=${Math.round(worktreeBudget.ttlMs / 60000)}m, max=${worktreeBudget.maxCount}, bytes=${formatBytes(worktreeBudget.maxBytes)}`);
             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) {
@@ -72,8 +89,12 @@ export async function runCleanup(options) {
             }
         }
     }
-    // Runs roots
-    for (const root of [path.join(getNexusStateDir(), 'runs'), ...getRuntimeTmpRoots()]) {
+    const runsRoots = new Set([
+        path.join(getNexusStateDir(), 'runs'),
+        ...getRuntimeTmpRoots(),
+        ...collectLegacyTmpRoots(),
+    ]);
+    for (const root of runsRoots) {
         const sweep = sweepDirectory(root, {
             maxAgeMs: runsBudget.ttlMs,
             maxCount: runsBudget.maxCount,
@@ -86,11 +107,11 @@ export async function runCleanup(options) {
         report.totalEntriesRemoved += sweep.removed.length;
         if (sweep.entriesBefore > 0 || sweep.removed.length > 0) {
             console.log(`  runs: ${root}`);
+            console.log(`    budget: ttl=${Math.round(runsBudget.ttlMs / 60000)}m, max=${runsBudget.maxCount}, bytes=${formatBytes(runsBudget.maxBytes)}`);
             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);

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

@@ -1,4 +1,15 @@
 import type { StateScope } from '../install/state-locator.js';
+import type { LicenseStatus } from '../licensing/types.js';
+export interface NgramFootprint {
+    dbPath: string;
+    dbBytes: number;
+    walBytes: number;
+    shmBytes: number;
+    totalBytes: number;
+    walLimitBytes: number;
+    footprintLimitBytes: number;
+    archives: number;
+}
 export interface DoctorReport {
     stateDir: string;
     totals: Record<StateScope, number>;
@@ -15,5 +26,13 @@ export interface DoctorReport {
         limit: number;
     }>;
     suggestCleanup: boolean;
+    /** Install manifest's recorded architecture generation, if present. */
+    installArchGeneration?: string;
+    /** Architecture generation built into this binary. */
+    currentArchGeneration: string;
+    /** ngram-index footprint snapshot for the canonical state-dir DB. */
+    ngram: NgramFootprint;
+    /** Active license status. */
+    license: Pick<LicenseStatus, 'tier' | 'valid' | 'expiresAt' | 'trial' | 'degradedReason'>;
 }
 export declare function runDoctorStorage(): DoctorReport;

package/dist/cli/doctor-storage.js

@@ -2,13 +2,29 @@
  * nexus doctor storage — read-only disk usage report.
  *
  * Shows scope-by-scope bytes under the state dir + tmp prefixes, flags any
- * scope that exceeds the corresponding cleanup budget, and prints a single
- * remediation hint (`nexus cleanup --fix`) when needed.
+ * scope that exceeds the corresponding cleanup budget, surfaces the install
+ * architecture generation + ngram WAL footprint + license status, and prints
+ * a single remediation hint (`nexus cleanup --fix`) when needed.
  */
 import * as fs from 'fs';
+import * as path from 'path';
 import { resolveRunsBudget, resolveWorktreeBudget } from './cleanup.js';
 import { dirBytes, formatBytes } from '../install/fs-purge.js';
-import { enumerateStatePaths, getNexusStateDir, getRuntimeTmpRoots, getWorktreeRoots, } from '../install/state-locator.js';
+import { enumerateNgramArchives, enumerateStatePaths, getNexusStateDir, getRuntimeTmpRoots, getWorktreeRoots, } from '../install/state-locator.js';
+import { INSTALL_ARCH_GENERATION, loadManifest, } from '../install/manifest.js';
+import { getNgramFootprintBytes } from '../engines/ngram-index.js';
+import { getSharedLicenseManager } from '../licensing/license-manager.js';
+const NGRAM_DEFAULT_WAL_LIMIT_BYTES = 64 * 1024 * 1024;
+const NGRAM_DEFAULT_FOOTPRINT_BYTES = 512 * 1024 * 1024;
+function readEnvBytesPositive(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return Math.floor(parsed);
+}
 export function runDoctorStorage() {
     const stateDir = getNexusStateDir();
     const entries = [];
@@ -47,14 +63,67 @@ export function runDoctorStorage() {
     if (totals.runtime > runsBudget.maxBytes) {
         flags.push({ scope: 'runtime', reason: 'bytes-over-limit', actual: totals.runtime, limit: runsBudget.maxBytes });
     }
+    const ngramDbPath = path.join(stateDir, 'ngram-index.db');
+    const walLimitBytes = readEnvBytesPositive('NEXUS_NGRAM_WAL_LIMIT_BYTES', NGRAM_DEFAULT_WAL_LIMIT_BYTES);
+    const footprintLimitBytes = readEnvBytesPositive('NEXUS_NGRAM_MAX_FOOTPRINT_BYTES', NGRAM_DEFAULT_FOOTPRINT_BYTES);
+    const safeStat = (p) => {
+        try {
+            return fs.existsSync(p) ? fs.statSync(p).size : 0;
+        }
+        catch {
+            return 0;
+        }
+    };
+    const ngram = {
+        dbPath: ngramDbPath,
+        dbBytes: safeStat(ngramDbPath),
+        walBytes: safeStat(`${ngramDbPath}-wal`),
+        shmBytes: safeStat(`${ngramDbPath}-shm`),
+        totalBytes: getNgramFootprintBytes(ngramDbPath),
+        walLimitBytes,
+        footprintLimitBytes,
+        archives: enumerateNgramArchives(stateDir).length,
+    };
+    if (ngram.walBytes > walLimitBytes) {
+        flags.push({ scope: 'db', reason: 'ngram-wal-over-limit', actual: ngram.walBytes, limit: walLimitBytes });
+    }
+    if (ngram.totalBytes > footprintLimitBytes) {
+        flags.push({ scope: 'db', reason: 'ngram-footprint-over-limit', actual: ngram.totalBytes, limit: footprintLimitBytes });
+    }
+    const manifest = loadManifest();
+    const license = (() => {
+        try {
+            const status = getSharedLicenseManager().getStatus();
+            return {
+                tier: status.tier,
+                valid: status.valid,
+                expiresAt: status.expiresAt,
+                trial: status.trial,
+                degradedReason: status.degradedReason,
+            };
+        }
+        catch {
+            return { tier: 'free', valid: false, expiresAt: null, trial: false, degradedReason: 'malformed' };
+        }
+    })();
     const report = {
         stateDir,
         totals,
         entries,
         flags,
         suggestCleanup: flags.length > 0,
+        installArchGeneration: manifest.architectureGeneration,
+        currentArchGeneration: INSTALL_ARCH_GENERATION,
+        ngram,
+        license,
     };
     console.log(`\n[doctor:storage] state dir: ${stateDir}`);
+    console.log(`  install arch  ${report.installArchGeneration ?? '(unstamped)'} → current ${report.currentArchGeneration}`);
+    const trialNote = license.trial && license.expiresAt
+        ? ` (trial, ${Math.max(0, Math.ceil((license.expiresAt - Date.now()) / (24 * 60 * 60 * 1000)))}d left)`
+        : '';
+    console.log(`  license       tier=${license.tier} valid=${license.valid}${trialNote}${license.degradedReason ? ` reason=${license.degradedReason}` : ''}`);
+    console.log(`  ngram db      db=${formatBytes(ngram.dbBytes)} wal=${formatBytes(ngram.walBytes)} shm=${formatBytes(ngram.shmBytes)} total=${formatBytes(ngram.totalBytes)} (cap=${formatBytes(footprintLimitBytes)})  archives=${ngram.archives}`);
     for (const [scope, bytes] of Object.entries(totals)) {
         console.log(`  ${scope.padEnd(10)} ${formatBytes(bytes)}`);
     }

package/dist/cli/install-wizard.d.ts

@@ -4,6 +4,7 @@
  * Invoked via: nexus-prime setup
  */
 import { type IDEId } from '../agents/adapters/ide-compat.js';
+import { INSTALL_ARCH_GENERATION } from '../install/manifest.js';
 export interface WizardOptions {
     /** Target workspace root (defaults to cwd) */
     workspaceRoot?: string;
@@ -36,6 +37,20 @@ export declare function configureIDE(ide: IDEId, opts?: WizardOptions): Promise<
     configPath: string | null;
     writtenHash: string | null;
 }>;
+/** Architecture-generation migration step. Idempotent and best-effort: when
+ *  the install manifest predates INSTALL_ARCH_GENERATION (or carries an older
+ *  one), we drop stale generated artefacts that the current generation no
+ *  longer owns. The manifest's path/registration entries are preserved so
+ *  uninstall can still reverse them. */
+export interface ArchUpgradeResult {
+    previousGeneration?: string;
+    currentGeneration: typeof INSTALL_ARCH_GENERATION;
+    migrated: boolean;
+    ngramArchivesPruned: number;
+}
+export declare function runArchitectureUpgrade(opts?: {
+    dryRun?: boolean;
+}): ArchUpgradeResult;
 /** Run the install wizard: detect IDEs and write MCP configs. */
 export declare function runInstallWizard(opts?: WizardOptions): Promise<WizardResult>;
 /** Print how to add nexus-prime manually to an MCP client. */

package/dist/cli/install-wizard.js

@@ -4,7 +4,7 @@
  * Invoked via: nexus-prime setup
  */
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
@@ -15,7 +15,8 @@ import { resolveNexusStateDir } from '../engines/runtime-registry.js';
 import { resolveWorkspaceContext } from '../engines/workspace-resolver.js';
 import { runPostinstallCleanup } from '../postinstall/cleanup.js';
 import { openBrowser, printHandoffBanner, withSpinner } from './interactive-setup.js';
-import { appendToManifest, recordPath, recordRegistration, recordSetupMarker } from '../install/manifest.js';
+import { appendToManifest, detectArchitectureUpgrade, loadManifest, recordArchitectureGeneration, recordPath, recordRegistration, recordSetupMarker, INSTALL_ARCH_GENERATION, } from '../install/manifest.js';
+import { enumerateNgramArchives } from '../install/state-locator.js';
 /** Compute sha256 of a file's content. Returns null if the file cannot be read. */
 export function computeFileHash(filePath) {
     try {
@@ -255,6 +256,45 @@ function _writeWorkspaceLocalConfigs(callerIde, workspaceRoot) {
         }
     }
 }
+export function runArchitectureUpgrade(opts = {}) {
+    const manifest = loadManifest();
+    const detection = detectArchitectureUpgrade(manifest);
+    if (!detection.requiresMigration) {
+        if (manifest.architectureGeneration !== INSTALL_ARCH_GENERATION && !opts.dryRun) {
+            // Fresh install or no recorded entries — just stamp the marker.
+            appendToManifest((m) => recordArchitectureGeneration(m));
+        }
+        return {
+            previousGeneration: detection.previousGeneration,
+            currentGeneration: detection.currentGeneration,
+            migrated: false,
+            ngramArchivesPruned: 0,
+        };
+    }
+    let ngramArchivesPruned = 0;
+    if (!opts.dryRun) {
+        // Stale ngram archives from prior generations: keep nothing — the new
+        // rotation path archives at most one and uses footprint accounting.
+        try {
+            const archives = enumerateNgramArchives();
+            for (const archive of archives) {
+                try {
+                    rmSync(archive.path, { force: true });
+                    ngramArchivesPruned += 1;
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        catch { /* best-effort */ }
+        appendToManifest((m) => recordArchitectureGeneration(m));
+    }
+    return {
+        previousGeneration: detection.previousGeneration,
+        currentGeneration: detection.currentGeneration,
+        migrated: true,
+        ngramArchivesPruned,
+    };
+}
 /** Run the install wizard: detect IDEs and write MCP configs. */
 export async function runInstallWizard(opts = {}) {
     const workspaceRoot = resolve(opts.workspaceRoot ?? process.cwd());
@@ -263,6 +303,10 @@ export async function runInstallWizard(opts = {}) {
     const setupMarker = readSetupMarker();
     const log = (msg) => { if (verbose)
         process.stdout.write(msg + '\n'); };
+    const upgrade = runArchitectureUpgrade({ dryRun });
+    if (upgrade.migrated && verbose) {
+        log(`  [arch] migrated install ${upgrade.previousGeneration ?? 'legacy'} → ${upgrade.currentGeneration} (ngram archives pruned: ${upgrade.ngramArchivesPruned})`);
+    }
     const detected = detectInstalledIDEs(workspaceRoot);
     if (detected.length === 0) {
         log('  No supported IDEs detected in this workspace. Skipping MCP config setup.');

package/dist/cli/uninstall.d.ts

@@ -2,17 +2,12 @@ import { loadManifest } from '../install/manifest.js';
 import { type StopAllNexusProcessesOptions } from '../install/process-cleanup.js';
 export interface UninstallOptions {
     dryRun: boolean;
-    /** Stop daemons and unregister all known clients. Accepted for CLI clarity; uninstall already does this by default. */
     all?: boolean;
-    /** Preferred purge flag. */
     purge?: boolean;
-    /** Back-compat alias for purge. */
     purgeAll?: boolean;
     yes: boolean;
     workspaceRoot?: string;
-    /** Skip interactive prompt in tests. */
     _forceYes?: boolean;
-    /** Test-only process cleanup injection; production callers should not set this. */
     _processCleanup?: StopAllNexusProcessesOptions;
 }
 export interface UninstallReport {

package/dist/cli/uninstall.js

@@ -1,14 +1,10 @@
 /**
  * nexus uninstall — reverse every mutation Nexus Prime made to this machine.
  *
- * `--dry-run`   walks the install manifest + heuristics and prints what would
- *               happen without touching anything.
- * `--purge`     additionally removes persistent state (memory.db, synapse.db,
- *               architects.db, logs, caches, worktrees). Requires `--yes`.
- *
- * The manifest is authoritative where present. Heuristics fill the gap when
- * the manifest is missing (e.g. legacy installs). Every destructive step has
- * a dry-run preview, and leftovers are always reported.
+ * `--dry-run` walks registrations, processes, markers, and filesystem paths.
+ * Default uninstall unregisters clients, stops processes, clears markers, removes
+ * transient scratch, and clears the install manifest. `--purge` also deletes
+ * durable state such as memory, Synapse, Architects, logs, caches, and worktrees.
  */
 import * as fs from 'fs';
 import * as readline from 'readline';
@@ -73,7 +69,6 @@ export async function runUninstall(options) {
     }
     const label = dryRun ? '[dry-run]' : '[uninstall]';
     console.log(`\n${label} Nexus Prime uninstall — workspace: ${workspaceRoot}`);
-    // Step 1 — reverse IDE registrations before stopping processes so clients do not immediately respawn MCP sessions.
     const manifest = loadManifest();
     const unregisterReport = unregisterNexusRegistrations({ workspaceRoot, dryRun, manifest });
     const removedRegs = unregisterReport.reports.filter((r) => r.removed);
@@ -83,13 +78,11 @@ export async function runUninstall(options) {
     for (const r of removedRegs) {
         console.log(`      - ${r.filePath} :: ${r.jsonPath.join('.') || '(root)'}`);
     }
-    // Step 2 — stop Nexus MCP/daemon processes and remove lockfiles.
     const processReport = await stopAllNexusProcesses({ ...options._processCleanup, dryRun });
     report.daemonsKilled = processReport.daemonsKilled;
     report.lockfilesRemoved = processReport.lockfilesRemoved;
     report.errors.push(...processReport.errors);
     console.log(`  ${dryRun ? '◦' : '✓'} processes: ${report.daemonsKilled} process(es), ${report.lockfilesRemoved} lockfile(s)`);
-    // Step 3 — remove setup markers.
     const markers = new Set([setupMarkerPath, ...manifest.setupMarkers]);
     for (const marker of markers) {
         if (!fs.existsSync(marker))
@@ -107,7 +100,6 @@ export async function runUninstall(options) {
             }
         }
     }
-    // Step 4 — purge filesystem artifacts.
     const extras = manifest.paths.map((e) => ({ path: e.path, scope: e.scope }));
     let stateReport = null;
     let tmpReport = null;
@@ -116,7 +108,6 @@ export async function runUninstall(options) {
         tmpReport = purgeTmpRoots({ dryRun });
     }
     else {
-        // Default (no --purge-all): only transient tmp dirs. Persistent state stays.
         tmpReport = purgeTmpRoots({ dryRun });
     }
     const totals = [stateReport, tmpReport]
@@ -137,11 +128,9 @@ export async function runUninstall(options) {
             console.log(`      - ${op.path}  (${formatBytes(op.bytes)})`);
         }
     }
-    // Step 5 — final manifest clear, but only on full uninstall, not dry-run.
-    if (!dryRun && purgeAll) {
+    if (!dryRun) {
         clearManifest(installManifestPath);
     }
-    // Step 6 — leftover audit.
     report.leftovers = collectLeftovers(nexusStateDir);
     if (report.leftovers.length > 0) {
         console.log(`  ! leftovers (still present in state dir):`);
@@ -156,7 +145,8 @@ export async function runUninstall(options) {
     report.ok = report.errors.length === 0 && (dryRun || (purgeAll ? report.leftovers.length === 0 : true));
     console.log(`\n${label} done. ${report.ok ? 'OK' : 'completed with issues'}.`);
     if (!purgeAll && !dryRun) {
-        console.log('  Persistent state preserved. Re-run with --purge --yes to remove everything.');
+        console.log('  Persistent memory preserved. All registrations, processes, manifest, and transient scratch were removed.');
+        console.log('  Re-run with --purge --yes to delete durable memory/Synapse/Architects state too.');
     }
     return report;
 }

package/dist/dashboard/routes/health.js

@@ -1,5 +1,25 @@
+import { DASHBOARD_API_VERSION } from '../contract.js';
+import { INSTALL_ARCH_GENERATION, loadManifest } from '../../install/manifest.js';
 import { getToolHealthSummary } from '../../agents/adapters/mcp/tool-health.js';
 export const handleHealthRoutes = async (ctx, req, res, url) => {
+    if (req.method === 'GET'
+        && (url.pathname === '/api/version' || url.pathname === '/api/dashboard/version')) {
+        // Stable version endpoint so external probes (CI smoke, foreign installs
+        // sharing port 3377) can identify the running dashboard generation.
+        const manifest = (() => { try {
+            return loadManifest();
+        }
+        catch {
+            return null;
+        } })();
+        ctx.respondJson(res, {
+            dashboardApiVersion: DASHBOARD_API_VERSION,
+            architectureGeneration: INSTALL_ARCH_GENERATION,
+            installArchGeneration: manifest?.architectureGeneration ?? null,
+            product: 'nexus-prime',
+        });
+        return true;
+    }
     if (req.method === 'GET' && url.pathname === '/api/license') {
         const { getSharedLicenseManager } = await import('../../licensing/index.js');
         ctx.respondJson(res, getSharedLicenseManager().getStatus());

package/dist/engines/ngram-index.d.ts

@@ -11,6 +11,9 @@
  *
  * Persistence: SQLite (same pattern as memory.db / graph.db)
  */
+export declare function getNgramWalPath(dbPath: string): string;
+export declare function getNgramShmPath(dbPath: string): string;
+export declare function getNgramFootprintBytes(dbPath: string): number;
 export interface Posting {
     docId: string;
     locMask: number;
@@ -54,6 +57,9 @@ export declare class NgramIndex {
     private deleteStmt;
     private lookupStmt;
     private docExistsStmt;
+    private writesSinceCheckpoint;
+    private lastCheckpointAt;
+    private quotaSkipNoticeShown;
     private _searchStats;
     constructor(dbPath?: string, options?: NgramIndexOptions);
     private rotateOversizeDbIfNeeded;
@@ -64,14 +70,35 @@ export declare class NgramIndex {
     private warmHashSet;
     /** Warm the hash set after a deferred init. No-op if already warm. */
     warmHashSetDeferred(): void;
+    /** Run an opportunistic WAL checkpoint. PASSIVE first, escalate to TRUNCATE
+     *  if the WAL is still over its configured limit. Returns the WAL byte size
+     *  observed after the attempt so callers can report progress. */
+    private checkpointIfNeeded;
+    /** Footprint quota check before a write. Returns true if the write should
+     *  proceed; false if it should be skipped. Throws when NEXUS_NGRAM_STRICT_QUOTA=1
+     *  so callers can surface hard quota failures during tests/CI. */
+    private allowWrite;
     /** Index a document's text content */
     addDocument(docId: string, text: string): void;
+    /** Trigger a passive checkpoint when either the doc or time interval threshold
+     *  is hit. Cheap on a healthy DB, prevents WAL growth on bulk indexing. */
+    private maybePeriodicCheckpoint;
     /** Remove a document from the index */
     removeDocument(docId: string): void;
     /** Check if a document is already indexed */
     isIndexed(docId: string): boolean;
     /** Get count of indexed documents */
     getDocCount(): number;
+    /** Path to the underlying SQLite database file. */
+    getDbPath(): string;
+    /** Bytes occupied by the .db file alone. */
+    getDbBytes(): number;
+    /** Bytes occupied by the .db-wal file. */
+    getWalBytes(): number;
+    /** Bytes occupied by the .db-shm file. */
+    getShmBytes(): number;
+    /** Total SQLite footprint = db + wal + shm. Use this for quota checks. */
+    getSqliteFootprintBytes(): number;
     /**
      * Search for documents matching a text query.
      * Returns candidate document IDs ranked by trigram match count.
@@ -120,8 +147,9 @@ export declare class NgramIndex {
     optimizeStorage(force?: boolean): void;
     /**
      * Operator-focused maintenance for the on-disk ngram DB.
-     * - Bounds runaway DB growth via rotation (default >= 1GB)
-     * - Vacuums only when safe (<= vacuumMaxBytes) and either forced or dirty
+     * - Bounds runaway DB growth via rotation (default >= 1GB), counting the
+     *   full SQLite footprint (db + wal + shm) so a runaway WAL triggers it.
+     * - Vacuums only when safe (<= vacuumMaxBytes) and either forced or dirty.
      */
     maintainBounded(options?: {
         force?: boolean;
@@ -132,7 +160,13 @@ export declare class NgramIndex {
         uniqueTrigramCount: number;
         dbSizeBytes: number;
     };
-    /** Close the database connection */
+    /** Close the database connection.
+     *
+     *  Always truncates the WAL so the .db-wal sibling can never outgrow the
+     *  configured cap on shutdown — the failure mode that produced the 84GB
+     *  WAL on a user machine. VACUUM is only run when the operator has both a
+     *  small DB and explicitly opts in via NEXUS_NGRAM_VACUUM_ON_CLOSE=1, since
+     *  blind VACUUM on multi-GB DBs blocks shutdown indefinitely. */
     close(): void;
 }
 /** Get or create the shared NgramIndex instance */