@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/claude-bin.test.mjs

@@ -64,12 +64,46 @@ test("augmentedPath includes common bin locations and preserves existing PATH",
   assert.ok(p.includes("/opt/homebrew/bin"));
 });
 
-test("daemonClaudeArgs returns strict-mcp-config by default", () => {
-  const prev = process.env.DAEMON_LOAD_MCPS;
-  delete process.env.DAEMON_LOAD_MCPS;
-  try {
-    assert.deepEqual(daemonClaudeArgs(), ["--strict-mcp-config"]);
-  } finally {
-    if (prev !== undefined) process.env.DAEMON_LOAD_MCPS = prev;
-  }
+test("daemonClaudeArgs returns strict-mcp-config when the agent has no .mcp.json", () => {
+  // Injected deps, so the result does not depend on the cwd the suite runs from.
+  const args = daemonClaudeArgs("/nope/agent", { existsSync: () => false, env: {} });
+  assert.deepEqual(args, ["--strict-mcp-config"]);
+});
+
+test("daemonClaudeArgs pairs --mcp-config with --strict-mcp-config so the ORG tools load", () => {
+  // The regression this guards: `--strict-mcp-config` alone means "load no MCP
+  // servers at all", which silently killed the agent's own curated org server
+  // and made rung 0 of the execution ladder unreachable.
+  const seen = [];
+  const args = daemonClaudeArgs("/agent", { existsSync: (p) => { seen.push(p); return true; }, env: {} });
+  assert.deepEqual(args, ["--mcp-config", "/agent/.mcp.json", "--strict-mcp-config"]);
+  assert.ok(seen.some((p) => String(p).endsWith("/agent/.mcp.json")));
+});
+
+test("daemonClaudeArgs falls back to $AGENT_ROOT when no root is passed", () => {
+  const args = daemonClaudeArgs(undefined, { existsSync: () => true, env: { AGENT_ROOT: "/from/env" } });
+  assert.deepEqual(args, ["--mcp-config", "/from/env/.mcp.json", "--strict-mcp-config"]);
+});
+
+test("daemonClaudeArgs: DAEMON_LOAD_MCPS=1 still means 'no flags at all'", () => {
+  assert.deepEqual(daemonClaudeArgs("/agent", { existsSync: () => true, env: { DAEMON_LOAD_MCPS: "1" } }), []);
+});
+
+test("daemonClaudeArgs: DAEMON_SKIP_ORG_MCP=1 restores the old blanket behaviour", () => {
+  assert.deepEqual(
+    daemonClaudeArgs("/agent", { existsSync: () => true, env: { DAEMON_SKIP_ORG_MCP: "1" } }),
+    ["--strict-mcp-config"],
+  );
+});
+
+test("daemonClaudeArgs: --bare stays first, ahead of the mcp flags", () => {
+  assert.deepEqual(
+    daemonClaudeArgs("/agent", { existsSync: () => true, env: { DAEMON_BARE_MODE: "1" } }),
+    ["--bare", "--mcp-config", "/agent/.mcp.json", "--strict-mcp-config"],
+  );
+});
+
+test("daemonClaudeArgs never throws on a bad root (a daemon must still spawn)", () => {
+  const args = daemonClaudeArgs("/agent", { existsSync: () => { throw new Error("EACCES"); }, env: {} });
+  assert.deepEqual(args, ["--strict-mcp-config"]);
 });

package/lib/execution/disposition.mjs

@@ -0,0 +1,501 @@
+/**
+ * lib/execution/disposition.mjs — given a DIRECTED event, decide what to do.
+ *
+ * This is the layer above `lib/org/inbound/`. That layer answers "did something
+ * happen, and is it mine?". This one answers the question the agent actually has
+ * to get right:
+ *
+ *     react now · schedule · delegate · escalate · ignore
+ *
+ * and it answers it the same way for every surface, so a board comment and a DM
+ * and a bounced email go through one ladder instead of three ad-hoc branches.
+ *
+ * Three properties are non-negotiable:
+ *
+ *  1. PURE. Every fact arrives on the argument — history, runtime state, the
+ *     capability manifest, the clock. No disk, no network, no `Date.now()`
+ *     unless the caller declined to supply one. That is what makes a decision
+ *     replayable from the journal months later, and testable per surface.
+ *
+ *  2. TOTAL. There is no input for which this returns undefined, throws, or
+ *     falls off the end. An unrecognised surface, a malformed candidate and a
+ *     verdict from a future version of the inbound layer all produce a decision
+ *     with a reason attached.
+ *
+ *  3. IGNORE IS A DECISION. An agent that replies to everything is exactly as
+ *     broken as one that replies to nothing, and the second failure mode is the
+ *     one this codebase keeps shipping — a guard returns "not configured", logs
+ *     nothing, and the message is gone. So `ignore` carries a machine-readable
+ *     `reason`, the full rule trace in `why`, and is journaled like any other
+ *     outcome. `ignore` never means "we lost it".
+ *
+ * The `why` array is the load-bearing output. It is an ordered trace of every
+ * rule that fired, in the order it fired, ending with the rule that decided.
+ * Read top to bottom it is a plain-English explanation of the agent's reasoning.
+ *
+ * @module lib/execution/disposition
+ */
+
+"use strict";
+
+import { policyFor, isDisposition } from "./surface-policy.mjs";
+import { routeRung } from "./route.mjs";
+import { dedupeKey, threadKey } from "./journal.mjs";
+
+/**
+ * Verdict reasons that mean "the event structurally named me" — tier T0 in the
+ * directedness ladder. A human pointed at this agent; the agent owes an answer.
+ */
+export const T0_REASONS = Object.freeze([
+  "direct", "dm", "mention", "named", "assignee", "reviewer", "owner",
+  "approver", "requester", "proposer", "participant", "invited", "attendee",
+  "waiting_on",
+]);
+
+/**
+ * Verdict reasons that mean "this landed in a lane I work in" — tier T1. Mine to
+ * notice, not necessarily mine to answer inside a minute.
+ */
+export const T1_REASONS = Object.freeze([
+  "thread", "channel", "shared", "commenter", "watcher", "creator", "lane",
+  "home_channel",
+]);
+
+/** Directedness tier for a verdict reason. Unknown ⇒ T1 (notice, don't jump). */
+export function tierOf(reason) {
+  const r = String(reason || "");
+  if (T0_REASONS.includes(r)) return "T0";
+  if (T1_REASONS.includes(r)) return "T1";
+  return "T1";
+}
+
+/**
+ * How many times one actor may wake this agent inside the flood window before
+ * their traffic gets batched instead of answered turn-by-turn. Not a silence —
+ * a downgrade from `react_now` to `schedule`, so nothing is lost, it is just
+ * answered once rather than eight times.
+ */
+export const DEFAULT_ACTOR_FLOOD_LIMIT = 8;
+
+/** Staleness rungs from SPEC §6.4, in seconds. */
+export const STALE_SUSPEND_OUTCOME_S = 24 * 3600;
+export const STALE_OFFLINE_ONLY_S = 72 * 3600;
+export const STALE_IDLE_S = 7 * 24 * 3600;
+
+/**
+ * Surfaces the staleness ladder does NOT gate, because handling them is what
+ * ENDS the staleness.
+ *
+ * §6.4 says the cache "is refreshed on every `topic:"mandate"` frame" and that a
+ * >7d-stale daemon "posts one PlanDrift per day and idles". Read together those
+ * two sentences are a deadlock if the ladder is applied uniformly: the mandate
+ * frame is the only thing that can clear the staleness, and at 7d the ladder
+ * would drop it, so the agent idles forever and never recovers on its own.
+ *
+ * `alert` is exempt for the same structural reason from the other direction — a
+ * local health/budget alert is derived from files on this disk, owes nothing to
+ * the mandate, and a partition is precisely when it matters most.
+ *
+ * Both are cheap and inward-facing (no action classes, nothing leaves the org),
+ * so exempting them cannot turn a stale agent into one emailing counterparties
+ * on week-old instructions — which is the risk the ladder exists to stop.
+ */
+export const RECOVERY_SURFACES = Object.freeze(["mandate", "alert"]);
+
+/** Build the terminal decision object. Internal; every exit funnels through it. */
+function verdictOut(base, disposition, reason, why, extra = {}) {
+  return {
+    ...base,
+    disposition,
+    reason,
+    why: why.slice(),
+    ...extra,
+  };
+}
+
+/**
+ * Decide what to do with one inbound event.
+ *
+ * @param {object} o
+ * @param {object} o.candidate  a `directedness.classifyEvent` Candidate
+ * @param {object} o.verdict    a `directedness.resolveDirected` verdict
+ * @param {string} [o.me]       my member id
+ * @param {object} [o.history]  a `journal.loadHistory` view (guards are skipped,
+ *                              LOUDLY, when absent — see `degraded`)
+ * @param {object} [o.runtime]  {
+ *   emergencyStop, directive, mandateStaleSeconds, enforcement,
+ *   remainingCents, dailyCapExhausted, withinWorkingHours, maxRung
+ * }
+ * @param {object|null} [o.obligation] the matched REACT obligation, or null
+ * @param {object} [o.need]     routing need estimate (see route.mjs Need)
+ * @param {Array}  [o.manifest] capability manifest
+ * @param {object} [o.facts]    delegation/authority facts {
+ *   ownerId, capableMemberId, capabilityReachable, ambiguousOptions, authorised
+ * }
+ * @param {number} [o.nowMs]
+ * @param {number} [o.actorFloodLimit]
+ * @returns {object} decision
+ */
+export function decide(o = {}) {
+  const why = [];
+  const cand = o.candidate && typeof o.candidate === "object" ? o.candidate : null;
+  const verdict = o.verdict && typeof o.verdict === "object" ? o.verdict : null;
+  const runtime = o.runtime && typeof o.runtime === "object" ? o.runtime : {};
+  const facts = o.facts && typeof o.facts === "object" ? o.facts : {};
+  const me = o.me ? String(o.me) : "";
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+
+  const surface = verdict && verdict.surface ? String(verdict.surface) : null;
+  const policy = o.policy || policyFor(surface);
+  const tier = verdict && verdict.directed ? tierOf(verdict.reason) : null;
+
+  const base = {
+    key: cand ? dedupeKey(cand) : null,
+    thread: cand ? threadKey(cand) : null,
+    actor: cand ? String(cand.actor || "") || null : null,
+    surface,
+    topic: cand ? String(cand.topic || "") || null : null,
+    tier,
+    family: cand ? String(cand.family || "") || null : null,
+    kind: cand ? String(cand.kind || "") || null : null,
+    obligationKey: o.obligation ? o.obligation.key || null : null,
+    objectiveId: o.obligation ? o.obligation.objective_id || o.obligation.objectiveId || null : null,
+    policySurface: policy.unknown ? "default" : surface,
+    rung: null,
+    mechanism: null,
+    action: null,
+    gates: {},
+    drift: null,
+    degraded: [],
+    at: new Date(nowMs).toISOString(),
+  };
+
+  // ── 0. structural sanity ────────────────────────────────────────────────
+  if (!cand) {
+    why.push("no candidate: the event did not classify into an inbound surface");
+    return verdictOut(base, "ignore", "not_classified", why);
+  }
+  if (!verdict) {
+    // A candidate with no verdict means the caller skipped the directedness
+    // join. Fail CLOSED on speaking: we will not reply to something nobody
+    // established was ours, but we will not drop it either.
+    why.push("no directedness verdict supplied — cannot establish this event is mine");
+    return verdictOut(base, "ignore", "no_verdict", why);
+  }
+  if (policy.unknown) {
+    why.push(`surface ${surface || "(none)"} has no policy row — falling back to the restrictive default`);
+    base.degraded.push(`unknown_surface:${surface || "none"}`);
+  }
+  if (!o.history) {
+    why.push("no journal history supplied — dedupe, ping-pong and flood guards are INACTIVE for this decision");
+    base.degraded.push("history_absent");
+  } else if (o.history.degraded) {
+    why.push(`journal history degraded: ${o.history.degradedReason || "unknown"}`);
+    base.degraded.push(`history_degraded:${o.history.degradedReason || "unknown"}`);
+  }
+
+  // ── 1. kill switches. Cooperative, and honestly labelled as such: these stop
+  //      a well-behaved daemon. The real control against a wedged laptop is
+  //      org-side credential revocation, not this branch.
+  if (runtime.emergencyStop === true) {
+    why.push("state/EMERGENCY_STOP present → the agent takes no action of any kind");
+    return verdictOut(base, "ignore", "emergency_stop", why);
+  }
+  const directive = runtime.directive ? String(runtime.directive) : null;
+  if (directive === "halt") {
+    why.push("beat directive `halt` → the seat is stopped");
+    return verdictOut(base, "ignore", "halt", why);
+  }
+
+  // ── 2. is it even mine? THE ignore case, and the most common one by volume.
+  if (verdict.directed !== true) {
+    const r = String(verdict.reason || "not_directed");
+    // An undirected verdict carries NO surface — that is the whole point of it.
+    // So the park-or-drop question is asked of the surfaces this event could
+    // plausibly have been, which the classifier listed most-specific-first. If
+    // ANY of them is a look-twice surface we park: a message in a space that
+    // matched no rule might be a mention whose hydration was incomplete, and
+    // that is exactly the case worth a second pass rather than a drop.
+    const plausible = Array.isArray(cand.surfaces) && cand.surfaces.length ? cand.surfaces : [surface];
+    const parkers = plausible.filter((s) => policyFor(s).ambientDrop === false);
+    if (parkers.length) {
+      why.push(`not directed (${r}), but it could have been ${parkers.join("/")} → park for the ambient sweep`);
+      return verdictOut(base, "ignore", r, why, { ambient: true, plausibleSurfaces: plausible });
+    }
+    why.push(`not directed (${r}) → drop`);
+    return verdictOut(base, "ignore", r, why, { ambient: false, plausibleSurfaces: plausible });
+  }
+  why.push(`directed: ${verdict.reason} on ${surface} (tier ${tier})`);
+
+  // Defensive echo check. `resolveDirected` already drops own-echo, but this is
+  // the branch that turns a bug there into a self-conversation, so it is worth
+  // asserting twice.
+  if (me && base.actor && base.actor === me) {
+    why.push("actor is me — this is my own echo arriving back");
+    return verdictOut(base, "ignore", "own_echo", why);
+  }
+
+  // ── 3. idempotency. The SSE push and the polling sweep BOTH deliver; without
+  //      this the agent answers every directed message exactly twice.
+  if (o.history && base.key && o.history.seen(base.key)) {
+    why.push(`already decided on ${base.key} inside the dedupe window → this is a redelivery`);
+    return verdictOut(base, "ignore", "duplicate", why);
+  }
+
+  // ── 4. ping-pong guard. Counts turns where the agent actually SPOKE, and is
+  //      reset by a human turn, so a live conversation is never cut off — only
+  //      an agent talking to itself is.
+  if (o.history && base.thread) {
+    const depth = o.history.chainDepth(base.thread);
+    if (depth >= policy.maxChainDepth) {
+      why.push(
+        `${depth} consecutive agent turn(s) in this thread with no human reply, ceiling ${policy.maxChainDepth} → stop talking`,
+      );
+      return verdictOut(base, "ignore", "reply_chain_depth", why, { chainDepth: depth });
+    }
+    if (depth > 0) why.push(`${depth} prior agent turn(s) in this thread (ceiling ${policy.maxChainDepth})`);
+  }
+
+  // ── 5. mandate staleness ladder (§6.4). A partitioned agent degrades on a
+  //      ramp; it does not go dark, and it does not keep speaking externally on
+  //      week-old instructions.
+  const stale = Number.isFinite(runtime.mandateStaleSeconds) ? runtime.mandateStaleSeconds : 0;
+  const recoverySurface = surface != null && RECOVERY_SURFACES.includes(surface);
+  if (recoverySurface && stale >= STALE_SUSPEND_OUTCOME_S) {
+    // NEVER SILENT: say out loud that the ladder was skipped and why, so a
+    // journal reader does not have to know this rule to understand the trace.
+    why.push(
+      `mandate cache is ${Math.floor(stale / 3600)}h stale, but ${surface} is a recovery surface — handling it is what clears the staleness, so the ladder does not gate it`,
+    );
+  }
+  if (!recoverySurface && stale >= STALE_IDLE_S) {
+    why.push(`mandate cache is ${Math.floor(stale / 86400)}d stale (≥7d) → idle and report drift`);
+    return verdictOut(base, "ignore", "mandate_stale", why, {
+      drift: { kind: "mandate_stale", detail: { staleSeconds: stale } },
+    });
+  }
+  if (!recoverySurface && stale >= STALE_OFFLINE_ONLY_S) {
+    const unsafe = policy.offlineSafe !== true || (policy.actionClasses || []).length > 0;
+    if (unsafe) {
+      why.push(
+        `mandate cache is ${Math.floor(stale / 3600)}h stale (>72h) and ${surface} is not offline-safe → defer until the mandate refreshes`,
+      );
+      return verdictOut(base, "schedule", "mandate_stale_deferred", why, {
+        notBefore: null,
+        drift: { kind: "mandate_stale", detail: { staleSeconds: stale, surface } },
+      });
+    }
+    why.push(`mandate ${Math.floor(stale / 3600)}h stale but ${surface} is offline-safe → proceeding`);
+  }
+
+  // ── 6. things the agent is structurally not allowed to decide. This is the
+  //      same law as `mandate.adopt` refusing self-adoption: a seat may not be
+  //      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`);
+    return finish(base, "escalate", "cannot_self_decide", why, o, {
+      escalateTo: facts.escalateTo || null,
+      options: Array.isArray(facts.ambiguousOptions) ? facts.ambiguousOptions : [],
+    });
+  }
+
+  // ── 7. capability wall. A missing capability is a FIRST-CLASS path, never a
+  //      silent failure — that is the concrete fix for "never refuse, walk the
+  //      ladder" breaking on the SDK side today.
+  if (facts.capabilityReachable === false) {
+    if (facts.capableMemberId && facts.capableMemberId !== me) {
+      why.push(
+        `the capability this needs is unreachable for me but ${facts.capableMemberId} has it → hand it to them`,
+      );
+      return finish(base, "delegate", "unreachable_capability_delegated", why, o, {
+        delegateTo: facts.capableMemberId,
+        drift: { kind: "unreachable_capability", detail: { key: base.obligationKey } },
+      });
+    }
+    why.push("the capability this needs is unreachable and no peer has it → ask the owner to grant, retarget or retire");
+    return finish(base, "escalate", "unreachable_capability", why, o, {
+      escalateTo: facts.escalateTo || null,
+      options: ["grant the capability", "retarget the objective", "retire the obligation"],
+      drift: { kind: "unreachable_capability", detail: { key: base.obligationKey } },
+    });
+  }
+
+  // ── 8. genuine ambiguity. Two or more viable options and no basis to choose
+  //      is an `escalation.ask` with concrete options — not a coin flip, and not
+  //      a paragraph of prose asking the human to work it out.
+  const options = Array.isArray(facts.ambiguousOptions) ? facts.ambiguousOptions : [];
+  if (options.length >= 2) {
+    why.push(`${options.length} viable options and no basis to choose → ask, with the options attached`);
+    return finish(base, "escalate", "ambiguous", why, o, {
+      escalateTo: facts.escalateTo || null,
+      options,
+    });
+  }
+
+  // ── 9. someone else owns this. Being mentioned on a task that is not yours is
+  //      a reason to route it, not to do it.
+  if (facts.ownerId && me && String(facts.ownerId) !== me && tier === "T1") {
+    why.push(`${facts.ownerId} owns this and I was only in the lane → route it to them`);
+    return finish(base, "delegate", "not_my_lane", why, o, { delegateTo: String(facts.ownerId) });
+  }
+
+  // ── 10. pause_schedules: the seat stops INITIATING but keeps ANSWERING. So a
+  //       conversational reply survives; queueing new work does not.
+  const paused = directive === "pause_schedules";
+
+  // ── 11. observe-only enforcement (§5.10). Decisions are still made and still
+  //       journaled — they just produce proposals instead of work. Downgrading
+  //       the EFFECT rather than the DECISION is what makes the 14-day window
+  //       readable afterwards: you can see exactly what the agent would have done.
+  const observeOnly = String(runtime.enforcement || "").toLowerCase() === "observe_only";
+  if (observeOnly) why.push("enforcement=observe_only → the decision stands but produces a proposal, not an action");
+
+  // ── 12. the respond-or-queue split.
+  const budgetOut =
+    runtime.dailyCapExhausted === true ||
+    (Number.isFinite(runtime.remainingCents) && runtime.remainingCents <= 0);
+
+  if (!policy.respondable) {
+    if (paused) {
+      why.push("`pause_schedules` is in force and this surface cannot be answered conversationally → park it");
+      return verdictOut(base, "ignore", "paused", why, { observeOnly });
+    }
+    why.push(`${surface} is not a conversational surface → queue the work`);
+    return finish(base, "schedule", "not_respondable", why, o, { observeOnly });
+  }
+
+  if (budgetOut) {
+    why.push("the spend envelope is exhausted → queue rather than spend; nothing is dropped");
+    return finish(base, "schedule", "budget_exhausted", why, o, { observeOnly });
+  }
+
+  // Flood control. A downgrade, not a silence.
+  const floodLimit = Number.isFinite(o.actorFloodLimit) ? o.actorFloodLimit : DEFAULT_ACTOR_FLOOD_LIMIT;
+  if (o.history && base.actor) {
+    const hits = o.history.actorActivity(base.actor);
+    if (hits >= floodLimit) {
+      why.push(`${base.actor} has woken me ${hits} time(s) in the flood window (limit ${floodLimit}) → batch the reply`);
+      return finish(base, "schedule", "actor_flood", why, o, { observeOnly, batched: true });
+    }
+  }
+
+  if (policy.latency !== "now") {
+    why.push(`${surface} is a ${policy.latency} surface — nobody is watching for an instant reply → next tick`);
+    return finish(base, "schedule", "batch_surface", why, o, { observeOnly });
+  }
+
+  if (tier !== "T0" && runtime.withinWorkingHours === false) {
+    why.push("lane-tier event outside working hours → next tick");
+    return finish(base, "schedule", "outside_hours", why, o, { observeOnly });
+  }
+
+  why.push(`${surface} wants an answer now and I am the one who owes it`);
+  return finish(base, "react_now", "directed_now", why, o, { observeOnly });
+}
+
+/**
+ * Attach routing (rung, mechanism, gates) to a decision that will act, and flag
+ * an uncovered event when nothing in the plan matched.
+ *
+ * Split out so every acting exit routes identically — an earlier draft routed in
+ * three places and two of them forgot the approval gate.
+ */
+function finish(base, disposition, reason, why, o, extra = {}) {
+  const policy = o.policy || policyFor(base.surface);
+  const runtime = o.runtime && typeof o.runtime === "object" ? o.runtime : {};
+  const drift = extra.drift || null;
+  const out = { ...extra };
+
+  // An event that is unmistakably mine but matches NO obligation is the signal
+  // that the plan is incomplete. Handle it once, cheaply, and record the gap so
+  // the plan learns instead of ossifying. Capping the rung is what keeps
+  // "unplanned" from meaning "unbounded".
+  let maxRung = Number.isFinite(runtime.maxRung) ? runtime.maxRung : undefined;
+  if (!o.obligation && disposition !== "ignore") {
+    why.push("no obligation in the compiled plan covers this event → handle once at rung ≤1 and record the gap");
+    maxRung = Math.min(maxRung === undefined ? 1 : maxRung, 1);
+    out.drift = drift || {
+      kind: "uncovered_event",
+      detail: { surface: base.surface, family: base.family, kind: base.kind },
+    };
+  } else if (drift) {
+    out.drift = drift;
+  }
+
+  // The blast radius of the ACTION is the union of what the surface costs to
+  // speak on and what the obligation itself declares.
+  const actionClasses = []
+    .concat(policy.actionClasses || [])
+    .concat((o.need && o.need.actionClasses) || [])
+    .concat((o.obligation && o.obligation.action_classes) || []);
+
+  const need = {
+    ...(o.need || {}),
+    actionClasses,
+    obligationKey: base.obligationKey,
+  };
+  if (!need.methods && policy.replyMethod && disposition === "react_now") {
+    need.methods = [policy.replyMethod];
+  }
+
+  const route = routeRung(need, {
+    manifest: o.manifest,
+    failures: o.history && base.obligationKey ? o.history.failures(base.obligationKey) : 0,
+    estCents: runtime.estCents,
+    remainingCents: runtime.remainingCents,
+    hasAdoptedObjective: !!base.objectiveId,
+    maxRung,
+  });
+
+  for (const line of route.why) why.push(`route: ${line}`);
+
+  const gates = {};
+  if (route.approval) gates.approval = route.approval;
+  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.
+  if (disposition === "react_now" && policy.replyMethod === "messaging.send" && base.surface !== "dm") {
+    gates.arbitration = { scope: "thread-ownership", resource: base.thread };
+  }
+
+  // Budget over-run turns an action into an enqueue. Never a silent downgrade
+  // to a cheaper rung — a cheaper rung is a worse answer, not a cheaper one.
+  let finalDisposition = disposition;
+  let finalReason = reason;
+  if (route.blocked && disposition === "react_now") {
+    why.push("routing is budget-blocked → the reply becomes a queued item");
+    finalDisposition = "schedule";
+    finalReason = "budget_blocked";
+  }
+
+  return verdictOut(base, finalDisposition, finalReason, why, {
+    ...out,
+    rung: route.rung,
+    mechanism: route.mechanism,
+    rungReason: route.reason,
+    escalatedFrom: route.escalatedFrom,
+    gates,
+    action: {
+      method: policy.replyMethod || null,
+      classes: route.approval ? route.approval.classes : [],
+    },
+  });
+}
+
+/** True when a decision means the agent will attempt something. */
+export function willAct(decision) {
+  return !!decision && isDisposition(decision.disposition) && decision.disposition !== "ignore";
+}
+
+export default {
+  decide,
+  willAct,
+  tierOf,
+  T0_REASONS,
+  T1_REASONS,
+  RECOVERY_SURFACES,
+  DEFAULT_ACTOR_FLOOD_LIMIT,
+  STALE_SUSPEND_OUTCOME_S,
+  STALE_OFFLINE_ONLY_S,
+  STALE_IDLE_S,
+};