@ijfw/memory-server 1.3.0

package/src/sandbox.js

@@ -0,0 +1,275 @@
+/**
+ * sandbox.js -- ijfw_run sandbox module
+ * Runs shell commands, caps output, summarizes for LLM context, spills full
+ * output to disk so the context window isn't flooded.
+ *
+ * Zero external dependencies -- Node.js built-ins only.
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, statSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const MAX_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_LINES = 50_000;
+const TIMEOUT_MS = 5 * 60 * 1000;   // 5 minutes
+
+// Strip ANSI escape sequences.
+function stripAnsi(s) {
+  return s.replace(/\x1b\[[0-9;]*[mGKHFJK]/g, ''); // eslint-disable-line no-control-regex
+}
+
+// Sanitize a label string for use as a filename.
+function sanitizeLabel(label) {
+  return String(label).replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 128);
+}
+
+/**
+ * runCommand(command, opts) → { stdout, exitCode, signal, durationMs, lines, bytes, timedOut }
+ *
+ * Spawns command in a shell. Merges stdout+stderr in arrival order, capped at
+ * MAX_BYTES / MAX_LINES. Kills the process after TIMEOUT_MS.
+ */
+export function runCommand(command, opts = {}) {
+  return new Promise((resolve) => {
+    const cwd = opts.cwd || process.cwd();
+    const start = Date.now();
+    let timedOut = false;
+    let totalBytes = 0;
+    let capped = false;
+    const chunks = [];
+
+    const child = spawn(command, [], {
+      shell: true,
+      cwd,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGKILL'); } catch {}
+    }, TIMEOUT_MS);
+
+    function onData(chunk) {
+      if (capped) return;
+      const remaining = MAX_BYTES - totalBytes;
+      if (chunk.length >= remaining) {
+        chunks.push(chunk.slice(0, remaining));
+        totalBytes += remaining;
+        capped = true;
+        try { child.kill('SIGKILL'); } catch {}
+      } else {
+        chunks.push(chunk);
+        totalBytes += chunk.length;
+      }
+    }
+
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      const raw = Buffer.concat(chunks).toString('utf8');
+      const lines = raw.split('\n').length;
+      const truncLines = Math.min(lines, MAX_LINES);
+      // If over MAX_LINES, trim to MAX_LINES worth of lines
+      const stdout = lines > MAX_LINES
+        ? raw.split('\n').slice(0, MAX_LINES).join('\n')
+        : raw;
+      const bytes = Buffer.byteLength(stdout, 'utf8');
+      resolve({
+        stdout,
+        exitCode: code,
+        signal,
+        durationMs: Date.now() - start,
+        lines: truncLines,
+        bytes,
+        timedOut,
+      });
+    });
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({
+        stdout: `spawn error: ${err.message}`,
+        exitCode: 1,
+        signal: null,
+        durationMs: Date.now() - start,
+        lines: 1,
+        bytes: 0,
+        timedOut: false,
+      });
+    });
+  });
+}
+
+/**
+ * detectDomain(output) → 'test' | 'build' | 'grep' | 'log' | 'raw'
+ * Heuristics on ANSI-stripped output.
+ */
+export function detectDomain(output) {
+  const lines = output.split('\n');
+  const sample = lines.slice(0, 500); // only inspect leading lines for speed
+
+  // test: pass/fail keywords + test count or suite name
+  if (
+    /\b(PASS|FAIL|passed|failed|\u2713|\u2717|ok|not ok)\b/i.test(output) &&
+    (/\d+\s+(test|spec|suite|passing|failing|pending)/i.test(output) || /^(PASS|FAIL)\s+/m.test(output))
+  ) {
+    return 'test';
+  }
+
+  // build: compiler/bundler error patterns
+  if (/error\[E\d|ERROR TS\d|SyntaxError|\b(webpack|vite|rollup|tsc|cargo)\b/i.test(output)) {
+    return 'build';
+  }
+
+  // grep: majority of lines are file:line: pattern
+  const grepLike = sample.filter(l => /^[^:]+:\d+:/.test(l)).length;
+  if (sample.length > 5 && grepLike / sample.length > 0.6) {
+    return 'grep';
+  }
+
+  // log: majority of lines start with ISO timestamp or [INFO]/[ERROR]/[WARN]
+  const logLike = sample.filter(l =>
+    /^\d{4}-\d{2}-\d{2}[T ]/.test(l) ||
+    /^\[?(INFO|ERROR|WARN|DEBUG)\]?[\s:]/i.test(l)
+  ).length;
+  if (sample.length > 5 && logLike / sample.length > 0.4) {
+    return 'log';
+  }
+
+  return 'raw';
+}
+
+/**
+ * summarize(output, domain, command, exitCode, durationMs) → string
+ */
+export function summarize(output, domain, command, exitCode, durationMs) {
+  const lines = output.split('\n');
+  const lineCount = lines.length;
+  const header = `[ijfw_run] ${command} exit=${exitCode} ${durationMs}ms | ${lineCount} lines`;
+
+  const parts = [header];
+
+  if (domain === 'test') {
+    // Extract pass/fail counts
+    const countMatch = output.match(/(\d+)\s+(?:test|spec|suite)s?\s+(?:passed|passing)/i)
+      || output.match(/Tests?:\s+(\d+)\s+passed/i);
+    const failMatch = output.match(/(\d+)\s+(?:test|spec|suite)s?\s+(?:failed|failing)/i)
+      || output.match(/Tests?:.*?(\d+)\s+failed/i);
+    if (countMatch || failMatch) {
+      const p = countMatch ? countMatch[1] : '?';
+      const f = failMatch ? failMatch[1] : '0';
+      parts.push(`Tests: ${p} passed, ${f} failed`);
+    }
+    // Failing test names
+    const failLines = lines.filter(l => /\b(FAIL|\u2717|not ok|\u00d7 )\b/.test(l) || /^\s+●/.test(l));
+    if (failLines.length > 0) {
+      parts.push('Failures:');
+      failLines.slice(0, 10).forEach(l => parts.push('  ' + l.trim()));
+    }
+  } else if (domain === 'build') {
+    const errorLines = lines.filter(l => /\b(error|Error|ERROR)\b/.test(l));
+    parts.push(`Build errors (${errorLines.length}):`);
+    errorLines.slice(0, 20).forEach(l => parts.push('  ' + l.trim()));
+    parts.push(`exit: ${exitCode}`);
+  } else if (domain === 'grep') {
+    const paths = new Set();
+    lines.forEach(l => {
+      const m = l.match(/^([^:]+):\d+:/);
+      if (m) paths.add(m[1]);
+    });
+    parts.push(`Matches: ${lineCount} lines | ${paths.size} unique files`);
+    Array.from(paths).slice(0, 10).forEach(p => parts.push('  ' + p));
+  } else if (domain === 'log') {
+    const notable = lines.filter(l => /\b(ERROR|WARN)\b/i.test(l));
+    parts.push(`Log: ${lineCount} lines | ${notable.length} ERROR/WARN`);
+    notable.slice(0, 20).forEach(l => parts.push('  ' + l.trim()));
+  } else {
+    // raw fallback
+    const first = lines.slice(0, 15);
+    const last = lines.slice(-5);
+    const omitted = Math.max(0, lineCount - 20);
+    first.forEach(l => parts.push(l));
+    if (omitted > 0) {
+      parts.push(`... (${omitted} lines omitted) ...`);
+      last.forEach(l => parts.push(l));
+    }
+  }
+
+  // Reliability tail: always append last 10 raw lines (except for raw which already includes them)
+  if (domain !== 'raw') {
+    parts.push('--- last 10 lines ---');
+    lines.slice(-10).forEach(l => parts.push(l));
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * writeToSandbox(label, command, output, meta) → sandboxPath (the label)
+ */
+export function writeToSandbox(label, command, output, meta) {
+  const dir = join(process.env.HOME || homedir(), '.ijfw', 'session-sandbox');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const safeLabel = sanitizeLabel(label);
+  const txtPath = join(dir, `${safeLabel}.txt`);
+  const jsonPath = join(dir, `${safeLabel}.json`);
+
+  writeFileSync(txtPath, output, { encoding: 'utf8', mode: 0o600 });
+  writeFileSync(jsonPath, JSON.stringify({
+    label: safeLabel,
+    command,
+    timestamp: new Date().toISOString(),
+    exitCode: meta.exitCode,
+    lines: meta.lines,
+    bytes: meta.bytes,
+  }), { encoding: 'utf8', mode: 0o600 });
+
+  return safeLabel;
+}
+
+/**
+ * purgeSandboxOld(maxAgeMs) -- deletes .txt + .json pairs older than maxAgeMs.
+ * Called on every ijfw_run invocation. Fast (stat+unlink only).
+ */
+export function purgeSandboxOld(maxAgeMs = 24 * 60 * 60 * 1000) {
+  const dir = join(process.env.HOME || homedir(), '.ijfw', 'session-sandbox');
+  if (!existsSync(dir)) return;
+  const now = Date.now();
+  try {
+    const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+    for (const f of files) {
+      const jsonPath = join(dir, f);
+      try {
+        const st = statSync(jsonPath);
+        if (now - st.mtimeMs > maxAgeMs) {
+          const base = f.slice(0, -5); // strip .json
+          try { unlinkSync(join(dir, `${base}.txt`)); } catch {}
+          try { unlinkSync(jsonPath); } catch {}
+        }
+      } catch { /* skip unreadable entries */ }
+    }
+  } catch { /* dir unreadable -- skip */ }
+}
+
+/**
+ * readFromSandbox(label) → string | null
+ */
+export function readFromSandbox(label) {
+  const safeLabel = sanitizeLabel(label);
+  const dir = join(process.env.HOME || homedir(), '.ijfw', 'session-sandbox');
+  const txtPath = join(dir, `${safeLabel}.txt`);
+  if (!existsSync(txtPath)) return null;
+  try {
+    return readFileSync(txtPath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export { stripAnsi };

package/src/sanitizer.js

@@ -0,0 +1,69 @@
+// --- Content sanitizer (defense against prompt-injection via stored memory) ---
+//
+// Stored content is read back and injected into LLM context on every recall.
+// An attacker who can write to .ijfw/memory/ (rogue dep, malicious teammate
+// commit, compromised plugin) controls future sessions unless we neutralize
+// the structural and semantic markdown features they could weaponize.
+//
+// Extracted from server.js in Phase 6 (audit finding X2) so ijfw-memorize
+// and any other memory writer can apply the same defang before append.
+
+export function sanitizeContent(s) {
+  if (typeof s !== 'string') return '';
+  let out = s;
+
+  // 1. Strip C0/C1 control characters (incl. NUL) except tab and newline.
+  // oxlint-disable-next-line no-control-regex -- intentional: sanitize control chars from stored content
+  out = out.replace(/[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g, '');
+
+  // 2. Strip Unicode bidi/zero-width/format chars used to hide payloads.
+  // U+200B-U+200F, U+202A-U+202E, U+2066-U+2069, U+FEFF
+  out = out.replace(/[\u200B-\u200F\u202A-\u202E\u2066-\u2069\uFEFF]/g, '');
+
+  // 3. Defang ANY heading prefix (1+ hashes, optional whitespace) -- entry must
+  // never produce a structural ## section that mimics a journal timestamp.
+  out = out.replace(/^[ \t]*#+[ \t]+/gm, '> ');
+
+  // 4. Defang setext-style headings (=== or --- under a line) -- strip the underline.
+  out = out.replace(/^[ \t]*[=-]{3,}[ \t]*$/gm, '');
+
+  // 5. Neutralize fenced code blocks (``` and ~~~) so attacker can't open a fence
+  // that swallows surrounding journal structure as "code".
+  out = out.replace(/^[ \t]*(```|~~~).*$/gm, '> $1');
+
+  // 6. Neutralize HTML/XML-style tags that LLMs may parse as instructions
+  // (<system>, </assistant>, <instructions>, etc.) -- escape angle brackets.
+  out = out.replace(/[<>]/g, ch => (ch === '<' ? '&lt;' : '&gt;'));
+
+  // 7. Collapse to single line -- multi-line stored content can't fake new
+  // journal sections. Newlines become " | " for readability.
+  out = out.replace(/\r\n?|\n/g, ' | ');
+
+  return out;
+}
+
+export function sanitizeForSandbox(s) {
+  if (typeof s !== 'string') return '';
+  let out = s;
+
+  // 1. Strip ANSI escape codes (colors, cursor movement).
+  // oxlint-disable-next-line no-control-regex -- intentional: strip ANSI from sandbox output
+  out = out.replace(/\x1b\[[0-9;]*[mGKHF]/g, '');
+
+  // 2. Strip lines starting with # (headings) -- defang prompt-injection via markdown headings.
+  out = out.replace(/^[ \t]*#+[ \t].*/gm, '');
+
+  // 3. Neutralize fenced code blocks (``` and ~~~).
+  out = out.replace(/^[ \t]*(```|~~~).*$/gm, '');
+
+  // 4. Strip <system>, <prompt>, <assistant> tag patterns (open and close).
+  out = out.replace(/<\/?(system|prompt|assistant)[^>]*>/gi, '');
+
+  // 5. Truncate any single line exceeding 2000 chars (minified JS, base64 blobs).
+  out = out
+    .split('\n')
+    .map(line => (line.length > 2000 ? line.slice(0, 200) + '...[truncated]' : line))
+    .join('\n');
+
+  return out;
+}

package/src/scan-resume.js

@@ -0,0 +1,167 @@
+// IJFW v1.3.0 Alpha -- A3 cross-session checkpoint+resume helper (V3-F2).
+//
+// Persists scan progress at <project>/.ijfw/scan-state.json so a crash
+// mid-walk on a 100k-file repo never re-scans from zero. State shape:
+//
+//   {
+//     scan_id:           string  -- opaque id, regenerated per restart
+//     started_at:        ISO8601 -- when the run began
+//     last_path_walked:  string  -- absolute path of last entry visited
+//     files_scanned:     number
+//     total_estimate:    number
+//     attempts:          number  -- bump on each resume; 3 caps it
+//     incomplete:        bool    -- false on clean finish, true on guardrail
+//     session_id:        string? -- forensic only; not used for resume
+//   }
+//
+// shouldResume() rules (per spec):
+//   - state.incomplete must be true
+//   - state.started_at must be <24h old
+//   - state.attempts must be <3 (so a 3rd attempt triggers fresh restart;
+//     a 4th is rejected by the cap)
+//
+// Atomic write: tmp + rename. POSIX rename(2) is atomic on the same fs.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, copyFileSync } from 'fs';
+import { join } from 'path';
+
+const STATE_FILE = 'scan-state.json';
+const LOCK_FILE = 'scan-state.json.lock';
+const STALENESS_MS = 24 * 60 * 60 * 1000; // 24h
+const ATTEMPT_CAP = 3;
+// P3-M6: stale-lock reclamation -- a lock older than this and with a dead
+// owner PID is reclaimable. Mirrors lock.sh's STALE_AGE_SECONDS=60.
+const LOCK_STALE_MS = 60 * 1000;
+
+function statePath(projectRoot) {
+  return join(String(projectRoot), '.ijfw', STATE_FILE);
+}
+
+export function loadScanState(projectRoot) {
+  const path = statePath(projectRoot);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') return parsed;
+  } catch { /* fall through */ }
+  return null;
+}
+
+export function writeScanState(projectRoot, state) {
+  const dir = join(String(projectRoot), '.ijfw');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const finalPath = statePath(projectRoot);
+  const tmpPath = `${finalPath}.tmp.${process.pid}.${Date.now()}`;
+  const safe = {
+    scan_id: String(state.scan_id || ''),
+    started_at: String(state.started_at || new Date().toISOString()),
+    last_path_walked: String(state.last_path_walked || ''),
+    files_scanned: Number.isFinite(state.files_scanned) ? state.files_scanned : 0,
+    total_estimate: Number.isFinite(state.total_estimate) ? state.total_estimate : 0,
+    attempts: Number.isFinite(state.attempts) ? state.attempts : 1,
+    incomplete: state.incomplete !== false,
+    session_id: state.session_id || null,
+  };
+  // P3-H3: persist accumulated partial walk state (counters, fingerprint
+  // sample, manifest hits, dir hits, ext totals, pattern hits) so resume
+  // continues to add to it rather than restarting at zero.
+  if (state.partial && typeof state.partial === 'object') {
+    safe.partial = state.partial;
+  }
+  writeFileSync(tmpPath, JSON.stringify(safe, null, 2) + '\n', 'utf8');
+  // P3-H5: cross-mount symlink layouts raise EXDEV from rename; copy +
+  // unlink keeps the write durable on dotfile setups where .ijfw/ lives
+  // on a different filesystem than the temp file.
+  try {
+    renameSync(tmpPath, finalPath);
+  } catch (err) {
+    if (!err || err.code !== 'EXDEV') throw err;
+    try {
+      copyFileSync(tmpPath, finalPath);
+    } finally {
+      try { unlinkSync(tmpPath); } catch { /* best-effort */ }
+    }
+  }
+  return finalPath;
+}
+
+// P3-M6: TOCTOU lock helpers for scan-state.json. Mirrors the noclobber
+// CAS pattern used by lock.sh -- exclusive create, PID + epoch_ms inside,
+// stale-lock reclamation on dead owners or age > LOCK_STALE_MS.
+function lockPath(projectRoot) {
+  return join(String(projectRoot), '.ijfw', LOCK_FILE);
+}
+
+function isPidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+function reclaimIfStale(lp) {
+  if (!existsSync(lp)) return;
+  let raw;
+  try { raw = readFileSync(lp, 'utf8'); } catch { return; }
+  const lines = String(raw).split(/\r?\n/);
+  const pid = Number(lines[0]);
+  const ts = Number(lines[1]);
+  const ageOk = Number.isFinite(ts) && (Date.now() - ts) <= LOCK_STALE_MS;
+  if (isPidAlive(pid) && ageOk) return;
+  try { unlinkSync(lp); } catch { /* best-effort */ }
+}
+
+/**
+ * acquireScanLock(projectRoot) -> { released } | null
+ * Returns null when another live writer holds the lock; the caller MUST
+ * skip its write rather than racing. On success, callers must invoke
+ * the returned `released` function (or implicitly release on process exit).
+ */
+export function acquireScanLock(projectRoot) {
+  const dir = join(String(projectRoot), '.ijfw');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const lp = lockPath(projectRoot);
+  reclaimIfStale(lp);
+  const payload = String(process.pid) + '\n' + String(Date.now()) + '\n';
+  try {
+    writeFileSync(lp, payload, { encoding: 'utf8', flag: 'wx' });
+  } catch (err) {
+    if (err && err.code === 'EEXIST') return null;
+    throw err;
+  }
+  let released = false;
+  return {
+    released: () => {
+      if (released) return;
+      released = true;
+      try { unlinkSync(lp); } catch { /* best-effort */ }
+    },
+  };
+}
+
+export function shouldResume(state) {
+  if (!state || typeof state !== 'object') return false;
+  if (state.incomplete !== true) return false;
+  if (!state.started_at || typeof state.started_at !== 'string') return false;
+  const startedMs = Date.parse(state.started_at);
+  if (!Number.isFinite(startedMs)) return false;
+  const ageMs = Date.now() - startedMs;
+  if (ageMs > STALENESS_MS) return false;
+  const attempts = Number.isFinite(state.attempts) ? state.attempts : 0;
+  if (attempts >= ATTEMPT_CAP) return false;
+  return true;
+}
+
+export function clearScanState(projectRoot) {
+  const path = statePath(projectRoot);
+  if (existsSync(path)) {
+    try { unlinkSync(path); } catch { /* best-effort */ }
+  }
+}
+
+export const __test = { STALENESS_MS, ATTEMPT_CAP, LOCK_STALE_MS, statePath, lockPath };

package/src/schema.js

@@ -0,0 +1,82 @@
+// --- Memory schema versioning (audit R1) ---
+// Changes to memory file structure bump this constant. Readers auto-migrate
+// legacy files on next touch (prepend-only, no data loss). Gives us room
+// to evolve the on-disk format in future waves without silent corruption.
+
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+
+export const MEMORY_SCHEMA = 'v1';
+export const SCHEMA_HEADER = `<!-- ijfw-schema: ${MEMORY_SCHEMA} -->`;
+export const LEGACY_HEADER_RE = /^<!-- ijfw[- ]schema[:\s][^>]*-->/;
+
+export function ensureSchemaHeader(filepath) {
+  if (!existsSync(filepath)) {
+    writeFileSync(filepath, SCHEMA_HEADER + '\n\n');
+    return 'created';
+  }
+  const cur = readFileSync(filepath, 'utf-8');
+  if (cur.startsWith(SCHEMA_HEADER)) return 'current';
+  writeFileSync(filepath, SCHEMA_HEADER + '\n\n' + cur);
+  return 'migrated';
+}
+
+// W3.2 / ST4 -- corruption recovery.
+// If a memory file is non-zero but fails a structure sanity check,
+// quarantine it to <name>.corrupt.<ts> and seed a fresh file. Returns
+// 'ok' | 'recovered' | 'created'. Called before any read that treats
+// the file as canonical (knowledge.md, handoff.md, project-journal.md).
+//
+// Sanity: file must parse as UTF-8 and either (a) start with an ijfw
+// schema header or (b) be plain markdown with a leading `#` heading.
+// Otherwise we treat it as corrupt and recover. Conservative by design:
+// false positives cost a rename, not data.
+export function recoverIfCorrupt(filepath) {
+  if (!existsSync(filepath)) return 'ok';
+  let cur;
+  try {
+    cur = readFileSync(filepath, 'utf-8');
+  } catch (e) {
+    return quarantine(filepath, cur, `read-failed:${e.code || e.message}`);
+  }
+  if (!cur) return 'ok'; // empty file is fine
+  // Well-formed: schema header OR legacy header OR markdown heading.
+  if (cur.startsWith(SCHEMA_HEADER)) return 'ok';
+  if (LEGACY_HEADER_RE.test(cur)) return 'ok';
+  if (/^\s*#/.test(cur)) return 'ok';
+  // Binary-ish? Look for high ratio of non-printable bytes.
+  const sample = cur.slice(0, 2048);
+  // oxlint-disable-next-line no-control-regex -- intentional: binary corruption detection
+  const bad = (sample.match(/[\u0000-\u0008\u000E-\u001F]/g) || []).length;
+  if (bad / Math.max(1, sample.length) > 0.02) {
+    return quarantine(filepath, cur, 'binary-content');
+  }
+  // Default: treat as ok -- preserve user's plain-text content even without
+  // structure markers. We only recover on true corruption.
+  return 'ok';
+}
+
+function quarantine(filepath, content, reason) {
+  try {
+    const ts = Date.now();
+    const quarantinePath = join(dirname(filepath), `${basename(filepath)}.corrupt.${ts}`);
+    if (content != null) {
+      writeFileSync(quarantinePath, `<!-- ijfw-quarantine reason=${reason} at=${new Date(ts).toISOString()} -->\n\n${content}`);
+    } else {
+      // Y4 -- renameSync can transiently fail on Windows when an indexer or
+      // AV holds a short lock on the file. Retry a few times with 50ms spacing.
+      let renamed = false;
+      for (let i = 0; i < 4 && !renamed; i++) {
+        try { renameSync(filepath, quarantinePath); renamed = true; }
+        catch {
+          const wait = Date.now() + 50;
+          while (Date.now() < wait) { /* busy-wait; sync path */ }
+        }
+      }
+    }
+    writeFileSync(filepath, SCHEMA_HEADER + '\n\n');
+    return 'recovered';
+  } catch {
+    return 'ok'; // never block a caller over recovery failure
+  }
+}