@desplega.ai/agent-swarm 1.71.2 → 1.72.1

package/src/tests/budget-admission.test.ts

@@ -0,0 +1,338 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { __resetKillSwitchWarnedForTests, canClaim } from "../be/budget-admission";
+import {
+  closeDb,
+  createAgent,
+  createSessionCost,
+  getBudgetRefusalNotification,
+  getDailySpendForAgent,
+  getDb,
+  hasBudgetRefusalNotificationToday,
+  initDb,
+  recordBudgetRefusalNotification,
+} from "../be/db";
+
+const TEST_DB_PATH = "./test-budget-admission.sqlite";
+
+async function removeDbFiles(path: string): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(path + suffix);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+}
+
+beforeAll(() => {
+  initDb(TEST_DB_PATH);
+});
+
+afterAll(async () => {
+  closeDb();
+  await removeDbFiles(TEST_DB_PATH);
+});
+
+// Reset DB-side budget / notification / session_cost rows between tests so
+// each test starts from a known empty slate. We don't tear the whole DB down
+// — initDb() in beforeAll is enough.
+//
+// We also wipe `agents` because session_costs has a FK to agents and the test
+// helper `insertSpendForAgent` re-creates agents on demand. Tests don't use
+// any other agent-related rows.
+beforeEach(() => {
+  const db = getDb();
+  db.prepare("DELETE FROM session_costs").run();
+  db.prepare("DELETE FROM budget_refusal_notifications").run();
+  db.prepare("DELETE FROM budgets").run();
+  db.prepare("DELETE FROM agents").run();
+  ensuredAgentIds.clear();
+});
+
+// Always restore the kill-switch env var so it doesn't leak across tests.
+afterEach(() => {
+  delete process.env.BUDGET_ADMISSION_DISABLED;
+  __resetKillSwitchWarnedForTests();
+});
+
+// Track which agents we've already created in the current test so we don't
+// hit the PK collision on a second `createAgent`. Cleared in `beforeEach`.
+const ensuredAgentIds = new Set<string>();
+
+function ensureAgent(agentId: string): void {
+  if (ensuredAgentIds.has(agentId)) return;
+  createAgent({
+    id: agentId,
+    name: `agent-${agentId}`,
+    isLead: false,
+    status: "idle",
+  });
+  ensuredAgentIds.add(agentId);
+}
+
+function insertBudget(scope: "global" | "agent", scopeId: string, dailyBudgetUsd: number): void {
+  getDb()
+    .prepare(
+      "INSERT INTO budgets (scope, scope_id, daily_budget_usd, createdAt, lastUpdatedAt) VALUES (?, ?, ?, ?, ?)",
+    )
+    .run(scope, scopeId, dailyBudgetUsd, Date.now(), Date.now());
+}
+
+// Pinned to the same UTC day as `NOW` so spend rows fall inside the queried day window regardless of when CI runs.
+const DEFAULT_SPEND_CREATED_AT = "2026-04-28T12:00:00.000Z";
+
+function insertSpendForAgent(
+  agentId: string,
+  totalCostUsd: number,
+  opts: { createdAt?: string } = {},
+): string {
+  ensureAgent(agentId);
+  const cost = createSessionCost({
+    sessionId: `sess-${crypto.randomUUID()}`,
+    agentId,
+    totalCostUsd,
+    durationMs: 1000,
+    numTurns: 1,
+    model: "test-model",
+  });
+  const createdAt = opts.createdAt ?? DEFAULT_SPEND_CREATED_AT;
+  getDb().prepare("UPDATE session_costs SET createdAt = ? WHERE id = ?").run(createdAt, cost.id);
+  return cost.id;
+}
+
+describe("canClaim — budget admission predicate", () => {
+  const NOW = new Date("2026-04-28T15:30:00.000Z");
+  const TODAY = "2026-04-28";
+
+  test("missing budget rows ⇒ allowed (default unlimited)", () => {
+    const result = canClaim("agent-1", NOW);
+    expect(result.allowed).toBe(true);
+  });
+
+  test("global budget set, spend below ceiling ⇒ allowed", () => {
+    insertBudget("global", "", 10.0);
+    insertSpendForAgent("agent-x", 3.5);
+
+    const result = canClaim("agent-1", NOW);
+    expect(result.allowed).toBe(true);
+  });
+
+  test("global budget set, spend at ceiling ⇒ refused with cause='global'", () => {
+    insertBudget("global", "", 10.0);
+    insertSpendForAgent("agent-x", 7.0);
+    insertSpendForAgent("agent-y", 3.0); // exactly hits 10.0
+
+    const result = canClaim("agent-z", NOW);
+    expect(result.allowed).toBe(false);
+    if (result.allowed) throw new Error("unreachable");
+    expect(result.cause).toBe("global");
+    expect(result.globalSpend).toBe(10.0);
+    expect(result.globalBudget).toBe(10.0);
+    // Global-cause refusals do not populate agent fields.
+    expect(result.agentSpend).toBeUndefined();
+    expect(result.agentBudget).toBeUndefined();
+  });
+
+  test("agent budget set, agent spend at ceiling ⇒ refused with cause='agent'", () => {
+    insertBudget("agent", "agent-1", 5.0);
+    insertSpendForAgent("agent-1", 5.0);
+
+    const result = canClaim("agent-1", NOW);
+    expect(result.allowed).toBe(false);
+    if (result.allowed) throw new Error("unreachable");
+    expect(result.cause).toBe("agent");
+    expect(result.agentSpend).toBe(5.0);
+    expect(result.agentBudget).toBe(5.0);
+    expect(result.globalSpend).toBeUndefined();
+    expect(result.globalBudget).toBeUndefined();
+  });
+
+  test("both budgets set + both blown ⇒ refused with cause='global' (global is checked first)", () => {
+    insertBudget("global", "", 10.0);
+    insertBudget("agent", "agent-1", 2.0);
+    insertSpendForAgent("agent-1", 10.0);
+
+    const result = canClaim("agent-1", NOW);
+    expect(result.allowed).toBe(false);
+    if (result.allowed) throw new Error("unreachable");
+    expect(result.cause).toBe("global");
+  });
+
+  test("spend on a different UTC day does NOT count toward today", () => {
+    insertBudget("agent", "agent-1", 5.0);
+    // Backdated cost from yesterday — should not contribute to today's total.
+    insertSpendForAgent("agent-1", 50.0, { createdAt: "2026-04-27T23:59:59.999Z" });
+    // A small cost today that does not blow the budget.
+    insertSpendForAgent("agent-1", 1.0, { createdAt: "2026-04-28T01:00:00.000Z" });
+
+    const todaySpend = getDailySpendForAgent("agent-1", TODAY);
+    expect(todaySpend).toBe(1.0);
+
+    const result = canClaim("agent-1", NOW);
+    expect(result.allowed).toBe(true);
+  });
+
+  test("resetAt for nowUtc=15:30Z is the FOLLOWING UTC midnight", () => {
+    insertBudget("global", "", 0.0); // force a refusal so resetAt is set
+    const result = canClaim("agent-1", new Date("2026-04-28T15:30:00.000Z"));
+    expect(result.allowed).toBe(false);
+    if (result.allowed) throw new Error("unreachable");
+    expect(result.resetAt).toBe("2026-04-29T00:00:00.000Z");
+  });
+
+  test("resetAt at exact UTC midnight rolls forward by +24h, not the current instant", () => {
+    insertBudget("global", "", 0.0);
+    const result = canClaim("agent-1", new Date("2026-04-28T00:00:00.000Z"));
+    expect(result.allowed).toBe(false);
+    if (result.allowed) throw new Error("unreachable");
+    expect(result.resetAt).toBe("2026-04-29T00:00:00.000Z");
+  });
+
+  test("resetAt rolls over month boundary: 2026-04-30T23:59:59.999Z → 2026-05-01T00:00:00.000Z", () => {
+    insertBudget("global", "", 0.0);
+    const result = canClaim("agent-1", new Date("2026-04-30T23:59:59.999Z"));
+    expect(result.allowed).toBe(false);
+    if (result.allowed) throw new Error("unreachable");
+    expect(result.resetAt).toBe("2026-05-01T00:00:00.000Z");
+  });
+
+  test("resetAt rolls over year boundary: 2026-12-31T23:59:59.999Z → 2027-01-01T00:00:00.000Z", () => {
+    insertBudget("global", "", 0.0);
+    const result = canClaim("agent-1", new Date("2026-12-31T23:59:59.999Z"));
+    expect(result.allowed).toBe(false);
+    if (result.allowed) throw new Error("unreachable");
+    expect(result.resetAt).toBe("2027-01-01T00:00:00.000Z");
+  });
+
+  test("BUDGET_ADMISSION_DISABLED=true short-circuits to allowed regardless of budget rows", () => {
+    insertBudget("global", "", 0.0); // would refuse without the flag
+    insertBudget("agent", "agent-1", 0.0);
+    insertSpendForAgent("agent-1", 100.0);
+
+    process.env.BUDGET_ADMISSION_DISABLED = "true";
+    const result = canClaim("agent-1", NOW);
+    expect(result.allowed).toBe(true);
+  });
+});
+
+describe("recordBudgetRefusalNotification — idempotent dedup", () => {
+  beforeEach(() => {
+    getDb().prepare("DELETE FROM budget_refusal_notifications").run();
+  });
+
+  test("first call inserts; second call with same (taskId, date) returns existing row with inserted=false", () => {
+    const args = {
+      taskId: "task-1",
+      date: "2026-04-28",
+      agentId: "agent-1",
+      cause: "agent" as const,
+      agentSpendUsd: 5.0,
+      agentBudgetUsd: 5.0,
+    };
+
+    const first = recordBudgetRefusalNotification(args);
+    expect(first.inserted).toBe(true);
+    expect(first.row.taskId).toBe("task-1");
+    expect(first.row.date).toBe("2026-04-28");
+    expect(first.row.cause).toBe("agent");
+    expect(first.row.agentSpendUsd).toBe(5.0);
+    expect(first.row.agentBudgetUsd).toBe(5.0);
+    expect(first.row.followUpTaskId).toBeUndefined();
+
+    const second = recordBudgetRefusalNotification({
+      ...args,
+      // Different cause/spend — should still be ignored, returning the original row.
+      cause: "global",
+      agentSpendUsd: 999,
+      agentBudgetUsd: 999,
+    });
+    expect(second.inserted).toBe(false);
+    expect(second.row.cause).toBe("agent"); // original
+    expect(second.row.agentSpendUsd).toBe(5.0); // original
+    expect(second.row.agentBudgetUsd).toBe(5.0); // original
+    expect(second.row.createdAt).toBe(first.row.createdAt);
+  });
+
+  test("same task on a different date inserts a new row", () => {
+    const first = recordBudgetRefusalNotification({
+      taskId: "task-1",
+      date: "2026-04-28",
+      agentId: "agent-1",
+      cause: "agent",
+    });
+    expect(first.inserted).toBe(true);
+
+    const next = recordBudgetRefusalNotification({
+      taskId: "task-1",
+      date: "2026-04-29",
+      agentId: "agent-1",
+      cause: "agent",
+    });
+    expect(next.inserted).toBe(true);
+    expect(next.row.date).toBe("2026-04-29");
+  });
+
+  test("hasBudgetRefusalNotificationToday observes presence/absence", () => {
+    expect(hasBudgetRefusalNotificationToday("task-1", "2026-04-28")).toBe(false);
+
+    recordBudgetRefusalNotification({
+      taskId: "task-1",
+      date: "2026-04-28",
+      agentId: "agent-1",
+      cause: "global",
+      globalSpendUsd: 12.5,
+      globalBudgetUsd: 10.0,
+    });
+
+    expect(hasBudgetRefusalNotificationToday("task-1", "2026-04-28")).toBe(true);
+    expect(hasBudgetRefusalNotificationToday("task-1", "2026-04-29")).toBe(false);
+  });
+
+  test("getBudgetRefusalNotification round-trips global-cause fields", () => {
+    recordBudgetRefusalNotification({
+      taskId: "task-2",
+      date: "2026-04-28",
+      agentId: "agent-1",
+      cause: "global",
+      globalSpendUsd: 12.5,
+      globalBudgetUsd: 10.0,
+    });
+
+    const row = getBudgetRefusalNotification("task-2", "2026-04-28");
+    expect(row).not.toBeNull();
+    expect(row?.cause).toBe("global");
+    expect(row?.globalSpendUsd).toBe(12.5);
+    expect(row?.globalBudgetUsd).toBe(10.0);
+    expect(row?.agentSpendUsd).toBeUndefined();
+    expect(row?.agentBudgetUsd).toBeUndefined();
+  });
+});
+
+describe("getDailySpendForAgent — uses an agentId-leading index (no full table scan)", () => {
+  interface ExplainRow {
+    id: number;
+    parent: number;
+    notused: number;
+    detail: string;
+  }
+
+  test("EXPLAIN QUERY PLAN uses an idx_session_costs_agent* index", () => {
+    // Both `idx_session_costs_agentId` (single-column) and
+    // `idx_session_costs_agent_createdAt` (composite) lead with `agentId`, so
+    // either one is a valid plan — SQLite's optimizer picks based on stats.
+    // What we MUST avoid is a full table scan ("SCAN session_costs" without
+    // "USING INDEX"). The assertion below covers both index choices and
+    // explicitly fails on a bare scan.
+    const rows = getDb()
+      .prepare<ExplainRow, [string, string]>(
+        "EXPLAIN QUERY PLAN SELECT COALESCE(SUM(totalCostUsd), 0) as total FROM session_costs WHERE agentId = ? AND substr(createdAt, 1, 10) = ?",
+      )
+      .all("agent-1", "2026-04-28");
+
+    const detail = rows.map((r) => r.detail).join(" | ");
+    expect(detail).toMatch(/USING INDEX idx_session_costs_agent/);
+  });
+});

package/src/tests/budget-claim-gate.test.ts

@@ -0,0 +1,288 @@
+// Phase 3: server-side budget admission gate tests.
+//
+// Exercises `handlePoll` (the `/api/poll` HTTP handler) and the MCP
+// `task-action` `accept` action directly with mocked req/res so we don't have
+// to spin up a full HTTP server. Each test starts from an empty DB.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import {
+  closeDb,
+  createAgent,
+  createSessionCost,
+  createTaskExtended,
+  getAgentById,
+  getDb,
+  incrementEmptyPollCount,
+  initDb,
+} from "../be/db";
+import { handlePoll } from "../http/poll";
+
+const TEST_DB_PATH = "./test-budget-claim-gate.sqlite";
+
+async function removeDbFiles(path: string): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(path + suffix);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}
+
+beforeAll(() => {
+  initDb(TEST_DB_PATH);
+});
+
+afterAll(async () => {
+  closeDb();
+  await removeDbFiles(TEST_DB_PATH);
+});
+
+beforeEach(() => {
+  const db = getDb();
+  // Clear data from previous test, leave schema in place. Delete task-graph
+  // tables in dependency order so FKs don't trip.
+  db.prepare("DELETE FROM session_costs").run();
+  db.prepare("DELETE FROM budget_refusal_notifications").run();
+  db.prepare("DELETE FROM budgets").run();
+  db.prepare("DELETE FROM agent_tasks").run();
+  db.prepare("DELETE FROM agents").run();
+});
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+interface PollResponse {
+  status: number;
+  body: { trigger: { type: string; [key: string]: unknown } | null } | { error: string };
+}
+
+/**
+ * Direct invocation of `handlePoll`. We use real Bun-built ServerResponse-ish
+ * mocks rather than spawning the API server — much faster and isolates the
+ * test surface to the gate itself.
+ */
+async function callPoll(agentId: string | undefined): Promise<PollResponse> {
+  let status = 200;
+  let bodyStr = "";
+  const headers: Record<string, string> = {};
+
+  const req = {
+    method: "GET",
+    url: "/api/poll",
+    headers: agentId ? { "x-agent-id": agentId } : {},
+  } as unknown as Parameters<typeof handlePoll>[0];
+
+  const res = {
+    setHeader(name: string, value: string) {
+      headers[name.toLowerCase()] = value;
+    },
+    writeHead(code: number, h?: Record<string, string>) {
+      status = code;
+      if (h) {
+        for (const [k, v] of Object.entries(h)) headers[k.toLowerCase()] = v;
+      }
+    },
+    end(body?: string) {
+      bodyStr = body ?? "";
+    },
+  } as unknown as Parameters<typeof handlePoll>[1];
+
+  const handled = await handlePoll(req, res, ["api", "poll"], new URLSearchParams(), agentId);
+  if (!handled) throw new Error("handlePoll did not handle the request");
+
+  return { status, body: bodyStr ? JSON.parse(bodyStr) : null };
+}
+
+function insertBudget(scope: "global" | "agent", scopeId: string, dailyBudgetUsd: number): void {
+  const now = Date.now();
+  getDb()
+    .prepare(
+      "INSERT INTO budgets (scope, scope_id, daily_budget_usd, createdAt, lastUpdatedAt) VALUES (?, ?, ?, ?, ?)",
+    )
+    .run(scope, scopeId, dailyBudgetUsd, now, now);
+}
+
+function insertSpend(agentId: string, totalCostUsd: number): void {
+  createSessionCost({
+    sessionId: `sess-${crypto.randomUUID()}`,
+    agentId,
+    totalCostUsd,
+    durationMs: 1_000,
+    numTurns: 1,
+    model: "test-model",
+  });
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe("Phase 3 — /api/poll budget admission gate", () => {
+  test("no budgets configured + pending task → trigger=task_assigned (existing behavior preserved)", async () => {
+    const worker = createAgent({ name: "w1", isLead: false, status: "idle", maxTasks: 1 });
+    const task = createTaskExtended("do the thing", { agentId: worker.id });
+    expect(task.status).toBe("pending");
+
+    const { status, body } = await callPoll(worker.id);
+    expect(status).toBe(200);
+    if ("error" in body) throw new Error("unexpected error response");
+    expect(body.trigger?.type).toBe("task_assigned");
+    expect((body.trigger as { taskId: string }).taskId).toBe(task.id);
+  });
+
+  test("no budgets configured + no work → trigger=null", async () => {
+    const worker = createAgent({ name: "w-empty", isLead: false, status: "idle", maxTasks: 1 });
+    const { status, body } = await callPoll(worker.id);
+    expect(status).toBe(200);
+    if ("error" in body) throw new Error("unexpected error response");
+    expect(body.trigger).toBeNull();
+  });
+
+  test("budgets present but spend below ceiling → trigger=task_assigned", async () => {
+    const worker = createAgent({ name: "w-below", isLead: false, status: "idle", maxTasks: 1 });
+    insertBudget("agent", worker.id, 10.0);
+    insertSpend(worker.id, 1.0); // well below 10.0
+    const task = createTaskExtended("budgeted task", { agentId: worker.id });
+
+    const { body } = await callPoll(worker.id);
+    if ("error" in body) throw new Error("unexpected error response");
+    expect(body.trigger?.type).toBe("task_assigned");
+    expect((body.trigger as { taskId: string }).taskId).toBe(task.id);
+  });
+
+  test("agent budget blown → trigger=budget_refused with cause='agent'", async () => {
+    const worker = createAgent({ name: "w-over", isLead: false, status: "idle", maxTasks: 1 });
+    insertBudget("agent", worker.id, 0.01);
+    insertSpend(worker.id, 0.05); // blows the 0.01 budget
+    createTaskExtended("blocked task", { agentId: worker.id });
+
+    const { body } = await callPoll(worker.id);
+    if ("error" in body) throw new Error("unexpected error response");
+    expect(body.trigger?.type).toBe("budget_refused");
+    expect((body.trigger as { cause: string }).cause).toBe("agent");
+    expect((body.trigger as { agentSpend: number }).agentSpend).toBe(0.05);
+    expect((body.trigger as { agentBudget: number }).agentBudget).toBe(0.01);
+    expect((body.trigger as { resetAt: string }).resetAt).toMatch(
+      /^\d{4}-\d{2}-\d{2}T00:00:00\.000Z$/,
+    );
+    // Global fields must not be present (cause=agent).
+    expect((body.trigger as { globalSpend?: number }).globalSpend).toBeUndefined();
+    expect((body.trigger as { globalBudget?: number }).globalBudget).toBeUndefined();
+  });
+
+  test("global budget blown → trigger=budget_refused with cause='global'", async () => {
+    const worker = createAgent({ name: "w-glob", isLead: false, status: "idle", maxTasks: 1 });
+    insertBudget("global", "", 0.01);
+    insertSpend(worker.id, 0.1); // blows the global budget
+    createTaskExtended("blocked-by-global", { agentId: worker.id });
+
+    const { body } = await callPoll(worker.id);
+    if ("error" in body) throw new Error("unexpected error response");
+    expect(body.trigger?.type).toBe("budget_refused");
+    expect((body.trigger as { cause: string }).cause).toBe("global");
+    expect((body.trigger as { globalSpend: number }).globalSpend).toBe(0.1);
+    expect((body.trigger as { globalBudget: number }).globalBudget).toBe(0.01);
+    // Agent fields must not be present (cause=global).
+    expect((body.trigger as { agentSpend?: number }).agentSpend).toBeUndefined();
+  });
+
+  test("budget refusal in pool path: blows the gate without claiming an unassigned task", async () => {
+    const worker = createAgent({ name: "w-pool", isLead: false, status: "idle", maxTasks: 1 });
+    insertBudget("agent", worker.id, 0.01);
+    insertSpend(worker.id, 0.5);
+    // Unassigned (pool) task — no `agentId`.
+    const pooled = createTaskExtended("pool task", {});
+    expect(pooled.status).toBe("unassigned");
+
+    const { body } = await callPoll(worker.id);
+    if ("error" in body) throw new Error("unexpected error response");
+    expect(body.trigger?.type).toBe("budget_refused");
+
+    // The pool task must still be unassigned (refusal short-circuited claim).
+    const row = getDb()
+      .prepare<{ status: string }, [string]>("SELECT status FROM agent_tasks WHERE id = ?")
+      .get(pooled.id);
+    expect(row?.status).toBe("unassigned");
+  });
+
+  test("refused poll does NOT auto-increment server-side empty-poll counter", async () => {
+    const worker = createAgent({ name: "w-emptyp", isLead: false, status: "idle", maxTasks: 1 });
+    insertBudget("agent", worker.id, 0.01);
+    insertSpend(worker.id, 0.5);
+    createTaskExtended("blocked", { agentId: worker.id });
+
+    const before = getAgentById(worker.id)?.emptyPollCount ?? 0;
+    await callPoll(worker.id);
+    const after = getAgentById(worker.id)?.emptyPollCount ?? 0;
+    // /api/poll never increments emptyPollCount itself — that's the MCP
+    // poll-task tool's job — and a refusal must not flip that invariant.
+    // We assert "no increment" specifically for the refusal path.
+    expect(after).toBe(before);
+    // Sanity: the agent's counter is still 0; if a pre-feature regression
+    // accidentally bumped it, this would catch it.
+    expect(after).toBe(0);
+    // Quick sanity that the bookkeeping helper itself still works (regression
+    // guard for the wasBudgetRefused flag plumbing in poll-task.ts).
+    const newCount = incrementEmptyPollCount(worker.id);
+    expect(newCount).toBe(1);
+  });
+
+  test("two-agent race: only one task is claimed; the other gets task_assigned for a different task or null", async () => {
+    const w1 = createAgent({ name: "race-1", isLead: false, status: "idle", maxTasks: 1 });
+    const w2 = createAgent({ name: "race-2", isLead: false, status: "idle", maxTasks: 1 });
+    // One unassigned task in the pool.
+    const t = createTaskExtended("race task", {});
+    expect(t.status).toBe("unassigned");
+
+    // Sequentially poll both; race correctness is enforced by SQLite
+    // serialization, so even back-to-back the atomic UPDATE WHERE
+    // status='unassigned' guarantees only one wins.
+    const r1 = await callPoll(w1.id);
+    const r2 = await callPoll(w2.id);
+
+    if ("error" in r1.body || "error" in r2.body) throw new Error("unexpected error");
+    const triggers = [r1.body.trigger, r2.body.trigger];
+    const claimedTriggers = triggers.filter((t) => t?.type === "task_assigned");
+    const nullTriggers = triggers.filter((t) => t === null);
+    expect(claimedTriggers).toHaveLength(1);
+    expect(nullTriggers).toHaveLength(1);
+  });
+});
+
+// ─── MCP task-action accept tests ───────────────────────────────────────────
+//
+// The MCP tool registration is hard to invoke without the MCP server harness,
+// so instead we exercise the underlying transaction by importing the same
+// code path via a focused "accept simulation". We can't import the inner
+// switch directly, so we call the same helpers and assert canClaim refusal
+// returns the documented envelope shape.
+
+describe("Phase 3 — MCP task-action accept gate (canClaim integration)", () => {
+  test("accept refuses when agent budget is blown (returns refusalCause='agent')", async () => {
+    // We test the canClaim integration directly because the MCP tool is wired
+    // through `createToolRegistrar` and would require a full MCP server boot
+    // to invoke. The accept handler's relevant code path in task-action.ts
+    // (lines extended in Phase 3) is exercised by the same predicate, so a
+    // direct canClaim assertion gives us coverage parity without the
+    // server-boot overhead.
+    const { canClaim } = await import("../be/budget-admission");
+    const worker = createAgent({ name: "accept-w", isLead: false, status: "idle", maxTasks: 1 });
+    insertBudget("agent", worker.id, 0.01);
+    insertSpend(worker.id, 0.5);
+
+    const result = canClaim(worker.id, new Date());
+    expect(result.allowed).toBe(false);
+    if (result.allowed) throw new Error("unreachable");
+    expect(result.cause).toBe("agent");
+    expect(result.agentSpend).toBe(0.5);
+    expect(result.agentBudget).toBe(0.01);
+    // Shape parity with the envelope returned by the accept handler.
+    expect(result.resetAt).toMatch(/^\d{4}-\d{2}-\d{2}T00:00:00\.000Z$/);
+  });
+
+  test("accept allows when no budgets configured", async () => {
+    const { canClaim } = await import("../be/budget-admission");
+    const worker = createAgent({ name: "accept-ok", isLead: false, status: "idle", maxTasks: 1 });
+    const result = canClaim(worker.id, new Date());
+    expect(result.allowed).toBe(true);
+  });
+});