@optave/codegraph 3.9.4 → 3.9.6

package/src/domain/graph/builder/stages/collect-files.ts

@@ -7,11 +7,13 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { performance } from 'node:perf_hooks';
 import { debug, info } from '../../../../infrastructure/logger.js';
 import { normalizePath } from '../../../../shared/constants.js';
+import { compileGlobs } from '../../../../shared/globs.js';
 import { readJournal } from '../../journal.js';
 import type { PipelineContext } from '../context.js';
-import { collectFiles as collectFilesUtil } from '../helpers.js';
+import { collectFiles as collectFilesUtil, passesIncludeExclude } from '../helpers.js';
 
 /**
  * Reconstruct allFiles from DB file_hashes + journal deltas.
@@ -20,7 +22,7 @@ import { collectFiles as collectFilesUtil } from '../helpers.js';
 function tryFastCollect(
   ctx: PipelineContext,
 ): { files: string[]; directories: Set<string> } | null {
-  const { db, rootDir } = ctx;
+  const { db, rootDir, config } = ctx;
   const useNative = ctx.engineName === 'native' && !!ctx.nativeDb?.getCollectFilesData;
 
   // 1. Check that file_hashes table exists and has entries
@@ -70,10 +72,20 @@ function tryFastCollect(
     }
   }
 
-  // 5. Convert to absolute paths and compute directories
+  // 5. Convert to absolute paths and compute directories, honoring
+  //    config.include / config.exclude globs so incremental builds reflect
+  //    config changes (paths from the DB were collected under older config).
+  const includeRegexes = compileGlobs(config?.include);
+  const excludeRegexes = compileGlobs(config?.exclude);
+  const hasGlobFilters = includeRegexes.length > 0 || excludeRegexes.length > 0;
+
   const files: string[] = [];
   const directories = new Set<string>();
   for (const relPath of fileSet) {
+    if (hasGlobFilters) {
+      const normRel = normalizePath(relPath);
+      if (!passesIncludeExclude(normRel, includeRegexes, excludeRegexes)) continue;
+    }
     const absPath = path.join(rootDir, relPath);
     files.push(absPath);
     directories.add(path.dirname(absPath));
@@ -89,42 +101,60 @@ export async function collectFiles(ctx: PipelineContext): Promise<void> {
   const { rootDir, config, opts } = ctx;
 
   if (opts.scope) {
-    // Scoped rebuild: rebuild only specified files
+    // Scoped rebuild: rebuild only specified files.
+    //
+    // Timer only wraps the filesystem-walk portion (existence checks + file
+    // list construction). Change-detection outputs (parseChanges, removed,
+    // isFullBuild) are attributed to detectMs for semantic consistency with
+    // the non-scoped path, even though this stage computes them.
+    const start = performance.now();
     const scopedFiles = opts.scope.map((f: string) => normalizePath(f));
     const existing: Array<{ file: string; relPath: string }> = [];
     const missing: string[] = [];
-    for (const rel of scopedFiles) {
-      const abs = path.join(rootDir, rel);
-      if (fs.existsSync(abs)) {
-        existing.push({ file: abs, relPath: rel });
-      } else {
-        missing.push(rel);
+    try {
+      for (const rel of scopedFiles) {
+        const abs = path.join(rootDir, rel);
+        if (fs.existsSync(abs)) {
+          existing.push({ file: abs, relPath: rel });
+        } else {
+          missing.push(rel);
+        }
       }
+      ctx.allFiles = existing.map((e) => e.file);
+      ctx.discoveredDirs = new Set(existing.map((e) => path.dirname(e.file)));
+    } finally {
+      ctx.timing.collectMs = performance.now() - start;
     }
-    ctx.allFiles = existing.map((e) => e.file);
-    ctx.discoveredDirs = new Set(existing.map((e) => path.dirname(e.file)));
+    // Change-detection outputs — timed under detectMs for semantic parity.
+    const detectStart = performance.now();
     ctx.parseChanges = existing;
     ctx.metadataUpdates = [];
     ctx.removed = missing;
     ctx.isFullBuild = false;
+    ctx.timing.detectMs = (ctx.timing.detectMs ?? 0) + (performance.now() - detectStart);
     info(`Scoped rebuild: ${existing.length} files to rebuild, ${missing.length} to purge`);
     return;
   }
 
-  // Incremental fast path: reconstruct file list from DB + journal deltas
-  // instead of full recursive filesystem scan (~8ms savings on 473 files).
-  if (ctx.incremental && !ctx.forceFullRebuild) {
-    const fast = tryFastCollect(ctx);
-    if (fast) {
-      ctx.allFiles = fast.files;
-      ctx.discoveredDirs = fast.directories;
-      info(`Found ${ctx.allFiles.length} files (cached)`);
-      return;
+  const start = performance.now();
+  try {
+    // Incremental fast path: reconstruct file list from DB + journal deltas
+    // instead of full recursive filesystem scan (~8ms savings on 473 files).
+    if (ctx.incremental && !ctx.forceFullRebuild) {
+      const fast = tryFastCollect(ctx);
+      if (fast) {
+        ctx.allFiles = fast.files;
+        ctx.discoveredDirs = fast.directories;
+        info(`Found ${ctx.allFiles.length} files (cached)`);
+        return;
+      }
     }
-  }
 
-  const collected = collectFilesUtil(rootDir, [], config, new Set<string>());
-  ctx.allFiles = collected.files;
-  ctx.discoveredDirs = collected.directories;
-  info(`Found ${ctx.allFiles.length} files to parse`);
+    const collected = collectFilesUtil(rootDir, [], config, new Set<string>());
+    ctx.allFiles = collected.files;
+    ctx.discoveredDirs = collected.directories;
+    info(`Found ${ctx.allFiles.length} files to parse`);
+  } finally {
+    ctx.timing.collectMs = performance.now() - start;
+  }
 }

package/src/domain/graph/builder/stages/detect-changes.ts

@@ -7,6 +7,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { performance } from 'node:perf_hooks';
 import { closeDb } from '../../../../db/index.js';
 import { debug, info } from '../../../../infrastructure/logger.js';
 import { normalizePath } from '../../../../shared/constants.js';
@@ -512,59 +513,66 @@ function handleIncrementalBuild(ctx: PipelineContext): void {
 }
 
 export async function detectChanges(ctx: PipelineContext): Promise<void> {
-  const { db, allFiles, rootDir, incremental, forceFullRebuild, opts } = ctx;
-  if ((opts as Record<string, unknown>).scope) {
-    handleScopedBuild(ctx);
-    return;
-  }
-  const increResult =
-    incremental && !forceFullRebuild
-      ? getChangedFiles(db, allFiles, rootDir)
-      : {
-          changed: allFiles.map((f): ChangedFile => ({ file: f })),
-          removed: [] as string[],
-          isFullBuild: true,
-        };
-  ctx.removed = increResult.removed;
-  ctx.isFullBuild = increResult.isFullBuild;
-  ctx.parseChanges = increResult.changed
-    .filter((c) => !c.metadataOnly)
-    .map((c) => ({
-      file: c.file,
-      relPath: c.relPath,
-      content: c.content,
-      hash: c.hash,
-      stat: c.stat ? { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size } : undefined,
-      _reverseDepOnly: c._reverseDepOnly,
-    }));
-  ctx.metadataUpdates = increResult.changed
-    .filter(
-      (c): c is ChangedFile & { relPath: string; hash: string; stat: FileStat } =>
-        !!c.metadataOnly && !!c.relPath && !!c.hash && !!c.stat,
-    )
-    .map((c) => ({
-      relPath: c.relPath,
-      hash: c.hash,
-      stat: { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size },
-    }));
-  if (!ctx.isFullBuild && ctx.parseChanges.length === 0 && ctx.removed.length === 0) {
-    const ranAnalysis = await runPendingAnalysis(ctx);
-    if (ranAnalysis) {
+  const start = performance.now();
+  try {
+    const { db, allFiles, rootDir, incremental, forceFullRebuild, opts } = ctx;
+    if ((opts as Record<string, unknown>).scope) {
+      handleScopedBuild(ctx);
+      return;
+    }
+    const increResult =
+      incremental && !forceFullRebuild
+        ? getChangedFiles(db, allFiles, rootDir)
+        : {
+            changed: allFiles.map((f): ChangedFile => ({ file: f })),
+            removed: [] as string[],
+            isFullBuild: true,
+          };
+    ctx.removed = increResult.removed;
+    ctx.isFullBuild = increResult.isFullBuild;
+    ctx.parseChanges = increResult.changed
+      .filter((c) => !c.metadataOnly)
+      .map((c) => ({
+        file: c.file,
+        relPath: c.relPath,
+        content: c.content,
+        hash: c.hash,
+        stat: c.stat ? { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size } : undefined,
+        _reverseDepOnly: c._reverseDepOnly,
+      }));
+    ctx.metadataUpdates = increResult.changed
+      .filter(
+        (c): c is ChangedFile & { relPath: string; hash: string; stat: FileStat } =>
+          !!c.metadataOnly && !!c.relPath && !!c.hash && !!c.stat,
+      )
+      .map((c) => ({
+        relPath: c.relPath,
+        hash: c.hash,
+        stat: { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size },
+      }));
+    if (!ctx.isFullBuild && ctx.parseChanges.length === 0 && ctx.removed.length === 0) {
+      const ranAnalysis = await runPendingAnalysis(ctx);
+      if (ranAnalysis) {
+        closeDb(db);
+        writeJournalHeader(rootDir, Date.now());
+        ctx.earlyExit = true;
+        return;
+      }
+      healMetadata(ctx);
+      info('No changes detected. Graph is up to date.');
       closeDb(db);
       writeJournalHeader(rootDir, Date.now());
       ctx.earlyExit = true;
       return;
     }
-    healMetadata(ctx);
-    info('No changes detected. Graph is up to date.');
-    closeDb(db);
-    writeJournalHeader(rootDir, Date.now());
-    ctx.earlyExit = true;
-    return;
-  }
-  if (ctx.isFullBuild) {
-    handleFullBuild(ctx);
-  } else {
-    handleIncrementalBuild(ctx);
+    if (ctx.isFullBuild) {
+      handleFullBuild(ctx);
+    } else {
+      handleIncrementalBuild(ctx);
+    }
+  } finally {
+    // Additive to respect any partial detectMs contribution from collectFiles
+    // (scoped-rebuild path splits change-detection outputs across both stages).
+    ctx.timing.detectMs = (ctx.timing.detectMs ?? 0) + (performance.now() - start);
   }
 }

package/src/domain/graph/builder/stages/finalize.ts

@@ -3,6 +3,7 @@
  *
  * WASM cleanup, stats logging, drift detection, build metadata, registry, journal.
  */
+import fs from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
@@ -88,6 +89,19 @@ function persistBuildMetadata(
   // subsequent build to be a full rebuild.
   const codeVersionToWrite =
     ctx.engineName === 'native' && ctx.engineVersion ? ctx.engineVersion : CODEGRAPH_VERSION;
+  // Persist the repo root so downstream commands (e.g. `codegraph embed`)
+  // can resolve relative file paths regardless of the invoking cwd.
+  // Use realpathSync (symlink-resolving) to match the Rust engine's
+  // std::fs::canonicalize — otherwise the JS write here would overwrite the
+  // canonical path Rust wrote for native full builds and could re-introduce
+  // a non-canonical path when the project root is behind a symlink.
+  const resolvedRootDir = path.resolve(ctx.rootDir);
+  let rootDirToWrite = resolvedRootDir;
+  try {
+    rootDirToWrite = fs.realpathSync(resolvedRootDir);
+  } catch {
+    /* realpath can fail (e.g. path no longer exists); fall back to resolve() */
+  }
   try {
     if (useNativeDb) {
       ctx.nativeDb!.setBuildMeta(
@@ -99,6 +113,7 @@ function persistBuildMetadata(
           built_at: buildNow.toISOString(),
           node_count: String(nodeCount),
           edge_count: String(actualEdgeCount),
+          root_dir: rootDirToWrite,
         }).map(([key, value]) => ({ key, value: String(value) })),
       );
     } else {
@@ -110,6 +125,7 @@ function persistBuildMetadata(
         built_at: buildNow.toISOString(),
         node_count: nodeCount,
         edge_count: actualEdgeCount,
+        root_dir: rootDirToWrite,
       });
     }
   } catch (err) {

package/src/domain/graph/journal.ts

@@ -1,9 +1,224 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { debug, warn } from '../../infrastructure/logger.js';
 
 export const JOURNAL_FILENAME = 'changes.journal';
 const HEADER_PREFIX = '# codegraph-journal v1 ';
+const LOCK_SUFFIX = '.lock';
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_MS = 25;
+
+// Busy-spin sleep avoids blocking the Node.js event loop (unlike Atomics.wait,
+// which freezes all I/O and timer callbacks). The retry interval is short
+// (25ms), so the CPU cost is negligible while keeping unrelated callbacks
+// responsive in watcher processes.
+function sleepSync(ms: number): void {
+  const end = process.hrtime.bigint() + BigInt(ms) * 1_000_000n;
+  while (process.hrtime.bigint() < end) {
+    /* spin */
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM means the process exists but we lack permission — still alive.
+    return (e as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+interface AcquiredLock {
+  fd: number;
+  nonce: string;
+}
+
+/**
+ * Steal a stale lockfile atomically via write-tmp + rename.
+ *
+ * Using rename (which is atomic on POSIX and Windows) avoids the TOCTOU race
+ * inherent to the unlink + openSync('wx') pattern: if two stealers both
+ * observed the same stale holder, one's unlink could cross the other's fresh
+ * acquisition, admitting two writers into the critical section.
+ *
+ * After rename, we re-read the lockfile to confirm our nonce — if another
+ * stealer's rename landed after ours, they own the lock and we retry.
+ */
+function trySteal(lockPath: string): AcquiredLock | null {
+  const nonce = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+  const tmpPath = `${lockPath}.${nonce}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, `${process.pid}\n${nonce}\n`, { flag: 'w' });
+  } catch {
+    return null;
+  }
+
+  try {
+    // Atomic replace: overwrites the stale lockfile.
+    fs.renameSync(tmpPath, lockPath);
+  } catch {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+      /* ignore */
+    }
+    return null;
+  }
+
+  // Verify the nonce — another stealer's rename may have landed after ours.
+  let content: string;
+  try {
+    content = fs.readFileSync(lockPath, 'utf-8');
+  } catch {
+    return null;
+  }
+  if (!content.includes(nonce)) {
+    // Lost the race to another stealer; do NOT unlink their live lockfile.
+    return null;
+  }
+
+  let fd: number;
+  try {
+    // Re-open r+ so we have a persistent fd the caller can close on release.
+    fd = fs.openSync(lockPath, 'r+');
+  } catch {
+    return null;
+  }
+  return { fd, nonce };
+}
+
+function acquireJournalLock(lockPath: string): AcquiredLock {
+  const start = Date.now();
+  for (;;) {
+    const nonce = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      try {
+        fs.writeSync(fd, `${process.pid}\n${nonce}\n`);
+      } catch {
+        // Stamp write failed (ENOSPC, I/O error). An empty lockfile would
+        // look stale to concurrent waiters (Number('') === 0, isPidAlive(0)
+        // returns false), so they'd steal our live lock. Release and retry.
+        try {
+          fs.closeSync(fd);
+        } catch {
+          /* ignore */
+        }
+        try {
+          fs.unlinkSync(lockPath);
+        } catch {
+          /* ignore */
+        }
+        if (Date.now() - start > LOCK_TIMEOUT_MS) {
+          throw new Error(
+            `Failed to acquire journal lock at ${lockPath} within ${LOCK_TIMEOUT_MS}ms`,
+          );
+        }
+        sleepSync(LOCK_RETRY_MS);
+        continue;
+      }
+      return { fd, nonce };
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
+    }
+
+    let holderAlive = true;
+    try {
+      const pidContent = fs.readFileSync(lockPath, 'utf-8').split('\n')[0]!.trim();
+      holderAlive = isPidAlive(Number(pidContent));
+    } catch {
+      /* unreadable — fall through to age check */
+    }
+
+    let shouldSteal = !holderAlive;
+    if (holderAlive) {
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+          shouldSteal = true;
+        }
+      } catch {
+        /* stat failed — keep retrying */
+      }
+    }
+
+    if (shouldSteal) {
+      const stolen = trySteal(lockPath);
+      if (stolen) return stolen;
+      // Steal failed or lost the race — fall through to timeout check & retry.
+    }
+
+    if (Date.now() - start > LOCK_TIMEOUT_MS) {
+      throw new Error(`Failed to acquire journal lock at ${lockPath} within ${LOCK_TIMEOUT_MS}ms`);
+    }
+    sleepSync(LOCK_RETRY_MS);
+  }
+}
+
+function releaseJournalLock(lockPath: string, lock: AcquiredLock): void {
+  try {
+    fs.closeSync(lock.fd);
+  } catch {
+    /* ignore */
+  }
+  // Only unlink if the lockfile still carries our nonce — if another stealer
+  // decided we were stale and replaced it, we must not unlink their live lock.
+  try {
+    const content = fs.readFileSync(lockPath, 'utf-8');
+    if (content.includes(lock.nonce)) {
+      fs.unlinkSync(lockPath);
+    }
+  } catch {
+    /* lockfile gone or unreadable — nothing to unlink */
+  }
+}
+
+function sweepStaleTmpFiles(dir: string): void {
+  // Clean up orphaned .tmp files left behind when a process is killed after
+  // writeFileSync(tmpPath, ...) succeeds but before renameSync(tmpPath, lockPath)
+  // completes (trySteal path). Without this, tmp files accumulate silently in
+  // .codegraph/ across crash cycles. Only sweep ones older than LOCK_STALE_MS
+  // so we don't race an in-flight steal on another process.
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  const prefix = `${JOURNAL_FILENAME}${LOCK_SUFFIX}.`;
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.startsWith(prefix) || !entry.name.endsWith('.tmp')) {
+      continue;
+    }
+    const tmpPath = path.join(dir, entry.name);
+    try {
+      const stat = fs.statSync(tmpPath);
+      if (now - stat.mtimeMs > LOCK_STALE_MS) {
+        fs.unlinkSync(tmpPath);
+      }
+    } catch {
+      /* stat/unlink raced another cleaner or was already removed — ignore */
+    }
+  }
+}
+
+function withJournalLock<T>(rootDir: string, fn: () => T): T {
+  const dir = path.join(rootDir, '.codegraph');
+  fs.mkdirSync(dir, { recursive: true });
+  sweepStaleTmpFiles(dir);
+  const lockPath = path.join(dir, `${JOURNAL_FILENAME}${LOCK_SUFFIX}`);
+  const lock = acquireJournalLock(lockPath);
+  try {
+    return fn();
+  } finally {
+    releaseJournalLock(lockPath, lock);
+  }
+}
 
 interface JournalResult {
   valid: boolean;
@@ -63,43 +278,85 @@ export function appendJournalEntries(
   rootDir: string,
   entries: Array<{ file: string; deleted?: boolean }>,
 ): void {
-  const dir = path.join(rootDir, '.codegraph');
-  const journalPath = path.join(dir, JOURNAL_FILENAME);
+  withJournalLock(rootDir, () => {
+    const journalPath = path.join(rootDir, '.codegraph', JOURNAL_FILENAME);
 
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
+    if (!fs.existsSync(journalPath)) {
+      fs.writeFileSync(journalPath, `${HEADER_PREFIX}0\n`);
+    }
 
-  if (!fs.existsSync(journalPath)) {
-    fs.writeFileSync(journalPath, `${HEADER_PREFIX}0\n`);
-  }
+    const lines = entries.map((e) => {
+      if (e.deleted) return `DELETED ${e.file}`;
+      return e.file;
+    });
 
-  const lines = entries.map((e) => {
-    if (e.deleted) return `DELETED ${e.file}`;
-    return e.file;
+    fs.appendFileSync(journalPath, `${lines.join('\n')}\n`);
   });
-
-  fs.appendFileSync(journalPath, `${lines.join('\n')}\n`);
 }
 
 export function writeJournalHeader(rootDir: string, timestamp: number): void {
-  const dir = path.join(rootDir, '.codegraph');
-  const journalPath = path.join(dir, JOURNAL_FILENAME);
-  const tmpPath = `${journalPath}.tmp`;
+  withJournalLock(rootDir, () => {
+    const journalPath = path.join(rootDir, '.codegraph', JOURNAL_FILENAME);
+    const tmpPath = `${journalPath}.tmp`;
 
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
+    try {
+      fs.writeFileSync(tmpPath, `${HEADER_PREFIX}${timestamp}\n`);
+      fs.renameSync(tmpPath, journalPath);
+    } catch (err) {
+      warn(`Failed to write journal header: ${(err as Error).message}`);
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        /* ignore */
+      }
+    }
+  });
+}
 
-  try {
-    fs.writeFileSync(tmpPath, `${HEADER_PREFIX}${timestamp}\n`);
-    fs.renameSync(tmpPath, journalPath);
-  } catch (err) {
-    warn(`Failed to write journal header: ${(err as Error).message}`);
+/**
+ * Atomically append entries while advancing the header timestamp.
+ *
+ * Used by the watcher: without this, the header timestamp stays frozen at the
+ * last build's finalize time while entries accumulate, so the next build's
+ * Tier 0 check sees `journal.timestamp < MAX(file_hashes.mtime)`, rejects the
+ * journal, and falls through to the expensive mtime+size / hash scan.
+ *
+ * Writes a tmp file then renames — a crash mid-rename leaves the previous
+ * journal state intact.
+ */
+export function appendJournalEntriesAndStampHeader(
+  rootDir: string,
+  entries: Array<{ file: string; deleted?: boolean }>,
+  timestamp: number,
+): void {
+  withJournalLock(rootDir, () => {
+    const journalPath = path.join(rootDir, '.codegraph', JOURNAL_FILENAME);
+    const tmpPath = `${journalPath}.tmp`;
+
+    let existingBody = '';
     try {
-      fs.unlinkSync(tmpPath);
+      const content = fs.readFileSync(journalPath, 'utf-8');
+      const newlineIdx = content.indexOf('\n');
+      if (newlineIdx >= 0) existingBody = content.slice(newlineIdx + 1);
     } catch {
-      /* ignore */
+      /* no existing journal — fall through to write header + new entries */
     }
-  }
+    if (existingBody && !existingBody.endsWith('\n')) existingBody = `${existingBody}\n`;
+
+    const newLines = entries.map((e) => (e.deleted ? `DELETED ${e.file}` : e.file));
+    const appended = newLines.length > 0 ? `${newLines.join('\n')}\n` : '';
+    const content = `${HEADER_PREFIX}${timestamp}\n${existingBody}${appended}`;
+
+    try {
+      fs.writeFileSync(tmpPath, content);
+      fs.renameSync(tmpPath, journalPath);
+    } catch (err) {
+      warn(`Failed to update journal: ${(err as Error).message}`);
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        /* ignore */
+      }
+    }
+  });
 }