@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/execution/intake.test.mjs

@@ -1,389 +0,0 @@
-/**
- * lib/execution/intake.test.mjs — every inbound shape, every surface, both signs.
- *
- * The negatives matter more than the positives here. `intake` is the only place
- * that decides a Slack channel message nobody addressed is NOT this agent's
- * problem, and the only place an `info` alert is stopped from becoming work. A
- * regression in a positive case is a missed reply; a regression in a negative
- * case is an agent that interrupts every conversation in the workspace.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  intake,
-  fromInboxItem,
-  fromChannelEvent,
-  fromAlert,
-  fromRawEvent,
-  fromMessageEvent,
-  parseRawRef,
-  isKnownSurface,
-  KIND_SURFACE,
-  SURFACE_FAMILY,
-  SURFACE_TOPIC,
-  RECONSTRUCTED_REASON,
-} from "./intake.mjs";
-import { SURFACE_POLICY, EXTENDED_SURFACE_NAMES } from "./surface-policy.mjs";
-import { SURFACE_NAMES } from "../org/inbound/surfaces.mjs";
-import { decide } from "./disposition.mjs";
-import { dedupeKey, threadKey } from "./journal.mjs";
-
-const ME = "mem_self";
-const NOW = "2026-08-11T09:00:00.000Z";
-
-/** A cohort inbox item as it exists on disk (post-`eventToInboxItem` flattening). */
-function orgItem(over = {}) {
-  return {
-    id: "cohort-mention-4821",
-    service: "cohort",
-    channel: "eng-space",
-    channel_id: "chan_1",
-    sender: "peer-one",
-    sender_id: "mem_peer",
-    timestamp: NOW,
-    subject: "Cohort @mention: eng-space",
-    content: "can you take a look at this",
-    thread_id: "msg_77",
-    is_reply: false,
-    priority_signals: { from_ceo: false, tagged_urgent: false, contains_deadline: false, mentions_agent: true },
-    raw_ref: "cohort:mention:msg_99:4821",
-    source: "cohort",
-    kind: "mention",
-    ...over,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// raw_ref
-// ---------------------------------------------------------------------------
-
-test("parseRawRef reads the projection's cohort ref, including ids containing colons", () => {
-  assert.deepEqual(parseRawRef("cohort:mention:msg_99:4821"), {
-    surface: "mention",
-    entityId: "msg_99",
-    seq: "4821",
-  });
-  assert.deepEqual(parseRawRef("cohort:task_comment:task:abc:def:12"), {
-    surface: "task_comment",
-    entityId: "task:abc:def",
-    seq: "12",
-  });
-});
-
-test("parseRawRef refuses a channel adapter's legacy ref and an unknown surface", () => {
-  assert.equal(parseRawRef("slack:C123:1699.1"), null, "legacy channel ref must not parse as cohort");
-  assert.equal(parseRawRef("cohort:teleport:x:1"), null, "unknown surface must not parse");
-  assert.equal(parseRawRef(""), null);
-  assert.equal(parseRawRef(null), null);
-});
-
-// ---------------------------------------------------------------------------
-// coverage: every surface is reachable and decidable
-// ---------------------------------------------------------------------------
-
-test("every policy surface has a family, a topic and a reconstructable reason", () => {
-  for (const name of Object.keys(SURFACE_POLICY)) {
-    assert.ok(SURFACE_FAMILY[name], `${name} has no family`);
-    assert.ok(SURFACE_TOPIC[name], `${name} has no topic`);
-    assert.ok(RECONSTRUCTED_REASON[name], `${name} has no reconstructable reason`);
-    assert.ok(isKnownSurface(name), `${name} is not a known surface`);
-  }
-});
-
-test("every org surface can be reconstructed from an on-disk item and decided", () => {
-  for (const surface of SURFACE_NAMES) {
-    const item = orgItem({
-      raw_ref: `cohort:${surface}:ent_1:900`,
-      kind: surface === "dm" ? "message" : surface,
-      id: `cohort-${surface}-900`,
-    });
-    const norm = fromInboxItem(item, { me: ME, now: NOW });
-    assert.equal(norm.verdict.surface, surface, `${surface} did not round-trip`);
-    assert.equal(norm.verdict.directed, true, `${surface} lost its directedness`);
-    assert.equal(norm.candidate.family, SURFACE_FAMILY[surface]);
-
-    const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
-    assert.ok(d.disposition, `${surface} produced no disposition`);
-    assert.notEqual(d.policySurface, "default", `${surface} fell back to DEFAULT_POLICY`);
-  }
-});
-
-test("the three extended surfaces decide without falling back to the default row", () => {
-  for (const surface of EXTENDED_SURFACE_NAMES) {
-    const norm = fromInboxItem(orgItem({ raw_ref: `cohort:${surface}:ent_9:12`, kind: surface }), { me: ME });
-    assert.equal(norm.verdict.surface, surface);
-    const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
-    assert.equal(d.policySurface, surface, `${surface} has no policy row`);
-  }
-});
-
-// ---------------------------------------------------------------------------
-// org inbox items
-// ---------------------------------------------------------------------------
-
-test("an org inbox item reconstructs directed:true and SAYS it reconstructed it", () => {
-  const norm = fromInboxItem(orgItem(), { me: ME });
-  assert.equal(norm.origin, "inbox_item");
-  assert.equal(norm.verdict.directed, true);
-  assert.equal(norm.verdict.surface, "mention");
-  assert.ok(
-    norm.degraded.some((d) => d.startsWith("verdict_reconstructed:")),
-    "a reconstructed verdict must be labelled as such, never presented as a resolved one",
-  );
-});
-
-test("mentions_agent upgrades a lane-tier reason to a structural one", () => {
-  const named = fromInboxItem(orgItem({ raw_ref: "cohort:thread_reply:msg_5:7", kind: "thread_reply" }), { me: ME });
-  assert.equal(named.verdict.reason, "named", "mentions_agent:true must read as T0");
-
-  const quiet = fromInboxItem(
-    orgItem({
-      raw_ref: "cohort:thread_reply:msg_5:7",
-      kind: "thread_reply",
-      priority_signals: { mentions_agent: false },
-    }),
-    { me: ME },
-  );
-  assert.equal(quiet.verdict.reason, "thread", "no mention must stay lane tier");
-});
-
-test("a lost raw_ref falls back to kind, and is_dm:false stops a channel item being read as a DM", () => {
-  const norm = fromInboxItem(orgItem({ raw_ref: "", kind: "message", is_dm: false }), { me: ME });
-  assert.equal(norm.verdict.surface, "mention");
-  assert.ok(norm.degraded.includes("surface_inferred_from_kind"));
-});
-
-test("an org item whose surface cannot be established is refused, not guessed", () => {
-  const norm = fromInboxItem(orgItem({ raw_ref: "", kind: "reaction" }), { me: ME });
-  assert.equal(norm.candidate, null);
-  assert.equal(norm.verdict.directed, false);
-  assert.equal(norm.verdict.reason, "unknown_surface");
-});
-
-test("two comments on the same task get different dedupe keys but share a thread", () => {
-  const a = fromInboxItem(orgItem({ raw_ref: "cohort:task_comment:task_7:101", kind: "task_comment" }), { me: ME });
-  const b = fromInboxItem(orgItem({ raw_ref: "cohort:task_comment:task_7:102", kind: "task_comment" }), { me: ME });
-  assert.notEqual(dedupeKey(a.candidate), dedupeKey(b.candidate), "distinct events must not collapse");
-  assert.equal(threadKey(a.candidate), threadKey(b.candidate), "one task is one conversation");
-});
-
-// ---------------------------------------------------------------------------
-// channel adapters — the negatives
-// ---------------------------------------------------------------------------
-
-function slackItem(over = {}) {
-  return {
-    id: "1699000000.0001",
-    service: "slack",
-    channel: "general",
-    channel_id: "C123",
-    sender: "someone",
-    sender_id: "U9",
-    timestamp: NOW,
-    content: "shipping the thing today",
-    thread_id: "",
-    is_reply: false,
-    priority_signals: { mentions_agent: false },
-    raw_ref: "slack:C123:1699000000.0001",
-    source: "slack",
-    ...over,
-  };
-}
-
-test("NEGATIVE: an ambient Slack channel message is NOT directed", () => {
-  const norm = fromChannelEvent(slackItem(), { me: ME });
-  assert.equal(norm.verdict.directed, false);
-  assert.equal(norm.verdict.reason, "ambient_channel");
-  assert.ok(norm.why.join(" ").includes("not directed"));
-});
-
-test("NEGATIVE: an ambient channel message is parked, not dropped, because it could have been a mention", () => {
-  const norm = fromChannelEvent(slackItem(), { me: ME });
-  const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
-  assert.equal(d.disposition, "ignore");
-  assert.equal(d.ambient, true, "a message that might have been a mention deserves the ambient sweep");
-});
-
-test("a Slack DM is directed by construction", () => {
-  const norm = fromChannelEvent(slackItem({ is_dm: true, channel_type: "im" }), { me: ME });
-  assert.equal(norm.verdict.directed, true);
-  assert.equal(norm.verdict.surface, "dm");
-});
-
-test("a Slack channel message that names the agent is a mention", () => {
-  const norm = fromChannelEvent(slackItem({ priority_signals: { mentions_agent: true } }), { me: ME });
-  assert.equal(norm.verdict.surface, "mention");
-  assert.equal(norm.verdict.reason, "mention");
-});
-
-test("a thread reply on a channel is lane tier, and says membership is unverified", () => {
-  const norm = fromChannelEvent(slackItem({ is_reply: true, thread_id: "1699.0" }), { me: ME });
-  assert.equal(norm.verdict.surface, "thread_reply");
-  assert.ok(norm.degraded.includes("thread_membership_unverified"));
-});
-
-test("an org-mail item is email, directed, and keeps its service as the key space", () => {
-  const norm = fromChannelEvent(slackItem({ service: "orgmail", content: "quote attached" }), { me: ME });
-  assert.equal(norm.verdict.surface, "email");
-  assert.equal(norm.verdict.directed, true);
-  assert.equal(norm.candidate.family, "orgmail");
-});
-
-test("channel and org key spaces never collide", () => {
-  const org = fromInboxItem(orgItem({ raw_ref: "cohort:dm:m1:5" }), { me: ME });
-  const chan = fromChannelEvent(slackItem({ id: "m1", is_dm: true }), { me: ME });
-  assert.notEqual(dedupeKey(org.candidate), dedupeKey(chan.candidate));
-  assert.notEqual(threadKey(org.candidate), threadKey(chan.candidate));
-});
-
-// ---------------------------------------------------------------------------
-// alerts
-// ---------------------------------------------------------------------------
-
-test("a critical alert is directed and decides to queued work", () => {
-  const norm = fromAlert({ id: "daemon_down", severity: "critical", detail: "no beat in 40m" }, { me: ME, now: NOW });
-  assert.equal(norm.verdict.directed, true);
-  assert.equal(norm.verdict.surface, "alert");
-  const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
-  assert.equal(d.disposition, "schedule", "an alert is work, not conversation");
-});
-
-test("NEGATIVE: an info alert never becomes work", () => {
-  const norm = fromAlert({ id: "cache_warm", severity: "info", detail: "warmed" }, { me: ME });
-  assert.equal(norm.verdict.directed, false);
-  assert.equal(norm.verdict.reason, "alert_below_threshold");
-  const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
-  assert.equal(d.disposition, "ignore");
-});
-
-test("repeated firings of one alert collapse onto one thread", () => {
-  const a = fromAlert({ id: "disk_low", severity: "warning" }, { me: ME, now: NOW });
-  const b = fromAlert({ id: "disk_low", severity: "warning" }, { me: ME, now: "2026-08-11T10:00:00.000Z" });
-  assert.equal(threadKey(a.candidate), threadKey(b.candidate), "a flapping check must not become a task storm");
-});
-
-// ---------------------------------------------------------------------------
-// raw chain events
-// ---------------------------------------------------------------------------
-
-test("a raw chain row is classified and joined through the inbound layer, not a second copy of it", () => {
-  const norm = fromRawEvent(
-    { seq: 12, family: "escalation", kind: "raised", entity_id: "esc_1", payload: { actor: "mem_peer", waitingOnMemberId: ME } },
-    { me: ME },
-  );
-  assert.equal(norm.origin, "raw_event");
-  assert.ok(norm.candidate, "the classifier should have produced a candidate");
-  assert.ok(norm.degraded.includes("joined_without_facts"), "a factless join must be labelled");
-});
-
-test("NEGATIVE: a family an agent is not woken for produces no candidate and no throw", () => {
-  const norm = fromRawEvent({ seq: 1, family: "presence", kind: "beat", payload: {} }, { me: ME });
-  assert.equal(norm.candidate, null);
-  assert.equal(norm.verdict.directed, false);
-  assert.equal(norm.verdict.reason, "not_classified");
-});
-
-// ---------------------------------------------------------------------------
-// projected MessageEvents
-// ---------------------------------------------------------------------------
-
-test("a projected MessageEvent is lossless — no reconstruction, no degradation", () => {
-  const norm = fromMessageEvent(
-    {
-      message_id: "msg_3",
-      channel_id: "chan_2",
-      thread_id: "msg_1",
-      from: { id: "mem_peer", name: "peer" },
-      timestamp: NOW,
-      kind: "mention",
-      cohort: { surface: "mention", topic: "message", reason: "mention", family: "messaging", event_kind: "send", entity_id: "msg_3", seq: 55, me: ME },
-    },
-    { me: ME },
-  );
-  assert.deepEqual(norm.degraded, [], "a full-provenance event needs no guessing");
-  assert.equal(norm.verdict.reason, "mention");
-  assert.equal(norm.candidate.seq, 55);
-});
-
-// ---------------------------------------------------------------------------
-// intake() dispatch + totality
-// ---------------------------------------------------------------------------
-
-test("intake routes each shape to the right reader", () => {
-  assert.equal(intake({ candidate: { family: "x" }, verdict: { directed: true, surface: "dm" } }).origin, "pair");
-  assert.equal(intake({ cohort: { surface: "dm" }, from: {} }).origin, "message_event");
-  assert.equal(intake({ id: "a", severity: "critical" }).origin, "alert");
-  assert.equal(intake({ family: "board", kind: "assigned", payload: {} }).origin, "raw_event");
-  assert.equal(intake(orgItem()).origin, "inbox_item");
-  assert.equal(intake(slackItem()).origin, "channel_event");
-});
-
-test("intake is TOTAL: no input throws, returns undefined, or silently vanishes", () => {
-  for (const bad of [null, undefined, 7, "a string", [], {}, { kind: 5 }, { raw_ref: {} }]) {
-    const r = intake(bad, { me: ME });
-    assert.ok(r && typeof r === "object", `intake(${JSON.stringify(bad)}) returned nothing`);
-    assert.ok(r.verdict, "every result carries a verdict");
-    assert.ok(Array.isArray(r.why) && r.why.length > 0, "every result explains itself");
-  }
-});
-
-test("an unrecognised object is refused with a reason rather than guessed at", () => {
-  const r = intake({ some: "thing" }, { me: ME });
-  assert.equal(r.verdict.directed, false);
-  assert.equal(r.verdict.reason, "unrecognised_shape");
-  assert.ok(r.degraded.includes("unrecognised_shape"));
-});
-
-test("KIND_SURFACE covers every event kind the channel contract ships", async () => {
-  const { EVENT_KINDS } = await import("../channels/contract.mjs");
-  const missing = EVENT_KINDS.filter((k) => !["reaction", "channel_cc"].includes(k) && !KIND_SURFACE[k]);
-  assert.deepEqual(missing, [], "a shipped event kind with no surface would fall through to the default policy");
-});
-
-// ───────────────────────────────────────────────────────────────────────────
-// The poll lane must agree with the push lane about WHY an event is mine.
-// ───────────────────────────────────────────────────────────────────────────
-
-test("a carried `direct_reason` beats the per-surface guess — the guess sets the TIER", () => {
-  // Before this, `fromInboxItem` re-derived the reason from a default table, so
-  // an approval blocking a task the seat REVIEWS was journalled as "directed:
-  // approver on approval". Since `disposition.tierOf` maps the reason onto the
-  // T0/T1 tier, guessing wrong is deciding wrong.
-  const guessed = fromInboxItem({
-    raw_ref: "cohort:approval:aprv_1:99",
-    kind: "approval",
-    id: "cohort-approval-99",
-    timestamp: NOW,
-  }, { me: ME });
-  assert.equal(guessed.verdict.reason, "approver", "the fallback guess is unchanged");
-  assert.ok(guessed.degraded.some((d) => /verdict_reconstructed/.test(d)));
-
-  const carried = fromInboxItem({
-    raw_ref: "cohort:approval:aprv_1:99",
-    kind: "approval",
-    id: "cohort-approval-99",
-    timestamp: NOW,
-    direct_reason: "reviewer",
-  }, { me: ME });
-  assert.equal(carried.verdict.reason, "reviewer");
-  assert.ok(
-    !carried.degraded.some((d) => /verdict_reconstructed/.test(d)),
-    "a carried reason is not a reconstruction and must not be reported as one",
-  );
-});
-
-test("`scope_id` lands on the id its family is looked up by", () => {
-  const approval = fromInboxItem(
-    { raw_ref: "cohort:approval:aprv_1:99", kind: "approval", id: "i", timestamp: NOW, scope_id: "T-9" },
-    { me: ME },
-  );
-  assert.equal(approval.candidate.ids.taskId, "T-9", "effects.escalate reads ids.taskId");
-
-  const decision = fromInboxItem(
-    { raw_ref: "cohort:decision:dec_1:99", kind: "decision", id: "i", timestamp: NOW, scope_id: "D-1" },
-    { me: ME },
-  );
-  assert.equal(decision.candidate.ids.decisionId, "D-1");
-});

package/lib/execution/journal.test.mjs

@@ -1,261 +0,0 @@
-/**
- * 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));
-});