@bharanidev/bhgraph-darwin-arm64 1.0.0

package/lib/dist/mcp/daemon-registry.js

@@ -0,0 +1,233 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRegistryDir = getRegistryDir;
+exports.isProcessAlive = isProcessAlive;
+exports.registerDaemon = registerDaemon;
+exports.deregisterDaemon = deregisterDaemon;
+exports.listDaemons = listDaemons;
+exports.stopDaemonAt = stopDaemonAt;
+exports.stopAllDaemons = stopAllDaemons;
+/**
+ * Global daemon registry + stop/list control — the discovery layer behind
+ * `bhgraph list` and `bhgraph stop [--all]`.
+ *
+ * Every per-project daemon already writes an authoritative lockfile at
+ * `<root>/.bhgraph/daemon.pid`. That's enough to stop ONE daemon you can name,
+ * but there's no central place to find them ALL — which `list` and `stop --all`
+ * need. So each daemon also drops a tiny record under `~/.bhgraph/daemons/` on
+ * start and removes it on graceful shutdown.
+ *
+ * The registry is a DISCOVERY index, never a source of truth: the live pid is.
+ * A SIGKILL'd daemon can't remove its own record, so readers prune any record
+ * whose pid is dead (`isProcessAlive`). Every write/read is best-effort — a
+ * registry hiccup must never break the daemon or a command; worst case `list`
+ * momentarily misses or over-lists one, which the next liveness prune corrects.
+ *
+ * Cross-platform by construction: only files + `process.kill(pid, signal)`,
+ * which behave consistently on macOS/Linux (real signals) and Windows (mapped to
+ * TerminateProcess). Validated live on all three.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const daemon_paths_1 = require("./daemon-paths");
+/**
+ * `~/.bhgraph/daemons` — GLOBAL, keyed off the home install dir. (The
+ * `BHGRAPH_DIR` env var only renames the per-project index dir, not this.)
+ */
+function getRegistryDir() {
+    return path.join(os.homedir(), '.bhgraph', 'daemons');
+}
+function recordPath(root) {
+    const hash = crypto.createHash('sha256').update(path.resolve(root)).digest('hex').slice(0, 16);
+    return path.join(getRegistryDir(), `${hash}.json`);
+}
+/**
+ * Is `pid` a live process? `kill(pid, 0)` sends no signal — it just probes:
+ * ESRCH ⇒ dead, EPERM ⇒ alive but not ours (still alive). Same liveness check
+ * the PPID watchdog (#277) and daemon lock arbitration use.
+ */
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Best-effort: record this daemon so `list`/`stop --all` can find it. */
+function registerDaemon(rec) {
+    try {
+        fs.mkdirSync(getRegistryDir(), { recursive: true });
+        fs.writeFileSync(recordPath(rec.root), JSON.stringify(rec, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best-effort — list's liveness prune tolerates a missing record */
+    }
+}
+/** Best-effort: drop this daemon's record on graceful shutdown. */
+function deregisterDaemon(root) {
+    try {
+        fs.unlinkSync(recordPath(root));
+    }
+    catch {
+        /* already gone */
+    }
+}
+/**
+ * All registered daemons whose process is still alive, newest first. Dead/garbage
+ * records are deleted as a side effect (self-healing) unless `prune` is false.
+ */
+function listDaemons(opts = {}) {
+    const prune = opts.prune ?? true;
+    const dir = getRegistryDir();
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return []; // no registry dir yet
+    }
+    const live = [];
+    for (const file of files) {
+        const full = path.join(dir, file);
+        let rec = null;
+        try {
+            rec = JSON.parse(fs.readFileSync(full, 'utf8'));
+        }
+        catch {
+            rec = null;
+        }
+        const valid = rec && typeof rec.pid === 'number' && typeof rec.root === 'string';
+        if (valid && isProcessAlive(rec.pid)) {
+            live.push(rec);
+        }
+        else if (prune) {
+            try {
+                fs.unlinkSync(full);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return live.sort((a, b) => b.startedAt - a.startedAt);
+}
+/** Remove a stopped daemon's leftover lockfile + socket + registry record. */
+function cleanupDaemonArtifacts(root) {
+    try {
+        fs.unlinkSync((0, daemon_paths_1.getDaemonPidPath)(root));
+    }
+    catch { /* gone */ }
+    // POSIX sockets are real files; Windows named pipes vanish with the process.
+    // Sweep every candidate — a daemon that relocated past an unusable in-project
+    // FS (ExFAT/FAT; #997) left its socket at the tmpdir fallback, not candidate 0.
+    if (process.platform !== 'win32') {
+        for (const candidate of (0, daemon_paths_1.getDaemonSocketCandidates)(root)) {
+            try {
+                fs.unlinkSync(candidate);
+            }
+            catch { /* gone */ }
+        }
+    }
+    deregisterDaemon(root);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function waitForDeath(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid))
+            return true;
+        await sleep(100);
+    }
+    return !isProcessAlive(pid);
+}
+/**
+ * Stop the daemon serving `root`: SIGTERM, wait, then SIGKILL if it won't go,
+ * then sweep its artifacts. `root` must be realpath'd (match how the daemon
+ * keys its socket/lockfile). Resolves the pid from the authoritative lockfile,
+ * falling back to the registry.
+ */
+async function stopDaemonAt(root) {
+    let pid = null;
+    try {
+        const info = (0, daemon_paths_1.decodeLockInfo)(fs.readFileSync((0, daemon_paths_1.getDaemonPidPath)(root), 'utf8'));
+        pid = info?.pid ?? null;
+    }
+    catch {
+        /* no lockfile */
+    }
+    if (pid == null) {
+        const rec = listDaemons({ prune: false }).find((r) => path.resolve(r.root) === path.resolve(root));
+        pid = rec?.pid ?? null;
+    }
+    if (pid == null) {
+        cleanupDaemonArtifacts(root);
+        return { root, pid: null, outcome: 'no-daemon' };
+    }
+    if (!isProcessAlive(pid)) {
+        cleanupDaemonArtifacts(root);
+        return { root, pid, outcome: 'not-running' };
+    }
+    // POSIX: SIGTERM runs the daemon's graceful shutdown. Windows: TerminateProcess
+    // (no graceful path), so we always sweep artifacts ourselves below.
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch { /* raced to exit */ }
+    let outcome = 'term';
+    if (!(await waitForDeath(pid, 3000))) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { /* raced to exit */ }
+        await waitForDeath(pid, 2000);
+        outcome = 'kill';
+    }
+    cleanupDaemonArtifacts(root);
+    return { root, pid, outcome };
+}
+/** Stop every registered, live daemon. */
+async function stopAllDaemons() {
+    const results = [];
+    for (const rec of listDaemons()) {
+        results.push(await stopDaemonAt(rec.root));
+    }
+    return results;
+}
+//# sourceMappingURL=daemon-registry.js.map

package/lib/dist/mcp/daemon-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-registry.js","sourceRoot":"","sources":["../../src/mcp/daemon-registry.ts"],"names":[],"mappings":"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"}

package/lib/dist/mcp/daemon.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Shared MCP daemon — issue #411.
+ *
+ * One detached `bhgraph serve --mcp` daemon process per project root,
+ * accepting N concurrent MCP clients over a Unix-domain socket (or named pipe
+ * on Windows). Each incoming connection gets its own {@link MCPSession}; all
+ * sessions share a single {@link MCPEngine}, which means a single file watcher
+ * (one inotify set), a single SQLite connection (one WAL writer), and a single
+ * tree-sitter warm-up — paid once, amortized across every agent talking to the
+ * project.
+ *
+ * Lifecycle (see also `./index.ts` and `./proxy.ts`):
+ *   - The daemon is spawned **detached** (its own session/process group, stdio
+ *     decoupled) by the first launcher that finds no daemon running. It is NOT
+ *     a child of any MCP host, so closing one terminal / Ctrl-C'ing one session
+ *     can't take it down and sever the others. That's why this process has no
+ *     PPID watchdog: it deliberately outlives every individual client.
+ *   - Every MCP host talks to the daemon through a thin `proxy` process (the
+ *     thing the host actually spawned). The proxy keeps the #277 PPID watchdog,
+ *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
+ *     close then decrements the daemon's refcount.
+ *   - When the last client disconnects the daemon lingers for
+ *     `BHGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
+ *     runs in the same project don't repay startup, then exits cleanly. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *
+ * What this file owns:
+ *   - Listening on the daemon socket and spawning per-connection sessions.
+ *   - The handshake "hello" line that lets a proxy verify it found a
+ *     same-version daemon before piping any JSON-RPC through it.
+ *   - The lockfile (`.bhgraph/daemon.pid`) competing daemons arbitrate
+ *     against — atomic `O_EXCL` create with the full record written in the same
+ *     breath (no empty-file window) + cleanup on exit.
+ *   - Reference counting + idle timeout.
+ *   - Graceful shutdown on SIGTERM/SIGINT and idle exit.
+ *
+ * What this file does NOT own:
+ *   - The proxy side (`./proxy.ts`).
+ *   - The decision of *whether* to run as daemon at all — that's `MCPServer`.
+ *   - The MCP protocol state machine — that's `./session.ts`.
+ */
+import * as net from 'net';
+import { DaemonLockInfo } from './daemon-paths';
+/**
+ * Finalize daemon shutdown. On POSIX, exit immediately — it's clean and fast.
+ * On Windows, do NOT force an exit while watchers may still be closing (that
+ * trips the libuv assertion above); instead mark success and let the loop drain
+ * to a natural exit, with an UNREF'd backstop that force-exits only if a stray
+ * handle would otherwise hang shutdown. Pure and platform-injected so both
+ * branches are unit-testable off-Windows. Returns the backstop timer (Windows)
+ * so callers/tests can clear it.
+ */
+export declare function finalizeDaemonExit(platform: NodeJS.Platform, exit: (code: number) => void): NodeJS.Timeout | null;
+/** Bytes/parse-window for an oversized hello line — bounded against a malicious peer. */
+declare const MAX_HELLO_LINE_BYTES = 4096;
+/**
+ * Wire format for the one-shot hello line the daemon emits on every new
+ * connection. Versioned with the package's own semver so a 0.9.x proxy never
+ * pipes through a 0.10.x daemon (or vice-versa) — the proxy falls back to
+ * direct mode on mismatch rather than risk subtle wire incompatibilities.
+ */
+export interface DaemonHello {
+    bhgraph: string;
+    pid: number;
+    socketPath: string;
+    protocol: 1;
+}
+/**
+ * Optional reverse-handshake line a proxy sends right after it verifies the
+ * daemon hello, carrying its own pids so the daemon can reap the client if its
+ * process dies WITHOUT the socket ever signalling close (the Windows named-pipe
+ * hazard behind #692). Entirely optional and fail-safe: a connection that never
+ * sends it (a legacy/direct client) just falls back to the socket-close
+ * lifecycle. The `bhgraph_client` marker is what tells it apart from the
+ * client's first JSON-RPC message.
+ */
+export interface DaemonClientHello {
+    bhgraph_client: 1;
+    pid: number;
+    hostPid: number | null;
+}
+export interface DaemonStartResult {
+    /** Always-non-null for a successfully-started daemon. */
+    socketPath: string;
+    /** Lockfile contents as written. */
+    lock: DaemonLockInfo;
+}
+/**
+ * Run as the shared daemon for `projectRoot`. Resolves once the socket is
+ * listening. The Daemon owns the socket, the engine, and the lockfile until
+ * `stop()` is called or it exits on idle/signal.
+ *
+ * Race-safe: callers must first call `tryAcquireDaemonLock(projectRoot)` and
+ * only construct a Daemon if they got the lock (`kind: 'acquired'`). The atomic
+ * `O_EXCL` create inside the acquire helper — which now also writes the full
+ * record before returning — is the only synchronization between competing
+ * daemons.
+ */
+export declare class Daemon {
+    private projectRoot;
+    private server;
+    private clients;
+    /** Per-client peer pids from the optional client-hello, for the liveness sweep. */
+    private clientPeers;
+    private idleTimer;
+    private idleTimeoutMs;
+    private maxIdleMs;
+    private lastActivityAt;
+    private maxIdleTimer;
+    private clientSweepTimer;
+    private engine;
+    private stopping;
+    private socketPath;
+    private pidPath;
+    constructor(projectRoot: string, opts?: {
+        idleTimeoutMs?: number;
+        maxIdleMs?: number;
+    });
+    /**
+     * Bind the socket, kick off engine init, and register signal handlers. The
+     * lockfile body was already written atomically by `tryAcquireDaemonLock`, so
+     * there is nothing to write here. The promise resolves once the server is
+     * listening — the daemon then sticks around until idle/shutdown.
+     */
+    start(): Promise<DaemonStartResult>;
+    /** Currently-connected client count. Exposed for tests / status output. */
+    getClientCount(): number;
+    /** The socket path the daemon is (or will be) listening on. */
+    getSocketPath(): string;
+    /** Graceful shutdown: close all sessions, the engine, and clean up the lock. */
+    stop(reason?: string): Promise<void>;
+    private handleConnection;
+    private dropClient;
+    private armIdleTimer;
+    private disarmIdleTimer;
+    /**
+     * Defense-in-depth against a daemon that outlives its clients (#692), for the
+     * cases the refcount + idle timer miss because a socket close never arrives:
+     *   - **Inactivity backstop:** after `maxIdleMs` with no inbound traffic, reap
+     *     the daemon — but ONLY if no connected client can be proven alive (see
+     *     {@link backstopShouldExit}). This is the sole phantom class the sweep
+     *     below can't catch: a client whose client-hello never arrived, so we have
+     *     no pid to check.
+     *   - **Liveness sweep:** drop any client whose peer process has died (per the
+     *     client-hello pids), which re-arms the idle timer once the last real
+     *     client is gone. Catches a dead peer within one sweep instead of waiting
+     *     out the whole backstop.
+     * Both timers are unref'd — the listening server keeps the loop alive, and
+     * neither should hold it open on its own.
+     */
+    private startLivenessTimers;
+    /**
+     * Decide whether the inactivity backstop should reap the daemon right now.
+     * Public + `isAlive`-injected for deterministic tests; the timer calls it each
+     * tick with the real liveness probe.
+     *
+     * The backstop exists ONLY to catch a **phantom** client (#692) — one counted
+     * but actually gone, whose socket-close was never delivered. It must never
+     * reap a **live-but-quiet** session (connected, alive peer, just not querying):
+     * doing so silently severed the shared daemon and degraded that session — and
+     * any others sharing it — to an in-process engine. `lastActivityAt` only tracks
+     * inbound query bytes, and MCP has no keepalive, so a genuinely-live session
+     * trips the raw inactivity window after ~30 min of not being queried.
+     *
+     * So: once the inactivity window elapses, drop provably-dead peers (the same
+     * check the periodic sweep runs), then reap the daemon only when NOT ONE
+     * remaining client can be proven alive — i.e. every client left is an
+     * unknown-pid connection the sweep can't verify. A single provably-alive
+     * client keeps the daemon up. Has the sweep's side effect (drops dead peers).
+     */
+    backstopShouldExit(isAlive: (pid: number) => boolean): boolean;
+    /**
+     * Drop every connected client whose peer process is gone. Returns the count
+     * reaped. `isAlive` is injected for testing. Clients with unknown pids (no
+     * client-hello) are skipped — they rely on the socket-close path.
+     */
+    reapDeadClients(isAlive: (pid: number) => boolean): number;
+    private cleanupLockfile;
+}
+/**
+ * Result of `tryAcquireDaemonLock`. Either we got the lockfile (caller becomes
+ * the daemon), or it already existed (caller should connect to the existing
+ * daemon as a proxy, or — if the holder is dead — clear it and retry).
+ */
+export type AcquireResult = {
+    kind: 'acquired';
+    pidPath: string;
+    info: DaemonLockInfo;
+} | {
+    kind: 'taken';
+    existing: DaemonLockInfo | null;
+    pidPath: string;
+};
+/**
+ * Atomically create the daemon pidfile with its full record already in place.
+ * Returns either an `acquired` result (the caller is the daemon-elect and may
+ * construct a {@link Daemon}) or a `taken` result.
+ *
+ * must-fix 1 (issue #411 review): the lockfile must appear in ONE atomic step,
+ * already complete — never empty, even momentarily. The first attempt at this
+ * (`O_EXCL` create then a separate `writeSync`) left a microsecond window where
+ * the file existed but was empty; under concurrent daemon startup a third
+ * candidate could read that empty file, decode it as `null`, and `unlink` the
+ * winner's lock → two daemons (two watchers, two writers). The window was
+ * normally too small to hit, but the file watcher's extra startup time made
+ * concurrent daemons overlap enough to reproduce it reliably.
+ *
+ * The fix writes the complete record to a private temp file, then hard-links it
+ * into place: `link()` is atomic AND exclusive (EEXIST if the target exists), so
+ * the pidfile becomes visible in one step already containing a full record.
+ * Whoever links first wins; everyone else gets EEXIST and reads a complete file.
+ * There is no empty-file window at all.
+ *
+ * Filesystems without hard links (#997): ExFAT/FAT external volumes and some
+ * network mounts can't `link()` at all — it throws ENOTSUP/EPERM, which would
+ * otherwise kill the daemon before it ever reaches the socket bind. There we
+ * fall back to an O_EXCL create (`acquireLockViaExclusiveOpen`): still exclusive
+ * ("first writer wins"), but the full record is written through the fd in a
+ * second step, so the empty-file window the link approach removed is reopened —
+ * only on these filesystems, only for the microseconds between create and write
+ * (far narrower than the original bug, which the file watcher's startup latency
+ * widened). The race's worst case is two daemons briefly; on a single external
+ * drive that's strictly better than the daemon never starting at all.
+ */
+export declare function tryAcquireDaemonLock(projectRoot: string): AcquireResult;
+/**
+ * Exclusive-create the pidfile (O_CREAT|O_EXCL via the `wx` flag) and write the
+ * full record through the same fd — the hard-link-free fallback used by
+ * {@link tryAcquireDaemonLock} on filesystems without `link()`. Returns true if
+ * we created it (acquired the lock), false on EEXIST (another candidate holds
+ * it). Any other error propagates. Still exclusive, so "first writer wins" holds
+ * exactly as the link path does; the only difference is the brief empty-file
+ * window between create and write. Exported for testing.
+ */
+export declare function acquireLockViaExclusiveOpen(pidPath: string, info: DaemonLockInfo): boolean;
+/**
+ * Remove a stale pidfile, but only if it still names a dead process. Re-reads
+ * the file immediately before unlinking so we never delete a lock that a live
+ * daemon (re)acquired in the meantime.
+ *
+ * must-fix 1 (issue #411 review): the original unconditionally `unlink`'d,
+ * which let a racing candidate delete a healthy daemon's lock. Passing
+ * `expectedDeadPid` (the pid the caller believed was dead) makes the clear a
+ * compare-and-delete: bail if the file now holds a different pid, or any live
+ * pid. Returns true when the stale lock is gone (or was already gone).
+ */
+export declare function clearStaleDaemonLock(pidPath: string, expectedDeadPid?: number): boolean;
+/**
+ * Probe whether `pid` is currently alive (signal-0). Treats EPERM as alive on
+ * every platform (the process exists, it's just not ours to signal) so we never
+ * mistake a live daemon for a dead one and clear its lock.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Bind the first usable socket from an ordered candidate list, relocating past
+ * any path that fails to bind for a non-conflict reason (see {@link
+ * SOCKET_BIND_CONFLICT_CODE}). The injected `listen` does the real
+ * `net.Server.listen` (and stale-socket clear); abstracted so the relocation
+ * policy is unit-testable without a real unsupported filesystem. Returns the
+ * server plus the path actually bound. An EADDRINUSE, or any error on the LAST
+ * candidate, propagates — the caller releases the lockfile and falls back to
+ * direct mode (#974). Exported for testing.
+ */
+export declare function bindFirstUsableSocket(candidates: string[], listen: (socketPath: string) => Promise<net.Server>, opts?: {
+    onRelocate?: (from: string, to: string, code: string) => void;
+}): Promise<{
+    server: net.Server;
+    socketPath: string;
+}>;
+/**
+ * Parse one client-hello line. Returns the peer pids if `line` is a well-formed
+ * client-hello (carries the `bhgraph_client` marker), or null otherwise — in
+ * which case the caller treats the bytes as ordinary JSON-RPC.
+ */
+export declare function parseClientHelloLine(line: string): {
+    pid: number;
+    hostPid: number | null;
+} | null;
+/**
+ * A client's peer is dead when its proxy process is gone, or when its known
+ * host process is gone. Unknown pid (no client-hello) is never "dead" on this
+ * basis — those clients rely on the socket-close path. Exported for testing.
+ */
+export declare function peerIsDead(peers: {
+    pid: number | null;
+    hostPid: number | null;
+}, isAlive: (pid: number) => boolean): boolean;
+/** Exported for test stubs that need to bound the hello-line read. */
+export { MAX_HELLO_LINE_BYTES };
+//# sourceMappingURL=daemon.d.ts.map

package/lib/dist/mcp/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/mcp/daemon.ts"],"names":[],"mappings":"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"}