@gcunharodrigues/wrxn 0.3.0 → 0.4.0

package/bin/wrxn.cjs

@@ -11,6 +11,7 @@ const worktree = require('../lib/worktree.cjs');
 const executor = require('../lib/executor.cjs');
 const onboard = require('../lib/onboard.cjs');
 const connect = require('../lib/connect.cjs');
+const brain = require('../lib/brain.cjs');
 const statusline = require('../lib/statusline.cjs');
 const { convert } = require('../lib/convert.cjs');
 const { ingest } = require('../lib/ingest.cjs');
@@ -58,6 +59,10 @@ function parseArgs(argv) {
       args.flags.probe = argv[++i];
     } else if (a === '--distillation') {
       args.flags.distillation = argv[++i];
+    } else if (a === '--limit') {
+      args.flags.limit = argv[++i];
+    } else if (a === '--type') {
+      args.flags.type = argv[++i];
     } else if (a === '--check-report') {
       args.flags['check-report'] = true;
     } else if (a.startsWith('--')) {
@@ -109,6 +114,17 @@ Usage:
       list                       print all registered connections (agent-readable JSON)
       get <name>                 print one connection by name
 
+  wrxn brain query "<q>" [--json] [--limit <n>] [--type <prose|code|NodeType>] [--neighbors] [--root <dir>]
+                                 ask the warm Brain (recon-wrxn's code+prose graph) from the terminal.
+                                 WHOLE-BRAIN by default. Discovers the live serve door via
+                                 .recon-wrxn/serve-endpoint.json and POSTs the query; prints ranked
+                                 hits (name · type · file:line). If the Brain is not warm (no live
+                                 serve), prints a clear error and exits non-zero — no cold load.
+                                 --json emits the structured hits · --limit asks the door for top n ·
+                                 --type post-filters (prose=Page/Section, code=the rest, or an exact
+                                 NodeType) · --neighbors expands each hit to its 1-hop graph neighbors
+                                 (callers/callees/relationships via recon_explain).
+
   wrxn statusline [--inject [--path <script>]]
                                  SYNAPSE live-window writer. With no flag: report whether a statusline
                                  is configured (~/.claude/settings.json) + print the marker-bounded
@@ -408,6 +424,32 @@ async function main(argv) {
     }
   }
 
+  if (cmd === 'brain') {
+    const sub = args._[1];
+    if (sub !== 'query') {
+      process.stderr.write(`wrxn: unknown brain subcommand "${sub || ''}" (expected: query)\n\n${USAGE}\n`);
+      return 2;
+    }
+    const q = args._[2];
+    if (!q) { process.stderr.write('wrxn: brain query requires "<query>"\n'); return 2; }
+    const opts = { json: !!args.flags.json, neighbors: !!args.flags.neighbors };
+    if (args.flags.limit != null) {
+      const n = parseInt(args.flags.limit, 10);
+      if (!Number.isInteger(n) || n <= 0) { process.stderr.write('wrxn: --limit requires a positive integer\n'); return 2; }
+      opts.limit = n;
+    }
+    if (args.flags.type) opts.type = String(args.flags.type);
+    const root = path.resolve(args.flags.root || process.cwd());
+    try {
+      const res = await brain.query(q, opts, { root });
+      process.stdout.write(brain.formatHits(res.hits, opts) + '\n');
+      return 0;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
   if (cmd === 'statusline') {
     const home = process.env.HOME || os.homedir();
     const detection = statusline.detectStatusLine(home);

package/lib/brain.cjs

@@ -0,0 +1,295 @@
+'use strict';
+
+// WRXN brain query (recon-brain-recall-03) — interrogate the warm Brain from the terminal.
+//
+// The Brain is recon-wrxn's unified code+prose knowledge graph, loaded WARM inside the `recon serve`
+// process Claude Code boots for a session. This command reaches it over the loopback find door that
+// serve announces via a discovery file — it is WHOLE-BRAIN (code AND prose, no scope filter by
+// default), the operator's on-demand counterpart to the prose-only proactive Recall hook.
+//
+// Endpoint-first (v1): if no warm door is discoverable, we raise a clear, actionable error and the CLI
+// exits non-zero — there is NO cold one-shot load (that would pay the index + embedder cost the warm
+// serve already absorbs).
+//
+// The query path takes an INJECTED transport + endpoint reader (deps) so its behavior is unit-testable
+// with no live serve — mirrors the injected-invoker seam in lib/connect.cjs and the recall hook's
+// httpTransport. lib/brain.cjs is PACKAGE code (invoked via bin/wrxn.cjs), NOT payload — no manifest
+// entry, consistent with lib/connect.cjs / lib/executor.cjs / lib/onboard.cjs.
+//
+// The discovery contract (serve-endpoint.json {pid,port}, pid-liveness) is duplicated here from the
+// payload recall-surface hook ON PURPOSE: that hook must be node-stdlib-only and self-contained (it
+// ships into installs without the kernel lib), so package code cannot import it. The contract is ~20
+// stable lines — duplicating it across the install boundary is the same self-containment trade the
+// payload hooks make for findInstallRoot.
+
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+
+const ENDPOINT_REL = path.join('.recon-wrxn', 'serve-endpoint.json');
+const FIND_PATH = '/api/tools/recon_find';
+const EXPLAIN_PATH = '/api/tools/recon_explain';
+const TIMEOUT_MS = 5000; // generous: an interactive CLI, not the per-prompt 150ms recall budget
+const MAX_RESPONSE_BYTES = 256 * 1024; // hard cap on an accumulated door response body (anti-flood)
+const PROSE_TYPES = new Set(['Page', 'Section']);
+const WALK_UP_LIMIT = 12;
+
+// ── discovery (the cross-repo warm-door contract) ────────────────────────────────────
+
+// A pid is alive unless process.kill(pid,0) throws. ESRCH = gone; EPERM = owned by another user but
+// alive. Mirrors the cross-repo discovery contract (and the recall hook).
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return !!e && e.code === 'EPERM';
+  }
+}
+
+// Refuse a discovery file another user could have planted, or that is group/world-writable — trusting
+// it would let a hostile workspace point the door host/port at an exfil/injection sink. lstat (not
+// stat) so a symlink's OWN ownership/mode is judged, not its target's. A platform without getuid (no
+// POSIX ownership) skips the uid check but still enforces the mode check. Any fault → not trusted.
+function endpointTrusted(file) {
+  let st;
+  try {
+    st = fs.lstatSync(file);
+  } catch {
+    return false;
+  }
+  if (typeof process.getuid === 'function' && st.uid !== process.getuid()) return false; // foreign owner
+  if ((st.mode & 0o022) !== 0) return false; // group/world-writable
+  return true;
+}
+
+// Walk up from startDir to the first directory carrying .recon-wrxn/serve-endpoint.json; read and
+// validate {pid,port}; trust it only when it is well-owned (not planted), well-formed, and the pid is
+// alive. Returns {pid,port,root} or null (the Brain is not warm: absent, untrusted, malformed, missing
+// fields, or a dead process).
+function discoverEndpoint(startDir) {
+  let dir = startDir || process.cwd();
+  for (let i = 0; i < WALK_UP_LIMIT; i++) {
+    const file = path.join(dir, ENDPOINT_REL);
+    if (fs.existsSync(file)) {
+      if (!endpointTrusted(file)) return null; // foreign-owned or loose perms → not warm
+      let obj;
+      try {
+        obj = JSON.parse(fs.readFileSync(file, 'utf8'));
+      } catch {
+        return null; // malformed → not warm
+      }
+      const pid = Number(obj && obj.pid);
+      const port = Number(obj && obj.port);
+      if (!Number.isInteger(pid) || pid <= 0) return null;
+      if (!Number.isInteger(port) || port <= 0) return null;
+      if (!pidAlive(pid)) return null; // dead process → not warm
+      return { pid, port, root: dir };
+    }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// ── transport (injectable; default = real loopback POST) ─────────────────────────────
+
+// Default transport: a real loopback POST with a hard timeout. Injectable so unit tests never touch
+// the network (mirrors lib/connect.cjs's invoke seam). Resolves {statusCode, body}; rejects on socket
+// error or timeout.
+function httpTransport({ port, path: reqPath, body, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const payload = Buffer.from(JSON.stringify(body));
+    const deadline = timeoutMs || TIMEOUT_MS;
+    let settled = false;
+    let wall = null;
+    const done = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      if (wall) clearTimeout(wall);
+      fn(arg);
+    };
+    const req = http.request(
+      {
+        host: '127.0.0.1',
+        port,
+        path: reqPath,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': payload.length },
+      },
+      (res) => {
+        const chunks = [];
+        let total = 0;
+        res.on('data', (c) => {
+          total += c.length;
+          if (total > MAX_RESPONSE_BYTES) { req.destroy(new Error('brain door response too large')); return; }
+          chunks.push(c);
+        });
+        res.on('end', () => done(resolve, { statusCode: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
+        res.on('error', (e) => done(reject, e));
+      }
+    );
+    req.on('error', (e) => done(reject, e));
+    // Idle timeout (no bytes for `deadline`) AND an independent wall-clock — the latter bounds a trickle
+    // attacker that dribbles bytes to keep the idle timer from ever firing.
+    req.setTimeout(deadline, () => req.destroy(new Error('brain door timeout')));
+    wall = setTimeout(() => req.destroy(new Error('brain door wall-clock timeout')), deadline);
+    req.write(payload);
+    req.end();
+  });
+}
+
+// POST a door tool and return the parsed JSON body. Raises a clean error (never a crash) on a transport
+// fault, a non-200 status, or a non-JSON body.
+async function postTool(transport, port, reqPath, body, timeoutMs) {
+  let resp;
+  try {
+    resp = await transport({ port, path: reqPath, body, timeoutMs: timeoutMs || TIMEOUT_MS });
+  } catch (err) {
+    throw new Error(`Brain door request to ${reqPath} failed: ${err.message}`);
+  }
+  if (!resp || resp.statusCode !== 200) {
+    throw new Error(`Brain door returned HTTP ${resp ? resp.statusCode : 'no-response'} for ${reqPath}`);
+  }
+  try {
+    return JSON.parse(resp.body);
+  } catch {
+    throw new Error(`Brain door returned a malformed (non-JSON) response for ${reqPath}`);
+  }
+}
+
+// ── pure helpers ─────────────────────────────────────────────────────────────────────
+
+function isProse(hit) {
+  return !!hit && PROSE_TYPES.has(hit.type);
+}
+
+// Post-filter hits by --type (the find request can't carry a type ARRAY, so prose=Page+Section is
+// always a post-filter): 'prose' → Page/Section, 'code' → everything else, else an exact NodeType.
+function filterByType(hits, type) {
+  if (!type) return hits;
+  if (type === 'prose') return hits.filter(isProse);
+  if (type === 'code') return hits.filter((h) => !isProse(h));
+  const t = String(type).toLowerCase();
+  return hits.filter((h) => String(h && h.type).toLowerCase() === t);
+}
+
+// Extract a hit's 1-hop neighbors from the door's structured recon_explain response:
+//   { result, neighbors: NeighborHit[] }, NeighborHit = { name, type, file, line, relationship }
+//   relationship ∈ caller | callee | import | importedBy | method | implementedBy | usedBy | testRef
+// Strictly 1-hop. Consumes that real shape directly — no relationship-bucket guesswork. A missing or
+// non-array `neighbors` (e.g. a degraded/empty explain) yields [] so the hit simply has no neighbors.
+function extractNeighbors(resp) {
+  if (!resp || typeof resp !== 'object' || !Array.isArray(resp.neighbors)) return [];
+  return resp.neighbors.map((n) => {
+    const r = n || {};
+    const out = { name: r.name, type: r.type, file: r.file };
+    if (r.line != null) out.line = r.line;
+    if (r.relationship) out.relationship = r.relationship;
+    return out;
+  });
+}
+
+// ── formatting (pure) ────────────────────────────────────────────────────────────────
+
+function hitLine(h) {
+  const name = h.name || '(unnamed)';
+  const type = h.type || '?';
+  const loc = h.file ? `${h.file}${h.line != null ? ':' + h.line : ''}` : '';
+  return loc ? `${name} · ${type} · ${loc}` : `${name} · ${type}`;
+}
+
+function neighborLine(n) {
+  const rel = n.relationship ? ` [${n.relationship}]` : '';
+  return `    - ${hitLine(n)}${rel}`;
+}
+
+// Render results: --json re-emits the structured hits; default is a human text list. With --neighbors,
+// each hit's 1-hop neighbors are listed indented beneath it.
+function formatHits(hits, opts = {}) {
+  const list = Array.isArray(hits) ? hits : [];
+  if (opts.json) return JSON.stringify(list, null, 2);
+  if (!list.length) return 'no results';
+  const lines = [];
+  for (const h of list) {
+    lines.push(hitLine(h));
+    if (opts.neighbors) {
+      const ns = Array.isArray(h.neighbors) ? h.neighbors : [];
+      if (ns.length) for (const n of ns) lines.push(neighborLine(n));
+      else lines.push('    (no 1-hop neighbors)');
+    }
+  }
+  return lines.join('\n');
+}
+
+// ── the query (IO shell over the injected seam) ──────────────────────────────────────
+
+const NOT_WARM =
+  'Brain is not warm — no live recon serve door found (.recon-wrxn/serve-endpoint.json is absent, ' +
+  'malformed, or its process is dead). Open a Claude Code session (which boots recon serve), or run ' +
+  '`recon serve` with the find door enabled, then retry.';
+
+/**
+ * Query the warm Brain. Whole-brain (code+prose) by default.
+ * @param {string} q          the query string
+ * @param {object} opts       { json?, limit?, type?, neighbors? }
+ * @param {object} deps       { root?, discover?, transport?, timeoutMs? } — injected seam for tests
+ * @returns {Promise<{hits: object[]}>}
+ * @throws  a clear error when the Brain is not warm, or on a malformed/non-200 door response.
+ */
+async function query(q, opts = {}, deps = {}) {
+  const term = String(q == null ? '' : q).trim();
+  if (!term) throw new Error('wrxn brain query requires a non-empty query string');
+
+  const startDir = deps.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const discover = deps.discover || discoverEndpoint;
+  const transport = deps.transport || httpTransport;
+  const timeoutMs = deps.timeoutMs || TIMEOUT_MS;
+
+  const door = discover(startDir);
+  if (!door) throw new Error(NOT_WARM);
+
+  const findBody = { query: term };
+  if (Number.isInteger(opts.limit) && opts.limit > 0) findBody.limit = opts.limit;
+
+  const found = await postTool(transport, door.port, FIND_PATH, findBody, timeoutMs);
+  if (!Array.isArray(found.hits)) {
+    throw new Error(
+      'Brain door returned an unexpected response shape (no structured `hits` array) — the recon-wrxn ' +
+      'serve door may predate the structured find response.'
+    );
+  }
+
+  let hits = filterByType(found.hits, opts.type);
+
+  // --neighbors: 1-hop expansion per hit via recon_explain — the ONLY place 1-hop lives. A per-hit
+  // explain failure degrades to empty neighbors (the find already succeeded); it never crashes.
+  if (opts.neighbors) {
+    for (const h of hits) {
+      const explainBody = { name: h.name };
+      if (h.file) explainBody.file = h.file;
+      try {
+        h.neighbors = extractNeighbors(await postTool(transport, door.port, EXPLAIN_PATH, explainBody, timeoutMs));
+      } catch {
+        h.neighbors = [];
+      }
+    }
+  }
+
+  return { hits };
+}
+
+module.exports = {
+  query,
+  formatHits,
+  discoverEndpoint,
+  pidAlive,
+  httpTransport,
+  filterByType,
+  extractNeighbors,
+  isProse,
+  FIND_PATH,
+  EXPLAIN_PATH,
+  PROSE_TYPES,
+};

package/migrations/003-serve-http-door.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 003 — open the warm-brain HTTP find door on existing installs (recon-brain-recall-05).
+ *
+ * The door is the concurrent, read-only, loopback HTTP transport `recon serve` runs alongside its
+ * stdio MCP transport when `.recon-wrxn.json` carries `serveHttp:true` (recon-wrxn ADR 0003) — the one
+ * warm index the per-prompt Recall hook and `wrxn brain query` reach. A fresh install gets the door
+ * from the updated seed, but `.recon-wrxn.json` is SEEDED (operator-owned), so `wrxn update` never
+ * overwrites it — an install created before this release would keep the door shut forever unless a
+ * migration flips it.
+ *
+ * up() sets `serveHttp:true` in place, PRESERVING every existing operator field (projects, ignore,
+ * watch, …) — it touches only the door bit, it does not retrofit the rest of the new template.
+ * Defensive like 002/001: a missing config is a no-op (a non-recon install has nothing to migrate), an
+ * already-open door is an idempotent no-op, and a corrupt/unparseable (or non-object) config is left
+ * untouched — never clobber a hand-edited file. `version` is a frozen 0.4.0: it runs via `wrxn update`
+ * once the install reaches the release that carries the door (the same release that bumps the recon-wrxn
+ * pin to the wrxn.3 build whose serve actually honors serveHttp).
+ */
+module.exports = {
+  id: '003',
+  version: '0.4.0',
+  up(ctx) {
+    const cfgPath = path.join(ctx.target, '.recon-wrxn.json');
+    if (!fs.existsSync(cfgPath)) return; // no recon config → nothing to migrate
+
+    let cfg;
+    try {
+      cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    } catch {
+      return; // malformed operator config → leave it untouched, never clobber
+    }
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) return; // not a config object → leave it
+
+    if (cfg.serveHttp === true) return; // door already open → idempotent no-op
+
+    cfg.serveHttp = true; // open the door; every other operator field is preserved
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "WRXN Kernel — installable AI operating system. Two profiles (project | workspace), pull-based updates, managed/seeded/state file classes.",
   "bin": {
     "wrxn": "bin/wrxn.cjs"
@@ -16,7 +16,7 @@
     "test": "node --test"
   },
   "dependencies": {
-    "recon-wrxn": "6.0.0-wrxn.2"
+    "recon-wrxn": "6.0.0-wrxn.3"
   },
   "engines": {
     "node": ">=20"

package/payload/.claude/hooks/recall-surface.cjs

@@ -1,43 +1,48 @@
 #!/usr/bin/env node
 'use strict';
 
-// WRXN recall-surface hook — per-prompt recall nudge (wrxn-kernel-11).
-// UserPromptSubmit. The symmetric RECALL half of reference-detect's CAPTURE: on each prompt it
-// matches the prompt's SALIENT terms against the wiki knowledge tiers (concepts/decisions/gotchas)
-// and, ONLY when a page matches, injects a <recall-surface> nudge — "you already have a page on X,
-// recall it before re-deriving / re-asking the operator". Gated → silent on non-matching prompts.
+// WRXN recall-surface hook — proactive PROSE Recall via the warm Brain door (recon-brain-recall-04).
+// UserPromptSubmit. Replaces the old wiki-substring engine: on each prompt it discovers recon-wrxn's
+// warm serve door, POSTs a prose-scoped hybrid query, and — ONLY when a hit clears the relevance gate
+// — injects a compact <recall-surface> block. Implements ADR 0002.
 //
-// Self-contained: ships into installs, MUST NOT import the kernel lib (node stdlib only). The kernel
-// wiki engine is substring (not BM25) — recall here is a deliberately simple distinct-salient-term
-// count, ranked, top-N. Fail-open: any fault emits {} — the hook NEVER blocks a prompt.
+// The gate (per arm, NEVER the fused RRF score): a prose hit qualifies on the semantic cosine FLOOR
+// (>= 0.4) OR on CONSENSUS (it surfaced in both the BM25 and the dense arm). Nothing clears ⇒ Abstain.
+// Prose only — hits are post-filtered to Page/Section, so code symbols never surface here (they stay
+// on the agent's on-demand recon_* / `wrxn brain query` path).
+//
+// Self-contained: ships into installs, MUST NOT import the kernel lib or recon — node stdlib ONLY
+// (http / fs / path). Fail-open SILENT: a cold/missing/dead door, a slow door, a non-200, malformed
+// JSON, or ANY fault emits {} — the hook NEVER blocks a prompt and never delays it past the hard
+// client timeout. There is NO substring fallback (a weak fallback can itself harm — ADR 0002).
 //
 // Contract: UserPromptSubmit event JSON on stdin → envelope JSON on stdout (exit 0).
+//   inject → { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": "<recall-surface>…" } }
+//   abstain → {}
 
 const fs = require('fs');
+const http = require('http');
 const path = require('path');
 
-const TIERS = ['concepts', 'decisions', 'gotchas']; // knowledge tiers; sessions (episodic) excluded
-const TOP_N = 2;
-const MIN_PROMPT_LEN = 8; // skip trivial prompts ("ok", "yes")
-// A page must share >=2 DISTINCT salient terms with the prompt to surface — the substring engine has
-// no BM25 score, so a single shared common word is too weak a signal (anti-noise). Tradeoff: a genuine
-// single-strong-term recall is silenced (fail-silent — a missed nudge is safer than a false one).
-const MIN_DISTINCT = 2;
-const MAX_BLOCK_CHARS = 600;
-
-// Drop stopwords + short tokens so common words don't match common page words (anti-noise).
-const STOPWORDS = new Set(['about', 'after', 'again', 'against', 'because', 'before', 'being', 'between',
-  'could', 'does', 'doing', 'down', 'during', 'each', 'from', 'further', 'have', 'having', 'here', 'how',
-  'into', 'just', 'like', 'more', 'most', 'only', 'other', 'over', 'same', 'should', 'some', 'such',
-  'than', 'that', 'their', 'them', 'then', 'there', 'these', 'they', 'this', 'those', 'through', 'under',
-  'until', 'very', 'want', 'what', 'when', 'where', 'which', 'while', 'with', 'would', 'your', 'today',
-  'tell', 'show', 'give', 'make', 'need', 'know', 'help', 'please', 'thing', 'stuff', 'really', 'going']);
+const MIN_PROMPT_LEN = 8;          // skip trivial prompts ("ok", "yes")
+const MAX_QUERY_CHARS = 512;       // trim the prompt before querying the door
+const FETCH_LIMIT = 15;            // ask the door WIDE — fetch is decoupled from inject so prose ranked
+                                   // below the whole-brain code hits is not truncated before we filter
+const TIMEOUT_MS = 150;            // hard client budget — never delay a prompt past this
+const MAX_RESPONSE_BYTES = 256 * 1024; // hard cap on an accumulated door response body (anti-flood)
+const TOP_N = 3;                   // inject at most 3 hits (the wide fetch is post-filtered down to this)
+const MAX_BLOCK_CHARS = 600;       // injection size cap (ADR 0002: inject little, high-signal)
+const SEMANTIC_FLOOR = 0.4;        // dense cosine floor (reused from P1.5)
+const PROSE_TYPES = new Set(['Page', 'Section']); // prose scope — drop code symbols
+const ENDPOINT_REL = path.join('.recon-wrxn', 'serve-endpoint.json');
+const FIND_PATH = '/api/tools/recon_find';
 
 function emit(envelope) {
   process.stdout.write(JSON.stringify(envelope));
   process.exit(0);
 }
 
+// Walk up from cwd / CLAUDE_PROJECT_DIR to the install root carrying wrxn.install.json.
 function findInstallRoot(startDir) {
   let dir = startDir || process.env.CLAUDE_PROJECT_DIR || process.cwd();
   for (let i = 0; i < 12; i++) {
@@ -49,79 +54,254 @@ function findInstallRoot(startDir) {
   return null;
 }
 
-// De-duped salient content tokens (lowercased, >=4 chars, non-stopword).
-function salientTerms(prompt) {
-  const seen = new Set();
-  for (const tok of (String(prompt || '').toLowerCase().match(/[a-z][a-z0-9]{3,}/g) || [])) {
-    if (!STOPWORDS.has(tok)) seen.add(tok);
+// ── the gate (PURE) ────────────────────────────────────────────────────────────────
+
+function isProse(hit) {
+  return !!hit && PROSE_TYPES.has(hit.type);
+}
+
+// Consensus = the hit surfaced in BOTH the BM25 and the dense arm (the find response's `sources`
+// provenance). A consensus hit qualifies even below the cosine floor.
+function hasConsensus(hit) {
+  const s = hit && hit.sources;
+  return Array.isArray(s) && s.includes('bm25') && s.includes('semantic');
+}
+
+// Qualify on the PER-ARM signal only: the semantic cosine floor OR consensus. NEVER the fused
+// `score` (RRF is a rank-based consensus, not a relevance magnitude — ADR 0002). The floor clause
+// requires the dense arm to actually be PRESENT in `sources` (not just a stray semanticScore) —
+// today these co-occur, but this is a defense against a future producer emitting a score without the
+// 'semantic' tag. An absent/NaN semanticScore can never clear the floor; only consensus rescues it.
+function qualifies(hit) {
+  const sem = Number(hit && hit.semanticScore);
+  const s = hit && hit.sources;
+  const hasSemantic = Array.isArray(s) && s.includes('semantic');
+  const floorOk = Number.isFinite(sem) && sem >= SEMANTIC_FLOOR && hasSemantic;
+  return floorOk || hasConsensus(hit);
+}
+
+function slugify(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+}
+
+// A stable slug for a hit: the prose file's basename (sans extension), else a slugified name.
+function slugOf(hit) {
+  if (hit.file) {
+    const base = path.basename(String(hit.file)).replace(/\.[^.]+$/, '');
+    if (base) return base.slice(0, 48);
   }
-  return [...seen];
-}
-
-// Score each wiki page by the count of DISTINCT salient terms it contains; keep pages with >=1.
-function recall(root, terms) {
-  const hits = [];
-  for (const tier of TIERS) {
-    const dir = path.join(root, '.wrxn', 'wiki', tier);
-    let names;
-    try {
-      names = fs.readdirSync(dir).filter((n) => n.endsWith('.md'));
-    } catch {
-      continue; // tier absent → skip
-    }
-    for (const name of names) {
-      let text;
-      try {
-        text = fs.readFileSync(path.join(dir, name), 'utf8').toLowerCase();
-      } catch {
-        continue;
-      }
-      const matched = terms.filter((t) => text.includes(t)).length;
-      if (matched >= MIN_DISTINCT) hits.push({ slug: name.replace(/\.md$/, ''), tier, score: matched });
-    }
+  return slugify(hit.name) || 'untitled';
+}
+
+// The one-line descriptor. NOTE: a recon FindHit carries NO body text — only name/file/line/scores —
+// so the snippet is the hit's NAME (the page title / section heading), the most descriptive line
+// available. (Follow-up: if the door later surfaces a per-hit text excerpt, prefer it here.)
+function snippetOf(hit) {
+  const s = String(hit.name || hit.file || '').replace(/\s+/g, ' ').trim();
+  return s.length > 100 ? s.slice(0, 99) + '…' : s;
+}
+
+// Render the qualifying hits into the <recall-surface> block, guaranteed <= MAX_BLOCK_CHARS and
+// always closed. Drops trailing bullets first, then hard-truncates the last line if it still overflows.
+function renderBlock(hits) {
+  const head = '<recall-surface>';
+  const intro = 'Knowledge already in your Brain, recalled for this prompt — read it before re-deriving or re-asking the operator:';
+  const foot = '</recall-surface>';
+  const bullets = hits.map((h) => `- ${slugOf(h)} — ${snippetOf(h)}`);
+  const assemble = (bs) => [head, intro, ...bs, foot].join('\n');
+  const kept = bullets.slice();
+  while (kept.length > 1 && assemble(kept).length > MAX_BLOCK_CHARS) kept.pop();
+  let block = assemble(kept);
+  if (block.length > MAX_BLOCK_CHARS) {
+    block = block.slice(0, MAX_BLOCK_CHARS - foot.length - 1).replace(/\s+\S*$/, '').trimEnd() + '\n' + foot;
+  }
+  return block;
+}
+
+// PURE: prose-filter → gate → top-N → format. Returns the block string, or null (Abstain).
+function decideRecall(hits) {
+  const list = Array.isArray(hits) ? hits : [];
+  const qualified = list.filter((h) => isProse(h) && qualifies(h)).slice(0, TOP_N);
+  if (!qualified.length) return null;
+  return renderBlock(qualified);
+}
+
+// ── the door (IO shell, injectable transport) ───────────────────────────────────────
+
+// A pid is alive unless process.kill(pid,0) throws ESRCH. EPERM means it exists (owned by another
+// user) — still alive. Mirrors the cross-repo discovery contract.
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return !!e && e.code === 'EPERM';
+  }
+}
+
+// Refuse a discovery file another user could have planted, or that is group/world-writable — trusting
+// it would let a hostile workspace point the door host/port at an exfil/injection sink (the hook feeds
+// the door's response into the prompt context). lstat (not stat) so a symlink's OWN ownership/mode is
+// judged. A platform without getuid skips the uid check but still enforces the mode check. Any fault →
+// not trusted (treated as not-warm).
+function endpointTrusted(file) {
+  let st;
+  try {
+    st = fs.lstatSync(file);
+  } catch {
+    return false;
   }
-  // Highest distinct-term count first; ties broken by slug for determinism.
-  hits.sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
-  return hits.slice(0, TOP_N);
+  if (typeof process.getuid === 'function' && st.uid !== process.getuid()) return false; // foreign owner
+  if ((st.mode & 0o022) !== 0) return false; // group/world-writable
+  return true;
 }
 
-function block(hits) {
-  const lines = [
-    '<recall-surface>',
-    'You already have captured page(s) on this topic — READ before answering (do not re-derive, do',
-    'not ask the operator to re-explain). Recall with: node .wrxn/wiki.cjs recall "<slug>"',
-    ...hits.map((h) => `- ${h.slug} (${h.tier})`),
-    '</recall-surface>',
-  ].join('\n');
-  return lines.length <= MAX_BLOCK_CHARS ? lines : `${lines.slice(0, MAX_BLOCK_CHARS - 18)}\n</recall-surface>`;
+// Discover the warm serve door from <root>/.recon-wrxn/serve-endpoint.json = {pid,port}. Returns
+// {pid,port} only when the file is well-owned (not planted), present, well-formed, and the pid is
+// alive — else null (not warm).
+function discoverEndpoint(root) {
+  const file = path.join(root, ENDPOINT_REL);
+  if (!endpointTrusted(file)) return null; // absent, foreign-owned, or loose perms → not warm
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null; // absent (race)
+  }
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+  } catch {
+    return null; // malformed
+  }
+  const pid = Number(obj && obj.pid);
+  const port = Number(obj && obj.port);
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0) return null;
+  if (!pidAlive(pid)) return null; // dead pid → not warm
+  return { pid, port };
+}
+
+// Default transport: a real POST over http with a hard timeout. Resolves {statusCode, body}; rejects
+// on socket error or timeout. Injectable so unit tests never touch the network (mirrors connect.cjs).
+function httpTransport({ port, path: reqPath, body, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const payload = Buffer.from(JSON.stringify(body));
+    const deadline = timeoutMs || TIMEOUT_MS;
+    let settled = false;
+    let wall = null;
+    const done = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      if (wall) clearTimeout(wall);
+      fn(arg);
+    };
+    const req = http.request(
+      {
+        host: '127.0.0.1',
+        port,
+        path: reqPath,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': payload.length },
+      },
+      (res) => {
+        const chunks = [];
+        let total = 0;
+        res.on('data', (c) => {
+          total += c.length;
+          if (total > MAX_RESPONSE_BYTES) { req.destroy(new Error('recall door response too large')); return; }
+          chunks.push(c);
+        });
+        res.on('end', () => done(resolve, { statusCode: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
+        res.on('error', (e) => done(reject, e));
+      }
+    );
+    req.on('error', (e) => done(reject, e));
+    // Idle timeout (no bytes for `deadline`) AND an independent wall-clock: the latter bounds a trickle
+    // attacker that dribbles bytes to keep the idle timer from ever firing past the hook budget.
+    req.setTimeout(deadline, () => req.destroy(new Error('recall door timeout')));
+    wall = setTimeout(() => req.destroy(new Error('recall door wall-clock timeout')), deadline);
+    req.write(payload);
+    req.end();
+  });
 }
 
-function main() {
+// IO shell: discover the door, POST the prose query, gate the hits. Returns the block string or null.
+// `transport` is injected in tests; production uses httpTransport. Sends NO `type` (recon_find takes a
+// single NodeType, not an array) — prose scope is enforced by decideRecall's post-filter.
+async function recallFromDoor(root, prompt, { transport, timeoutMs } = {}) {
+  const door = discoverEndpoint(root);
+  if (!door) return null; // not warm → Abstain (silent)
+  const query = String(prompt || '').trim().slice(0, MAX_QUERY_CHARS);
+  if (!query) return null;
+  let resp;
+  try {
+    resp = await (transport || httpTransport)({
+      port: door.port,
+      path: FIND_PATH,
+      body: { query, limit: FETCH_LIMIT },
+      timeoutMs: timeoutMs || TIMEOUT_MS,
+    });
+  } catch {
+    return null; // timeout / connection refused / abort → silent
+  }
+  if (!resp || resp.statusCode !== 200) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(resp.body);
+  } catch {
+    return null; // malformed body → silent
+  }
+  return decideRecall(Array.isArray(parsed.hits) ? parsed.hits : []);
+}
+
+// ── entrypoint ──────────────────────────────────────────────────────────────────────
+
+async function main() {
   let event = {};
   try {
     const stdin = fs.readFileSync(0, 'utf8');
     if (stdin.trim()) event = JSON.parse(stdin);
   } catch {
-    emit({});
+    return emit({});
   }
 
-  const root = findInstallRoot();
-  if (!root) emit({});
+  const root = findInstallRoot(event.cwd);
+  if (!root) return emit({});
 
   const prompt = typeof event.prompt === 'string' ? event.prompt : '';
-  if (prompt.trim().length < MIN_PROMPT_LEN) emit({});
-
-  const terms = salientTerms(prompt);
-  if (!terms.length) emit({});
+  if (prompt.trim().length < MIN_PROMPT_LEN) return emit({});
 
-  const hits = recall(root, terms);
-  if (!hits.length) emit({}); // no captured page matched → silent (the gate)
+  let block = null;
+  try {
+    block = await recallFromDoor(root, prompt.trim());
+  } catch {
+    return emit({});
+  }
+  if (!block) return emit({}); // nothing cleared the gate → Abstain
 
-  emit({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: block(hits) } });
+  return emit({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: block } });
 }
 
-try {
-  main();
-} catch {
-  emit({});
+if (require.main === module) {
+  main().catch(() => emit({}));
 }
+
+module.exports = {
+  decideRecall,
+  recallFromDoor,
+  discoverEndpoint,
+  httpTransport,
+  pidAlive,
+  isProse,
+  hasConsensus,
+  qualifies,
+  renderBlock,
+  findInstallRoot,
+  SEMANTIC_FLOOR,
+  PROSE_TYPES,
+};

package/payload/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "recon-wrxn": {
       "command": "npx",
-      "args": ["-y", "recon-wrxn@6.0.0-wrxn.2", "serve"]
+      "args": ["-y", "recon-wrxn@6.0.0-wrxn.3", "serve"]
     }
   }
 }

package/payload/.recon-wrxn.json

@@ -1,6 +1,8 @@
 {
   "projects": [],
   "embeddings": false,
+  "serveEmbed": true,
+  "serveHttp": true,
   "watch": true,
   "ignore": []
 }