@cohortapp/agent-sdk 2.3.0

package/lib/diagnostics/alerts.test.mjs

@@ -0,0 +1,318 @@
+/**
+ * alerts.test.mjs — coverage for lib/diagnostics/alerts.mjs.
+ *
+ * Each behavioral rule must FIRE at/above its threshold and stay QUIET below it,
+ * emitAlerts must post every alert to an injected sink (no live call), and both
+ * entry points must never throw on garbage input.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  evaluateAlerts,
+  emitAlerts,
+  loadThresholds,
+  mergeThresholds,
+  DEFAULT_THRESHOLDS,
+  _internals,
+} from "./alerts.mjs";
+
+const ids = (alerts) => alerts.map((a) => a.id).sort();
+const byId = (alerts, id) => alerts.find((a) => a.id === id);
+
+// ---------------------------------------------------------------------------
+// refusal spike
+// ---------------------------------------------------------------------------
+
+test("refusal_spike: quiet below warn, warns at warn, critical at crit", () => {
+  // Defaults: warn 10, crit 25, across counters refusal/policy.refusal/classifier.refusal.
+  assert.equal(byId(evaluateAlerts({ snapshot: { refusal: 9 } }), "refusal_spike"), undefined);
+
+  const warn = byId(evaluateAlerts({ snapshot: { refusal: 10 } }), "refusal_spike");
+  assert.ok(warn, "fires at warn threshold");
+  assert.equal(warn.severity, "warning");
+
+  // Summed across the configured counters.
+  const summed = byId(
+    evaluateAlerts({ snapshot: { refusal: 12, "policy.refusal": 8, "classifier.refusal": 6 } }),
+    "refusal_spike"
+  );
+  assert.ok(summed);
+  assert.equal(summed.severity, "critical"); // 26 >= 25
+  assert.match(summed.detail, /26 refusals/);
+});
+
+// ---------------------------------------------------------------------------
+// guard fail-open spike (named + suffix match)
+// ---------------------------------------------------------------------------
+
+test("guard_fail_spike: suffix-matched counters are summed and banded", () => {
+  // Below warn (5).
+  assert.equal(
+    byId(evaluateAlerts({ snapshot: { "rate_guard.fail_open": 4 } }), "guard_fail_spike"),
+    undefined
+  );
+
+  // At warn: 5 across suffix matches.
+  const warn = byId(
+    evaluateAlerts({ snapshot: { "rate_guard.fail_open": 3, "budget_guard.persist_failed": 2 } }),
+    "guard_fail_spike"
+  );
+  assert.ok(warn);
+  assert.equal(warn.severity, "warning");
+
+  // At crit: 20.
+  const crit = byId(
+    evaluateAlerts({ snapshot: { "x.fail_open": 10, "y.degraded": 10 } }),
+    "guard_fail_spike"
+  );
+  assert.ok(crit);
+  assert.equal(crit.severity, "critical");
+
+  // A non-matching counter must NOT contribute.
+  assert.equal(
+    byId(evaluateAlerts({ snapshot: { "some.unrelated_counter": 99 } }), "guard_fail_spike"),
+    undefined
+  );
+});
+
+// ---------------------------------------------------------------------------
+// cost per session p99
+// ---------------------------------------------------------------------------
+
+test("cost_per_session_p99: uses p99 of the distribution when present", () => {
+  // 10 cheap sessions, one $4 outlier — p99 (nearest-rank) picks the outlier.
+  const perSessionUSD = [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 4.0];
+  const a = byId(
+    evaluateAlerts({ ledger: { sessions: 10, spentUSD: 4.9, perSessionUSD } }),
+    "cost_per_session_p99"
+  );
+  assert.ok(a, "fires when p99 exceeds crit");
+  assert.equal(a.severity, "critical"); // 4.0 >= crit 3.0
+  assert.match(a.detail, /p99/);
+});
+
+test("cost_per_session_p99: falls back to mean when no distribution", () => {
+  // mean = 10/5 = 2.0 → warning (>=1.5, <3.0).
+  const a = byId(
+    evaluateAlerts({ ledger: { sessions: 5, spentUSD: 10 } }),
+    "cost_per_session_p99"
+  );
+  assert.ok(a);
+  assert.equal(a.severity, "warning");
+  assert.match(a.detail, /mean/);
+});
+
+test("cost_per_session_p99: stays quiet below the warn threshold", () => {
+  // mean = 5/5 = 1.0 < warn 1.5.
+  assert.equal(
+    byId(evaluateAlerts({ ledger: { sessions: 5, spentUSD: 5 } }), "cost_per_session_p99"),
+    undefined
+  );
+});
+
+test("cost_per_session_p99: does not fire on a tiny sample (minSessions)", () => {
+  // Only 4 sessions (< minSessions 5) even though per-session spend is huge.
+  assert.equal(
+    byId(evaluateAlerts({ ledger: { sessions: 4, spentUSD: 40 } }), "cost_per_session_p99"),
+    undefined
+  );
+});
+
+// ---------------------------------------------------------------------------
+// absent agent
+// ---------------------------------------------------------------------------
+
+test("absent_agent: quiet below warn, warns then crits on heartbeat age", () => {
+  // Defaults: warn 600s, crit 1800s.
+  assert.equal(
+    byId(evaluateAlerts({ presence: { heartbeatAgeSec: 300 } }), "absent_agent"),
+    undefined
+  );
+
+  const warn = byId(evaluateAlerts({ presence: { heartbeatAgeSec: 600 } }), "absent_agent");
+  assert.ok(warn);
+  assert.equal(warn.severity, "warning");
+
+  const crit = byId(evaluateAlerts({ presence: { heartbeatAgeSec: 2000 } }), "absent_agent");
+  assert.ok(crit);
+  assert.equal(crit.severity, "critical");
+
+  // No heartbeat age supplied → absent_agent does NOT fire (daemon_down covers it).
+  assert.equal(byId(evaluateAlerts({ presence: {} }), "absent_agent"), undefined);
+});
+
+// ---------------------------------------------------------------------------
+// daemon down
+// ---------------------------------------------------------------------------
+
+test("daemon_down: explicit flag is critical; stale heartbeat is banded", () => {
+  const flagged = byId(evaluateAlerts({ presence: { daemonDown: true } }), "daemon_down");
+  assert.ok(flagged);
+  assert.equal(flagged.severity, "critical");
+
+  // Defaults: warn 120s, crit 300s.
+  assert.equal(
+    byId(evaluateAlerts({ presence: { daemonHealthAgeSec: 60 } }), "daemon_down"),
+    undefined
+  );
+  const warn = byId(evaluateAlerts({ presence: { daemonHealthAgeSec: 150 } }), "daemon_down");
+  assert.ok(warn);
+  assert.equal(warn.severity, "warning");
+  const crit = byId(evaluateAlerts({ presence: { daemonHealthAgeSec: 600 } }), "daemon_down");
+  assert.ok(crit);
+  assert.equal(crit.severity, "critical");
+});
+
+// ---------------------------------------------------------------------------
+// determinism, ordering, custom thresholds
+// ---------------------------------------------------------------------------
+
+test("evaluateAlerts: deterministic, critical-first ordering", () => {
+  const args = {
+    snapshot: { refusal: 30 }, // critical refusal_spike
+    presence: { heartbeatAgeSec: 700 }, // warning absent_agent
+  };
+  const a = evaluateAlerts(args);
+  assert.deepEqual(ids(a), ["absent_agent", "refusal_spike"]);
+  // Critical sorts before warning.
+  assert.equal(a[0].severity, "critical");
+  assert.equal(a[0].id, "refusal_spike");
+  // Repeated evaluation is identical.
+  assert.deepEqual(evaluateAlerts(args), a);
+});
+
+test("evaluateAlerts: custom thresholds override defaults", () => {
+  // Lower the refusal warn to 2 so 3 refusals fires.
+  const a = byId(
+    evaluateAlerts({ snapshot: { refusal: 3 }, thresholds: { refusalSpike: { warnCount: 2, critCount: 100 } } }),
+    "refusal_spike"
+  );
+  assert.ok(a);
+  assert.equal(a.severity, "warning");
+});
+
+test("evaluateAlerts: clean inputs produce no alerts", () => {
+  const a = evaluateAlerts({
+    snapshot: { some_ok_counter: 3 },
+    ledger: { sessions: 100, spentUSD: 10 }, // mean 0.1 — fine
+    presence: { heartbeatAgeSec: 5, daemonHealthAgeSec: 5 },
+  });
+  assert.deepEqual(a, []);
+});
+
+test("evaluateAlerts: never throws on garbage input", () => {
+  assert.doesNotThrow(() => evaluateAlerts());
+  assert.doesNotThrow(() => evaluateAlerts(null));
+  assert.doesNotThrow(() => evaluateAlerts({ snapshot: 42, ledger: "x", presence: [] }));
+  assert.deepEqual(evaluateAlerts({ snapshot: 42, ledger: "x", presence: [] }), []);
+});
+
+// ---------------------------------------------------------------------------
+// emitAlerts — injected sink, never live
+// ---------------------------------------------------------------------------
+
+test("emitAlerts: posts every alert to the injected sink", async () => {
+  const posted = [];
+  const sink = (alert) => {
+    posted.push(alert);
+    return true;
+  };
+  const alerts = [
+    { id: "a", severity: "warning", detail: "x" },
+    { id: "b", severity: "critical", detail: "y" },
+  ];
+  const summary = await emitAlerts(alerts, { sink });
+  assert.equal(summary.attempted, 2);
+  assert.equal(summary.delivered, 2);
+  assert.equal(summary.failed, 0);
+  assert.deepEqual(posted.map((a) => a.id), ["a", "b"]);
+});
+
+test("emitAlerts: async sink is awaited; undefined return counts as delivered", async () => {
+  const seen = [];
+  const sink = async (alert) => {
+    await Promise.resolve();
+    seen.push(alert.id);
+    // returns undefined
+  };
+  const summary = await emitAlerts([{ id: "z", severity: "warning", detail: "d" }], { sink });
+  assert.equal(summary.delivered, 1);
+  assert.deepEqual(seen, ["z"]);
+});
+
+test("emitAlerts: a throwing sink fails that alert but not the rest", async () => {
+  const delivered = [];
+  const sink = (alert) => {
+    if (alert.id === "boom") throw new Error("sink down");
+    delivered.push(alert.id);
+    return true;
+  };
+  const summary = await emitAlerts(
+    [
+      { id: "ok1", severity: "warning", detail: "" },
+      { id: "boom", severity: "critical", detail: "" },
+      { id: "ok2", severity: "warning", detail: "" },
+    ],
+    { sink }
+  );
+  assert.equal(summary.attempted, 3);
+  assert.equal(summary.delivered, 2);
+  assert.equal(summary.failed, 1);
+  assert.deepEqual(delivered, ["ok1", "ok2"]);
+  assert.deepEqual(summary.results.find((r) => r.id === "boom"), { id: "boom", ok: false });
+});
+
+test("emitAlerts: a sink returning false is a failed delivery", async () => {
+  const summary = await emitAlerts([{ id: "a", severity: "warning", detail: "" }], {
+    sink: () => false,
+  });
+  assert.equal(summary.delivered, 0);
+  assert.equal(summary.failed, 1);
+});
+
+test("emitAlerts: no sink wired counts as failed (raised but went nowhere)", async () => {
+  const summary = await emitAlerts([{ id: "a", severity: "warning", detail: "" }], {});
+  assert.equal(summary.attempted, 1);
+  assert.equal(summary.delivered, 0);
+  assert.equal(summary.failed, 1);
+});
+
+test("emitAlerts: never throws on garbage", async () => {
+  await assert.doesNotReject(() => emitAlerts());
+  await assert.doesNotReject(() => emitAlerts(null, null));
+  const s = await emitAlerts("not-an-array", { sink: () => true });
+  assert.equal(s.attempted, 0);
+});
+
+// ---------------------------------------------------------------------------
+// thresholds config
+// ---------------------------------------------------------------------------
+
+test("loadThresholds: returns defaults when no config file present", async () => {
+  const t = await loadThresholds({ configPath: "/nonexistent/alerts.yaml" });
+  assert.equal(t.refusalSpike.warnCount, DEFAULT_THRESHOLDS.refusalSpike.warnCount);
+  assert.equal(t.daemonDown.critSec, DEFAULT_THRESHOLDS.daemonDown.critSec);
+});
+
+test("mergeThresholds: deep-merges override over defaults without mutating defaults", () => {
+  const merged = mergeThresholds(DEFAULT_THRESHOLDS, { refusalSpike: { warnCount: 1 } });
+  assert.equal(merged.refusalSpike.warnCount, 1);
+  // Sibling keys preserved.
+  assert.equal(merged.refusalSpike.critCount, DEFAULT_THRESHOLDS.refusalSpike.critCount);
+  // Defaults untouched (frozen + cloned).
+  assert.equal(DEFAULT_THRESHOLDS.refusalSpike.warnCount, 10);
+});
+
+// ---------------------------------------------------------------------------
+// internals
+// ---------------------------------------------------------------------------
+
+test("p99: nearest-rank, tolerant of junk, null on empty", () => {
+  assert.equal(_internals.p99([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]), 10);
+  assert.equal(_internals.p99([5]), 5);
+  assert.equal(_internals.p99([]), null);
+  assert.equal(_internals.p99("nope"), null);
+  assert.equal(_internals.p99([1, "x", 3, null, 2]), 3); // junk dropped → [1,2,3]
+});

package/lib/diagnostics/backup-freshness.mjs

@@ -0,0 +1,188 @@
+/**
+ * lib/diagnostics/backup-freshness.mjs — is the off-machine backup real and current?
+ *
+ * Machine-loss DR (gaps-enterprise-ops G16) starts with one honest question the
+ * operator can never answer from casual inspection: *does this agent have a
+ * backup, and how old is it?* An agent with no backup configured looks identical
+ * to a healthy one until the disk dies. `backupFreshness` collapses that question
+ * to a single, fail-open verdict that both `maestro doctor` and the alerting path
+ * (lib/diagnostics/alerts.mjs) consume — so a missing/stale backup is loud, not
+ * silent.
+ *
+ * Sources of truth (matching scripts/maintenance/backup-to-cloud.sh +
+ * scripts/setup/init-backup.mjs):
+ *   - `.maestro/backup-config.yaml`   — is backup configured + `enabled: true`?
+ *   - `.maestro/last-backup.json`     — the marker the backup driver stamps on a
+ *                                       successful run: `{ completed_at, ... }`.
+ *
+ * "Configured" means the config file exists AND `enabled: true` — an agent whose
+ * config sits at the scaffold default (`enabled: false`) is reported
+ * `configured:false` so doctor flags it, NOT silently green. "Stale" means the
+ * last successful backup is older than `staleHours` (default 48h — two missed
+ * daily runs), or there is no marker at all when backup is configured.
+ *
+ * Invariant: NEVER throws. A missing file, an unreadable marker, a malformed
+ * timestamp all degrade to a conservative verdict (`stale:true` when configured,
+ * `configured:false` when we can't even read the config) — diagnostics must not
+ * be able to crash the path that observes them, and a DR check that throws is
+ * worse than one that says "I can't tell, assume bad."
+ *
+ * Constraints (CLAUDE.md): ESM, Node built-ins only, injectable clock + paths so
+ * tests are hermetic and need no real `.maestro/` on disk.
+ *
+ * @module lib/diagnostics/backup-freshness
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/** Two missed daily runs before we call the backup stale. */
+export const DEFAULT_STALE_HOURS = 48;
+
+const MS_PER_HOUR = 3_600_000;
+
+/**
+ * Resolve the agent root the same way every other maestro module does, so the
+ * `.maestro/` markers are found wherever the agent actually lives.
+ * @param {object} [cfg]
+ * @returns {string}
+ */
+function agentRoot(cfg = {}) {
+  return resolve(
+    cfg.agentRoot ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+}
+
+/**
+ * Path to `.maestro/backup-config.yaml` (explicit override wins for tests).
+ * @param {object} cfg
+ * @returns {string}
+ */
+function configPath(cfg) {
+  if (cfg.configPath) return resolve(cfg.configPath);
+  return join(agentRoot(cfg), ".maestro", "backup-config.yaml");
+}
+
+/**
+ * Path to `.maestro/last-backup.json` (explicit override wins for tests).
+ * @param {object} cfg
+ * @returns {string}
+ */
+function markerPath(cfg) {
+  if (cfg.markerPath) return resolve(cfg.markerPath);
+  return join(agentRoot(cfg), ".maestro", "last-backup.json");
+}
+
+/**
+ * Is backup configured AND enabled? Reads `enabled:` from the YAML with a
+ * targeted regex rather than pulling in a parser — the same zero-dep, never-throw
+ * idiom lib/budget-guard.mjs uses for recovery.yaml. A missing file, an
+ * unreadable file, or `enabled: false` all → false.
+ * @param {object} cfg
+ * @returns {boolean}
+ */
+function isConfigured(cfg) {
+  const p = configPath(cfg);
+  let body;
+  try {
+    if (!existsSync(p)) return false;
+    body = readFileSync(p, "utf-8");
+  } catch {
+    return false;
+  }
+  if (typeof body !== "string") return false;
+  const m = body.match(/^\s*enabled\s*:\s*(true|false)\b/im);
+  return !!m && m[1].toLowerCase() === "true";
+}
+
+/**
+ * Read the last-backup marker's `completed_at` as epoch ms, or null if the
+ * marker is absent, unreadable, or carries no parseable timestamp.
+ * @param {object} cfg
+ * @returns {{ lastBackupAt: string|null, ms: number|null }}
+ */
+function readMarker(cfg) {
+  const p = markerPath(cfg);
+  let raw;
+  try {
+    if (!existsSync(p)) return { lastBackupAt: null, ms: null };
+    raw = readFileSync(p, "utf-8");
+  } catch {
+    return { lastBackupAt: null, ms: null };
+  }
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+  } catch {
+    return { lastBackupAt: null, ms: null };
+  }
+  if (!obj || typeof obj !== "object") return { lastBackupAt: null, ms: null };
+  const at = obj.completed_at;
+  if (typeof at !== "string") return { lastBackupAt: null, ms: null };
+  const ms = Date.parse(at);
+  if (!Number.isFinite(ms)) return { lastBackupAt: at, ms: null };
+  return { lastBackupAt: at, ms };
+}
+
+/**
+ * Report whether the off-machine backup is configured and current.
+ *
+ * @param {object} [cfg]
+ * @param {string} [cfg.agentRoot]    agent root (derives the `.maestro/` paths)
+ * @param {string} [cfg.configPath]   explicit backup-config.yaml path (tests)
+ * @param {string} [cfg.markerPath]   explicit last-backup.json path (tests)
+ * @param {number} [cfg.staleHours]   age beyond which a backup is stale (48h)
+ * @param {number} [cfg.now]          clock in epoch ms (default Date.now())
+ * @returns {{
+ *   configured: boolean,
+ *   lastBackupAt: string|null,
+ *   ageHours: number|null,
+ *   stale: boolean
+ * }}
+ */
+export function backupFreshness(cfg = {}) {
+  try {
+    const now = Number.isFinite(cfg.now) ? cfg.now : Date.now();
+    const staleHours =
+      Number.isFinite(cfg.staleHours) && cfg.staleHours > 0
+        ? cfg.staleHours
+        : DEFAULT_STALE_HOURS;
+
+    const configured = isConfigured(cfg);
+    const { lastBackupAt, ms } = readMarker(cfg);
+
+    // Age is only meaningful when we have a parseable marker timestamp.
+    const ageHours =
+      ms == null ? null : round2((now - ms) / MS_PER_HOUR);
+
+    // Stale logic:
+    //   - not configured → not "stale" (it's unconfigured; a different, louder
+    //     problem doctor reports separately) but ageHours is whatever we found.
+    //   - configured but no usable marker → stale (a backup that never ran, or
+    //     whose marker we can't read, is not a current backup).
+    //   - configured with a marker → stale iff older than the window. A
+    //     future-dated marker (clock skew) is treated as fresh, not stale.
+    let stale;
+    if (!configured) {
+      stale = false;
+    } else if (ageHours == null) {
+      stale = true;
+    } else {
+      stale = ageHours > staleHours;
+    }
+
+    return { configured, lastBackupAt, ageHours, stale };
+  } catch {
+    // Never throw: degrade to the conservative "I can't tell, assume bad" shape.
+    return { configured: false, lastBackupAt: null, ageHours: null, stale: true };
+  }
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+export default { backupFreshness, DEFAULT_STALE_HOURS };

package/lib/diagnostics/backup-freshness.test.mjs

@@ -0,0 +1,185 @@
+/**
+ * backup-freshness.test.mjs — coverage for lib/diagnostics/backup-freshness.mjs.
+ *
+ * Hermetic: every case builds a tmp `.maestro/` fixture (config + marker) and
+ * injects `now`, so no real backup machinery runs. Verifies the configured /
+ * stale / ageHours verdict for the cases doctor + alerting depend on.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { backupFreshness, DEFAULT_STALE_HOURS } from "./backup-freshness.mjs";
+
+const HOUR = 3_600_000;
+
+/** Build a tmp agent root with optional backup-config.yaml + last-backup.json. */
+function makeAgent({ configBody, marker } = {}) {
+  const root = mkdtempSync(join(tmpdir(), "bf-test-"));
+  mkdirSync(join(root, ".maestro"), { recursive: true });
+  if (configBody !== undefined) {
+    writeFileSync(join(root, ".maestro", "backup-config.yaml"), configBody);
+  }
+  if (marker !== undefined) {
+    writeFileSync(
+      join(root, ".maestro", "last-backup.json"),
+      typeof marker === "string" ? marker : JSON.stringify(marker)
+    );
+  }
+  return root;
+}
+
+function cleanup(root) {
+  rmSync(root, { recursive: true, force: true });
+}
+
+test("unconfigured (no files) → configured:false, not stale, no age", () => {
+  const root = makeAgent();
+  try {
+    const r = backupFreshness({ agentRoot: root, now: Date.now() });
+    assert.equal(r.configured, false);
+    assert.equal(r.stale, false);
+    assert.equal(r.lastBackupAt, null);
+    assert.equal(r.ageHours, null);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("scaffold default (enabled: false) → configured:false", () => {
+  const root = makeAgent({ configBody: "enabled: false\nprovider: gcs\n" });
+  try {
+    const r = backupFreshness({ agentRoot: root });
+    assert.equal(r.configured, false);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("enabled: true with a fresh marker → configured, not stale, age computed", () => {
+  const now = Date.parse("2026-06-11T12:00:00Z");
+  const completed_at = new Date(now - 6 * HOUR).toISOString(); // 6h ago
+  const root = makeAgent({
+    configBody: "enabled: true\nprovider: gcs\nbucket: x\nprefix: y\n",
+    marker: { completed_at, provider: "gcs", size_bytes: 1234 },
+  });
+  try {
+    const r = backupFreshness({ agentRoot: root, now });
+    assert.equal(r.configured, true);
+    assert.equal(r.stale, false);
+    assert.equal(r.lastBackupAt, completed_at);
+    assert.equal(r.ageHours, 6);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("enabled with a marker older than the window → stale", () => {
+  const now = Date.parse("2026-06-11T12:00:00Z");
+  const completed_at = new Date(now - 72 * HOUR).toISOString(); // 72h ago > 48h default
+  const root = makeAgent({
+    configBody: "enabled: true\n",
+    marker: { completed_at },
+  });
+  try {
+    const r = backupFreshness({ agentRoot: root, now });
+    assert.equal(r.configured, true);
+    assert.equal(r.ageHours, 72);
+    assert.equal(r.stale, true);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("stale boundary: exactly at staleHours is fresh; just over is stale", () => {
+  const now = Date.parse("2026-06-11T12:00:00Z");
+  const atBoundary = new Date(now - DEFAULT_STALE_HOURS * HOUR).toISOString();
+  const overBoundary = new Date(now - (DEFAULT_STALE_HOURS * HOUR + 60_000)).toISOString();
+  const rootA = makeAgent({ configBody: "enabled: true\n", marker: { completed_at: atBoundary } });
+  const rootB = makeAgent({ configBody: "enabled: true\n", marker: { completed_at: overBoundary } });
+  try {
+    assert.equal(backupFreshness({ agentRoot: rootA, now }).stale, false, "exactly at window is fresh");
+    assert.equal(backupFreshness({ agentRoot: rootB, now }).stale, true, "just over window is stale");
+  } finally {
+    cleanup(rootA);
+    cleanup(rootB);
+  }
+});
+
+test("custom staleHours is honoured", () => {
+  const now = Date.parse("2026-06-11T12:00:00Z");
+  const completed_at = new Date(now - 10 * HOUR).toISOString();
+  const root = makeAgent({ configBody: "enabled: true\n", marker: { completed_at } });
+  try {
+    // 10h old: stale under an 8h window, fresh under the 48h default.
+    assert.equal(backupFreshness({ agentRoot: root, now, staleHours: 8 }).stale, true);
+    assert.equal(backupFreshness({ agentRoot: root, now }).stale, false);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("configured but NO marker → stale (a backup that never ran)", () => {
+  const root = makeAgent({ configBody: "enabled: true\n" });
+  try {
+    const r = backupFreshness({ agentRoot: root, now: Date.now() });
+    assert.equal(r.configured, true);
+    assert.equal(r.lastBackupAt, null);
+    assert.equal(r.ageHours, null);
+    assert.equal(r.stale, true);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("configured with a corrupt marker → stale, not a throw", () => {
+  const root = makeAgent({ configBody: "enabled: true\n", marker: "{not json" });
+  try {
+    const r = backupFreshness({ agentRoot: root, now: Date.now() });
+    assert.equal(r.configured, true);
+    assert.equal(r.lastBackupAt, null);
+    assert.equal(r.stale, true);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("future-dated marker (clock skew) is treated as fresh, not stale", () => {
+  const now = Date.parse("2026-06-11T12:00:00Z");
+  const completed_at = new Date(now + 2 * HOUR).toISOString(); // 2h in the future
+  const root = makeAgent({ configBody: "enabled: true\n", marker: { completed_at } });
+  try {
+    const r = backupFreshness({ agentRoot: root, now });
+    assert.equal(r.stale, false);
+    assert.ok(r.ageHours < 0, "negative age for a future marker");
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("explicit configPath + markerPath overrides agentRoot", () => {
+  const now = Date.parse("2026-06-11T12:00:00Z");
+  const root = mkdtempSync(join(tmpdir(), "bf-explicit-"));
+  const cfg = join(root, "cfg.yaml");
+  const mk = join(root, "marker.json");
+  writeFileSync(cfg, "enabled: true\n");
+  writeFileSync(mk, JSON.stringify({ completed_at: new Date(now - HOUR).toISOString() }));
+  try {
+    const r = backupFreshness({ configPath: cfg, markerPath: mk, now });
+    assert.equal(r.configured, true);
+    assert.equal(r.ageHours, 1);
+    assert.equal(r.stale, false);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("never throws on a totally bogus cfg", () => {
+  assert.doesNotThrow(() => backupFreshness(null));
+  assert.doesNotThrow(() => backupFreshness({ agentRoot: 42, now: "x" }));
+  const r = backupFreshness({ configPath: 12345 });
+  assert.equal(typeof r.configured, "boolean");
+});