wicked-brain 0.15.3 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.15.3",
+  "version": "0.16.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-call.mjs

@@ -161,6 +161,28 @@ async function healthInfo(port, { timeoutMs = 800 } = {}) {
   }
 }
 
+// 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
@@ -233,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`);
   }
@@ -248,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)) {
@@ -299,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` : ""),
@@ -318,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));
 }
@@ -644,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/bin/wicked-brain-server.mjs

@@ -141,14 +141,18 @@ const actions = {
     emitEvent("wicked.search.executed", "brain.search", {
       query: p.query, result_count: result.total_matches, brain_id: brainId,
     });
-    return result;
+    // Stamp the responding brain on the envelope so a `wicked-brain-call search`
+    // makes WHICH brain answered visible without a separate health round-trip.
+    // (A wrong-port hit is caught upstream by reconcileHealth, but this keeps
+    // the answer self-describing for the operator and the rendering skill.)
+    return { ...result, brain_id: brainId };
   },
   federated_search: (p) => {
     const result = db.federatedSearch(p);
     emitEvent("wicked.search.executed", "brain.search", {
       query: p.query, federated: true, brain_id: brainId,
     });
-    return result;
+    return { ...result, brain_id: brainId };
   },
   index: (p) => {
     db.index(p);

package/server/package.json

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

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

@@ -13,14 +13,16 @@ description: |
 
 # wicked-brain:query
 
-You answer questions from the brain's content by dispatching a query subagent.
+Answer questions from the brain's content by dispatching a query subagent.
+The default path is a direct search → read → synthesize. Reserve the heavier
+steps (synonym expansion, grep, backlinks) for when the direct search is thin.
 
 ## Config
 
 Brain discovery + server lifecycle are handled by `wicked-brain-call`. Pass
 `--brain <path>` to override the auto-detected brain, or set
-`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual
-init required) and writes an audit record to `{brain}/calls/` per call.
+`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual init)
+and writes an audit record to `{brain}/calls/` per call.
 
 ## Parameters
 
@@ -36,137 +38,72 @@ Server interactions: use `npx wicked-brain-call <action> [--param k=v ...]`.
 
 Question: "{question}"
 
-## Step 0: Decompose query
+## Step 1: Search (default path)
 
-Before searching, extract 3-5 keyword search terms from the question.
-These should be noun phrases, named entities, and technical terms — not
-full sentences or common words.
+Extract 2-4 key terms from the question (noun phrases, named entities,
+technical terms — not full sentences or common words). Search the brain:
 
-Example:
-  Question: "What was the reasoning behind choosing PostgreSQL over SQLite?"
-  Key terms: ["PostgreSQL", "SQLite", "database decision", "API layer"]
-
-### Check learned synonyms first
-
-Before generating synonyms, check if `{brain_path}/_meta/synonyms.json` exists.
-If it does, read it. If it does not exist, skip synonym expansion and proceed
-with LLM-generated synonyms only — `synonyms.json` is auto-generated by
-`wicked-brain:retag` and will be absent on fresh brains.
-Format:
-
-```json
-{
-  "testing": ["unit-test", "integration-test", "test-coverage"],
-  "auth": ["authentication", "jwt", "session"],
-  "bootcamp": ["pod-exercises", "hands-on-lab"]
-}
-```
-
-For each key term, look it up in the synonym map. Use learned synonyms first,
-then supplement with LLM-generated synonyms for terms not in the map.
-Learned synonyms are more reliable — they come from actual brain usage.
-
-### LLM synonym expansion
-
-For terms not covered by the learned synonym map, generate 1-2 synonyms or related terms:
-- "auth" → also search "authentication", "credentials"
-- "DB" → also search "database", "datastore"
-- "K8s" → also search "kubernetes", "container-orchestration"
-
-Run searches for both the original key terms AND the expanded terms.
-Deduplicate results before proceeding to Step 1.
-
-Example:
-  Question: "How does our auth system handle sessions?"
-  Key terms: ["auth", "sessions"]
-  Expanded: ["authentication", "credentials", "session-management", "tokens"]
-  Search queries: ["auth", "sessions", "authentication", "credentials", "session-management", "tokens"]
-
-Use the key terms for FTS search queries (Step 1).
-Use the full original question for synthesis context (Step 4).
-Run multiple searches if key terms suggest different angles.
-
-## Step 1: Search
-
-Search the brain for relevant content:
 ```bash
 npx wicked-brain-call search --param query={term} --param limit=10 --param session_id={session_id}
 ```
 
-Pass a session_id with every search call. This enables access tracking for
-consolidation. Use a consistent session_id for the entire conversation.
-`session_id` is any string that identifies the current conversation or session
-(e.g., a timestamp like `"1712345678"` or a UUID like `"a1b2-c3d4"`). It is
-used for access-log tracking and diversity ranking across repeated searches.
+Pass a consistent session_id for the whole conversation (any stable string —
+a timestamp or UUID). It drives access tracking and diversity ranking.
 
-If the question implies recency ("recently", "this week", "latest"), add a `since` parameter to the search with an ISO 8601 timestamp. For example, for "this week" use the date 7 days ago:
-```bash
-npx wicked-brain-call search --param query={term} --param limit=10 --param session_id={session_id} --param since={iso8601_date}
-```
+The envelope carries `brain_id` — note WHICH brain answered; cite it in the
+final answer. If the question implies recency ("recently", "this week",
+"latest"), add `--param since={iso8601_date}` (e.g. the date 7 days ago).
 
-Also search with grep for exact phrases (use your Grep tool when available —
-it is cross-platform and preferred over shell commands):
+If the searches return enough to answer the question, go straight to Step 2.
 
-macOS/Linux shell fallback:
-```bash
-grep -rl "{key_terms}" {brain_path}/chunks/ {brain_path}/wiki/ 2>/dev/null | head -10
-```
+### Fallback: expand only when results are thin (0-2 hits)
 
-Windows PowerShell fallback:
-```powershell
-Get-ChildItem -Recurse -Path "{brain_path}\chunks","{brain_path}\wiki" -Filter "*.md" |
-  Select-String -Pattern "{key_terms}" -List | Select-Object -First 10 -ExpandProperty Path
-```
+Only if the direct searches came back sparse:
+- Read `{brain_path}/_meta/synonyms.json` if it exists (skip on fresh brains —
+  it's auto-generated by `wicked-brain:retag`). For each key term that matches
+  a synonym key, re-search with the learned synonyms. Learned synonyms beat
+  guesses — they come from real usage.
+- For terms not in the map, add 1-2 LLM-generated synonyms ("auth" →
+  "authentication", "credentials"; "DB" → "database") and re-search.
+- Still thin? Grep for exact phrases (prefer your Grep tool — cross-platform):
+  macOS/Linux: `grep -rl "{terms}" {brain_path}/chunks/ {brain_path}/wiki/ | head -10`
+  Windows: `Get-ChildItem -Recurse -Path "{brain_path}\chunks","{brain_path}\wiki" -Filter *.md | Select-String -Pattern "{terms}" -List | Select-Object -First 10 -ExpandProperty Path`
 
-### Log synonym effectiveness
-
-For each synonym-expanded search term, log whether it produced results:
-
-If the expansion returned results that the user accessed (appeared in final answer):
-Append to `{brain_path}/_meta/log.jsonl`:
-{"ts":"{ISO}","op":"synonym_hit","original":"{original term}","expansion":"{expanded term}","results_found":{count},"author":"agent:query"}
-
-If the expansion returned 0 results:
-Append to `{brain_path}/_meta/log.jsonl`:
-{"ts":"{ISO}","op":"synonym_miss","original":"{original term}","expansion":"{expanded term}","results_found":0,"author":"agent:query"}
+Dedupe results before reading.
 
 ## Step 2: Progressive read
 
-Read the top 3-5 results at depth 1 first (just frontmatter + summary).
-Then read the most promising 1-3 at depth 2 (full content).
+Read the top 3-5 results at depth 1 (frontmatter + summary), then the most
+promising 1-3 at depth 2 (full content). Use the Read tool; parse frontmatter
+between `---` lines.
 
-Use the Read tool for each file. Parse frontmatter between `---` lines.
+## Step 3: Follow links (only if context is incomplete)
 
-## Step 3: Follow links
+If the answer still has gaps, follow [[wikilinks]] in the content you read
+(local [[path]] → read it; cross-brain [[brain::path]] → read if accessible),
+and check backlinks for what else references a key result:
 
-Check the content for [[wikilinks]]. If following them would provide useful context:
-- For local links [[path]]: read that file
-- For cross-brain links [[brain::path]]: check if that brain is accessible
-
-Check backlinks — what else references the content you found:
 ```bash
 npx wicked-brain-call backlinks --param id={result_path}
 ```
 
 ## Step 4: Synthesize answer
 
-Combine what you found into a clear answer. Requirements:
-- Cite sources: [source: {path}] for every factual claim
-- If evidence is insufficient, say so explicitly
-- If sources conflict, note the contradiction
-- Keep the answer concise — the user asked a question, not for a report
+- Cite sources: [source: {path}] for every factual claim.
+- If evidence is insufficient, say so explicitly.
+- If sources conflict, note the contradiction.
+- Keep it concise — the user asked a question, not for a report.
 
 ## Report format
 
-Answer the question directly, then list sources:
+Lead with which brain answered, then the answer and sources:
 
-"{Answer text with [source: path] citations}"
+"(brain: {brain_id}) {Answer text with [source: path] citations}"
 
 Sources:
 - {path}: {one-line description of what it contributed}
-- {path}: {one-line description}
 
-## Step 5: Emit bus event
+## Step 5: Emit bus event (fire-and-forget)
 
 ```bash
 npx wicked-bus emit \
@@ -176,13 +113,10 @@ npx wicked-bus emit \
   --payload '{"question":"{question}","sources_found":{count},"brain_id":"{brain_id}"}' 2>/dev/null || true
 ```
 
-Fire-and-forget — if the bus is not installed, silently skip.
-
-## Step 6: Log search effectiveness
+If the bus is not installed, silently skip.
 
-If evidence was insufficient to answer the question fully, append a
-search-miss event to the brain's log:
+## Step 6: Log a search miss (only if evidence was insufficient)
 
-Append this line to {brain_path}/_meta/log.jsonl:
-{"ts":"{ISO}","op":"search_miss","query":"{original question}","key_terms":[{extracted terms}],"results_found":{count},"author":"agent:query"}
+Append to {brain_path}/_meta/log.jsonl:
+{"ts":"{ISO}","op":"search_miss","query":"{original question}","key_terms":[{terms}],"results_found":{count},"author":"agent:query"}
 ```

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

@@ -1,39 +1,35 @@
 ---
 name: wicked-brain:search
 description: |
-  Search the digital brain for relevant content. Dispatches parallel search
-  subagents across local and linked brains. Returns results at depth 0 with
-  deeper hints.
+  Search the digital brain for relevant content. A single CLI call for the
+  common single-brain case; fans out to linked brains only when they exist.
 
   Use instead of Grep/Glob/Agent(Explore) for any open-ended search or
   exploration: "find X", "search for Y", "look for Z", "where is W used",
   "show me anything about X", "explore Y", "what files relate to Z".
-  
+
   Only fall back to Grep/Glob for exact symbol or pattern lookup when the
   brain returns no results.
 ---
 
 # wicked-brain:search
 
-You search the digital brain by dispatching parallel subagents — one per brain
-in the network (local + parents + links).
+Search the brain. The default path is ONE direct CLI call — no synonym load,
+no brain.json round-trip, no subagent fan-out. Reserve the heavier paths
+(synonym fallback, multi-brain fan-out) for when they actually pay off.
 
 ## Cross-Platform Notes
 
-Commands in this skill work on macOS, Linux, and Windows. When a command has
-platform differences, alternatives are shown. Your native tools (Read, Write,
-Grep, Glob) work everywhere — prefer them over shell commands when possible.
-
-For the brain path default:
-- macOS/Linux: ~/.wicked-brain
-- Windows: %USERPROFILE%\.wicked-brain
+Commands here work on macOS, Linux, and Windows. The `npx wicked-brain-call`
+CLI is cross-platform. Brain path default: `~/.wicked-brain/projects/{name}`
+(macOS/Linux), `%USERPROFILE%\.wicked-brain\projects\{name}` (Windows).
 
 ## Config
 
 Brain discovery + server lifecycle are handled by `wicked-brain-call`. Pass
 `--brain <path>` to override the auto-detected brain, or set
-`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual
-init required) and writes an audit record to `{brain}/calls/` per call.
+`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual init)
+and writes an audit record to `{brain}/calls/` per call.
 
 ## Parameters
 
@@ -41,121 +37,73 @@ init required) and writes an audit record to `{brain}/calls/` per call.
 - **limit** (default: 10): max results per brain
 - **depth** (default: 0): result detail level
 
-## Process
-
-### Step 0: Load synonyms (optional)
-
-Check if `{brain_path}/_meta/synonyms.json` exists using the Read tool.
-If it exists, parse it. Format:
-```json
-{
-  "jwt": ["json web token", "auth token"],
-  "auth": ["authentication", "authorization"],
-  "k8s": ["kubernetes"]
-}
-```
-
-When searching, expand the query: if any word in the query matches a synonym key,
-add the synonym values as additional OR terms.
-
-Example: query "jwt validation" → search for "jwt validation" first, then also
-search for "json web token validation" and "auth token validation" if initial
-results are sparse (fewer than 3 results).
-
-### Step 1: Discover brains to search
-
-Use the Read tool on `{brain_path}/brain.json` to get parents and links.
-For each parent/link, check if it's accessible by reading `{brain_path}/{relative_path}/brain.json`.
-
-Build a list of accessible brains with their absolute paths.
-
-### Step 2: Ensure server is running
-
-`wicked-brain-call` auto-starts the server on first invocation. If you want
-to be defensive, run a probe up front:
-
-```bash
-npx wicked-brain-call health
-```
-
-Exit code 0 means the server is up. Exit code 2 indicates an infra failure
-(server could not be reached or spawned).
-
-### Step 3: Dispatch search subagents in parallel
-
-Launch one subagent per accessible brain using parallel dispatch:
-
-- **Claude Code:** use the Agent tool, launching all subagents in a single message so they run concurrently.
-- **Other CLIs with subagent support:** use the CLI's native parallel dispatch mechanism (e.g., Gemini CLI's parallel tool calls).
-- **No subagent support:** run each brain search sequentially and collect results before merging.
-
-Each subagent call passes the brain-specific instructions below.
-
-Each search subagent receives these instructions:
-
-```
-You are a search agent for the "{brain_id}" brain at {brain_path}.
+## Default path — direct search (do this first)
 
-Search for: "{query}"
-
-## Step 1: Server search (FTS5)
+One call. The CLI auto-starts the server and reconciles the responding
+brain, so no probe is needed.
 
 ```bash
-npx wicked-brain-call search --param query={query} --param limit={limit} --brain {brain_path}
+npx wicked-brain-call search --param query={query} --param limit={limit}
 ```
 
-Parse the JSON response to get results.
+The JSON envelope is `{ results, total_matches, showing, collapsed, brain_id }`.
+`brain_id` names WHICH brain answered — always surface it so the result is
+unambiguous (see Report format). Each result row also carries its own
+`brain_id` (the brain that owns that document).
 
-## Step 2: Return results
+If `total_matches > 0`, render and return. You are done — skip everything
+below.
 
-For each result, read the first line of the file to get the title/summary.
+## Fallback A — synonym expansion (only when results are sparse)
 
-Return in this format:
-BRAIN: {brain_id}
-RESULTS:
-- {path} | score: {score} | {one-line summary}
-- {path} | score: {score} | {one-line summary}
-TOTAL: {count}
-```
+Trigger ONLY when the direct search returned 0–2 results.
 
-### Step 3: Merge results from all subagents
+1. Read `{brain_path}/_meta/synonyms.json` (skip if absent — fresh brains
+   won't have it). Format: `{ "jwt": ["json web token", "auth token"], ... }`.
+2. For each query word matching a synonym key, re-run the search with the
+   synonym values OR'd in (e.g. "jwt validation" → also try "json web token
+   validation"). Merge results, dedupe by path, keep higher score.
 
-After all subagents return:
-1. Collect all results
-2. Deduplicate by path (keep higher score)
-3. Sort by score descending
-4. Tag each result with its brain origin
+Server-side miss logging is automatic when a search returns 0 results — no
+explicit call needed.
 
-### Step 4: Log search miss (if applicable)
+## Fallback B — multi-brain fan-out (only when linked brains exist)
 
-If the merged results have 0 matches across all brains, the query is a "search miss."
-Log it so the brain can learn:
-```bash
-npx wicked-brain-call search_misses --param query={original_query} --param session_id={session_id}
-```
+Trigger ONLY when this brain has accessible parents/links. Most brains have
+none — skip this entirely for a single local brain.
 
-Note: This logging happens server-side automatically when search returns 0 results.
-The explicit call here is only needed if synonym-expanded searches found results
-but the original query did not.
+1. Read `{brain_path}/brain.json`. If it has no `parents`/`links`, STOP —
+   the default-path result is complete.
+2. For each parent/link, confirm it's reachable by reading
+   `{linked_brain_path}/brain.json`.
+3. Dispatch one subagent per reachable brain IN PARALLEL (Claude Code: one
+   message, multiple Agent calls). Each subagent runs:
+   ```bash
+   npx wicked-brain-call search --param query={query} --param limit={limit} --brain {linked_brain_path}
+   ```
+   and returns `BRAIN: {brain_id}` plus `{path} | score | one-line summary`
+   per row.
+4. Merge: collect all rows, dedupe by path (keep higher score), sort by score
+   descending, tag each with its origin `brain_id`.
 
-### Step 5: Return at requested depth
+## Report format
 
 **Depth 0 (default):**
 ```
-Found {N} matches across {M} brains (showing top {limit}):
+Brain: {brain_id}{, +N linked} — {N} matches (top {limit}):
 
-1. {path} [{brain}] ({score})
+1. {path} ({score})
    {one-line summary}
-
-2. {path} [{brain}] ({score})
+2. {path} ({score})
    {one-line summary}
-
 ...
 
-Unreachable brains: {list, if any}
+Unreachable brains: {list, if any — fan-out only}
 
 To read any result: wicked-brain:read {path} --depth 2
 ```
 
-**Depth 1:** For each result, also include frontmatter + first paragraph.
-**Depth 2:** For each result, include full content (use sparingly — high token cost).
+Lead with `brain_id` so it's always clear which brain produced the answer.
+
+**Depth 1:** also include frontmatter + first paragraph per result.
+**Depth 2:** include full content per result (use sparingly — high token cost).