@agentprojectcontext/apx 1.77.3 → 1.79.0

package/src/core/stores/code-sessions.js

@@ -14,6 +14,7 @@ import path from "node:path";
 import { nowIso } from "../util/time.js";
 import { shortId as makeShortId } from "../util/ids.js";
 import { CODE_MODES, DEFAULT_CODE_MODE } from "../constants/code-modes.js";
+import { readJson, writeJson } from "#core/util/json-file.js";
 
 function sessionsDir(storagePath) {
   return path.join(storagePath, "code-sessions");
@@ -28,20 +29,8 @@ function shortId() {
 }
 
 // Atomic write: tmp file + rename so a crash mid-write can't corrupt a session.
-function writeJson(file, obj) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = `${file}.${process.pid}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2));
-  fs.renameSync(tmp, file);
-}
-
-function readJson(file) {
-  try {
-    return JSON.parse(fs.readFileSync(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
+// readJson/writeJson come from the shared kernel (this module's atomic write
+// was the one the others were missing).
 
 /** Lightweight row for the session list (no messages). */
 function toRow(s) {

package/src/core/stores/commitments.js

@@ -0,0 +1,331 @@
+// Commitments per project.
+//
+// Append-only JSONL event log, one file per month under
+//   ~/.apx/projects/<apxId>/commitments/YYYY-MM.jsonl
+//
+// A TASK is something to do. A COMMITMENT is something PROMISED TO A PERSON:
+// it has a counterparty, a date you gave them, and the channel you said it on.
+// Breaking one costs trust, not just throughput, and that is why it is a type
+// and not a tag.
+//
+// The tag version is tempting and wrong. The day you want "everything I owe
+// Ana" you would be substring-matching your way through task titles, and
+// "kept" versus "renegotiated" — the distinction that tells you whether a
+// relationship is fine — has nowhere to live at all.
+//
+// Events:
+//   create        — the promise (counterparty, body, due, origin_channel, …)
+//   update        — shallow-merge patch
+//   kept          — delivered
+//   missed        — the date passed without delivery. Recorded, not hidden:
+//                   a system that quietly drops what you failed to do cannot
+//                   tell you that you keep failing the same person.
+//   renegotiate   — a NEW date, agreed with them. Distinct from missing:
+//                   moving a date with someone is not the same as letting it
+//                   slide, and the history keeps both.
+//
+// State: "open" → "kept" | "missed" | "renegotiated" → (renegotiated reopens
+// as "open" with a new due, keeping the previous date in `history`).
+import fs from "node:fs";
+import path from "node:path";
+import { nowIso } from "../util/time.js";
+import { shortId as makeShortId } from "../util/ids.js";
+
+export const COMMITMENT_STATES = Object.freeze(["open", "kept", "missed", "renegotiated"]);
+
+function commitmentsDir(storagePath) {
+  return path.join(storagePath, "commitments");
+}
+
+function monthlyFile(storagePath, date = new Date()) {
+  const ym = date.toISOString().slice(0, 7); // YYYY-MM
+  return path.join(commitmentsDir(storagePath), `${ym}.jsonl`);
+}
+
+function shortId() {
+  return makeShortId("c");
+}
+
+function appendEvent(storagePath, event) {
+  const file = monthlyFile(storagePath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(event) + "\n");
+}
+
+function readAllEvents(storagePath) {
+  const dir = commitmentsDir(storagePath);
+  if (!fs.existsSync(dir)) return [];
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl")).sort();
+  const events = [];
+  for (const f of files) {
+    const text = fs.readFileSync(path.join(dir, f), "utf8");
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const ev = JSON.parse(line);
+        if (ev && ev.id && ev.op) events.push(ev);
+      } catch {
+        // One bad write must not blank the projection.
+      }
+    }
+  }
+  events.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
+  return events;
+}
+
+function projectState(events) {
+  const rows = new Map();
+  for (const ev of events) {
+    const existing = rows.get(ev.id);
+    switch (ev.op) {
+      case "create": {
+        if (existing) break; // duplicate create — keep the first
+        rows.set(ev.id, {
+          id: ev.id,
+          created_at: ev.ts,
+          updated_at: ev.ts,
+          state: "open",
+          counterparty: ev.counterparty || "",
+          body: ev.body || "",
+          promised_at: ev.promised_at || ev.ts,
+          due: ev.due || null,
+          origin_channel: ev.origin_channel || null,
+          origin_message_ref: ev.origin_message_ref || null,
+          created_by: ev.created_by || null,
+          // Every date this promise has ever had. Renegotiating twice is a
+          // fact about the relationship, and it is only visible if kept.
+          history: [],
+          meta: ev.meta && typeof ev.meta === "object" ? { ...ev.meta } : {},
+        });
+        break;
+      }
+      case "update": {
+        if (!existing) break;
+        const patch = ev.patch && typeof ev.patch === "object" ? ev.patch : {};
+        for (const k of Object.keys(patch)) {
+          if (k === "id" || k === "state" || k === "created_at" || k === "history") continue;
+          existing[k] = patch[k];
+        }
+        existing.updated_at = ev.ts;
+        break;
+      }
+      case "kept": {
+        if (!existing) break;
+        existing.state = "kept";
+        existing.closed_at = ev.ts;
+        existing.note = ev.note || existing.note || null;
+        existing.updated_at = ev.ts;
+        break;
+      }
+      case "missed": {
+        if (!existing) break;
+        existing.state = "missed";
+        existing.closed_at = ev.ts;
+        existing.note = ev.note || existing.note || null;
+        existing.updated_at = ev.ts;
+        break;
+      }
+      case "renegotiate": {
+        if (!existing) break;
+        existing.history.push({
+          due: existing.due,
+          moved_at: ev.ts,
+          note: ev.note || null,
+        });
+        existing.due = ev.due || existing.due;
+        // Back to open: a renegotiated promise is a live promise with a new
+        // date, not a closed one. "renegotiated" as a resting state would hide
+        // it from every "what do I owe people" view.
+        existing.state = "open";
+        existing.renegotiated_count = (existing.renegotiated_count || 0) + 1;
+        existing.updated_at = ev.ts;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return rows;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Record a promise.
+ * fields: { counterparty (required), body (required), due?, promised_at?,
+ *           origin_channel?, origin_message_ref?, created_by?, meta? }
+ */
+export function createCommitment(storagePath, fields) {
+  if (!fields || typeof fields !== "object") throw new Error("createCommitment: fields required");
+  if (!fields.counterparty || typeof fields.counterparty !== "string") {
+    // The counterparty IS the type. Without it this is a task.
+    throw new Error("createCommitment: counterparty required");
+  }
+  if (!fields.body || typeof fields.body !== "string") {
+    throw new Error("createCommitment: body required");
+  }
+  const id = shortId();
+  appendEvent(storagePath, {
+    id,
+    ts: nowIso(),
+    op: "create",
+    counterparty: fields.counterparty.trim(),
+    body: fields.body.trim(),
+    promised_at: fields.promised_at || nowIso(),
+    due: fields.due || null,
+    origin_channel: fields.origin_channel || null,
+    origin_message_ref: fields.origin_message_ref || null,
+    created_by: fields.created_by || null,
+    meta: fields.meta && typeof fields.meta === "object" ? fields.meta : {},
+  });
+  return getCommitment(storagePath, id);
+}
+
+/** Newest first, id as tiebreak — same reasoning as tasks.js byNewest. */
+function byNewest(a, b) {
+  const t = (b.created_at || "").localeCompare(a.created_at || "");
+  return t !== 0 ? t : String(b.id || "").localeCompare(String(a.id || ""));
+}
+
+/** Soonest deadline first; undated last. The order the anchors want. */
+function byDue(a, b) {
+  if (!a.due && !b.due) return byNewest(a, b);
+  if (!a.due) return 1;
+  if (!b.due) return -1;
+  const d = a.due.localeCompare(b.due);
+  return d !== 0 ? d : byNewest(a, b);
+}
+
+/**
+ * List commitments.
+ *
+ * opts: { state, counterparty, due_before, due_after, overdue, updated_since,
+ *         sort: "due"|"newest", limit }
+ * Default state is "open" — the useful question is what you still owe.
+ */
+export function listCommitments(storagePath, opts = {}) {
+  let out = [...projectState(readAllEvents(storagePath)).values()];
+
+  if (opts.state && opts.state !== "all") {
+    out = out.filter((c) => c.state === opts.state);
+  } else if (!opts.state) {
+    out = out.filter((c) => c.state === "open");
+  }
+  if (opts.counterparty) {
+    // Case-insensitive substring: counterparty is free text, not a CRM key,
+    // so "ana" must find "Ana Pérez" or the field is unusable.
+    const needle = String(opts.counterparty).toLowerCase();
+    out = out.filter((c) => String(c.counterparty).toLowerCase().includes(needle));
+  }
+  if (opts.due_before) out = out.filter((c) => c.due && c.due <= opts.due_before);
+  if (opts.due_after) out = out.filter((c) => c.due && c.due >= opts.due_after);
+  if (opts.overdue) {
+    const now = opts.now || nowIso();
+    out = out.filter((c) => c.state === "open" && c.due && c.due < now);
+  }
+  if (opts.updated_since) {
+    out = out.filter((c) => (c.updated_at || c.created_at || "") >= opts.updated_since);
+  }
+
+  out.sort(opts.sort === "newest" ? byNewest : byDue);
+  if (opts.limit && Number.isFinite(opts.limit)) out = out.slice(0, opts.limit);
+  return out;
+}
+
+/**
+ * The same query folded across registered projects. Mirrors
+ * listTasksAcrossProjects — a chief of staff lives in the cross-project layer,
+ * and a promise made in a meeting rarely knows which repo it belongs to.
+ *
+ * A project whose log is unreadable is SKIPPED, not fatal.
+ */
+export function listCommitmentsAcrossProjects(projects, opts = {}) {
+  const { limit, ...perProject } = opts || {};
+  const commitments = [];
+  const skipped = [];
+
+  for (const entry of projects || []) {
+    if (!entry?.storagePath) continue;
+    try {
+      for (const c of listCommitments(entry.storagePath, perProject)) {
+        commitments.push({
+          ...c,
+          project_id: entry.id,
+          project_name: entry.name || entry.path || String(entry.id),
+        });
+      }
+    } catch (e) {
+      skipped.push({ id: entry.id, error: e?.message || String(e) });
+    }
+  }
+
+  commitments.sort(opts.sort === "newest" ? byNewest : byDue);
+  return {
+    commitments: Number.isFinite(limit) && limit > 0 ? commitments.slice(0, limit) : commitments,
+    skipped,
+  };
+}
+
+/** Get one by id or unique id prefix (≥ 3 chars). */
+export function getCommitment(storagePath, idOrPrefix) {
+  if (!idOrPrefix || typeof idOrPrefix !== "string") return null;
+  const rows = projectState(readAllEvents(storagePath));
+  if (rows.has(idOrPrefix)) return rows.get(idOrPrefix);
+  if (idOrPrefix.length < 3) return null;
+  const matches = [...rows.values()].filter((c) => c.id.startsWith(idOrPrefix));
+  return matches.length === 1 ? matches[0] : null;
+}
+
+export function patchCommitment(storagePath, idOrPrefix, patch) {
+  const existing = getCommitment(storagePath, idOrPrefix);
+  if (!existing) return null;
+  if (!patch || typeof patch !== "object") return existing;
+  appendEvent(storagePath, { id: existing.id, ts: nowIso(), op: "update", patch });
+  return getCommitment(storagePath, existing.id);
+}
+
+/** Delivered. */
+export function keepCommitment(storagePath, idOrPrefix, note = null) {
+  return close(storagePath, idOrPrefix, "kept", note);
+}
+
+/** The date passed and it did not happen. */
+export function missCommitment(storagePath, idOrPrefix, note = null) {
+  return close(storagePath, idOrPrefix, "missed", note);
+}
+
+function close(storagePath, idOrPrefix, op, note) {
+  const existing = getCommitment(storagePath, idOrPrefix);
+  if (!existing) return null;
+  appendEvent(storagePath, { id: existing.id, ts: nowIso(), op, note: note || null });
+  return getCommitment(storagePath, existing.id);
+}
+
+/**
+ * A new date, agreed with them. Requires the new date: "renegotiated, no idea
+ * until when" is how a promise disappears.
+ */
+export function renegotiateCommitment(storagePath, idOrPrefix, due, note = null) {
+  if (!due) throw new Error("renegotiateCommitment: a new due date is required");
+  const existing = getCommitment(storagePath, idOrPrefix);
+  if (!existing) return null;
+  appendEvent(storagePath, {
+    id: existing.id, ts: nowIso(), op: "renegotiate", due, note: note || null,
+  });
+  return getCommitment(storagePath, existing.id);
+}
+
+/** Counts for status displays and anchors. */
+export function countCommitments(storagePath, now = nowIso()) {
+  const rows = [...projectState(readAllEvents(storagePath)).values()];
+  const open = rows.filter((c) => c.state === "open");
+  return {
+    open: open.length,
+    kept: rows.filter((c) => c.state === "kept").length,
+    missed: rows.filter((c) => c.state === "missed").length,
+    overdue: open.filter((c) => c.due && c.due < now).length,
+    total: rows.length,
+  };
+}

package/src/core/stores/engine-sessions.js

@@ -13,10 +13,6 @@ import path from "node:path";
 
 const homeDir = (opts) => (opts && opts.home) || os.homedir();
 
-function encodeClaudeProjectPath(cwd) {
-  return String(cwd || "").replace(/[^A-Za-z0-9]/g, "-");
-}
-
 function safeStatMtime(p) {
   try {
     return fs.statSync(p).mtimeMs;

package/src/core/stores/messages.js

@@ -29,11 +29,6 @@ function dayPathJsonl(projectRoot, ts) {
   return path.join(projectRoot, "messages", `${day}.jsonl`);
 }
 
-function dayPathMd(projectRoot, ts) {
-  const day = (ts || nowIso()).slice(0, 10);
-  return path.join(projectRoot, "messages", `${day}.md`);
-}
-
 // `compact` is a progressive-compaction summary record (Pieza 3): a dense
 // recap of older turns, stored inline in the channel JSONL so the reader can
 // prepend it as a [RESUMEN COMPACTADO] system turn instead of replaying the
@@ -689,6 +684,10 @@ export function readGlobalThread({ channel, date, _globalMessagesDir } = {}) {
         ...(r.actor_kind ? { actor_kind: r.actor_kind } : {}),
         ...(r.meta?.model ? { model: r.meta.model } : {}),
         ...(usage && typeof usage === "object" ? { usage } : {}),
+        // What the turn actually did. Recorded compactly at write time
+        // (core/agent/tool-summary.js) because the live tool events are gone
+        // by the time anyone reads the thread back.
+        ...(r.meta?.tool_summary ? { tool_summary: r.meta.tool_summary } : {}),
       };
     });
   return { id: date, channel, messages };

package/src/core/stores/organization.js

@@ -19,6 +19,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { apcOrganizationFile } from "../apc/paths.js";
+import { readJson } from "#core/util/json-file.js";
 
 export const ORG_SLUG_RE = /^[a-z][a-z0-9_-]*$/;
 
@@ -39,17 +40,14 @@ function emptyOrg() {
 
 export function readOrganization(root) {
   const file = apcOrganizationFile(root);
-  if (!fs.existsSync(file)) return emptyOrg();
-  try {
-    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
-    return {
-      areas: Array.isArray(raw.areas) ? raw.areas : [],
-      roles: Array.isArray(raw.roles) ? raw.roles : [],
-    };
-  } catch {
-    // A corrupt file shouldn't take down the whole project view.
-    return emptyOrg();
-  }
+  // A missing or corrupt file shouldn't take down the whole project view —
+  // readJson returns the fallback for both.
+  const raw = readJson(file, null);
+  if (!raw) return emptyOrg();
+  return {
+    areas: Array.isArray(raw.areas) ? raw.areas : [],
+    roles: Array.isArray(raw.roles) ? raw.roles : [],
+  };
 }
 
 function writeOrganization(root, org) {

package/src/core/stores/routines.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { CronExpressionParser } from "cron-parser";
 import { nowIso, isoToMs } from "../util/time.js";
 import { shortId } from "../util/ids.js";
+import { readJson, writeJson } from "#core/util/json-file.js";
 
 function routinesPath(storagePath) {
   // storagePath is always ~/.apx/projects/{apxId}/ — flat, no .apc subdir needed.
@@ -12,26 +13,31 @@ function routinesPath(storagePath) {
 }
 
 function readFile(projectPath) {
-  const p = routinesPath(projectPath);
-  if (!fs.existsSync(p)) return [];
-  try {
-    const raw = JSON.parse(fs.readFileSync(p, "utf8"));
-    return Array.isArray(raw.routines) ? raw.routines : [];
-  } catch {
-    return [];
-  }
+  const raw = readJson(routinesPath(projectPath), {});
+  return Array.isArray(raw?.routines) ? raw.routines : [];
 }
 
+// Atomic: a crash mid-write used to leave a truncated routines.json, and since
+// the reader swallows parse errors the next read reported "no routines".
 function writeFile(projectPath, routines) {
-  const p = routinesPath(projectPath);
-  fs.mkdirSync(path.dirname(p), { recursive: true });
-  fs.writeFileSync(p, JSON.stringify({ routines }, null, 2) + "\n");
+  writeJson(routinesPath(projectPath), { routines });
 }
 
 // --------------------- schedule parsing -------------------------------------
 
 export function parseSchedule(s, baseMs = Date.now()) {
   if (!s || typeof s !== "string") return { kind: "invalid" };
+
+  // "manual" — runs only when someone runs it. It USED to work by accident:
+  // the string failed cron parsing, came back "invalid", and an invalid
+  // schedule never becomes due. Correct outcome, wrong reason, and it meant
+  // every surface reported a deliberate choice as a broken expression.
+  if (s.trim().toLowerCase() === "manual") return { kind: "manual" };
+
+  // Tolerate a leading "cron " label. The web editor's own presets wrote
+  // `cron 0 9 * * *`, which cron-parser rejects — so picking "daily at 9am"
+  // in the panel produced a routine that never ran, with nothing to show why.
+  const labelled = s.trim().replace(/^cron\s+/i, "");
   
   if (s.startsWith("every:")) {
     const spec = s.slice(6).trim();
@@ -51,7 +57,7 @@ export function parseSchedule(s, baseMs = Date.now()) {
 
   // Fallback: Try parsing as standard cron expression using cron-parser
   try {
-    const interval = CronExpressionParser.parse(s, { currentDate: new Date(baseMs) });
+    const interval = CronExpressionParser.parse(labelled, { currentDate: new Date(baseMs) });
     return { kind: "cron", parser: interval };
   } catch (err) {
     return { kind: "invalid" };
@@ -60,7 +66,7 @@ export function parseSchedule(s, baseMs = Date.now()) {
 
 export function computeNextRun(routine, baseMs = Date.now()) {
   const sched = parseSchedule(routine.schedule, baseMs);
-  if (sched.kind === "invalid") return null;
+  if (sched.kind === "invalid" || sched.kind === "manual") return null;
   if (sched.kind === "once") {
     return sched.atMs > baseMs
       ? new Date(sched.atMs).toISOString().replace(/\.\d{3}Z$/, "Z")
@@ -232,7 +238,10 @@ export function getDueRoutines(projectPath, nowStr) {
     // CRITICAL: If the schedule cannot be parsed, NEVER run it.
     // Otherwise, an invalid schedule (like a cron string) sets next_run_at to null,
     // which previously caused it to be considered ALWAYS due and spam execution every 5 seconds!
-    if (parseSchedule(r.schedule).kind === "invalid") return false;
+    const kind = parseSchedule(r.schedule).kind;
+    // "manual" is a deliberate never-on-a-clock, not a broken expression —
+    // both are skipped here, but only one of them is a problem to report.
+    if (kind === "invalid" || kind === "manual") return false;
     return (!r.next_run_at || r.next_run_at <= nowStr);
   });
 }

package/src/core/stores/runtime-callbacks.js

@@ -18,6 +18,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { APX_HOME } from "#core/config/paths.js";
 import { nowIso } from "#core/util/time.js";
+import { readJson } from "#core/util/json-file.js";
 
 export const PENDING_CALLBACKS_DIR = path.join(APX_HOME, "pending-callbacks");
 
@@ -63,7 +64,7 @@ export function listPendingCallbacks() {
   const out = [];
   for (const f of files) {
     try {
-      const entry = JSON.parse(fs.readFileSync(path.join(PENDING_CALLBACKS_DIR, f), "utf8"));
+      const entry = readJson(path.join(PENDING_CALLBACKS_DIR, f), null);
       if (entry?.session_id) out.push(entry);
     } catch {
       /* skip corrupt */

package/src/core/util/json-file.js

@@ -0,0 +1,128 @@
+// JSON files on disk — one implementation.
+//
+// Six modules had grown their own read/write pair and 35 more sites inlined
+// `JSON.parse(fs.readFileSync(...))`. They did not agree on the things that
+// matter, so the guarantees your data got depended on which copy happened to
+// touch it:
+//
+//   - Atomicity. Only core/stores/code-sessions.js wrote through a temp file
+//     and renamed. Everywhere else, a crash or a full disk mid-write left a
+//     truncated file — and since the readers swallow parse errors, the next
+//     read silently returned "empty" instead of "corrupt". routines.json and
+//     the MCP stores were exposed to that.
+//   - Permissions. vars and mcp chmod 0600 because they hold tokens; the
+//     others did not, so the same kind of data could land world-readable
+//     depending on the writer.
+//   - Missing-file semantics. Some returned null, some {}, some threw.
+//
+// Reads are forgiving by design (a missing or corrupt file yields the caller's
+// fallback), because every caller here treats "no data" as a valid state.
+// Writes are strict: they create the directory, write atomically, and throw if
+// they cannot.
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+/** Mode for files that may contain tokens or credentials. */
+export const SECRET_MODE = 0o600;
+
+// Twelve call sites still parse inline, on purpose. They are the ones whose
+// failure mode is not "fall back to empty":
+//
+//   config/index.js       a corrupt ~/.apx/config.json must THROW, loudly. Its
+//                         silent fallback would be an empty config, i.e. every
+//                         key reset — the worst possible recovery.
+//   mcp/sources.js,       these report *which* file failed and why, so the user
+//   integrations/sources  can fix it; a bare fallback would hide the problem.
+//   profiles/lifecycle,   these read package.json / manifests where a parse
+//   project-config, …     error is a real error, not a missing-file state.
+//
+// If you are adding a new read whose answer on failure is "treat it as empty",
+// use readJson. If it is "tell the user", keep it explicit.
+
+/**
+ * Read and parse a JSON file.
+ *
+ * @param {string} file
+ * @param {unknown} [fallback=null] returned when the file is missing, empty or
+ *   unparseable. Pass `{}` or `[]` when the caller wants a shape it can spread.
+ */
+export function readJson(file, fallback = null) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return fallback; // missing file is a normal state, not an error
+  }
+  if (!raw.trim()) return fallback;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+/** Async variant, for request paths that must not block the event loop. */
+export async function readJsonAsync(file, fallback = null) {
+  let raw;
+  try {
+    raw = await fsp.readFile(file, "utf8");
+  } catch {
+    return fallback;
+  }
+  if (!raw.trim()) return fallback;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Write a value as pretty JSON, atomically.
+ *
+ * Writes to `<file>.<pid>.tmp` and renames, so a reader never observes a
+ * half-written file and a crash cannot destroy the previous contents.
+ *
+ * @param {string} file
+ * @param {unknown} value
+ * @param {{ mode?: number }} [opts] `mode: SECRET_MODE` for files holding
+ *   credentials.
+ */
+export function writeJson(file, value, { mode } = {}) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n");
+    if (mode !== undefined) fs.chmodSync(tmp, mode);
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    // Never leave the temp file behind on a failed write.
+    try { fs.unlinkSync(tmp); } catch { /* already gone */ }
+    throw err;
+  }
+}
+
+/** Async variant. Same atomic rename. */
+export async function writeJsonAsync(file, value, { mode } = {}) {
+  await fsp.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    await fsp.writeFile(tmp, JSON.stringify(value, null, 2) + "\n");
+    if (mode !== undefined) await fsp.chmod(tmp, mode);
+    await fsp.rename(tmp, file);
+  } catch (err) {
+    try { await fsp.unlink(tmp); } catch { /* already gone */ }
+    throw err;
+  }
+}
+
+/**
+ * Read, transform, write back — atomically, with the same fallback rules.
+ * Returns the value that was written.
+ */
+export function updateJson(file, updater, { fallback = null, mode } = {}) {
+  const next = updater(readJson(file, fallback));
+  writeJson(file, next, { mode });
+  return next;
+}