wicked-brain 0.14.2 → 0.15.0

package/package.json

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

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

@@ -18,6 +18,7 @@ import { renderViewerHtml } from "../lib/viewer-page.mjs";
 import { walkBrainContent, purgeBrainContent } from "../lib/brain-walker.mjs";
 import { runOnboardWiki } from "../lib/onboard-wiki.mjs";
 import { readFile as readFileAsync } from "node:fs/promises";
+import { makeGraphActions } from "../lib/codegraph-actions.mjs";
 
 // Parse args
 const args = argv.slice(2);
@@ -112,6 +113,7 @@ try {
 
 // LSP client — pass source path so language servers are rooted at the project, not the brain dir
 const lsp = new LspClient(brainPath, db, sourcePath);
+const graphActions = makeGraphActions({ sourcePath, brainPath });
 
 // Auto-memorize subscriber handle (set after bus init in server.listen callback)
 let memorySubscriber = null;
@@ -246,6 +248,8 @@ const actions = {
   "lsp-call-hierarchy-in": (p) => lsp.callHierarchyIn(p),
   "lsp-call-hierarchy-out": (p) => lsp.callHierarchyOut(p),
   "lsp-diagnostics": (p) => lsp.diagnostics(p),
+  // Graph (codegraph) actions
+  ...graphActions,
   reonboard: async () => {
     // Detect mode + stamp the CLAUDE.md/AGENTS.md pointer, then rebuild the
     // search index from whatever content is on disk in this brain. Does NOT
@@ -318,6 +322,8 @@ const WRITE_ACTIONS = new Set([
   // DLQ replay/drop mutate the bus DB; list is read-only.
   "dlq_replay",
   "dlq_drop",
+  // Graph rebuild is a write — shells out to codegraph CLI.
+  "graph-index",
 ]);
 
 // HTTP server

package/server/lib/codegraph-actions.mjs

@@ -0,0 +1,34 @@
+import Database from "better-sqlite3";
+import { CodegraphClient } from "./codegraph-client.mjs";
+import { runIndex, staleness, dbPath } from "./codegraph-index.mjs";
+import { runExtractors } from "./codegraph-extract.mjs";
+
+/**
+ * Build the graph-* action handlers bound to a source repo. A fresh client per
+ * call keeps the readonly DB handle short-lived and always reopens after a rebuild.
+ */
+export function makeGraphActions({ sourcePath, brainPath } = {}) {
+  const withClient = (fn) => {
+    const c = new CodegraphClient(sourcePath);
+    try { return fn(c); } finally { c.close(); }
+  };
+  return {
+    "graph-blast-radius": (p = {}) => withClient((c) => c.blastRadius({ node: p.node, maxDepth: p.maxDepth })),
+    "graph-callers": (p = {}) => withClient((c) => c.callers({ node: p.node })),
+    "graph-lineage": (p = {}) => withClient((c) => c.lineage({ node: p.node, maxDepth: p.maxDepth })),
+    "graph-index": async () => {
+      const r = await runIndex(sourcePath, { brainPath, sourcePath });
+      if (!r.ok) {
+        return { ...r, staleness: staleness(sourcePath) };
+      }
+      const db = new Database(dbPath(sourcePath));
+      let injected;
+      try {
+        injected = await runExtractors({ db, sourcePath });
+      } finally {
+        db.close();
+      }
+      return { ...r, injected, staleness: staleness(sourcePath) };
+    },
+  };
+}

package/server/lib/codegraph-client.mjs

@@ -0,0 +1,85 @@
+import { existsSync } from "node:fs";
+import Database from "better-sqlite3";
+import { dbPath, staleness } from "./codegraph-index.mjs";
+
+// Pinned by Task 1 (docs/codegraph-contract.md): edges are stored
+// consumer->producer, edge(source=dependent, target=dependency). So dependents
+// of X are rows WHERE target=X (collect source); dependencies are the inverse.
+const DEPENDENTS_BY = "target";
+const DEPENDENCIES_BY = DEPENDENTS_BY === "target" ? "source" : "target";
+
+export class CodegraphClient {
+  #sourcePath;
+  #db = null;
+
+  constructor(sourcePath) { this.#sourcePath = sourcePath; }
+
+  #open() {
+    if (this.#db) return this.#db;
+    const p = dbPath(this.#sourcePath);
+    if (!existsSync(p)) return null;
+    this.#db = new Database(p, { readonly: true });
+    return this.#db;
+  }
+
+  close() { if (this.#db) { this.#db.close(); this.#db = null; } }
+
+  #nodeRows(ids) {
+    if (ids.length === 0) return [];
+    const ph = ids.map(() => "?").join(",");
+    return this.#db.prepare(
+      `SELECT id, kind, name, file_path, start_line, end_line FROM nodes WHERE id IN (${ph})`
+    ).all(...ids);
+  }
+
+  // BFS over edges. matchCol = the column matched against the frontier;
+  // collectCol = the column collected as the next frontier.
+  #walk(start, { matchCol, collectCol, maxDepth }) {
+    const stmt = this.#db.prepare(
+      `SELECT DISTINCT ${collectCol} AS next FROM edges WHERE ${matchCol} = ?`);
+    const seen = new Set();
+    let frontier = [start];
+    let depth = 0;
+    while (frontier.length && depth < maxDepth) {
+      const nextFrontier = [];
+      for (const node of frontier) {
+        for (const row of stmt.all(node)) {
+          if (row.next && row.next !== start && !seen.has(row.next)) {
+            seen.add(row.next);
+            nextFrontier.push(row.next);
+          }
+        }
+      }
+      frontier = nextFrontier;
+      depth += 1;
+    }
+    return [...seen];
+  }
+
+  #unavailable() {
+    return { engine: "unavailable",
+      reason: `no graph at ${dbPath(this.#sourcePath)} — run graph-index`,
+      staleness: staleness(this.#sourcePath) };
+  }
+
+  /** Transitive dependents — "what breaks if I change X". */
+  blastRadius({ node, maxDepth = 25 }) {
+    if (!this.#open()) return this.#unavailable();
+    const ids = this.#walk(node, { matchCol: DEPENDENTS_BY, collectCol: DEPENDENCIES_BY, maxDepth });
+    return { node, dependents: this.#nodeRows(ids), staleness: staleness(this.#sourcePath) };
+  }
+
+  /** Direct dependents only (depth 1). */
+  callers({ node }) {
+    if (!this.#open()) return this.#unavailable();
+    const ids = this.#walk(node, { matchCol: DEPENDENTS_BY, collectCol: DEPENDENCIES_BY, maxDepth: 1 });
+    return { node, callers: this.#nodeRows(ids), staleness: staleness(this.#sourcePath) };
+  }
+
+  /** Transitive dependencies — downstream lineage. */
+  lineage({ node, maxDepth = 25 }) {
+    if (!this.#open()) return this.#unavailable();
+    const ids = this.#walk(node, { matchCol: DEPENDENCIES_BY, collectCol: DEPENDENTS_BY, maxDepth });
+    return { node, dependencies: this.#nodeRows(ids), staleness: staleness(this.#sourcePath) };
+  }
+}

package/server/lib/codegraph-extract.mjs

@@ -0,0 +1,92 @@
+/**
+ * codegraph-extract.mjs — extractor registry (builtins + drop-ins).
+ *
+ * Ships three built-in extractors and discovers per-repo drop-in extractors
+ * under <sourcePath>/.codegraph-extractors/*.mjs, each exporting `extract`.
+ *
+ * Fail-open per extractor: one throwing must not abort the rest.
+ *
+ * NOTE on drop-in imports: this imports and runs code from the target repo —
+ * by design (the repo provides trusted extractors), same trust level as
+ * running its tests.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { extract as busExtract } from "./codegraph-extractors/bus.mjs";
+import { extract as dispatchExtract } from "./codegraph-extractors/dispatch.mjs";
+import { extract as capabilityExtract } from "./codegraph-extractors/capability.mjs";
+import { ensureFileNode, ensureVirtualNode } from "./codegraph-nodes.mjs";
+
+const BUILTINS = [
+  { label: "bus", extract: busExtract },
+  { label: "dispatch", extract: dispatchExtract },
+  { label: "capability", extract: capabilityExtract },
+];
+
+/**
+ * Discover drop-in extractors under <sourcePath>/.codegraph-extractors/*.mjs.
+ * Each file must export a function `extract`. Sorted for deterministic ordering.
+ * Broken files (import error or missing export) are silently skipped.
+ *
+ * @param {string} sourcePath
+ * @returns {Promise<Array<{label:string, extract:Function}>>}
+ */
+export async function discoverDropins(sourcePath) {
+  const dir = join(sourcePath, ".codegraph-extractors");
+  if (!existsSync(dir)) return [];
+
+  let entries;
+  try {
+    entries = readdirSync(dir)
+      .filter((f) => f.endsWith(".mjs"))
+      .sort();
+  } catch {
+    return [];
+  }
+
+  const dropins = [];
+  for (const filename of entries) {
+    const fullpath = join(dir, filename);
+    try {
+      const mod = await import(pathToFileURL(fullpath).href);
+      if (typeof mod.extract === "function") {
+        dropins.push({ label: `dropin:${filename}`, extract: mod.extract });
+      }
+    } catch {
+      // Broken drop-in — skip, not fatal
+    }
+  }
+  return dropins;
+}
+
+/**
+ * Run all extractors (builtins + drop-ins) against the open read-write db.
+ * Fail-open per extractor: one throwing must not abort the rest.
+ *
+ * @param {{ db: import("better-sqlite3").Database, sourcePath: string }} opts
+ * @returns {Promise<Record<string, object> & { total_injected_edges: number, dropins: string[] }>}
+ */
+export async function runExtractors({ db, sourcePath }) {
+  const dropins = await discoverDropins(sourcePath);
+  const dropin_labels = dropins.map((d) => d.label);
+  const all = [...BUILTINS, ...dropins];
+
+  const nodes = { ensureFileNode, ensureVirtualNode };
+
+  const out = {};
+  let total = 0;
+
+  for (const ext of all) {
+    try {
+      const counts = await ext.extract({ db, sourcePath, nodes });
+      out[ext.label] = counts;
+      total += counts.edges_added || 0;
+    } catch (e) {
+      out[ext.label] = { error: String((e && e.message) || e) };
+    }
+  }
+
+  return { ...out, total_injected_edges: total, dropins: dropin_labels };
+}

package/server/lib/codegraph-extractors/bus.mjs

@@ -0,0 +1,180 @@
+/**
+ * codegraph-extractors/bus.mjs — wicked-bus producer→consumer injected edges.
+ *
+ * Port of scripts/codegraph/inject_edges.py with the edge direction CORRECTED:
+ *
+ *   Garden's inject_edges.py inserts (source=producer, target=consumer).
+ *   The contract doc resolves the ambiguity: edges are stored
+ *   source=dependent→target=dependency, and DEPENDENTS_BY="target". So
+ *   blast-radius(X) = WHERE target=X (collect source). For the consumer to
+ *   surface as a dependent of the producer, the edge must be:
+ *
+ *       source = consumer (dependent — breaks when producer's event changes)
+ *       target = producer (dependency — the thing being changed)
+ *
+ * This is the corrected direction. Garden's version inserts the opposite and
+ * is a latent bug (blast-radius of the producer would NOT surface the consumer).
+ *
+ * Algorithm:
+ *   1. DELETE edges WHERE provenance='injected:bus'   (idempotent)
+ *   2. Read <sourcePath>/scripts/_bus_consumers.json
+ *   3. Grep <sourcePath>/scripts/**\/*.py for event-string literals
+ *   4. For each consumer: confirm node exists; for each producer: confirm node
+ *      exists; INSERT edge (source=consumer, target=producer)
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+const EVENT_RE = /["']((?:wicked|wg)\.[a-z0-9_]+(?:\.[a-z0-9_]+)+)["']/g;
+const INJECTED_PROVENANCE = "injected:bus";
+
+/**
+ * Read and parse _bus_consumers.json. Returns [] on missing or malformed file.
+ * @param {string} sourcePath
+ * @returns {{ event_filter: string, module: string }[]}
+ */
+function readConsumers(sourcePath) {
+  const p = join(sourcePath, "scripts", "_bus_consumers.json");
+  try {
+    const data = JSON.parse(readFileSync(p, "utf8"));
+    const consumers = data?.consumers;
+    if (!Array.isArray(consumers)) return [];
+    return consumers.filter((c) => c?.event_filter && c?.module);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Recursively collect all .py files under dir, skipping __pycache__ dirs
+ * and files whose basename ends with _bus_consumers.py.
+ * @param {string} dir
+ * @returns {string[]} absolute file paths
+ */
+function collectPyFiles(dir) {
+  const results = [];
+  let entries;
+  try { entries = readdirSync(dir); } catch { return results; }
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) {
+      if (entry === "__pycache__") continue;
+      results.push(...collectPyFiles(full));
+    } else if (entry.endsWith(".py") && !entry.endsWith("_bus_consumers.py")) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Build event→Set<producerRelpath> map by grepping scripts/**\/*.py.
+ * @param {string} sourcePath
+ * @param {Set<string>} events
+ * @returns {Map<string, Set<string>>}
+ */
+function buildProducerMap(sourcePath, events) {
+  /** @type {Map<string, Set<string>>} */
+  const map = new Map();
+  for (const ev of events) map.set(ev, new Set());
+
+  const scriptsDir = join(sourcePath, "scripts");
+  const pyFiles = collectPyFiles(scriptsDir);
+
+  for (const absPath of pyFiles) {
+    let text;
+    try { text = readFileSync(absPath, "utf8"); } catch { continue; }
+    // posix relpath relative to sourcePath
+    const rel = relative(sourcePath, absPath).split(sep).join("/");
+    // reset lastIndex between files
+    EVENT_RE.lastIndex = 0;
+    let m;
+    while ((m = EVENT_RE.exec(text)) !== null) {
+      const ev = m[1];
+      if (map.has(ev)) {
+        map.get(ev).add(rel);
+      }
+      // reset not needed between matches in same string, but be safe
+    }
+  }
+  return map;
+}
+
+/**
+ * Confirm a file node exists in the graph; return the node id or null.
+ * @param {import("better-sqlite3").Database} db
+ * @param {string} relpath
+ * @returns {string|null}
+ */
+function fileNodeId(db, relpath) {
+  const id = `file:${relpath}`;
+  const row = db.prepare("SELECT 1 FROM nodes WHERE id = ?").get(id);
+  return row ? id : null;
+}
+
+/**
+ * Extract wicked-bus producer→consumer injected edges into the codegraph DB.
+ *
+ * @param {{ db: import("better-sqlite3").Database, sourcePath: string }} opts
+ * @returns {{ edges_added: number, skipped: number, consumers: number }}
+ */
+export function extract({ db, sourcePath }) {
+  // 1. Idempotent: clear prior bus edges
+  db.prepare("DELETE FROM edges WHERE provenance = ?").run(INJECTED_PROVENANCE);
+
+  // 2. Load consumer registry
+  const consumers = readConsumers(sourcePath);
+  if (consumers.length === 0) {
+    return { edges_added: 0, skipped: 0, consumers: 0 };
+  }
+
+  // 3. Grep for producers
+  const events = new Set(consumers.map((c) => c.event_filter));
+  const producerMap = buildProducerMap(sourcePath, events);
+
+  // 4. Insert edges
+  const insertEdge = db.prepare(
+    "INSERT INTO edges (source, target, kind, metadata, provenance) VALUES (?, ?, ?, ?, ?)"
+  );
+
+  let edges_added = 0;
+  let skipped = 0;
+
+  for (const { event_filter: ev, module: consumerMod } of consumers) {
+    // Confirm consumer node exists
+    const consumerNodeId = fileNodeId(db, consumerMod);
+    if (!consumerNodeId) {
+      skipped++;
+      continue;
+    }
+
+    const producers = producerMap.get(ev) ?? new Set();
+    for (const prodRelpath of [...producers].sort()) {
+      // Don't self-link
+      if (prodRelpath === consumerMod) continue;
+
+      // Confirm producer node exists
+      const producerNodeId = fileNodeId(db, prodRelpath);
+      if (!producerNodeId) {
+        skipped++;
+        continue;
+      }
+
+      // DIRECTION: source=consumer (dependent), target=producer (dependency)
+      // blastRadius(producer) = WHERE target=producer → source=consumer ✓
+      insertEdge.run(
+        consumerNodeId,              // source = consumer (dependent)
+        producerNodeId,              // target = producer (dependency)
+        "references",
+        JSON.stringify({ injected: "bus", event: ev }),
+        INJECTED_PROVENANCE
+      );
+      edges_added++;
+    }
+  }
+
+  return { edges_added, skipped, consumers: consumers.length };
+}

package/server/lib/codegraph-extractors/capability.mjs

@@ -0,0 +1,139 @@
+/**
+ * codegraph-extractors/capability.mjs — agent→capability injected edges.
+ *
+ * An agent declares needed capabilities via a `tool-capabilities:` YAML frontmatter
+ * block list. This extractor reads those declarations and creates synthetic
+ * `capability:<name>` nodes plus edges from the agent file to each capability.
+ *
+ * Edge direction: source=agent (dependent) → target=capability (dependency).
+ * DEPENDENTS_BY="target": blastRadius(capability) = WHERE target=capability → source=agent ✓
+ *
+ * Frontmatter-only port of wicked-garden's inject_capability_edges.py.
+ * No capability registry is imported — brain stays dependency-free.
+ *
+ * This extractor OWNS the capability nodes:
+ *   - DELETE edges WHERE provenance='injected:capability'
+ *   - DELETE nodes WHERE kind='capability'
+ * then re-inserts cleanly on each run (fully idempotent).
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { ensureFileNode, ensureVirtualNode } from "../codegraph-nodes.mjs";
+
+const INJECTED_PROVENANCE = "injected:capability";
+
+// Matches the tool-capabilities: YAML block at the start or in frontmatter.
+// Captures the multi-line list body (lines starting with optional whitespace + "- item").
+const CAPS_BLOCK_RE = /(?:^|\n)tool-capabilities:\s*\n((?:[ \t]+-[ \t]*[a-z0-9_-]+[ \t]*\n?)+)/;
+
+// Matches individual list items: "  - capability-name"
+const ITEM_RE = /-[ \t]*([a-z0-9_-]+)/g;
+
+/**
+ * Extract the YAML frontmatter block (between leading --- fences) from text.
+ * Returns the frontmatter string, or the full text if no fences found.
+ * @param {string} text
+ * @returns {string}
+ */
+function extractFrontmatter(text) {
+  const match = text.match(/^---\s*\n([\s\S]*?)\n---/);
+  return match ? match[1] : "";
+}
+
+/**
+ * Parse tool-capabilities list from frontmatter text.
+ * Returns a Set of capability names (deduped).
+ * @param {string} frontmatter
+ * @returns {Set<string>}
+ */
+function parseCapabilities(frontmatter) {
+  const caps = new Set();
+  const blockMatch = CAPS_BLOCK_RE.exec(frontmatter);
+  if (!blockMatch) return caps;
+
+  const block = blockMatch[1];
+  ITEM_RE.lastIndex = 0;
+  let m;
+  while ((m = ITEM_RE.exec(block)) !== null) {
+    caps.add(m[1]);
+  }
+  return caps;
+}
+
+/**
+ * Recursively collect all .md files under dir.
+ * @param {string} dir
+ * @returns {string[]} absolute file paths
+ */
+function collectMdFiles(dir) {
+  const results = [];
+  let entries;
+  try { entries = readdirSync(dir); } catch { return results; }
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) {
+      results.push(...collectMdFiles(full));
+    } else if (entry.endsWith(".md")) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Extract agent→capability injected edges into the codegraph DB.
+ *
+ * @param {{ db: import("better-sqlite3").Database, sourcePath: string }} opts
+ * @returns {{ edges_added: number, capabilities: number }}
+ */
+export function extract({ db, sourcePath }) {
+  // 1. Idempotent: clear prior capability edges and owned nodes
+  db.prepare("DELETE FROM edges WHERE provenance = ?").run(INJECTED_PROVENANCE);
+  db.prepare("DELETE FROM nodes WHERE kind = 'capability'").run();
+
+  const insertEdge = db.prepare(
+    "INSERT INTO edges (source, target, kind, metadata, provenance) VALUES (?, ?, ?, ?, ?)"
+  );
+
+  let edges_added = 0;
+  const distinctCaps = new Set();
+
+  // 2. Scan agents/**/*.md
+  const agentsDir = join(sourcePath, "agents");
+  const agentFiles = collectMdFiles(agentsDir);
+
+  for (const absPath of agentFiles) {
+    let text;
+    try { text = readFileSync(absPath, "utf8"); } catch { continue; }
+
+    // Posix relpath relative to sourcePath
+    const relpath = relative(sourcePath, absPath).split(sep).join("/");
+
+    // 3. Parse frontmatter capabilities (deduped per agent)
+    const frontmatter = extractFrontmatter(text);
+    const caps = parseCapabilities(frontmatter);
+    if (caps.size === 0) continue;
+
+    const src = ensureFileNode(db, relpath);
+
+    for (const cap of caps) {
+      // Ensure the capability virtual node exists
+      const tgt = ensureVirtualNode(db, `capability:${cap}`, "capability", cap);
+
+      insertEdge.run(
+        src,
+        tgt,
+        "references",
+        JSON.stringify({ injected: "capability", capability: cap }),
+        INJECTED_PROVENANCE
+      );
+      edges_added++;
+      distinctCaps.add(cap);
+    }
+  }
+
+  return { edges_added, capabilities: distinctCaps.size };
+}

package/server/lib/codegraph-extractors/dispatch.mjs

@@ -0,0 +1,122 @@
+/**
+ * codegraph-extractors/dispatch.mjs — command→agent injected edges.
+ *
+ * A slash command dispatches to a subagent via a `subagent_type: <plugin>:<domain>:<name>`
+ * string (in Task(subagent_type="...") or YAML frontmatter). The command file never
+ * references the agent file — grep/static can't link them. This extractor injects
+ * those edges so blast-radius traversal can surface the dispatching commands when
+ * an agent changes.
+ *
+ * Edge direction: source=command (dependent) → target=agent (dependency).
+ * DEPENDENTS_BY="target": blastRadius(agent) = WHERE target=agent → source=command ✓
+ *
+ * Port of wicked-garden's inject_dispatch_edges.py. Direction is already correct
+ * in the garden version for our blast-radius convention (no reversal needed, unlike bus).
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { ensureFileNode } from "../codegraph-nodes.mjs";
+
+const INJECTED_PROVENANCE = "injected:dispatch";
+
+// Matches subagent_type: "plugin:domain:name" or subagent_type="plugin:domain:name"
+// (with or without quotes, colon or equals separator)
+const SUBAGENT_RE = /subagent_type\s*[:=]\s*["']?([a-z0-9_-]+:[a-z0-9_-]+:[a-z0-9_-]+)["']?/g;
+
+/**
+ * Recursively collect all .md files under dir.
+ * @param {string} dir
+ * @returns {string[]} absolute file paths
+ */
+function collectMdFiles(dir) {
+  const results = [];
+  let entries;
+  try { entries = readdirSync(dir); } catch { return results; }
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) {
+      results.push(...collectMdFiles(full));
+    } else if (entry.endsWith(".md")) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Given a handle `plugin:domain:name`, resolve to the agent relpath
+ * `agents/<domain>/<name>.md`. Returns the relpath if the file exists, else null.
+ * @param {string} sourcePath
+ * @param {string} handle  e.g. "wicked-garden:d:my-agent"
+ * @returns {string|null}
+ */
+function resolveHandle(sourcePath, handle) {
+  const parts = handle.split(":");
+  if (parts.length !== 3) return null;
+  const [, domain, name] = parts;
+  const relpath = `agents/${domain}/${name}.md`;
+  if (existsSync(join(sourcePath, relpath))) return relpath;
+  return null;
+}
+
+/**
+ * Extract command→agent dispatch injected edges into the codegraph DB.
+ *
+ * @param {{ db: import("better-sqlite3").Database, sourcePath: string }} opts
+ * @returns {{ edges_added: number, dispatches: number }}
+ */
+export function extract({ db, sourcePath }) {
+  // 1. Idempotent: clear prior dispatch edges
+  db.prepare("DELETE FROM edges WHERE provenance = ?").run(INJECTED_PROVENANCE);
+
+  const insertEdge = db.prepare(
+    "INSERT INTO edges (source, target, kind, metadata, provenance) VALUES (?, ?, ?, ?, ?)"
+  );
+
+  let edges_added = 0;
+  let dispatches = 0;
+
+  // 2. Scan commands/**/*.md
+  const commandsDir = join(sourcePath, "commands");
+  const commandFiles = collectMdFiles(commandsDir);
+
+  for (const absPath of commandFiles) {
+    let text;
+    try { text = readFileSync(absPath, "utf8"); } catch { continue; }
+
+    // Posix relpath relative to sourcePath
+    const relpath = relative(sourcePath, absPath).split(sep).join("/");
+
+    // 3. Find distinct handles in this file
+    SUBAGENT_RE.lastIndex = 0;
+    const handles = new Set();
+    let m;
+    while ((m = SUBAGENT_RE.exec(text)) !== null) {
+      handles.add(m[1]);
+    }
+
+    for (const handle of handles) {
+      // 4. Resolve handle to agent file
+      const agentRelpath = resolveHandle(sourcePath, handle);
+      if (!agentRelpath) continue; // not an agent file, or file doesn't exist
+
+      const src = ensureFileNode(db, relpath);
+      const tgt = ensureFileNode(db, agentRelpath);
+
+      insertEdge.run(
+        src,
+        tgt,
+        "references",
+        JSON.stringify({ injected: "dispatch", subagent_type: handle }),
+        INJECTED_PROVENANCE
+      );
+      edges_added++;
+      dispatches++;
+    }
+  }
+
+  return { edges_added, dispatches };
+}

package/server/lib/codegraph-index.mjs

@@ -0,0 +1,56 @@
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCodegraph } from "./codegraph-resolver.mjs";
+
+export function dbPath(sourcePath) {
+  return join(sourcePath, ".codegraph", "codegraph.db");
+}
+
+/**
+ * How far the graph has drifted from HEAD. Fail-open: errors report
+ * present-but-unknown, never throw.
+ * @returns {{present:boolean, stale:boolean|null, commits_behind:number|null, indexed_at:string|null}}
+ */
+export function staleness(sourcePath) {
+  const db = dbPath(sourcePath);
+  if (!existsSync(db)) {
+    return { present: false, stale: null, commits_behind: null, indexed_at: null };
+  }
+  try {
+    const iso = new Date(statSync(db).mtimeMs).toISOString();
+    const out = execFileSync("git",
+      ["-C", sourcePath, "rev-list", "--count", `--since=${iso}`, "HEAD"],
+      { encoding: "utf-8", timeout: 10_000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const behind = out ? parseInt(out, 10) : 0;
+    return { present: true, stale: behind > 0, commits_behind: behind, indexed_at: iso };
+  } catch {
+    return { present: true, stale: null, commits_behind: null, indexed_at: null };
+  }
+}
+
+/**
+ * Build/refresh the graph by shelling codegraph. `init` bootstraps .codegraph
+ * AND indexes; `index` refreshes an existing graph (fails if .codegraph is
+ * absent) — so we pick based on db presence (pinned in docs/codegraph-contract.md).
+ * Resolves nothing -> {ok:false}. Never throws. `_spawn` is injectable for tests.
+ * @returns {Promise<{ok:boolean, subcommand?:string, error?:string}>}
+ */
+export function runIndex(sourcePath, opts = {}, _spawn = spawn) {
+  return new Promise((resolve) => {
+    const argv = resolveCodegraph({ ...opts, sourcePath });
+    if (!argv) { resolve({ ok: false, error: "codegraph not resolvable" }); return; }
+    const [cmd, ...prefix] = argv;
+    const sub = existsSync(dbPath(sourcePath)) ? "index" : "init";
+    // stdout is "ignore", not "pipe": codegraph prints a progress banner and on a
+    // large repo an undrained stdout pipe can fill and deadlock the child. stderr
+    // stays piped so we can surface the failure message.
+    const proc = _spawn(cmd, [...prefix, sub, "."], { cwd: sourcePath, stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    proc.stderr.on("data", (d) => { stderr += d.toString(); });
+    proc.on("error", (e) => resolve({ ok: false, error: e.message }));
+    proc.on("close", (code) =>
+      resolve(code === 0 ? { ok: true, subcommand: sub }
+                         : { ok: false, error: stderr.trim() || `exit ${code}` }));
+  });
+}

package/server/lib/codegraph-nodes.mjs

@@ -0,0 +1,63 @@
+/**
+ * codegraph-nodes.mjs — self-noding helpers for injected-edge extractors.
+ *
+ * codegraph indexes *code* (tree-sitter parsed). Injected edges to/from .md
+ * files or virtual capability nodes need their endpoints to exist in the nodes
+ * table first. These helpers create them idempotently via INSERT OR IGNORE, so
+ * real code files codegraph already indexed are never overwritten.
+ *
+ * Port of scripts/codegraph/_graph_nodes.py, targeting the exact schema in
+ * docs/codegraph-contract.md (all NOT NULL columns populated).
+ */
+
+// Populates every NOT NULL column the codegraph `nodes` schema requires.
+// Columns with defaults (is_exported etc.) are omitted — SQLite fills them.
+const INSERT_NODE =
+  "INSERT OR IGNORE INTO nodes " +
+  "(id, kind, name, qualified_name, file_path, language, " +
+  " start_line, end_line, start_column, end_column, updated_at) " +
+  "VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, 0, ?)";
+
+function nowMs() {
+  return Date.now();
+}
+
+/**
+ * Ensure a `file:<relpath>` node exists in the graph; return its id.
+ *
+ * For .md command/agent files that codegraph skipped, this creates a synthetic
+ * file node so dispatch/capability edges can anchor. For a real source file
+ * codegraph already indexed, INSERT OR IGNORE is a no-op (real node preserved).
+ *
+ * @param {import("better-sqlite3").Database} db - read-write Database
+ * @param {string} relpath - POSIX-relative path from repo root
+ * @param {string} [language] - language tag (default "markdown")
+ * @returns {string} the node id `file:<relpath>`
+ */
+export function ensureFileNode(db, relpath, language = "markdown") {
+  const id = `file:${relpath}`;
+  const name = relpath.split("/").pop();
+  db.prepare(INSERT_NODE).run(id, "file", name, relpath, relpath, language, 1, 1, nowMs());
+  return id;
+}
+
+/**
+ * Ensure a synthetic non-file node (e.g. `capability:<name>`) exists; return id.
+ *
+ * Populates every NOT NULL column the schema demands — the original capability
+ * insert set only id/kind/name/file_path and would violate NOT NULL constraints.
+ *
+ * @param {import("better-sqlite3").Database} db - read-write Database
+ * @param {string} id - node id (e.g. "capability:foo")
+ * @param {string} kind - node kind (e.g. "capability")
+ * @param {string} name - human-readable name
+ * @param {string|null} [filePath] - optional file_path; falls back to id
+ * @returns {string} the node id
+ */
+export function ensureVirtualNode(db, id, kind, name, filePath = null) {
+  db.prepare(INSERT_NODE).run(
+    id, kind, name, name, filePath ?? id, "virtual",
+    0, 0, nowMs()
+  );
+  return id;
+}

package/server/lib/codegraph-resolver.mjs

@@ -0,0 +1,64 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { platform } from "node:os";
+
+const PACKAGE = "@colbymchenry/codegraph";
+
+function argvFor(target) {
+  // A .mjs/.js path is a script -> invoke via node; else run directly.
+  return /\.(mjs|js)$/.test(target) ? ["node", target] : [target];
+}
+
+function whichDefault(command) {
+  try {
+    const cmd = platform() === "win32" ? "where" : "which";
+    const out = execFileSync(cmd, [command], { encoding: "utf-8", timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"] });
+    return out.trim().split("\n")[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+function configBin(brainPath) {
+  if (!brainPath) return null;
+  try {
+    const cfg = JSON.parse(readFileSync(join(brainPath, "_meta", "codegraph.json"), "utf-8"));
+    return typeof cfg.bin === "string" && cfg.bin.trim() ? cfg.bin.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the argv prefix that invokes codegraph, or null.
+ * Ladder: WICKED_CODEGRAPH_BIN (set-but-empty = kill switch) -> brain
+ * _meta/codegraph.json {bin} -> PATH -> source node_modules/.bin -> `npx`.
+ */
+export function resolveCodegraph(opts = {}) {
+  const { env = process.env, brainPath, sourcePath, which = whichDefault,
+    allowNpx = true } = opts;
+
+  if (Object.prototype.hasOwnProperty.call(env, "WICKED_CODEGRAPH_BIN")) {
+    const v = (env.WICKED_CODEGRAPH_BIN || "").trim();
+    return v ? argvFor(v) : null; // empty == kill switch
+  }
+  const cfg = configBin(brainPath);
+  if (cfg) return argvFor(cfg);
+
+  const onPath = which("codegraph");
+  if (onPath) return [onPath];
+
+  if (sourcePath) {
+    const local = join(sourcePath, "node_modules", ".bin", "codegraph");
+    if (existsSync(local)) return [local];
+  }
+  if (allowNpx && which("npx")) return ["npx", "-y", PACKAGE];
+  return null;
+}
+
+/** True iff a CONCRETE install resolves (not the npx last resort). */
+export function codegraphAvailable(opts = {}) {
+  return resolveCodegraph({ ...opts, allowNpx: false }) !== null;
+}

package/server/lib/memory-subscriber.mjs

@@ -13,6 +13,12 @@ import { join } from "node:path";
 import { getBusDb, isBusAvailable, emitEvent } from "./bus.mjs";
 import { promoteFact } from "./memory-promoter.mjs";
 
+// Subscriber identity on the bus. Used both to register the subscription and to
+// locate its cursor for the TTL self-heal — keep them in one place so the two
+// can't drift.
+const PLUGIN = "wicked-brain";
+const FACT_FILTER = "wicked.fact.extracted";
+
 /**
  * Start the auto-memorize subscriber.
  * Returns the subscription handle (with .stop()) or null if the bus is unavailable.
@@ -38,10 +44,22 @@ export async function startMemorySubscriber({ brainPath, brainId, db }) {
 
   const memoryDir = join(brainPath, "memory");
 
+  // Self-heal a cursor stranded behind the bus TTL window (e.g. after a long
+  // server outage). The subscriber RESUMES its existing cursor, so cursor_init
+  // "latest" does not recover a stale one — poll() would throw WB-003 every
+  // cycle and auto-memorize would stall until manually reset. Advance it to the
+  // latest event before subscribing.
+  const healed = fastForwardStaleCursor(busDb, PLUGIN, FACT_FILTER);
+  if (healed) {
+    console.error(
+      `[memory-subscriber] cursor was behind the TTL window; repositioned ${healed.from} -> ${healed.to} to replay survivors`,
+    );
+  }
+
   const sub = subscribe({
     db: busDb,
-    plugin: "wicked-brain",
-    filter: "wicked.fact.extracted",
+    plugin: PLUGIN,
+    filter: FACT_FILTER,
     cursor_init: "latest",
     pollIntervalMs: 5000,
     maxRetries: 3,
@@ -84,6 +102,63 @@ export async function startMemorySubscriber({ brainPath, brainId, db }) {
   return sub;
 }
 
+/**
+ * Fast-forward a subscriber cursor that has fallen behind the bus TTL window.
+ *
+ * After a long server outage the durable cursor can sit below the oldest
+ * surviving event; wicked-bus poll() then throws WB-003 ("cursor behind the TTL
+ * window") every cycle. The subscriber resumes its existing cursor (cursor_init
+ * only applies on first registration), so it never recovers on its own. This
+ * mirrors poll()'s WB-003 check and, when behind, repositions the cursor to just
+ * before the oldest surviving event so the subscriber still replays everything
+ * left in the bus (at-least-once) instead of discarding the survivors.
+ *
+ * No-op when the cursor is current, when there are no events, or when no cursor
+ * exists yet (a fresh subscriber initializes at "latest" anyway). Never throws —
+ * a self-heal failure must not block server startup.
+ *
+ * @param {import('better-sqlite3').Database} busDb
+ * @param {string} plugin
+ * @param {string} filter  event_type_filter the subscriber registered with
+ * @returns {{from:number,to:number}|null} the adjustment made, or null for no-op
+ */
+export function fastForwardStaleCursor(busDb, plugin, filter) {
+  try {
+    const bounds = busDb
+      .prepare("SELECT MIN(event_id) AS min_id FROM events")
+      .get();
+    if (!bounds || bounds.min_id == null) return null; // no events to be behind of
+
+    const row = busDb
+      .prepare(
+        `SELECT c.cursor_id AS cursor_id, c.last_event_id AS last_event_id
+           FROM subscriptions s
+           INNER JOIN cursors c ON c.subscription_id = s.subscription_id
+          WHERE s.plugin = ? AND s.role = 'subscriber'
+            AND s.event_type_filter = ?
+            AND s.deregistered_at IS NULL AND c.deregistered_at IS NULL
+          ORDER BY s.registered_at DESC
+          LIMIT 1`,
+      )
+      .get(plugin, filter);
+    if (!row) return null; // no existing cursor — fresh subscribe inits at "latest"
+
+    // Mirror wicked-bus poll(): WB-003 fires when last_event_id < oldest - 1.
+    // Reposition to oldest-1 (not latest) so the subscriber replays every event
+    // that survived the sweep instead of discarding the backlog.
+    const target = bounds.min_id - 1;
+    if (row.last_event_id < target) {
+      busDb
+        .prepare("UPDATE cursors SET last_event_id = ? WHERE cursor_id = ?")
+        .run(target, row.cursor_id);
+      return { from: row.last_event_id, to: target };
+    }
+    return null;
+  } catch {
+    return null; // never block startup on the self-heal
+  }
+}
+
 /**
  * Render a memory descriptor as a markdown file with YAML-ish frontmatter.
  * Minimal serializer — no YAML lib. Matches the format used by wicked-brain:memory.

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [

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

@@ -0,0 +1,54 @@
+---
+name: wicked-brain:graph
+description: |
+  Code-relationship graph queries — blast radius, callers, and lineage — backed
+  by a codegraph static graph the brain owns. Answers "what breaks if I change X",
+  "who calls X", and "what does X depend on" across the whole repo, including
+  relationships a grep or single-file LSP lookup cannot see.
+
+  Use when: "blast radius", "what breaks if I change", "impact of changing X",
+  "who depends on X", "what depends on X", "lineage", "what does X depend on",
+  "architecture map", "code relationship graph".
+---
+
+# wicked-brain:graph
+
+Relationship-graph intelligence over a codegraph-built SQLite graph. Distinct from
+`wicked-brain:lsp` (live, single-symbol definitions / references / hover /
+diagnostics) — this is the whole-repo relationship graph and the home of
+blast-radius / lineage.
+
+## Cross-Platform Notes
+
+This skill uses `npx wicked-brain-call` for all server interaction. The CLI works
+on macOS, Linux, and Windows; it discovers the brain, auto-starts the server, and
+writes a per-call audit record under `{brain}/calls/`.
+
+## Queries
+
+- `graph-index` — build/refresh the graph (`codegraph init`/`index`). Run once per
+  repo, then on demand when a result reports it is stale.
+- `graph-blast-radius {node}` — transitive **dependents** of `node` ("what breaks
+  if I change it").
+- `graph-callers {node}` — direct dependents only (depth 1).
+- `graph-lineage {node}` — transitive **dependencies** (what `node` depends on,
+  downstream).
+
+`node` ids follow codegraph's convention — e.g. `file:src/app.py`, or a symbol id
+like `function:<hash>` (use `qualified_name` from a search/symbols lookup to find
+the id). Every result carries a `staleness` stamp (`commits_behind`, `indexed_at`);
+when `stale` is true, re-run `graph-index`.
+
+## Freshness
+
+Lazy by design — the graph is **never** auto-rebuilt by a file watcher (that path
+is a known CPU-runaway hazard). Results tell you when they are behind HEAD; rebuild
+explicitly with `graph-index` (or wire the optional commit hook). If codegraph is
+not installed, queries return `engine: "unavailable"` rather than a misleading
+empty graph.
+
+## Engine
+
+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.

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

@@ -6,14 +6,18 @@ description: |
   language servers when missing.
 
   Use when: "where is X defined", "who uses X", "what type is X",
-  "list symbols in", "find symbol", "who calls X", "blast radius",
-  "architecture map", "code diagnostics", "lsp health".
+  "list symbols in", "find symbol", "who calls X",
+  "code diagnostics", "lsp health".
 ---
 
 # wicked-brain:lsp
 
 Universal code intelligence for any CLI/IDE via the brain's LSP client layer.
 
+> For whole-repo **relationship** queries — blast radius, lineage, architecture
+> map — use `wicked-brain:graph` (codegraph-backed). LSP here is live,
+> single-symbol intelligence (definitions, references, hover, diagnostics).
+
 ## Cross-Platform Notes
 
 This skill uses `npx wicked-brain-call` for all server interaction. The CLI