@ijfw/memory-server 1.5.1 → 1.5.4

package/src/brain/dump-ingest.js

@@ -0,0 +1,88 @@
+// IJFW v1.5.2 -- brain dump inbox scanner.
+//
+// scanInbox(dir) walks the inbox dir at depth-0 ONLY (no recursion into
+// subdirs, no dotfiles), classifies each regular file into one of the
+// supported kinds, and returns metadata for the dream-cycle to extract.
+//
+// Subdirs are reserved for future use (e.g., per-source folders); the dump
+// pipeline treats them as opaque and skips them.
+
+import { readdirSync, statSync, writeFileSync, readFileSync, renameSync, existsSync } from 'node:fs';
+import { join, extname } from 'node:path';
+
+function classify(name) {
+  if (name.includes('.transcript.')) return 'transcript';
+  const ext = extname(name).toLowerCase();
+  if (ext === '.md' || ext === '.markdown') return 'markdown';
+  if (ext === '.pdf') return 'pdf';
+  if (ext === '.txt') return 'text';
+  return 'unknown';
+}
+
+export function scanInbox(inboxDir) {
+  let entries;
+  try {
+    entries = readdirSync(inboxDir, { withFileTypes: true });
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+  return entries
+    .filter((e) => e.isFile() && !e.name.startsWith('.'))
+    .map((e) => {
+      const p = join(inboxDir, e.name);
+      const s = statSync(p);
+      return {
+        path: p,
+        name: e.name,
+        kind: classify(e.name),
+        sizeBytes: s.size,
+        mtimeMs: s.mtimeMs,
+      };
+    })
+    .filter((f) => f.kind !== 'unknown');
+}
+
+export { classify };
+
+/**
+ * writeManifest -- write the per-file receipt as <processed>/<name>.manifest.json
+ * atomically via .tmp+rename. Must be called BEFORE commitProcessed so a crash
+ * between manifest-write and inbox-rename leaves the file as an orphan in
+ * inbox/ (reprocessable on next cycle) -- never a half-state.
+ */
+export function writeManifest(processedDir, fileName, payload) {
+  const final = manifestPath(processedDir, fileName);
+  const tmp = final + '.tmp';
+  writeFileSync(tmp, JSON.stringify(payload, null, 2));
+  renameSync(tmp, final);
+}
+
+/**
+ * commitProcessed -- atomically move <inbox>/<name> -> <processed>/<name>.
+ * Same-filesystem rename = atomic. Idempotent: silently succeeds if file
+ * already at destination and source is gone.
+ */
+export function commitProcessed(inboxDir, processedDir, fileName) {
+  const src = join(inboxDir, fileName);
+  const dst = join(processedDir, fileName);
+  if (!existsSync(src) && existsSync(dst)) return; // already committed (recovery no-op)
+  renameSync(src, dst);
+}
+
+/**
+ * isProcessed -- true iff the manifest exists for this file. The manifest is
+ * the source of truth for "this file completed" -- the inbox->processed rename
+ * is a cleanup step after the manifest is written.
+ */
+export function isProcessed(processedDir, fileName) {
+  return existsSync(manifestPath(processedDir, fileName));
+}
+
+export function readManifest(processedDir, fileName) {
+  return JSON.parse(readFileSync(manifestPath(processedDir, fileName), 'utf8'));
+}
+
+function manifestPath(processedDir, fileName) {
+  return join(processedDir, `${fileName}.manifest.json`);
+}

package/src/brain/entity-collapse.js

@@ -0,0 +1,28 @@
+// IJFW v1.5.2 -- brain entity collapse.
+//
+// canonicalize(s): lowercase + collapsed-whitespace + trim. findCandidateMerges(db)
+// surfaces groups of distinct stored subject strings that normalize to the same
+// form (e.g. "Sean Donahoe" / "sean donahoe" / " Sean  Donahoe " all collapse
+// to "sean donahoe"). Promotion (actual merge) is operator-confirmed -- this
+// module only surfaces candidates.
+
+export function canonicalize(s) {
+  return String(s == null ? '' : s).toLowerCase().trim().replace(/\s+/g, ' ');
+}
+
+export function findCandidateMerges(db) {
+  const rows = db.prepare('SELECT DISTINCT subject FROM facts').all();
+  const groups = new Map();
+  for (const { subject } of rows) {
+    if (subject == null) continue;
+    const c = canonicalize(subject);
+    if (!c) continue;
+    if (!groups.has(c)) groups.set(c, new Set());
+    groups.get(c).add(subject);
+  }
+  const out = [];
+  for (const [canonical, set] of groups) {
+    if (set.size > 1) out.push({ canonical, variants: [...set].sort() });
+  }
+  return out.sort((a, b) => a.canonical.localeCompare(b.canonical));
+}

package/src/brain/export.js

@@ -0,0 +1,121 @@
+// IJFW v1.5.2 -- brain export + share helpers.
+//
+// exportPageBundle(repoRoot, slug, outFile)
+//   Reads <slug>.md from any of the 4 wiki type dirs, finds [[linked]]
+//   wikilinks in the content, inlines each linked page as an "### slug"
+//   section after the root. Returns { outFile, bytes, linkedPagesIncluded }.
+//
+// writeShareReadme(repoRoot)
+//   Writes <repoRoot>/ijfw/README.md with team-share instructions
+//   (commit ijfw/ to git, teammates clone + `ijfw memory reindex`).
+//
+// Both functions tolerate the v1->v2 layout transition: they consult the
+// layout sentinel via resolveBrainPaths to pick the right wiki location.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { resolveBrainPaths } from './paths.js';
+import { validateSafeRepoPath } from './path-guard.js';
+
+const WIKI_TYPES = ['concepts', 'entities', 'decisions', 'milestones'];
+// Match the entire bracket-pair content as a single negated character class.
+// The slug (left of optional `|`) is extracted in JS after the regex match
+// instead of via a nested optional group -- safe-regex flagged the original
+// pattern (`[^\]\n|]+(?:\|[^\]\n]*)?`) as potentially unsafe even though it
+// can't backtrack catastrophically. This single-class form is provably linear.
+const WIKILINK_RE = /\[\[([^\]\n]+)\]\]/g;
+
+function findPage(wikiDir, slug) {
+  for (const t of WIKI_TYPES) {
+    const p = join(wikiDir, t, `${slug}.md`);
+    if (existsSync(p)) return { path: p, type: t };
+  }
+  return null;
+}
+
+function parseWikilinks(md) {
+  if (!md) return [];
+  const out = new Set();
+  for (const m of md.matchAll(WIKILINK_RE)) {
+    // The capture group now includes the optional `|alias` suffix; the slug
+    // is the substring before the first `|` (matches the original semantics).
+    const inner = m[1];
+    const pipeIdx = inner.indexOf('|');
+    const target = (pipeIdx === -1 ? inner : inner.slice(0, pipeIdx)).trim();
+    if (target) out.add(target);
+  }
+  return [...out];
+}
+
+export function exportPageBundle(repoRoot, slug, outFile) {
+  // F-LENS2-05 defense-in-depth: brain-handler already validates outFile via
+  // validateSafeRepoPath, but exportPageBundle is also exported and may be
+  // called directly by future callers. Re-validate here so the policy holds
+  // at the writer boundary too.
+  const guard = validateSafeRepoPath(repoRoot, outFile);
+  if (!guard.ok) return { error: guard.error };
+  const paths = resolveBrainPaths(repoRoot);
+  const root = findPage(paths.wikiDir, slug);
+  if (!root) return { error: 'page-not-found', slug };
+  const rootBody = readFileSync(root.path, 'utf8');
+  const linked = parseWikilinks(rootBody);
+
+  const parts = [
+    `# Export: ${slug}\n\n_Generated by IJFW brain export from ${root.type}/${slug}.md._\n`,
+    `## ${slug}\n\n${rootBody.trim()}`,
+  ];
+  const includedLinks = [];
+  for (const target of linked) {
+    const found = findPage(paths.wikiDir, target);
+    if (!found) continue;
+    let body;
+    try { body = readFileSync(found.path, 'utf8'); } catch { continue; }
+    parts.push(`### ${target}\n\n${body.trim()}`);
+    includedLinks.push(target);
+  }
+  const out = parts.join('\n\n') + '\n';
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeFileSync(outFile, out);
+  return { outFile, bytes: Buffer.byteLength(out, 'utf8'), linkedPagesIncluded: includedLinks };
+}
+
+const SHARE_README = `# Your IJFW Brain
+
+This folder is **your project brain** — durable, queryable knowledge maintained by IJFW across every CLI you use (Claude Code, Codex, Cursor, Windsurf, Gemini, and more).
+
+## Structure
+
+\`\`\`
+ijfw/
+├── memory/      # raw memory entries (knowledge.md, handoff.md, journal.md, decisions.md)
+├── sessions/    # readable per-session logs
+├── dump/
+│   ├── inbox/      # drop ANY file here (md/txt/transcript/pdf) — gets ingested next dream cycle
+│   └── processed/  # files move here once ingested, with a .manifest.json receipt
+└── wiki/        # LLM-curated, Obsidian-readable
+    ├── concepts/, entities/, decisions/, milestones/
+\`\`\`
+
+## Share with your team
+
+1. Commit \`ijfw/\` to git like any other source folder.
+2. Teammates clone the repo and run \`ijfw memory reindex\` to populate their local index.
+3. The internal index db lives in \`.ijfw/\` (gitignored) — only the content in \`ijfw/\` is shared.
+
+## Privacy
+
+Everything in \`ijfw/\` is plain markdown / json. Inspect it. Edit it. Diff it. Your brain stays under your version control.
+`;
+
+export function writeShareReadme(repoRoot) {
+  const paths = resolveBrainPaths(repoRoot);
+  const out = join(paths.contentDir, 'README.md');
+  // F-LENS2-05: validate the share-readme path before writing. A symlinked
+  // ijfw/ directory or contentDir resolution outside the repo would otherwise
+  // let writeFileSync clobber an arbitrary path.
+  const guard = validateSafeRepoPath(repoRoot, out);
+  if (!guard.ok) return { error: guard.error };
+  mkdirSync(paths.contentDir, { recursive: true });
+  writeFileSync(out, SHARE_README);
+  return { outFile: out, bytes: Buffer.byteLength(SHARE_README, 'utf8') };
+}

package/src/brain/extractors/index.js

@@ -0,0 +1,24 @@
+// index.js -- dispatch extractFile(file) by kind.
+import { extractMarkdown } from './markdown.js';
+import { extractTranscript } from './transcript.js';
+import { extractPdf } from './pdf.js';
+
+/**
+ * file: object from scanInbox -- shape { path, name, kind, sizeBytes, mtimeMs }.
+ * Returns Promise<{ text, chunks } | { error, ... }>.
+ */
+export async function extractFile(file) {
+  switch (file.kind) {
+    case 'markdown':
+    case 'text':
+      return extractMarkdown(file.path);
+    case 'transcript':
+      return extractTranscript(file.path);
+    case 'pdf':
+      return extractPdf(file.path);
+    default:
+      return { error: 'unsupported-kind', kind: file.kind, path: file.path };
+  }
+}
+
+export { extractMarkdown, extractTranscript, extractPdf };

package/src/brain/extractors/markdown.js

@@ -0,0 +1,27 @@
+// markdown.js -- markdown + text extractor (chunk on blank-line boundaries).
+import { readFileSync } from 'node:fs';
+
+const DEFAULT_MAX_CHARS = 3000;
+
+export function chunkAtBlankLines(text, maxChars = DEFAULT_MAX_CHARS) {
+  if (text.length <= maxChars) return [text];
+  const paragraphs = text.split(/\n\s*\n/);
+  const chunks = [];
+  let cur = '';
+  for (const p of paragraphs) {
+    const candidate = cur ? cur + '\n\n' + p : p;
+    if (candidate.length <= maxChars) { cur = candidate; continue; }
+    if (cur) chunks.push(cur);
+    if (p.length <= maxChars) { cur = p; continue; }
+    // single paragraph exceeds maxChars — hard-split on chars
+    for (let i = 0; i < p.length; i += maxChars) chunks.push(p.slice(i, i + maxChars));
+    cur = '';
+  }
+  if (cur) chunks.push(cur);
+  return chunks;
+}
+
+export function extractMarkdown(filePath, { maxChars = DEFAULT_MAX_CHARS } = {}) {
+  const text = readFileSync(filePath, 'utf8');
+  return { text, chunks: chunkAtBlankLines(text, maxChars) };
+}

package/src/brain/extractors/pdf.js

@@ -0,0 +1,31 @@
+// pdf.js -- lazy pdf-parse wrapper. pdf-parse is NOT a hard dependency;
+// returns { error } gracefully when the dep is missing.
+
+import { readFileSync } from 'node:fs';
+
+export async function extractPdf(filePath) {
+  let pdfParse;
+  try {
+    // pdf-parse exposes its parser as the default export of its CJS module.
+    const mod = await import('pdf-parse');
+    pdfParse = mod.default || mod;
+  } catch (e) {
+    if (e.code === 'ERR_MODULE_NOT_FOUND' || /Cannot find module/i.test(e.message || '')) {
+      return { error: 'pdf-parse-not-installed', filePath };
+    }
+    throw e;
+  }
+  try {
+    const buf = readFileSync(filePath);
+    const parsed = await pdfParse(buf);
+    const text = parsed && typeof parsed.text === 'string' ? parsed.text : '';
+    // Chunk on form-feed (PDF page break) when present, else fall back to blank-line chunking.
+    const { chunkAtBlankLines } = await import('./markdown.js');
+    const pageChunks = text.includes('\f')
+      ? text.split('\f').map((p) => p.trim()).filter(Boolean)
+      : chunkAtBlankLines(text);
+    return { text, chunks: pageChunks };
+  } catch (e) {
+    return { error: 'pdf-parse-failed', message: e.message, filePath };
+  }
+}

package/src/brain/extractors/transcript.js

@@ -0,0 +1,38 @@
+// transcript.js -- speaker-turn chunking.
+//
+// Detects turns whose first line starts with `Name:` or `[Name]`. Each turn
+// is one chunk. Sequential lines without a speaker prefix belong to the
+// current speaker's turn.
+
+import { readFileSync } from 'node:fs';
+
+// Speaker prefix at line start: "Name:" (alphanumeric + spaces) or "[Name]".
+// Allow up to 60 chars of name to avoid pathological matches on prose.
+const SPEAKER_RE = /^(\[[^\]]{1,60}\]|[A-Za-z][A-Za-z0-9 _.'-]{0,59}:)\s/;
+
+export function splitOnSpeakerTurns(text) {
+  const lines = text.split('\n');
+  const turns = [];
+  let current = null;
+  for (const line of lines) {
+    if (SPEAKER_RE.test(line)) {
+      if (current !== null) turns.push(current);
+      current = line;
+    } else {
+      if (current === null) {
+        // pre-amble before any speaker — collect into its own chunk
+        current = line;
+      } else {
+        current += '\n' + line;
+      }
+    }
+  }
+  if (current !== null) turns.push(current);
+  // trim trailing newlines per turn, drop empty
+  return turns.map((t) => t.replace(/\n+$/, '')).filter((t) => t.trim().length > 0);
+}
+
+export function extractTranscript(filePath) {
+  const text = readFileSync(filePath, 'utf8');
+  return { text, chunks: splitOnSpeakerTurns(text) };
+}

package/src/brain/first-run-scan.js

@@ -0,0 +1,61 @@
+// IJFW v1.5.2 -- brain first-run scan.
+//
+// Powers the dashboard / Wayland portal "wow" cold-start by surfacing the
+// operator's existing CLI memory from known per-CLI homes. Each "source"
+// reports { id, label, path, found, count, projects }. onProgress fires
+// as { stage: "scanning" | "found", id, ... }.
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SOURCES = [
+  { id: 'claude',    label: 'Claude Code',       rel: '.claude/projects',   kind: 'dir-of-projects' },
+  { id: 'codex',     label: 'Codex CLI',         rel: '.codex',             kind: 'dir' },
+  { id: 'gemini',    label: 'Gemini CLI',        rel: '.gemini',            kind: 'dir' },
+  { id: 'cursor',    label: 'Cursor',            rel: '.cursor',            kind: 'dir' },
+  { id: 'windsurf',  label: 'Windsurf',          rel: '.windsurf',          kind: 'dir' },
+  { id: 'claude-md', label: 'Global CLAUDE.md',  rel: 'CLAUDE.md',          kind: 'file' },
+  { id: 'agents-md', label: 'Global AGENTS.md',  rel: 'AGENTS.md',          kind: 'file' },
+  { id: 'gemini-md', label: 'Global GEMINI.md',  rel: 'GEMINI.md',          kind: 'file' },
+];
+
+function safeReaddir(p) { try { return readdirSync(p); } catch { return []; } }
+
+function sessionsForClaude(claudeProjectsDir) {
+  const projects = safeReaddir(claudeProjectsDir).filter((name) => {
+    try { return statSync(join(claudeProjectsDir, name)).isDirectory(); } catch { return false; }
+  });
+  let totalSessions = 0;
+  for (const p of projects) {
+    const files = safeReaddir(join(claudeProjectsDir, p)).filter((f) => f.endsWith('.jsonl'));
+    totalSessions += files.length;
+  }
+  return { projects: projects.length, totalSessions };
+}
+
+export function firstRunScan({ homeDir, onProgress } = {}) {
+  const sources = [];
+  let totalSessions = 0;
+  for (const src of SOURCES) {
+    if (onProgress) onProgress({ stage: 'scanning', id: src.id });
+    const p = join(homeDir, src.rel);
+    const present = existsSync(p);
+    if (!present) {
+      sources.push({ id: src.id, label: src.label, path: p, found: false, count: 0, projects: 0 });
+      continue;
+    }
+    let count = 0, projects = 0;
+    if (src.kind === 'dir-of-projects') {
+      const r = sessionsForClaude(p);
+      projects = r.projects; count = r.totalSessions; totalSessions += r.totalSessions;
+    } else if (src.kind === 'dir') {
+      count = safeReaddir(p).length;
+    } else if (src.kind === 'file') {
+      try { count = statSync(p).size > 0 ? 1 : 0; } catch { count = 0; }
+    }
+    const entry = { id: src.id, label: src.label, path: p, found: true, count, projects };
+    sources.push(entry);
+    if (onProgress) onProgress({ stage: 'found', id: src.id, count, projects });
+  }
+  return { sources, totalSessions };
+}

package/src/brain/index.js

@@ -0,0 +1 @@
+export const BRAIN_VERSION = 1;

package/src/brain/layout-sentinel.js

@@ -0,0 +1,29 @@
+import { readFileSync, writeFileSync, existsSync, openSync, closeSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function readLayoutVersion(repoRoot) {
+  const p = join(repoRoot, '.ijfw', '.layout-version');
+  if (!existsSync(p)) return 1;
+  const v = parseInt(readFileSync(p, 'utf8').trim(), 10);
+  return Number.isFinite(v) && v >= 1 ? v : 1;
+}
+
+export function writeLayoutVersion(repoRoot, version) {
+  writeFileSync(join(repoRoot, '.ijfw', '.layout-version'), `${version}\n`);
+}
+
+export async function withLayoutLock(repoRoot, fn, { timeoutMs = 5000 } = {}) {
+  const lockPath = join(repoRoot, '.ijfw', '.migrate.lock');
+  const start = Date.now();
+  let fd = null;
+  while (true) {
+    try { fd = openSync(lockPath, 'wx'); break; }
+    catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      if (Date.now() - start > timeoutMs) throw new Error(`layout-sentinel: locked > ${timeoutMs}ms`);
+      await new Promise(r => setTimeout(r, 25));
+    }
+  }
+  try { return await fn(); }
+  finally { try { closeSync(fd); } catch {} try { unlinkSync(lockPath); } catch {} }
+}

package/src/brain/migrate-facts-internal-once.js

@@ -0,0 +1,87 @@
+// IJFW v1.5.2 -- one-shot migration: relocate FACTS_FILE + FACTS_DB_FILE to
+// the internal hidden-paths location (Plan A audit F5).
+//
+// Plan A's lazy MEMORY_DIR refactor (Task 5) intentionally kept FACTS_FILE
+// + FACTS_DB_FILE at <contentDir>/memory/ with a deferral comment, because
+// moving them required a data migration outside Task 5's scope. This file
+// IS the F5 migration that closes that deferral:
+//
+//   .ijfw/memory/facts.jsonl  -> .ijfw/facts.jsonl
+//   .ijfw/memory/facts.db     -> .ijfw/index/memory.db
+//
+// This matches the design contract from Task 3's paths.js: internal paths
+// (indexDb, factsJsonl, stateDir, metricsDir, receiptsDir) ALWAYS live under
+// .ijfw/, never under the visible ijfw/ content dir. Without this migration
+// the post-Task-10 layout would move FACTS into ijfw/memory/ — the opposite
+// of where they belong.
+//
+// Sync, idempotent, atomic (renameSync is a single syscall on POSIX). Runs at
+// server startup; safe to call repeatedly. Crash mid-migration leaves either
+// the old or the new path populated, never both — operator can re-run
+// safely.
+
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+export function migrateFactsInternalOnce(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return { skipped: true, reason: 'no-repo-root' };
+  }
+  const oldJsonl = join(repoRoot, '.ijfw', 'memory', 'facts.jsonl');
+  const newJsonl = join(repoRoot, '.ijfw', 'facts.jsonl');
+  const oldDb = join(repoRoot, '.ijfw', 'memory', 'facts.db');
+  const newDb = join(repoRoot, '.ijfw', 'index', 'memory.db');
+  // v1.5.2.1 F3: 010 may have already copied facts.{jsonl,db} into the visible
+  // layer at ijfw/memory/ before this migration runs. Those copies are NEVER
+  // valid as a runtime source — facts always live at the internal paths
+  // (paths().factsJsonl / paths().indexDb), and the visible-layer copies will
+  // drift on the first write. Flag them so the operator can prune; do NOT
+  // delete automatically (could destroy user data in extremis).
+  const visibleJsonlOrphan = join(repoRoot, 'ijfw', 'memory', 'facts.jsonl');
+  const visibleDbOrphan = join(repoRoot, 'ijfw', 'memory', 'facts.db');
+
+  // Helper to extend the orphans list with any visible-layer facts files.
+  const collectVisibleOrphans = (orphans) => {
+    if (existsSync(visibleJsonlOrphan)) orphans.push(visibleJsonlOrphan);
+    if (existsSync(visibleDbOrphan)) orphans.push(visibleDbOrphan);
+    return orphans;
+  };
+
+  // Idempotent short-circuit: if EITHER new path exists, treat as migrated.
+  // (We don't require both because a partial migration that crashed before
+  // the second move would still be detectable on retry, but a fully
+  // intentional standalone deployment of just one is operator-territory and
+  // we don't second-guess it.)
+  if (existsSync(newJsonl) || existsSync(newDb)) {
+    // FLAG-7: detect orphans — if a legacy path ALSO exists alongside the
+    // new path, surface it so the operator can clean up. Don't move
+    // automatically (could overwrite real data); just flag. v1.5.2.1 also
+    // detects the visible-layer facts files left by an earlier 010 run.
+    const orphans = [];
+    if (existsSync(oldJsonl)) orphans.push(oldJsonl);
+    if (existsSync(oldDb)) orphans.push(oldDb);
+    collectVisibleOrphans(orphans);
+    return orphans.length > 0
+      ? { skipped: true, reason: 'already-migrated', orphans }
+      : { skipped: true, reason: 'already-migrated' };
+  }
+
+  const moved = [];
+  if (existsSync(oldJsonl)) {
+    mkdirSync(dirname(newJsonl), { recursive: true });
+    renameSync(oldJsonl, newJsonl);
+    moved.push({ from: oldJsonl, to: newJsonl });
+  }
+  if (existsSync(oldDb)) {
+    mkdirSync(dirname(newDb), { recursive: true });
+    renameSync(oldDb, newDb);
+    moved.push({ from: oldDb, to: newDb });
+  }
+  // v1.5.2.1 F3: surface visible-layer facts orphans on the success path too,
+  // in case 010 ran before 011 on this install. They're still wrong; operator
+  // gets the same prune cue.
+  const orphans = collectVisibleOrphans([]);
+  return orphans.length > 0
+    ? { skipped: false, moved, orphans }
+    : { skipped: false, moved };
+}

package/src/brain/path-guard.js

@@ -0,0 +1,103 @@
+// IJFW v1.5.2.1 -- shared safe-write path guard (F-LENS2-05, F-LENS2-06, F-LENS2-10).
+//
+// validateSafeRepoPath(repoRoot, targetPath) returns:
+//   { ok: true, resolved }
+//   { ok: false, error: 'repoRoot-missing' | 'outFile-escapes-repo' | 'outFile-reserved-name', ... }
+//
+// Why a shared helper:
+//   - F-LENS2-05: wiki.export's guard was the only callsite. wiki.compile,
+//     wiki.shareReadme, dream/budget logs all wrote without containment.
+//   - F-LENS2-06: the reserved-name regex missed Windows trailing-dot /
+//     trailing-space / NTFS-stream variants ("CON ", "CON.", "CON:Stream1")
+//     because Windows itself trims those before opening the device.
+//   - F-LENS2-10: the previous guard threw if repoRoot didn't exist on disk
+//     (realpathSync on a missing dir). Tests sometimes pass a not-yet-created
+//     repoRoot — return a structured rejection instead.
+//
+// The reserved-name check normalises basename via the same trim Windows
+// applies: strip trailing dots/whitespace, then drop NTFS alternate-data-
+// stream suffix (everything after the first ':'). The tightened character
+// class is `com[1-9]|lpt[1-9]` (1-9, not 0-9) per Microsoft's documented set.
+
+import { realpathSync, lstatSync } from 'node:fs';
+import {
+  resolve as pathResolve,
+  relative as pathRelative,
+  dirname as pathDirname,
+  basename as pathBasename,
+  isAbsolute as pathIsAbsolute,
+  join as pathJoin,
+} from 'node:path';
+
+const WIN_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+
+export function validateSafeRepoPath(repoRoot, targetPath) {
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return { ok: false, error: 'repoRoot-missing', repoRoot };
+  }
+  if (!targetPath || typeof targetPath !== 'string') {
+    return { ok: false, error: 'outFile-missing', targetPath };
+  }
+  let resolvedRoot;
+  try {
+    resolvedRoot = realpathSync(pathResolve(repoRoot));
+  } catch {
+    return { ok: false, error: 'repoRoot-missing', repoRoot };
+  }
+  let resolved = pathResolve(targetPath);
+  // Walk UP toward the root to find the closest existing ancestor, realpath
+  // THAT, then re-attach the not-yet-created suffix. Why: macOS /tmp is a
+  // symlink to /private/tmp; resolvedRoot becomes /private/var/folders/...
+  // but pathResolve(targetPath) gives /var/folders/.../ijfw/wiki/... — the
+  // bare-lexical containment check would then claim the path "escapes" the
+  // repo. Canonicalising the deepest-existing ancestor unmasks the symlink
+  // chain symmetrically with resolvedRoot.
+  {
+    let ancestor = resolved;
+    const suffix = [];
+    // Bound the walk so a pathological input can't spin: at most 64 levels
+    // (far deeper than any realistic project layout).
+    for (let i = 0; i < 64; i++) {
+      try {
+        ancestor = realpathSync(ancestor);
+        break;
+      } catch {
+        const parent = pathDirname(ancestor);
+        if (parent === ancestor) break; // reached '/' or drive root
+        suffix.unshift(pathBasename(ancestor));
+        ancestor = parent;
+      }
+    }
+    resolved = suffix.length ? pathJoin(ancestor, ...suffix) : ancestor;
+  }
+  const rel = pathRelative(resolvedRoot, resolved);
+  if (rel === '' || rel.startsWith('..') || pathIsAbsolute(rel)) {
+    return { ok: false, error: 'outFile-escapes-repo', resolved, repoRoot: resolvedRoot };
+  }
+  // Windows trims trailing dots/whitespace and treats `name:stream` as the
+  // bare `name` device. Normalise the basename the same way before checking.
+  const baseRaw = pathBasename(resolved);
+  const baseTrimmed = baseRaw.replace(/[.\s]+$/, '');
+  const stem = baseTrimmed.split(':')[0].split('.')[0];
+  if (WIN_RESERVED.test(stem)) {
+    return { ok: false, error: 'outFile-reserved-name', resolved };
+  }
+  // F-LENS2-07: TOCTOU hardening. Even after parent-ancestor canonicalization,
+  // an attacker could create the TARGET itself as a symlink between this
+  // guard and the writeFileSync. lstatSync (does NOT follow symlinks) catches
+  // an existing symlink at the resolved path. Pre-existing regular file is
+  // fine — writers either overwrite or 'wx'-fail on their own. The residual
+  // TOCTOU window between this check and the writer's open is microseconds
+  // and requires a same-uid attacker; documented threat model.
+  try {
+    const st = lstatSync(resolved);
+    if (st.isSymbolicLink()) {
+      return { ok: false, error: 'outFile-is-symlink', resolved };
+    }
+  } catch {
+    // ENOENT — target doesn't exist yet; the most common case. OK to proceed.
+  }
+  return { ok: true, resolved };
+}
+
+export default { validateSafeRepoPath };