nexus-prime 7.7.1 → 7.8.0

package/dist/cli.js

@@ -30,6 +30,7 @@ import { runHookBootstrap, runHookMemory, runHookMindkit, runHookGhostPass, runH
 import { resolveWorkspaceContext } from './engines/workspace-resolver.js';
 import { ensureDaemonReady, getDaemonStatus, stopDaemon } from './daemon/client.js';
 import { NexusDaemonServer } from './daemon/server.js';
+import { DaemonSupervisor } from './daemon/supervisor.js';
 import { startDaemonBackedMcpProxy } from './daemon/proxy.js';
 import { getSharedLicenseManager, snapshotPCU, formatPCUStatus, loginFromCLI, isLoggedIn, logout, readAuthInfo } from './licensing/index.js';
 import { syncLicense, requestUpgrade } from './licensing/license-sync.js';
@@ -806,6 +807,14 @@ program
         process.exit(1);
     }
     console.error(`Nexus Prime daemon started (pid ${record.pid}, ${formatDaemonAddress(record)})`);
+    // Liveness supervisor: pings /health every 30s; restarts the daemon if
+    // 3 consecutive timeouts. Opt out with NEXUS_SUPERVISOR_DISABLED=1.
+    const supervisor = new DaemonSupervisor({
+        daemon,
+        workspaceContext,
+        getLockRecord: () => daemon.getLockRecord(),
+    });
+    supervisor.start();
 }));
 program
     .command('mcp')

package/dist/daemon/server.d.ts

@@ -15,6 +15,12 @@ export declare class NexusDaemonServer {
     private stopping;
     constructor(workspace: WorkspaceContext);
     private installProcessErrorHandlers;
+    /**
+     * Live read of the lock record (port + token) so supervisors and other
+     * callers can re-fetch credentials after a stop()/start() cycle without
+     * holding stale references.
+     */
+    getLockRecord(): DaemonLockRecord | null;
     start(): Promise<{
         started: boolean;
         record: DaemonLockRecord;

package/dist/daemon/server.js

@@ -148,7 +148,18 @@ export class NexusDaemonServer {
             catch { /* last-resort logging — swallow */ }
         });
     }
+    /**
+     * Live read of the lock record (port + token) so supervisors and other
+     * callers can re-fetch credentials after a stop()/start() cycle without
+     * holding stale references.
+     */
+    getLockRecord() {
+        return this.lockRecord;
+    }
     async start() {
+        // Clear the stopping flag so a second start() after a supervisor-triggered
+        // stop() doesn't silently no-op via the SIGINT/SIGTERM handler guard.
+        this.stopping = false;
         const lock = acquireDaemonLock(this.workspace, {
             token: this.authToken,
         });

package/dist/daemon/supervisor.d.ts

@@ -0,0 +1,57 @@
+import { NexusDaemonServer } from './server.js';
+import type { DaemonLockRecord } from './lock.js';
+import type { WorkspaceContext } from '../engines/workspace-resolver.js';
+export interface SupervisorOptions {
+    /** The live daemon. The supervisor replaces this internally on a restart. */
+    daemon: NexusDaemonServer;
+    /** Workspace context — used to construct a fresh server on restart. */
+    workspaceContext: WorkspaceContext;
+    /** Live lock-record fetcher. Returns null when daemon hasn't yet listened. */
+    getLockRecord: () => DaemonLockRecord | null;
+    /** Override the incidents log path. Defaults to ~/.nexus-prime/incidents.jsonl. */
+    incidentsPath?: string;
+    /** Ping interval. Default 30 s. */
+    pingIntervalMs?: number;
+    /** Per-ping timeout. Default 5 s. */
+    pingTimeoutMs?: number;
+    /** Consecutive timeouts before declaring hung. Default 3. */
+    maxConsecutiveTimeouts?: number;
+}
+export interface SupervisorIncident {
+    ts: number;
+    kind: 'hung' | 'restart-ok' | 'restart-failed';
+    consecutiveTimeouts: number;
+    pid: number;
+    port: number | undefined;
+    error?: string;
+}
+export declare class DaemonSupervisor {
+    private daemon;
+    private readonly workspaceContext;
+    private readonly getLockRecord;
+    private readonly incidentsPath;
+    private readonly pingIntervalMs;
+    private readonly pingTimeoutMs;
+    private readonly maxConsecutiveTimeouts;
+    private consecutiveTimeouts;
+    private intervalHandle;
+    private restarting;
+    private stopped;
+    constructor(options: SupervisorOptions);
+    /**
+     * Schedule the first tick via setImmediate (no boot-time latency cost),
+     * then a periodic interval. Honors NEXUS_SUPERVISOR_DISABLED=1 — returns
+     * a no-op start in that case so callers don't need an outer guard.
+     */
+    start(): void;
+    /** Stop watching. Safe to call repeatedly. */
+    stop(): void;
+    /** Single health-check tick. Public for tests. */
+    tick(): Promise<void>;
+    private handleHung;
+    private appendIncident;
+    /** Test helper: read current consecutive-timeout counter. */
+    getConsecutiveTimeouts(): number;
+    /** Test helper: get the live daemon ref (changes after a restart). */
+    getDaemon(): NexusDaemonServer;
+}

package/dist/daemon/supervisor.js

@@ -0,0 +1,151 @@
+/**
+ * Daemon liveness supervisor.
+ *
+ * Watches the daemon's `/health` endpoint on a fixed interval. If three
+ * consecutive pings time out, the daemon is considered hung — supervisor
+ * stops the existing server, constructs a fresh one, and starts it.
+ *
+ * Architecture: in-process. Holds a direct reference to the live
+ * NexusDaemonServer so a restart is a `stop()` + new `NexusDaemonServer().start()`
+ * call, not a fork. Cheaper than a child-process supervisor and avoids PID
+ * race conditions with the lock file. The tradeoff: a truly deadlocked event
+ * loop won't fire setInterval callbacks at all — but a deadlocked Node would
+ * also fail any out-of-process probe. The intended fail mode is "hung HTTP
+ * handler", which this catches.
+ *
+ * Opt out with `NEXUS_SUPERVISOR_DISABLED=1`.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { NexusDaemonServer } from './server.js';
+import { pingDaemonHealth } from './client.js';
+const DEFAULT_PING_INTERVAL_MS = 30_000;
+const DEFAULT_PING_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_TIMEOUTS = 3;
+export class DaemonSupervisor {
+    daemon;
+    workspaceContext;
+    getLockRecord;
+    incidentsPath;
+    pingIntervalMs;
+    pingTimeoutMs;
+    maxConsecutiveTimeouts;
+    consecutiveTimeouts = 0;
+    intervalHandle;
+    restarting = false;
+    stopped = false;
+    constructor(options) {
+        this.daemon = options.daemon;
+        this.workspaceContext = options.workspaceContext;
+        this.getLockRecord = options.getLockRecord;
+        this.incidentsPath = options.incidentsPath
+            ?? path.join(os.homedir(), '.nexus-prime', 'incidents.jsonl');
+        this.pingIntervalMs = options.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+        this.pingTimeoutMs = options.pingTimeoutMs ?? DEFAULT_PING_TIMEOUT_MS;
+        this.maxConsecutiveTimeouts = options.maxConsecutiveTimeouts ?? DEFAULT_MAX_TIMEOUTS;
+    }
+    /**
+     * Schedule the first tick via setImmediate (no boot-time latency cost),
+     * then a periodic interval. Honors NEXUS_SUPERVISOR_DISABLED=1 — returns
+     * a no-op start in that case so callers don't need an outer guard.
+     */
+    start() {
+        if (process.env.NEXUS_SUPERVISOR_DISABLED === '1') {
+            return;
+        }
+        if (this.intervalHandle)
+            return;
+        // Defer so daemon.start() can finish listening before we ping.
+        setImmediate(() => {
+            if (this.stopped)
+                return;
+            void this.tick();
+        });
+        this.intervalHandle = setInterval(() => { void this.tick(); }, this.pingIntervalMs);
+        this.intervalHandle.unref();
+    }
+    /** Stop watching. Safe to call repeatedly. */
+    stop() {
+        this.stopped = true;
+        if (this.intervalHandle) {
+            clearInterval(this.intervalHandle);
+            this.intervalHandle = undefined;
+        }
+    }
+    /** Single health-check tick. Public for tests. */
+    async tick() {
+        if (this.stopped || this.restarting)
+            return;
+        const record = this.getLockRecord();
+        if (!record)
+            return; // daemon not yet listening — skip silently
+        try {
+            await pingDaemonHealth(record, this.pingTimeoutMs);
+            this.consecutiveTimeouts = 0;
+        }
+        catch (err) {
+            this.consecutiveTimeouts += 1;
+            if (this.consecutiveTimeouts >= this.maxConsecutiveTimeouts) {
+                await this.handleHung(err);
+            }
+        }
+    }
+    async handleHung(error) {
+        if (this.restarting)
+            return;
+        this.restarting = true;
+        const record = this.getLockRecord();
+        const errMsg = error instanceof Error ? error.message : String(error);
+        this.appendIncident({
+            ts: Date.now(),
+            kind: 'hung',
+            consecutiveTimeouts: this.consecutiveTimeouts,
+            pid: process.pid,
+            port: record?.port,
+            error: errMsg,
+        });
+        try {
+            await this.daemon.stop('supervisor-restart');
+            const fresh = new NexusDaemonServer(this.workspaceContext);
+            await fresh.start();
+            this.daemon = fresh;
+            this.consecutiveTimeouts = 0;
+            this.appendIncident({
+                ts: Date.now(),
+                kind: 'restart-ok',
+                consecutiveTimeouts: 0,
+                pid: process.pid,
+                port: this.daemon.getLockRecord()?.port,
+            });
+        }
+        catch (restartErr) {
+            this.appendIncident({
+                ts: Date.now(),
+                kind: 'restart-failed',
+                consecutiveTimeouts: this.consecutiveTimeouts,
+                pid: process.pid,
+                port: record?.port,
+                error: restartErr instanceof Error ? restartErr.message : String(restartErr),
+            });
+        }
+        finally {
+            this.restarting = false;
+        }
+    }
+    appendIncident(incident) {
+        try {
+            fs.mkdirSync(path.dirname(this.incidentsPath), { recursive: true });
+            fs.appendFileSync(this.incidentsPath, JSON.stringify(incident) + '\n', 'utf8');
+        }
+        catch { /* incident log is best-effort */ }
+    }
+    /** Test helper: read current consecutive-timeout counter. */
+    getConsecutiveTimeouts() {
+        return this.consecutiveTimeouts;
+    }
+    /** Test helper: get the live daemon ref (changes after a restart). */
+    getDaemon() {
+        return this.daemon;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-prime",
-  "version": "7.7.1",
+  "version": "7.8.0",
   "description": "Local-first MCP control plane for coding agents with bootstrap-orchestrate execution, memory fabric, token budgeting, and worktree-backed swarms",
   "type": "module",
   "main": "dist/index.js",