@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/kpi.test.mjs

@@ -0,0 +1,244 @@
+/**
+ * kpi.test.mjs — measurement, the series, and the gap.
+ * Run: `node --test lib/kpi.test.mjs`
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  windowFor,
+  isoWeek,
+  isDue,
+  readSeries,
+  recordMeasurement,
+  recordIntervention,
+  readInterventions,
+  measureKpi,
+  gapFor,
+  periodSeconds,
+} from "./kpi.mjs";
+
+function root() {
+  return mkdtempSync(join(tmpdir(), "kpi-test-"));
+}
+function cleanup(p) {
+  try { rmSync(p, { recursive: true, force: true }); } catch { /* */ }
+}
+
+const T = Date.parse("2026-08-11T09:00:00Z"); // a Tuesday, ISO week 33
+const now = () => T;
+
+const OBJ = {
+  key: "pipeline",
+  metric: "pipeline_coverage_x",
+  target: 3,
+  tolerance: 0.2,
+  direction: "up",
+  cadence: "weekly",
+  sensor: { capability: "crm_list_deals", params: { stage: "open" }, source: "method" },
+};
+
+// ---------------------------------------------------------------------------
+// windows
+// ---------------------------------------------------------------------------
+
+test("windowFor produces the right idempotency key per cadence", () => {
+  assert.equal(windowFor("weekly", T), "2026-W33");
+  assert.equal(windowFor("monthly", T), "2026-08");
+  assert.equal(windowFor("quarterly", T), "2026-Q3");
+  assert.equal(windowFor("daily", T), "2026-08-11");
+  assert.equal(isoWeek(new Date(T)).week, 33);
+});
+
+test("periodSeconds covers every cadence and defaults to a day", () => {
+  assert.equal(periodSeconds("weekly"), 604800);
+  assert.equal(periodSeconds("monthly"), 2592000);
+  assert.equal(periodSeconds("nonsense"), 86400);
+});
+
+// ---------------------------------------------------------------------------
+// the ledger
+// ---------------------------------------------------------------------------
+
+test("recordMeasurement is idempotent on (objective, window) and refuses a weaker duplicate", () => {
+  const r = root();
+  try {
+    const a = recordMeasurement(r, { objectiveKey: "pipeline", value: 2.1, window: "2026-W33", source: "method" }, { now });
+    assert.equal(a.recorded, true);
+
+    const dup = recordMeasurement(r, { objectiveKey: "pipeline", value: 9.9, window: "2026-W33", source: "llm" }, { now });
+    assert.equal(dup.recorded, false);
+    assert.equal(dup.reason, "duplicate-window");
+    assert.equal(readSeries(r, "pipeline")[0].value, 2.1, "the llm guess must not overwrite the measured number");
+
+    // A STRONGER source may supersede a weaker one in the same window.
+    const r2 = root();
+    try {
+      recordMeasurement(r2, { objectiveKey: "p", value: 1, window: "w", source: "llm" }, { now });
+      const better = recordMeasurement(r2, { objectiveKey: "p", value: 5, window: "w", source: "method" }, { now });
+      assert.equal(better.recorded, true);
+      assert.equal(readSeries(r2, "p")[0].value, 5);
+      assert.equal(readSeries(r2, "p").length, 1, "the window collapses to the strongest source");
+    } finally { cleanup(r2); }
+  } finally { cleanup(r); }
+});
+
+test("recordMeasurement refuses a non-numeric value and logs it", () => {
+  const r = root();
+  const logs = [];
+  try {
+    const res = recordMeasurement(r, { objectiveKey: "p", value: "banana", window: "w", source: "method" }, { now, log: (l, m) => logs.push(`${l}:${m}`) });
+    assert.equal(res.recorded, false);
+    assert.equal(res.reason, "non-numeric value");
+    assert.equal(logs.length, 1, "a refusal is never silent");
+  } finally { cleanup(r); }
+});
+
+test("interventions are the learning signal and read back newest-last", () => {
+  const r = root();
+  try {
+    for (const d of [-1, 0.5, 2]) {
+      recordIntervention(r, { objectiveKey: "pipeline", taskId: `t${d}`, expectedDelta: 1, realizedDelta: d }, { now });
+    }
+    const last2 = readInterventions(r, "pipeline", 2);
+    assert.deepEqual(last2.map((i) => i.realizedDelta), [0.5, 2]);
+  } finally { cleanup(r); }
+});
+
+test("isDue opens once per window and closes after a sample; no cadence is never due", () => {
+  const r = root();
+  try {
+    assert.equal(isDue(OBJ, [], { now }).due, true);
+    recordMeasurement(r, { objectiveKey: "pipeline", value: 2, window: "2026-W33", source: "method" }, { now });
+    assert.equal(isDue(OBJ, readSeries(r, "pipeline"), { now }).due, false);
+    const none = isDue({ ...OBJ, cadence: null }, [], { now });
+    assert.equal(none.due, false);
+    assert.match(none.reason, /no measure cadence/);
+  } finally { cleanup(r); }
+});
+
+// ---------------------------------------------------------------------------
+// measurement — the negative cases matter most
+// ---------------------------------------------------------------------------
+
+test("measureKpi executes a registered sensor and stamps method-sourced evidence", async () => {
+  const seen = [];
+  const m = await measureKpi(OBJ, {
+    sensors: { crm_list_deals: async ({ params }) => { seen.push(params); return { value: 2.4, rowCount: 17 }; } },
+    reachable: new Set(["crm_list_deals"]),
+  });
+  assert.equal(m.ok, true);
+  assert.equal(m.value, 2.4);
+  assert.equal(m.source, "method");
+  assert.equal(m.evidence.method, "crm_list_deals");
+  assert.equal(m.evidence.rowCount, 17);
+  assert.deepEqual(seen, [{ stage: "open" }]);
+});
+
+test("NEGATIVE — an unreachable capability refuses to measure rather than recording a zero", async () => {
+  const logs = [];
+  const m = await measureKpi(OBJ, {
+    sensors: { crm_list_deals: async () => 2.4 },
+    reachable: new Set(["something_else"]),
+    log: (l, msg) => logs.push(msg),
+  });
+  assert.equal(m.ok, false);
+  assert.equal(m.reason, "unreachable-capability");
+  assert.equal(m.value, null);
+  assert.match(logs.join(" "), /NOT reachable/);
+});
+
+test("NEGATIVE — a missing sensor implementation, a throwing sensor and a non-numeric result all fail loudly", async () => {
+  const logs = [];
+  const log = (l, msg) => logs.push(msg);
+
+  const missing = await measureKpi(OBJ, { sensors: {}, reachable: new Set(["crm_list_deals"]), log });
+  assert.equal(missing.reason, "no-implementation");
+
+  const threw = await measureKpi(OBJ, {
+    sensors: { crm_list_deals: async () => { throw new Error("server unreachable"); } },
+    reachable: new Set(["crm_list_deals"]),
+    log,
+  });
+  assert.equal(threw.reason, "sensor-threw");
+
+  const junk = await measureKpi(OBJ, {
+    sensors: { crm_list_deals: async () => ({ value: "n/a" }) },
+    reachable: new Set(["crm_list_deals"]),
+    log,
+  });
+  assert.equal(junk.reason, "non-numeric");
+  assert.equal(logs.length, 3, "every degradation is logged");
+});
+
+test("an objective with a human sensor is not an error — it is a human obligation", async () => {
+  const m = await measureKpi({ ...OBJ, sensor: { capability: null, source: "human" } }, { sensors: {} });
+  assert.equal(m.ok, false);
+  assert.equal(m.reason, "no-sensor");
+  assert.equal(m.source, "human");
+});
+
+// ---------------------------------------------------------------------------
+// the gap
+// ---------------------------------------------------------------------------
+
+function series(values, cadence = "weekly", at = "2026-08-11T09:00:00Z") {
+  return values.map((v, i) => ({ objectiveKey: "pipeline", value: v, window: `w${i}`, at, source: "method" }));
+}
+
+test("gapFor honours direction: up is a shortfall, down is an excess", () => {
+  const up = gapFor(OBJ, series([2.0]), { now });
+  assert.equal(up.gap, 1);
+  assert.equal(up.withinTolerance, false);
+  assert.equal(up.normalizedGap, +(1 / 3).toFixed(6));
+
+  const down = gapFor({ ...OBJ, direction: "down", target: 5 }, series([7]), { now });
+  assert.equal(down.gap, 2, "for a down metric, above target is the gap");
+
+  const under = gapFor({ ...OBJ, direction: "down", target: 5 }, series([3]), { now });
+  assert.equal(under.gap, -2);
+  assert.equal(under.withinTolerance, true, "beating a down-target is not a gap");
+});
+
+test("gapFor honours tolerance and band direction", () => {
+  const inTol = gapFor(OBJ, series([2.85]), { now });
+  assert.ok(inTol.gap <= 0.2 && inTol.withinTolerance, "0.15 short of 3 is inside a 0.2 tolerance");
+
+  const band = gapFor({ ...OBJ, direction: "band", target: 10, tolerance: 2 }, series([13]), { now });
+  assert.equal(band.gap, 1, "a band gap is the distance outside the band");
+  const inBand = gapFor({ ...OBJ, direction: "band", target: 10, tolerance: 2 }, series([11]), { now });
+  assert.equal(inBand.gap, 0);
+});
+
+test("gapFor computes a real trend over the gap, not the raw value", () => {
+  assert.equal(gapFor(OBJ, series([1.0, 1.8, 2.5]), { now }).trend, "improving");
+  assert.equal(gapFor(OBJ, series([2.5, 1.8, 1.0]), { now }).trend, "worsening");
+  assert.equal(gapFor(OBJ, series([2.0, 2.0, 2.0]), { now }).trend, "flat");
+  assert.equal(gapFor(OBJ, series([2.0]), { now }).trend, "unknown");
+});
+
+test("NEGATIVE — no samples, and no target, both report rather than compute", () => {
+  const none = gapFor(OBJ, [], { now });
+  assert.equal(none.gap, null);
+  assert.equal(none.reason, "no samples");
+
+  const noTarget = gapFor({ ...OBJ, target: null }, series([2]), { now });
+  assert.equal(noTarget.gap, null);
+  assert.match(noTarget.reason, /no numeric target/);
+  assert.equal(noTarget.target, null, "a null target must never coerce to 0");
+});
+
+test("a sensor silent for 2× its cadence is itself a gap", () => {
+  const stale = gapFor(OBJ, series([2], "weekly", "2026-07-01T09:00:00Z"), { now });
+  assert.equal(stale.stale, true);
+  assert.ok(stale.stalenessPeriods > 2);
+
+  const fresh = gapFor(OBJ, series([2], "weekly", "2026-08-10T09:00:00Z"), { now });
+  assert.equal(fresh.stale, false);
+});

package/lib/mandate/audit.mjs

@@ -0,0 +1,168 @@
+/**
+ * lib/mandate/audit.mjs — one audit line for every autonomous decision.
+ *
+ * The question this file exists to answer, offline, from local state alone:
+ * **"why did the agent do that?"** Every decision the goal loop makes — a
+ * measurement taken, a gap computed, a candidate admitted or REJECTED, a
+ * disposition chosen, an execution rung picked, a budget refusal, an approval
+ * gate — appends exactly one line here, carrying the provenance chain back to
+ * the pillar and the human who adopted the objective.
+ *
+ * Rejections are recorded with the same weight as admissions. A candidate that
+ * is silently dropped is indistinguishable from a bug — the recurring failure
+ * mode this codebase keeps rediscovering.
+ *
+ * Append-only JSONL, atomic append, never throws. When an org mirror is
+ * injected it is called best-effort AFTER the local write, so an unreachable
+ * server never loses the local audit line.
+ *
+ * Not to be confused with `lib/execution/journal.mjs`, which is the REACTIVE
+ * lane's ledger: it is keyed on inbound dedupe/thread keys and is scan-capped
+ * for flood detection. This ledger is keyed on `objectiveKey`/`obligationKey`
+ * and is never truncated, because it is the provenance record a human reads
+ * when asking why a goal produced a task. Different key space, different
+ * retention, deliberately separate files.
+ *
+ * @module lib/mandate/audit
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+import { resolveAgentRoot } from "../agent-root.mjs";
+import { appendJsonl } from "../fs-atomic.mjs";
+import { provenanceOf } from "./model.mjs";
+
+export const AUDIT_REL = join("state", "mandate", "audit.jsonl");
+
+/** Decision kinds that may appear on an audit line. */
+export const DECISIONS = Object.freeze([
+  "measured",
+  "measure_failed",
+  "gap",
+  "candidate_admitted",
+  "candidate_rejected",
+  "disposition",
+  "routed",
+  "route_failed",
+  "execution_rung",
+  "budget_refused",
+  "approval_gate",
+  "drift",
+  "observe_only",
+  "mandate_refreshed",
+]);
+
+/** Absolute path of the audit ledger. */
+export function auditPath(agentRoot) {
+  return join(resolveAgentRoot(agentRoot), AUDIT_REL);
+}
+
+function nowIso(deps) {
+  return new Date(deps && typeof deps.now === "function" ? deps.now() : Date.now()).toISOString();
+}
+
+/**
+ * Build the provenance block for an objective key: the chain of keys up to the
+ * pillar, the charter clause, and who adopted it. Delegates to
+ * `model.provenanceOf` — the walk has exactly one implementation. Pure; offline.
+ *
+ * @param {object|object[]} mandate  cache record, body, or objective array
+ * @param {string} objectiveKey
+ * @returns {{chain:string[], pillar:string|null, clause:string|null, adoptedBy:string|null, origin:string|null}}
+ */
+export function provenanceFor(mandate, objectiveKey) {
+  return provenanceOf(mandate, objectiveKey);
+}
+
+/**
+ * Append one audit line. Never throws.
+ *
+ * @param {string} agentRoot
+ * @param {object} record - { decision, objectiveKey?, obligationKey?, detail?, … }
+ * @param {object} [deps] { now, mandate?, mirror?, log? }
+ * @returns {object} the written record (with `at` + `provenance` stamped)
+ */
+export function recordDecision(agentRoot, record, deps = {}) {
+  const rec = {
+    at: nowIso(deps),
+    decision: String((record && record.decision) || "unknown"),
+    objectiveKey: (record && record.objectiveKey) || null,
+    obligationKey: (record && record.obligationKey) || null,
+    ...record,
+  };
+  if (!DECISIONS.includes(rec.decision) && typeof deps.log === "function") {
+    deps.log("warn", `[mandate-audit] unrecognised decision kind "${rec.decision}" — recorded anyway`);
+  }
+  if (deps.mandate && rec.objectiveKey) {
+    rec.provenance = provenanceFor(deps.mandate, rec.objectiveKey);
+  }
+  try {
+    const p = auditPath(agentRoot);
+    mkdirSync(dirname(p), { recursive: true });
+    appendJsonl(p, rec);
+  } catch (err) {
+    if (typeof deps.log === "function") {
+      deps.log("error", `[mandate-audit] could not append audit line: ${err && err.message ? err.message : err}`);
+    }
+  }
+  if (typeof deps.mirror === "function") {
+    try {
+      const r = deps.mirror(rec);
+      if (r && typeof r.catch === "function") {
+        r.catch((err) => {
+          if (typeof deps.log === "function") {
+            deps.log("warn", `[mandate-audit] org mirror failed (local line is intact): ${err && err.message ? err.message : err}`);
+          }
+        });
+      }
+    } catch (err) {
+      if (typeof deps.log === "function") {
+        deps.log("warn", `[mandate-audit] org mirror threw (local line is intact): ${err && err.message ? err.message : err}`);
+      }
+    }
+  }
+  return rec;
+}
+
+/**
+ * Read audit lines back (newest last). Never throws; malformed lines skipped.
+ * @param {string} agentRoot @param {{limit?:number, decision?:string, objectiveKey?:string}} [q]
+ * @returns {object[]}
+ */
+export function readAudit(agentRoot, q = {}) {
+  const p = auditPath(agentRoot);
+  if (!existsSync(p)) return [];
+  let body;
+  try { body = readFileSync(p, "utf-8"); } catch { return []; }
+  const out = [];
+  for (const line of body.split("\n")) {
+    if (!line.trim()) continue;
+    let rec;
+    try { rec = JSON.parse(line); } catch { continue; }
+    if (q.decision && rec.decision !== q.decision) continue;
+    if (q.objectiveKey && rec.objectiveKey !== q.objectiveKey) continue;
+    out.push(rec);
+  }
+  return Number.isFinite(q.limit) && q.limit > 0 ? out.slice(-q.limit) : out;
+}
+
+/**
+ * The offline "why did the agent do that?" answer for one objective: its
+ * provenance chain plus every decision taken against it. Needs no network —
+ * this is the client-side half of the audit story (the server-side half is a
+ * chain query joining Task.obligationKey → AgentPlanDigest → Objective).
+ * @param {string} agentRoot @param {object|object[]} mandate @param {string} objectiveKey
+ * @returns {{objectiveKey:string, provenance:object, decisions:object[]}}
+ */
+export function explain(agentRoot, mandate, objectiveKey) {
+  return {
+    objectiveKey,
+    provenance: provenanceFor(mandate, objectiveKey),
+    decisions: readAudit(agentRoot, { objectiveKey }),
+  };
+}
+
+export default { AUDIT_REL, DECISIONS, auditPath, provenanceFor, recordDecision, readAudit, explain };

package/lib/mandate/audit.test.mjs

@@ -0,0 +1,195 @@
+/**
+ * lib/mandate/audit.test.mjs — an audit line for every autonomous decision.
+ *
+ * The governance question this answers is "why did the agent do that?", and it
+ * has to be answerable OFFLINE, from the ledger plus the cached mandate alone.
+ * Every line therefore carries its own provenance walk: objective → pillar →
+ * charter clause → who adopted it.
+ *
+ * The failure mode being guarded against is the one this codebase keeps hitting:
+ * a decision that happens but leaves no trace. So the ledger never throws, never
+ * drops a line for an unrecognised decision kind, and logs when the org mirror
+ * fails rather than pretending it succeeded.
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { recordDecision, readAudit, explain, provenanceFor, auditPath, DECISIONS, AUDIT_REL } from "./audit.mjs";
+
+const NOW = Date.parse("2026-08-11T09:00:00.000Z");
+
+const MANDATE = {
+  body: {
+    memberId: "mem_self",
+    objectives: [
+      { key: "revenue", kind: "PILLAR", state: "active", charterSectionId: "cs_12", adoptedById: "mem_boss" },
+      {
+        key: "pipeline", kind: "OBJECTIVE", parentKey: "revenue", state: "active",
+        metric: "pipeline_coverage_x", target: 3, adoptedById: "mem_boss",
+      },
+    ],
+  },
+};
+
+function makeRoot() { return mkdtempSync(join(tmpdir(), "mandate-audit-")); }
+function cleanup(root) { try { rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ } }
+function lines(root) {
+  return readFileSync(auditPath(root), "utf-8").trim().split("\n").map((l) => JSON.parse(l));
+}
+
+test("every decision kind the loop emits is in the declared vocabulary", () => {
+  // If the loop grows a decision the ledger has never heard of, that is a
+  // review signal, not a silent write.
+  for (const d of [
+    "measured", "measure_failed", "gap", "candidate_admitted", "candidate_rejected",
+    "disposition", "routed", "route_failed", "execution_rung", "budget_refused",
+    "approval_gate", "drift", "observe_only",
+  ]) {
+    assert.ok(DECISIONS.includes(d), `"${d}" must be a declared decision kind`);
+  }
+});
+
+test("a decision line stamps time, kind, and the full provenance chain", () => {
+  const root = makeRoot();
+  try {
+    const rec = recordDecision(
+      root,
+      { decision: "candidate_admitted", objectiveKey: "pipeline", obligationKey: "outcome.pipeline", detail: { title: "Book calls" } },
+      { now: () => NOW, mandate: MANDATE }
+    );
+    assert.equal(rec.at, new Date(NOW).toISOString());
+    assert.equal(rec.decision, "candidate_admitted");
+    assert.equal(rec.obligationKey, "outcome.pipeline");
+    // The offline "why" walk.
+    assert.deepEqual(rec.provenance.chain, ["pipeline", "revenue"]);
+    assert.equal(rec.provenance.pillar, "revenue");
+    assert.equal(rec.provenance.clause, "cs_12");
+    assert.equal(rec.provenance.adoptedBy, "mem_boss");
+
+    assert.equal(lines(root).length, 1);
+    assert.equal(lines(root)[0].provenance.clause, "cs_12");
+  } finally { cleanup(root); }
+});
+
+test("the ledger is append-only and read back oldest-first", () => {
+  const root = makeRoot();
+  try {
+    for (const d of ["measured", "gap", "candidate_admitted"]) {
+      recordDecision(root, { decision: d, objectiveKey: "pipeline" }, { now: () => NOW, mandate: MANDATE });
+    }
+    const all = readAudit(root);
+    assert.deepEqual(all.map((a) => a.decision), ["measured", "gap", "candidate_admitted"]);
+    assert.equal(readAudit(root, { decision: "gap" }).length, 1);
+    assert.equal(readAudit(root, { objectiveKey: "pipeline" }).length, 3);
+    assert.equal(readAudit(root, { objectiveKey: "nope" }).length, 0);
+    assert.equal(readAudit(root, { limit: 2 }).length, 2);
+  } finally { cleanup(root); }
+});
+
+test("an UNRECOGNISED decision kind is recorded anyway, with a warning", () => {
+  const root = makeRoot();
+  try {
+    const logs = [];
+    recordDecision(root, { decision: "invented_kind" }, { now: () => NOW, log: (l, m) => logs.push(`${l}:${m}`) });
+    // Recorded — dropping it would be the silent failure.
+    assert.equal(lines(root).length, 1);
+    assert.equal(lines(root)[0].decision, "invented_kind");
+    // …but loudly.
+    assert.ok(logs.some((l) => l.startsWith("warn:") && /unrecognised decision kind/.test(l)));
+  } finally { cleanup(root); }
+});
+
+test("a decision with no objective still records — provenance is optional, the line is not", () => {
+  const root = makeRoot();
+  try {
+    recordDecision(root, { decision: "drift", detail: { kind: "mandate_stale" } }, { now: () => NOW });
+    const [rec] = lines(root);
+    assert.equal(rec.objectiveKey, null);
+    assert.equal(rec.provenance, undefined);
+    assert.equal(rec.detail.kind, "mandate_stale");
+  } finally { cleanup(root); }
+});
+
+test("readAudit tolerates a malformed line rather than losing the whole ledger", () => {
+  const root = makeRoot();
+  try {
+    recordDecision(root, { decision: "gap", objectiveKey: "pipeline" }, { now: () => NOW, mandate: MANDATE });
+    // Simulate a torn write.
+    const p = auditPath(root);
+    const body = readFileSync(p, "utf-8");
+    writeFileSync(p, body + "{ this is not json\n");
+    recordDecision(root, { decision: "measured", objectiveKey: "pipeline" }, { now: () => NOW, mandate: MANDATE });
+    const all = readAudit(root);
+    assert.equal(all.length, 2, "the readable lines must survive one corrupt line");
+  } finally { cleanup(root); }
+});
+
+test("an unwritable ledger logs and returns — it never throws into the agent loop", () => {
+  const logs = [];
+  // A path that cannot be created.
+  const rec = recordDecision("/proc/nonexistent-root-xyz", { decision: "gap" }, {
+    now: () => NOW,
+    log: (l, m) => logs.push(`${l}:${m}`),
+  });
+  assert.equal(rec.decision, "gap", "the caller still gets its record back");
+  assert.ok(logs.some((l) => l.startsWith("error:")), "an unwritable ledger must be reported");
+});
+
+test("a FAILING org mirror never costs the local line, and is logged", async () => {
+  const root = makeRoot();
+  try {
+    const logs = [];
+    recordDecision(root, { decision: "gap", objectiveKey: "pipeline" }, {
+      now: () => NOW, mandate: MANDATE,
+      mirror: () => { throw new Error("ECONNREFUSED"); },
+      log: (l, m) => logs.push(`${l}:${m}`),
+    });
+    assert.equal(lines(root).length, 1, "the local line is intact even when hq is unreachable");
+    assert.ok(logs.some((l) => /mirror threw/.test(l)));
+
+    // …and the async rejection path too.
+    recordDecision(root, { decision: "gap", objectiveKey: "pipeline" }, {
+      now: () => NOW, mandate: MANDATE,
+      mirror: async () => { throw new Error("502"); },
+      log: (l, m) => logs.push(`${l}:${m}`),
+    });
+    await new Promise((r) => setTimeout(r, 10));
+    assert.equal(lines(root).length, 2);
+    assert.ok(logs.some((l) => /mirror failed/.test(l)));
+  } finally { cleanup(root); }
+});
+
+test("provenanceFor and explain answer 'why did the agent do that' offline", () => {
+  const root = makeRoot();
+  try {
+    const prov = provenanceFor(MANDATE, "pipeline");
+    assert.equal(prov.clause, "cs_12");
+    assert.equal(prov.adoptedBy, "mem_boss");
+
+    recordDecision(root, { decision: "candidate_admitted", objectiveKey: "pipeline" }, { now: () => NOW, mandate: MANDATE });
+    recordDecision(root, { decision: "routed", objectiveKey: "pipeline" }, { now: () => NOW, mandate: MANDATE });
+    recordDecision(root, { decision: "gap", objectiveKey: "other" }, { now: () => NOW, mandate: MANDATE });
+
+    const e = explain(root, MANDATE, "pipeline");
+    assert.equal(e.provenance.clause, "cs_12");
+    assert.equal(e.decisions.length, 2, "explain must scope to the objective asked about");
+  } finally { cleanup(root); }
+});
+
+test("an unknown objective key degrades to a null chain, not a throw", () => {
+  const prov = provenanceFor(MANDATE, "does-not-exist");
+  assert.deepEqual(prov.chain, []);
+  assert.equal(prov.clause, null);
+});
+
+test("the ledger path is the documented one", () => {
+  assert.equal(AUDIT_REL, join("state", "mandate", "audit.jsonl"));
+  assert.ok(auditPath("/tmp/x").endsWith(AUDIT_REL));
+  assert.equal(existsSync(join("/tmp/definitely-not-here", AUDIT_REL)), false);
+});