@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/execution/drive.test.mjs

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

package/lib/execution/effects.test.mjs

@@ -1,344 +0,0 @@
-/**
- * effects.test.mjs — the on-disk side effects, and the format contract with the
- * machinery that already consumes them.
- * Run: node --test lib/execution/effects.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { parseQueueItems } from "../backlog.mjs";
-import {
-  scheduleToQueue,
-  writeDrift,
-  writeProposal,
-  defaultEffects,
-  errText,
-  INBOUND_QUEUE_REL,
-  DRIFT_REL,
-  PROPOSED_REL,
-} from "./effects.mjs";
-
-const NOW = Date.parse("2026-08-11T12:00:00Z");
-function tmp() { return mkdtempSync(join(tmpdir(), "exec-effects-")); }
-
-const DECISION = {
-  key: "board.item.assigned#42",
-  thread: "board:-:t1",
-  surface: "task_assigned",
-  disposition: "schedule",
-  reason: "not_respondable",
-  tier: "T0",
-  rung: 3,
-  obligationKey: "react.task_assigned",
-  why: ["directed: assignee on task_assigned (tier T0)", "task_assigned is not a conversational surface"],
-};
-
-test("a scheduled item is parseable by the EXISTING backlog parser", () => {
-  // The whole reuse claim rests on this: the daemon's 2-minute sweep already
-  // reads this format, so scheduling needs no dispatcher change.
-  const root = tmp();
-  try {
-    const r = scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
-    assert.equal(r.ok, true);
-    const body = readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8");
-    const items = parseQueueItems(body, "inbound.yaml");
-    assert.equal(items.length, 1);
-    assert.equal(items[0].status, "open");
-    assert.equal(items[0].priority, "high", "a T0 event is high priority");
-    assert.ok(items[0].id, "the id must survive — the claim subsystem is gated on it");
-    assert.ok(items[0].title.includes("task_assigned"));
-    assert.ok(items[0].next_action);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("the reasoning travels WITH the queued work", () => {
-  const root = tmp();
-  try {
-    scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
-    const body = readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8");
-    assert.match(body, /why:/);
-    assert.match(body, /tier T0/, "a queue item whose provenance is a mystery is one nobody actions");
-    assert.match(body, /event_key: "board.item.assigned#42"/);
-    assert.match(body, /obligation_key: "react.task_assigned"/);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("scheduling the same decision twice does NOT double-queue", () => {
-  const root = tmp();
-  try {
-    const a = scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
-    const b = scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
-    assert.equal(a.ref.deduped, false);
-    assert.equal(b.ref.deduped, true);
-    const items = parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q");
-    assert.equal(items.length, 1);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("distinct events append distinct items", () => {
-  const root = tmp();
-  try {
-    scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
-    scheduleToQueue({ ...DECISION, key: "board.item.assigned#43" }, { agentRoot: root, nowMs: NOW });
-    const items = parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q");
-    assert.equal(items.length, 2);
-    assert.notEqual(items[0].id, items[1].id);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("the dedupe check anchors on a whole `id` key, not a substring", () => {
-  const root = tmp();
-  try {
-    // `#4` must not be seen as already present because `#42` is.
-    scheduleToQueue({ ...DECISION, key: "board.item.assigned#42" }, { agentRoot: root, nowMs: NOW });
-    const r = scheduleToQueue({ ...DECISION, key: "board.item.assigned#4" }, { agentRoot: root, nowMs: NOW });
-    assert.equal(r.ref.deduped, false, "a prefix collision must not swallow a distinct event");
-    assert.equal(parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q").length, 2);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("a hostile surface/reason cannot inject YAML lines", () => {
-  const root = tmp();
-  try {
-    scheduleToQueue(
-      { ...DECISION, key: "k1", surface: 'x"\nstatus: blocked\npriority: "critical', why: ["a\nb"] },
-      { agentRoot: root, nowMs: NOW },
-    );
-    const items = parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q");
-    assert.equal(items.length, 1, "the injected `status: blocked` must not become a real key");
-    assert.equal(items[0].status, "open");
-    assert.equal(items[0].priority, "high");
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("a lower-tier or downgraded event queues at normal priority", () => {
-  const root = tmp();
-  try {
-    scheduleToQueue({ ...DECISION, key: "k1", tier: "T1" }, { agentRoot: root, nowMs: NOW });
-    scheduleToQueue({ ...DECISION, key: "k2", reason: "actor_flood" }, { agentRoot: root, nowMs: NOW });
-    const items = parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q");
-    assert.deepEqual(items.map((i) => i.priority), ["normal", "normal"]);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("an unwritable root is reported, not thrown", () => {
-  const r = scheduleToQueue(DECISION, { agentRoot: "/proc/nonexistent-cannot-create", nowMs: NOW });
-  assert.equal(r.ok, false);
-  assert.ok(r.error, "the caller must be told the work was not queued");
-});
-
-test("drift and proposals are appended as JSONL with their provenance", () => {
-  const root = tmp();
-  try {
-    writeDrift({ kind: "uncovered_event", detail: { surface: "dm" } }, { agentRoot: root, nowMs: NOW, decision: DECISION });
-    const drift = JSON.parse(readFileSync(join(root, DRIFT_REL), "utf-8").trim());
-    assert.equal(drift.kind, "uncovered_event");
-    assert.equal(drift.key, "react.task_assigned");
-    assert.equal(drift.source, "execution-ladder");
-
-    writeProposal({ ...DECISION, disposition: "react_now" }, { agentRoot: root, nowMs: NOW });
-    const prop = JSON.parse(readFileSync(join(root, PROPOSED_REL), "utf-8").trim());
-    assert.equal(prop.disposition, "react_now");
-    assert.deepEqual(prop.why, DECISION.why, "the observe-only window is only readable if the reasoning is kept");
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("writeDrift tolerates a malformed drift record", () => {
-  const root = tmp();
-  try {
-    assert.equal(writeDrift(null, { agentRoot: root, nowMs: NOW }).ok, true);
-    const row = JSON.parse(readFileSync(join(root, DRIFT_REL), "utf-8").trim());
-    assert.equal(row.kind, "unknown");
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("defaultEffects wires every effect EXCEPT react, which the caller must supply", () => {
-  const root = tmp();
-  try {
-    const e = defaultEffects({ agentRoot: root });
-    for (const name of ["schedule", "delegate", "escalate", "requestApproval", "arbitrate", "reportDrift", "propose"]) {
-      assert.equal(typeof e[name], "function", `${name} should be wired`);
-    }
-    // `react` is deliberately absent: the dispatcher owns session spawning and
-    // this module must not grow a second spawner. A caller that forgets gets a
-    // loud `react_effect_missing`, which is the correct failure.
-    assert.equal(e.react, undefined);
-    assert.equal(typeof defaultEffects({ agentRoot: root, react: async () => ({ ok: true }) }).react, "function");
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("the default schedule effect writes through to the queue", async () => {
-  const root = tmp();
-  try {
-    const e = defaultEffects({ agentRoot: root, nowMs: NOW });
-    const r = await e.schedule({ decision: DECISION });
-    assert.equal(r.ok, true);
-    assert.ok(existsSync(join(root, INBOUND_QUEUE_REL)));
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("the default propose + reportDrift effects write through", async () => {
-  const root = tmp();
-  try {
-    const e = defaultEffects({ agentRoot: root, nowMs: NOW });
-    assert.equal((await e.propose({ decision: DECISION })).ok, true);
-    assert.equal((await e.reportDrift({ drift: { kind: "budget_breach" }, decision: DECISION })).ok, true);
-    assert.ok(existsSync(join(root, PROPOSED_REL)));
-    assert.ok(existsSync(join(root, DRIFT_REL)));
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-// ───────────────────────────────────────────────────────────────────────────
-// The joint: does the escalate effect actually reach the org?
-// ───────────────────────────────────────────────────────────────────────────
-
-import { writeFileSync as _wf, mkdirSync as _mk } from "node:fs";
-
-/** An agent root with a real config/org.yaml, as `maestro setup` writes it. */
-function enrolledRoot() {
-  const root = mkdtempSync(join(tmpdir(), "effects-org-"));
-  _mk(join(root, "config"), { recursive: true });
-  _wf(
-    join(root, "config", "org.yaml"),
-    "org:\n  cohort:\n    enabled: true\n    base: https://example.invalid\n    orgId: org_t\n    token: tok_t\n",
-  );
-  return root;
-}
-
-test("escalate resolves the org binding from the agent root — `agentRoot` alone used to be ignored", async () => {
-  // `client.call()` reads `o.base` and nothing else; `defaultEffects` is built by
-  // the daemon as `{agentRoot, me, react}`. So every network effect returned
-  // BAD_REQUEST "missing base" before a byte left the machine: the ladder could
-  // decide to escalate and could never escalate.
-  const root = enrolledRoot();
-  const seen = [];
-  const orig = globalThis.fetch;
-  globalThis.fetch = async (url, init) => {
-    seen.push({ url: String(url), body: JSON.parse(init.body) });
-    return new Response(JSON.stringify({ ok: true, result: { id: "oq_1" } }), {
-      status: 200, headers: { "content-type": "application/json" },
-    });
-  };
-  try {
-    const eff = defaultEffects({ agentRoot: root, me: "M-1" });
-    const r = await eff
-      .escalate({
-        decision: {
-          key: "approval.requested#1", surface: "approval", reason: "cannot_self_decide",
-          rung: 1, mechanism: "claude-skill", why: ["a", "b"],
-          options: ["approve it", "reject it"],
-        },
-        candidate: { ids: { taskId: "T-1" } },
-      });
-    {
-        assert.equal(r.ok, true, r.error || "escalate failed");
-        // The escalation now has TWO legs — the record, and the person. The
-        // person leg reads the directory + rooms first, so the request this test
-        // is about is found by name rather than by being the only one.
-        const ask = seen.find((s) => /escalation\.ask$/.test(s.url));
-        assert.ok(ask, "no escalation.ask request was made");
-        assert.equal(ask.body.options.length, 2);
-        assert.equal(typeof ask.body.context, "string", "hq's `context` is a STRING");
-        assert.equal(ask.body.trigger, "cannot_self_decide");
-        assert.ok(ask.body.question, "hq requires a question");
-        assert.ok(r.ref.engagement, "the escalation must report what it did about telling a human");
-    }
-  } finally {
-    globalThis.fetch = orig;
-  }
-});
-
-test("fewer than two options falls back to escalation.create WITH a target", async () => {
-  const root = enrolledRoot();
-  const seen = [];
-  const orig = globalThis.fetch;
-  globalThis.fetch = async (url, init) => {
-    seen.push({ url: String(url), body: JSON.parse(init.body) });
-    return new Response(JSON.stringify({ ok: true, result: { id: "esc_1" } }), {
-      status: 200, headers: { "content-type": "application/json" },
-    });
-  };
-  try {
-    const eff = defaultEffects({ agentRoot: root, me: "M-1" });
-    const r = await eff
-      .escalate({
-        decision: { key: "k", surface: "task_comment", reason: "stuck", why: ["x"], options: [] },
-        candidate: { ids: { taskId: "T-7" } },
-      });
-    {
-        assert.equal(r.ok, true);
-        assert.match(seen[0].url, /escalation\.create$/);
-        assert.ok(seen[0].body.title, "hq requires a title, not a `summary`");
-        assert.equal(seen[0].body.taskId, "T-7", "hq requires a taskId or channelId");
-    }
-  } finally {
-    globalThis.fetch = orig;
-  }
-});
-
-test("no options AND no target: no escalation ROW is attempted, and the failure names the human who was not reached", async () => {
-  const root = enrolledRoot();
-  const orig = globalThis.fetch;
-  const urls = [];
-  globalThis.fetch = async (url) => { urls.push(String(url)); return new Response("{}", { status: 200 }); };
-  try {
-    const eff = defaultEffects({ agentRoot: root, me: "M-1" });
-    const r = await eff
-      .escalate({ decision: { key: "k", surface: "approval", reason: "r", why: [], options: [] }, candidate: { ids: {} } });
-    {
-        assert.equal(r.ok, false);
-        assert.match(r.error, /needs a taskId or channelId/);
-        assert.match(r.error, /No escalation ROW was raised/);
-        // THE POINT OF THE CHANGE. It used to end at "Nothing was raised" — a
-        // true statement about a table that told nobody anything. The failure now
-        // has to account for the person as well, and only claims total failure
-        // when neither leg reached anyone.
-        assert.match(r.error, /nobody was engaged either/);
-        assert.match(r.error, /Nothing reached a human/);
-        assert.equal(r.ref.spoke, false);
-        assert.ok(
-          urls.every((u) => !/escalation\./.test(u)),
-          "an escalation.* call that cannot succeed must still not be made",
-        );
-    }
-  } finally {
-    globalThis.fetch = orig;
-  }
-});
-
-test("when the record cannot be raised but a PERSON is reached, the escalation succeeds — and says the row is missing", async () => {
-  const root = enrolledRoot();
-  const orig = globalThis.fetch;
-  globalThis.fetch = async () => new Response("{}", { status: 200 });
-  try {
-    const eff = defaultEffects({
-      agentRoot: root,
-      me: "M-1",
-      // The judgement is injected here; it is proved on its own terms in
-      // lib/org/engagement.test.mjs.
-      engageImpl: async () => ({ ok: true, engaged: true, outcome: "engaged", surface: "dm", decision: { targets: [{ memberId: "M-2", rung: "supervisory" }], reasonCode: "blocked:approval" } }),
-    });
-    const r = await eff.escalate({
-      decision: { key: "k", surface: "approval", reason: "r", why: [], options: [] },
-      candidate: { ids: {} },
-    });
-    assert.equal(r.ok, true, "a human heard about it — that is not a failure");
-    assert.equal(r.ref.spoke, true);
-    assert.deepEqual(r.ref.engagement.targets, ["M-2"]);
-    assert.deepEqual(r.ref.degraded, ["escalation_record_unraisable:k"]);
-  } finally {
-    globalThis.fetch = orig;
-  }
-});
-
-test("errText renders an RPC error frame as a line, never `[object Object]`", () => {
-  assert.equal(errText({ code: "BAD_REQUEST", message: "title is required" }), "BAD_REQUEST: title is required");
-  assert.equal(errText("plain"), "plain");
-  assert.equal(errText(null), null);
-  assert.notEqual(String(errText({ code: "X" })), "[object Object]");
-});