mover-os 4.7.7 → 4.7.9

package/src/dashboard/lib/roast-wall-parser.js

@@ -0,0 +1,200 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { dailiesDir, autoLearningsPath } = require("./paths");
+
+// roast-wall-parser.js — Codex's #1 viral pick. Surfaces dated AI verdicts
+// (the brutal honest one-liners /analyse-day produces). Sources:
+//   1. Daily Notes "## Session Log" entries that contain verdict markers
+//   2. Auto_Learnings.md CORRECTION + BELIEF SHIFT entries
+//   3. Roast quotes embedded in Daily Note ## Session Log sections
+//
+// Returns ranked Roast[] with severity, date, quote, pattern attribution.
+
+const SEVERITY_KEYWORDS = {
+  high: ["override", "broke", "violated", "again", "third time", "structural", "avoidance", "phantom"],
+  med:  ["drift", "slipping", "deferred", "missed", "skipped", "stale"],
+};
+
+function compute({ vault, autoLearnings = null, daysLookback = 60 } = {}) {
+  if (!vault) return { available: false, count: 0, roasts: [], stats: { high: 0, med: 0, low: 0 }, sourcesChecked: 0 };
+  const roasts = [];
+
+  // False-zero discipline (T261): track how many real sources we were able to
+  // open. A wall we actually scanned but found empty is a true count:0 and
+  // stays available:true. But if NOTHING was scannable — no Auto_Learnings
+  // patterns AND no Dailies dir on disk — then count:0 is an artifact of
+  // having nothing to read, not a clean record. That flips available:false so
+  // the consumer shows "calibrating"/empty rather than "0 roasts = you're good".
+  let sourcesChecked = 0;
+
+  // Collect from Auto_Learnings — pre-categorized.
+  // False-zero fix (T261, Codex #1): the build.js fallback for an UNAVAILABLE
+  // Auto_Learnings still carries `activePatternsConf3Plus: []`, so a truthiness
+  // check on the array alone counted a non-source as "scanned" and forced
+  // available:true with count:0. Only count this source when it was genuinely
+  // readable (available !== false) AND actually had patterns to read. A real
+  // available AL with zero patterns contributes no roasts and does NOT, on its
+  // own, make the wall "scanned" — the Dailies walk below governs that case
+  // (a present Dailies dir → available:true count:0; nothing on disk →
+  // sourcesChecked stays 0 → available:false).
+  if (
+    autoLearnings &&
+    autoLearnings.available !== false &&
+    Array.isArray(autoLearnings.activePatternsConf3Plus) &&
+    autoLearnings.activePatternsConf3Plus.length > 0
+  ) {
+    sourcesChecked++;
+    autoLearnings.activePatternsConf3Plus.forEach((p) => {
+      if (!p.description) return;
+      roasts.push({
+        source: "Auto_Learnings.md",
+        date: p.lastSeen || p.firstSeen || "live",
+        severity: p.confidence >= 4 ? "high" : "med",
+        quote: p.description.slice(0, 280),
+        pattern: p.id || "—",
+        confidence: p.confidence || 0,
+      });
+    });
+  }
+
+  // Walk recent Daily Notes for verdict-marker lines.
+  // Audit pass 2 (find-bugs #14): existsSync check before readdirSync so
+  // fresh-install vaults (no Dailies dir yet) don't silently swallow the
+  // ENOENT inside the catch — distinguishes "no dailies dir" from "no
+  // verdict markers found in dailies."
+  let dailiesAvailable = true;
+  try {
+    const dDir = dailiesDir(vault);
+    if (!fs.existsSync(dDir)) { dailiesAvailable = false; throw Object.assign(new Error("dailies dir missing"), { code: "ENOENT" }); }
+    // False-zero fix (T261, Codex #4): only count the Dailies source as
+    // "checked" AFTER we successfully READ the directory. existsSync passing
+    // doesn't guarantee readability (permissions / race) — incrementing before
+    // readdirSync could leave sourcesChecked >= 1 on a dir we never actually
+    // scanned, fabricating available:true count:0 from an unscanned source.
+    const months = fs.readdirSync(dDir).filter((d) => /^\d{4}-\d{2}$/.test(d)).sort().reverse();
+    sourcesChecked++;
+    const cutoff = Date.now() - daysLookback * 24 * 3600 * 1000;
+    let scanned = 0;
+    for (const mDir of months) {
+      if (scanned >= 30) break;
+      const monthPath = path.join(dDir, mDir);
+      try {
+        const files = fs.readdirSync(monthPath).filter((f) => /^Daily - \d{4}-\d{2}-\d{2}\.md$/.test(f)).sort().reverse();
+        for (const f of files) {
+          if (scanned >= 30) break;
+          const m = f.match(/(\d{4})-(\d{2})-(\d{2})/);
+          if (!m) continue;
+          const t = Date.parse(`${m[1]}-${m[2]}-${m[3]}`);
+          if (!Number.isFinite(t) || t < cutoff) continue;
+          scanned++;
+          const text = safeRead(path.join(monthPath, f));
+          extractRoastsFromDaily(text, m[0], roasts);
+        }
+      } catch (_) { /* skip month */ }
+    }
+  } catch (_) { /* daily walk failed */ }
+
+  // Rank: severity → date desc → confidence
+  const sev = { high: 0, med: 1, low: 2 };
+  roasts.sort((a, b) => {
+    const s = (sev[a.severity] ?? 3) - (sev[b.severity] ?? 3);
+    if (s !== 0) return s;
+    if (a.date && b.date && a.date !== "live" && b.date !== "live") {
+      return String(b.date).localeCompare(String(a.date));
+    }
+    return (b.confidence || 0) - (a.confidence || 0);
+  });
+
+  // Dedupe by first 80 chars of quote
+  const seen = new Set();
+  const deduped = roasts.filter((r) => {
+    const key = (r.quote || "").slice(0, 80).toLowerCase().replace(/\s+/g, " ");
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  // If no source was openable, count:0 is meaningless absence, not a clean
+  // wall — flag unavailable so the consumer renders an empty/calibrating
+  // state instead of "0 roasts" read as "all clear". A scanned-but-empty
+  // wall (sourcesChecked >= 1) keeps available:true with a real count:0.
+  if (sourcesChecked === 0) {
+    return {
+      available: false,
+      count: 0,
+      roasts: [],
+      stats: { high: 0, med: 0, low: 0 },
+      sourcesChecked: 0,
+    };
+  }
+
+  return {
+    available: true,
+    count: deduped.length,
+    roasts: deduped.slice(0, 24),
+    stats: {
+      high: deduped.filter((r) => r.severity === "high").length,
+      med: deduped.filter((r) => r.severity === "med").length,
+      low: deduped.filter((r) => r.severity === "low").length,
+    },
+    sourcesChecked,
+  };
+}
+
+function extractRoastsFromDaily(text, dateKey, accumulator) {
+  if (!text) return;
+  // Find roast markers in session logs — look for italicized quotes,
+  // [FLAG], [VERDICT], or block-quote lines with sharp prose.
+  const lines = text.split(/\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Block quote with sharp prose >40 chars
+    const blockMatch = line.match(/^>\s+["“]([^"”]{40,300})["”]/);
+    if (blockMatch) {
+      accumulator.push({
+        source: `Daily - ${dateKey}.md`,
+        date: dateKey,
+        severity: scoreSeverity(blockMatch[1]),
+        quote: blockMatch[1].trim(),
+        pattern: "—",
+        confidence: 3,
+      });
+      continue;
+    }
+    // FLAG: / VERDICT: / OVERRIDE: lines.
+    //
+    // T242 bug hunt fix (B#15): anchor to start of line. Previous regex
+    // had no `^` so prose like "this was not an OVERRIDE: success"
+    // matched and got scored with inverted polarity. Reject lines whose
+    // preceding context contains a negation cue.
+    const negationCue = /\b(?:not|no|wasn'?t|isn'?t|don'?t|never)\s+[^.]{0,40}$/i;
+    const headStart = line.match(/^(.{0,40}?)\s*(?:FLAG|VERDICT|OVERRIDE|ROAST):/i);
+    if (headStart && negationCue.test(headStart[1])) continue;
+    const flag = line.match(/^\s*[-*>]*\s*(?:FLAG|VERDICT|OVERRIDE|ROAST):\s+(.{40,300})/i);
+    if (flag) {
+      accumulator.push({
+        source: `Daily - ${dateKey}.md`,
+        date: dateKey,
+        severity: scoreSeverity(flag[1]),
+        quote: flag[1].trim(),
+        pattern: flag[0].split(":")[0].toUpperCase(),
+        confidence: 4,
+      });
+    }
+  }
+}
+
+function scoreSeverity(text) {
+  const t = String(text).toLowerCase();
+  if (SEVERITY_KEYWORDS.high.some((k) => t.includes(k))) return "high";
+  if (SEVERITY_KEYWORDS.med.some((k) => t.includes(k))) return "med";
+  return "low";
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, "utf8"); } catch (_) { return ""; }
+}
+
+module.exports = { compute };

package/src/dashboard/lib/run-registry.js

@@ -0,0 +1,286 @@
+"use strict";
+
+/**
+ * run-registry.js — server-held registry for one-shot agent runs (the Run tab).
+ *
+ * WHY: the original Run path (server.js runAgentStream) piped the child's
+ * stdout STRAIGHT to the HTTP response with no server-side buffer and no
+ * handle on the child. So navigating away from the Run tab — or a page
+ * refresh — lost the run and its output, and there was no way to re-attach.
+ * The Run tab was ephemeral; the Chat tab (AgentSessionManager) was not.
+ *
+ * This registry makes Run persistent the same way Chat is: the child and its
+ * output live on the SERVER, decoupled from the request that started them. A
+ * client can disconnect and reconnect; the run keeps going and its output is
+ * retained. Unlike the Chat path (Claude-only stream-json), this wraps the
+ * existing multi-agent one-shot command (agentCommand), so Run stays
+ * claude/codex/gemini — there is no Claude-only regression.
+ *
+ * Persistence scope == Chat's: in-memory, per running daemon. A daemon restart
+ * clears runs (AgentSessionManager behaves identically). Bounds keep memory
+ * sane for a long-lived daemon: a per-run output cap (drop the head, keep the
+ * meaningful tail incl. the exit line) and a retained-run cap + age eviction.
+ *
+ * Subscribe semantics mirror AgentSessionManager.subscribe: a new subscriber
+ * gets the full buffer replayed first (so a reattaching client sees history),
+ * then live chunks. The replay snapshot + subscriber-add happen in one
+ * synchronous step, so a stdout 'data' event (only dispatched at an I/O yield)
+ * can never interleave and drop or duplicate a chunk.
+ */
+
+const { spawn } = require("child_process");
+const { writeMarker, removeMarker, groupAlive, killGroup, reapOrphans } = require("./pid-markers");
+
+const DEFAULTS = {
+  maxRuns: 40,                       // retain at most N runs (live + finished)
+  maxConcurrent: 4,                  // live child processes at once; excess requests are refused
+  maxBuffer: 1024 * 1024,            // 1 MB per-run output cap (head dropped, tail kept)
+  finishedTtlMs: 6 * 60 * 60 * 1000, // evict finished runs 6h after they end
+  idleSweepMs: 5 * 60 * 1000,        // sweep cadence
+  timeoutMs: 10 * 60 * 1000,         // hard stop a run after 10 min (matches legacy)
+};
+
+class RunRegistry {
+  constructor(opts = {}) {
+    this.opt = { ...DEFAULTS, ...opts };
+    this.runs = new Map(); // id -> run record
+    this._seq = 0;
+    // R5-A: reap children escaped by a crashed dashboard (same MF2 guarantee
+    // AgentSessionManager has; the marker dir is shared so either manager's
+    // startup cleans up both kinds of orphan).
+    reapOrphans();
+    this._sweep = setInterval(() => this._evict(), this.opt.idleSweepMs);
+    if (this._sweep.unref) this._sweep.unref();
+  }
+
+  /** Live (running/stopping) child count — the concurrency the cap guards. */
+  liveCount() {
+    let n = 0;
+    for (const r of this.runs.values()) if (r.status === "running" || r.status === "stopping") n++;
+    return n;
+  }
+
+  /**
+   * Spawn a tracked run. The CALLER builds the command (agentCommand) and the
+   * final prompt (buildAgentPrompt); this owns the process + buffer lifecycle.
+   * spec: { agent, label, cmd, args, stdin, finalPrompt, cwd, env, preamble }
+   * Returns the run record (its `.id` is the handle for subscribe/get/stop).
+   */
+  start(spec) {
+    // Concurrency cap (R5-A): every run is a real long-lived CLI child with
+    // full tool access; a buggy retry loop must not fork-bomb the machine.
+    if (this.liveCount() >= this.opt.maxConcurrent) {
+      const err = new Error(`${this.opt.maxConcurrent} agents are already running. Stop one or let it finish first.`);
+      err.code = "RUN_LIMIT";
+      throw err;
+    }
+    const id = `run_${process.pid}_${++this._seq}`;
+    const run = {
+      id,
+      agent: spec.agent || "claude-code",
+      label: (spec.label || spec.agent || "task").slice(0, 200),
+      status: "running",
+      output: spec.preamble ? String(spec.preamble) : "",
+      started: Date.now(),
+      ended: null,
+      exit: null,
+      truncated: false,
+      child: null,
+      subscribers: new Set(),
+    };
+    this.runs.set(id, run);
+    this._trimCount();
+
+    let child;
+    try {
+      // detached: own process group, so Stop/shutdown can signal the whole
+      // tree (a run's tool calls spawn grandchildren the bare child.kill()
+      // never reached), and the pid marker lets a post-crash startup reap it.
+      child = spawn(spec.cmd, spec.args, { cwd: spec.cwd, env: spec.env, stdio: ["pipe", "pipe", "pipe"], detached: true });
+    } catch (e) {
+      this._append(run, `\n[mover-studio] failed to start ${run.agent}: ${e && e.message}\n`);
+      this._finish(run, "failed", null);
+      return run;
+    }
+    run.child = child;
+    if (child.pid) writeMarker(child.pid, { pid: child.pid, ownerPid: process.pid, at: Date.now(), kind: "run" });
+
+    const timeout = setTimeout(() => {
+      // Mark stopping BEFORE the kill so the close handler reports "stopped",
+      // not a false "done" (terra run-path F2).
+      run.status = "stopping";
+      this._append(run, "\n[mover-studio] timeout after 10 minutes; stopping agent.\n", true);
+      killGroup(child.pid, "SIGTERM");
+      const esc = setTimeout(() => { if (groupAlive(child.pid)) killGroup(child.pid, "SIGKILL"); }, 2500);
+      if (esc.unref) esc.unref();
+    }, this.opt.timeoutMs);
+    if (timeout.unref) timeout.unref();
+
+    // Guard stdin against an async EPIPE if the child dies early (mirrors the
+    // legacy one-shot path + the AgentSession stdin guard).
+    if (child.stdin) child.stdin.on("error", () => {});
+    try {
+      if (spec.stdin) child.stdin.end(spec.finalPrompt);
+      else child.stdin.end();
+    } catch (_) {}
+
+    child.stdout.on("data", (c) => this._onChunk(run, c));
+    child.stderr.on("data", (c) => this._onChunk(run, c));
+    child.on("error", (err) => {
+      clearTimeout(timeout);
+      this._append(run, `\n[mover-studio] failed to start ${run.agent}: ${err && err.message}\n`, true);
+      this._finish(run, "failed", null);
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timeout);
+      this._append(run, `\n[mover-studio] agent exited with code ${code}${signal ? ` (signal ${signal})` : ""}\n`, true);
+      // A run we SIGTERM'd (stop OR timeout) keeps "stopping" -> "stopped". A
+      // clean exit (code 0) is "done"; ANY other termination — a non-zero code OR
+      // code==null from a signal we did not send — is "exited", never a false
+      // "done" (terra run-path F2: a signal-killed run was reported as success).
+      const status = run.status === "stopping" ? "stopped" : code === 0 ? "done" : "exited";
+      this._finish(run, status, code);
+    });
+
+    return run;
+  }
+
+  /** Subscribe to a run: replay the full buffer, then stream live chunks.
+   *  cb receives {type:"replay"|"chunk"|"end", text?, status?, exit?}.
+   *  Returns an unsubscribe fn. */
+  subscribe(id, cb) {
+    const run = this.runs.get(id);
+    if (!run) { cb({ type: "end", status: "missing", exit: null }); return () => {}; }
+    // Snapshot + register atomically (no I/O between) so no chunk is lost.
+    cb({ type: "replay", text: run.output, status: run.status, exit: run.exit });
+    if (run.status === "running" || run.status === "stopping") {
+      // Cap live subscribers per run so a flood of stream connections can't pile
+      // up callbacks/sockets (terra run-path F3). Over the cap, the client still
+      // got the full replay above; end it rather than live-stream.
+      if (run.subscribers.size >= 64) { cb({ type: "end", status: run.status, exit: run.exit }); return () => {}; }
+      run.subscribers.add(cb);
+      return () => run.subscribers.delete(cb);
+    }
+    cb({ type: "end", status: run.status, exit: run.exit });
+    return () => {};
+  }
+
+  /** Really stop a run (SIGTERM the child's whole process group — a run's
+   *  tool calls spawn grandchildren). Distinct from a client merely
+   *  detaching its stream ("stop watching"). */
+  stop(id) {
+    const run = this.runs.get(id);
+    if (!run || !run.child || (run.status !== "running")) return false;
+    run.status = "stopping";
+    const pid = run.child.pid;
+    killGroup(pid, "SIGTERM");
+    // Escalate if the group ignores SIGTERM.
+    const t = setTimeout(() => { if (run.status === "stopping" && groupAlive(pid)) killGroup(pid, "SIGKILL"); }, 2500);
+    if (t.unref) t.unref();
+    return true;
+  }
+
+  get(id) { const r = this.runs.get(id); return r ? this._summary(r, true) : null; }
+  has(id) { return this.runs.has(id); }
+  list() {
+    return [...this.runs.values()].sort((a, b) => b.started - a.started).map((r) => this._summary(r, false));
+  }
+
+  /** Kill every live run's process group and WAIT for it to die, escalating
+   *  to SIGKILL after graceMs — mirrors AgentSessionManager.shutdownAll (MF1)
+   *  so the server's hard-exit timer can't strand a stubborn child. If a
+   *  group somehow survives SIGKILL, its marker stays on disk so the next
+   *  startup reaps it — never a silent orphan. */
+  shutdownAll(graceMs = 1500) {
+    if (this._sweep) { clearInterval(this._sweep); this._sweep = null; }
+    const live = [...this.runs.values()].filter((r) => r.child && (r.status === "running" || r.status === "stopping"));
+    return Promise.all(live.map((r) => new Promise((resolve) => {
+      const pid = r.child.pid;
+      killGroup(pid, "SIGTERM");
+      const start = Date.now();
+      let killed = false;
+      const tick = () => {
+        if (!groupAlive(pid)) { removeMarker(pid); return resolve(); }
+        if (!killed && Date.now() - start >= graceMs) { killGroup(pid, "SIGKILL"); killed = true; }
+        if (killed && Date.now() - start >= graceMs + 700) {
+          if (!groupAlive(pid)) removeMarker(pid);
+          return resolve();
+        }
+        const t = setTimeout(tick, 150); if (t.unref) t.unref();
+      };
+      tick();
+    })));
+  }
+
+  // ── internals ──────────────────────────────────────────────────────────────
+
+  _onChunk(run, chunk) {
+    const s = chunk.toString("utf8");
+    this._append(run, s);
+    this._emit(run, { type: "chunk", text: s });
+  }
+
+  _append(run, s, isTail) {
+    run.output += s;
+    if (run.output.length > this.opt.maxBuffer) {
+      // Keep the TAIL — it carries the latest work and the exit line that the
+      // client derives status from. `isTail` writes (exit/timeout lines) are
+      // short and always survive because they were just appended.
+      run.output = "[… earlier output truncated …]\n" + run.output.slice(run.output.length - this.opt.maxBuffer);
+      run.truncated = true;
+    }
+  }
+
+  _emit(run, ev) {
+    for (const cb of [...run.subscribers]) { try { cb(ev); } catch (_) { /* a dead subscriber must not break the loop */ } }
+  }
+
+  _finish(run, status, exit) {
+    // Terminal guard: a spawn failure fires 'error' THEN 'close', so both
+    // handlers call _finish. Without this, the second call overwrites a real
+    // "failed"/"stopped" with the close code (null -> "done") and emits a
+    // second "end". First finish wins. (Found by a Codex review, 2026-06-30.)
+    if (run.ended) return;
+    // Drop the crash marker only once the whole GROUP is gone; if a tool
+    // grandchild outlived the leader, the marker survives and the next
+    // dashboard startup reaps it.
+    if (run.child && run.child.pid && !groupAlive(run.child.pid)) removeMarker(run.child.pid);
+    run.status = status;
+    run.exit = exit;
+    run.ended = Date.now();
+    run.child = null;
+    this._emit(run, { type: "end", status, exit });
+    run.subscribers.clear();
+  }
+
+  _summary(run, withOutput) {
+    const s = {
+      id: run.id, agent: run.agent, label: run.label, status: run.status,
+      started: run.started, ended: run.ended, exit: run.exit,
+      truncated: run.truncated, bytes: run.output.length,
+    };
+    if (withOutput) s.output = run.output;
+    return s;
+  }
+
+  // Cap the number of retained runs: drop the OLDEST finished runs first; never
+  // evict a still-running run to make room.
+  _trimCount() {
+    if (this.runs.size <= this.opt.maxRuns) return;
+    const finished = [...this.runs.values()]
+      .filter((r) => r.status !== "running" && r.status !== "stopping")
+      .sort((a, b) => a.started - b.started);
+    while (this.runs.size > this.opt.maxRuns && finished.length) this.runs.delete(finished.shift().id);
+  }
+
+  _evict() {
+    const now = Date.now();
+    for (const r of [...this.runs.values()]) {
+      if (r.status !== "running" && r.status !== "stopping" && r.ended && now - r.ended > this.opt.finishedTtlMs) {
+        this.runs.delete(r.id);
+      }
+    }
+  }
+}
+
+module.exports = { RunRegistry, DEFAULTS };

package/src/dashboard/lib/safe-write.js

@@ -0,0 +1,63 @@
+"use strict";
+
+// safe-write.js — drift-guarded file writes (B5). Global Rules S21 (multi-instance safety) made
+// MECHANICAL instead of prompt-level. Multiple agents/dashboards can touch the same vault; before a
+// programmatic writer overwrites an important file (an Engine file, the Daily Note) it re-reads it
+// and byte-compares against the content it based its edit on (`expected`). If the file changed
+// underneath — another instance, the user in Obsidian, or an agent — the current bytes are preserved
+// to a timestamped sidecar (.bak.<ts>) BEFORE the new content lands, so a concurrent edit is never
+// silently clobbered. The write itself is atomic (tmp + rename). Pure Node stdlib, zero-dep.
+
+const fs = require("fs");
+const path = require("path");
+
+class DriftError extends Error {
+  constructor(file, backupPath) {
+    super(
+      backupPath
+        ? `drift: ${file} changed since it was read; preserved a backup at ${backupPath}`
+        : `drift: ${file} changed since it was read; aborted without writing (re-read and retry)`
+    );
+    this.name = "DriftError";
+    this.code = "EDRIFT";
+    this.file = file;
+    this.backupPath = backupPath || null;
+  }
+}
+
+// Write `next` to `file`, guarding against a concurrent edit.
+//   expected           — the bytes the caller last read and based `next` on. Pass null to skip drift
+//                        detection (a first write / no baseline / a known-fresh file).
+//   opts.throwOnDrift  — on drift, abort WITHOUT touching the file and throw DriftError, so the
+//                        caller can re-read + re-merge. Default false: back up the current bytes,
+//                        then proceed with the overwrite.
+//   opts.now           — timestamp for the .bak/.tmp suffix (deterministic in tests).
+// Returns { written, existed, drifted, backupPath }.
+function writeWithDriftGuard(file, expected, next, opts = {}) {
+  const ts = opts.now != null ? opts.now : Date.now();
+
+  let current = null, existed = false;
+  try { current = fs.readFileSync(file, "utf8"); existed = true; } catch { existed = false; }
+  const drifted = existed && expected != null && current !== expected;
+
+  // Abort path: leave the file exactly as the concurrent writer left it — no data loss, no backup.
+  if (drifted && opts.throwOnDrift) throw new DriftError(file, null);
+
+  let backupPath = null;
+  if (drifted) {
+    // We are about to overwrite a concurrent edit → preserve it first so nothing is lost silently.
+    backupPath = `${file}.bak.${ts}`;
+    fs.writeFileSync(backupPath, current);
+  }
+
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Same-directory tmp so the rename is a same-filesystem (atomic) operation, never a cross-device
+  // copy. pid in the suffix so two writers in the same ms don't collide on the scratch file.
+  const tmp = `${file}.tmp.${ts}.${process.pid}`;
+  fs.writeFileSync(tmp, next);
+  fs.renameSync(tmp, file); // atomic on POSIX: a concurrent reader sees old-or-new, never a partial
+
+  return { written: true, existed, drifted, backupPath };
+}
+
+module.exports = { writeWithDriftGuard, DriftError };