@ijfw/memory-server 1.5.0 → 1.5.3

package/src/server.js

@@ -16,11 +16,19 @@ import { createInterface } from 'readline';
 import {
   existsSync, mkdirSync, readFileSync, writeFileSync,
   appendFileSync, readdirSync, statSync, renameSync, unlinkSync,
-  openSync, closeSync, fsyncSync, realpathSync
+  openSync, closeSync, fsyncSync, realpathSync,
+  accessSync, constants as fsConstants
 } from 'fs';
 import { join, resolve, isAbsolute, normalize, basename, dirname } from 'path';
+import { resolveBrainPaths } from './brain/paths.js';
+import { migrateFactsInternalOnce } from './brain/migrate-facts-internal-once.js';
+// v1.5.2.1 F3: fs-layout migrations live in their own directory with their
+// own registry (not auto-discovered by the SQL migration-runner). Invoked
+// inside __mainEntryPoint() only — never as a top-level side effect of
+// importing server.js.
+import { runLayoutMigrations } from './memory/layout-migrations/index.js';
 import { homedir } from 'os';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { createHash, randomBytes } from 'crypto';
 
 // Read version dynamically from package.json so bumps don't require a code change.
@@ -30,6 +38,7 @@ const PKG_VERSION = (() => {
   catch { return 'unknown'; }
 })();
 import { checkPrompt } from './prompt-check.js';
+import { handleIjfwBrain, IJFW_BRAIN_VERBS } from './handlers/brain-handler.js';
 import { applyCaps, CAP_CONTENT } from './caps.js';
 import { ensureSchemaHeader, SCHEMA_HEADER } from './schema.js';
 import { searchCorpus } from './search-bm25.js';
@@ -41,6 +50,11 @@ import { maybeRerankWithVectors } from './search-hybrid.js';
 import { crossProjectSearch } from './cross-project-search.js';
 // R2-E -- single source of truth for markdown/HTML/control-char defanger.
 import { sanitizeContent } from './sanitizer.js';
+// v1.5.1 R4-H3 — secret redaction on the direct ijfw_store write path.
+// The redactor is already wired into FTS5 ingest + auto-memorize; the
+// direct MCP store was the one bypass, so a secret pasted into an
+// ijfw_store call could land in .ijfw/memory/*.md cleartext.
+import { redactSecrets } from './redactor.js';
 // H5.5 / H5.6 — ingest-time fact extraction + semantic dedup. Closes
 // memory-engine.md competitor gaps (mem0/Zep extract facts; Graphiti dedups).
 // Both are pure-JS, zero-LLM, deterministic.
@@ -271,14 +285,16 @@ function validatePath(raw) {
 function isWritable(dir) {
   try {
     if (!existsSync(dir)) {
-      // Try to create it; if that works it's writable.
+      // Try to create it; if mkdir fails, treat as non-writable.
       mkdirSync(dir, { recursive: true });
       return true;
     }
-    // Exists -- probe with a tmp file.
-    const probe = join(dir, `.ijfw-probe-${process.pid}-${Date.now()}`);
-    writeFileSync(probe, '');
-    unlinkSync(probe);
+    // v1.5.2.1 H-1 (Lens 1): previously wrote+unlinked a probe file
+    // (`.ijfw-probe-<pid>-<ts>`). That broke the "importing server.js
+    // produces ZERO filesystem artifacts" contract: the probe leaked
+    // under inotify/fswatch even when self-tests in tmpdir saw nothing.
+    // accessSync(W_OK) gives the same writability signal with no I/O.
+    accessSync(dir, fsConstants.W_OK);
     return true;
   } catch {
     return false;
@@ -307,6 +323,33 @@ function safeProjectDir() {
 const PROJECT_DIR = safeProjectDir();
 const PROJECT_HASH = createHash('sha256').update(PROJECT_DIR).digest('hex').slice(0, 12);
 const IJFW_DIR = join(PROJECT_DIR, '.ijfw');
+// REPO_ROOT is the parent of .ijfw/ — required by resolveBrainPaths.
+const REPO_ROOT = dirname(IJFW_DIR);
+// paths() re-reads the layout sentinel on every call so a long-running server
+// process picks up the migration-010 sentinel flip without restart.
+function paths() { return resolveBrainPaths(REPO_ROOT); }
+// v1.5.2.1 F1: __isServerEntryPoint gates ALL top-level imperative effects
+// (facts relocation, fs-layout migration, dir bootstrap, WS client, stdio
+// transport, signal handlers). Without this gate, importing server.js from
+// a test or helper would fire every side-effect against the importer's cwd:
+// stray `ijfw/`, `.ijfw/`, .ijfw-probe-* files in repos that aren't IJFW
+// projects. The gate uses realpathSync on BOTH sides because process.argv[1]
+// can be a symlinked bin shim (npm global installs) while import.meta.url
+// resolves to the real path inside node_modules.
+const __isServerEntryPoint = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    const entryReal = realpathSync(process.argv[1]);
+    const selfReal = realpathSync(fileURLToPath(import.meta.url));
+    return entryReal === selfReal;
+  } catch (e) {
+    if (process.env.IJFW_DEBUG) {
+      try { process.stderr.write(`[ijfw entry-gate] check failed: ${e.message}\n`); } catch {}
+    }
+    return false;
+  }
+})();
+// Back-compat values for the line-2349 re-export. New code MUST use paths().memoryDir / paths().sessionsDir.
 const MEMORY_DIR = join(IJFW_DIR, 'memory');
 const SESSIONS_DIR = join(IJFW_DIR, 'sessions');
 const GLOBAL_DIR = join(homedir(), '.ijfw', 'memory');
@@ -342,14 +385,18 @@ const NATIVE_CLAUDE_DIR = join(
 // Failures here do NOT write to stderr during startup -- any stderr byte during
 // MCP handshake can make strict clients (incl. Claude Code) mark the server
 // as failed. Subsequent store/read calls surface structured errors instead.
-try {
-  [MEMORY_DIR, SESSIONS_DIR].forEach(dir => {
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  });
-} catch { /* handleStore/recall surface structured errors on first use */ }
-try {
-  if (!existsSync(GLOBAL_DIR)) mkdirSync(GLOBAL_DIR, { recursive: true });
-} catch { /* handleStore reports on attempted write */ }
+// v1.5.2.1 F1: called from __mainEntryPoint() so importing server.js no
+// longer creates directories in the importer's cwd.
+function __bootstrapDirs() {
+  try {
+    [paths().memoryDir, paths().sessionsDir].forEach(dir => {
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    });
+  } catch { /* handleStore/recall surface structured errors on first use */ }
+  try {
+    if (!existsSync(GLOBAL_DIR)) mkdirSync(GLOBAL_DIR, { recursive: true });
+  } catch { /* handleStore reports on attempted write */ }
+}
 
 // R2-E -- sanitizeContent moved to mcp-server/src/sanitizer.js so MCP stores
 // and auto-memorize stores share a single implementation. Imported above.
@@ -462,7 +509,7 @@ function emitRecallObservation({ context_hint, from_project } = {}) {
 
 // --- Storage helpers ---
 function appendToJournal(entry) {
-  const journalPath = join(MEMORY_DIR, 'project-journal.md');
+  const journalPath = join(paths().memoryDir, 'project-journal.md');
   const ts = new Date().toISOString();
   const line = `- [${ts}] ${entry}`;
   return appendLine(journalPath, line);
@@ -472,7 +519,7 @@ function appendToJournal(entry) {
 // similar to Claude's native auto-memory format: YAML frontmatter plus a body with
 // Why / How-to-apply sections. This is the format users retrieve well from.
 function appendStructuredToKnowledge({ type, summary, content, why, howToApply, tags }) {
-  const filepath = join(MEMORY_DIR, 'knowledge.md');
+  const filepath = join(paths().memoryDir, 'knowledge.md');
   const ts = new Date().toISOString();
   const tagLine = tags && tags.length ? tags.join(', ') : '';
   const block = [
@@ -519,10 +566,10 @@ function appendToGlobalPrefs(entry, tags = []) {
 }
 
 function readKnowledgeBase() {
-  return readOr(join(MEMORY_DIR, 'knowledge.md'));
+  return readOr(join(paths().memoryDir, 'knowledge.md'));
 }
 function readHandoff() {
-  return readOr(join(MEMORY_DIR, 'handoff.md'));
+  return readOr(join(paths().memoryDir, 'handoff.md'));
 }
 // Read Claude Code native auto-memory for this project. Returns concatenated
 // sanitized content of all project_*.md files (skipping MEMORY.md index).
@@ -591,25 +638,8 @@ function readGlobalKnowledge() {
   ).join('\n\n');
 }
 
-function getSessionCount() {
-  try {
-    if (!existsSync(SESSIONS_DIR)) return 0;
-    return readdirSync(SESSIONS_DIR).filter(f => f.endsWith('.md')).length;
-  } catch {
-    return 0;
-  }
-}
-
-function getDecisionCount() {
-  const journal = readOr(join(MEMORY_DIR, 'project-journal.md'));
-  if (!journal) return 0;
-  // Match only journal entry lines (we now prefix with - [timestamp]) -- not
-  // arbitrary list bullets that might appear in seeded content.
-  return (journal.match(/^- \[\d{4}-\d{2}-\d{2}T/gm) || []).length;
-}
-
 function getRecentJournalEntries(count = 5) {
-  const journal = readOr(join(MEMORY_DIR, 'project-journal.md'));
+  const journal = readOr(join(paths().memoryDir, 'project-journal.md'));
   if (!journal) return '';
   const entries = journal.split('\n').filter(l => /^- \[\d{4}-/.test(l));
   return entries.slice(-count).join('\n');
@@ -620,7 +650,7 @@ function getRecentJournalEntries(count = 5) {
 // down to ms; collisions would only happen on near-simultaneous writes which
 // our atomic-append + fs flush ordering already serialise).
 function getRecentMemoriesForDedup(limit = 50) {
-  const journal = readOr(join(MEMORY_DIR, 'project-journal.md'));
+  const journal = readOr(join(paths().memoryDir, 'project-journal.md'));
   if (!journal) return [];
   const lines = journal.split('\n').filter(l => /^- \[\d{4}-/.test(l));
   // Most-recent-last in the file → reverse so findNearDuplicate sees newest first.
@@ -635,7 +665,18 @@ function getRecentMemoriesForDedup(limit = 50) {
 
 // H5.5 — sidecar file for structured facts (one JSON object per line).
 // Append-only; consumed by handleRecall({context_hint:'facts'}).
-const FACTS_FILE = join(MEMORY_DIR, 'facts.jsonl');
+// v1.5.2 F5: now resolves via paths().factsJsonl (.ijfw/facts.jsonl) — internal
+// hidden location per Task 3 design. The one-shot migrateFactsInternalOnce()
+// call above relocated existing data from the legacy .ijfw/memory/ location.
+//
+// v1.5.2.1 H-2 (Lens 1): use accessor functions for internal callers so that
+// a layout-migration sentinel flip mid-process (rare but possible) is picked
+// up without a server restart. The named export `FACTS_FILE` (consumed by
+// test-server-ingest.js as a one-shot import-time snapshot) is preserved
+// below for back-compat.
+function factsFile() { return paths().factsJsonl; }
+function factsDbFile() { return paths().indexDb; }
+const FACTS_FILE = factsFile();
 
 // Stable short id for joining a fact back to its journal entry. We don't have
 // a uuid; the journal-line text itself + ts is unique enough for cross-ref.
@@ -650,7 +691,8 @@ function appendFactsToSidecar(facts, meta) {
   if (!Array.isArray(facts) || facts.length === 0) return { ok: true, written: 0 };
   try {
     const lines = facts.map(f => factToJsonl(f, meta)).join('\n') + '\n';
-    appendFileSync(FACTS_FILE, lines);
+    // v1.5.2.1 H-2: factsFile() re-reads layout sentinel each call.
+    appendFileSync(factsFile(), lines);
     return { ok: true, written: facts.length };
   } catch (err) {
     // Non-fatal: facts are augmentation, not source-of-truth. Journal already
@@ -664,12 +706,16 @@ function appendFactsToSidecar(facts, meta) {
 // table (queryable point-in-time view) stay co-located. Lazy-opened on first
 // use so a project that never stores a memory never pays the better-sqlite3
 // load cost.
-const FACTS_DB_FILE = join(MEMORY_DIR, 'facts.db');
+// v1.5.2 F5: now resolves via paths().indexDb (.ijfw/index/memory.db) — internal
+// hidden location per Task 3 design. Data migrated by migrateFactsInternalOnce().
+// v1.5.2.1 H-2: FACTS_DB_FILE is the export-time snapshot; internal use goes
+// through factsDbFile() above so mid-process sentinel flips are honored.
+const FACTS_DB_FILE = factsDbFile();
 let _factsDbHandle = null;
 function getFactsDb() {
   if (_factsDbHandle) return _factsDbHandle;
   try {
-    _factsDbHandle = openTemporalDbSync(FACTS_DB_FILE);
+    _factsDbHandle = openTemporalDbSync(factsDbFile());
     return _factsDbHandle;
   } catch (err) {
     // Non-fatal. JSONL sidecar still gets written; we just lose the bi-temporal
@@ -804,10 +850,10 @@ async function searchMemory(query, limit = 10, scope = 'project', opts = {}) {
   }
 
   const sources = [
-    { name: 'team',          content: readTeamKnowledge(),                          boost: 1.25, path: join(MEMORY_DIR, 'team-knowledge.md') },
-    { name: 'knowledge',     content: readKnowledgeBase(),                          boost: 1.15, path: join(MEMORY_DIR, 'knowledge.md') },
-    { name: 'journal',       content: readOr(join(MEMORY_DIR, 'project-journal.md')), boost: 1.0,  path: join(MEMORY_DIR, 'project-journal.md') },
-    { name: 'handoff',       content: readHandoff(),                                boost: 1.1,  path: join(MEMORY_DIR, 'handoff.md') },
+    { name: 'team',          content: readTeamKnowledge(),                          boost: 1.25, path: join(paths().memoryDir, 'team-knowledge.md') },
+    { name: 'knowledge',     content: readKnowledgeBase(),                          boost: 1.15, path: join(paths().memoryDir, 'knowledge.md') },
+    { name: 'journal',       content: readOr(join(paths().memoryDir, 'project-journal.md')), boost: 1.0,  path: join(paths().memoryDir, 'project-journal.md') },
+    { name: 'handoff',       content: readHandoff(),                                boost: 1.1,  path: join(paths().memoryDir, 'handoff.md') },
     { name: 'global',        content: readGlobalKnowledge(),                        boost: 0.95, path: null },
     { name: 'claude-native', content: readNativeClaudeMemory(),                     boost: 0.95, path: null },
   ];
@@ -991,7 +1037,7 @@ const TOOLS = [
   },
   {
     name: 'ijfw_memory_search',
-    description: 'Keyword search across memory sources. Up to 20 results. Scope defaults to current project; pass scope:"all" to search across every IJFW project ever opened on this machine (results tagged [project:<name>]). Pass scope:"sandbox" to retrieve sandboxed ijfw_run output -- include label to get the full output of a specific run, or omit label to list all available sandbox entries.',
+    description: 'Keyword search across memory sources. Up to 20 results. Scope defaults to current project; pass scope:"all" to search across every IJFW project ever opened on this machine (results tagged [project:<name>]). Pass scope:"sandbox" to retrieve sandboxed ijfw_run output -- include label to get the full output of a specific run, or omit label to list all available sandbox entries. The query field also accepts colon-namespaced commands: "compute:<query>" hits the per-project FTS5 index, "graph:<query>" routes through the knowledge-graph search.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1050,8 +1096,8 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        period: { type: 'string', enum: ['today', '7d', '30d', 'all'], description: 'Time window (default 7d).' },
-        metric: { type: 'string', enum: ['tokens', 'cost', 'sessions', 'routing'], description: 'Which metric to render (default tokens).' }
+        period: { type: 'string', enum: ['today', '7d', '30d', 'all'], default: '7d', description: 'Time window (default 7d).' },
+        metric: { type: 'string', enum: ['tokens', 'cost', 'sessions', 'routing'], default: 'tokens', description: 'Which metric to render (default tokens).' }
       },
       required: []
     }
@@ -1072,7 +1118,7 @@ const TOOLS = [
   UPDATE_APPLY_TOOL,
   {
     name: 'ijfw_run',
-    description: 'Run a shell command. For commands likely to produce large output (builds, test suites, grep -r, log tails), use this instead of Bash -- full output is sandboxed to disk and a smart summary is returned to context. For git/nav/quick ops, use Bash directly.',
+    description: 'Run a shell command. For commands likely to produce large output (builds, test suites, grep -r, log tails), use this instead of Bash -- full output is sandboxed to disk and a smart summary is returned to context. For git/nav/quick ops, use Bash directly. Also accepts colon-namespaced commands instead of a shell line: "compute:python", "compute:js", "index:<source>", "detect:project_type".',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1083,15 +1129,30 @@ const TOOLS = [
       required: ['command'],
     },
   },
+  {
+    // v1.5.2 T24-27+T29: ijfw_brain — combined brain-query tool (slot 14/14).
+    // Replaces what would have been 4 standalone tools; combined-tool pattern
+    // keeps the cap raise to +1 instead of +4.
+    name: 'ijfw_brain',
+    description: 'IJFW Brain — query, links, wiki, conflict-resolve in one combined tool. verb=' + IJFW_BRAIN_VERBS.join('|'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        verb: { type: 'string', enum: IJFW_BRAIN_VERBS, description: 'Brain verb: think|links|wiki.get|wiki.compile|wiki.promote|wiki.export|wiki.shareReadme|conflict.resolve' },
+        args: { type: 'object', description: 'Verb-specific arguments (see verb docs).' },
+      },
+      required: ['verb'],
+    },
+  },
   {
     // v1.5.0 T13: ijfw_state — single MCP face for the state-SDK verb facade.
     // Absorbs the retired ijfw_subagent_post_done tool (post-done IS a state
     // transition → reachable as the `subagent.post-done` verb). All 20 frozen
     // verbs from STATE-SDK-CONTRACT §7 are reachable through this one tool,
-    // keeping the MCP cap at 12/12. The same `query(verb, payload, ctx)` core
+    // keeping the MCP cap at 13/13. The same `query(verb, payload, ctx)` core
     // is also exposed as a JS import and a CLI colon-namespace (`ijfw state:<verb>`).
     name: 'ijfw_state',
-    description: 'State-SDK verb facade — invoke any of the 20 frozen verbs (workflow.*, wave.*, phase.*, subagent.*, event.emit, telemetry.record, roster.*, extension.set-active, decision.add, blocker.*, state.replay, state.validate) over the canonical physical state files. Single MCP face for the state-SDK; subagent.post-done is the verb that absorbed the retired ijfw_subagent_post_done tool. Returns the verb result with `ok` + `verbId` + verb-specific fields (see STATE-SDK-CONTRACT §7).',
+    description: 'State-SDK verb facade — invoke any of the 20 frozen verbs over the canonical physical state files. The 20 verbs: workflow.get, workflow.set-phase, wave.get, wave.advance, wave.record-task, phase.plan-check, phase.complete, subagent.dispatch, subagent.checkpoint, subagent.post-done, event.emit, telemetry.record, roster.synthesize, roster.record, extension.set-active, decision.add, blocker.add, blocker.resolve, state.replay, state.validate. Single MCP face for the state-SDK; subagent.post-done is the verb that absorbed the retired ijfw_subagent_post_done tool. Returns the verb result with `ok` + `verbId` + verb-specific fields (see STATE-SDK-CONTRACT §7).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1110,15 +1171,16 @@ const TOOLS = [
     // (codex/gemini/claude by default) in parallel; if verdicts diverge,
     // re-runs with a CYCLE_SUMMARY of the disagreement until consensus or
     // maxIterations (default 3).  Stall breaker halts on byte-identical
-    // iterations.  Fills the 12th tool-cap slot.
+    // iterations.  Slot 14 of the 14/14 tool cap.
     name: 'ijfw_cross_audit_converge',
     description: 'Multi-lens Trident audit with consensus convergence loop. Dispatches codex/gemini/claude in parallel against a commit range, detects verdict divergence, and re-runs with a cycle summary until consensus or maxIterations. Returns {verdict, iterations, findings, divergence?, stalled?}. Verdict: PASS / CONDITIONAL / FAIL / consensus_failed / UNREACHABLE.',
     inputSchema: {
       type: 'object',
       properties: {
         commitRange:   { type: 'string',  description: 'Git commit range to audit (e.g. "HEAD~1..HEAD", "main..feature/x"). Required.' },
-        maxIterations: { type: 'number',  description: 'Max convergence iterations (default 3). 1 → single-shot (fallback mode).' },
+        maxIterations: { type: 'number',  minimum: 1, maximum: 10, description: 'Max convergence iterations (default 3, capped at 10). 1 → single-shot (fallback mode).' },
         lenses:        { type: 'array',   items: { type: 'string' }, description: 'Lens ids to dispatch (default ["codex","gemini","claude"]).' },
+        autoFix:       { type: 'boolean', description: 'v1.5.1 (T27) — opt-in consensus auto-fix. When true, after a non-PASS convergence the consensus code-fixer AUTOMATICALLY MODIFIES CODE: it runs an atomic per-finding fix loop (one revertable git commit per fix) over HIGH findings that 2+ lenses agreed on. SAFETY BOUNDS: the fixer can only write files inside the audited project root (path-containment guard refuses out-of-root paths) and touches at most 10 distinct files per run (change cap — beyond it it stops and reports rather than mass-rewriting). Logic bugs are deferred to humans, never auto-patched. Results surface on result.autoFix without changing the verdict. Default false — the audit is read-only unless you explicitly opt in.' },
       },
       required: ['commitRange'],
     },
@@ -1250,10 +1312,12 @@ function handleRecall({ context_hint, detail_level = 'standard', from_project })
         }
         // SQL table empty -- fall through to JSONL back-compat path below.
       }
-      if (!existsSync(FACTS_FILE)) {
+      // v1.5.2.1 H-2: factsFile() re-resolves via paths() each call.
+      const _ff = factsFile();
+      if (!existsSync(_ff)) {
         return { text: 'No structured facts extracted yet. Store memories with key:value lines, "X uses Y", or "decided to ..." phrases to populate.' };
       }
-      const raw = readFileSync(FACTS_FILE, 'utf8');
+      const raw = readFileSync(_ff, 'utf8');
       // detail_level === 'summary' → just count + a sample tail. Keeps token
       // usage bounded for session-start hydration.
       if (detail_level === 'summary') {
@@ -1272,6 +1336,69 @@ function handleRecall({ context_hint, detail_level = 'standard', from_project })
   return { text: results.map(r => `[${r.source}] ${r.content}`).join('\n') };
 }
 
+// v1.5.1 R4-H2 — wire the v1.5.0 memory-moat to the real write path.
+//
+// M1 (Obsidian wikilink/tag/meta indexing -> memory_links/_tags/_meta) and
+// M2 (A-Mem auto-linking) only fire inside memory/fts5.js#indexEntry. But the
+// production memory writers never called indexEntry: handleStore wrote the
+// markdown journal only, and search.js#autoIndex did a raw INSERT. So the
+// memory-moat's flagship — "memory that learns about you" — ran ONLY in the
+// benchmark harness. This helper routes a real ijfw_store through indexEntry,
+// which in one atomic INSERT also fires M1 (synchronous, idempotent) + M2
+// (fire-and-forget, env-gated via IJFW_AUTOLINK_OFF, budget-capped).
+//
+// Best-effort + fire-and-forget: handleStore stays synchronous and a missing
+// driver / unmigrated schema / DB error never breaks the markdown-or-JSONL
+// store path. The journal markdown remains the source of truth (hot tier);
+// the FTS5 row is the warm-tier mirror. Dedup safety: handleStore previously
+// did NO DB INSERT at all, so this is a NEW row, not a duplicate of an
+// existing write. search.js#autoIndex only batch-rebuilds when the FTS table
+// is empty (rowCount === 0) — it will skip an already-populated table — so a
+// store followed by a search cannot double-index the same entry.
+async function indexStoredEntryToFts5({ body, source, sessionId }) {
+  if (typeof body !== 'string' || body.length === 0) return null;
+  const fts5Mod = await import('./memory/fts5.js');
+  const root = process.env.IJFW_PROJECT_DIR || PROJECT_DIR;
+  const db = await fts5Mod.openDb(root);
+  try {
+    // indexEntry runs the ingest scrub gate + M1 indexObsidianRelations +
+    // M2 autoLink internally. body is already sanitised + redacted by the
+    // handleStore caller; the scrub gate re-running over already-clean text
+    // is idempotent.
+    const inserted = fts5Mod.indexEntry(db, {
+      body,
+      source: source || 'memory_store',
+      session_id: sessionId || null,
+    });
+    // indexEntry dispatches M2 autoLink + the D2 graph auto-index as
+    // fire-and-forget promises that still hold the db handle. We own the
+    // handle here, so we MUST let those settle before closing the db —
+    // otherwise autoLink races into a "database connection is not open"
+    // error. Capture the promise references SYNCHRONOUSLY right after
+    // indexEntry returns (no await in between) so an interleaved store
+    // can't overwrite the module-level statics before we read them. Both
+    // promises swallow their own failures, so awaiting them never rejects.
+    // This keeps M2 wired on the real store path without changing
+    // handleStore's fire-and-forget contract (the caller already treats
+    // this whole function as fire-and-forget).
+    const autoLinkP = fts5Mod.indexEntry.__lastAutoLinkPromise;
+    const autoIndexP = typeof fts5Mod.__getLastAutoIndexPromise === 'function'
+      ? fts5Mod.__getLastAutoIndexPromise()
+      : null;
+    try { await autoLinkP; } catch { /* swallowed by indexEntry */ }
+    try { await autoIndexP; } catch { /* swallowed by indexEntry */ }
+    return inserted;
+  } finally {
+    try { fts5Mod.closeDb(db); } catch { /* best-effort */ }
+  }
+}
+
+// Diagnostic hook for tests — holds the most recent FTS5/M1/M2 indexing
+// promise fired by handleStore so end-to-end tests can await deterministic
+// completion before asserting on memory_links / memory_tags. Production
+// callers do not read this.
+handleStore.__lastIndexPromise = null;
+
 function handleStore({ content, type, tags = [], summary, why, how_to_apply }) {
   // --- Input Validation ---
   if (!content || typeof content !== 'string') {
@@ -1304,13 +1431,22 @@ function handleStore({ content, type, tags = [], summary, why, how_to_apply }) {
 
   // Sanitize ALL text fields -- never store raw user/agent text in markdown
   // that gets re-injected into a future LLM context.
-  const safeContent = sanitizeContent(content);
+  //
+  // v1.5.1 R4-H3 — secret redaction. sanitizeContent strips prompt-injection
+  // control chars but does NOT scrub secret-shaped tokens (API keys, OAuth
+  // secrets). Without this, a secret pasted into a direct ijfw_store call
+  // lands in .ijfw/memory/*.md cleartext and re-injects into every future
+  // recall. The redactor is already wired into the FTS5 ingest path
+  // (memory/fts5.js#indexEntry) and the auto-memorize path; this closes the
+  // direct MCP store as the one remaining bypass. Redact AFTER sanitize so
+  // the redaction labels ([REDACTED:*]) are never themselves scrubbed.
+  const safeContent = redactSecrets(sanitizeContent(content));
   if (!safeContent) {
     return { text: 'content was empty after sanitisation (only control/format chars).', isError: true };
   }
-  const safeSummary = summary ? sanitizeContent(summary).substring(0, 120) : '';
-  const safeWhy = why ? sanitizeContent(why) : '';
-  const safeHow = how_to_apply ? sanitizeContent(how_to_apply) : '';
+  const safeSummary = summary ? redactSecrets(sanitizeContent(summary)).substring(0, 120) : '';
+  const safeWhy = why ? redactSecrets(sanitizeContent(why)) : '';
+  const safeHow = how_to_apply ? redactSecrets(sanitizeContent(how_to_apply)) : '';
 
   const tagStr = tags.length > 0 ? ` [${tags.join(', ')}]` : '';
   const journalEntry = `**${type}**${tagStr}: ${safeSummary || safeContent.substring(0, 200)}`;
@@ -1345,6 +1481,27 @@ function handleStore({ content, type, tags = [], summary, why, how_to_apply }) {
     return { text: `Memory journal is not writable (${journalResult.code}) -- check .ijfw/ directory permissions and retry.`, isError: true };
   }
 
+  // v1.5.1 R4-H2 — mirror the stored entry into the FTS5 warm tier, which
+  // also fires M1 (Obsidian indexing) + M2 (A-Mem auto-linking). Index the
+  // full content (already sanitised + redacted above) so [[wikilinks]],
+  // #tags and [key:: value] metadata land in memory_links/_tags/_meta and
+  // the auto-linker sees the real body. Fire-and-forget: handleStore stays
+  // synchronous and a DB failure never breaks the markdown store. The
+  // promise is exposed for tests that need deterministic completion.
+  try {
+    handleStore.__lastIndexPromise = indexStoredEntryToFts5({
+      body: safeContent,
+      source: `memory_store:${type}`,
+      sessionId: null,
+    }).catch((e) => {
+      try { console.error('[ijfw memory] FTS5/M1/M2 index failed:', e?.message || e); } catch { /* never throw */ }
+      return null;
+    });
+  } catch (e) {
+    handleStore.__lastIndexPromise = null;
+    try { console.error('[ijfw memory] FTS5 index dispatch failed:', e?.message || e); } catch { /* never throw */ }
+  }
+
   // H5.5 — Fact extraction AFTER successful append. Best-effort: a failure
   // here is logged in the return text but does NOT poison the store result.
   // Memory-id ties facts.jsonl rows back to their journal entry.
@@ -1385,7 +1542,7 @@ function handleStore({ content, type, tags = [], summary, why, how_to_apply }) {
   }
 
   if (type === 'handoff') {
-    const handoffPath = join(MEMORY_DIR, 'handoff.md');
+    const handoffPath = join(paths().memoryDir, 'handoff.md');
     const prior = readMarkdownFile(handoffPath);
     if (prior.ok && prior.content.trim()) {
       appendToJournal(`prior-handoff-archived: ${sanitizeContent(prior.content).substring(0, 500)}`);
@@ -1484,7 +1641,7 @@ async function handlePrelude({ detail_level = 'summary' } = {}) {
       try {
         const top = topKSuccessfulSkills(db, { k: 5 });
         if (top.length > 0) {
-          const names = top.map((r) => `${r.skill_id} (${r.success_count}×)`).join(', ');
+          const names = top.map((r) => `${r.skill_id} (${r.success_count}x)`).join(', ');
           parts.push(
             '<ijfw-recommended-skills>',
             `Observed success this project: ${names}`,
@@ -1659,7 +1816,21 @@ async function handlePrelude({ detail_level = 'summary' } = {}) {
     return { text: abstain.join('\n') };
   }
 
-  return { text };
+  // v1.5.2 brain context injection — env-gated (IJFW_BRAIN_INJECT=auto|always|never).
+  // Default 'never' keeps existing behavior unchanged; opt-in surfaces the
+  // top-N most-recently-touched wiki pages to the prelude. Best-effort —
+  // any failure is swallowed so prelude never breaks.
+  let injectedText = text;
+  try {
+    const mode = process.env.IJFW_BRAIN_INJECT || 'never';
+    if (mode === 'auto' || mode === 'always') {
+      const { buildContextInjection } = await import('./brain/context-injection.js');
+      const injection = buildContextInjection(REPO_ROOT, { mode });
+      if (injection) injectedText = text + injection;
+    }
+  } catch { /* swallow — injection is best-effort */ }
+
+  return { text: injectedText };
 }
 
 async function handleSearch({ query, limit = 10, scope = 'project', label }) {
@@ -1848,32 +2019,6 @@ function handleMetrics({ period = '7d', metric = 'tokens' } = {}) {
   return { text: out.join('\n') };
 }
 
-function handleStatus() {
-  const sessionCount = getSessionCount();
-  const decisionCount = getDecisionCount();
-  const hasKnowledge = existsSync(join(MEMORY_DIR, 'knowledge.md'));
-  const hasHandoff = existsSync(join(MEMORY_DIR, 'handoff.md'));
-  const hasGlobal = readGlobalKnowledge().trim().length > 0;
-
-  const parts = [];
-  if (hasKnowledge) {
-    const kb = readKnowledgeBase();
-    const kbLines = kb.split('\n').filter(l => l.trim().startsWith('**')).length;
-    parts.push(`Knowledge: ${kbLines} entries`);
-  }
-  if (sessionCount > 0 || decisionCount > 0) {
-    parts.push(`History: ${sessionCount} sessions, ${decisionCount} decisions`);
-  }
-  if (hasHandoff) {
-    const handoff = readHandoff();
-    const statusLine = handoff.split('\n').find(l => l.trim().length > 0 && !l.startsWith('<!--') && !l.startsWith('#'));
-    if (statusLine) parts.push(`Last: ${statusLine.trim().substring(0, 150)}`);
-  }
-  if (hasGlobal) parts.push('Project preferences loaded');
-
-  return { text: parts.join('\n') || 'Fresh project -- no memory yet.' };
-}
-
 // --- MCP Protocol Handler (JSON-RPC 2.0 over stdio) ---
 
 function createResponse(id, result) {
@@ -1945,6 +2090,28 @@ function handleMessage(msg) {
             result = { text: JSON.stringify(r, null, 2), isError: !!(r && r.error) };
             break;
           }
+          case 'ijfw_brain': {
+            // v1.5.2 T24-27+T29: combined brain verb facade.
+            const a = args || {};
+            if (typeof a.verb !== 'string' || a.verb.length === 0) {
+              result = { text: JSON.stringify({ ok: false, error: 'verb (string) is required' }), isError: true };
+              break;
+            }
+            try {
+              const r = await handleIjfwBrain({
+                verb: a.verb,
+                args: (a.args && typeof a.args === 'object') ? a.args : {},
+                db: getFactsDb(),
+                repoRoot: REPO_ROOT,
+                env: process.env,
+              });
+              result = { text: JSON.stringify(r, null, 2), isError: r.ok === false };
+            } catch (err) {
+              const msg = err && err.message ? err.message : String(err);
+              result = { text: JSON.stringify({ ok: false, error: msg }), isError: true };
+            }
+            break;
+          }
           case 'ijfw_state': {
             // v1.5.0 T13: single MCP face for the state-SDK. Routes every call
             // into the same `query(verb, payload, ctx)` core that the JS module
@@ -1999,9 +2166,74 @@ function handleMessage(msg) {
                 lenses: Array.isArray(a.lenses) && a.lenses.length > 0 ? a.lenses : undefined,
                 dispatch: defaultConvergeDispatch,
                 projectRoot: process.cwd(),
+                // v1.5.1 R4-H4 — opt-in consensus auto-fix (T27). Threaded
+                // from the tool schema so the code-fixer can genuinely fire;
+                // default false so the audit stays non-mutating unless the
+                // caller explicitly asks for it.
+                autoFix: a.autoFix === true,
               });
               const isErr = r.verdict === 'consensus_failed' || r.verdict === 'FAIL' || r.verdict === 'UNREACHABLE';
-              result = { text: JSON.stringify(r, null, 2), isError: isErr };
+              // v1.5.1 W2.D — emit a canonical gate-result block through the
+              // gate-result-formatter so this Trident-as-a-service surface is
+              // consistent with the Trident gate (dispatch.js) and preflight
+              // gates. appendGateResult guarantees the fenced block is the
+              // LAST content emitted and is idempotent. Failure to format the
+              // block must NOT clobber the verdict payload — observability,
+              // not correctness.
+              let convergeText = JSON.stringify(r, null, 2);
+              try {
+                const { emitGateResult } = await import('./gate-result.js');
+                const { appendGateResult } = await import('./gate-result-formatter.js');
+                // Map the converge verdict onto a schema-valid gate status.
+                const VERDICT_TO_STATUS = {
+                  PASS: 'PASS',
+                  CONDITIONAL: 'CONDITIONAL',
+                  WARN: 'WARN',
+                  FLAG: 'FLAG',
+                  FAIL: 'FAIL',
+                  consensus_failed: 'FAIL',
+                  UNREACHABLE: 'FAIL',
+                  INCONCLUSIVE: 'FLAG',
+                };
+                const gateStatus = VERDICT_TO_STATUS[r.verdict] || 'FLAG';
+                const block = await emitGateResult(
+                  {
+                    gate: 'cross-audit',
+                    status: gateStatus,
+                    lenses: [],
+                    affected_artifacts: [],
+                    accounting: {
+                      duration_ms:
+                        typeof r.duration_ms === 'number' ? r.duration_ms : 0,
+                      lenses_invoked: Array.isArray(a.lenses)
+                        ? a.lenses.length
+                        : 0,
+                      cost_usd: null,
+                    },
+                    remediation: [],
+                  },
+                  { projectRoot: process.cwd() },
+                );
+                // emitGateResult returns the fenced block as a string; the
+                // formatter validates it back into an object before append.
+                const parsed = JSON.parse(
+                  block.replace(/^```gate-result\n/, '').replace(/\n```$/, ''),
+                );
+                convergeText = appendGateResult(convergeText, parsed);
+              } catch (gateErr) {
+                try {
+                  const msg =
+                    gateErr && gateErr.message
+                      ? gateErr.message
+                      : String(gateErr);
+                  process.stderr.write(
+                    `ijfw: cross_audit_converge gate-result emit failed: ${msg}\n`,
+                  );
+                } catch {
+                  /* never crash the tool on a logging-channel failure */
+                }
+              }
+              result = { text: convergeText, isError: isErr };
             } catch (err) {
               result = { text: JSON.stringify({ error: err && err.message ? err.message : String(err) }), isError: true };
             }
@@ -2038,9 +2270,6 @@ function handleMessage(msg) {
             result = await handleSearch(searchArgs);
             break;
           }
-          case 'ijfw_memory_status':
-            result = handleStatus();
-            break;
           case 'ijfw_memory_prelude':
             result = await handlePrelude(args || {});
             break;
@@ -2153,51 +2382,175 @@ function handleMessage(msg) {
   }
 }
 
+// --- B17 WebSocket revocation client (dynamic-import gate) ---
+// extension-registry-ws.js is dormant by default. Its docstring contract:
+// "Imported via `await import(...)` ONLY when `process.env.IJFW_REGISTRY_WS_URL`
+// is set at startup." Firing the gate here at MCP startup keeps the module out
+// of the import graph entirely unless the operator opts in via the env var, so
+// MCP startup never opens a socket for the common (unset) case. Best-effort:
+// a failed WS bind must never block the stdio transport.
+// v1.5.2.1 F1: called from __mainEntryPoint() so importing server.js no
+// longer fires the WS client even when the env var is set in the importer's
+// process (relevant in tests / dashboards that share env with the server).
+function __maybeStartWsClient() {
+  if (!process.env.IJFW_REGISTRY_WS_URL && !process.env.IJFW_REGISTRY_WS_SOURCE) return;
+  (async () => {
+    try {
+      const { initWsClient } = await import('./extension-registry-ws.js');
+      const res = await initWsClient();
+      if (!res.ok) {
+        process.stderr.write(`IJFW: WS revocation client not started: ${res.error}\n`);
+      }
+    } catch (err) {
+      process.stderr.write(`IJFW: WS revocation client init failed: ${err && err.message ? err.message : err}\n`);
+    }
+  })();
+}
+
 // --- stdio Transport ---
-const rl = createInterface({ input: process.stdin, terminal: false });
+// v1.5.2.1 F1: called from __mainEntryPoint(). Importing server.js used to
+// install a global stdin listener that swallowed every byte the importer's
+// process received — making the import poisonous to any host with its own
+// stdin loop.
+// v1.5.2.1 M-3 (Lens 1): idempotency flag so a re-entrant invocation (test
+// harness, repeated __mainEntryPoint call, etc.) does NOT install a second
+// stdin listener — duplicate listeners cause double-handling of each line.
+let __stdioAttached = false;
+function __attachStdioTransport() {
+  if (__stdioAttached) return;
+  __stdioAttached = true;
+  const rl = createInterface({ input: process.stdin, terminal: false });
+  rl.on('line', (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0', id: null,
+        error: { code: -32700, message: 'Parse error' }
+      }) + '\n');
+      return;
+    }
+    try {
+      const response = handleMessage(msg);
+      if (response && typeof response.then === 'function') {
+        response.then(r => { if (r) process.stdout.write(r + '\n'); }).catch(err => {
+          process.stdout.write(JSON.stringify({
+            jsonrpc: '2.0',
+            id: msg && msg.id ? msg.id : null,
+            error: { code: -32603, message: `Internal error: ${err.message}` }
+          }) + '\n');
+        });
+      } else if (response) {
+        process.stdout.write(response + '\n');
+      }
+    } catch (err) {
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0',
+        id: msg && msg.id ? msg.id : null,
+        error: { code: -32603, message: `Internal error: ${err.message}` }
+      }) + '\n');
+    }
+  });
+}
 
-rl.on('line', (line) => {
-  if (!line.trim()) return;
-  let msg;
+// v1.5.2.1 F1: signal handlers belong to the server process — installing
+// them on import would steal SIGINT/SIGTERM from whatever host imported us.
+// v1.5.2.1 M-2 (Lens 1): idempotency flag — a re-entrant call would stack
+// duplicate SIGINT/SIGTERM handlers (each calling process.exit(0)) and
+// stack uncaughtException loggers (duplicating stderr noise per crash).
+let __signalsAttached = false;
+function __attachSignalHandlers() {
+  if (__signalsAttached) return;
+  __signalsAttached = true;
+  process.on('SIGINT', () => process.exit(0));
+  process.on('SIGTERM', () => process.exit(0));
+  process.on('uncaughtException', (err) => {
+    process.stderr.write(`IJFW: uncaught: ${err.stack || err.message}\n`);
+  });
+  process.on('unhandledRejection', (err) => {
+    process.stderr.write(`IJFW: unhandled rejection: ${err}\n`);
+  });
+}
+
+// v1.5.2.1 F6.META: when migrateFactsInternalOnce returns a list of orphan
+// files (stray facts at visible-layer paths after relocation), surface them
+// to the operator ONCE — keyed by a sentinel containing the fingerprint of
+// the orphan list, so repeated server starts don't spam stderr unless the
+// orphan set changes. Best-effort: any write failure is silent (stderr may
+// be detached during smoke tests; the sentinel may be in a read-only fs).
+async function __maybeWarnFactsOrphans(orphans) {
+  if (!orphans || orphans.length === 0) return;
+  const sentinelPath = join(REPO_ROOT, '.ijfw', '.facts-orphan-warned');
+  // v1.5.2.1 M-5 (Lens 1): switched from '\n'.join to JSON.stringify so a
+  // path containing an embedded newline cannot collide-by-fingerprint with
+  // a different orphan set. JSON encodes the separator and each element
+  // unambiguously.
+  const orphanFingerprint = JSON.stringify(orphans.slice().sort());
   try {
-    msg = JSON.parse(line);
-  } catch {
-    process.stdout.write(JSON.stringify({
-      jsonrpc: '2.0', id: null,
-      error: { code: -32700, message: 'Parse error' }
-    }) + '\n');
-    return;
+    const prev = readFileSync(sentinelPath, 'utf8');
+    if (prev === orphanFingerprint) return;
+  } catch { /* sentinel missing; fall through to warn */ }
+  try {
+    process.stderr.write(
+      `[ijfw facts-migrate] stray facts files at visible-layer paths ` +
+      `(NOT read at runtime; safe to delete after backup):\n` +
+      orphans.map(p => `  rm "${p}"`).join('\n') + '\n'
+    );
+    // v1.5.2.1 M-4 (Lens 1): ensure parent dir exists before writing the
+    // sentinel. The orphan-warn helper can fire before any code has created
+    // .ijfw/ (e.g. on a brand-new repo where the only IJFW artifact is the
+    // stray legacy file we're warning about).
+    try {
+      mkdirSync(dirname(sentinelPath), { recursive: true });
+      writeFileSync(sentinelPath, orphanFingerprint, 'utf8');
+    } catch {}
+  } catch { /* stderr detached */ }
+}
+
+// v1.5.2.1 F1: the single entry point for ALL server-startup side effects.
+// Anything that touches the filesystem, opens sockets, or installs process
+// listeners belongs here. The __isServerEntryPoint gate below ensures this
+// only fires when server.js is the Node entry point — never on import.
+async function __mainEntryPoint() {
+  // F5: relocate FACTS_FILE / FACTS_DB_FILE from legacy .ijfw/memory/ to
+  // .ijfw/. Sync + idempotent. F6.META: surface any orphan files left
+  // behind so the operator can clean them up.
+  try {
+    const factsResult = migrateFactsInternalOnce(REPO_ROOT);
+    if (factsResult && Array.isArray(factsResult.orphans) && factsResult.orphans.length > 0) {
+      await __maybeWarnFactsOrphans(factsResult.orphans);
+    }
+  } catch (e) {
+    try { process.stderr.write(`[ijfw facts-migrate] failed: ${e && e.message ? e.message : e}\n`); } catch {}
   }
+  // F3.4: fs-layout migrations via static registry (NOT the SQL runner).
+  // L-2 (Lens 1): runLayoutMigrations returns per-migration results so one
+  // failure cannot abort siblings. Surface each failure to stderr.
   try {
-    const response = handleMessage(msg);
-    if (response && typeof response.then === 'function') {
-      response.then(r => { if (r) process.stdout.write(r + '\n'); }).catch(err => {
-        process.stdout.write(JSON.stringify({
-          jsonrpc: '2.0',
-          id: msg && msg.id ? msg.id : null,
-          error: { code: -32603, message: `Internal error: ${err.message}` }
-        }) + '\n');
-      });
-    } else if (response) {
-      process.stdout.write(response + '\n');
+    const layoutResults = await runLayoutMigrations(REPO_ROOT);
+    for (const r of layoutResults) {
+      if (!r.ok) {
+        try {
+          process.stderr.write(
+            `[ijfw layout-migrate] ${r.description}: ${r.error}\n`
+          );
+        } catch {}
+      }
     }
-  } catch (err) {
-    process.stdout.write(JSON.stringify({
-      jsonrpc: '2.0',
-      id: msg && msg.id ? msg.id : null,
-      error: { code: -32603, message: `Internal error: ${err.message}` }
-    }) + '\n');
-  }
-});
-
-process.on('SIGINT', () => process.exit(0));
-process.on('SIGTERM', () => process.exit(0));
-process.on('uncaughtException', (err) => {
-  process.stderr.write(`IJFW: uncaught: ${err.stack || err.message}\n`);
-});
-process.on('unhandledRejection', (err) => {
-  process.stderr.write(`IJFW: unhandled rejection: ${err}\n`);
-});
+  } catch (e) {
+    try { process.stderr.write(`[ijfw layout-migrate] failed: ${e && e.message ? e.message : e}\n`); } catch {}
+  }
+  __bootstrapDirs();
+  __maybeStartWsClient();
+  __attachStdioTransport();
+  __attachSignalHandlers();
+}
+
+if (__isServerEntryPoint) {
+  await __mainEntryPoint();
+}
 
 // Export for tests (Node ESM allows this -- only consumed when imported, not on stdio run)
 // gatePermissionAndQuota is exported inline at its declaration above (B16/SEC-M-03)
@@ -2209,4 +2562,5 @@ export {
   handleStore, handleRecall, handleSearch, handlePrelude,
   MEMORY_DIR, FACTS_FILE, FACTS_DB_FILE,
   getFactsDb,
+  paths,
 };