@cohortapp/agent-sdk 2.4.0 → 2.5.0

package/bin/maestro.mjs

@@ -128,6 +128,13 @@ function create(targetName) {
     "ingest",
     "mcp",
     "services",
+    // archetypes/ is DATA that lib/archetype.mjs resolves as its own sibling
+    // (ARCHETYPES_DIR = <lib>/../archetypes). It ships in the npm tarball, but
+    // until it was listed here the copier left it behind, so resolveArchetype()
+    // threw for every lookup in a real agent repo and took the generate-*
+    // setup scripts down with it. Data and the code that resolves it travel
+    // together or neither works.
+    "archetypes",
     // lib/ holds shared framework primitives — singleton lock, cadence bus,
     // action executor, tool definitions — that scripts/ imports via relative
     // paths. Must travel with each agent repo so the relative imports work
@@ -755,6 +762,8 @@ const UPGRADE_PATHS = [
   // (e.g. ../../lib/cadence-bus.mjs from scripts/cadence/*) resolve in
   // every agent repo without needing @cohortapp/agent-sdk in node_modules.
   { path: "lib", mode: "smart" },
+  // Must travel with lib/ — see the note in the scaffold copy list above.
+  { path: "archetypes", mode: "smart" },
 ];
 
 function sha256File(p) {

package/lib/backlog.mjs

@@ -365,6 +365,41 @@ export function parseQueueItems(content, sourceFile = "") {
     const dispMatch = cleanBlock.match(/^\s*-?\s*"?disposition"?:\s*["']?(SELF|COLLABORATE|HANDOFF|NEEDS_REVIEW)["']?/m);
     if (dispMatch) item.disposition = dispMatch[1];
 
+    // `rung` — the execution rung `lib/execution/route.routeRung` chose and
+    // `lib/goals/loop.renderQueueItems` writes on every self-directed item.
+    // It was the ONE field the goal steward decided, audited, and wrote that no
+    // consumer read back: the daemon's backlog sweep dispatched every row as a
+    // plain session regardless, so the router's whole cost/blast-radius decision
+    // died on disk. Extracting it is what lets `sweepBacklog` size the session to
+    // the rung and name any mechanism the drain cannot honour.
+    const rungMatch = cleanBlock.match(/^\s*-?\s*"?rung"?:\s*["']?([0-5])["']?\s*$/m);
+    if (rungMatch) item.rung = Number(rungMatch[1]);
+
+    // --- what the work is ABOUT (execution-ladder provenance) --------------
+    // `lib/execution/effects.scheduleToQueue` writes `entity_id` / `source_ref`
+    // / `uses` / `context` onto every row the reactive ladder queues. They were
+    // the fields that made the difference between a row the drain could act on
+    // and one it could only read: without `entity_id` the dispatched session
+    // has no meeting/task/approval to name, and without `uses` no method to
+    // name it with. All optional — a goal-steward or hand-written row lacks
+    // them and behaves exactly as before.
+    const entityMatch = cleanBlock.match(/^\s*-?\s*"?entity_id"?:\s*["']?([^"'\n]*?)["']?\s*$/m);
+    const entityId = entityMatch?.[1]?.trim();
+    if (entityId) item.entity_id = entityId;
+    const srcRefMatch = cleanBlock.match(/^\s*-?\s*"?source_ref"?:\s*["']?([^"'\n]*?)["']?\s*$/m);
+    const srcRef = srcRefMatch?.[1]?.trim();
+    if (srcRef) item.source_ref = srcRef;
+    const usesMatch = cleanBlock.match(/^\s*-?\s*"?uses"?:\s*["']?([^"'\n]*?)["']?\s*$/m);
+    const usesRaw = usesMatch?.[1]?.trim();
+    if (usesRaw) item.uses = usesRaw.split(",").map((u) => u.trim()).filter(Boolean);
+    // `context:` is a quoted single-line scalar (scheduleToQueue collapses
+    // newlines precisely so this stays one line and cannot tear the block).
+    const ctxMatch = cleanBlock.match(/^\s*-?\s*"?context"?:\s*"(.*)"\s*$/m);
+    const ctx = ctxMatch?.[1];
+    if (ctx) item.context = ctx.replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    const sourceMatch = cleanBlock.match(/^\s*-?\s*"?source"?:\s*["']?([a-z0-9._-]+)["']?\s*$/m);
+    if (sourceMatch) item.source = sourceMatch[1];
+
     out.push(item);
   }
   return out;

package/lib/backlog.test.mjs

@@ -264,3 +264,39 @@ test("buildBacklogSkeleton: standalone (no orgContext) is byte-for-byte the arch
   const b = buildBacklogSkeleton(profile, IDENTITY, { date: "2026-06-01", orgContext: null });
   assert.deepEqual(a, b);
 });
+
+test("REGRESSION — parseQueueItems reads back the `rung` the goal steward wrote", () => {
+  // `lib/goals/loop.renderQueueItems` writes rung: on every self-directed item.
+  // Nothing read it back, so the daemon's sweep dispatched a rung-0 single-method
+  // call and a rung-5 subagent fan-out as the identical plain session: the
+  // router's whole cost/blast-radius decision died on disk.
+  const yaml = [
+    "queue: goals",
+    "items:",
+    "  - id: goal-x-2026-W33-1",
+    '    title: "Close the on_time_rate gap"',
+    "    status: open",
+    "    priority: normal",
+    '    next_action: "Close the on_time_rate gap"',
+    "    source: goal-steward",
+    "    advances: [board-on-time-delivery]",
+    "    expected_delta: 10",
+    "    obligation_key: outcome.board-on-time-delivery",
+    "    disposition: SELF",
+    "    rung: 3",
+    "    created: 2026-08-11",
+  ].join("\n");
+  const [item] = parseQueueItems(yaml, "goals.yaml");
+  assert.equal(item.rung, 3);
+  assert.equal(item.source, "goal-steward");
+  assert.equal(item.disposition, "SELF");
+  assert.deepEqual(item.advances, ["board-on-time-delivery"]);
+  assert.equal(item.expected_delta, 10);
+  assert.equal(item.obligation_key, "outcome.board-on-time-delivery");
+});
+
+test("a hand-written item with no rung is unchanged (rung stays absent, not 0)", () => {
+  const yaml = ['items:', '  - id: seeded-1', '    title: "Tidy docs"', "    status: open", '    next_action: "tidy"'].join("\n");
+  const [item] = parseQueueItems(yaml, "backlog.yaml");
+  assert.equal("rung" in item, false, "absence must not become rung 0 — that is the cheapest rung");
+});

package/lib/channels/contract.mjs

@@ -81,6 +81,7 @@ export const EVENT_KINDS = Object.freeze([
   "decision",
   "escalation",
   "handoff",
+  "calendar",
   "email",
 ]);
 

package/lib/channels/contract.test.mjs

@@ -27,7 +27,7 @@ import { ChannelMessage } from "./index.mjs";
 test("EVENT_KINDS is the closed set from the design", () => {
   // Two groups. The five CHAT kinds are the original design set and must not
   // move — `message` in particular is the default and the byte-compat anchor.
-  // The ten WORK-SURFACE kinds were added for wide org inbound
+  // The eleven WORK-SURFACE kinds were added for wide org inbound
   // (lib/org/inbound/surfaces.mjs): an org agent is addressed through board
   // items, approvals, decisions, docs and mail as well as chat, and `kind` is
   // the routing hint the daemon classifier reads. Adding one here without a
@@ -35,6 +35,7 @@ test("EVENT_KINDS is the closed set from the design", () => {
   // lib/org/inbound/project.test.mjs.
   assert.deepEqual([...EVENT_KINDS].sort(), [
     "approval",
+    "calendar",
     "call",
     "channel_cc",
     "decision",

package/lib/channels/inbox-item.mjs

@@ -183,6 +183,60 @@ export function eventToInboxItem(ev) {
   // this seam existed (it never wrote a `kind` field).
   if (kind !== DEFAULT_EVENT_KIND) item.kind = kind;
 
+  // THE CHAIN KIND. `ev.cohort` is the wide-inbound projection's provenance
+  // block (lib/org/inbound/project.mjs) and this converter drops unknown keys,
+  // so the hq event kind — `item.blocked`, `item.completed`, `item.commented` —
+  // has always died here. The SURFACE survives (in `kind` and in `raw_ref`), but
+  // ten distinct board kinds share the surface `task_comment`, so on the poll
+  // lane they all arrive indistinguishable.
+  //
+  // That is not cosmetic: `lib/execution/match.kindAliases` derives an
+  // obligation's bindable tokens from the candidate kind, so an obligation
+  // written `{topic: task, kind: blocked}` BINDS when the event arrives on the
+  // push/chain lane and reads UNCOVERED when the very same event arrives on the
+  // poll lane — capping it at rung ≤1 and filing a bogus coverage-gap proposal.
+  // §6.1 has both lanes converging on the same events, so which behaviour you
+  // got was a race. Measured, on all four board kinds.
+  //
+  // One extra scalar closes it. Absent for every non-org producer, so nothing
+  // else changes shape.
+  const cohort = ev.cohort && typeof ev.cohort === "object" ? ev.cohort : null;
+  const chainKind = cohort ? cohort.event_kind : null;
+  if (typeof chainKind === "string" && chainKind) {
+    item.event_kind = sanitizeYamlField(chainKind);
+  }
+
+  // THE DIRECTEDNESS REASON, for the same reason and by the same rule.
+  //
+  // `lib/org/inbound/directedness.mjs` does real work to answer WHY an event is
+  // this seat's — `reviewer`, `assignee`, `waiting_on`, `mention`, `channel` —
+  // and until this line the answer died here too. `intake.fromInboxItem` then
+  // RE-GUESSED it from a per-surface default table, so an approval blocking a
+  // task the seat REVIEWS was journalled as "directed: approver on approval".
+  // That is not a rounding error: `disposition.tierOf` maps the reason onto the
+  // T0/T1 tier that drives the whole ladder, so a guess that lands on a
+  // different tier than the truth changes the decision. Here it was lucky (both
+  // T0); for a `channel`-tier approval the guess would have promoted T1→T0 and
+  // made the agent jump on something it was only entitled to notice.
+  //
+  // Carried as a scalar, absent for every non-org producer.
+  const reason = cohort ? cohort.reason : null;
+  if (typeof reason === "string" && reason) {
+    item.direct_reason = sanitizeYamlField(reason);
+  }
+
+  // The surface's OWN scope id — the task an approval blocks, the decision a
+  // comment is on. `channel_id` only ever carries a real Cohort channel
+  // (project.mjs is explicit that putting an entity id there would make a reply
+  // post-to-a-non-channel), so a non-channel surface arrived at the ladder with
+  // no id for its subject at all. `effects.escalate` needs one: hq's
+  // `escalation.create` requires a `taskId` or `channelId` and refuses to invent
+  // either.
+  const scopeId = cohort ? cohort.scope_id : null;
+  if (typeof scopeId === "string" && scopeId) {
+    item.scope_id = sanitizeYamlField(scopeId);
+  }
+
   // Carry attachments through when present (voice notes, media). The legacy
   // YAML writer (scripts/poller/utils.mjs) renders these when shaped as
   // { id, name, mimetype, size }; adapters that produce contract-style

package/lib/comms/send-gate.mjs

@@ -94,12 +94,22 @@ export const BANNED_OPENERS = Object.freeze([
 
 /* ────────────────────────── recipient classification ─────────────────────── */
 
+/**
+ * A Cohort entity id (channel or member). hq mints cuid/cuid2 — a lowercase
+ * alphanumeric token — and also accepts uuid-shaped ids on some rows. Anchored
+ * and length-floored so it can never match an email local part or a phone number.
+ */
+const COHORT_ID = /^(?:[a-z][a-z0-9]{14,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+
+/** One-shot guard so the org-recipient warning is not emitted per message. */
+let _warnedExternalOrgRecipient = false;
+
 /**
  * Decide whether a recipient is INTERNAL (workspace member / internal domain) or
  * EXTERNAL (everyone else). Default-deny: anything unrecognised is external, so
  * the fail-CLOSED branch covers the unknown case.
  *
- * @param {string} channel  slack|telegram|whatsapp|sms|email|voice|document
+ * @param {string} channel  cohort|slack|telegram|whatsapp|sms|email|voice|document
  * @param {string} recipient
  * @param {string[]} internalDomains  lower-cased email domains treated internal
  * @returns {"internal"|"external"}
@@ -109,6 +119,35 @@ export function classifyRecipient(channel, recipient, internalDomains = []) {
   if (!r) return "external"; // no recipient ⇒ treat conservatively
 
   switch (channel) {
+    // Both spellings are live in the tree: `lib/org/messaging.sendMessage` says
+    // "cohort", `lib/org/tool-surface` says "cohort-org". They are the same
+    // surface and must classify the same way, so both are listed rather than
+    // one of them being quietly wrong.
+    case "cohort":
+    case "cohort-org":
+      // The agent's OWN org workspace. `lib/org/messaging.sendMessage` screens
+      // every outbound org message as `{channel:"cohort", recipient:<channelId>}`,
+      // and a Cohort channel/member id is a row inside the org the agent is a
+      // member of — hq's ACL is what put it in reach. There is no such thing as
+      // an "external" Cohort channel id.
+      //
+      // WITHOUT THIS CASE the switch fell to `default`, the id has no "@", and
+      // the function returned "external" for every message the agent posts into
+      // its own workspace. Two live consequences, both observed:
+      //   1. `failPolicy` fails CLOSED on any policy-file fault, so a missing or
+      //      malformed `policies/*.yaml` silently gags the agent in every space
+      //      and DM it is in. A public #general thread reply was blocked with
+      //      "failing closed for external recipient".
+      //   2. Every `information-barriers.yaml` wall scoped
+      //      `recipient_class: external` applied to internal org chat, and the
+      //      AI-disclosure posture resolved on the external branch.
+      //
+      // Scoped deliberately: an id-shaped recipient is internal by construction;
+      // anything else on this channel (an email address handed to the org mailer)
+      // still falls through to the domain test below, so a genuinely external
+      // address is NOT laundered into "internal" by arriving on this channel.
+      if (COHORT_ID.test(r)) return "internal";
+      break;
     case "slack":
     case "telegram":
       // Slack channel/DM ids (C…, D…, G…, U…) and Telegram chat ids live inside
@@ -388,6 +427,22 @@ export async function screenOutbound({
   const recipientClass = classifyRecipient(channel, recipient, internalDomains);
   const isExternal = recipientClass === "external";
 
+  // NEVER SILENT. An org-surface recipient that still classifies EXTERNAL is
+  // the surprising case, and it is the expensive one: it flips `failPolicy` to
+  // fail-CLOSED, so a policy-file fault gags the agent everywhere in its own
+  // workspace with nothing in the log but a per-message "blocked" reason. Say
+  // it once, at the moment the classification is taken.
+  if (isExternal && (channel === "cohort" || channel === "cohort-org") && !_warnedExternalOrgRecipient) {
+    _warnedExternalOrgRecipient = true;
+    try {
+      console.warn(
+        `[send-gate] org recipient "${recipient}" did not match a Cohort entity id — screening it as EXTERNAL. ` +
+          "Required-policy faults will now fail CLOSED for this surface (the agent goes quiet rather than posts). " +
+          "If this is a real org channel/member id, COHORT_ID in lib/comms/send-gate.mjs needs to learn its shape.",
+      );
+    } catch { /* never throw from logging */ }
+  }
+
   // failPolicy: for a missing/unreadable REQUIRED policy file. External → block,
   // internal → open (so transient FS faults never wall off internal ops chatter).
   const failPolicy = (file) =>

package/lib/comms/send-gate.test.mjs

@@ -549,6 +549,62 @@ describe("classifyRecipient", () => {
   it("treats empty recipient as external (conservative)", () => {
     assert.equal(classifyRecipient("email", ""), "external");
   });
+
+  // REGRESSION — observed live, 2026-08-11, tracing a public-space thread reply
+  // end to end for a real seat. `sendMessage` screens every org post as
+  // {channel:"cohort", recipient:<channelId>}; with no `cohort` case the switch
+  // fell through and a cuid has no "@", so the agent's OWN #general channel
+  // classified EXTERNAL. That flipped `failPolicy` to fail-closed and the reply
+  // was refused with: outbound policy "policies/ai-disclosure.yaml" unreadable
+  // — failing closed for external recipient.
+  it("classifies Cohort channel/member ids as internal — the agent's own workspace", () => {
+    // The literal ids from the live trace.
+    assert.equal(classifyRecipient("cohort", "cmqs5i86p0008ta0129ql6rv9"), "internal"); // #general
+    assert.equal(classifyRecipient("cohort", "cmqh0tcml004ihhl6zev6ocb5"), "internal"); // a member (DM)
+    // lib/org/tool-surface.mjs spells the same surface "cohort-org".
+    assert.equal(classifyRecipient("cohort-org", "cms6vuxjw00a7mx01ljlyrluu"), "internal");
+    // uuid-shaped org ids too.
+    assert.equal(
+      classifyRecipient("cohort", "3f2504e0-4f89-11d3-9a0c-0305e82c3301"),
+      "internal",
+    );
+  });
+
+  it("does NOT launder a genuinely external address arriving on the org channel", () => {
+    // The whole point of scoping the case to id-shaped recipients: an email or
+    // a phone number handed to an org surface must still be external, or the
+    // fix would open the AI-disclosure gate for real outsiders.
+    assert.equal(classifyRecipient("cohort", "someone@external.com"), "external");
+    assert.equal(classifyRecipient("cohort-org", "client@bank.example"), "external");
+    assert.equal(classifyRecipient("cohort", "+15551234567"), "external");
+    // …and an allow-listed internal domain still resolves through the domain test.
+    assert.equal(
+      classifyRecipient("cohort", "alex@internal.example", ["internal.example"]),
+      "internal",
+    );
+  });
+
+  it("an unreadable required policy no longer gags the agent in its own workspace", async () => {
+    // The end-to-end symptom, reduced: no policies/ on disk at all.
+    const emptyFs = { existsSync: () => false, readFileSync: () => { throw new Error("ENOENT"); } };
+    const org = await screenOutbound({
+      channel: "cohort",
+      recipient: "cmqs5i86p0008ta0129ql6rv9",
+      text: "Already voted espresso — I'm in the count.",
+      fs: emptyFs,
+    });
+    assert.equal(org.allow, true, `org post must fail OPEN, got: ${org.reason}`);
+
+    // The external posture is untouched — this is the half that must NOT regress.
+    const outsider = await screenOutbound({
+      channel: "email",
+      recipient: "someone@external.com",
+      text: "Already voted espresso — I'm in the count.",
+      fs: emptyFs,
+    });
+    assert.equal(outsider.allow, false);
+    assert.match(outsider.reason, /failing closed for external recipient/);
+  });
 });
 
 /* ─── real-disk integration smoke (uses the actual readPolicy path) ────────*/

package/lib/execution/disposition.mjs

@@ -293,9 +293,27 @@ export function decide(o = {}) {
   //      the terminal authority on its own approvals or on committing the org.
   if (policy.selfApprove === false) {
     why.push(`${surface} may never be resolved by the agent itself → escalate to a human decider`);
+    // The options are what make this an ESCALATION rather than a shrug. A caller
+    // that worked out the real alternatives wins; otherwise the surface's own
+    // structurally-known set is used, because hq's `escalation.ask` refuses a
+    // question with fewer than two and an approval with no options attached is
+    // just a second chat message — the exact thing OpenQuestion exists to
+    // replace. NEVER SILENT when a surface declares none.
+    const declared = Array.isArray(policy.escalationOptions) ? policy.escalationOptions : [];
+    const options = Array.isArray(facts.ambiguousOptions) && facts.ambiguousOptions.length >= 2
+      ? facts.ambiguousOptions
+      : declared;
+    if (options.length >= 2) {
+      why.push(`offering the ${options.length} ways this can go: ${options.join(" / ")}`);
+    } else {
+      why.push(
+        `no options are available for ${surface} (neither the caller nor the surface policy ` +
+          "declared any) — this will raise a blockage flag, not a decision",
+      );
+    }
     return finish(base, "escalate", "cannot_self_decide", why, o, {
       escalateTo: facts.escalateTo || null,
-      options: Array.isArray(facts.ambiguousOptions) ? facts.ambiguousOptions : [],
+      options,
     });
   }
 
@@ -450,7 +468,49 @@ function finish(base, disposition, reason, why, o, extra = {}) {
   for (const line of route.why) why.push(`route: ${line}`);
 
   const gates = {};
-  if (route.approval) gates.approval = route.approval;
+  // ── the blast-radius gate, and the two dispositions it must NOT be applied to.
+  //
+  //    THE DEADLOCK THIS FIXES. `surface-policy` gives `approval` and `decision`
+  //    `actionClasses:["irreversible"]` AND `selfApprove:false`. Rule 6 above
+  //    therefore ALWAYS returns `escalate` on them — and, until this branch, also
+  //    attached an approval gate to that escalation. `drive.mjs` step 4 runs the
+  //    gate BEFORE the effect and fails closed, so the sequence was:
+  //
+  //        the agent may not decide this approval
+  //          → escalate it to a human
+  //            → but first obtain an approval
+  //              → which is the thing it may not decide.
+  //
+  //    The escalate effect never ran. Observed live against a production org:
+  //    `escalate @rung 1 (claude-skill) — cannot_self_decide`, `writes=[]`. The
+  //    one disposition that exists to put a decision in front of a person was
+  //    structurally unreachable on every surface that needs it.
+  //
+  //    `escalate` and `delegate` are exempt for the same reason: neither ACTS on
+  //    the surface. They hand the thing to somebody else — a human decider, or a
+  //    peer seat that runs this identical ladder and is gated in its own right.
+  //    Gating them buys no safety and costs the handover.
+  //
+  //    `react_now` and `schedule` KEEP the gate. `react_now` obviously — the
+  //    classes are literally the cost of replying. `schedule` less obviously,
+  //    and deliberately: the queued item is drained by the backlog sweep into a
+  //    session that does NOT re-enter this ladder, so a gate dropped here is a
+  //    gate lost for good. An inbound email queues, and it stays gated.
+  //
+  //    NEVER SILENT: when the gate is dropped, say so and why, so a journal
+  //    reader does not have to know this rule to read the trace.
+  const HANDS_OFF = disposition === "escalate" || disposition === "delegate";
+  if (route.approval) {
+    if (!HANDS_OFF) {
+      gates.approval = route.approval;
+    } else {
+      why.push(
+        `blast radius ${route.approval.classes.join("+")} is the cost of ACTING on ${base.surface}; ` +
+          `this decision is \`${disposition}\`, which hands the act to someone else who is gated in ` +
+          "their own right — the approval gate does not apply and would deadlock it",
+      );
+    }
+  }
   if (route.gate) gates[route.gate.kind] = route.gate.detail;
   // A reply into a shared room must win the thread-ownership lease first, or two
   // agents answer the same @mention. DMs and queued work need no arbitration.

package/lib/execution/disposition.test.mjs

@@ -95,6 +95,10 @@ const SURFACE_CASES = {
   escalation:   { verdict: yes("escalation", "waiting_on"),  candidate: { family: "escalation", kind: "raised", topic: "escalation", surfaces: ["escalation"], ids: { escalationId: "e1" } } },
   handoff:      { verdict: yes("handoff", "direct"),         candidate: { family: "handoff", kind: "offered", topic: "handoff", surfaces: ["handoff"], ids: { handoffId: "h1" } } },
   email:        { verdict: yes("email", "direct"),           candidate: { family: "email", kind: "received", topic: "email", surfaces: ["email"], ids: { messageId: "e1" } } },
+  // JOINT 3. `attendee` is the reason `resolveCalendar` emits when the ACL'd
+  // `calendar.list` read (owner OR attendeeRows) proved the event is this
+  // seat's — the payload can only ever prove `calendar_owner`.
+  calendar:     { verdict: yes("calendar", "attendee"),      candidate: { family: "calendar", kind: "event.created", topic: "calendar", surfaces: ["calendar"], ids: { eventId: "ev1" } } },
 };
 
 test("every inbound surface has a decision case in this test file", () => {
@@ -480,3 +484,53 @@ test("decide is PURE: the same inputs give the same decision", () => {
   const b = run(SURFACE_CASES.mention);
   assert.deepEqual(a, b);
 });
+
+// ───────────────────────────────────────────────────────────────────────────
+// The escalate deadlock. Regression for a live failure, not a hypothetical.
+// ───────────────────────────────────────────────────────────────────────────
+
+test("ESCALATE is never blast-radius gated — gating it deadlocks the only route to a human", () => {
+  // `approval` and `decision` carry actionClasses:["irreversible"] AND
+  // selfApprove:false, so rule 6 always escalates them. Attaching the approval
+  // gate to that escalation means: to escalate an approval, first get an
+  // approval. drive.mjs step 4 fails closed, so the effect never ran and the
+  // lane produced nothing. Observed live (writes=[]).
+  for (const s of ["approval", "decision"]) {
+    const d = run(SURFACE_CASES[s]);
+    assert.equal(d.disposition, "escalate");
+    assert.equal(d.gates.approval, undefined, `${s} escalation was gated behind an approval`);
+    assert.ok(
+      d.why.some((w) => /would deadlock it/.test(w)),
+      "dropping the gate must be stated out loud, never done quietly",
+    );
+  }
+});
+
+test("an escalation carries >= 2 concrete options — hq refuses a question with fewer", () => {
+  // hq's escalation.ask 400s below two options ("a question with fewer is a
+  // message, not a decision"). Nothing supplies facts.ambiguousOptions for an
+  // approval, so without the surface policy's declared set the ladder decided
+  // `escalate` and the effect had nothing to ask with.
+  for (const s of ["approval", "decision"]) {
+    const d = run(SURFACE_CASES[s]);
+    assert.ok(Array.isArray(d.options), `${s} carried no options array`);
+    assert.ok(d.options.length >= 2, `${s} escalation offered ${d.options.length} option(s)`);
+    assert.equal(new Set(d.options).size, d.options.length, "duplicate labels are not a choice");
+  }
+});
+
+test("a caller-supplied option set beats the surface policy's default", () => {
+  const d = run({
+    ...SURFACE_CASES.approval,
+    facts: { ambiguousOptions: ["ship it", "hold it", "hand it to finance"] },
+  });
+  assert.deepEqual(d.options, ["ship it", "hold it", "hand it to finance"]);
+});
+
+test("SCHEDULE keeps its blast-radius gate — the queue drain does not re-enter this ladder", () => {
+  // The exemption is for handovers (escalate/delegate) only. An inbound email
+  // queues, and dropping the `external` gate here would lose it for good.
+  const email = run(SURFACE_CASES.email);
+  assert.equal(email.disposition, "schedule");
+  assert.deepEqual(email.gates.approval, { required: true, classes: ["external"] });
+});

package/lib/execution/drive.mjs

@@ -330,7 +330,7 @@ export async function drive(decision, o = {}) {
       degraded,
     });
   }
-  const r = await runEffect(effects[name], name, { decision, candidate: o.candidate });
+  const r = await runEffect(effects[name], name, { decision, candidate: o.candidate, item: o.item });
   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 });