@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/execution/drive.mjs

@@ -0,0 +1,352 @@
+/**
+ * lib/execution/drive.mjs — turn a decision into a thing that actually happened.
+ *
+ * `disposition.mjs` is pure and decides; this module is effectful and does. The
+ * split exists so the decision can be tested exhaustively per surface without a
+ * network, and so the journal records the reasoning *before* the side effect
+ * runs — if the process dies mid-action there is still a record of what it was
+ * trying to do and why.
+ *
+ * Order of operations, and the reason for each:
+ *
+ *   1. journal the decision            (so a crash leaves evidence, not silence)
+ *   2. ignore ⇒ record and stop        (an ignore is an outcome, not an absence)
+ *   3. observe-only ⇒ propose          (§5.10: the 14-day window creates no work)
+ *   4. approval gate                   (§8: blast radius gates BEFORE any rung)
+ *   5. arbitration gate                (one agent per thread, fail-open on 3s)
+ *   6. the effect itself
+ *   7. drift report                    (best effort; never blocks the action)
+ *   8. journal the outcome
+ *
+ * Every effect is INJECTED. `drive` imports nothing that touches the network —
+ * `effects.mjs` does that — which keeps this file testable with plain fakes and
+ * keeps the sequencing logic in one readable place.
+ *
+ * FAIL-OPEN, NEVER SILENT. An effect that throws does not take the daemon down
+ * and does not abort the remaining bookkeeping; it produces `ok:false` with the
+ * error text on the outcome row and a `degraded` entry the caller logs. Every
+ * bug found in this system so far has been a silent fail-open, so there is no
+ * bare `catch {}` in this file.
+ *
+ * @module lib/execution/drive
+ */
+
+"use strict";
+
+import { recordDecision, recordOutcome } from "./journal.mjs";
+import { willAct } from "./disposition.mjs";
+import { isDisposition } from "./surface-policy.mjs";
+
+/** The effect name invoked for each disposition. */
+export const EFFECT_FOR = Object.freeze({
+  react_now: "react",
+  schedule: "schedule",
+  delegate: "delegate",
+  escalate: "escalate",
+});
+
+/** Dispositions after which the agent has SPOKEN (deepens a reply chain). */
+const SPEAKING = Object.freeze(["react_now"]);
+
+/**
+ * Run one effect with uniform error capture. Returns a normalised result rather
+ * than throwing, so the caller's sequencing stays linear.
+ *
+ * @param {Function|undefined} fn
+ * @param {string} name
+ * @param {object} args
+ * @returns {Promise<{ok:boolean, ref:any, error:string|null, missing:boolean}>}
+ */
+async function runEffect(fn, name, args) {
+  if (typeof fn !== "function") {
+    return { ok: false, ref: null, error: `no effect wired for \`${name}\``, missing: true };
+  }
+  try {
+    const r = await fn(args);
+    if (r && typeof r === "object" && "ok" in r) {
+      return {
+        ok: r.ok !== false,
+        ref: r.ref === undefined ? null : r.ref,
+        error: r.error ? String(r.error) : null,
+        missing: false,
+      };
+    }
+    return { ok: true, ref: r === undefined ? null : r, error: null, missing: false };
+  } catch (err) {
+    return {
+      ok: false,
+      ref: null,
+      error: err && err.message ? err.message : String(err),
+      missing: false,
+    };
+  }
+}
+
+/**
+ * Drive a decision to an action.
+ *
+ * @param {object} decision the output of `disposition.decide`
+ * @param {object} o
+ * @param {object} o.candidate the inbound Candidate the decision was made about
+ * @param {object} o.effects   {
+ *   react, schedule, delegate, escalate, propose,
+ *   requestApproval, arbitrate, reportDrift
+ * } — every key optional; a missing one degrades that path loudly
+ * @param {string} [o.agentRoot]
+ * @param {number} [o.nowMs]
+ * @param {string} [o.traceId]
+ * @param {Function} [o.log]  (level, message, attrs) — defaults to console.warn
+ *                            for degradations. Never swallowed.
+ * @param {Function} [o.append] journal writer override (tests)
+ * @returns {Promise<{
+ *   ok:boolean, disposition:string, effect:string|null, ref:any,
+ *   spoke:boolean, error:string|null, degraded:string[], decision:object
+ * }>}
+ */
+export async function drive(decision, o = {}) {
+  const effects = (o && o.effects) || {};
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const journalOpts = {
+    agentRoot: o.agentRoot,
+    nowMs,
+    traceId: o.traceId,
+    append: o.append,
+    path: o.journalPath,
+  };
+  const degraded = [].concat((decision && decision.degraded) || []);
+  const log =
+    typeof o.log === "function"
+      ? o.log
+      : (level, msg, attrs) => {
+          // A degradation that is not printed is a degradation nobody fixes.
+          const line = `[execution] ${msg}`;
+          if (level === "error") console.error(line, attrs || "");
+          else console.warn(line, attrs || "");
+        };
+
+  if (!decision || typeof decision !== "object") {
+    log("error", "drive called with no decision — the inbound event is unaccounted for");
+    return {
+      ok: false,
+      disposition: null,
+      effect: null,
+      ref: null,
+      spoke: false,
+      error: "no decision",
+      degraded: ["no_decision"],
+      decision: null,
+    };
+  }
+
+  // 1. Journal the reasoning FIRST. If the process dies in the effect below,
+  //    this row is what tells you what it was doing.
+  const written = recordDecision(decision, journalOpts);
+  if (!written.ok) {
+    degraded.push("journal_decision_write_failed");
+    log("error", "could not write the decision journal — proceeding, but this action will be unexplained", {
+      key: decision.key,
+    });
+  }
+  for (const d of decision.degraded || []) log("warn", `decision degraded: ${d}`, { key: decision.key });
+
+  const finish = async (res) => {
+    const outcome = {
+      key: decision.key,
+      thread: decision.thread,
+      surface: decision.surface,
+      disposition: decision.disposition,
+      effect: res.effect,
+      ok: res.ok,
+      spoke: res.spoke === true,
+      ref: res.ref,
+      error: res.error,
+      degraded: res.degraded && res.degraded.length ? res.degraded.join(",") : null,
+      obligationKey: decision.obligationKey,
+      costCents: res.costCents,
+    };
+    const w = recordOutcome(outcome, journalOpts);
+    if (!w.ok) log("error", "could not write the outcome journal", { key: decision.key });
+    return {
+      ok: res.ok,
+      disposition: decision.disposition,
+      effect: res.effect,
+      ref: res.ref,
+      spoke: res.spoke === true,
+      error: res.error,
+      degraded: res.degraded || [],
+      decision,
+    };
+  };
+
+  // Drift is reported for ignore paths too (`mandate_stale` is an ignore), so it
+  // runs before the ignore short-circuit. Best effort by design: a drift report
+  // that fails must never stop the agent doing the actual work.
+  if (decision.drift) {
+    const d = await runEffect(effects.reportDrift, "reportDrift", {
+      drift: decision.drift,
+      decision,
+      candidate: o.candidate,
+    });
+    if (!d.ok) {
+      degraded.push(`drift_report_failed:${decision.drift.kind}`);
+      log("warn", `drift report failed (${decision.drift.kind}) — the plan gap is local-only`, { error: d.error });
+    }
+  }
+
+  // 2. An ignore is a completed decision. Record it and stop.
+  //
+  // An UNRECOGNISED disposition is not the same thing and must not be quietly
+  // folded in here — that would be the exact silent fail-open this codebase
+  // keeps shipping: a malformed decision would look like a successful "we chose
+  // not to act" and the event would vanish with a green outcome row.
+  if (!isDisposition(decision.disposition)) {
+    log("error", `unrecognised disposition \`${decision.disposition}\` — the event was not acted on`, {
+      key: decision.key,
+    });
+    degraded.push("invalid_disposition");
+    return finish({
+      effect: null,
+      ok: false,
+      spoke: false,
+      ref: null,
+      error: `unmapped disposition ${decision.disposition}`,
+      degraded,
+    });
+  }
+  if (!willAct(decision)) {
+    return finish({ effect: "none", ok: true, spoke: false, ref: null, error: null, degraded });
+  }
+
+  // 3. Observe-only: decide fully, act not at all. The proposal is the artefact.
+  if (decision.observeOnly === true) {
+    const r = await runEffect(effects.propose, "propose", { decision, candidate: o.candidate });
+    if (r.missing) {
+      degraded.push("propose_effect_missing");
+      log("warn", "observe-only decision had nowhere to be proposed — it is journal-only", { key: decision.key });
+    }
+    return finish({
+      effect: "propose",
+      ok: r.ok || r.missing, // a missing proposal sink is a degradation, not a failure to decide
+      spoke: false,
+      ref: r.ref,
+      error: r.error,
+      degraded,
+    });
+  }
+
+  const gates = decision.gates || {};
+
+  // 4. Blast radius. An `external | irreversible | financial` action is approved
+  //    BEFORE any rung executes, rung 0 included.
+  if (gates.approval && gates.approval.required) {
+    const a = await runEffect(effects.requestApproval, "requestApproval", {
+      decision,
+      candidate: o.candidate,
+      classes: gates.approval.classes,
+    });
+    if (a.missing) {
+      // No approval channel wired and the action is gated: the ONLY safe answer
+      // is not to do it. Fail closed here — this is the one place in the file
+      // where failing open would let an agent email the world unsupervised.
+      degraded.push("approval_effect_missing");
+      log("error", "gated action with no approval channel wired → refusing to execute", {
+        key: decision.key,
+        classes: gates.approval.classes,
+      });
+      return finish({
+        effect: "approval",
+        ok: false,
+        spoke: false,
+        ref: null,
+        error: "gated action with no approval channel",
+        degraded,
+      });
+    }
+    if (!a.ok) {
+      log("warn", "approval request failed → holding the action", { key: decision.key, error: a.error });
+      return finish({ effect: "approval", ok: false, spoke: false, ref: a.ref, error: a.error, degraded });
+    }
+    const granted = a.ref && typeof a.ref === "object" ? a.ref.granted : undefined;
+    if (granted === false) {
+      log("warn", "approval declined → the action does not run", { key: decision.key });
+      return finish({ effect: "approval", ok: true, spoke: false, ref: a.ref, error: null, degraded });
+    }
+    if (granted !== true) {
+      // Pending is a legitimate terminal state for this pass: the approval will
+      // arrive as its own inbound event and re-enter the ladder.
+      degraded.push("approval_pending");
+      return finish({ effect: "approval", ok: true, spoke: false, ref: a.ref, error: null, degraded });
+    }
+  }
+
+  // 5. Thread arbitration. Exactly one agent answers a shared thread. Fails OPEN
+  //    on a 3s timeout (a down coordination plane must not silence the agent),
+  //    and the fail-open is recorded rather than assumed.
+  if (gates.arbitration) {
+    const t = await runEffect(effects.arbitrate, "arbitrate", {
+      decision,
+      candidate: o.candidate,
+      scope: gates.arbitration.scope,
+      resource: gates.arbitration.resource,
+    });
+    if (t.missing) {
+      degraded.push("arbitration_effect_missing");
+      log("warn", "no arbitration wired for a shared-thread reply — risking a double answer", {
+        key: decision.key,
+      });
+    } else if (!t.ok) {
+      degraded.push("arbitration_failed_open");
+      log("warn", "arbitration call failed → proceeding fail-open", { key: decision.key, error: t.error });
+    } else {
+      const may = t.ref && typeof t.ref === "object" ? t.ref.mayReply : true;
+      if (t.ref && t.ref.failedOpen) {
+        degraded.push("arbitration_failed_open");
+        log("warn", "arbitration timed out → proceeding fail-open", { key: decision.key });
+      }
+      if (may === false) {
+        log("warn", "another agent holds this thread → standing down", { key: decision.key });
+        return finish({
+          effect: "arbitration",
+          ok: true,
+          spoke: false,
+          ref: t.ref,
+          error: null,
+          degraded,
+        });
+      }
+    }
+  }
+
+  // 6. The effect.
+  const name = EFFECT_FOR[decision.disposition] || null;
+  if (!name) {
+    log("error", `no effect mapping for disposition ${decision.disposition}`, { key: decision.key });
+    return finish({
+      effect: null,
+      ok: false,
+      spoke: false,
+      ref: null,
+      error: `unmapped disposition ${decision.disposition}`,
+      degraded,
+    });
+  }
+  const r = await runEffect(effects[name], name, { decision, candidate: o.candidate });
+  if (r.missing) {
+    degraded.push(`${name}_effect_missing`);
+    log("error", `no \`${name}\` effect wired — the event was decided but not acted on`, { key: decision.key });
+  } else if (!r.ok) {
+    log("error", `${name} effect failed`, { key: decision.key, error: r.error });
+  }
+
+  return finish({
+    effect: name,
+    ok: r.ok,
+    spoke: r.ok && SPEAKING.includes(decision.disposition),
+    ref: r.ref,
+    error: r.error,
+    degraded,
+    costCents: r.ref && typeof r.ref === "object" ? r.ref.costCents : undefined,
+  });
+}
+
+export default { drive, EFFECT_FOR };

package/lib/execution/drive.test.mjs

@@ -0,0 +1,270 @@
+/**
+ * drive.test.mjs — sequencing, gates, and the fail-open-but-never-silent rule.
+ * Run: node --test lib/execution/drive.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { drive, EFFECT_FOR } from "./drive.mjs";
+
+const NOW = Date.parse("2026-08-11T12:00:00Z");
+
+/**
+ * Collect journal rows instead of writing them, and swallow nothing.
+ *
+ * Overrides are WRAPPED in the same recorder as the defaults — an override that
+ * forgot to record would make `names()` silently under-report and turn a real
+ * assertion into a false pass. Passing `undefined` for a key removes the effect
+ * entirely (that is how the "not wired" cases are expressed).
+ */
+function harness(over = {}) {
+  const rows = [];
+  const logs = [];
+  const calls = [];
+  const defaults = {
+    react: async () => ({ ok: true, ref: { messageId: "m1" } }),
+    schedule: async () => ({ ok: true, ref: { id: "q1" } }),
+    delegate: async () => ({ ok: true, ref: { id: "h1" } }),
+    escalate: async () => ({ ok: true, ref: { id: "e1" } }),
+    propose: async () => ({ ok: true, ref: { proposed: true } }),
+    requestApproval: async () => ({ ok: true, ref: { granted: true } }),
+    arbitrate: async () => ({ ok: true, ref: { mayReply: true } }),
+    reportDrift: async () => ({ ok: true }),
+  };
+  const effects = {};
+  for (const name of Object.keys(defaults)) {
+    const impl = Object.prototype.hasOwnProperty.call(over, name) ? over[name] : defaults[name];
+    if (typeof impl !== "function") continue; // explicitly "not wired"
+    effects[name] = async (a) => { calls.push([name, a]); return impl(a); };
+  }
+  return {
+    rows, logs, calls, effects,
+    opts: {
+      effects,
+      nowMs: NOW,
+      append: (_p, r) => { rows.push(r); return true; },
+      log: (level, msg, attrs) => logs.push({ level, msg, attrs }),
+      candidate: { ids: { channelId: "c1" }, entityId: "m1" },
+    },
+    names: () => calls.map((c) => c[0]),
+  };
+}
+
+const REACT = {
+  key: "messaging.send#1", thread: "messaging:c1:m1", surface: "dm",
+  disposition: "react_now", reason: "directed_now", why: ["directed"], rung: 0, gates: {},
+};
+
+test("the decision is journaled BEFORE the effect runs", async () => {
+  const h = harness({
+    react: async () => { assert.equal(h.rows.length, 1, "reasoning must be on disk before the side effect"); return { ok: true }; },
+  });
+  await drive(REACT, h.opts);
+  assert.equal(h.rows[0].event, "decision");
+  assert.equal(h.rows[1].event, "outcome");
+});
+
+test("each disposition invokes its own effect, and only that one", async () => {
+  for (const [disposition, effect] of Object.entries(EFFECT_FOR)) {
+    const h = harness();
+    await drive({ ...REACT, disposition, gates: {} }, h.opts);
+    assert.deepEqual(h.names(), [effect], `${disposition} → ${effect}`);
+  }
+});
+
+test("an ignore is RECORDED as a completed outcome, not skipped", async () => {
+  const h = harness();
+  const r = await drive({ ...REACT, disposition: "ignore", reason: "duplicate" }, h.opts);
+  assert.equal(r.ok, true);
+  assert.equal(r.effect, "none");
+  assert.equal(r.spoke, false);
+  assert.deepEqual(h.names(), [], "no effect runs");
+  assert.equal(h.rows.length, 2, "but both the decision and the outcome are written");
+  assert.equal(h.rows[1].disposition, "ignore");
+  assert.equal(h.rows[1].ok, true, "an ignore is a success, not a failure");
+});
+
+test("`spoke` is true only when the agent actually replied", async () => {
+  const spoke = await drive(REACT, harness().opts);
+  assert.equal(spoke.spoke, true);
+  for (const d of ["schedule", "delegate", "escalate"]) {
+    const r = await drive({ ...REACT, disposition: d }, harness().opts);
+    assert.equal(r.spoke, false, `${d} does not deepen a reply chain`);
+  }
+});
+
+test("a failed effect does not count as speaking", async () => {
+  const h = harness({ react: async () => ({ ok: false, error: "network down" }) });
+  const r = await drive(REACT, h.opts);
+  assert.equal(r.ok, false);
+  assert.equal(r.spoke, false, "a failed send must not gag the next attempt via the chain guard");
+});
+
+// ── gates ──────────────────────────────────────────────────────────────────
+
+test("a gated action is approved BEFORE the effect runs", async () => {
+  const h = harness();
+  await drive({ ...REACT, gates: { approval: { required: true, classes: ["external"] } } }, h.opts);
+  assert.deepEqual(h.names(), ["requestApproval", "react"]);
+  assert.deepEqual(h.calls[0][1].classes, ["external"]);
+});
+
+test("a DECLINED approval stops the action, and is not an error", async () => {
+  const h = harness({ requestApproval: async () => ({ ok: true, ref: { granted: false } }) });
+  const r = await drive({ ...REACT, gates: { approval: { required: true, classes: ["financial"] } } }, h.opts);
+  assert.deepEqual(h.names(), ["requestApproval"]);
+  assert.equal(r.ok, true, "a human saying no is a working system");
+  assert.equal(r.spoke, false);
+});
+
+test("a PENDING approval ends the pass without acting", async () => {
+  const h = harness({ requestApproval: async () => ({ ok: true, ref: { granted: undefined, id: "ap1" } }) });
+  const r = await drive({ ...REACT, gates: { approval: { required: true, classes: ["external"] } } }, h.opts);
+  assert.deepEqual(h.names(), ["requestApproval"]);
+  assert.ok(r.degraded.includes("approval_pending"));
+});
+
+test("a gated action with NO approval channel FAILS CLOSED and screams", async () => {
+  // The one place fail-open would let an agent email the world unsupervised.
+  const h = harness({ requestApproval: undefined });
+  const r = await drive({ ...REACT, gates: { approval: { required: true, classes: ["external"] } } }, h.opts);
+  assert.equal(r.ok, false);
+  assert.deepEqual(h.names(), [], "the action never ran");
+  assert.ok(h.logs.some((l) => l.level === "error" && /no approval channel/.test(l.msg)));
+});
+
+test("a failed approval REQUEST holds the action rather than proceeding", async () => {
+  const h = harness({ requestApproval: async () => { throw new Error("hq unreachable"); } });
+  const r = await drive({ ...REACT, gates: { approval: { required: true, classes: ["irreversible"] } } }, h.opts);
+  assert.equal(r.ok, false);
+  assert.deepEqual(h.names(), ["requestApproval"], "it asked, and stopped when asking failed");
+  assert.equal(h.names().includes("react"), false, "the gated action must NOT run unapproved");
+  assert.match(r.error, /hq unreachable/);
+});
+
+test("losing the thread lease stands the agent down, quietly and correctly", async () => {
+  const h = harness({ arbitrate: async () => ({ ok: true, ref: { mayReply: false } }) });
+  const r = await drive({ ...REACT, gates: { arbitration: { scope: "thread-ownership", resource: "t" } } }, h.opts);
+  assert.deepEqual(h.names(), ["arbitrate"]);
+  assert.equal(r.spoke, false);
+  assert.equal(r.ok, true, "another agent answering is a working system");
+});
+
+test("arbitration FAILS OPEN — a down coordination plane must not silence the agent", async () => {
+  for (const arbitrate of [
+    async () => { throw new Error("timeout"); },
+    async () => ({ ok: true, ref: { mayReply: true, failedOpen: true } }),
+  ]) {
+    const h = harness({ arbitrate });
+    const r = await drive({ ...REACT, gates: { arbitration: { scope: "thread-ownership" } } }, h.opts);
+    assert.ok(h.names().includes("react"), "the agent still answered");
+    assert.ok(r.degraded.includes("arbitration_failed_open"));
+    assert.ok(h.logs.length > 0, "and the fail-open was LOGGED, not assumed");
+  }
+});
+
+test("gates run in order: approval, then arbitration, then the effect", async () => {
+  const h = harness();
+  await drive({
+    ...REACT,
+    gates: { approval: { required: true, classes: ["external"] }, arbitration: { scope: "thread-ownership" } },
+  }, h.opts);
+  assert.deepEqual(h.names(), ["requestApproval", "arbitrate", "react"]);
+});
+
+// ── observe-only + drift ───────────────────────────────────────────────────
+
+test("observe-only proposes instead of acting", async () => {
+  const h = harness();
+  const r = await drive({ ...REACT, observeOnly: true }, h.opts);
+  assert.deepEqual(h.names(), ["propose"]);
+  assert.equal(r.effect, "propose");
+  assert.equal(r.spoke, false);
+});
+
+test("observe-only with no proposal sink degrades loudly but still decides", async () => {
+  const h = harness({ propose: undefined });
+  const r = await drive({ ...REACT, observeOnly: true }, h.opts);
+  assert.equal(r.ok, true);
+  assert.ok(r.degraded.includes("propose_effect_missing"));
+  assert.ok(h.logs.some((l) => /nowhere to be proposed/.test(l.msg)));
+});
+
+test("drift is reported even on an ignore path, and never blocks the action", async () => {
+  const stale = { ...REACT, disposition: "ignore", reason: "mandate_stale", drift: { kind: "mandate_stale" } };
+  const h1 = harness();
+  await drive(stale, h1.opts);
+  assert.deepEqual(h1.names(), ["reportDrift"]);
+
+  // A failing drift report must not stop real work.
+  const h2 = harness({ reportDrift: async () => { throw new Error("disk full"); } });
+  const r = await drive({ ...REACT, drift: { kind: "uncovered_event" } }, h2.opts);
+  assert.ok(h2.names().includes("react"), "the reply still went out");
+  assert.ok(r.degraded.some((d) => /drift_report_failed/.test(d)));
+  assert.ok(h2.logs.some((l) => /drift report failed/.test(l.msg)));
+});
+
+// ── failure modes ──────────────────────────────────────────────────────────
+
+test("a missing effect is an ERROR, never a silent successful no-op", async () => {
+  const h = harness({ react: undefined });
+  const r = await drive(REACT, h.opts);
+  assert.equal(r.ok, false, "a missing responder is an outage, not a no-op");
+  assert.ok(r.degraded.includes("react_effect_missing"));
+  assert.ok(h.logs.some((l) => l.level === "error" && /no `react` effect wired/.test(l.msg)));
+  assert.equal(h.rows[1].ok, false, "and the journal records the failure");
+});
+
+test("a throwing effect is captured, journaled, and does not propagate", async () => {
+  const h = harness({ schedule: async () => { throw new Error("disk full"); } });
+  const r = await drive({ ...REACT, disposition: "schedule" }, h.opts);
+  assert.equal(r.ok, false);
+  assert.match(r.error, /disk full/);
+  assert.equal(h.rows[1].error, "disk full");
+  assert.ok(h.logs.some((l) => l.level === "error"));
+});
+
+test("an effect returning a bare value is treated as success", async () => {
+  const h = harness({ schedule: async () => "queued-1" });
+  const r = await drive({ ...REACT, disposition: "schedule" }, h.opts);
+  assert.equal(r.ok, true);
+  assert.equal(r.ref, "queued-1");
+});
+
+test("decision-level degradations are logged, not just carried", async () => {
+  const h = harness();
+  await drive({ ...REACT, degraded: ["history_absent", "unknown_surface:x"] }, h.opts);
+  assert.equal(h.logs.filter((l) => /decision degraded/.test(l.msg)).length, 2);
+});
+
+test("a journal write failure is reported but does not abort the action", async () => {
+  const h = harness();
+  const r = await drive(REACT, { ...h.opts, append: () => false });
+  assert.ok(h.names().includes("react"), "the work still happened");
+  assert.ok(r.degraded.includes("journal_decision_write_failed"));
+  assert.ok(h.logs.some((l) => l.level === "error" && /unexplained/.test(l.msg)));
+});
+
+test("drive with no decision is an error, not a crash", async () => {
+  for (const d of [null, undefined, "nonsense", 42]) {
+    const r = await drive(d, harness().opts);
+    assert.equal(r.ok, false);
+    assert.equal(r.error, "no decision");
+  }
+});
+
+test("an unmapped disposition fails loudly instead of doing nothing", async () => {
+  const h = harness();
+  const r = await drive({ ...REACT, disposition: "teleport" }, h.opts);
+  assert.equal(r.ok, false);
+  assert.match(r.error, /unmapped disposition/);
+});
+
+test("with no effects wired at all, nothing throws and everything is recorded", async () => {
+  const rows = [];
+  const r = await drive(REACT, { effects: {}, nowMs: NOW, append: (_p, x) => { rows.push(x); return true; }, log: () => {} });
+  assert.equal(r.ok, false);
+  assert.equal(rows.length, 2);
+});