wicked-brain 0.15.2 → 0.15.4

package/README.md

@@ -159,8 +159,50 @@ The viewer has no auth. It's localhost-only, same-machine trust.
 | `wicked-brain:retag` | Backfill synonym-expanded tags across all chunks for better search recall |
 | `wicked-brain:update` | Check npm for updates and reinstall skills across all detected CLIs |
 | `wicked-brain:lsp` | Universal code intelligence via LSP — hover, go-to-definition, diagnostics, completions |
+| `wicked-brain:graph` | Code-relationship graph — blast radius, callers, lineage — backed by a static code graph |
 | `wicked-brain:ui` | Open the read-only browser viewer — Material-styled Search + Wiki tabs over `http://localhost:<port>/` |
 
+## Code Graph (offline / air-gapped)
+
+`wicked-brain:graph` (blast radius, callers, lineage) is backed by the
+[`@colbymchenry/codegraph`](https://www.npmjs.com/package/@colbymchenry/codegraph)
+CLI. By **default** the brain resolves that CLI by shelling out to
+`npx @colbymchenry/codegraph` — which **fetches from the npm registry and will
+not work air-gapped**. On an offline/air-gapped machine, point the brain at a
+pre-installed binary with the **`WICKED_CODEGRAPH_BIN`** environment variable.
+
+`WICKED_CODEGRAPH_BIN` sits at the **top** of the resolution ladder:
+
+```
+WICKED_CODEGRAPH_BIN  →  brain _meta/codegraph.json {bin}  →  PATH  →  source node_modules/.bin/codegraph  →  npx (last resort, network)
+```
+
+**Offline install path:**
+
+```bash
+# 1. On a connected machine, install codegraph globally (or vendor it):
+npm install -g @colbymchenry/codegraph        # provides a `codegraph` on PATH
+#    …or install it into the project: npm install @colbymchenry/codegraph
+
+# 2. On the air-gapped machine, point the brain at the binary:
+export WICKED_CODEGRAPH_BIN=/usr/local/bin/codegraph     # macOS/Linux
+#    A .mjs/.js path is run via node; any other path is executed directly.
+```
+
+```powershell
+# Windows (PowerShell)
+$env:WICKED_CODEGRAPH_BIN = "C:\tools\codegraph\codegraph.cmd"
+```
+
+Notes:
+- Setting `WICKED_CODEGRAPH_BIN` to an **empty string** is a deliberate **kill
+  switch** — graph queries return `engine: "unavailable"` instead of falling
+  through to the network `npx` path.
+- A per-brain alternative to the env var is `_meta/codegraph.json` with
+  `{ "bin": "/path/to/codegraph" }`.
+- If nothing resolves, graph queries degrade gracefully to
+  `engine: "unavailable"` rather than returning a misleading empty graph.
+
 ## Multi-Brain Federation
 
 Brains can link to other brains. A personal research brain can reference a team standards brain. A client brain can inherit from a company knowledge base.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [

package/server/bin/wicked-brain-call.mjs

@@ -106,6 +106,20 @@ function readMetaConfig(brainPath) {
   }
 }
 
+// The brain the caller EXPECTS to be on this port. The server derives its
+// brain_id from brain.json's `id` field (see wicked-brain-server.mjs), so we
+// read the same source here. Fall back to the per-project basename convention
+// when brain.json is absent — that's the id a freshly-init'd brain will carry.
+function readExpectedBrainId(brainPath) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(brainPath, "brain.json"), "utf-8"));
+    if (cfg && typeof cfg.id === "string" && cfg.id) return cfg.id;
+  } catch {
+    // brain.json missing/unreadable — fall through to the basename convention.
+  }
+  return basename(brainPath);
+}
+
 // ---------- HTTP ----------
 
 async function callApi(port, action, params, { timeoutMs = 30000, auditFile } = {}) {
@@ -135,6 +149,40 @@ async function healthCheck(port, { timeoutMs = 800 } = {}) {
   }
 }
 
+// Like healthCheck, but returns the full health body (which carries brain_id)
+// so callers can confirm WHICH brain is answering the port — not just that
+// SOMETHING is. Returns null when nothing responds healthily.
+async function healthInfo(port, { timeoutMs = 800 } = {}) {
+  try {
+    const r = await callApi(port, "health", {}, { timeoutMs });
+    return r && r.status === "ok" ? r : null;
+  } catch {
+    return null;
+  }
+}
+
+// Raised by ensureServer when a server answers the persisted port but it
+// belongs to a DIFFERENT brain than the one we resolved. The data path
+// (search/index/remove/forget/query/...) routes through ensureServer, so this
+// guard is the single choke point that stops a destructive op from silently
+// hitting the wrong brain on a shared/recycled port. Fail closed — never
+// operate on a mismatched brain.
+class PortConflictError extends Error {
+  constructor({ port, expectedBrainId, actualBrainId }) {
+    super(
+      `port_conflict: port ${port} is held by a different brain ` +
+        `(expected brain_id "${expectedBrainId}", got "${actualBrainId ?? "unknown"}"). ` +
+        `Refusing the operation so it can't hit the wrong brain. ` +
+        `Stop the other server, free the port, or pass the correct --port for this brain.`,
+    );
+    this.name = "PortConflictError";
+    this.code = "port_conflict";
+    this.port = port;
+    this.expectedBrainId = expectedBrainId;
+    this.actualBrainId = actualBrainId ?? null;
+  }
+}
+
 // ---------- spawn lock ----------
 // Cross-platform exclusive-create lock via { flag: "wx" }. Stale entries
 // (older than STALE_LOCK_MS) are reaped on contention so a crashed CLI
@@ -207,12 +255,42 @@ function openServerLog(brainPath) {
   }
 }
 
+// Reconcile the responding server's brain_id against the brain we resolved.
+// Returns true when the port is ours (or when expectedBrainId is unknown and
+// we choose not to gate). Throws PortConflictError when a DIFFERENT brain
+// answers — the fail-closed path that protects the data plane. One health
+// round-trip per resolution; cheap enough that we don't cache across calls
+// (each CLI invocation resolves the server exactly once anyway).
+function reconcileHealth(health, { port, expectedBrainId }) {
+  // No expected id to compare against (no brain.json id, no basename) — can't
+  // meaningfully gate, so don't. In practice readExpectedBrainId always yields
+  // at least the basename, so this is a defensive fallback only.
+  if (!expectedBrainId) return true;
+  if (health.brain_id === expectedBrainId) return true;
+  throw new PortConflictError({
+    port,
+    expectedBrainId,
+    actualBrainId: health.brain_id,
+  });
+}
+
 async function ensureServer(brainPath, opts) {
   const { explicitPort, sourceOverride, noSpawn, log, spawnTimeoutMs = 10_000 } = opts;
   const meta = readMetaConfig(brainPath);
   const port = explicitPort || meta.server_port || 4242;
-
-  if (await healthCheck(port)) return port;
+  // The brain we EXPECT on this port — same source --status/--stop reconcile
+  // against (brain.json `id`, falling back to the per-project basename).
+  const expectedBrainId = opts.expectedBrainId ?? readExpectedBrainId(brainPath);
+
+  // Warm path: a server already answers the port. Confirm it's OUR brain before
+  // handing the port to the data plane. A foreign brain can occupy this port
+  // (stale config, manual restart, EADDRINUSE probe-up), and routing by port
+  // alone would let a destructive op (remove/forget) silently hit it.
+  const warmHealth = await healthInfo(port);
+  if (warmHealth) {
+    reconcileHealth(warmHealth, { port, expectedBrainId });
+    return port;
+  }
   if (noSpawn) {
     throw new Error(`server not reachable on port ${port} and --no-spawn was set`);
   }
@@ -222,14 +300,26 @@ async function ensureServer(brainPath, opts) {
 
   if (!tryLock(lockPath)) {
     log(`another process is starting the server; waiting...`);
-    if (await waitForHealth(port, spawnTimeoutMs)) return port;
+    const concurrentHealth = await waitForHealthInfo(port, spawnTimeoutMs);
+    if (concurrentHealth) {
+      // The peer that held the lock brought a server up — confirm it's OUR
+      // brain before we route the data plane at it.
+      reconcileHealth(concurrentHealth, { port, expectedBrainId });
+      return port;
+    }
     throw new Error(`concurrent spawn timed out on port ${port}`);
   }
 
   try {
     // Re-check after acquiring the lock — another process might have started
-    // and finished while we were contending.
-    if (await healthCheck(port)) return port;
+    // and finished while we were contending. Reconcile brain_id here too: the
+    // server that came up while we waited could be a different brain probing up
+    // onto this port.
+    const relockHealth = await healthInfo(port);
+    if (relockHealth) {
+      reconcileHealth(relockHealth, { port, expectedBrainId });
+      return port;
+    }
 
     const pidPath = join(brainPath, "_meta", "server.pid");
     if (existsSync(pidPath)) {
@@ -273,7 +363,14 @@ async function ensureServer(brainPath, opts) {
     }
     if (logFd !== null) log(`server logs -> ${logPath}`);
 
-    if (await waitForHealth(port, spawnTimeoutMs)) return port;
+    const ready = await waitForHealthInfo(port, spawnTimeoutMs);
+    if (ready) {
+      // We spawned with --brain brainPath, so the server that comes up should
+      // be ours. Reconcile anyway: a foreign brain could have won the bind in
+      // the race window before our child listened. Fail closed if so.
+      reconcileHealth(ready, { port, expectedBrainId });
+      return port;
+    }
     throw new Error(
       `server did not become ready within ${spawnTimeoutMs}ms on port ${port}` +
         (logFd !== null ? ` — see ${logPath} for the cause` : ""),
@@ -292,6 +389,18 @@ async function waitForHealth(port, timeoutMs) {
   return false;
 }
 
+// Like waitForHealth but returns the health body (carrying brain_id) once the
+// port answers, so the spawn path can confirm WHICH brain came up.
+async function waitForHealthInfo(port, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const h = await healthInfo(port, { timeoutMs: 500 });
+    if (h) return h;
+    await sleep(150);
+  }
+  return null;
+}
+
 function sleep(ms) {
   return new Promise(r => setTimeout(r, ms));
 }
@@ -495,15 +604,44 @@ Examples:
   if (args.flags.status) {
     const meta = readMetaConfig(brainPath);
     const port = args.flags.port || meta.server_port || 4242;
-    const running = await healthCheck(port);
+    const expectedBrainId = readExpectedBrainId(brainPath);
+    // Ask the responding server WHICH brain it is rather than trusting that the
+    // persisted port still belongs to us. A different brain's server can have
+    // claimed this port (probe-up on EADDRINUSE, stale config, manual restart),
+    // and a blind `running:true` would point an operator at the wrong process.
+    const health = await healthInfo(port);
     let pid = null;
     try { pid = parseInt(readFileSync(join(brainPath, "_meta", "server.pid"), "utf-8").trim(), 10); } catch {}
-    const payload = {
-      brain_path: brainPath,
-      port,
-      running,
-      pid: running && pidAlive(pid) ? pid : null,
-    };
+
+    let payload;
+    if (!health) {
+      payload = {
+        brain_path: brainPath,
+        brain_id: expectedBrainId,
+        port,
+        running: false,
+        pid: null,
+      };
+    } else if (health.brain_id !== expectedBrainId) {
+      // Port is occupied — but by a DIFFERENT brain than the one we resolved.
+      payload = {
+        brain_path: brainPath,
+        brain_id: expectedBrainId,
+        port,
+        running: false,
+        port_conflict: true,
+        actual_brain_id: health.brain_id ?? null,
+        pid: null,
+      };
+    } else {
+      payload = {
+        brain_path: brainPath,
+        brain_id: expectedBrainId,
+        port,
+        running: true,
+        pid: pidAlive(pid) ? pid : null,
+      };
+    }
     process.stdout.write(
       (args.flags.pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload)) + "\n",
     );
@@ -514,9 +652,32 @@ Examples:
   if (args.flags.stop) {
     const meta = readMetaConfig(brainPath);
     const port = args.flags.port || meta.server_port || 4242;
+    const expectedBrainId = readExpectedBrainId(brainPath);
     const pidPath = join(brainPath, "_meta", "server.pid");
     let pid = null;
     try { pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10); } catch {}
+
+    // Reconcile the port's actual occupant before signalling anything. If a
+    // DIFFERENT brain answers this port, refuse — killing our persisted PID
+    // (or, worse, mistaking the port owner for ours) would take down an
+    // unrelated process. The operator must target the right brain or port.
+    const health = await healthInfo(port);
+    if (health && health.brain_id !== expectedBrainId) {
+      const payload = {
+        stopped: false,
+        reason: "port_conflict",
+        port,
+        brain_id: expectedBrainId,
+        actual_brain_id: health.brain_id ?? null,
+      };
+      process.stdout.write(
+        (args.flags.pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload)) + "\n",
+      );
+      // Refused on purpose — surface a non-zero exit so scripted callers notice.
+      process.exitCode = 1;
+      return;
+    }
+
     if (!pid || !pidAlive(pid)) {
       process.stdout.write(JSON.stringify({ stopped: false, reason: "not running", port }) + "\n");
       return;
@@ -566,13 +727,43 @@ Examples:
     }
   }
 
-  const port = await ensureServer(brainPath, {
-    explicitPort: args.flags.port,
-    sourceOverride: args.flags.source,
-    noSpawn: args.flags.noSpawn,
-    spawnTimeoutMs: args.flags.spawnTimeoutMs,
-    log,
-  }).catch(err => die(err.message));
+  let port;
+  try {
+    port = await ensureServer(brainPath, {
+      explicitPort: args.flags.port,
+      sourceOverride: args.flags.source,
+      noSpawn: args.flags.noSpawn,
+      spawnTimeoutMs: args.flags.spawnTimeoutMs,
+      log,
+    });
+  } catch (err) {
+    if (err instanceof PortConflictError) {
+      // Fail closed: the persisted port is held by a different brain. Refuse the
+      // op (read OR mutate) so a destructive call (remove/forget/index) can't
+      // silently hit the wrong brain. Emit a structured payload on stdout that
+      // mirrors --stop/--status, plus a non-zero exit for scripted callers.
+      const payload = {
+        error: err.message,
+        action,
+        refused: true,
+        reason: "port_conflict",
+        port: err.port,
+        brain_id: err.expectedBrainId,
+        actual_brain_id: err.actualBrainId,
+      };
+      // Leave a refusal breadcrumb so the audit trail shows the op was blocked.
+      if (auditEnabled(args.flags.noAudit)) {
+        const a = writeAuditOpen(brainPath, action, params, err.port);
+        writeAuditClose(a, { exitCode: 1, durationMs: 0, response: payload, error: err.message });
+      }
+      process.stdout.write(
+        (args.flags.pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload)) + "\n",
+      );
+      process.exitCode = 1;
+      return;
+    }
+    die(err.message);
+  }
 
   // Open audit BEFORE the call so a crash mid-flight still leaves a partial
   // record. Audit is best-effort — write failures never block the request.

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [
@@ -40,6 +40,6 @@
     "wicked-bus": "^2.0.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
 }

package/skills/wicked-brain-graph/SKILL.md

@@ -52,3 +52,28 @@ empty graph.
 Backed by the `@colbymchenry/codegraph` CLI (resolved at runtime via
 `WICKED_CODEGRAPH_BIN` → brain config → PATH → `npx`). The brain reads codegraph's
 SQLite graph directly; it shells the CLI only to (re)build.
+
+### Offline / air-gapped install
+
+By **default** the engine is resolved by shelling out to
+`npx @colbymchenry/codegraph`, which **downloads from the npm registry and will
+not work on an air-gapped machine**. To run offline, install the CLI ahead of
+time and point the brain at the binary with **`WICKED_CODEGRAPH_BIN`** — the
+**highest-priority** entry in the resolution ladder:
+
+```
+WICKED_CODEGRAPH_BIN  →  _meta/codegraph.json {bin}  →  PATH  →  source node_modules/.bin/codegraph  →  npx (network, last resort)
+```
+
+```bash
+# Pre-install on a connected machine, then on the air-gapped host:
+export WICKED_CODEGRAPH_BIN=/usr/local/bin/codegraph     # macOS/Linux
+```
+```powershell
+$env:WICKED_CODEGRAPH_BIN = "C:\tools\codegraph\codegraph.cmd"   # Windows
+```
+
+- A `.mjs`/`.js` target is invoked via `node`; any other path is executed directly.
+- An **empty** `WICKED_CODEGRAPH_BIN` is a **kill switch** — queries return
+  `engine: "unavailable"` rather than reaching for the network `npx` path.
+- Per-brain alternative: write `_meta/codegraph.json` with `{ "bin": "/path/to/codegraph" }`.