@ijfw/memory-server 1.5.4 → 1.5.6

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "@ijfw/memory-server",
-  "version": "1.5.4",
+  "version": "1.5.6",
   "description": "Cross-platform persistent memory server for IJFW. 14 MCP tools (memory + admin/update + brain). Works with 15 platforms: 14 via MCP (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Copilot, Hermes, Wayland, OpenCode, QwenCode, Cline, KimiCode, OpenClaw, Antigravity) plus Aider via the rules-only tier.",
   "author": "Sean Donahoe",
+  "contributors": [
+    {
+      "name": "Ferrox Labs",
+      "url": "https://ferroxlabs.com"
+    }
+  ],
   "license": "MIT",
+  "homepage": "https://github.com/FerroxLabs/ijfw",
+  "bugs": {
+    "url": "https://github.com/FerroxLabs/ijfw/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FerroxLabs/ijfw.git"
+  },
   "type": "module",
   "main": "src/server.js",
   "bin": {

package/src/brain/dream-pipeline.js

@@ -16,8 +16,10 @@
 // Budget: every LLM call goes through BudgetGuard. budgetExhausted=true
 // signals the cycle stopped voluntarily (not crashed).
 
-import { mkdirSync, appendFileSync, lstatSync } from 'node:fs';
-import { dirname } from 'node:path';
+import {
+  mkdirSync, existsSync, openSync, writeSync, closeSync, constants as fsConstants,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
 import { resolveBrainPaths } from './paths.js';
 import { scanInbox, writeManifest, commitProcessed, isProcessed } from './dump-ingest.js';
 import { extractFile } from './extractors/index.js';
@@ -25,6 +27,7 @@ import { BudgetGuard } from './budget-guard.js';
 import { compileWikiPage } from './wiki-compiler.js';
 import { callTiered } from './tiered-llm.js';
 import { validateSafeRepoPath } from './path-guard.js';
+import { withFsLock, lockPathFor } from '../fs-lock.js';
 
 function ensureFactsTable(db) {
   // Idempotent: matches the schema downstream consumers expect.
@@ -41,18 +44,33 @@ function ensureFactsTable(db) {
 function appendLog(wikiLogPath, line, repoRoot) {
   try {
     // F-LENS2-05/11: refuse to follow a symlinked log path out of the repo.
-    // lstat (NOT stat) so we see the symlink itself; if the path is a
-    // symlink, drop the append rather than write through it.
     if (repoRoot) {
       const guard = validateSafeRepoPath(repoRoot, wikiLogPath);
       if (!guard.ok) return;
     }
-    try {
-      const lst = lstatSync(wikiLogPath);
-      if (lst.isSymbolicLink()) return; // F-LENS2-11: refuse symlink follow
-    } catch { /* file doesn't exist yet — ok to create */ }
     mkdirSync(dirname(wikiLogPath), { recursive: true });
-    appendFileSync(wikiLogPath, line + '\n');
+    // V155-039 (MED): the prior `lstatSync` → `appendFileSync` sequence had
+    // a TOCTOU window — an attacker could swap a regular file for a symlink
+    // between the two syscalls so the write follows the new symlink (e.g.
+    // to /etc/passwd). `O_NOFOLLOW` makes `openSync` fail atomically if the
+    // FINAL path component is a symlink, closing the race with a single
+    // syscall. `O_APPEND` keeps append semantics; `O_CREAT` creates on
+    // first write. Mode 0o600 keeps log private.
+    let fd;
+    try {
+      // eslint-disable-next-line no-bitwise
+      fd = openSync(
+        wikiLogPath,
+        fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_WRONLY | fsConstants.O_NOFOLLOW,
+        0o600,
+      );
+    } catch {
+      // ELOOP / EACCES → refuse to write. No fallback path — logging is
+      // best-effort and a symlinked log path is a refusal, not a degrade.
+      return;
+    }
+    try { writeSync(fd, line + '\n'); }
+    finally { try { closeSync(fd); } catch { /* best-effort */ } }
   } catch { /* logging is best-effort */ }
 }
 
@@ -179,6 +197,23 @@ export async function defaultExtractFacts({ file: _file, text, chunks, env, guar
 
 function nowIso() { return new Date().toISOString(); }
 
+// V155-020 (HIGH): facts-table source check. `isProcessed(processed, name)`
+// only inspects the manifest file — `rm -rf <processed>/` looks like a
+// clean slate to the gate, so re-ingest doubles every triple (cycle 2 = 2x,
+// cycle 3 = 3x, …). Cross-check the facts table: if ANY fact already
+// references this file as its `source`, treat it as processed regardless
+// of manifest presence. Cleaner than adding a UNIQUE constraint (no
+// migration required); the source column already stores file.name.
+function isProcessedDouble(db, processedDir, fileName) {
+  if (isProcessed(processedDir, fileName)) return true;
+  try {
+    const row = db.prepare(
+      'SELECT 1 FROM facts WHERE source = ? LIMIT 1'
+    ).get(fileName);
+    return !!row;
+  } catch { return false; }
+}
+
 export async function runDreamCycle({ db, repoRoot, env = process.env, cycleId, extractFacts } = {}) {
   if (!db) throw new Error('dream-pipeline: db required');
   if (!repoRoot) throw new Error('dream-pipeline: repoRoot required');
@@ -195,6 +230,32 @@ export async function runDreamCycle({ db, repoRoot, env = process.env, cycleId,
   const guard = BudgetGuard(guardOpts);
   const extractor = extractFacts || defaultExtractFacts;
 
+  // V155-064 (LOW): gate the mkdirSyncs on existsSync so the syscalls don't
+  // fire on every cycle (cheap-and-correct today, but if a future watcher
+  // layers fs-events on those dirs the mkdir wakeups become hot-path noise).
+  // `mkdir … recursive:true` is idempotent at the kernel layer; this is a
+  // userspace short-circuit.
+  if (!existsSync(paths.dumpInbox)) mkdirSync(paths.dumpInbox, { recursive: true });
+  if (!existsSync(paths.dumpProcessed)) mkdirSync(paths.dumpProcessed, { recursive: true });
+
+  // V155-038 (MED): project-scope lock around the entire run. Two
+  // simultaneous `ijfw_brain dream` triggers (manual + chokidar; or two
+  // operators on the same repo) would otherwise BOTH scan the same inbox,
+  // BOTH call the (paid) LLM extractor, and BOTH run the rename race for
+  // `commitProcessed` — the loser silently catches ENOENT but its facts
+  // already landed (no UNIQUE constraint on facts). Net: double-extract
+  // cost + duplicate facts + single committed file. The lock makes a
+  // concurrent invocation wait for the first to finish; the second then
+  // sees the manifests (and V155-020 facts-table cross-check) and exits
+  // with zero candidates.
+  const lockTarget = join(repoRoot, '.ijfw', 'state', '.dream-cycle.lock');
+  if (!existsSync(dirname(lockTarget))) mkdirSync(dirname(lockTarget), { recursive: true });
+  return withFsLock(lockPathFor(lockTarget), async () => runDreamCycleLocked({
+    db, repoRoot, env, paths, cid, guard, extractor,
+  }));
+}
+
+async function runDreamCycleLocked({ db, repoRoot, env, paths, cid, guard, extractor }) {
   let processed = 0;
   let factsInserted = 0;
   let pagesCompiled = 0;
@@ -202,11 +263,11 @@ export async function runDreamCycle({ db, repoRoot, env = process.env, cycleId,
   const touchedSubjects = new Set();
   const errors = [];
 
-  mkdirSync(paths.dumpInbox, { recursive: true });
-  mkdirSync(paths.dumpProcessed, { recursive: true });
-
+  // V155-020: cross-check the facts table so a `rm -rf <processed>/` cannot
+  // trigger re-ingest doubling. The manifest gate stays as the cheap first
+  // check; only filename-collision survivors get the DB query.
   const candidates = scanInbox(paths.dumpInbox).filter(
-    (f) => !isProcessed(paths.dumpProcessed, f.name)
+    (f) => !isProcessedDouble(db, paths.dumpProcessed, f.name)
   );
 
   for (const file of candidates) {
@@ -310,8 +371,10 @@ export async function runDreamCycle({ db, repoRoot, env = process.env, cycleId,
   }
 
   // Compile pages for touched subjects. Failures are logged, not fatal.
+  // V155-015: compileWikiPage is now async (withFsLock primitive).
   for (const subject of touchedSubjects) {
-    const r = compileWikiPage(db, { repoRoot, type: 'entity', subject });
+    // eslint-disable-next-line no-await-in-loop
+    const r = await compileWikiPage(db, { repoRoot, type: 'entity', subject });
     if (r.ok) {
       pagesCompiled += 1;
       appendLog(paths.wikiLog, `${nowIso()} compile entity ${subject} facts=${r.factsCount}`, repoRoot);

package/src/brain/dump-ingest.js

@@ -79,10 +79,42 @@ export function isProcessed(processedDir, fileName) {
   return existsSync(manifestPath(processedDir, fileName));
 }
 
+// readManifest: legacy behaviour — returns the parsed JSON payload directly,
+// throws on missing/unreadable/parse-fail. Callers in tests + E2E paths rely
+// on the direct round-trip shape; do NOT break the contract.
+//
+// V155-068 (v1.5.5): added `readManifestSafe` (below) for callers — like the
+// dream cycle's manifest-reprocess logic — that need to treat
+// corrupt/absent as a graceful "needs reprocess" signal rather than letting
+// JSON.parse abort the whole cycle.
 export function readManifest(processedDir, fileName) {
   return JSON.parse(readFileSync(manifestPath(processedDir, fileName), 'utf8'));
 }
 
+/**
+ * Tolerant variant of readManifest for callers that need to distinguish:
+ *   - { ok: true,  data }                       — clean read
+ *   - { ok: false, code: 'enoent' }             — manifest absent
+ *   - { ok: false, code: 'unreadable', message } — readFile threw
+ *   - { ok: false, code: 'parse-fail', message, path } — JSON.parse threw
+ *
+ * V155-068 (v1.5.5): closes the dream-cycle crash on tampered manifests.
+ */
+export function readManifestSafe(processedDir, fileName) {
+  const p = manifestPath(processedDir, fileName);
+  if (!existsSync(p)) return { ok: false, code: 'enoent' };
+  let raw;
+  try { raw = readFileSync(p, 'utf8'); }
+  catch (e) {
+    return { ok: false, code: 'unreadable', message: e?.message || String(e) };
+  }
+  try {
+    return { ok: true, data: JSON.parse(raw) };
+  } catch (e) {
+    return { ok: false, code: 'parse-fail', message: e?.message || String(e), path: p };
+  }
+}
+
 function manifestPath(processedDir, fileName) {
   return join(processedDir, `${fileName}.manifest.json`);
 }

package/src/brain/entity-collapse.js

@@ -2,8 +2,8 @@
 //
 // 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
+// form (e.g. "Jane Doe" / "jane doe" / " Jane  Doe " all collapse
+// to "jane doe"). Promotion (actual merge) is operator-confirmed -- this
 // module only surfaces candidates.
 
 export function canonicalize(s) {

package/src/brain/export.js

@@ -12,7 +12,7 @@
 // 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 { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { resolveBrainPaths } from './paths.js';
 import { validateSafeRepoPath } from './path-guard.js';
@@ -47,6 +47,34 @@ function parseWikilinks(md) {
   return [...out];
 }
 
+// V155-034 (v1.5.5): export size caps. Wiki pages are written by the dream
+// pipeline from user-droppable `dump/inbox/` content, so a poisoned dump can
+// produce a page with `[[link1]]...[[linkN]]` plus a few 100MB linked pages.
+// Without caps, `wiki.export` concatenates everything into memory and OOMs the
+// MCP server. The caps bound:
+//   - any single page (root or linked) at MAX_PAGE_BYTES
+//   - the total bundle at MAX_BUNDLE_BYTES
+// Truncated pages are replaced with a sentinel header so the consumer can
+// tell the export was capped, not silently empty.
+const MAX_PAGE_BYTES = 2 * 1024 * 1024;     // 2 MB per page
+const MAX_BUNDLE_BYTES = 10 * 1024 * 1024;  // 10 MB per bundle
+
+function readPageCapped(filePath) {
+  try {
+    const st = statSync(filePath);
+    if (st.size > MAX_PAGE_BYTES) {
+      return {
+        truncated: true,
+        sizeBytes: st.size,
+        body: `[... truncated — page is ${(st.size / 1024 / 1024).toFixed(2)} MB; export cap is ${(MAX_PAGE_BYTES / 1024 / 1024).toFixed(0)} MB ...]`,
+      };
+    }
+    return { truncated: false, sizeBytes: st.size, body: readFileSync(filePath, 'utf8') };
+  } catch (e) {
+    return { truncated: false, error: e?.message || String(e), body: null };
+  }
+}
+
 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
@@ -57,26 +85,52 @@ export function exportPageBundle(repoRoot, slug, outFile) {
   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 rootRead = readPageCapped(root.path);
+  if (rootRead.body == null) {
+    return { error: 'root-page-unreadable', slug, message: rootRead.error };
+  }
+  const rootBody = rootRead.body;
   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()}`,
   ];
+  let runningBytes = Buffer.byteLength(parts.join('\n\n'), 'utf8');
   const includedLinks = [];
+  const truncatedLinks = [];
+  const skippedLinks = [];
+  let bundleTruncated = false;
   for (const target of linked) {
+    if (runningBytes >= MAX_BUNDLE_BYTES) {
+      bundleTruncated = true;
+      skippedLinks.push(target);
+      continue;
+    }
     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()}`);
+    const r = readPageCapped(found.path);
+    if (r.body == null) continue;
+    const block = `### ${target}\n\n${r.body.trim()}`;
+    runningBytes += Buffer.byteLength(block, 'utf8') + 2; // approx '\n\n'
+    parts.push(block);
     includedLinks.push(target);
+    if (r.truncated) truncatedLinks.push(target);
   }
+  if (rootRead.truncated && !truncatedLinks.includes(slug)) truncatedLinks.unshift(slug);
+
   const out = parts.join('\n\n') + '\n';
   mkdirSync(dirname(outFile), { recursive: true });
   writeFileSync(outFile, out);
-  return { outFile, bytes: Buffer.byteLength(out, 'utf8'), linkedPagesIncluded: includedLinks };
+  return {
+    outFile,
+    bytes: Buffer.byteLength(out, 'utf8'),
+    linkedPagesIncluded: includedLinks,
+    // Diagnostic fields — only present when caps actually fired so the common
+    // case stays terse.
+    ...(truncatedLinks.length > 0 ? { truncatedPages: truncatedLinks } : {}),
+    ...(bundleTruncated ? { bundleTruncated: true, skippedLinks } : {}),
+  };
 }
 
 const SHARE_README = `# Your IJFW Brain

package/src/brain/extractors/markdown.js

@@ -1,7 +1,13 @@
 // markdown.js -- markdown + text extractor (chunk on blank-line boundaries).
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
 
 const DEFAULT_MAX_CHARS = 3000;
+// V155-067 (v1.5.5): default file-size cap. Inbox files come from
+// user-droppable `dump/inbox/`; a multi-GB drop would OOM the dream cycle
+// during `readFileSync('utf8')`. Cap at 10 MB — well above any reasonable
+// hand-written brief or transcript. Caller can override (and `scanInbox`
+// already records `sizeBytes` so the candidate filter can pre-skip).
+export const DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024;
 
 export function chunkAtBlankLines(text, maxChars = DEFAULT_MAX_CHARS) {
   if (text.length <= maxChars) return [text];
@@ -21,7 +27,27 @@ export function chunkAtBlankLines(text, maxChars = DEFAULT_MAX_CHARS) {
   return chunks;
 }
 
-export function extractMarkdown(filePath, { maxChars = DEFAULT_MAX_CHARS } = {}) {
+export function extractMarkdown(
+  filePath,
+  { maxChars = DEFAULT_MAX_CHARS, maxFileBytes = DEFAULT_MAX_FILE_BYTES } = {},
+) {
+  // V155-067 (v1.5.5): pre-stat + size cap. statSync is cheap and lets us
+  // surface a structured `error` for oversized files instead of hitting the
+  // OOM during readFileSync.
+  let st;
+  try { st = statSync(filePath); }
+  catch (e) {
+    return { text: '', chunks: [], error: 'stat-failed', message: e?.message || String(e) };
+  }
+  if (typeof maxFileBytes === 'number' && st.size > maxFileBytes) {
+    return {
+      text: '',
+      chunks: [],
+      error: 'file-too-large',
+      sizeBytes: st.size,
+      capBytes: maxFileBytes,
+    };
+  }
   const text = readFileSync(filePath, 'utf8');
   return { text, chunks: chunkAtBlankLines(text, maxChars) };
 }

package/src/brain/layout-sentinel.js

@@ -1,5 +1,6 @@
-import { readFileSync, writeFileSync, existsSync, openSync, closeSync, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { withFsLock, lockPathFor } from '../fs-lock.js';
 
 export function readLayoutVersion(repoRoot) {
   const p = join(repoRoot, '.ijfw', '.layout-version');
@@ -12,18 +13,22 @@ export function writeLayoutVersion(repoRoot, version) {
   writeFileSync(join(repoRoot, '.ijfw', '.layout-version'), `${version}\n`);
 }
 
+// V155-016 (HIGH): replace the bespoke `openSync('wx')` mutex with the
+// canonical `withFsLock` primitive. The prior implementation had no stale
+// recovery — on SIGKILL between `openSync` and the `finally` unlink, the
+// lockfile orphaned forever; next server startup would throw after 5s and
+// the operator had to manually `rm .ijfw/.migrate.lock`. `withFsLock`
+// inherits canonical heartbeat-refreshed stale recovery (live processes
+// always renew before staleMs fires; crashed holders age out cleanly).
+// The .migrate.lock path sorts to LOCK_TIERS' tier-99 fallback (unknown
+// path → tail of canonical order) so it cannot deadlock against numbered
+// §3 locks. `timeoutMs` is preserved as `acquireTimeoutMs` so the documented
+// startup-timeout behaviour is unchanged.
 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 {} }
+  const lockTarget = join(repoRoot, '.ijfw', '.migrate.lock');
+  return withFsLock(lockPathFor(lockTarget), fn, {
+    staleMs: 60_000,
+    heartbeatMs: 2_000,
+    acquireTimeoutMs: timeoutMs,
+  });
 }

package/src/brain/path-guard.js

@@ -89,11 +89,28 @@ export function validateSafeRepoPath(repoRoot, targetPath) {
   // 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.
+  //
+  // V155-055 (v1.5.5): hardlink hardening. isSymbolicLink() returns false for
+  // hardlinks, so a same-uid attacker can pre-create
+  // `<repoRoot>/.ijfw/wiki/concepts/foo.md` as a hardlink to
+  // `~/.ssh/authorized_keys`. writeAtomic via rename severs the hardlink
+  // (safe), but appendFileSync callers (budget-guard, dream-pipeline) write
+  // through the hardlink. We refuse any target file with nlink > 1 — under
+  // the brain's content tree, every file should be IJFW-owned and have nlink
+  // exactly 1.
   try {
     const st = lstatSync(resolved);
     if (st.isSymbolicLink()) {
       return { ok: false, error: 'outFile-is-symlink', resolved };
     }
+    if (st.isFile() && typeof st.nlink === 'number' && st.nlink > 1) {
+      return {
+        ok: false,
+        error: 'outFile-is-hardlink',
+        resolved,
+        nlink: st.nlink,
+      };
+    }
   } catch {
     // ENOENT — target doesn't exist yet; the most common case. OK to proceed.
   }

package/src/brain/wiki-compiler.js

@@ -9,15 +9,20 @@
 // Wiki path: <ijfw|.ijfw>/wiki/<type>s/<slug>.md per the layout sentinel.
 // Slug is the subject lowercased + non-alphanum -> '-'.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, openSync, closeSync, unlinkSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
-const STALE_LOCK_MS = 60_000; // 60s — locks older than this are assumed dead-process orphans
+// V155-054 (LOW): a poisoned wiki page on disk could blow up memory during
+// compile via the existing-page readFileSync. Refuse compile if the prior
+// page is larger than this cap.
+const WIKI_PAGE_MAX_BYTES = 2 * 1024 * 1024; // 2 MB
+
 import { resolveBrainPaths } from './paths.js';
 import { applyTemplate } from './wiki-templates.js';
 import { resolveCitations } from './citation-resolver.js';
 import { getHistoryWindow } from '../memory/temporal.js';
 import { validateSafeRepoPath } from './path-guard.js';
+import { withFsLock, lockPathFor } from '../fs-lock.js';
 
 export function slugify(s) {
   return String(s || '').toLowerCase().trim()
@@ -68,7 +73,7 @@ function querySources(db, subject) {
   } catch { return []; }
 }
 
-export function compileWikiPage(db, { repoRoot, type, subject } = {}) {
+export async function compileWikiPage(db, { repoRoot, type, subject } = {}) {
   if (!subject) return { ok: false, error: 'missing-subject' };
   const paths = resolveBrainPaths(repoRoot);
   const slug = slugify(subject);
@@ -83,42 +88,36 @@ export function compileWikiPage(db, { repoRoot, type, subject } = {}) {
   const guard = validateSafeRepoPath(repoRoot, pagePath);
   if (!guard.ok) return guard;
 
-  // F8: per-page advisory lock prevents two concurrent compiles for the
-  // same subject from interleaving (both read existing → both render →
-  // both rename → operator NOTES from the intermediate state could be
-  // lost). EEXIST-based exclusive open is portable + atomic.
   mkdirSync(pageDir, { recursive: true });
-  const lockPath = pagePath + '.lock';
-  let lockFd;
-  try {
-    lockFd = openSync(lockPath, 'wx');
-  } catch (e) {
-    if (e.code === 'EEXIST') {
-      // FLAG-8: stale-lock recovery. If a prior compile process was SIGKILL'd
-      // between acquire and finally, the lockfile orphans and every subsequent
-      // compile fails. Check the lockfile's age; if older than STALE_LOCK_MS,
-      // assume it's a dead-process orphan and reclaim.
-      let stale = false;
-      try {
-        const age = Date.now() - statSync(lockPath).mtimeMs;
-        if (age > STALE_LOCK_MS) stale = true;
-      } catch { /* lockfile vanished while we checked — race won by us */ stale = true; }
-      if (stale) {
-        try { unlinkSync(lockPath); } catch {}
-        try { lockFd = openSync(lockPath, 'wx'); }
-        catch (e2) { return { ok: false, error: 'page-locked-by-concurrent-compile', pagePath, staleReclaimFailed: e2.code }; }
-      } else {
-        return { ok: false, error: 'page-locked-by-concurrent-compile', pagePath };
-      }
-    } else {
-      throw e;
-    }
-  }
 
-  try {
+  // V155-015 (HIGH): per-page advisory lock now uses the canonical
+  // `withFsLock` primitive instead of an isolated openSync('wx') + manual
+  // stale recovery. The prior pattern had a stale-reclaim race — process A
+  // holds lock, B reads mtime >60s, B unlinks A's lockfile, B opens its own
+  // lock, BOTH then rename their .tmp into pagePath. `withFsLock` inherits
+  // heartbeat-refresh (`heartbeatMs` < `staleMs`) so a live A always renews
+  // before B's stale check fires; a crashed A's lock still ages out cleanly.
+  // The wiki-page lock sorts to LOCK_TIERS' tier-99 fallback (unknown path
+  // → tail of canonical order), so it never deadlocks against §3 locks.
+  return withFsLock(lockPathFor(pagePath), async () => {
     // Read existing AFTER acquiring the lock so we see the freshest committed
     // state (no race with another compile that just landed its rename).
-    const existing = existsSync(pagePath) ? readFileSync(pagePath, 'utf8') : '';
+    let existing = '';
+    if (existsSync(pagePath)) {
+      // V155-054 (LOW): cap the existing-page size to defend against a
+      // poisoned wiki page that would otherwise blow up memory + LLM budget
+      // during compile. 2 MB is generous — real wiki pages are <100 KB.
+      try {
+        const st = statSync(pagePath);
+        if (st.size > WIKI_PAGE_MAX_BYTES) {
+          return {
+            ok: false, error: 'page-too-large', pagePath,
+            sizeBytes: st.size, maxBytes: WIKI_PAGE_MAX_BYTES,
+          };
+        }
+      } catch { /* statSync race — proceed with read */ }
+      existing = readFileSync(pagePath, 'utf8');
+    }
     const facts = queryFacts(db, subject);
     const history = getHistoryWindow(db, subject, null, { limit: 50 });
     const backlinks = queryBacklinks(db, slug);
@@ -137,8 +136,5 @@ export function compileWikiPage(db, { repoRoot, type, subject } = {}) {
     renameSync(tmp, pagePath);
 
     return { ok: true, pagePath, factsCount: facts.length, historyRows: history.rows.length };
-  } finally {
-    try { closeSync(lockFd); } catch {}
-    try { unlinkSync(lockPath); } catch {}
-  }
+  });
 }

package/src/codex-agents.js

@@ -1,5 +1,8 @@
-import { existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
-import { isAbsolute, join, relative, resolve } from 'node:path';
+import {
+  existsSync, mkdirSync, readFileSync, realpathSync,
+  readdirSync, unlinkSync,
+} from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
 import { writeAtomic } from './lib/atomic-io.js';
 
 // F-FUN-7 (audit-MED-teams-#8): role-type → Codex tool allowlist. Honors
@@ -102,12 +105,32 @@ export function syncCodexAgents(projectRoot = process.cwd(), options = {}) {
     agentFiles.push(agentPath);
   }
 
+  // V155-063 (v1.5.5): garbage-collect TOML files for roles that no longer
+  // exist in the current charter. Without this sweep, charter A (role X+Y)
+  // → charter B (role X only) leaves `<safeAgentsDir>/y.toml` on disk and
+  // Codex continues to pick up the phantom agent. We compare the dir
+  // listing against the set of just-written agentFiles and unlink any
+  // `.toml` whose basename isn't claimed.
+  const removed = [];
+  const expected = new Set(agentFiles.map((p) => basename(p)));
+  let entries = [];
+  try { entries = readdirSync(safeAgentsDir); } catch { /* best-effort */ }
+  for (const name of entries) {
+    if (!name.endsWith('.toml')) continue;
+    if (expected.has(name)) continue;
+    const p = join(safeAgentsDir, name);
+    try { unlinkSync(p); removed.push(p); } catch { /* best-effort */ }
+  }
+
   return {
     ok: true,
     agentsDir: safeAgentsDir,
     agentFiles,
     count: agentFiles.length,
     skipped,
+    // Only surface `removed` when something was GCed so the common path stays
+    // terse.
+    ...(removed.length > 0 ? { removed } : {}),
   };
 }