@desplega.ai/agent-swarm 1.135.2 → 1.136.0

package/src/tests/db-retention.test.ts

@@ -0,0 +1,344 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, getDbClient, initDb } from "../be/db";
+import {
+  DB_RETENTION_TABLES,
+  getDbRetentionStats,
+  resetDbRetentionForTests,
+  runDbRetentionTick,
+  startDbRetention,
+  stopDbRetention,
+} from "../be/db-retention";
+import { MAX_DB_RETENTION_DAYS, validateConfigValue } from "../be/swarm-config-guard";
+
+const TEST_DB_PATH = "./test-db-retention.sqlite";
+const NOW = new Date("2026-08-23T12:00:00.000Z");
+const RETENTION_KEYS = DB_RETENTION_TABLES.map((table) => table.envKey);
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"])
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => undefined);
+}
+
+async function insertRow(
+  table: (typeof DB_RETENTION_TABLES)[number]["table"],
+  id: string,
+  createdAt: string,
+): Promise<void> {
+  const client = getDbClient();
+  if (table === "session_logs") {
+    await client.run(
+      "INSERT INTO session_logs (id, sessionId, iteration, cli, content, lineNumber, createdAt) VALUES (?, ?, 0, 'bun', 'log', 1, ?)",
+      [id, `session-${id}`, createdAt],
+    );
+    return;
+  }
+  if (table === "agent_log") {
+    await client.run("INSERT INTO agent_log (id, eventType, createdAt) VALUES (?, 'test', ?)", [
+      id,
+      createdAt,
+    ]);
+    return;
+  }
+  await client.run(
+    "INSERT INTO events (id, category, event, source, createdAt) VALUES (?, 'test', 'retention.test', 'test', ?)",
+    [id, createdAt],
+  );
+}
+
+async function countRows(table: (typeof DB_RETENTION_TABLES)[number]["table"]): Promise<number> {
+  const row = await getDbClient().get<{ count: number }>(`SELECT COUNT(*) AS count FROM ${table}`);
+  return row?.count ?? 0;
+}
+
+beforeAll(async () => {
+  closeDb();
+  await removeDbFiles();
+  initDb(TEST_DB_PATH);
+});
+
+afterAll(async () => {
+  await resetDbRetentionForTests();
+  closeDb();
+  await removeDbFiles();
+});
+
+beforeEach(async () => {
+  await resetDbRetentionForTests();
+  for (const table of DB_RETENTION_TABLES) await getDbClient().run(`DELETE FROM ${table.table}`);
+  for (const key of [...RETENTION_KEYS, "DB_RETENTION_DRY_RUN"]) delete process.env[key];
+});
+
+afterEach(async () => {
+  await stopDbRetention();
+});
+
+describe("DB retention", () => {
+  test("keeps the closed allowlist limited to the three approved tables", () => {
+    expect(DB_RETENTION_TABLES.map((table) => table.table)).toEqual([
+      "session_logs",
+      "agent_log",
+      "events",
+    ]);
+  });
+
+  test("validates each retention setting as an integer of at least one day", () => {
+    for (const key of RETENTION_KEYS) {
+      expect(validateConfigValue(key, "30")).toBeNull();
+      expect(validateConfigValue(key, "0")).toContain("between 1");
+      expect(validateConfigValue(key, "-1")).toContain("integer");
+      expect(validateConfigValue(key, "abc")).toContain("integer");
+      expect(validateConfigValue(key, String(MAX_DB_RETENTION_DAYS))).toBeNull();
+      expect(validateConfigValue(key, String(MAX_DB_RETENTION_DAYS + 1))).toContain("between");
+    }
+  });
+
+  test("validates the dry-run setting as a strict boolean literal", () => {
+    for (const value of ["true", "false", "1", "0"]) {
+      expect(validateConfigValue("DB_RETENTION_DRY_RUN", value)).toBeNull();
+    }
+    expect(validateConfigValue("DB_RETENTION_DRY_RUN", "treu")).toContain(
+      "Invalid DB_RETENTION_DRY_RUN",
+    );
+  });
+
+  test("is opt-in and rejects invalid retention windows", async () => {
+    for (const table of DB_RETENTION_TABLES)
+      await insertRow(table.table, `${table.table}-old`, "2026-08-01T00:00:00.000Z");
+    process.env.SESSION_LOG_RETENTION_DAYS = "0";
+    process.env.AGENT_LOG_RETENTION_DAYS = "abc";
+    process.env.EVENTS_RETENTION_DAYS = "-1";
+
+    await runDbRetentionTick({ now: NOW });
+
+    for (const table of DB_RETENTION_TABLES) expect(await countRows(table.table)).toBe(1);
+  });
+
+  test("sweeps only enabled tables and preserves rows at or after the ISO cutoff", async () => {
+    const cutoff = "2026-08-22T12:00:00.000Z";
+    for (const table of DB_RETENTION_TABLES) {
+      await insertRow(table.table, `${table.table}-old`, "2026-08-22T11:59:59.999Z");
+      await insertRow(table.table, `${table.table}-cutoff`, cutoff);
+    }
+    process.env.SESSION_LOG_RETENTION_DAYS = "1";
+
+    await runDbRetentionTick({ now: NOW });
+
+    expect(await countRows("session_logs")).toBe(1);
+    expect(await countRows("agent_log")).toBe(2);
+    expect(await countRows("events")).toBe(2);
+    expect(await getDbRetentionStats().sessionLogs).toMatchObject({
+      rowsDeleted: 1,
+      dryRun: false,
+    });
+  });
+
+  test("never deletes old rows from critical tables", async () => {
+    const old = "2020-01-01T00:00:00.000Z";
+    const client = getDbClient();
+    await client.run(
+      "INSERT INTO agents (id, name, status, createdAt, lastUpdatedAt) VALUES ('critical-agent', 'Critical', 'idle', ?, ?)",
+      [old, old],
+    );
+    await client.run(
+      "INSERT INTO agent_tasks (id, task, status, source, createdAt, lastUpdatedAt) VALUES ('critical-task', 'keep', 'completed', 'mcp', ?, ?)",
+      [old, old],
+    );
+    await client.run(
+      "INSERT INTO agent_memory (id, scope, name, content, source, createdAt, accessedAt) VALUES ('critical-memory', 'swarm', 'keep', 'keep', 'manual', ?, ?)",
+      [old, old],
+    );
+    await client.run(
+      "INSERT INTO permission_audit (id, ts, principalType, verb, decision, source) VALUES ('critical-audit', ?, 'operator', 'config.read', 'allow', 'http')",
+      [old],
+    );
+    for (const table of DB_RETENTION_TABLES) process.env[table.envKey] = "1";
+
+    await runDbRetentionTick({ now: NOW });
+
+    for (const table of ["agents", "agent_tasks", "agent_memory", "permission_audit"]) {
+      const row = await client.get<{ count: number }>(
+        `SELECT COUNT(*) AS count FROM ${table} WHERE id LIKE 'critical-%'`,
+      );
+      expect(row?.count).toBe(1);
+    }
+  });
+
+  test("uses bounded batches and continues on the next tick", async () => {
+    process.env.SESSION_LOG_RETENTION_DAYS = "1";
+    for (let index = 0; index < 5; index++) {
+      await insertRow("session_logs", `old-${index}`, "2026-08-01T00:00:00.000Z");
+    }
+
+    await runDbRetentionTick({ now: NOW, batchSize: 2, perTableBatchCap: 1 });
+    expect(await countRows("session_logs")).toBe(3);
+    await runDbRetentionTick({ now: NOW, batchSize: 2, perTableBatchCap: 1 });
+    expect(await countRows("session_logs")).toBe(1);
+    await runDbRetentionTick({ now: NOW, batchSize: 2, perTableBatchCap: 1 });
+    expect(await countRows("session_logs")).toBe(0);
+    expect(getDbRetentionStats().sessionLogs).toMatchObject({
+      rowsDeleted: 1,
+      batches: 1,
+      cumulativeRowsDeleted: 5,
+    });
+  });
+
+  test("dry run reports candidates without deleting any enabled table rows", async () => {
+    for (const table of DB_RETENTION_TABLES) {
+      process.env[table.envKey] = "1";
+      await insertRow(table.table, `${table.table}-old`, "2026-08-01T00:00:00.000Z");
+    }
+    process.env.DB_RETENTION_DRY_RUN = "true";
+
+    await runDbRetentionTick({ now: NOW });
+
+    for (const table of DB_RETENTION_TABLES) expect(await countRows(table.table)).toBe(1);
+    expect(getDbRetentionStats()).toMatchObject({
+      sessionLogs: { rowsDeleted: 1, dryRun: true },
+      agentLog: { rowsDeleted: 1, dryRun: true },
+      events: { rowsDeleted: 1, dryRun: true },
+    });
+  });
+
+  test("uses dry run when the deployed dry-run value is invalid", async () => {
+    process.env.SESSION_LOG_RETENTION_DAYS = "1";
+    process.env.DB_RETENTION_DRY_RUN = "treu";
+    await insertRow("session_logs", "invalid-dry-run-old", "2026-08-01T00:00:00.000Z");
+
+    await runDbRetentionTick({ now: NOW });
+
+    expect(await countRows("session_logs")).toBe(1);
+    expect(getDbRetentionStats().sessionLogs).toMatchObject({ rowsDeleted: 1, dryRun: true });
+  });
+
+  test("dry run reports an exact count above the former safety cap", async () => {
+    process.env.SESSION_LOG_RETENTION_DAYS = "1";
+    process.env.DB_RETENTION_DRY_RUN = "true";
+    await getDbClient().run(
+      `WITH RECURSIVE candidates(value) AS (
+         SELECT 1
+         UNION ALL
+         SELECT value + 1 FROM candidates WHERE value < 250001
+       )
+       INSERT INTO session_logs (id, sessionId, iteration, cli, content, lineNumber, createdAt)
+       SELECT 'dry-' || value, 'dry-session', 0, 'bun', 'log', value, '2026-08-01T00:00:00.000Z'
+       FROM candidates`,
+    );
+
+    await runDbRetentionTick({ now: NOW });
+
+    expect(getDbRetentionStats().sessionLogs?.rowsDeleted).toBe(250_001);
+    expect(await countRows("session_logs")).toBe(250_001);
+  });
+
+  test("dry run scans sparse tables in bounded keyset pages when no rows are eligible", async () => {
+    process.env.SESSION_LOG_RETENTION_DAYS = "1";
+    process.env.DB_RETENTION_DRY_RUN = "true";
+    await getDbClient().run(
+      `WITH RECURSIVE recent(value) AS (
+         SELECT 1
+         UNION ALL
+         SELECT value + 1 FROM recent WHERE value < 10000
+       )
+       INSERT INTO session_logs (id, sessionId, iteration, cli, content, lineNumber, createdAt)
+       SELECT 'recent-' || printf('%05d', value), 'recent-session', 0, 'bun', 'log', value,
+              '2026-08-23T11:59:59.999Z'
+       FROM recent`,
+    );
+
+    await runDbRetentionTick({ now: NOW, batchSize: 100, wallClockCapMs: 1 });
+
+    expect(getDbRetentionStats().sessionLogs).toBeUndefined();
+    expect(await countRows("session_logs")).toBe(10_000);
+  });
+
+  test("bounds pages fetched on a non-dry sweep of a sparse table with no eligible rows", async () => {
+    process.env.SESSION_LOG_RETENTION_DAYS = "1";
+    await getDbClient().run(
+      `WITH RECURSIVE recent(value) AS (
+         SELECT 1
+         UNION ALL
+         SELECT value + 1 FROM recent WHERE value < 10000
+       )
+       INSERT INTO session_logs (id, sessionId, iteration, cli, content, lineNumber, createdAt)
+       SELECT 'recent-' || printf('%05d', value), 'recent-session', 0, 'bun', 'log', value,
+              '2026-08-23T11:59:59.999Z'
+       FROM recent`,
+    );
+
+    const startedAt = Date.now();
+    await runDbRetentionTick({ now: NOW, batchSize: 1, perTableBatchCap: 1 });
+
+    // A page counter must cap the loop even when zero rows are eligible for
+    // deletion, since batches only increments on a page with a match. Without
+    // that cap this sweep walks all 10,000 pages (with a 5ms yield between
+    // each) instead of stopping after the one page the cap allows.
+    expect(Date.now() - startedAt).toBeLessThan(500);
+    expect(getDbRetentionStats().sessionLogs).toMatchObject({ rowsDeleted: 0, batches: 0 });
+    expect(await countRows("session_logs")).toBe(10_000);
+  });
+
+  test("stops a dry-run count when its wall-clock budget expires", async () => {
+    process.env.SESSION_LOG_RETENTION_DAYS = "1";
+    process.env.DB_RETENTION_DRY_RUN = "true";
+    await getDbClient().run(
+      `WITH RECURSIVE candidates(value) AS (
+         SELECT 1
+         UNION ALL
+         SELECT value + 1 FROM candidates WHERE value < 1000
+       )
+       INSERT INTO session_logs (id, sessionId, iteration, cli, content, lineNumber, createdAt)
+       SELECT 'deadline-' || value, 'deadline-session', 0, 'bun', 'log', value, '2026-08-01T00:00:00.000Z'
+       FROM candidates`,
+    );
+
+    const startedAt = Date.now();
+    await runDbRetentionTick({ now: NOW, batchSize: 1, wallClockCapMs: 10 });
+
+    expect(Date.now() - startedAt).toBeLessThan(150);
+    expect(await countRows("session_logs")).toBe(1000);
+    expect(getDbRetentionStats().sessionLogs).toBeUndefined();
+  });
+
+  test("rejects an excessive window without aborting later table sweeps", async () => {
+    process.env.SESSION_LOG_RETENTION_DAYS = String(MAX_DB_RETENTION_DAYS + 1);
+    process.env.AGENT_LOG_RETENTION_DAYS = "1";
+    await insertRow("session_logs", "oversized-window", "2026-08-01T00:00:00.000Z");
+    await insertRow("agent_log", "valid-window", "2026-08-01T00:00:00.000Z");
+
+    await runDbRetentionTick({ now: NOW });
+
+    expect(await countRows("session_logs")).toBe(1);
+    expect(await countRows("agent_log")).toBe(0);
+  });
+
+  test("shutdown cancels an in-flight sweep between batches and waits for it", async () => {
+    process.env.SESSION_LOG_RETENTION_DAYS = "1";
+    for (let index = 0; index < 100; index++) {
+      await insertRow("session_logs", `shutdown-${index}`, "2026-08-01T00:00:00.000Z");
+    }
+
+    const tick = runDbRetentionTick({ now: NOW, batchSize: 1, perTableBatchCap: 100 });
+    while ((await countRows("session_logs")) === 100) {
+      await Bun.sleep(1);
+    }
+    await stopDbRetention();
+    await tick;
+
+    const remaining = await countRows("session_logs");
+    expect(remaining).toBeGreaterThan(0);
+    expect(remaining).toBeLessThan(100);
+    await Bun.sleep(20);
+    expect(await countRows("session_logs")).toBe(remaining);
+  });
+
+  test("runs the first lifecycle tick immediately and can stop cleanly", async () => {
+    process.env.SESSION_LOG_RETENTION_DAYS = "1";
+    await insertRow("session_logs", "lifecycle-old", "2026-08-01T00:00:00.000Z");
+
+    await startDbRetention(60_000);
+
+    expect(await countRows("session_logs")).toBe(0);
+    await stopDbRetention();
+  });
+});

package/src/tests/docs-index-footprint.test.js

@@ -78,7 +78,7 @@ describe("docs API index footprint", () => {
     expect(tasks).toContain('"path":"/api/task-templates","method":"get"');
   });
 
-  test("OpenAPI and generated pages keep all 351 operations", async () => {
+  test("OpenAPI and generated pages keep all 352 operations", async () => {
     const spec = await Bun.file(resolve(repoRoot, "openapi.json")).json();
     const operationKeys = [];
     const tags = new Set();
@@ -102,18 +102,17 @@ describe("docs API index footprint", () => {
     }
 
     const generatedKeys = await generatedOperationKeys();
-    expect(operationKeys).toHaveLength(351);
-    expect(generatedKeys).toHaveLength(351);
+    expect(operationKeys).toHaveLength(352);
+    expect(generatedKeys).toHaveLength(352);
     expect(new Set(generatedKeys)).toEqual(new Set(operationKeys));
   });
 
-  test("keeps retired routes out of the 135-page sitemap source inventory", async () => {
+  test("keeps retired routes out of the sitemap source inventory", async () => {
     const urls = contentRoutes().map((route) => `${baseUrl}${route}`);
     const sitemapSource = await Bun.file(resolve(repoRoot, "docs-site/app/sitemap.ts")).text();
 
     expect(sitemapSource).toContain("source.getPages().map((page) => ({");
     expect(sitemapSource).toMatch(/url:\s*`\$\{baseUrl\}\$\{page\.url\}`/);
-    expect(urls).toHaveLength(135);
     expect(new Set(urls).size).toBe(urls.length);
     for (const route of retiredRoutes) {
       expect(urls).not.toContain(`${baseUrl}${route}`);

package/src/tests/draft-task-dispatch-race.test.ts

@@ -0,0 +1,189 @@
+/**
+ * #1240 — a UI task with attachments is pool-claimable before its
+ * attachments exist. Covers the `draft` status that closes the race:
+ * created dispatch-ineligible, promoted once the upload batch settles (or
+ * times out via the heartbeat sweep for an abandoned draft).
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import {
+  claimTask,
+  closeDb,
+  createAgent,
+  createTaskExtended,
+  getDbClient,
+  getPendingTaskForAgent,
+  getTaskById,
+  initDb,
+  promoteAbandonedDraftTasks,
+  promoteDraftTask,
+} from "../be/db";
+
+const TEST_DB_PATH = "./test-draft-task-dispatch-race.sqlite";
+
+describe("Draft task dispatch race (#1240)", () => {
+  beforeAll(async () => {
+    try {
+      await unlink(TEST_DB_PATH);
+    } catch {
+      // File doesn't exist
+    }
+    closeDb();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    closeDb();
+    try {
+      await unlink(TEST_DB_PATH);
+      await unlink(`${TEST_DB_PATH}-wal`);
+      await unlink(`${TEST_DB_PATH}-shm`);
+    } catch {
+      // Files may not exist
+    }
+  });
+
+  beforeEach(async () => {
+    await getDbClient().run("DELETE FROM agent_tasks");
+    await getDbClient().run("DELETE FROM agents");
+    await getDbClient().run("DELETE FROM agent_log");
+  });
+
+  test("status:'draft' wins over agentId — task lands in draft, not pending", async () => {
+    const agent = await createAgent({ name: "lead-1", isLead: true, status: "idle" });
+    const task = await createTaskExtended("Draft task with owner", {
+      agentId: agent.id,
+      status: "draft",
+    });
+    expect(task.status).toBe("draft");
+    expect(task.agentId).toBe(agent.id);
+  });
+
+  test("status:'draft' wins over offeredTo — task lands in draft, not offered", async () => {
+    const agent = await createAgent({ name: "offeree-1", isLead: false, status: "idle" });
+    const task = await createTaskExtended("Draft task offered", {
+      offeredTo: agent.id,
+      status: "draft",
+    });
+    expect(task.status).toBe("draft");
+  });
+
+  test("a draft task assigned to an agent is NOT returned by getPendingTaskForAgent", async () => {
+    const agent = await createAgent({ name: "lead-2", isLead: true, status: "idle" });
+    await createTaskExtended("Draft task, uploads in flight", {
+      agentId: agent.id,
+      status: "draft",
+    });
+
+    const pending = await getPendingTaskForAgent(agent.id);
+    expect(pending).toBeNull();
+  });
+
+  test("a draft task with no owner is NOT returned by pool claim", async () => {
+    const agent = await createAgent({ name: "worker-1", isLead: false, status: "idle" });
+    const task = await createTaskExtended("Draft task, no owner yet", {
+      status: "draft",
+    });
+
+    const claimed = await claimTask(task.id, agent.id);
+    expect(claimed).toBeNull();
+
+    const stored = await getTaskById(task.id);
+    expect(stored?.status).toBe("draft");
+    expect(stored?.agentId).toBeNull();
+  });
+
+  test("promoteDraftTask moves an owned draft to pending, then it dispatches normally", async () => {
+    const agent = await createAgent({ name: "lead-3", isLead: true, status: "idle" });
+    const task = await createTaskExtended("Draft task to promote", {
+      agentId: agent.id,
+      status: "draft",
+    });
+
+    // Not dispatch-eligible yet.
+    expect(await getPendingTaskForAgent(agent.id)).toBeNull();
+
+    const promoted = await promoteDraftTask(task.id);
+    expect(promoted?.status).toBe("pending");
+    expect(promoted?.agentId).toBe(agent.id);
+
+    // Now dispatch-eligible.
+    const pending = await getPendingTaskForAgent(agent.id);
+    expect(pending?.id).toBe(task.id);
+  });
+
+  test("promoteDraftTask moves an unowned draft to unassigned, then pool claim succeeds", async () => {
+    const worker = await createAgent({ name: "worker-2", isLead: false, status: "idle" });
+    const task = await createTaskExtended("Draft task, no owner", { status: "draft" });
+
+    expect(await claimTask(task.id, worker.id)).toBeNull();
+
+    const promoted = await promoteDraftTask(task.id);
+    expect(promoted?.status).toBe("unassigned");
+
+    const claimed = await claimTask(task.id, worker.id);
+    expect(claimed?.status).toBe("in_progress");
+    expect(claimed?.agentId).toBe(worker.id);
+  });
+
+  test("promoteDraftTask moves an offered draft to offered", async () => {
+    const agent = await createAgent({ name: "offeree-2", isLead: false, status: "idle" });
+    const task = await createTaskExtended("Draft task, offered", {
+      offeredTo: agent.id,
+      status: "draft",
+    });
+
+    const promoted = await promoteDraftTask(task.id);
+    expect(promoted?.status).toBe("offered");
+    expect(promoted?.offeredTo).toBe(agent.id);
+  });
+
+  test("promoteDraftTask is a no-op on a task that already left draft", async () => {
+    const task = await createTaskExtended("Already pending", {});
+    expect(task.status).toBe("unassigned");
+
+    const result = await promoteDraftTask(task.id);
+    expect(result).toBeNull();
+
+    const stored = await getTaskById(task.id);
+    expect(stored?.status).toBe("unassigned");
+  });
+
+  test("promoteAbandonedDraftTasks leaves a fresh draft untouched", async () => {
+    const agent = await createAgent({ name: "lead-4", isLead: true, status: "idle" });
+    const task = await createTaskExtended("Fresh draft", {
+      agentId: agent.id,
+      status: "draft",
+    });
+
+    const promotedCount = await promoteAbandonedDraftTasks(5);
+    expect(promotedCount).toBe(0);
+
+    const stored = await getTaskById(task.id);
+    expect(stored?.status).toBe("draft");
+  });
+
+  test("promoteAbandonedDraftTasks promotes a draft past the timeout", async () => {
+    const agent = await createAgent({ name: "lead-5", isLead: true, status: "idle" });
+    const task = await createTaskExtended("Abandoned draft (tab closed)", {
+      agentId: agent.id,
+      status: "draft",
+    });
+
+    // Simulate an abandoned draft — back-date lastUpdatedAt past the timeout.
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000).toISOString();
+    await getDbClient().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [
+      staleTime,
+      task.id,
+    ]);
+
+    const promotedCount = await promoteAbandonedDraftTasks(5);
+    expect(promotedCount).toBe(1);
+
+    const stored = await getTaskById(task.id);
+    expect(stored?.status).toBe("pending");
+
+    const pending = await getPendingTaskForAgent(agent.id);
+    expect(pending?.id).toBe(task.id);
+  });
+});

package/src/tests/events-http.test.ts

@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { unlink } from "node:fs/promises";
 import type { Subprocess } from "bun";
-import { getFreePort, SERVER_BOOT_HOOK_TIMEOUT_MS, waitForServer } from "./test-net";
+import { getFreePort, SERVER_BOOT_HOOK_TIMEOUT_MS } from "./test-net";
 
 let TEST_PORT = 0;
 const TEST_DB_PATH = `/tmp/test-events-http-${Date.now()}.sqlite`;
@@ -10,6 +10,44 @@ const TEST_API_KEY = "test-events-http-key";
 
 let serverProc: Subprocess;
 
+/**
+ * Poll the child until the authenticated events route answers.
+ *
+ * A refused connection means the child is still booting: keep waiting. The
+ * ceiling matches waitForServer() in test-net.ts because a boot under
+ * --parallel load on a shared runner takes far longer than the ~1 s it takes
+ * idle, and restarting a slow child only resets its progress.
+ *
+ * Any HTTP response that is not a 200 events list comes from another server:
+ * a parallel test claimed the released getFreePort() socket first and the
+ * child's own listen failed with EADDRINUSE. Report "foreign" so the caller
+ * retries on a fresh port right away.
+ */
+async function waitForEventsApi(timeoutMs = 60_000): Promise<"ready" | "foreign"> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`${BASE}/api/events`, {
+        headers: { Authorization: `Bearer ${TEST_API_KEY}` },
+      });
+      const body = (await response.json().catch(() => null)) as { events?: unknown } | null;
+      return response.status === 200 && Array.isArray(body?.events) ? "ready" : "foreign";
+    } catch {
+      // Connection refused: the child has not bound the port yet.
+    }
+    await Bun.sleep(50);
+  }
+  throw new Error(`Events API did not become ready on ${BASE} within ${timeoutMs}ms`);
+}
+
+async function cleanupTestDb(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+}
+
 async function api(
   method: string,
   path: string,
@@ -36,31 +74,40 @@ async function api(
 const get = (p: string) => api("GET", p);
 const post = (p: string, body?: unknown) => api("POST", p, { body });
 
+const PORT_CLAIM_ATTEMPTS = 3;
+
 beforeAll(async () => {
-  TEST_PORT = await getFreePort();
-  BASE = `http://localhost:${TEST_PORT}`;
+  for (let attempt = 1; attempt <= PORT_CLAIM_ATTEMPTS; attempt++) {
+    TEST_PORT = await getFreePort();
+    BASE = `http://localhost:${TEST_PORT}`;
+    await cleanupTestDb();
 
-  try {
-    await unlink(TEST_DB_PATH);
-  } catch {}
+    serverProc = Bun.spawn(["bun", "src/http.ts"], {
+      cwd: `${import.meta.dir}/../..`,
+      env: {
+        ...process.env,
+        PORT: String(TEST_PORT),
+        DATABASE_PATH: TEST_DB_PATH,
+        API_KEY: TEST_API_KEY,
+        CAPABILITIES: "core",
+        SLACK_BOT_TOKEN: "",
+        GITHUB_WEBHOOK_SECRET: "",
+        AGENTMAIL_API_KEY: "",
+      },
+      stdout: "ignore",
+      stderr: "ignore",
+    });
 
-  serverProc = Bun.spawn(["bun", "src/http.ts"], {
-    cwd: `${import.meta.dir}/../..`,
-    env: {
-      ...process.env,
-      PORT: String(TEST_PORT),
-      DATABASE_PATH: TEST_DB_PATH,
-      API_KEY: TEST_API_KEY,
-      CAPABILITIES: "core",
-      SLACK_BOT_TOKEN: "",
-      GITHUB_WEBHOOK_SECRET: "",
-      AGENTMAIL_API_KEY: "",
-    },
-    stdout: "ignore",
-    stderr: "ignore",
-  });
+    // A slow boot throws here and fails the suite: afterAll still kills the child.
+    if ((await waitForEventsApi()) === "ready") return;
 
-  await waitForServer(`${BASE}/health`);
+    // Another server owns this port. Drop the child and try a fresh port.
+    serverProc.kill();
+    await serverProc.exited.catch(() => {});
+  }
+  throw new Error(
+    `another server claimed the events-http port on ${PORT_CLAIM_ATTEMPTS} consecutive attempts`,
+  );
 }, SERVER_BOOT_HOOK_TIMEOUT_MS);
 
 afterAll(async () => {
@@ -71,11 +118,7 @@ afterAll(async () => {
     } catch {}
   }
   await Bun.sleep(50);
-  try {
-    await unlink(TEST_DB_PATH);
-    await unlink(`${TEST_DB_PATH}-wal`);
-    await unlink(`${TEST_DB_PATH}-shm`);
-  } catch {}
+  await cleanupTestDb();
 });
 
 describe("POST /api/events — single event", () => {