@ijfw/memory-server 1.5.1 → 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';
@@ -276,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;
@@ -312,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');
@@ -347,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.
@@ -467,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);
@@ -477,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 = [
@@ -524,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).
@@ -597,7 +639,7 @@ function readGlobalKnowledge() {
 }
 
 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');
@@ -608,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.
@@ -623,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.
@@ -638,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
@@ -652,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
@@ -792,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 },
   ];
@@ -1071,6 +1129,21 @@ 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
@@ -1098,7 +1171,7 @@ 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.  Slot 12 of the 13/13 tool cap.
+    // 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: {
@@ -1239,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') {
@@ -1467,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)}`);
@@ -1566,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}`,
@@ -1741,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 }) {
@@ -2001,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
@@ -2278,7 +2389,11 @@ function handleMessage(msg) {
 // 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.
-if (process.env.IJFW_REGISTRY_WS_URL || process.env.IJFW_REGISTRY_WS_SOURCE) {
+// 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');
@@ -2293,50 +2408,149 @@ if (process.env.IJFW_REGISTRY_WS_URL || process.env.IJFW_REGISTRY_WS_SOURCE) {
 }
 
 // --- 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');
+    }
+  });
+}
+
+// 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`);
+  });
+}
 
-rl.on('line', (line) => {
-  if (!line.trim()) return;
-  let msg;
+// 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)
@@ -2348,4 +2562,5 @@ export {
   handleStore, handleRecall, handleSearch, handlePrelude,
   MEMORY_DIR, FACTS_FILE, FACTS_DB_FILE,
   getFactsDb,
+  paths,
 };

package/src/update-apply.js

@@ -7,7 +7,7 @@
 // terminal CLI does not require the sentinel to confirm — the token itself is
 // authoritative. The tool is retained for v1.5.0 back-compat (older skills that
 // still call it work unchanged) and slated for retirement in v1.6.0 to free the
-// MCP-tool slot (see CLAUDE.md "MCP server: ≤13 tools" cap).
+// MCP-tool slot (see CLAUDE.md "MCP server: ≤14 tools" cap).
 //
 // Does NOT execute the update. Validates the token, writes (or overwrites)
 // the pending sentinel, returns instruction telling the user to run the