@lincoln504/pi-research 1.1.2 → 1.2.0

package/src/security/github-advisories.ts

@@ -17,6 +17,7 @@ import { normalizeEcosystem } from './ecosystem.ts';
 import { createTimeoutSignal, retryWithBackoff, isTransientError } from '../web-research/retry-utils.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError } from '../utils/http-body.ts';
 import { logger } from '../logger.ts';
 import {
   isGitHubAdvisoryRaw,
@@ -153,10 +154,16 @@ export async function searchGitHubAdvisories(
 
       let data: unknown;
       try {
-        data = await response.json();
-      } catch {
+        data = await readJsonCapped(response);
+      } catch (err) {
+        // Size failures keep their own identity rather than being reported as a
+        // syntax error, which would point diagnosis at the wrong thing entirely.
+        if (err instanceof BodyTooLargeError) {
+          metrics.increment('github_search_errors_total', 1, { error_type: 'body_too_large' });
+          throw err;
+        }
         metrics.increment('github_search_errors_total', 1, { error_type: 'malformed_json' });
-        throw new Error('GitHub API returned a malformed JSON response (repo advisories).');
+        throw new Error('GitHub API returned a malformed JSON response (repo advisories).', { cause: err });
       }
       let repoAdvisories: readonly GitHubAdvisoryRaw[] = [];
 
@@ -244,10 +251,14 @@ export async function searchGitHubAdvisories(
         // A 404 on a direct GHSA/CVE lookup means "no such advisory", not failure.
         let data: unknown;
         try {
-          data = await response.json();
-        } catch {
+          data = await readJsonCapped(response);
+        } catch (err) {
+          if (err instanceof BodyTooLargeError) {
+            metrics.increment('github_search_errors_total', 1, { error_type: 'body_too_large', endpoint: endpointType });
+            throw err;
+          }
           metrics.increment('github_search_errors_total', 1, { error_type: 'malformed_json', endpoint: endpointType });
-          throw new Error(`GitHub API returned a malformed JSON response for term "${term}".`);
+          throw new Error(`GitHub API returned a malformed JSON response for term "${term}".`, { cause: err });
         }
         let items: readonly GitHubAdvisoryRaw[] = [];
 
@@ -259,7 +270,7 @@ export async function searchGitHubAdvisories(
           items = data.items.filter(isGitHubAdvisoryRaw);
         }
 
-        metrics.increment(items.length > 0 ? 'github_cache_hits_total' : 'github_cache_misses_total', 1, { term, endpoint: endpointType });
+        metrics.increment(items.length > 0 ? 'github_cache_hits_total' : 'github_cache_misses_total', 1, { endpoint: endpointType });
 
         return items.map(mapGitHubAdvisory);
       };

package/src/security/nvd-client.ts

@@ -24,6 +24,7 @@ import { createTimeoutSignal, retryWithBackoff, isTransientError } from '../web-
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { safeUnref } from '../utils/safe-unref.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError, MAX_BULK_JSON_BODY_BYTES } from '../utils/http-body.ts';
 import {
   isWeaknessDescription,
   isWeakness,
@@ -396,11 +397,17 @@ async function fetchPaginated(
     const response = await fetchWithRetry(url, signal);
     let data: unknown;
     try {
-      data = await response.json();
-    } catch {
+      // A page can legitimately carry up to MAX_RESULTS_PER_PAGE (2000) full CVE
+      // records, so pagination reads against the bulk cap rather than the default.
+      data = await readJsonCapped(response, MAX_BULK_JSON_BODY_BYTES);
+    } catch (err) {
       // A 200 with a truncated/HTML body (proxy or CDN error page) would otherwise
-      // throw and discard this whole term. Stop paginating this term instead.
-      metrics.increment('nvd_search_errors_total', 1, { error_type: 'malformed_json' });
+      // throw and discard this whole term. Stop paginating this term instead —
+      // the pages already gathered are kept. An over-cap body degrades the same
+      // way but is counted separately so the cause stays diagnosable.
+      metrics.increment('nvd_search_errors_total', 1, {
+        error_type: err instanceof BodyTooLargeError ? 'body_too_large' : 'malformed_json',
+      });
       break;
     }
 
@@ -412,10 +419,14 @@ async function fetchPaginated(
     const admitted = rawEntries.filter(admitEntry).map((entry) => parseNVDEntry(entry, options));
 
     if (rawEntries.length === 0) {
-      metrics.increment('nvd_cache_misses_total', 1, { term });
+      // No `term` label: the metrics registry keys counters by label set and is only
+      // cleared by an explicit clearSession(), so labelling by the raw search term made
+      // every distinct security query add a permanent entry for the life of a pi host
+      // session — unbounded growth driven straight by user input.
+      metrics.increment('nvd_cache_misses_total', 1);
       break;
     }
-    metrics.increment('nvd_cache_hits_total', 1, { term });
+    metrics.increment('nvd_cache_hits_total', 1);
 
     allVulnerabilities.push(...admitted);
 

package/src/security/osv-client.ts

@@ -14,6 +14,7 @@ import { logger } from '../logger.ts';
 import { OSV_TIMEOUT_MS, DEFAULT_MAX_RETRIES, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS } from '../constants.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError } from '../utils/http-body.ts';
 import {
   isOsvVulnerability,
   isOsvQueryResponse,
@@ -137,10 +138,17 @@ export async function searchOSV(
 
       let data: unknown;
       try {
-        data = await response.json();
-      } catch {
+        data = await readJsonCapped(response);
+      } catch (err) {
+        // An over-cap body is a size failure, not a syntax one. Rethrowing it
+        // unwrapped keeps the diagnosis honest instead of reporting a 40MB reply
+        // as malformed JSON.
+        if (err instanceof BodyTooLargeError) {
+          metrics.increment('osv_search_errors_total', 1, { error_type: 'body_too_large' });
+          throw err;
+        }
         metrics.increment('osv_search_errors_total', 1, { error_type: 'malformed_json' });
-        throw new Error(`OSV returned a malformed JSON response for "${term}".`);
+        throw new Error(`OSV returned a malformed JSON response for "${term}".`, { cause: err });
       }
 
       let items: OsvVulnerability[];
@@ -154,7 +162,9 @@ export async function searchOSV(
       }
 
       const endpoint = isIdLookup ? 'vulns_by_id' : 'query';
-      metrics.increment(items.length > 0 ? 'osv_cache_hits_total' : 'osv_cache_misses_total', 1, { term, endpoint });
+      // `endpoint` only — see the nvd-client note: a raw-term label grows the counter
+      // registry without bound across a session.
+      metrics.increment(items.length > 0 ? 'osv_cache_hits_total' : 'osv_cache_misses_total', 1, { endpoint });
 
       const vulns: Vulnerability[] = [];
       for (const item of items) {

package/src/skill-install/skill-installer.ts

@@ -18,6 +18,7 @@
  * only written on explicit opt-in (callers must pass them deliberately).
  */
 
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -57,6 +58,24 @@ export const HARNESSES: readonly HarnessDef[] = [
 const SKILL_NAME = 'pi-research';
 const PACKAGE_NAME = '@lincoln504/pi-research';
 
+/**
+ * This package's version, used to stamp manifest entries so a stale COPY can be
+ * detected and refreshed. Read from the SKILL.md we are about to install rather
+ * than from package.json: that file is the copied artifact, its metadata line is
+ * kept in sync by the `version` npm script, and it is present in every layout
+ * (repo, published tarball, installed copy). Returns null if unreadable, which
+ * simply means "cannot tell" — the entry is then always treated as stale, which
+ * refreshes rather than skips.
+ */
+function readSkillVersion(sourceDir: string): string | null {
+  try {
+    const md = fs.readFileSync(path.join(sourceDir, 'SKILL.md'), 'utf-8');
+    return /"version"\s*:\s*"([^"]+)"/.exec(md)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The coding agents the in-app installer (the /research-config TUI) targets:
  * Claude, Codex, and OpenClaw. Each loads skills from a home-directory
@@ -81,6 +100,22 @@ export interface ManifestEntry {
   /** Absolute path of the skill source this was linked/copied from. */
   source: string;
   createdAt: string;
+  /**
+   * Package version that produced this entry.
+   *
+   * Only load-bearing for `copy` entries: a symlink re-reads the package on every
+   * use and so is always current, but a COPY is a point-in-time snapshot that
+   * nothing ever refreshed — reconcile skipped non-symlinks entirely, and the
+   * entry recorded no version, so drift was undetectable by construction. Copies
+   * are not rare: they happen on Windows without symlink privilege, cross-device,
+   * with `--copy`, and via the documented OpenClaw install route. Those users kept
+   * the SKILL.md their engine shipped with *forever* — including its exit-code
+   * contract — while the engine underneath them changed.
+   *
+   * Optional so manifests written before this field are still valid; an entry with
+   * no version simply reads as "not current" and is refreshed once.
+   */
+  version?: string;
 }
 
 interface Manifest {
@@ -293,6 +328,7 @@ export function installSkill(toolIds: string[], opts: InstallOptions = {}): Inst
   const manifest = readManifest(opts);
   const results: InstallResult[] = [];
   const now = new Date().toISOString();
+  const skillVersion = readSkillVersion(source);
 
   for (const id of toolIds) {
     const def = HARNESSES.find(h => h.id === id);
@@ -315,16 +351,22 @@ export function installSkill(toolIds: string[], opts: InstallOptions = {}): Inst
         if (lst.isSymbolicLink()) {
           const dest = path.resolve(path.dirname(absSkillPath), fs.readlinkSync(absSkillPath));
           if (dest !== path.resolve(source)) {
+            // dryRun means "plan only, touch nothing" — the re-point is a real
+            // unlink+symlink and must honour it like the fresh-install path does.
+            if (opts.dryRun) {
+              results.push({ tool: id, path: absSkillPath, type: 'symlink', status: 'planned', message: 'would re-point stale symlink to current source' });
+              continue;
+            }
             fs.unlinkSync(absSkillPath);
             fs.symlinkSync(source, absSkillPath, process.platform === 'win32' ? 'junction' : 'dir');
-            upsertEntry(manifest, { tool: id, path: absSkillPath, type: 'symlink', source, createdAt: now });
+            upsertEntry(manifest, { tool: id, path: absSkillPath, type: 'symlink', source, createdAt: now, ...(skillVersion ? { version: skillVersion } : {}) });
             results.push({ tool: id, path: absSkillPath, type: 'symlink', status: 'installed', message: 're-pointed stale symlink to current source' });
             continue;
           }
         }
       } catch { /* fall through to already-installed below */ }
       results.push({ tool: id, path: absSkillPath, type, status: 'already-installed' });
-      upsertEntry(manifest, { tool: id, path: absSkillPath, type: isSymlinkPresent(absSkillPath) ? 'symlink' : 'copy', source, createdAt: now });
+      upsertEntry(manifest, { tool: id, path: absSkillPath, type: isSymlinkPresent(absSkillPath) ? 'symlink' : 'copy', source, createdAt: now, ...(skillVersion ? { version: skillVersion } : {}) });
       continue;
     }
     if (fs.existsSync(absSkillPath) || isSymlinkPresent(absSkillPath)) {
@@ -344,14 +386,14 @@ export function installSkill(toolIds: string[], opts: InstallOptions = {}): Inst
         } catch (err: any) {
           // Windows without privilege, or cross-device: fall back to copy.
           copyDir(source, absSkillPath);
-          upsertEntry(manifest, { tool: id, path: absSkillPath, type: 'copy', source, createdAt: now });
+          upsertEntry(manifest, { tool: id, path: absSkillPath, type: 'copy', source, createdAt: now, ...(skillVersion ? { version: skillVersion } : {}) });
           results.push({ tool: id, path: absSkillPath, type: 'copy', status: 'installed', message: `symlink unavailable (${err?.code ?? err?.message}); copied instead` });
           continue;
         }
       } else {
         copyDir(source, absSkillPath);
       }
-      upsertEntry(manifest, { tool: id, path: absSkillPath, type, source, createdAt: now });
+      upsertEntry(manifest, { tool: id, path: absSkillPath, type, source, createdAt: now, ...(skillVersion ? { version: skillVersion } : {}) });
       results.push({ tool: id, path: absSkillPath, type, status: 'installed' });
     } catch (err: any) {
       results.push({ tool: id, path: absSkillPath, type, status: 'error', message: err?.message ?? String(err) });
@@ -412,7 +454,7 @@ export function uninstallSkill(toolIds?: string[], opts: InstallOptions = {}): U
     }
     try {
       if (isSymlinkPresent(skillPath)) fs.unlinkSync(skillPath);
-      else fs.rmSync(skillPath, { recursive: true, force: true });
+      else fs.rmSync(skillPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
       results.push({ tool, path: skillPath, status: 'removed' });
     } catch (err: any) {
       results.push({ tool, path: skillPath, status: 'error', message: err?.message ?? String(err) });
@@ -441,6 +483,12 @@ export interface ReconcileResult {
   pruned: string[];
   /** Stale/dangling owned symlinks re-pointed to the current package source. */
   repointed: string[];
+  /**
+   * Owned COPIES refreshed because the package version moved on. A symlink tracks
+   * the package automatically; a copy does not, so without this an upgrade left
+   * copy-installed users on the previous SKILL.md indefinitely.
+   */
+  refreshed: string[];
 }
 
 /**
@@ -460,17 +508,77 @@ export interface ReconcileResult {
  * Foreign (non-owned) paths and self-contained copies are never touched.
  */
 export function reconcileSkillInstalls(opts: InstallOptions = {}): ReconcileResult {
-  const result: ReconcileResult = { pruned: [], repointed: [] };
+  const result: ReconcileResult = { pruned: [], repointed: [], refreshed: [] };
   const manifest = readManifest(opts);
   if (manifest.entries.length === 0) return result;
 
   let source: string | null;
   try { source = resolveSkillSourceDir(opts.skillSourceDir); } catch { source = null; }
 
+  const currentVersion = source !== null ? readSkillVersion(source) : null;
+
   const keep: ManifestEntry[] = [];
   for (const e of manifest.entries) {
-    // Copies are self-contained (no target to dangle); leave them as-is.
-    if (e.type !== 'symlink') { keep.push(e); continue; }
+    // A COPY has no target to dangle, but it is a point-in-time snapshot: unlike a
+    // symlink it does not track the package, so an engine upgrade leaves it serving
+    // the OLD SKILL.md — including its exit-code contract — indefinitely. Refresh it
+    // when the stamped version differs from what we now ship. An entry written
+    // before versions were stamped has none, so it reads as stale and is refreshed
+    // once. Ownership is re-checked first: a foreign directory at this path is
+    // never overwritten.
+    if (e.type !== 'symlink') {
+      const stale = currentVersion !== null && e.version !== currentVersion;
+      if (stale && source !== null && fs.existsSync(e.path) && isOwnedCopy(e.path)) {
+        // Build-then-swap, never rm-then-copy. The old shape (rmSync, then
+        // copyDir) destroyed the install permanently when the copy failed
+        // (ENOSPC, a locked file): the retry guard requires the path to exist,
+        // so a vanished install was never retried either. The staging names are
+        // dot-prefixed so a crash mid-swap cannot leave a directory a skill
+        // scanner would pick up as a duplicate skill.
+        const dir = path.dirname(e.path);
+        const base = path.basename(e.path);
+        // Sweep leftovers from a previous crashed swap before starting a new one.
+        try {
+          for (const name of fs.readdirSync(dir)) {
+            if (name.startsWith(`.${base}.new-`) || name.startsWith(`.${base}.old-`)) {
+              fs.rmSync(path.join(dir, name), { recursive: true, force: true });
+            }
+          }
+        } catch { /* hygiene only */ }
+        const suffix = crypto.randomBytes(4).toString('hex');
+        const fresh = path.join(dir, `.${base}.new-${suffix}`);
+        const retired = path.join(dir, `.${base}.old-${suffix}`);
+        try {
+          copyDir(source, fresh);
+        } catch {
+          try { fs.rmSync(fresh, { recursive: true, force: true }); } catch { /* best effort */ }
+          keep.push(e); // source unreadable / disk full — install intact, retry next startup
+          continue;
+        }
+        try {
+          fs.renameSync(e.path, retired);
+        } catch {
+          try { fs.rmSync(fresh, { recursive: true, force: true }); } catch { /* best effort */ }
+          keep.push(e); // could not move the old copy aside (locked on Windows) — intact
+          continue;
+        }
+        try {
+          fs.renameSync(fresh, e.path);
+        } catch {
+          // Put the old copy back — an old skill is strictly better than none.
+          try { fs.renameSync(retired, e.path); } catch { /* skills dir itself broken */ }
+          try { fs.rmSync(fresh, { recursive: true, force: true }); } catch { /* best effort */ }
+          keep.push(e);
+          continue;
+        }
+        try { fs.rmSync(retired, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 }); } catch { /* leaked dot-dir; swept next reconcile */ }
+        keep.push({ ...e, source, version: currentVersion });
+        result.refreshed.push(e.path);
+      } else {
+        keep.push(e);
+      }
+      continue;
+    }
 
     // Link the user deleted by hand — nothing on disk; drop the stale entry.
     if (!isSymlinkPresent(e.path)) { result.pruned.push(e.path); continue; }
@@ -514,6 +622,24 @@ export function reconcileSkillInstalls(opts: InstallOptions = {}): ReconcileResu
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Recursive copy at the JS level — deliberately NOT fs.cpSync. cpSync's native
+ * implementation (std::filesystem) ABORTS the whole process on an unreadable
+ * directory instead of throwing a catchable error (observed on Node 25:
+ * "terminate called after throwing an instance of
+ * 'std::filesystem::__cxx11::filesystem_error'"). This runs inside
+ * reconcileSkillInstalls at every startup, where a copy failure must be caught
+ * and rolled back — never take the host down. statSync/copyFileSync follow
+ * symlinks, matching the dereference behaviour cpSync was given.
+ */
 function copyDir(src: string, dest: string): void {
-  fs.cpSync(src, dest, { recursive: true, dereference: true });
+  const st = fs.statSync(src);
+  if (st.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const name of fs.readdirSync(src)) {
+      copyDir(path.join(src, name), path.join(dest, name));
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+  }
 }

package/src/stackexchange/rest-client.ts

@@ -7,6 +7,7 @@ import type { StackExchangeWrapper } from './types.ts';
 import { logger } from '../logger.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError } from '../utils/http-body.ts';
 
 const API_BASE = 'https://api.stackexchange.com/2.3';
 
@@ -99,7 +100,7 @@ export class StackExchangeClient {
 
         // NB: the timeout is cleared in `finally`, not here. Clearing it now —
         // when only the headers have arrived — would leave the body read
-        // (response.json() below) with no timeout, so a stalled body could hang
+        // (readJsonCapped below) with no timeout, so a stalled body could hang
         // for the whole process lifetime.
 
         // The SE API returns a structured JSON wrapper (with error_id) even for
@@ -109,8 +110,11 @@ export class StackExchangeClient {
         // "Unexpected token <" SyntaxError that hides the real cause.
         let data: StackExchangeWrapper<T>;
         try {
-          data = await response.json() as StackExchangeWrapper<T>;
+          data = await readJsonCapped<StackExchangeWrapper<T>>(response);
         } catch (parseErr) {
+          // An over-cap body is a size failure, not a malformed-JSON one: rethrow
+          // it unwrapped so it can't be relabelled as an HTTP-status error below.
+          if (parseErr instanceof BodyTooLargeError) throw parseErr;
           if (!response.ok) throw new Error(`HTTP ${response.status} from Stack Exchange API`, { cause: parseErr });
           throw parseErr;
         }

package/src/tools/research-knowledge-search.ts

@@ -962,6 +962,21 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
         return buildSteeringResult(result, urls);
       } catch (error) {
         const durationMs = Date.now() - startTime;
+        const msg = error instanceof Error ? error.message : String(error);
+
+        // A CANCELLED search is not an empty store. Reporting the miss string here
+        // told the calling agent, definitively, that the knowledge store has
+        // nothing on this topic — so it would go straight to full live research,
+        // the very work the user just interrupted. Propagate the abort instead;
+        // the run is ending either way. (Same misclassification as the search
+        // layer's "browser workers may be unavailable" on Ctrl-C.)
+        if (signal?.aborted || (error instanceof Error && error.name === 'AbortError') || /^(aborted|research (aborted|cancelled))$/i.test(msg)) {
+          metrics.observe('research_knowledge_search_duration_ms', durationMs, { status: 'cancelled' });
+          metrics.increment('research_knowledge_search_total', 1, { status: 'cancelled' });
+          logger.debug('[research-knowledge-search] Cancelled mid-search — propagating rather than reporting an empty store.');
+          throw error;
+        }
+
         metrics.observe('research_knowledge_search_duration_ms', durationMs, { status: 'error' });
         metrics.increment('research_knowledge_search_total', 1, { status: 'error' });
 

package/src/tools/search.ts

@@ -106,7 +106,12 @@ export function createSearchTool(options: {
         results.forEach((r, i) => {
           markdown += `## Query ${i + 1}: ${r.query}\n`;
           if (r.results.length === 0) {
-            markdown += `*No results found.*\n\n`;
+            // Render the attributed failure, not a bare "no results": a timeout or
+            // dead worker says nothing about the query, and presenting it as an
+            // empty result sent the model off rewriting perfectly good queries —
+            // the misdirection QueryFailure exists to prevent. This is the only
+            // surface the researcher agent actually reads.
+            markdown += r.error ? `*${r.error.message}*\n\n` : `*No results found.*\n\n`;
           } else {
             r.results.forEach((item, j) => {
               markdown += `[${j + 1}] **${item.title}**\n${item.url}\n${item.content}\n\n`;

package/src/utils/atomic-replace.ts

@@ -0,0 +1,101 @@
+/**
+ * Atomic file replacement, with the Windows caveat handled honestly.
+ *
+ * The temp-file + fsync + rename dance exists so a reader never observes a partial
+ * file and a crash never leaves one: rename is atomic, so the destination is either
+ * entirely the old content or entirely the new.
+ *
+ * On Windows that guarantee is easy to lose. The long-standing comment at these call
+ * sites — "fs.rename fails on Windows if target exists (NTFS)" — is not true: Node
+ * calls `MoveFileExW` with `MOVEFILE_REPLACE_EXISTING`, so replacing an existing file
+ * is fine. What actually fails is a rename whose TARGET is held open by another
+ * process without delete sharing (an AV scanner mid-scan, a backup agent), which
+ * surfaces as EPERM/EBUSY/EACCES.
+ *
+ * The old remedy — fall straight to `copyFile` — traded a transient, retryable error
+ * for a permanent hazard: `copyFile` truncates the destination and rewrites it in
+ * place, so a concurrent reader or a crash mid-copy sees a torn or zero-length file.
+ * For `state.json` (leader election, server auth secrets) and `config.env` (API keys)
+ * that is a much worse outcome than the error it was avoiding.
+ *
+ * So: retry the rename first. An AV lock clears in tens of milliseconds, and a retried
+ * rename stays atomic. Only a lock that outlives every retry falls back to copying,
+ * which is reported to the caller so it can be logged as the degraded path it is.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+
+/** Transient Windows sharing/locking failures — worth retrying, unlike ENOENT/ENOSPC. */
+const RETRYABLE_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+
+const MAX_RENAME_ATTEMPTS = 5;
+const RENAME_RETRY_DELAY_MS = 25;
+
+export type ReplaceOutcome = 'renamed' | 'copied';
+
+function isRetryable(err: unknown): boolean {
+  const code = (err as NodeJS.ErrnoException | undefined)?.code;
+  return code !== undefined && RETRYABLE_CODES.has(code);
+}
+
+/**
+ * Replace `destPath` with `tmpPath` atomically where the platform allows it.
+ *
+ * Returns `'renamed'` for the atomic path and `'copied'` for the degraded Windows
+ * fallback. Rethrows on every non-Windows failure, and on Windows failures that are
+ * not lock-related.
+ */
+export async function replaceFile(tmpPath: string, destPath: string): Promise<ReplaceOutcome> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_RENAME_ATTEMPTS; attempt++) {
+    try {
+      await fs.rename(tmpPath, destPath);
+      return 'renamed';
+    } catch (err) {
+      lastError = err;
+      // Only a Windows sharing conflict is worth another try; anything else (and any
+      // failure on a POSIX platform, where rename-over-existing always works) is real.
+      if (process.platform !== 'win32' || !isRetryable(err)) throw err;
+      if (attempt < MAX_RENAME_ATTEMPTS - 1) {
+        await new Promise((r) => setTimeout(r, RENAME_RETRY_DELAY_MS * (attempt + 1)));
+      }
+    }
+  }
+
+  // Every retry lost to the same lock. Copying is not atomic — a reader can catch the
+  // destination mid-write — but it is the only remaining way to persist the data.
+  try {
+    await fs.copyFile(tmpPath, destPath);
+    return 'copied';
+  } catch {
+    throw lastError;
+  }
+}
+
+/** Synchronous {@link replaceFile}, for the config writer, which is sync throughout. */
+export function replaceFileSync(tmpPath: string, destPath: string): ReplaceOutcome {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_RENAME_ATTEMPTS; attempt++) {
+    try {
+      fsSync.renameSync(tmpPath, destPath);
+      return 'renamed';
+    } catch (err) {
+      lastError = err;
+      if (process.platform !== 'win32' || !isRetryable(err)) throw err;
+      if (attempt < MAX_RENAME_ATTEMPTS - 1) {
+        // Sync busy-wait: this path is rare, bounded (~250ms worst case) and the
+        // caller is already blocking on a synchronous write.
+        const until = Date.now() + RENAME_RETRY_DELAY_MS * (attempt + 1);
+        while (Date.now() < until) { /* spin */ }
+      }
+    }
+  }
+
+  try {
+    fsSync.copyFileSync(tmpPath, destPath);
+    return 'copied';
+  } catch {
+    throw lastError;
+  }
+}

package/src/utils/citation-utils.ts

@@ -16,7 +16,9 @@ export interface GlobalCitation extends Citation {
  * @param reports - Map of researcher ID to report content
  * @returns Object containing normalized reports and the global citation list
  */
-export function normalizeCitations(reports: Map<string, string>): {
+// ReadonlyMap: this only reads `reports` (it returns a NEW normalizedReports map),
+// and callers now pass a read-only view to avoid create-on-read side effects.
+export function normalizeCitations(reports: ReadonlyMap<string, string>): {
   normalizedReports: Map<string, string>;
   globalCitations: GlobalCitation[];
 } {