@cohortapp/agent-sdk 2.3.0

package/lib/env-compat.mjs

@@ -0,0 +1,74 @@
+/**
+ * lib/env-compat.mjs — NEOLITH_* ⇄ COHORT_* environment bridge.
+ *
+ * The Neolith→Cohort rename (f3082db) moved every brand env read site to
+ * COHORT_* (~86 sites: COHORT_API_KEY, COHORT_ORG_ID, COHORT_BASE, COHORT_DB,
+ * COHORT_ADMIN_TOKEN, …), but the installed fleet of Mac-mini agents still
+ * launches maestro binaries with the NEOLITH_* names baked into launchd
+ * plists, operator shells, and .env files. This module is the runtime layer a
+ * text rename cannot ship: one bidirectional alias pass over the environment,
+ * so that
+ *
+ *   - a fleet host exporting only NEOLITH_* keeps working against code that
+ *     reads COHORT_* (legacy → canonical), and
+ *   - a freshly-provisioned host exporting only COHORT_* keeps working for
+ *     any older installed binary or spawned subprocess that still reads
+ *     NEOLITH_* — children inherit the bridged env (canonical → legacy).
+ *
+ * Suffixes map 1:1 (the rename was textual): NEOLITH_API_KEY ⇄ COHORT_API_KEY.
+ * Never clobbers: a key that is already PRESENT — even set to "" — is left
+ * byte-for-byte untouched (`in` presence check, not truthiness), so an
+ * operator who deliberately sets both names to different values sees no
+ * surprise. Idempotent: a second pass finds every twin present and no-ops.
+ *
+ * NO import-time side effect — maestro modules are side-effect-free at import
+ * by convention. Every process entry (bin/maestro.mjs, bin/cohort-mcp.mjs,
+ * services/cohort/bin/cohort.mjs, the env-reading scripts/*.mjs) and the SDK
+ * entry lib/org/client.mjs — which agent bins import without ever passing
+ * through maestro's own entrypoints — call applyBrandEnvCompat() explicitly
+ * at the top, before any env-first config resolution.
+ *
+ * Zero deps — not even node builtins. ESM.
+ *
+ * @module lib/env-compat
+ */
+
+"use strict";
+
+/** Legacy brand prefix the installed fleet still exports. */
+export const LEGACY_PREFIX = "NEOLITH_";
+
+/** Canonical brand prefix the codebase reads post-rename. */
+export const CANONICAL_PREFIX = "COHORT_";
+
+/**
+ * Mirror every `NEOLITH_*` key onto its `COHORT_*` twin and vice versa,
+ * in place, skipping any twin that already exists (never clobbers; presence
+ * is `in`-based so an explicit empty string beats an alias). Safe to call
+ * repeatedly — the second call is a no-op.
+ *
+ * @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env=process.env]
+ *   Environment map to bridge in place; injectable for deterministic tests.
+ * @returns {{from:string,to:string}[]} the aliases created, in application
+ *   order — [] when nothing needed bridging (and always [] on a re-run).
+ */
+export function applyBrandEnvCompat(env = process.env) {
+  const created = [];
+  if (!env || typeof env !== "object") return created;
+  for (const key of Object.keys(env)) {
+    let twin;
+    if (key.startsWith(LEGACY_PREFIX)) {
+      twin = CANONICAL_PREFIX + key.slice(LEGACY_PREFIX.length);
+    } else if (key.startsWith(CANONICAL_PREFIX)) {
+      twin = LEGACY_PREFIX + key.slice(CANONICAL_PREFIX.length);
+    } else {
+      continue;
+    }
+    if (twin in env) continue; // never clobber — presence wins, even ""
+    const value = env[key];
+    if (typeof value !== "string") continue; // never mint "undefined" strings
+    env[twin] = value;
+    created.push({ from: key, to: twin });
+  }
+  return created;
+}

package/lib/env-compat.test.mjs

@@ -0,0 +1,104 @@
+/**
+ * env-compat.test.mjs — NEOLITH_* ⇄ COHORT_* bridge: both directions,
+ * no-clobber (presence beats aliasing, even for ""), non-brand keys
+ * untouched, idempotency, and the default process.env path. Uses injected
+ * plain-object envs everywhere except the one save/restore process.env test.
+ * Run: node --test lib/env-compat.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { applyBrandEnvCompat, LEGACY_PREFIX, CANONICAL_PREFIX } from "./env-compat.mjs";
+
+test("legacy → canonical: NEOLITH_* is mirrored to COHORT_*", () => {
+  const env = { NEOLITH_API_KEY: "nlk_123", NEOLITH_ORG_ID: "acme" };
+  const created = applyBrandEnvCompat(env);
+  assert.equal(env.COHORT_API_KEY, "nlk_123");
+  assert.equal(env.COHORT_ORG_ID, "acme");
+  assert.equal(env.NEOLITH_API_KEY, "nlk_123"); // source untouched
+  assert.deepEqual(
+    created.sort((a, b) => a.from.localeCompare(b.from)),
+    [
+      { from: "NEOLITH_API_KEY", to: "COHORT_API_KEY" },
+      { from: "NEOLITH_ORG_ID", to: "COHORT_ORG_ID" },
+    ],
+  );
+});
+
+test("canonical → legacy: COHORT_* is mirrored to NEOLITH_*", () => {
+  const env = { COHORT_DB: "/var/db/cohort.sqlite", COHORT_ADMIN_TOKEN: "adm_1" };
+  applyBrandEnvCompat(env);
+  assert.equal(env.NEOLITH_DB, "/var/db/cohort.sqlite");
+  assert.equal(env.NEOLITH_ADMIN_TOKEN, "adm_1");
+});
+
+test("never clobbers: a present twin is left byte-for-byte untouched", () => {
+  const env = {
+    NEOLITH_API_KEY: "old-value",
+    COHORT_API_KEY: "new-value", // both set, deliberately different
+    NEOLITH_BASE: "https://legacy.example",
+    COHORT_BASE: "", // present-but-empty still wins over the alias
+  };
+  const created = applyBrandEnvCompat(env);
+  assert.equal(env.COHORT_API_KEY, "new-value");
+  assert.equal(env.NEOLITH_API_KEY, "old-value");
+  assert.equal(env.COHORT_BASE, ""); // NOT overwritten by NEOLITH_BASE
+  assert.deepEqual(created, []); // every twin existed — nothing bridged
+});
+
+test("presence propagates: an empty-string source mirrors as empty string", () => {
+  const env = { NEOLITH_AGENT_ID: "" };
+  applyBrandEnvCompat(env);
+  assert.equal(env.COHORT_AGENT_ID, "");
+});
+
+test("non-brand keys and non-string values are ignored", () => {
+  const env = {
+    PATH: "/usr/bin",
+    NEOLITHIC_ERA: "not-a-brand-var", // prefix must match exactly
+    COHORTS: "plural, not the prefix",
+    NEOLITH_BROKEN: undefined, // never minted into "undefined"
+  };
+  const created = applyBrandEnvCompat(env);
+  assert.deepEqual(created, []);
+  assert.ok(!("COHORT_BROKEN" in env));
+  assert.ok(!("COHORTIC_ERA" in env));
+  assert.equal(Object.keys(env).length, 4);
+});
+
+test("idempotent: a second pass is a no-op that reports []", () => {
+  const env = { NEOLITH_API_TOKEN: "t1", COHORT_REPO: "/path/to/hq" };
+  const first = applyBrandEnvCompat(env);
+  assert.equal(first.length, 2);
+  const snapshot = { ...env };
+  const second = applyBrandEnvCompat(env);
+  assert.deepEqual(second, []);
+  assert.deepEqual(env, snapshot);
+});
+
+test("defaults to process.env and bridges the real environment", () => {
+  // Unique suffix so a concurrent test file can never collide.
+  const suffix = `ENV_COMPAT_TEST_${process.pid}`;
+  const legacyKey = `${LEGACY_PREFIX}${suffix}`;
+  const canonicalKey = `${CANONICAL_PREFIX}${suffix}`;
+  const prevLegacy = process.env[legacyKey];
+  const prevCanonical = process.env[canonicalKey];
+  try {
+    delete process.env[canonicalKey];
+    process.env[legacyKey] = "bridged";
+    applyBrandEnvCompat();
+    assert.equal(process.env[canonicalKey], "bridged");
+  } finally {
+    if (prevLegacy == null) delete process.env[legacyKey];
+    else process.env[legacyKey] = prevLegacy;
+    if (prevCanonical == null) delete process.env[canonicalKey];
+    else process.env[canonicalKey] = prevCanonical;
+  }
+});
+
+test("tolerates a missing/foreign env argument without throwing", () => {
+  assert.deepEqual(applyBrandEnvCompat(null), []);
+  assert.deepEqual(applyBrandEnvCompat("not-an-object"), []);
+});

package/lib/feature-init.mjs

@@ -0,0 +1,331 @@
+/**
+ * Maestro — Feature Init Tracking
+ *
+ * Pairs the framework's `framework-features.json` (versioned registry) with
+ * each agent's `.maestro/features.json` (per-agent installed state) so
+ * `maestro upgrade` and `maestro init` can:
+ *
+ *   1. Detect new framework features the agent has not yet initialised.
+ *   2. Auto-run low-risk init steps (mkdir, scaffold, copy).
+ *   3. Defer init steps that need user input (RAG repo selection, backup
+ *      credentials) onto a `pending` queue.
+ *   4. Surface the pending queue via a SessionStart hook banner so the
+ *      operator (or Claude) sees "run `maestro init` to complete setup"
+ *      every time a Claude Code session opens in the agent's directory.
+ *
+ * Storage:
+ *   ~/maestro/framework-features.json     ← framework SOT
+ *   ~/<agent>/.maestro/features.json      ← agent's installed state
+ *
+ * Agent file shape:
+ *   {
+ *     "framework_version": "1.9.0",
+ *     "schema_version": "1",
+ *     "last_upgrade": "2026-05-12T10:00:00Z",
+ *     "initialized": {
+ *       "<feature-name>": { "version": "1", "initialized_at": "..." }
+ *     },
+ *     "pending": [
+ *       { "feature": "...", "added_at": "...", "version": "1" }
+ *     ]
+ *   }
+ *
+ * The library is dep-free (only node:fs / node:path / node:child_process)
+ * and exits cleanly on missing files — fresh agents that haven't been
+ * upgraded yet simply have no `.maestro/features.json`.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const FEATURE_REGISTRY_RELATIVE = "framework-features.json";
+export const AGENT_STATE_RELATIVE = ".maestro/features.json";
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+export function resolveAgentRoot(agentRoot) {
+  return resolve(agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+}
+
+export function getStatePath(agentRoot) {
+  return join(resolveAgentRoot(agentRoot), AGENT_STATE_RELATIVE);
+}
+
+// ---------------------------------------------------------------------------
+// Registry / state loaders
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the framework feature registry. Pass the absolute path to
+ * `framework-features.json` (typically resolved relative to the maestro
+ * CLI entry point). Returns the parsed registry or throws if missing.
+ */
+export function loadRegistry(registryPath) {
+  if (!existsSync(registryPath)) {
+    throw new Error(`framework-features.json not found at ${registryPath}`);
+  }
+  try {
+    return JSON.parse(readFileSync(registryPath, "utf-8"));
+  } catch (err) {
+    throw new Error(`failed to parse framework-features.json: ${err.message}`);
+  }
+}
+
+/**
+ * Load the per-agent install state. Returns a fresh empty state if the
+ * file doesn't exist yet — callers should treat that as "every feature is
+ * pending init for the first time".
+ */
+export function loadAgentState(agentRoot) {
+  const statePath = getStatePath(agentRoot);
+  if (!existsSync(statePath)) {
+    return {
+      framework_version: null,
+      schema_version: "1",
+      last_upgrade: null,
+      initialized: {},
+      pending: [],
+    };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(statePath, "utf-8"));
+    // Defensive defaults so partially-written state still works.
+    raw.initialized = raw.initialized || {};
+    raw.pending = Array.isArray(raw.pending) ? raw.pending : [];
+    raw.schema_version = raw.schema_version || "1";
+    return raw;
+  } catch {
+    return {
+      framework_version: null,
+      schema_version: "1",
+      last_upgrade: null,
+      initialized: {},
+      pending: [],
+    };
+  }
+}
+
+export function saveAgentState(agentRoot, state) {
+  const statePath = getStatePath(agentRoot);
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Diff between registry and agent state
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a list of features that need initialisation. A feature is "needs
+ * init" when the registry's `version` is strictly newer than the agent's
+ * recorded version, OR when the agent has no entry at all.
+ *
+ * Returns: [{ name, version, definition, status: "new" | "upgraded" }]
+ */
+export function diffFeatures(registry, agentState) {
+  const out = [];
+  const installed = agentState.initialized || {};
+  for (const [name, def] of Object.entries(registry.features || {})) {
+    const current = installed[name];
+    if (!current) {
+      out.push({ name, version: def.version, definition: def, status: "new" });
+      continue;
+    }
+    if (String(current.version) !== String(def.version)) {
+      out.push({ name, version: def.version, definition: def, status: "upgraded" });
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Init runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconcile the agent's state with the registry. For each diffed feature:
+ *   - if `init.auto === true` and `runAuto`, execute init.command (spawn
+ *     /bin/bash -lc so wrappers / npx scripts resolve correctly).
+ *   - else, add to pending list.
+ *
+ * Options:
+ *   maestroRoot   absolute path to ~/maestro (used to resolve init scripts)
+ *   agentRoot     absolute path to the agent's repo
+ *   registry      parsed registry (loaded by loadRegistry)
+ *   runAuto       boolean; default true. Set false during dry-run/plan modes.
+ *   logger        optional fn({ stage, feature, status, message })
+ *
+ * Returns: { ranAuto: [...], pending: [...], failed: [...] }
+ */
+export function reconcileFeatures({ maestroRoot, agentRoot, registry, runAuto = true, logger } = {}) {
+  const root = resolveAgentRoot(agentRoot);
+  const state = loadAgentState(root);
+  const diff = diffFeatures(registry, state);
+  const result = { ranAuto: [], pending: [], failed: [] };
+  const log = logger || (() => {});
+  const now = new Date().toISOString();
+
+  for (const item of diff) {
+    const init = item.definition.init || {};
+    const isAuto = init.auto === true;
+
+    if (isAuto && runAuto) {
+      log({ stage: "running", feature: item.name, message: init.description });
+      const ran = runInitCommand({ maestroRoot, agentRoot: root, command: init.command });
+      if (ran.ok) {
+        state.initialized[item.name] = { version: String(item.version), initialized_at: now };
+        result.ranAuto.push(item.name);
+        log({ stage: "completed", feature: item.name });
+      } else {
+        result.failed.push({ name: item.name, error: ran.error });
+        // Push to pending so user can retry manually.
+        pushPending(state, item, now);
+        log({ stage: "failed", feature: item.name, message: ran.error });
+      }
+    } else {
+      pushPending(state, item, now);
+      result.pending.push(item.name);
+      log({ stage: "pending", feature: item.name, message: init.description });
+    }
+  }
+
+  // After reconciliation, prune any pending entries that are now
+  // initialised (e.g. user ran the init manually).
+  state.pending = (state.pending || []).filter((p) => !state.initialized[p.feature]);
+
+  state.framework_version = registry.framework_version || state.framework_version;
+  state.last_upgrade = now;
+  saveAgentState(root, state);
+  return result;
+}
+
+function pushPending(state, item, now) {
+  const existing = (state.pending || []).find((p) => p.feature === item.name);
+  if (existing) {
+    existing.version = String(item.version);
+    existing.added_at = existing.added_at || now;
+    return;
+  }
+  state.pending = state.pending || [];
+  state.pending.push({
+    feature: item.name,
+    version: String(item.version),
+    added_at: now,
+    title: item.definition.title || item.name,
+    description: item.definition.init?.description || "",
+    command: item.definition.init?.command || "",
+  });
+}
+
+/**
+ * Run an init command in the agent repo.
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * TRUST BOUNDARY (audit L20) — READ BEFORE CHANGING.
+ *
+ * `command` MUST originate ONLY from the trusted framework feature registry
+ * (`framework-features.json`, loaded by {@link loadRegistry}). That file is
+ * shipped with maestro and version-controlled; its `init.command` strings are
+ * authored by framework maintainers, NOT by end users, inbound messages, or
+ * any other runtime input.
+ *
+ * The generic-shell fallback below executes `command` via `/bin/bash -lc`,
+ * which is shell-INTERPRETED (unlike the rest of maestro, which uses
+ * execFile/spawn with argv arrays per the project's no-shell convention). That
+ * is acceptable ONLY because the input is trusted-by-provenance. If you ever
+ * wire a caller that lets untrusted data reach `command`, you MUST instead
+ * pass an argv array to spawnSync without a shell (or an allowlist) — do NOT
+ * extend the `/bin/bash -lc` path to untrusted input.
+ *
+ * As defence-in-depth, this function refuses an obviously-untrusted command:
+ * a non-string, or a string carrying NUL / newline / carriage-return bytes
+ * (which a legitimate single-line registry command never contains and which
+ * are classic shell-injection smuggling vectors). This guard does not weaken
+ * the trusted path; it only fails closed on input that could not have come
+ * from a well-formed registry entry.
+ *
+ * Accepts simple shell strings so init scripts can rely on PATH having
+ * homebrew/nvm bins. Always runs with cwd = agentRoot and inherits the
+ * caller's env plus AGENT_ROOT.
+ * ──────────────────────────────────────────────────────────────────────────
+ */
+function runInitCommand({ maestroRoot, agentRoot, command }) {
+  if (!command || command === "true") return { ok: true };
+  // Defence-in-depth guard (audit L20): a well-formed registry init.command is
+  // a single-line string. Anything else is treated as untrusted and refused
+  // rather than handed to the shell.
+  if (typeof command !== "string" || /[\0\r\n]/.test(command)) {
+    return { ok: false, error: "refused untrusted init command (must be a single-line string from the framework registry)" };
+  }
+  // If the command names a path that exists relative to maestroRoot,
+  // resolve to its absolute path so the init script doesn't depend on
+  // the agent having a copy of the script already.
+  const parts = command.split(/\s+/);
+  // Support: `node scripts/setup/init-xxx.mjs`
+  if (parts[0] === "node" && parts[1]) {
+    const candidateAgent = join(agentRoot, parts[1]);
+    const candidateFramework = maestroRoot ? join(maestroRoot, parts[1]) : null;
+    let scriptPath = null;
+    if (existsSync(candidateAgent)) scriptPath = candidateAgent;
+    else if (candidateFramework && existsSync(candidateFramework)) scriptPath = candidateFramework;
+    if (scriptPath) {
+      const args = [scriptPath, ...parts.slice(2)];
+      const r = spawnSync(process.execPath, args, {
+        cwd: agentRoot,
+        env: { ...process.env, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot, MAESTRO_ROOT: maestroRoot || "" },
+        encoding: "utf-8",
+      });
+      if (r.status === 0) return { ok: true, stdout: r.stdout };
+      return { ok: false, error: (r.stderr || `exit ${r.status}`).trim() };
+    }
+    return { ok: false, error: `init script not found: ${parts[1]}` };
+  }
+  // Generic shell fallback. SHELL-INTERPRETED — `command` MUST be trusted
+  // (framework-registry-sourced) per the TRUST BOUNDARY note above. The guard
+  // at the top of this function has already rejected obviously-untrusted input.
+  const r = spawnSync("/bin/bash", ["-lc", command], {
+    cwd: agentRoot,
+    env: { ...process.env, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot, MAESTRO_ROOT: maestroRoot || "" },
+    encoding: "utf-8",
+  });
+  if (r.status === 0) return { ok: true, stdout: r.stdout };
+  return { ok: false, error: (r.stderr || `exit ${r.status}`).trim() };
+}
+
+// ---------------------------------------------------------------------------
+// Pending queue accessors (used by banner + `maestro init`)
+// ---------------------------------------------------------------------------
+
+export function listPending(agentRoot) {
+  const state = loadAgentState(agentRoot);
+  return state.pending || [];
+}
+
+export function markInitialised(agentRoot, featureName, version) {
+  const state = loadAgentState(agentRoot);
+  state.initialized = state.initialized || {};
+  state.initialized[featureName] = {
+    version: String(version),
+    initialized_at: new Date().toISOString(),
+  };
+  state.pending = (state.pending || []).filter((p) => p.feature !== featureName);
+  saveAgentState(agentRoot, state);
+}
+
+export function bannerSnapshot(agentRoot) {
+  const state = loadAgentState(agentRoot);
+  return {
+    pending_count: (state.pending || []).length,
+    pending: state.pending || [],
+    last_upgrade: state.last_upgrade,
+    framework_version: state.framework_version,
+  };
+}

package/lib/fs-atomic.mjs

@@ -0,0 +1,112 @@
+/**
+ * fs-atomic.mjs — durable, atomic filesystem write primitives.
+ *
+ * Many maestro writers (self.json, org-state JSONLs, registry/presence files,
+ * cost ledgers) currently use a bare `writeFileSync`, which can leave a
+ * zero-length or half-written file if the process dies mid-write — exactly the
+ * corruption hazard the state-integrity audit flagged. This module is the one
+ * shared home for the write-temp → fsync → rename primitive so every durable
+ * writer gets crash-safety the same way (SPEC-org-server Phase 0; roadmap 0.15).
+ *
+ * The pattern (proven in lib/cadence-bus.mjs `writeJsonAtomic`): write a sibling
+ * `.tmp` file, fsync its CONTENTS to disk, then `rename(2)` it over the target.
+ * The fsync happens BEFORE the rename so the durable bytes are in place once the
+ * atomic rename publishes the name — a crash after rename returns cannot surface
+ * a partial file. On macOS APFS (and Linux ext4/xfs) rename(2) is atomic for a
+ * same-directory source/dest.
+ *
+ * Node builtins only (maestro is "type":"module", near-zero-dep by design).
+ *
+ * @module lib/fs-atomic
+ */
+
+import {
+  mkdirSync,
+  openSync,
+  writeSync,
+  fsyncSync,
+  closeSync,
+  renameSync,
+  unlinkSync,
+  appendFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+/**
+ * Build a collision-resistant sibling temp path for `targetPath`. Keeping the
+ * temp file in the SAME directory guarantees the subsequent rename is
+ * same-volume (and therefore atomic), unlike a temp in os.tmpdir().
+ * @param {string} targetPath
+ * @returns {string}
+ */
+function tmpSibling(targetPath) {
+  return `${targetPath}.tmp.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}`;
+}
+
+/**
+ * Atomically write `data` (string or Buffer) to `targetPath`, creating parent
+ * dirs as needed. Durable: contents are fsync'd before the rename publishes the
+ * name. Throws on failure (after cleaning up the temp file).
+ *
+ * @param {string} targetPath
+ * @param {string|Buffer} data
+ * @param {object} [opts]
+ * @param {import("node:fs").Mode} [opts.mode] file mode for the created file
+ * @returns {void}
+ */
+export function writeFileAtomic(targetPath, data, opts = {}) {
+  mkdirSync(dirname(targetPath), { recursive: true });
+  const tmp = tmpSibling(targetPath);
+  const fd = openSync(tmp, "w", opts.mode);
+  try {
+    writeSync(fd, data);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    renameSync(tmp, targetPath);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* ignore orphan-cleanup failure */ }
+    throw err;
+  }
+}
+
+/**
+ * Atomically write `obj` as pretty-printed JSON (+ trailing newline) to
+ * `targetPath`. The canonical writer for self.json / config / state snapshots.
+ *
+ * @param {string} targetPath
+ * @param {unknown} obj
+ * @param {object} [opts] @param {import("node:fs").Mode} [opts.mode]
+ * @returns {void}
+ */
+export function writeJsonAtomic(targetPath, obj, opts = {}) {
+  writeFileAtomic(targetPath, JSON.stringify(obj, null, 2) + "\n", opts);
+}
+
+/**
+ * Append one JSON record as a single line to a JSONL file (append-only logs:
+ * audit trails, org-event streams, ledgers). Creates parent dirs as needed.
+ *
+ * A single `appendFileSync` of a sub-PIPE_BUF line is the standard atomic-append
+ * idiom for an O_APPEND write on a local filesystem; we serialize the object
+ * once and write it in a single call so concurrent appenders interleave whole
+ * lines, never partial ones. Returns true on success; on IO failure returns
+ * false rather than throwing, so a best-effort audit append can never crash the
+ * caller's main path (callers that need hard durability should check the return).
+ *
+ * @param {string} targetPath
+ * @param {unknown} record
+ * @returns {boolean} true if the line was written
+ */
+export function appendJsonl(targetPath, record) {
+  try {
+    mkdirSync(dirname(targetPath), { recursive: true });
+    appendFileSync(targetPath, JSON.stringify(record) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}