@desplega.ai/agent-swarm 1.135.2 → 1.136.0

package/src/tests/otel-abort-span.test.ts

@@ -0,0 +1,156 @@
+/**
+ * A client that disconnects mid-request fires neither `finish` nor `error` —
+ * `wireHttpSpanLifecycle` (used by `src/http/index.ts`) handles that via
+ * `res.on("close", ...)`. Two invariants on that path:
+ *
+ *  1. `http.response.status_code` must not report the pre-`writeHead` `200`
+ *     default when no response was ever sent (self-contradicts
+ *     `agentswarm.http.aborted: true`).
+ *  2. The span status must stay Unset — OTel HTTP semconv reserves ERROR for
+ *     5xx, and a client abort is the normal SSE teardown path for /mcp and
+ *     /mcp-user.
+ *
+ * (1) is a pure function (`abortedStatusCodeAttribute`), tested directly.
+ * (2), plus the end-exactly-once guarantee across `finish`/`error`/`close` in
+ * every firing order, is exercised against `wireHttpSpanLifecycle` with a
+ * mocked response and span — extracted out of `src/http/index.ts` (which
+ * binds a port at module scope, see `shutdown-error-scrubbing.test.ts`)
+ * specifically so this lifecycle is testable without reading source text.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  abortedStatusCodeAttribute,
+  type SpanLifecycleResponse,
+  wireHttpSpanLifecycle,
+} from "../http/utils";
+import type { Attributes, SpanStatus, SwarmSpan } from "../otel";
+
+function createMockResponse(headersSent: boolean) {
+  const listeners: Record<string, ((err?: Error) => void)[]> = {};
+  const res: SpanLifecycleResponse & {
+    emit: (event: "finish" | "error" | "close", err?: Error) => void;
+  } = {
+    headersSent,
+    on(event, listener) {
+      if (!listeners[event]) listeners[event] = [];
+      listeners[event].push(listener);
+      return res;
+    },
+    emit(event, err) {
+      for (const listener of listeners[event] ?? []) listener(err);
+    },
+  };
+  return res;
+}
+
+function createMockSpan() {
+  const attributeCalls: Attributes[] = [];
+  const statusCalls: SpanStatus[] = [];
+  let endCalls = 0;
+  const span: SwarmSpan = {
+    setAttribute: () => span,
+    setAttributes: (attrs) => {
+      attributeCalls.push(attrs);
+      return span;
+    },
+    addEvent: () => span,
+    recordException: () => {},
+    setStatus: (status) => {
+      statusCalls.push(status);
+      return span;
+    },
+    end: () => {
+      endCalls += 1;
+    },
+  };
+  return { span, attributeCalls, statusCalls, getEndCalls: () => endCalls };
+}
+
+describe("abortedStatusCodeAttribute", () => {
+  test("omits the status code when no response was ever sent", () => {
+    expect(abortedStatusCodeAttribute(false, 200)).toBeUndefined();
+  });
+
+  test("reports the real status code once headers were sent", () => {
+    expect(abortedStatusCodeAttribute(true, 404)).toBe(404);
+  });
+});
+
+describe("wireHttpSpanLifecycle", () => {
+  test("a premature close (no finish, no error) ends the span exactly once, marks aborted, omits the fabricated status", () => {
+    const res = createMockResponse(false);
+    const { span, attributeCalls, statusCalls, getEndCalls } = createMockSpan();
+    wireHttpSpanLifecycle(res, span, () => 200, performance.now());
+
+    res.emit("close");
+
+    expect(getEndCalls()).toBe(1);
+    expect(attributeCalls.at(-1)).toMatchObject({ "agentswarm.http.aborted": true });
+    // headersSent is false — must not claim the pre-writeHead 200 default was sent.
+    expect(attributeCalls.at(-1)?.["http.response.status_code"]).toBeUndefined();
+    // A client abort is not a 5xx — status must stay Unset, not ERROR.
+    expect(statusCalls).toEqual([]);
+  });
+
+  test("close firing before a would-be finish leaves the span ended — finish is a no-op", () => {
+    const res = createMockResponse(true);
+    const { span, getEndCalls } = createMockSpan();
+    wireHttpSpanLifecycle(res, span, () => 200, performance.now());
+
+    res.emit("close");
+    res.emit("finish");
+
+    // Deleting the guard (or the close handler's `span.end()`) would leave
+    // this at 0 or let a second `end()` land — either way the count moves.
+    expect(getEndCalls()).toBe(1);
+  });
+
+  test("close after headers were sent reports the real status code, not the 200 default", () => {
+    const res = createMockResponse(true);
+    const { span, attributeCalls } = createMockSpan();
+    wireHttpSpanLifecycle(res, span, () => 404, performance.now());
+
+    res.emit("close");
+
+    expect(attributeCalls.at(-1)?.["http.response.status_code"]).toBe(404);
+  });
+
+  test("finish then close (the happy-path order) ends the span exactly once and never marks aborted", () => {
+    const res = createMockResponse(true);
+    const { span, attributeCalls, getEndCalls } = createMockSpan();
+    wireHttpSpanLifecycle(res, span, () => 200, performance.now());
+
+    res.emit("finish");
+    res.emit("close");
+
+    expect(getEndCalls()).toBe(1);
+    for (const attrs of attributeCalls) {
+      expect(attrs).not.toHaveProperty("agentswarm.http.aborted");
+    }
+  });
+
+  test("a 5xx finish sets ERROR status; close arriving after it is a no-op", () => {
+    const res = createMockResponse(true);
+    const { span, statusCalls, getEndCalls } = createMockSpan();
+    wireHttpSpanLifecycle(res, span, () => 503, performance.now());
+
+    res.emit("finish");
+    res.emit("close");
+
+    expect(getEndCalls()).toBe(1);
+    expect(statusCalls).toEqual([{ code: 2, message: "HTTP 503" }]);
+  });
+
+  test("error ends the span exactly once and records ERROR status; a later close is a no-op", () => {
+    const res = createMockResponse(false);
+    const { span, statusCalls, getEndCalls } = createMockSpan();
+    wireHttpSpanLifecycle(res, span, () => 200, performance.now());
+
+    res.emit("error", new Error("boom"));
+    res.emit("close");
+
+    expect(getEndCalls()).toBe(1);
+    expect(statusCalls).toEqual([{ code: 2, message: "boom" }]);
+  });
+});

package/src/tests/otel-span-kind.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Tests that `startSpan` maps the backend-agnostic `SwarmSpanKind` onto the
+ * real OTel `SpanKind` before handing it to the tracer. Datadog's APM
+ * resource-name derivation only appends `http.route` for `SpanKindServer`
+ * spans — an inbound HTTP span created without an explicit kind defaults to
+ * `INTERNAL` and collapses every endpoint into one resource per method.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { SpanKind, type Tracer } from "@opentelemetry/api";
+import { _injectTracerForTests, startSpan } from "../otel-impl";
+
+function fakeTracer() {
+  const calls: { name: string; kind: SpanKind | undefined }[] = [];
+  const tracer = {
+    startSpan(name: string, options?: { kind?: SpanKind }) {
+      calls.push({ name, kind: options?.kind });
+      return {
+        setAttribute: () => {},
+        setAttributes: () => {},
+        addEvent: () => {},
+        recordException: () => {},
+        setStatus: () => {},
+        end: () => {},
+      };
+    },
+  };
+  return { calls, tracer: tracer as unknown as Tracer };
+}
+
+describe("startSpan span-kind mapping", () => {
+  afterEach(() => {
+    _injectTracerForTests(undefined);
+  });
+
+  test("forwards SpanKind.SERVER when kind: 'server' is requested", () => {
+    const { calls, tracer } = fakeTracer();
+    _injectTracerForTests(tracer);
+
+    startSpan(
+      "GET /api/attribution/by-person",
+      { "http.request.method": "GET" },
+      { kind: "server" },
+    );
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.kind).toBe(SpanKind.SERVER);
+  });
+
+  test("leaves kind undefined when no options are passed", () => {
+    const { calls, tracer } = fakeTracer();
+    _injectTracerForTests(tracer);
+
+    startSpan("mcp.tool kv-get", { "mcp.tool.name": "kv-get" });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.kind).toBeUndefined();
+  });
+});

package/src/tests/promote-draft-task-route.test.ts

@@ -0,0 +1,175 @@
+/**
+ * HTTP-level coverage for the #1240 draft-task surface: `POST /api/tasks`
+ * with `draft: true` and `POST /api/tasks/{id}/promote-draft`.
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import { closeDb, createAgent, createTaskExtended, createUser, initDb } from "../be/db";
+import { findUserById } from "../be/users";
+import { handleTasks } from "../http/tasks";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import { setRequestAuth } from "../utils/request-auth-context";
+
+const TEST_DB_PATH = "./test-promote-draft-task-route.sqlite";
+
+let server: Server;
+let baseUrl: string;
+let leadAgentId: string;
+
+function createTestServer(): Server {
+  return createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+    // Tests opt into a "user" principal via `x-test-user-id`; otherwise the
+    // request runs as a trusted operator (ownership checks pass through),
+    // matching the existing task-title-route.test.ts pattern.
+    const testUserId = req.headers["x-test-user-id"] as string | undefined;
+    if (testUserId) {
+      const user = await findUserById(testUserId);
+      setRequestAuth(req, user ? { kind: "user", userId: user.id, user } : null);
+    } else {
+      setRequestAuth(req, { kind: "operator", fingerprint: "promote-draft-route-test" });
+    }
+    res.setHeader("Content-Type", "application/json");
+    const pathSegments = getPathSegments(req.url ?? "");
+    const query = parseQueryParams(req.url ?? "");
+    const callerAgentId = req.headers["x-agent-id"] as string | undefined;
+    if (await handleTasks(req, res, pathSegments, query, callerAgentId)) return;
+    res.writeHead(404);
+    res.end(JSON.stringify({ error: "Not found" }));
+  });
+}
+
+async function api(
+  method: string,
+  path: string,
+  body?: unknown,
+  headers?: Record<string, string>,
+): Promise<{ status: number; body: any }> {
+  const response = await fetch(`${baseUrl}${path}`, {
+    method,
+    headers: { "Content-Type": "application/json", ...headers },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await response.text();
+  return { status: response.status, body: text ? JSON.parse(text) : undefined };
+}
+
+beforeAll(async () => {
+  initDb(TEST_DB_PATH);
+  leadAgentId = (
+    await createAgent({ name: "promote-draft-route-lead", isLead: true, status: "idle" })
+  ).id;
+
+  server = createTestServer();
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("test server did not listen");
+  baseUrl = `http://127.0.0.1:${address.port}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+});
+
+describe("POST /api/tasks draft:true + /promote-draft (#1240)", () => {
+  test("draft:true creates a task in draft status, invisible to the assigned agent's dispatch queue", async () => {
+    const created = await api("POST", "/api/tasks", {
+      task: "session with attachments uploading",
+      agentId: leadAgentId,
+      source: "ui",
+      draft: true,
+    });
+    expect(created.status).toBe(201);
+    expect(created.body.status).toBe("draft");
+    expect(created.body.agentId).toBe(leadAgentId);
+
+    // Session list surfacing (GET /api/sessions) isn't wired into handleTasks
+    // — covered separately by listRecentSessions having no status filter.
+  });
+
+  test("promote-draft transitions draft -> pending for an owned task", async () => {
+    const created = await api("POST", "/api/tasks", {
+      task: "another draft session",
+      agentId: leadAgentId,
+      source: "ui",
+      draft: true,
+    });
+    expect(created.body.status).toBe("draft");
+
+    const promoted = await api("POST", `/api/tasks/${created.body.id}/promote-draft`);
+    expect(promoted.status).toBe(200);
+    expect(promoted.body.status).toBe("pending");
+    expect(promoted.body.agentId).toBe(leadAgentId);
+  });
+
+  test("promote-draft is idempotent — a second call returns the already-promoted task", async () => {
+    const created = await api("POST", "/api/tasks", {
+      task: "idempotency check",
+      agentId: leadAgentId,
+      source: "ui",
+      draft: true,
+    });
+
+    const first = await api("POST", `/api/tasks/${created.body.id}/promote-draft`);
+    expect(first.status).toBe(200);
+    expect(first.body.status).toBe("pending");
+
+    const second = await api("POST", `/api/tasks/${created.body.id}/promote-draft`);
+    expect(second.status).toBe(200);
+    expect(second.body.status).toBe("pending");
+  });
+
+  test("promote-draft on a task with no owner promotes to unassigned", async () => {
+    const task = await createTaskExtended("owner-less draft", { status: "draft" });
+    const promoted = await api("POST", `/api/tasks/${task.id}/promote-draft`);
+    expect(promoted.status).toBe(200);
+    expect(promoted.body.status).toBe("unassigned");
+  });
+
+  test("unknown task id returns 404", async () => {
+    const res = await api("POST", "/api/tasks/nonexistent-task-id/promote-draft");
+    expect(res.status).toBe(404);
+  });
+
+  test("a user who did not request the task cannot promote it", async () => {
+    const owner = await createUser({ name: "Draft Owner" });
+    const stranger = await createUser({ name: "Not The Owner" });
+
+    const created = await api(
+      "POST",
+      "/api/tasks",
+      {
+        task: "owned draft session",
+        agentId: leadAgentId,
+        source: "ui",
+        draft: true,
+        requestedByUserId: owner.id,
+      },
+      { "x-test-user-id": owner.id },
+    );
+    expect(created.body.status).toBe("draft");
+    expect(created.body.requestedByUserId).toBe(owner.id);
+
+    const deniedRes = await api("POST", `/api/tasks/${created.body.id}/promote-draft`, undefined, {
+      "x-test-user-id": stranger.id,
+    });
+    expect(deniedRes.status).toBe(403);
+
+    const allowedRes = await api("POST", `/api/tasks/${created.body.id}/promote-draft`, undefined, {
+      "x-test-user-id": owner.id,
+    });
+    expect(allowedRes.status).toBe(200);
+    expect(allowedRes.body.status).toBe("pending");
+  });
+});

package/src/tests/route-def-find-route.test.ts

@@ -73,21 +73,107 @@ describe("describeRequestRoute", () => {
     expect(desc.httpRoute).toBe("/api/tasks");
   });
 
-  test("unmatched path falls back to `{METHOD} /{firstSegment}` and omits http.route", () => {
-    // /health is a core route not declared via route(), so no template match.
+  test("a core static route not declared via route() still gets http.route", () => {
+    // /health isn't registered through route(), but it's a fixed literal path
+    // (not a template), so CORE_ROUTE_TEMPLATES maps it to http.route too.
     const desc = describeRequestRoute("GET", ["health"]);
     expect(desc.spanName).toBe("GET /health");
-    // No fabricated value — http.route is omitted for unmatched paths.
+    expect(desc.httpRoute).toBe("/health");
+  });
+
+  test("unmatched path with no core-route entry falls back to `{METHOD} /{firstSegment}` and omits http.route", () => {
+    const desc = describeRequestRoute("GET", ["nope", "missing"]);
+    expect(desc.spanName).toBe("GET /nope");
+    // No fabricated value — http.route is omitted for genuinely unmatched paths.
     expect(desc.httpRoute).toBeUndefined();
   });
 
   test("unmatched deeper path still only uses the first segment, no http.route", () => {
-    // Bounded cardinality: never `GET /mcp/<session-id>`.
+    // Bounded cardinality: never `GET /mcp/<session-id>`. The core-route
+    // template only matches the exact literal `/mcp`, not a deeper path under it.
     const desc = describeRequestRoute("POST", ["mcp", "session-xyz", "messages"]);
     expect(desc.spanName).toBe("POST /mcp");
     expect(desc.httpRoute).toBeUndefined();
   });
 
+  test("the exact literal /mcp path gets http.route", () => {
+    const desc = describeRequestRoute("POST", ["mcp"]);
+    expect(desc.spanName).toBe("POST /mcp");
+    expect(desc.httpRoute).toBe("/mcp");
+  });
+
+  test("a multi-segment core static route gets its full path as http.route", () => {
+    const desc = describeRequestRoute("POST", ["internal", "reload-config"]);
+    expect(desc.spanName).toBe("POST /internal/reload-config");
+    expect(desc.httpRoute).toBe("/internal/reload-config");
+  });
+
+  test("POST /me is a 404 in handleCore (GET-only) and must not carry http.route", () => {
+    const desc = describeRequestRoute("POST", ["me"]);
+    expect(desc.spanName).toBe("POST /me");
+    expect(desc.httpRoute).toBeUndefined();
+  });
+
+  test("GET /internal/reload-config is a 404 in handleCore (POST-only) and must not carry http.route", () => {
+    const desc = describeRequestRoute("GET", ["internal", "reload-config"]);
+    expect(desc.spanName).toBe("GET /internal");
+    expect(desc.httpRoute).toBeUndefined();
+  });
+
+  test("PUT /mcp is a 405 in handleMcp (GET/POST/DELETE-only) and must not carry http.route", () => {
+    const desc = describeRequestRoute("PUT", ["mcp"]);
+    expect(desc.spanName).toBe("PUT /mcp");
+    expect(desc.httpRoute).toBeUndefined();
+  });
+
+  test("POST /health has no method gate in handleCore, so it still carries http.route", () => {
+    const desc = describeRequestRoute("POST", ["health"]);
+    expect(desc.spanName).toBe("POST /health");
+    expect(desc.httpRoute).toBe("/health");
+  });
+
+  test("GET /health?t=123 is a 404 in handleCore (strict URL equality) and must not carry http.route", () => {
+    const desc = describeRequestRoute("GET", ["health"], true);
+    expect(desc.spanName).toBe("GET /health");
+    expect(desc.httpRoute).toBeUndefined();
+  });
+
+  test("GET /me?x=1 matches handleCore's `?`-suffixed form and keeps http.route", () => {
+    const desc = describeRequestRoute("GET", ["me"], true);
+    expect(desc.spanName).toBe("GET /me");
+    expect(desc.httpRoute).toBe("/me");
+  });
+
+  test("GET /health/ is a 404 in handleCore (strict URL equality) and must not carry http.route", () => {
+    const desc = describeRequestRoute("GET", ["health"], false, true);
+    expect(desc.spanName).toBe("GET /health");
+    expect(desc.httpRoute).toBeUndefined();
+  });
+
+  test("GET /openapi.json/ is a 404 in handleCore and must not carry http.route", () => {
+    const desc = describeRequestRoute("GET", ["openapi.json"], false, true);
+    expect(desc.spanName).toBe("GET /openapi.json");
+    expect(desc.httpRoute).toBeUndefined();
+  });
+
+  test("POST /mcp/ is a 404 in handleMcp (strict URL equality) and must not carry http.route", () => {
+    const desc = describeRequestRoute("POST", ["mcp"], false, true);
+    expect(desc.spanName).toBe("POST /mcp");
+    expect(desc.httpRoute).toBeUndefined();
+  });
+
+  test("GET /mcp-user/ is a 404 in handleCore (strict URL equality) and must not carry http.route", () => {
+    const desc = describeRequestRoute("GET", ["mcp-user"], false, true);
+    expect(desc.spanName).toBe("GET /mcp-user");
+    expect(desc.httpRoute).toBeUndefined();
+  });
+
+  test("GET /docs/ is the one intentional exception and keeps http.route", () => {
+    const desc = describeRequestRoute("GET", ["docs"], false, true);
+    expect(desc.spanName).toBe("GET /docs");
+    expect(desc.httpRoute).toBe("/docs");
+  });
+
   test("known path with unknown method omits http.route", () => {
     // No PATCH handler on /api/tasks — must not fabricate a template.
     const desc = describeRequestRoute("PATCH", ["api", "tasks"]);

package/src/tests/sibling-block.test.ts

@@ -19,6 +19,7 @@ function sibling(overrides: Partial<SiblingTaskInfo> = {}): SiblingTaskInfo {
     agentName: "Picateclas",
     description: "Do the thing",
     updatedAt: new Date(NOW - 60_000).toISOString(),
+    createdAt: new Date(NOW - 60_000).toISOString(),
     ...overrides,
   };
 }
@@ -100,7 +101,34 @@ describe("renderSiblingBlock", () => {
     );
     expect(out).toContain("[in_progress] task:id-1");
     expect(out).toContain("[pending] task:id-2");
-    expect(out).toContain("started 1h ago");
+    expect(out).toContain("last active 1h ago");
+  });
+
+  test("reports start time from createdAt, not from the progress-bumped updatedAt", () => {
+    // Regression: a sibling created 60s ago that emitted a progress event 1s
+    // ago used to render as "started 1s ago", making two independent user
+    // inputs look like a double-submit of the same one.
+    const out = renderSiblingBlock(
+      "task:slack:C1:1",
+      [
+        sibling({
+          createdAt: new Date(NOW - 60_000).toISOString(),
+          updatedAt: new Date(NOW - 1_000).toISOString(),
+        }),
+      ],
+      NOW,
+    );
+    expect(out).toContain("started 1m ago, last active 1s ago");
+    expect(out).not.toContain("started 1s ago");
+  });
+
+  test("omits the started clause rather than guessing when createdAt is absent", () => {
+    const { createdAt: _omitted, ...withoutCreatedAt } = sibling({
+      updatedAt: new Date(NOW - 1_000).toISOString(),
+    });
+    const out = renderSiblingBlock("task:slack:C1:1", [withoutCreatedAt], NOW);
+    expect(out).toContain("last active 1s ago");
+    expect(out).not.toContain("started");
   });
 
   test("falls back to agent:unassigned when no agent info", () => {

package/src/tests/slack-assistant-comention-production.test.ts

@@ -30,6 +30,7 @@ process.env.SLACK_RENDER_V2 = "false";
 
 let createAssistantFn: typeof import("../slack/assistant").createAssistant;
 let registerMessageHandlerFn: typeof import("../slack/handlers").registerMessageHandler;
+let resetSlackHandlerCachesForTestingFn: typeof import("../slack/handlers").resetSlackHandlerCachesForTesting;
 
 let createTaskWithSiblingAwarenessSpy: any;
 let getAllAgentsSpy: any;
@@ -98,7 +99,11 @@ beforeAll(async () => {
   installSpyImplementations();
 
   ({ createAssistant: createAssistantFn } = await import("../slack/assistant"));
-  ({ registerMessageHandler: registerMessageHandlerFn } = await import("../slack/handlers"));
+  ({
+    registerMessageHandler: registerMessageHandlerFn,
+    resetSlackHandlerCachesForTesting: resetSlackHandlerCachesForTestingFn,
+  } = await import("../slack/handlers"));
+  resetSlackHandlerCachesForTestingFn();
 });
 
 beforeEach(() => {
@@ -120,6 +125,7 @@ afterAll(() => {
   restoreEnvValue("SLACK_ALLOWED_EMAIL_DOMAINS");
   restoreEnvValue("SLACK_ALLOWED_USER_IDS");
   mock.restore();
+  resetSlackHandlerCachesForTestingFn();
 });
 
 // ---------------------------------------------------------------------------

package/src/tests/steering-enabled.test.ts

@@ -198,6 +198,12 @@ describe("STEERING_ENABLED opt-in", () => {
     });
   });
 
+  test("reports an empty retention object on the authenticated metrics endpoint before a sweep", async () => {
+    const metrics = await api("GET", "/api/metrics");
+    expect(metrics.status).toBe(200);
+    expect(metrics.body.retention).toEqual({});
+  });
+
   test("removes steering MCP tools when disabled and restores them when enabled", async () => {
     await withSteeringDisabled(async () => {
       const serverTools = registeredTools(await createServer({ fullSurface: true }));

package/src/tests/swarm-config-reserved-keys.test.ts

@@ -249,6 +249,17 @@ describe("swarm-config reserved keys guard", () => {
 
   // ─── MCP tool: set-config ─────────────────────────────────────────────────
   describe("MCP set-config tool", () => {
+    test("rejects an invalid database retention dry-run flag", async () => {
+      const handler = mcpServer.handlers.get("set-config");
+      const result = (await handler!(
+        { scope: "global", key: "DB_RETENTION_DRY_RUN", value: "treu" },
+        makeRequestInfo(),
+      )) as { structuredContent: { success: boolean; message: string } };
+
+      expect(result.structuredContent.success).toBe(false);
+      expect(result.structuredContent.message).toContain("Invalid DB_RETENTION_DRY_RUN");
+    });
+
     test("rejects reserved key with structured error", async () => {
       const handler = mcpServer.handlers.get("set-config");
       expect(handler).toBeDefined();
@@ -385,6 +396,22 @@ describe("swarm-config reserved keys guard", () => {
 
   // ─── HTTP: PUT /api/config ────────────────────────────────────────────────
   describe("HTTP PUT /api/config", () => {
+    test("returns 400 for an invalid database retention dry-run flag", async () => {
+      const res = await fetch(`${baseUrl}/api/config`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          scope: "global",
+          key: "DB_RETENTION_DRY_RUN",
+          value: "treu",
+        }),
+      });
+
+      expect(res.status).toBe(400);
+      const body = (await res.json()) as { error: string };
+      expect(body.error).toContain("Invalid DB_RETENTION_DRY_RUN");
+    });
+
     test("returns 400 for reserved key API_KEY", async () => {
       const res = await fetch(`${baseUrl}/api/config`, {
         method: "PUT",

package/src/types.ts

@@ -237,6 +237,7 @@ export function resolveTaskModelSelection(opts: {
 
 // Task status - includes new unassigned and offered states
 export const AgentTaskStatusSchema = z.enum([
+  "draft", // Created but not yet dispatch-eligible (UI attachments still uploading, #1240); promoted to pending/offered/unassigned once the upload batch settles or times out
   "backlog", // Task is in backlog, not yet ready for pool
   "unassigned", // Task pool - no owner yet
   "offered", // Offered to agent, awaiting accept/reject
@@ -654,7 +655,7 @@ export const CreateTaskOptionsSchema = z.object({
   dependsOn: z.array(z.string()).optional(),
   offeredTo: z.string().optional(),
   /** Explicitly set initial status. */
-  status: z.enum(["backlog", "unassigned"]).optional(),
+  status: z.enum(["draft", "backlog", "unassigned"]).optional(),
   slackChannelId: z.string().optional(),
   slackThreadTs: z.string().optional(),
   /** Exact Slack message that directly triggered this task; never inherited. */

package/templates/skills/swarm-scripts/SKILL.md

@@ -137,6 +137,10 @@ function rowsToObjects(res: any): any[] {
 }
 ```
 
+### Concurrency limit
+
+`ctx.swarm.db_query` throttles at about three concurrent calls. A wider `Promise.all` fan-out can return 429 responses with no `rows` key, so `res?.data?.rows ?? []` misreads throttling as a clean zero. Check the response status and `data.error` before reading `rows`. Serialize queries or cap concurrency at three.
+
 Common tables: `agent_tasks`, `session_logs`, `agent_memory`, `scheduled_tasks`, `agents`. `session_logs` has no `tool_name` column. Tool names sit inside the `content` JSON column. Extract them with `instr` and `substr` in SQL, or parse the JSON in the script.
 
 ## Progress from a script

package/templates/skills/swarm-scripts/content.md

@@ -132,6 +132,10 @@ function rowsToObjects(res: any): any[] {
 }
 ```
 
+### Concurrency limit
+
+`ctx.swarm.db_query` throttles at about three concurrent calls. A wider `Promise.all` fan-out can return 429 responses with no `rows` key, so `res?.data?.rows ?? []` misreads throttling as a clean zero. Check the response status and `data.error` before reading `rows`. Serialize queries or cap concurrency at three.
+
 Common tables: `agent_tasks`, `session_logs`, `agent_memory`, `scheduled_tasks`, `agents`. `session_logs` has no `tool_name` column. Tool names sit inside the `content` JSON column. Extract them with `instr` and `substr` in SQL, or parse the JSON in the script.
 
 ## Progress from a script