@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/execution/journal.mjs

@@ -0,0 +1,374 @@
+/**
+ * lib/execution/journal.mjs — the append-only record of "why did the agent do
+ * that?", and the memory the decision ladder consults to avoid doing it twice.
+ *
+ * Two jobs, deliberately in one module because they are the same file:
+ *
+ *  1. WRITE. Every decision — including every `ignore` — is appended to
+ *     `state/execution/journal.jsonl` with the ordered rule trace that produced
+ *     it. An ignore that leaves no trace is indistinguishable from a crash, and
+ *     "the agent silently did nothing" has been the hardest class of bug in this
+ *     system to diagnose. So the ignore path writes MORE, not less.
+ *
+ *  2. READ. The ladder needs three facts that only history can answer:
+ *       - have I already handled this exact event?           (idempotency)
+ *       - how many turns have I taken in this thread with no
+ *         human in between?                                  (ping-pong guard)
+ *       - how many times has this actor woken me lately?      (flood guard)
+ *     All three are derived from the same tail scan, so one bounded read of the
+ *     file answers all of them.
+ *
+ * The file is read TAIL-FIRST and bounded (`MAX_SCAN_BYTES`, `MAX_SCAN_ROWS`) so
+ * a long-lived agent's journal cannot turn a per-event decision into an O(file)
+ * operation. A journal older than the scan window simply stops contributing to
+ * the guards — which is correct: a reply chain from three weeks ago is not a
+ * ping-pong loop.
+ *
+ * Every failure is soft (returns an empty view) but NEVER silent: the caller
+ * gets `{degraded, degradedReason}` and is expected to log it.
+ *
+ * @module lib/execution/journal
+ */
+
+"use strict";
+
+import { existsSync, openSync, readSync, fstatSync, closeSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveAgentRoot } from "../agent-root.mjs";
+import { appendJsonl } from "../fs-atomic.mjs";
+
+/** Journal path relative to the agent root. */
+export const JOURNAL_REL = "state/execution/journal.jsonl";
+
+/** Never read more than this much of the tail for a guard query. */
+export const MAX_SCAN_BYTES = 512 * 1024;
+
+/** Never consider more than this many rows, even inside the byte budget. */
+export const MAX_SCAN_ROWS = 2000;
+
+/** Default flood window: how far back `actorActivity` looks. */
+export const DEFAULT_FLOOD_WINDOW_MS = 15 * 60 * 1000;
+
+/** Default idempotency window: how far back a duplicate still counts as one. */
+export const DEFAULT_DEDUPE_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/** Absolute path to the journal for an agent root. */
+export function journalPath(agentRoot) {
+  return join(resolveAgentRoot(agentRoot), JOURNAL_REL);
+}
+
+/**
+ * The idempotency key for one inbound event. Stable across restarts and across
+ * the two delivery paths (SSE push and the polling sweep), which is the whole
+ * point: the same event arriving twice by two routes must collapse to one key.
+ *
+ * `seq` is preferred when the ledger supplied one — it is the org-wide cursor
+ * and cannot collide. Falling back to `entityId` alone would collapse DISTINCT
+ * events on the same entity (two comments on one task), so the fallback carries
+ * the coordinates and the timestamp too.
+ *
+ * @param {{seq?:number|string|null, family?:string, kind?:string, entityId?:string|null, at?:string}} cand
+ * @returns {string}
+ */
+export function dedupeKey(cand = {}) {
+  // A default parameter fires only on `undefined`. These two helpers are called
+  // on the live inbound path with whatever the classifier produced, so an
+  // explicit `null` must degrade to a placeholder key, not throw.
+  if (!cand || typeof cand !== "object") cand = {};
+  const family = String(cand.family || "?");
+  const kind = String(cand.kind || "?");
+  if (cand.seq !== undefined && cand.seq !== null && cand.seq !== "") {
+    return `${family}.${kind}#${cand.seq}`;
+  }
+  const entity = String(cand.entityId || "-");
+  const at = String(cand.at || "-");
+  return `${family}.${kind}:${entity}@${at}`;
+}
+
+/**
+ * The thread identity a ping-pong guard counts turns within. A board comment
+ * thread, a chat thread and an email thread are all "a conversation" and all
+ * need the same guard, so they normalise onto one key space.
+ *
+ * @param {{family?:string, ids?:Record<string,string|undefined>, entityId?:string|null}} cand
+ * @returns {string}
+ */
+export function threadKey(cand = {}) {
+  if (!cand || typeof cand !== "object") cand = {};
+  const ids = (cand.ids && typeof cand.ids === "object") ? cand.ids : {};
+  const family = String(cand.family || "?");
+  const thread =
+    ids.threadRootId ||
+    ids.threadId ||
+    ids.messageId ||
+    ids.taskId ||
+    ids.callId ||
+    ids.fileId ||
+    cand.entityId ||
+    "-";
+  const room = ids.channelId || ids.boardId || "-";
+  return `${family}:${room}:${thread}`;
+}
+
+/**
+ * Read the tail of the journal as parsed rows, newest LAST (file order).
+ * Bounded by bytes and rows. Never throws.
+ *
+ * @param {object} [o]
+ * @param {string} [o.agentRoot]
+ * @param {number} [o.maxBytes]
+ * @param {number} [o.maxRows]
+ * @returns {{rows:object[], degraded:boolean, degradedReason:string|null, truncated:boolean}}
+ */
+export function readTail(o = {}) {
+  const path = o.path || journalPath(o.agentRoot);
+  if (!existsSync(path)) {
+    return { rows: [], degraded: false, degradedReason: null, truncated: false };
+  }
+  const maxBytes = Number.isFinite(o.maxBytes) ? o.maxBytes : MAX_SCAN_BYTES;
+  const maxRows = Number.isFinite(o.maxRows) ? o.maxRows : MAX_SCAN_ROWS;
+
+  let fd = null;
+  try {
+    fd = openSync(path, "r");
+    const size = fstatSync(fd).size;
+    const start = Math.max(0, size - maxBytes);
+    const length = size - start;
+    const buf = Buffer.allocUnsafe(length);
+    let read = 0;
+    while (read < length) {
+      const n = readSync(fd, buf, read, length - read, start + read);
+      if (n <= 0) break;
+      read += n;
+    }
+    let text = buf.subarray(0, read).toString("utf-8");
+    const truncated = start > 0;
+    // A non-zero start almost certainly lands mid-line; drop the first partial.
+    if (truncated) {
+      const nl = text.indexOf("\n");
+      text = nl === -1 ? "" : text.slice(nl + 1);
+    }
+    const lines = text.split("\n").filter((l) => l.trim());
+    const slice = lines.length > maxRows ? lines.slice(lines.length - maxRows) : lines;
+    const rows = [];
+    let bad = 0;
+    for (const line of slice) {
+      try {
+        const row = JSON.parse(line);
+        if (row && typeof row === "object") rows.push(row);
+      } catch {
+        bad += 1;
+      }
+    }
+    return {
+      rows,
+      degraded: bad > 0,
+      degradedReason: bad > 0 ? `${bad} unparseable journal line(s)` : null,
+      truncated: truncated || lines.length > maxRows,
+    };
+  } catch (err) {
+    return {
+      rows: [],
+      degraded: true,
+      degradedReason: `journal read failed: ${err && err.message ? err.message : String(err)}`,
+      truncated: false,
+    };
+  } finally {
+    if (fd !== null) {
+      try { closeSync(fd); } catch { /* fd already gone; nothing to salvage */ }
+    }
+  }
+}
+
+/**
+ * Build the history view the decision ladder needs, from one tail scan.
+ *
+ * @param {object} [o]
+ * @param {string} [o.agentRoot]
+ * @param {number} [o.nowMs]
+ * @param {number} [o.dedupeWindowMs]
+ * @param {number} [o.floodWindowMs]
+ * @param {object[]} [o.rows] pre-read rows (tests / a caller that already scanned)
+ * @returns {{
+ *   seen:(key:string)=>boolean,
+ *   chainDepth:(threadKey:string)=>number,
+ *   actorActivity:(actor:string)=>number,
+ *   failures:(obligationKey:string)=>number,
+ *   rows:object[], degraded:boolean, degradedReason:string|null
+ * }}
+ */
+export function loadHistory(o = {}) {
+  const now = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const dedupeWindow = Number.isFinite(o.dedupeWindowMs) ? o.dedupeWindowMs : DEFAULT_DEDUPE_WINDOW_MS;
+  const floodWindow = Number.isFinite(o.floodWindowMs) ? o.floodWindowMs : DEFAULT_FLOOD_WINDOW_MS;
+
+  const scan = Array.isArray(o.rows)
+    ? { rows: o.rows, degraded: false, degradedReason: null }
+    : readTail(o);
+
+  const seenKeys = new Set();
+  const chains = new Map();   // threadKey → consecutive agent turns (reset by a human turn)
+  const actors = new Map();   // actor → count inside floodWindow
+  const failures = new Map(); // obligationKey → failure count
+
+  for (const row of scan.rows) {
+    const ts = typeof row.ts === "string" ? Date.parse(row.ts) : NaN;
+    const age = Number.isFinite(ts) ? now - ts : Infinity;
+
+    if (row.key && age <= dedupeWindow) seenKeys.add(String(row.key));
+
+    // Chain depth counts only turns where the agent actually SPOKE. A decision
+    // to ignore or to queue does not deepen a conversation, so it must not
+    // count toward the ping-pong ceiling — otherwise three ignores in a row
+    // would gag the agent on the fourth, genuinely-directed message.
+    const tk = row.thread ? String(row.thread) : null;
+    if (tk) {
+      if (row.event === "human_turn") {
+        chains.set(tk, 0);
+      } else if (row.event === "outcome" && row.spoke === true) {
+        chains.set(tk, (chains.get(tk) || 0) + 1);
+      }
+    }
+
+    if (row.actor && age <= floodWindow && row.event === "decision") {
+      const a = String(row.actor);
+      actors.set(a, (actors.get(a) || 0) + 1);
+    }
+
+    if (row.obligationKey && row.event === "outcome") {
+      const k = String(row.obligationKey);
+      if (row.ok === false) failures.set(k, (failures.get(k) || 0) + 1);
+      else if (row.ok === true) failures.set(k, 0);
+    }
+  }
+
+  return {
+    seen: (key) => seenKeys.has(String(key)),
+    chainDepth: (tk) => chains.get(String(tk)) || 0,
+    actorActivity: (actor) => actors.get(String(actor)) || 0,
+    failures: (k) => failures.get(String(k)) || 0,
+    rows: scan.rows,
+    degraded: !!scan.degraded,
+    degradedReason: scan.degradedReason || null,
+  };
+}
+
+/** Coerce to a plain, JSON-safe object; never lets a getter throw into the log path. */
+function safe(v) {
+  try {
+    return JSON.parse(JSON.stringify(v === undefined ? null : v));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Append a decision row. Returns the row so the caller can correlate it with the
+ * outcome row it will write later.
+ *
+ * @param {object} decision the result of `disposition.decide`
+ * @param {object} [o] { agentRoot, nowMs, traceId, append }
+ * @returns {{ok:boolean, row:object}}
+ */
+export function recordDecision(decision = {}, o = {}) {
+  const now = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const row = {
+    ts: new Date(now).toISOString(),
+    event: "decision",
+    key: decision.key || null,
+    thread: decision.thread || null,
+    actor: decision.actor || null,
+    surface: decision.surface || null,
+    topic: decision.topic || null,
+    disposition: decision.disposition || null,
+    reason: decision.reason || null,
+    rung: Number.isFinite(decision.rung) ? decision.rung : null,
+    mechanism: decision.mechanism || null,
+    obligationKey: decision.obligationKey || null,
+    objectiveId: decision.objectiveId || null,
+    // The ordered rule trace. This is the answer to "why did the agent do that?"
+    // and it is why the journal is worth writing at all.
+    why: Array.isArray(decision.why) ? decision.why.map(String) : [],
+    gates: safe(decision.gates || null),
+    drift: safe(decision.drift || null),
+    trace_id: o.traceId || null,
+  };
+  const append = typeof o.append === "function" ? o.append : appendJsonl;
+  const ok = append(o.path || journalPath(o.agentRoot), row);
+  return { ok, row };
+}
+
+/**
+ * Append the outcome of acting on a decision.
+ *
+ * `spoke` is separate from `ok` on purpose: an action can succeed without the
+ * agent having said anything (queued a task), and the ping-pong guard counts
+ * SPEAKING, not succeeding.
+ *
+ * @param {object} outcome { key, thread, disposition, ok, spoke, effect, ref, error, obligationKey, costCents }
+ * @param {object} [o] { agentRoot, nowMs, traceId, append }
+ * @returns {{ok:boolean, row:object}}
+ */
+export function recordOutcome(outcome = {}, o = {}) {
+  const now = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const row = {
+    ts: new Date(now).toISOString(),
+    event: "outcome",
+    key: outcome.key || null,
+    thread: outcome.thread || null,
+    surface: outcome.surface || null,
+    disposition: outcome.disposition || null,
+    effect: outcome.effect || null,
+    ok: outcome.ok === true,
+    spoke: outcome.spoke === true,
+    ref: outcome.ref === undefined ? null : safe(outcome.ref),
+    error: outcome.error ? String(outcome.error) : null,
+    degraded: outcome.degraded ? String(outcome.degraded) : null,
+    obligationKey: outcome.obligationKey || null,
+    costCents: Number.isFinite(outcome.costCents) ? outcome.costCents : null,
+    trace_id: o.traceId || null,
+  };
+  const append = typeof o.append === "function" ? o.append : appendJsonl;
+  const ok = append(o.path || journalPath(o.agentRoot), row);
+  return { ok, row };
+}
+
+/**
+ * Record that a HUMAN spoke in a thread, which resets the ping-pong counter.
+ * Called by the inbound pipeline for any event whose actor is not an agent — it
+ * is what lets a conversation continue past `maxChainDepth` when the human is
+ * still engaged, instead of the agent going mute mid-exchange.
+ *
+ * @param {{thread:string, actor?:string, surface?:string}} o1
+ * @param {object} [o]
+ */
+export function recordHumanTurn(o1 = {}, o = {}) {
+  const now = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const row = {
+    ts: new Date(now).toISOString(),
+    event: "human_turn",
+    thread: o1.thread || null,
+    actor: o1.actor || null,
+    surface: o1.surface || null,
+    trace_id: o.traceId || null,
+  };
+  const append = typeof o.append === "function" ? o.append : appendJsonl;
+  return { ok: append(o.path || journalPath(o.agentRoot), row), row };
+}
+
+export default {
+  JOURNAL_REL,
+  MAX_SCAN_BYTES,
+  MAX_SCAN_ROWS,
+  DEFAULT_FLOOD_WINDOW_MS,
+  DEFAULT_DEDUPE_WINDOW_MS,
+  journalPath,
+  dedupeKey,
+  threadKey,
+  readTail,
+  loadHistory,
+  recordDecision,
+  recordOutcome,
+  recordHumanTurn,
+};

package/lib/execution/journal.test.mjs

@@ -0,0 +1,261 @@
+/**
+ * journal.test.mjs — the reasoning record and the three guards it answers.
+ * Run: node --test lib/execution/journal.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+
+import {
+  dedupeKey,
+  threadKey,
+  readTail,
+  loadHistory,
+  recordDecision,
+  recordOutcome,
+  recordHumanTurn,
+  journalPath,
+  JOURNAL_REL,
+} from "./journal.mjs";
+
+const NOW = Date.parse("2026-08-11T12:00:00Z");
+function tmp() { return mkdtempSync(join(tmpdir(), "exec-journal-")); }
+function ago(ms) { return new Date(NOW - ms).toISOString(); }
+
+function seed(root, rows) {
+  const p = join(root, JOURNAL_REL);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, rows.map((r) => JSON.stringify(r)).join("\n") + "\n");
+  return p;
+}
+
+test("dedupeKey prefers the ledger seq — the collision-free coordinate", () => {
+  assert.equal(dedupeKey({ family: "messaging", kind: "send", seq: 41 }), "messaging.send#41");
+  // seq 0 is a real cursor position, not "absent"
+  assert.equal(dedupeKey({ family: "board", kind: "item.assigned", seq: 0 }), "board.item.assigned#0");
+});
+
+test("dedupeKey without a seq does NOT collapse distinct events on one entity", () => {
+  const a = dedupeKey({ family: "board", kind: "item.commented", entityId: "t1", at: "2026-08-11T10:00:00Z" });
+  const b = dedupeKey({ family: "board", kind: "item.commented", entityId: "t1", at: "2026-08-11T10:05:00Z" });
+  assert.notEqual(a, b, "two comments on one task must be two events");
+  // ...but the SAME event redelivered is the same key
+  const c = dedupeKey({ family: "board", kind: "item.commented", entityId: "t1", at: "2026-08-11T10:00:00Z" });
+  assert.equal(a, c);
+});
+
+test("dedupeKey and threadKey never throw on junk", () => {
+  for (const v of [undefined, null, {}, { ids: null }, { seq: "" }]) {
+    assert.equal(typeof dedupeKey(v), "string");
+    assert.equal(typeof threadKey(v), "string");
+  }
+});
+
+test("threadKey normalises chat, board and file threads into one key space", () => {
+  const chat = threadKey({ family: "messaging", ids: { channelId: "c1", threadRootId: "m9" } });
+  const board = threadKey({ family: "board", ids: { taskId: "t1" }, entityId: "t1" });
+  assert.equal(chat, "messaging:c1:m9");
+  assert.equal(board, "board:-:t1");
+  // the same thread from two deliveries yields one key
+  assert.equal(chat, threadKey({ family: "messaging", ids: { channelId: "c1", threadRootId: "m9" } }));
+  // different threads in one room do not collide
+  assert.notEqual(chat, threadKey({ family: "messaging", ids: { channelId: "c1", threadRootId: "m8" } }));
+});
+
+test("readTail: absent file is empty and NOT degraded", () => {
+  const root = tmp();
+  try {
+    const r = readTail({ agentRoot: root });
+    assert.deepEqual(r.rows, []);
+    assert.equal(r.degraded, false);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("readTail: unparseable lines are counted and REPORTED, not silently dropped", () => {
+  const root = tmp();
+  try {
+    const p = join(root, JOURNAL_REL);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, `{"event":"decision","key":"a"}\nnot json at all\n{"event":"decision","key":"b"}\n`);
+    const r = readTail({ agentRoot: root });
+    assert.equal(r.rows.length, 2);
+    assert.equal(r.degraded, true);
+    assert.match(r.degradedReason, /1 unparseable/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("readTail: a huge journal is bounded, and the partial first line is dropped", () => {
+  const root = tmp();
+  try {
+    const p = join(root, JOURNAL_REL);
+    mkdirSync(dirname(p), { recursive: true });
+    const rows = [];
+    for (let i = 0; i < 5000; i++) rows.push(JSON.stringify({ event: "decision", key: `k${i}`, pad: "x".repeat(200) }));
+    writeFileSync(p, rows.join("\n") + "\n");
+    const r = readTail({ agentRoot: root, maxBytes: 20 * 1024 });
+    assert.ok(r.truncated, "a bounded read reports truncation");
+    assert.ok(r.rows.length > 0 && r.rows.length < 5000);
+    // every surviving row parsed — i.e. the partial head line was discarded
+    assert.equal(r.degraded, false, `partial line leaked: ${r.degradedReason}`);
+    // and the rows we kept are the NEWEST ones
+    assert.equal(r.rows[r.rows.length - 1].key, "k4999");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("readTail: maxRows caps even inside the byte budget", () => {
+  const root = tmp();
+  try {
+    seed(root, Array.from({ length: 100 }, (_, i) => ({ event: "decision", key: `k${i}` })));
+    const r = readTail({ agentRoot: root, maxRows: 10 });
+    assert.equal(r.rows.length, 10);
+    assert.equal(r.rows[9].key, "k99", "keeps the newest");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("seen(): a redelivery inside the window is caught; outside it is not", () => {
+  const root = tmp();
+  try {
+    seed(root, [
+      { ts: ago(60_000), event: "decision", key: "messaging.send#1" },
+      { ts: ago(48 * 3600 * 1000), event: "decision", key: "messaging.send#2" },
+    ]);
+    const h = loadHistory({ agentRoot: root, nowMs: NOW });
+    assert.equal(h.seen("messaging.send#1"), true);
+    assert.equal(h.seen("messaging.send#2"), false, "48h old, 24h window");
+    assert.equal(h.seen("messaging.send#999"), false);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("chainDepth counts only turns where the agent SPOKE", () => {
+  const root = tmp();
+  try {
+    seed(root, [
+      { ts: ago(5000), event: "outcome", thread: "t", spoke: true },
+      { ts: ago(4000), event: "outcome", thread: "t", spoke: false },  // a queued item
+      { ts: ago(3000), event: "decision", thread: "t" },               // a decision alone
+      { ts: ago(2000), event: "outcome", thread: "t", spoke: true },
+    ]);
+    const h = loadHistory({ agentRoot: root, nowMs: NOW });
+    assert.equal(h.chainDepth("t"), 2, "ignores and queues must not gag the agent");
+    assert.equal(h.chainDepth("other"), 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("a human turn RESETS the chain — a live conversation is never cut off", () => {
+  const root = tmp();
+  try {
+    seed(root, [
+      { ts: ago(9000), event: "outcome", thread: "t", spoke: true },
+      { ts: ago(8000), event: "outcome", thread: "t", spoke: true },
+      { ts: ago(7000), event: "human_turn", thread: "t" },
+      { ts: ago(6000), event: "outcome", thread: "t", spoke: true },
+    ]);
+    const h = loadHistory({ agentRoot: root, nowMs: NOW });
+    assert.equal(h.chainDepth("t"), 1);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("actorActivity counts decisions inside the flood window only", () => {
+  const root = tmp();
+  try {
+    seed(root, [
+      ...Array.from({ length: 5 }, () => ({ ts: ago(60_000), event: "decision", actor: "m1" })),
+      { ts: ago(60 * 60 * 1000), event: "decision", actor: "m1" }, // an hour ago
+      { ts: ago(60_000), event: "outcome", actor: "m1" },          // outcomes do not count
+    ]);
+    const h = loadHistory({ agentRoot: root, nowMs: NOW });
+    assert.equal(h.actorActivity("m1"), 5);
+    assert.equal(h.actorActivity("m2"), 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("failures(): counts consecutive failures and is RESET by a success", () => {
+  const root = tmp();
+  try {
+    seed(root, [
+      { ts: ago(5000), event: "outcome", obligationKey: "o1", ok: false },
+      { ts: ago(4000), event: "outcome", obligationKey: "o1", ok: false },
+      { ts: ago(3000), event: "outcome", obligationKey: "o2", ok: false },
+      { ts: ago(2000), event: "outcome", obligationKey: "o2", ok: true },
+    ]);
+    const h = loadHistory({ agentRoot: root, nowMs: NOW });
+    assert.equal(h.failures("o1"), 2, "two failures buys exactly one rung");
+    assert.equal(h.failures("o2"), 0, "a success clears the walk-up");
+    assert.equal(h.failures("never-seen"), 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("recordDecision writes the full rule trace — including for an ignore", () => {
+  const root = tmp();
+  try {
+    recordDecision(
+      {
+        key: "messaging.send#7", thread: "messaging:c1:m1", actor: "m2", surface: "mention",
+        disposition: "ignore", reason: "reply_chain_depth",
+        why: ["directed: mention on mention (tier T0)", "3 consecutive agent turns → stop talking"],
+      },
+      { agentRoot: root, nowMs: NOW },
+    );
+    const rows = readTail({ agentRoot: root }).rows;
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].event, "decision");
+    assert.equal(rows[0].disposition, "ignore");
+    assert.equal(rows[0].reason, "reply_chain_depth");
+    assert.equal(rows[0].why.length, 2, "an ignore records MORE, not less");
+    assert.ok(rows[0].ts);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("recordOutcome separates `ok` from `spoke`", () => {
+  const root = tmp();
+  try {
+    recordOutcome({ key: "k", thread: "t", disposition: "schedule", effect: "schedule", ok: true, spoke: false },
+      { agentRoot: root, nowMs: NOW });
+    const [row] = readTail({ agentRoot: root }).rows;
+    assert.equal(row.ok, true);
+    assert.equal(row.spoke, false, "queuing work succeeded without the agent saying anything");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("record* survive non-serialisable payloads instead of throwing", () => {
+  const root = tmp();
+  try {
+    const cyclic = {}; cyclic.self = cyclic;
+    const r = recordDecision({ key: "k", why: ["x"], gates: cyclic, drift: cyclic }, { agentRoot: root, nowMs: NOW });
+    assert.equal(r.ok, true);
+    const [row] = readTail({ agentRoot: root }).rows;
+    assert.equal(row.gates, null, "unserialisable input degrades to null, it does not crash the log path");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("a failed append is REPORTED to the caller, never swallowed", () => {
+  const r = recordDecision({ key: "k" }, { agentRoot: "/x", append: () => false });
+  assert.equal(r.ok, false, "the caller must be able to see that the reasoning was not persisted");
+});
+
+test("recordHumanTurn round-trips through loadHistory", () => {
+  const root = tmp();
+  try {
+    recordOutcome({ thread: "t", ok: true, spoke: true }, { agentRoot: root, nowMs: NOW - 2000 });
+    recordHumanTurn({ thread: "t", actor: "human1" }, { agentRoot: root, nowMs: NOW - 1000 });
+    assert.equal(loadHistory({ agentRoot: root, nowMs: NOW }).chainDepth("t"), 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("loadHistory accepts pre-read rows (the batch path) without touching disk", () => {
+  const h = loadHistory({
+    nowMs: NOW,
+    rows: [{ ts: ago(1000), event: "decision", key: "a", actor: "m1" }],
+    agentRoot: "/nonexistent-on-purpose",
+  });
+  assert.equal(h.seen("a"), true);
+  assert.equal(h.actorActivity("m1"), 1);
+});
+
+test("journalPath resolves under the agent root", () => {
+  assert.equal(journalPath("/tmp/agent-x"), join("/tmp/agent-x", JOURNAL_REL));
+});