@desplega.ai/agent-swarm 2.2.0 → 2.4.0

package/src/tests/heartbeat-jev-gate.test.ts

@@ -1,3 +1,4 @@
+import { Database } from "bun:sqlite";
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
@@ -19,7 +20,9 @@ type Fixture = {
   configs: Record<string, string>;
   heartbeatMd?: string;
   prevStatus?: string;
+  reportedFailures?: unknown;
   prevOutput?: string | null;
+  prevCreatedAt?: string | null;
   failed?: Array<Record<string, unknown>>;
   approvalStatus?: string;
   /** Stands in for `ctx.swarm.systemOne_decide`; returns the bridge result. */
@@ -33,6 +36,7 @@ function fakeCtx(f: Fixture) {
     kvSets: 0,
     decides: [] as Array<Record<string, any>>,
     approvalReads: 0,
+    previousReads: 0,
   };
   const table = (columns: string[], rows: unknown[][]) => ({
     success: true,
@@ -56,17 +60,48 @@ function fakeCtx(f: Fixture) {
           },
         };
       },
-      db_query: async ({ sql }: { sql: string }) => {
+      db_query: async ({ sql, params = [] }: { sql: string; params?: any[] }) => {
         if (sql.includes("FROM approval_requests")) {
           calls.approvalReads++;
           return table(["status"], f.approvalStatus ? [[f.approvalStatus]] : []);
         }
         if (sql.includes("heartbeatMd")) return table(["heartbeatMd"], [[f.heartbeatMd ?? ""]]);
-        if (sql.includes("'heartbeat-checklist'")) {
-          return table(
-            ["id", "output", "status"],
-            [["prev-id", f.prevOutput ?? null, f.prevStatus ?? ""]],
-          );
+        if (sql.includes("'heartbeat-checklist'") || sql.includes("finishedAt <= ?")) {
+          if (sql.includes("'heartbeat-checklist'")) calls.previousReads++;
+          // Execute historical selection against real rows, including its bounds and limit.
+          const db = new Database(":memory:");
+          try {
+            db.run(`CREATE TABLE agent_tasks (
+              id TEXT, output TEXT, task TEXT, agentId TEXT, taskType TEXT,
+              status TEXT, createdAt TEXT, finishedAt TEXT
+            )`);
+            if (f.prevCreatedAt !== null)
+              db.run("INSERT INTO agent_tasks VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [
+                "prev-id",
+                f.prevOutput ?? null,
+                f.prevStatus ?? "",
+                LEAD,
+                "heartbeat-checklist",
+                "completed",
+                f.prevCreatedAt ?? "2026-10-15T13:00:00.000Z",
+                null,
+              ]);
+            for (const failure of f.failed ?? []) {
+              db.run("INSERT INTO agent_tasks VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [
+                failure.id,
+                null,
+                failure.task,
+                failure.agentId,
+                "test",
+                "failed",
+                "2026-10-15T06:00:00.000Z",
+                failure.finishedAt,
+              ]);
+            }
+            return { data: { rows: db.query(sql).all(...params) } };
+          } finally {
+            db.close();
+          }
         }
         if (sql.includes("completed24")) {
           return table(
@@ -75,7 +110,10 @@ function fakeCtx(f: Fixture) {
           );
         }
         if (sql.includes("status = 'failed' AND finishedAt")) {
-          const rows = f.failed ?? [];
+          const rows = (f.failed ?? [])
+            .filter((r) => String(r.finishedAt) > params[0])
+            .sort((a, b) => String(b.finishedAt).localeCompare(String(a.finishedAt)))
+            .slice(0, 10);
           return table(
             ["id", "agentId", "task", "failureReason", "finishedAt"],
             rows.map((r) => [r.id, r.agentId, r.task, r.failureReason, r.finishedAt]),
@@ -93,8 +131,13 @@ function fakeCtx(f: Fixture) {
         }
         throw new Error(`unexpected sql: ${sql}`);
       },
-      kv_getOrNull: async ({ key }: { key: string }) =>
-        kv.has(key) ? { key, value: kv.get(key) } : null,
+      kv_getOrNull: async ({ namespace, key }: { namespace: string; key: string }) => {
+        if (namespace === "heartbeat-checklist:reported-failures") {
+          expect(key).toBe("prev-id");
+          return f.reportedFailures === undefined ? null : { key, value: f.reportedFailures };
+        }
+        return kv.has(key) ? { key, value: kv.get(key) } : null;
+      },
       kv_set: async ({ key, value }: { key: string; value: unknown }) => {
         calls.kvSets++;
         kv.set(key, value);
@@ -168,6 +211,7 @@ describe("heartbeat-jev-gate with a provider", () => {
   test("wake at or above the threshold, with the new failures and due items in summary", async () => {
     const { ctx } = fakeCtx({
       configs: { TYPESAFE_API_KEY: "x" },
+      reportedFailures: ["aaaaaaaa-0000"],
       heartbeatMd: [
         "# Standing orders",
         `- Watch: release on ${MMDD} — lift after ship`,
@@ -176,7 +220,7 @@ describe("heartbeat-jev-gate with a provider", () => {
       ].join("\n"),
       // The previous checklist already listed aaaaaaaa, so only bbbbbbbb is new.
       prevStatus:
-        '## Recent Failures (last 6h) [auto-generated]\n- [aaaaaaaa] "old failure" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z\n',
+        '## Current System Status [auto-generated]\n## Recent Failures (last 6h) [auto-generated]\n- [aaaaaaaa] "old failure" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z\n',
       prevOutput: "All clear.\n\nNothing to do.",
       failed: [
         {
@@ -217,6 +261,346 @@ describe("heartbeat-jev-gate with a provider", () => {
     });
   });
 
+  for (const ordersFirst of [true, false]) {
+    test(`previous failures are not new with standing orders ${ordersFirst ? "before" : "after"} status`, async () => {
+      const failures =
+        '## Recent Failures (last 6h) [auto-generated]\n- [aaaaaaaa] "old failure" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z\n';
+      const orders = "## Your Standing Orders\n- Already triaged.\n";
+      const status = `## Current System Status [auto-generated]\n${failures}`;
+      const { ctx } = fakeCtx({
+        configs: { TYPESAFE_API_KEY: "x" },
+        reportedFailures: ["aaaaaaaa-0000"],
+        prevStatus: ordersFirst ? orders + status : status + orders,
+        failed: [
+          {
+            id: "aaaaaaaa-0000",
+            agentId: "12345678-bbbb",
+            task: "old failure",
+            failureReason: "boom",
+            finishedAt: "2026-10-15T12:00:00Z",
+          },
+          {
+            id: "bbbbbbbb-0000",
+            agentId: "12345678-bbbb",
+            task: "new failure",
+            failureReason: "exit 1",
+            finishedAt: "2026-10-15T13:01:00.000Z",
+          },
+        ],
+        jev: jevSays(0.9),
+      });
+      const verdict = await run(ctx, { dryRun: true });
+      expect(verdict.state.new_failures_since_previous_heartbeat).toEqual([
+        "bbbbbbbb: new failure | exit 1",
+      ]);
+      expect(verdict.state.failures_last_6h_total).toBe(2);
+    });
+  }
+
+  test.each([
+    "## Recent Failures (last 6h) [auto-generated]\nNone.\n",
+    "",
+  ])("failures outside the previous Recent Failures section stay new (%s)", async (section) => {
+    const { ctx } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      prevStatus: `## Current System Status [auto-generated]\n${section}## Gate Findings [auto-generated]\n- [aaaaaaaa] "quoted failure" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z\n`,
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "quoted failure",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T13:01:00.000Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    expect((await run(ctx, { dryRun: true })).state.new_failures_since_previous_heartbeat).toEqual([
+      "aaaaaaaa: quoted failure | boom",
+    ]);
+  });
+
+  test.each([
+    "- Item 544: fix `## Recent Failures` parsing.\n",
+    "## Recent Failures\nSnapshot notes.\n",
+    '## Recent Failures (last 6h) [auto-generated]\n- [bbbbbbbb] "snapshot quote" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z\n',
+  ])("snapshot failure headings cannot hijack generated status (%s)", async (snapshot) => {
+    const { ctx, calls } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      reportedFailures: ["aaaaaaaa-0000"],
+      prevStatus: [
+        "## Your Standing Orders (snapshot from HEARTBEAT.md)",
+        snapshot,
+        "## Instructions",
+        "Review the generated status.",
+        "## Current System Status [auto-generated]",
+        "## Recent Failures (last 6h) [auto-generated]",
+        '- [aaaaaaaa] "old failure" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z',
+      ].join("\n"),
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "old failure",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:00:00Z",
+        },
+        {
+          id: "bbbbbbbb-0000",
+          agentId: "12345678-bbbb",
+          task: "snapshot quote",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T13:01:00.000Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    expect((await run(ctx, { dryRun: true })).state.new_failures_since_previous_heartbeat).toEqual([
+      "bbbbbbbb: snapshot quote | boom",
+    ]);
+    expect(calls.previousReads).toBe(1);
+  });
+
+  test("an absent generated failures section cannot use a trailing snapshot heading", async () => {
+    const { ctx, calls } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      prevStatus: [
+        "## Current System Status [auto-generated]",
+        "## Task Overview [auto-generated]",
+        "- Failed (24h): 0",
+        "## Agent Status [auto-generated]",
+        "- Online: 6",
+        "## Your Standing Orders (snapshot from HEARTBEAT.md)",
+        "## Recent Failures (last 6h) [auto-generated]",
+        '- [aaaaaaaa] "snapshot quote" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z',
+      ].join("\n"),
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "snapshot quote",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T13:01:00.000Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    expect((await run(ctx, { dryRun: true })).state.new_failures_since_previous_heartbeat).toEqual([
+      "aaaaaaaa: snapshot quote | boom",
+    ]);
+    expect(calls.previousReads).toBe(1);
+  });
+
+  test("a failed-task title heading does not hide later failures", async () => {
+    const { ctx, calls } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      reportedFailures: ["aaaaaaaa-0000", "bbbbbbbb-0000"],
+      prevStatus: [
+        "## Current System Status [auto-generated]",
+        "## Recent Failures (last 6h) [auto-generated]",
+        '- [aaaaaaaa] "Fix the task\n## Requirements" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z',
+        '- [bbbbbbbb] "later failure" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z',
+        "## Gate Findings [auto-generated]",
+        '- [cccccccc] "outside failures" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00Z',
+      ].join("\n"),
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "Fix the task\n## Requirements",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:00:00Z",
+        },
+        {
+          id: "bbbbbbbb-0000",
+          agentId: "12345678-bbbb",
+          task: "later failure",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:00:00Z",
+        },
+        {
+          id: "cccccccc-0000",
+          agentId: "12345678-bbbb",
+          task: "outside failures",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T13:01:00.000Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    const verdict = await run(ctx, { dryRun: true });
+    expect(verdict.state.new_failures_since_previous_heartbeat).toEqual([
+      "cccccccc: outside failures | boom",
+    ]);
+    expect(verdict.state.failures_last_6h_total).toBe(3);
+    expect(calls.previousReads).toBe(1);
+  });
+
+  test("code-fenced snapshot system and agent markers cannot hide previous failures", async () => {
+    const { ctx, calls } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      reportedFailures: ["aaaaaaaa-0000"],
+      prevStatus: [
+        "## Your Standing Orders (snapshot from HEARTBEAT.md)",
+        "```md",
+        "## Current System Status [auto-generated]",
+        "## Agent Status [auto-generated]",
+        "```",
+        "## Current System Status [auto-generated]",
+        "## Recent Failures (last 6h) [auto-generated]",
+        '- [aaaaaaaa] "old failure" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00.000Z',
+        "## Agent Status [auto-generated]",
+      ].join("\n"),
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "old failure",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:00:00.000Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    expect((await run(ctx, { dryRun: true })).state.new_failures_since_previous_heartbeat).toBe(
+      "none",
+    );
+    expect(calls.previousReads).toBe(1);
+  });
+
+  test("a generated Requirements heading in a failed title cannot hide later failures", async () => {
+    const { ctx } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      reportedFailures: ["aaaaaaaa-0000", "bbbbbbbb-0000"],
+      prevStatus: [
+        "## Current System Status [auto-generated]",
+        "## Recent Failures (last 6h) [auto-generated]",
+        '- [aaaaaaaa] "Fix\n## Requirements [auto-generated]\nbody" — agent: 12345678, reason: boom, at: 2026-10-15T12:00:00.000Z',
+        '- [bbbbbbbb] "later failure" — agent: 12345678, reason: boom, at: 2026-10-15T12:01:00.000Z',
+        "## Agent Status [auto-generated]",
+      ].join("\n"),
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "Fix\n## Requirements [auto-generated]\nbody",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:00:00.000Z",
+        },
+        {
+          id: "bbbbbbbb-0000",
+          agentId: "12345678-bbbb",
+          task: "later failure",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:01:00.000Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    expect((await run(ctx, { dryRun: true })).state.new_failures_since_previous_heartbeat).toBe(
+      "none",
+    );
+  });
+
+  test("a failure finished after previous creation stays new even if its ID is quoted", async () => {
+    const { ctx } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      prevStatus:
+        '## Current System Status [auto-generated]\n## Recent Failures (last 6h) [auto-generated]\n- [aaaaaaaa] "new failure" — agent: 12345678, reason: boom, at: 2026-10-15T13:00:00.001Z',
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "new failure",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T13:00:00.001Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    expect((await run(ctx, { dryRun: true })).state.new_failures_since_previous_heartbeat).toEqual([
+      "aaaaaaaa: new failure | boom",
+    ]);
+  });
+
+  test.each([
+    { reportedFailures: ["aaaaaaaa-0000"] },
+    { reportedFailures: '["aaaaaaaa-0000"]' },
+  ])("a failure unseen during gathering stays new before checklist creation (%j)", async ({
+    reportedFailures,
+  }) => {
+    const { ctx } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      reportedFailures,
+      prevCreatedAt: "2026-10-15T13:00:00.000Z",
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "reported",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:00:00.000Z",
+        },
+        {
+          id: "bbbbbbbb-0000",
+          agentId: "12345678-bbbb",
+          task: "unseen",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:59:59.999Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    expect((await run(ctx, { dryRun: true })).state.new_failures_since_previous_heartbeat).toEqual([
+      "bbbbbbbb: unseen | boom",
+    ]);
+  });
+
+  test.each(
+    [undefined, "not JSON", {}, [42]].map((reportedFailures) => ({ reportedFailures })),
+  )("missing or invalid receipts treat every current failure as new (%j)", async ({
+    reportedFailures,
+  }) => {
+    const { ctx } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      reportedFailures,
+      prevStatus: '## Recent Failures (last 6h) [auto-generated]\n- [aaaaaaaa] "quoted"',
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "still new",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:00:00.000Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    expect((await run(ctx, { dryRun: true })).state.new_failures_since_previous_heartbeat).toEqual([
+      "aaaaaaaa: still new | boom",
+    ]);
+  });
+
+  test("without a previous checklist all current failures are new", async () => {
+    const { ctx } = fakeCtx({
+      configs: { TYPESAFE_API_KEY: "x" },
+      prevCreatedAt: null,
+      failed: [
+        {
+          id: "aaaaaaaa-0000",
+          agentId: "12345678-bbbb",
+          task: "first failure",
+          failureReason: "boom",
+          finishedAt: "2026-10-15T12:00:00.000Z",
+        },
+      ],
+      jev: jevSays(0.9),
+    });
+    expect((await run(ctx, { dryRun: true })).state.new_failures_since_previous_heartbeat).toEqual([
+      "aaaaaaaa: first failure | boom",
+    ]);
+  });
+
   test("threshold and time zone come from swarm config", async () => {
     const { ctx } = fakeCtx({
       configs: {

package/src/tests/inbox-state.test.ts

@@ -0,0 +1,167 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createServer, type Server } from "node:http";
+import {
+  closeDb,
+  createUser,
+  getDbClient,
+  initDb,
+  listInboxState,
+  upsertInboxState,
+} from "../be/db";
+import { handleInboxState } from "../http/inbox-state";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import { listenOnFreePort } from "./test-net";
+
+const TEST_DB_PATH = "./test-inbox-state.sqlite";
+const earlier = "2026-01-01T00:00:00.000Z";
+const later = "2026-02-01T00:00:00.000Z";
+let userId: string;
+let server: Server;
+let baseUrl: string;
+
+beforeAll(async () => {
+  initDb(TEST_DB_PATH);
+  userId = (await createUser({ name: "Inbox User", email: "inbox-state@example.com" })).id;
+  server = createServer(async (req, res) => {
+    const url = req.url ?? "";
+    if (await handleInboxState(req, res, getPathSegments(url), parseQueryParams(url))) return;
+    res.writeHead(404).end();
+  });
+  baseUrl = `http://127.0.0.1:${await listenOnFreePort(server)}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) {
+    const file = Bun.file(`${TEST_DB_PATH}${suffix}`);
+    if (await file.exists()) await file.delete();
+  }
+});
+
+async function patch(path: string, body: Record<string, unknown>) {
+  return fetch(`${baseUrl}/api/inbox-state${path}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ userId, ...body }),
+  });
+}
+
+describe("inbox read cursor", () => {
+  test("sets, preserves, moves back, and clears the cursor independently of sticky readAt", async () => {
+    const item = {
+      userId,
+      itemType: "to_read" as const,
+      itemId: "cursor",
+      status: "open" as const,
+    };
+    const initial = await upsertInboxState(item);
+    expect(initial.lastReadAt).toBeUndefined();
+    const set = await upsertInboxState({ ...item, readAt: earlier, lastReadAt: later });
+    expect(set.lastReadAt).toBe(later);
+    expect((await upsertInboxState({ ...item, readAt: later })).lastReadAt).toBe(later);
+    const movedBack = await upsertInboxState({ ...item, readAt: later, lastReadAt: earlier });
+    expect(movedBack.lastReadAt).toBe(earlier);
+    expect(movedBack.readAt).toBe(earlier);
+    const cleared = await upsertInboxState({ ...item, status: "done", lastReadAt: null });
+    expect(cleared.lastReadAt).toBeUndefined();
+    expect(cleared.readAt).toBe(earlier);
+    expect(cleared.status).toBe("done");
+    expect(
+      (await listInboxState({ userId })).find((row) => row.id === set.id)?.lastReadAt,
+    ).toBeUndefined();
+  });
+
+  test("single PATCH accepts a timestamp and null", async () => {
+    const item = { itemType: "to_read", itemId: "http-cursor", status: "open" };
+    const set = await patch("", { ...item, readAt: earlier, lastReadAt: later });
+    expect(set.status).toBe(200);
+    expect((await set.json()).item.lastReadAt).toBe(later);
+    const cleared = await patch("", { ...item, lastReadAt: null });
+    expect(cleared.status).toBe(200);
+    expect((await cleared.json()).item).toMatchObject({ readAt: earlier });
+    expect(
+      (await listInboxState({ userId })).find((row) => row.itemId === item.itemId)?.lastReadAt,
+    ).toBeUndefined();
+  });
+});
+
+describe("bulk inbox state", () => {
+  test("returns rows in request order and applies single-item cursor semantics", async () => {
+    const item = { itemType: "to_read", itemId: "bulk-cursor", status: "open" };
+    const response = await patch("/bulk", {
+      items: [
+        { ...item, readAt: earlier, lastReadAt: later },
+        { ...item, readAt: later },
+        { ...item, lastReadAt: earlier },
+        { ...item, lastReadAt: null },
+        { ...item, itemId: "bulk-other", status: "dismissed" },
+      ],
+    });
+    expect(response.status).toBe(200);
+    const { items } = await response.json();
+    expect(items.map((row: { itemId: string }) => row.itemId)).toEqual([
+      "bulk-cursor",
+      "bulk-cursor",
+      "bulk-cursor",
+      "bulk-cursor",
+      "bulk-other",
+    ]);
+    expect(items.map((row: { lastReadAt?: string }) => row.lastReadAt)).toEqual([
+      later,
+      later,
+      earlier,
+      undefined,
+      undefined,
+    ]);
+    expect(items.slice(0, 4).every((row: { readAt: string }) => row.readAt === earlier)).toBe(true);
+  });
+
+  test("rejects an invalid item before writing anything", async () => {
+    const response = await patch("/bulk", {
+      items: [
+        { itemType: "to_read", itemId: "must-not-write", status: "open" },
+        { itemType: "to_read", itemId: "invalid-cursor", status: "open", lastReadAt: "invalid" },
+      ],
+    });
+    expect(response.status).toBe(400);
+    expect((await listInboxState({ userId })).some((row) => row.itemId === "must-not-write")).toBe(
+      false,
+    );
+  });
+
+  test("rejects empty batches and more than 200 items", async () => {
+    for (const count of [0, 201]) {
+      const response = await patch("/bulk", {
+        items: Array.from({ length: count }, (_, i) => ({
+          itemType: "to_read",
+          itemId: `limit-${i}`,
+          status: "open",
+        })),
+      });
+      expect(response.status).toBe(400);
+    }
+    expect((await listInboxState({ userId })).some((row) => row.itemId.startsWith("limit-"))).toBe(
+      false,
+    );
+  });
+
+  test("rolls back earlier writes when a later upsert fails", async () => {
+    await getDbClient().run(`CREATE TRIGGER reject_inbox_state_test BEFORE INSERT ON inbox_item_state
+      WHEN NEW.itemId = 'reject-write' BEGIN SELECT RAISE(ABORT, 'test write failure'); END`);
+    try {
+      const response = await patch("/bulk", {
+        items: [
+          { itemType: "to_read", itemId: "rolled-back", status: "open" },
+          { itemType: "to_read", itemId: "reject-write", status: "open" },
+        ],
+      });
+      expect(response.status).toBe(500);
+      expect((await listInboxState({ userId })).some((row) => row.itemId === "rolled-back")).toBe(
+        false,
+      );
+    } finally {
+      await getDbClient().run("DROP TRIGGER reject_inbox_state_test");
+    }
+  });
+});

package/src/tests/kv-tool.test.ts

@@ -118,6 +118,21 @@ describe("kv MCP tools", () => {
     expect(getRes.structuredContent.entry?.value).toEqual({ hello: "world" });
   });
 
+  test.each([
+    "heartbeat-checklist",
+    "heartbeat-checklist:reported-failures",
+  ])("kv-set refuses reserved heartbeat receipts even for lead (%s)", async (namespace) => {
+    const result = (await buildServer().set.handler(
+      { namespace, key: "checklist-id", value: ["forged-id"] },
+      meta(lead),
+    )) as StructuredResult<{ success: boolean; message: string }>;
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("reserved for heartbeat checklist receipts");
+    expect(
+      await getDbClient().get("SELECT key FROM kv_entries WHERE namespace = ?", [namespace]),
+    ).toBeNull();
+  });
+
   test("kv-get returns entry=null for missing keys", async () => {
     const tools = buildServer();
     const getRes = (await tools.get.handler({ key: "nope" }, meta(agentA))) as StructuredResult<{