@desplega.ai/agent-swarm 1.99.1 → 1.100.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.99.1",
+    "version": "1.100.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.99.1",
+  "version": "1.100.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -111,14 +111,14 @@
     "@aws-sdk/client-bedrock": "3.1048.0",
     "@desplega.ai/business-use": "^0.4.2",
     "@desplega.ai/localtunnel": "^2.2.0",
-    "@earendil-works/pi-agent-core": "^0.79.1",
-    "@earendil-works/pi-ai": "^0.79.1",
-    "@earendil-works/pi-coding-agent": "^0.79.1",
+    "@earendil-works/pi-agent-core": "^0.79.6",
+    "@earendil-works/pi-ai": "^0.79.6",
+    "@earendil-works/pi-coding-agent": "^0.79.6",
     "@inkjs/ui": "^2.0.0",
     "@linear/sdk": "^77.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@openai/codex-sdk": "^0.139.0",
-    "@opencode-ai/sdk": "^1.17.4",
+    "@openai/codex-sdk": "^0.140.0",
+    "@opencode-ai/sdk": "^1.17.7",
     "@openfort/openfort-node": "^0.9.1",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",

package/src/be/db.ts

@@ -4,6 +4,7 @@ import pkg from "../../package.json";
 import { addEyesReactionOnTaskStart } from "../github/task-reactions";
 import { type ModelTier, parseModelTier } from "../model-tiers";
 import { configureDbResolver } from "../prompts/resolver";
+import { telemetry } from "../telemetry";
 import type {
   ActiveSession,
   Agent,
@@ -114,6 +115,19 @@ import { isReservedConfigKey, reservedKeyError } from "./swarm-config-guard";
 let db: Database | null = null;
 let sqliteVecAvailable = false;
 
+type TaskTelemetryProps = Parameters<typeof telemetry.taskEvent>[1];
+
+function emitTaskLifecycleTelemetryAfterCommit(
+  event: string,
+  props: TaskTelemetryProps,
+  verify?: (task: AgentTask | null) => boolean,
+): void {
+  queueMicrotask(() => {
+    if (verify && !verify(getTaskById(props.taskId))) return;
+    telemetry.taskEvent(event, props);
+  });
+}
+
 export function isSqliteVecAvailable(): boolean {
   return sqliteVecAvailable;
 }
@@ -2105,6 +2119,16 @@ export function completeTask(id: string, output?: string): AgentTask | null {
   }
 
   if (row && oldTask) {
+    emitTaskLifecycleTelemetryAfterCommit(
+      "completed",
+      {
+        taskId: id,
+        agentId: row.agentId ?? undefined,
+        durationMs: row.createdAt ? Date.now() - new Date(row.createdAt).getTime() : undefined,
+      },
+      (task) => task?.status === "completed",
+    );
+
     try {
       createLogEntry({
         eventType: "task_status_change",
@@ -2145,6 +2169,16 @@ export function failTask(id: string, reason: string): AgentTask | null {
   const scrubbedReason = scrubSecrets(reason);
   const row = taskQueries.setFailure().get(scrubbedReason, finishedAt, id);
   if (row && oldTask) {
+    emitTaskLifecycleTelemetryAfterCommit(
+      "failed",
+      {
+        taskId: id,
+        agentId: row.agentId ?? undefined,
+        durationMs: row.createdAt ? Date.now() - new Date(row.createdAt).getTime() : undefined,
+      },
+      (task) => task?.status === "failed",
+    );
+
     try {
       createLogEntry({
         eventType: "task_status_change",
@@ -2192,6 +2226,20 @@ export function cancelTask(id: string, reason?: string): AgentTask | null {
   const row = taskQueries.setCancelled().get(cancelReason, finishedAt, id);
 
   if (row && oldTask) {
+    emitTaskLifecycleTelemetryAfterCommit(
+      "cancelled",
+      {
+        taskId: id,
+        source: oldTask.source,
+        agentId: oldTask.agentId ?? undefined,
+        previousStatus: oldTask.status,
+        durationMs: oldTask.createdAt
+          ? Date.now() - new Date(oldTask.createdAt).getTime()
+          : undefined,
+      },
+      (task) => task?.status === "cancelled",
+    );
+
     try {
       createLogEntry({
         eventType: "task_status_change",
@@ -3157,6 +3205,18 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
     });
   } catch {}
 
+  emitTaskLifecycleTelemetryAfterCommit(
+    "created",
+    {
+      taskId: row.id,
+      source: row.source,
+      tags: options?.tags ?? [],
+      hasParent: !!row.parentTaskId,
+      priority: row.priority,
+    },
+    (task) => task !== null,
+  );
+
   try {
     import("../workflows/event-bus").then(({ workflowEventBus }) => {
       workflowEventBus.emit("task.created", {

package/src/http/index.ts

@@ -382,7 +382,7 @@ async function shutdown() {
   // Stop OAuth keepalive
   if (process.env.OAUTH_KEEPALIVE_DISABLE !== "true") {
     const { stopOAuthKeepalive } = await import("../oauth/keepalive");
-    stopOAuthKeepalive();
+    await stopOAuthKeepalive();
   }
 
   // Stop MCP OAuth pending-session garbage collector

package/src/http/tasks.ts

@@ -26,7 +26,6 @@ import {
 import { ModelTierSchema, splitLegacyModelAlias } from "../model-tiers";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { createResumeFollowUp, createWorkerTaskFollowUp } from "../tasks/worker-follow-up";
-import { telemetry } from "../telemetry";
 import {
   type AgentTaskSource,
   AgentTaskSourceSchema,
@@ -420,14 +419,6 @@ export async function handleTasks(
         },
       });
 
-      telemetry.taskEvent("created", {
-        taskId: task.id,
-        source: task.source,
-        tags: parsed.body.tags ?? [],
-        hasParent: !!task.parentTaskId,
-        priority: task.priority,
-      });
-
       json(res, task, 201);
     } catch (error) {
       console.error("[HTTP] Failed to create task:", error);
@@ -536,14 +527,6 @@ export async function handleTasks(
       });
     }
 
-    telemetry.taskEvent("cancelled", {
-      taskId: parsed.params.id,
-      source: task.source,
-      agentId: task.agentId ?? undefined,
-      previousStatus: task.status,
-      durationMs: task.createdAt ? Date.now() - new Date(task.createdAt).getTime() : undefined,
-    });
-
     if (task.agentId) {
       updateAgentStatusFromCapacity(task.agentId);
     }
@@ -645,15 +628,6 @@ export async function handleTasks(
     if (result.task && !("alreadyFinished" in result && result.alreadyFinished)) {
       const finishEventId = parsed.body.status === "completed" ? "completed" : "failed";
 
-      const durationMs = result.task.createdAt
-        ? Date.now() - new Date(result.task.createdAt).getTime()
-        : undefined;
-
-      telemetry.taskEvent(finishEventId, {
-        taskId: parsed.params.id,
-        agentId: myAgentId,
-        durationMs,
-      });
       ensure({
         id: finishEventId,
         flow: "task",

package/src/jira/webhook-lifecycle.ts

@@ -10,7 +10,6 @@ const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
  * first refresh round-trip (Atlassian returns the authoritative expiry).
  */
 const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
-const SLACK_ALERTS_CHANNEL = process.env.SLACK_ALERTS_CHANNEL || "C08JCRURPBV";
 
 const WEBHOOK_EVENTS = [
   "jira:issue_updated",
@@ -40,6 +39,12 @@ function getRegisteredWebhookUrl(): string {
 // ─── Slack alert (best-effort) ───────────────────────────────────────────────
 
 async function notifySlack(text: string): Promise<void> {
+  const channel = process.env.SLACK_ALERTS_CHANNEL;
+  if (!channel) {
+    console.warn("[Jira webhook keepalive] SLACK_ALERTS_CHANNEL not set; skipping alert");
+    return;
+  }
+
   try {
     const { getSlackApp } = await import("../slack/app");
     const app = getSlackApp();
@@ -48,13 +53,21 @@ async function notifySlack(text: string): Promise<void> {
       return;
     }
     await app.client.chat.postMessage({
-      channel: SLACK_ALERTS_CHANNEL,
+      channel,
       text,
     });
-    console.log("[Jira webhook keepalive] Slack notification sent");
+    console.log(`[Jira webhook keepalive] Slack notification sent to ${channel}`);
   } catch (slackErr) {
+    const code =
+      typeof slackErr === "object" && slackErr !== null && "code" in slackErr
+        ? ` code=${String(slackErr.code)}`
+        : "";
+    const data =
+      typeof slackErr === "object" && slackErr !== null && "data" in slackErr
+        ? ` data=${JSON.stringify(slackErr.data)}`
+        : "";
     console.error(
-      "[Jira webhook keepalive] Failed to send Slack notification:",
+      `[Jira webhook keepalive] Failed to send Slack notification to ${channel}${code}${data}:`,
       slackErr instanceof Error ? slackErr.message : slackErr,
     );
   }
@@ -362,3 +375,9 @@ export function stopJiraWebhookKeepalive(): void {
     console.log("[Jira webhook keepalive] Stopped");
   }
 }
+
+// ─── Test helpers (exported for unit tests only) ─────────────────────────────
+
+export const _test = {
+  notifySlack,
+};

package/src/oauth/keepalive.ts

@@ -1,42 +1,46 @@
 import { ensureTokenOrThrow } from "./ensure-token";
 
-// Tick every 50 minutes with a 65-minute "expiring soon" buffer.
-//
-// Atlassian (and Linear) issue 1h access tokens. With this cadence the DB row
-// is always rotated before its current access token expires, so anything that
-// reads oauth_tokens.accessToken directly without going through jiraFetch /
-// linear-outbound (e.g. agents using the read-only db-query MCP) sees a
-// not-yet-expired token. The 65-min buffer is wider than the access-token
-// lifetime, so isTokenExpiringSoon always returns true and every tick rotates.
-//
-// Touching the row this often also serves the original "keep the refresh
-// token alive" goal — Atlassian expires inactive refresh tokens after 90 days,
-// and Linear's behavior is similar; refreshing every 50 min trivially keeps
-// both providers active.
-const KEEPALIVE_INTERVAL_MS = 50 * 60 * 1000;
-const KEEPALIVE_BUFFER_MS = 65 * 60 * 1000;
-const SLACK_ALERTS_CHANNEL = process.env.SLACK_ALERTS_CHANNEL || "C08JCRURPBV";
+// Keep refresh tokens warm without constantly rotating strict-rotation
+// providers. Reactive callers still refresh access tokens before API use.
+const KEEPALIVE_INTERVAL_MS = 12 * 60 * 60 * 1000;
+const KEEPALIVE_BUFFER_MS = 10 * 60 * 1000;
+const STARTUP_KEEPALIVE_DELAY_MS = 10_000;
 
 const KEEPALIVE_PROVIDERS = ["linear", "jira"] as const;
 
 let keepaliveInterval: ReturnType<typeof setInterval> | null = null;
+let startupKeepaliveTimeout: ReturnType<typeof setTimeout> | null = null;
+let inflightKeepalive: Promise<void> | null = null;
+
+function scheduleKeepaliveRun(trigger: "startup" | "interval" | "manual"): Promise<void> {
+  if (inflightKeepalive) {
+    console.log(`[OAuth Keepalive] ${trigger} tick skipped; previous run still in flight`);
+    return inflightKeepalive;
+  }
+
+  inflightKeepalive = runKeepalive(trigger).finally(() => {
+    inflightKeepalive = null;
+  });
+  return inflightKeepalive;
+}
 
 /**
  * Proactively refresh OAuth tokens on a schedule.
  *
  * Two purposes, both served by the same tick:
  *
- *  1. Access-token freshness in the DB. Anything that reads
- *     `oauth_tokens.accessToken` directly (db-query MCP, future MCP servers,
- *     `tracker-status`) needs a not-yet-expired value. The 50-min cadence
- *     keeps the row ahead of the 1h access-token lifetime.
- *  2. Refresh-token liveness. Atlassian rotates refresh tokens and expires
+ *  1. Refresh-token liveness. Atlassian rotates refresh tokens and expires
  *     them after ~90 days of inactivity, so silent gaps in usage would kill
- *     the integration. Refreshing on every tick keeps the refresh token
- *     active and surfaces a dead one as a Slack alert instead of a runtime
- *     401 in the middle of an agent task.
+ *     the integration. The 12h cadence keeps the refresh token active without
+ *     rotating it dozens of times per day.
+ *  2. Loud failure on boot and during scheduled checks. A dead token surfaces
+ *     as structured logs plus a Slack alert instead of silently retrying.
+ *
+ * Access-token freshness is handled reactively by ensureToken callers before
+ * Jira/Linear API use.
  */
-async function runKeepalive(): Promise<void> {
+async function runKeepalive(trigger: "startup" | "interval" | "manual" = "manual"): Promise<void> {
+  console.log(`[OAuth Keepalive] Running ${trigger} token refresh check`);
   for (const provider of KEEPALIVE_PROVIDERS) {
     console.log(`[OAuth Keepalive] Running scheduled token refresh for ${provider}...`);
     try {
@@ -53,6 +57,12 @@ async function runKeepalive(): Promise<void> {
 }
 
 async function notifySlack(text: string): Promise<void> {
+  const channel = process.env.SLACK_ALERTS_CHANNEL;
+  if (!channel) {
+    console.warn("[OAuth Keepalive] SLACK_ALERTS_CHANNEL not set; skipping alert");
+    return;
+  }
+
   try {
     const { getSlackApp } = await import("../slack/app");
     const app = getSlackApp();
@@ -61,13 +71,21 @@ async function notifySlack(text: string): Promise<void> {
       return;
     }
     await app.client.chat.postMessage({
-      channel: SLACK_ALERTS_CHANNEL,
+      channel,
       text,
     });
-    console.log("[OAuth Keepalive] Slack notification sent");
+    console.log(`[OAuth Keepalive] Slack notification sent to ${channel}`);
   } catch (slackErr) {
+    const code =
+      typeof slackErr === "object" && slackErr !== null && "code" in slackErr
+        ? ` code=${String(slackErr.code)}`
+        : "";
+    const data =
+      typeof slackErr === "object" && slackErr !== null && "data" in slackErr
+        ? ` data=${JSON.stringify(slackErr.data)}`
+        : "";
     console.error(
-      "[OAuth Keepalive] Failed to send Slack notification:",
+      `[OAuth Keepalive] Failed to send Slack notification to ${channel}${code}${data}:`,
       slackErr instanceof Error ? slackErr.message : slackErr,
     );
   }
@@ -87,21 +105,45 @@ export function startOAuthKeepalive(): void {
     `[OAuth Keepalive] Starting (interval ${Math.round(KEEPALIVE_INTERVAL_MS / 60_000)}min, buffer ${Math.round(KEEPALIVE_BUFFER_MS / 60_000)}min)`,
   );
 
-  // Run once after a short delay (let server finish startup)
-  setTimeout(() => runKeepalive(), 10_000);
+  // Run once after a short delay (let server finish startup).
+  startupKeepaliveTimeout = setTimeout(() => {
+    startupKeepaliveTimeout = null;
+    scheduleKeepaliveRun("startup");
+  }, STARTUP_KEEPALIVE_DELAY_MS);
 
   keepaliveInterval = setInterval(() => {
-    runKeepalive();
+    scheduleKeepaliveRun("interval");
   }, KEEPALIVE_INTERVAL_MS);
 }
 
 /**
- * Stop the OAuth keepalive timer.
+ * Stop the OAuth keepalive timer and wait for any in-flight refresh to persist.
  */
-export function stopOAuthKeepalive(): void {
+export async function stopOAuthKeepalive(): Promise<void> {
+  if (startupKeepaliveTimeout) {
+    clearTimeout(startupKeepaliveTimeout);
+    startupKeepaliveTimeout = null;
+  }
+
   if (keepaliveInterval) {
     clearInterval(keepaliveInterval);
     keepaliveInterval = null;
     console.log("[OAuth Keepalive] Stopped");
   }
+
+  if (inflightKeepalive) {
+    console.log("[OAuth Keepalive] Waiting for in-flight token refresh before shutdown");
+    await inflightKeepalive;
+  }
 }
+
+// ─── Test helpers (exported for unit tests only) ─────────────────────────────
+
+export const _test = {
+  KEEPALIVE_INTERVAL_MS,
+  KEEPALIVE_BUFFER_MS,
+  STARTUP_KEEPALIVE_DELAY_MS,
+  notifySlack,
+  runKeepalive: scheduleKeepaliveRun,
+  getInflightKeepalive: () => inflightKeepalive,
+};

package/src/tests/jira-webhook-lifecycle.test.ts

@@ -1,10 +1,19 @@
-import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { afterAll, beforeAll, beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
 import { unlink } from "node:fs/promises";
 import { closeDb, getDb, initDb } from "../be/db";
 import { upsertOAuthApp } from "../be/db-queries/oauth";
 import { getJiraMetadata, updateJiraMetadata } from "../jira/metadata";
 
 const TEST_DB_PATH = "./test-jira-webhook-lifecycle.sqlite";
+const originalSlackAlertsChannel = process.env.SLACK_ALERTS_CHANNEL;
+
+function restoreSlackAlertsChannel(): void {
+  if (originalSlackAlertsChannel === undefined) {
+    delete process.env.SLACK_ALERTS_CHANNEL;
+    return;
+  }
+  process.env.SLACK_ALERTS_CHANNEL = originalSlackAlertsChannel;
+}
 
 // Mock the Jira fetch client. Each test installs its own per-call response.
 const jiraFetchMock = mock(
@@ -38,22 +47,40 @@ beforeAll(() => {
 afterAll(async () => {
   delete process.env.JIRA_WEBHOOK_TOKEN;
   delete process.env.MCP_BASE_URL;
+  restoreSlackAlertsChannel();
   closeDb();
   await unlink(TEST_DB_PATH).catch(() => {});
   await unlink(`${TEST_DB_PATH}-wal`).catch(() => {});
   await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
 });
 
-const { refreshJiraWebhooks, registerJiraWebhook } = await import("../jira/webhook-lifecycle");
+const { _test, refreshJiraWebhooks, registerJiraWebhook } = await import(
+  "../jira/webhook-lifecycle"
+);
 
 beforeEach(() => {
   jiraFetchMock.mockClear();
+  restoreSlackAlertsChannel();
   // Reset the webhookIds list each test (and clear metadata writebacks).
   getDb()
     .query("UPDATE oauth_apps SET metadata = ? WHERE provider = 'jira'")
     .run(JSON.stringify({ cloudId: "cloud-1", siteUrl: "https://example.atlassian.net" }));
 });
 
+describe("Jira webhook Slack alerts", () => {
+  test("skips Slack notification when alerts channel env is unset", async () => {
+    delete process.env.SLACK_ALERTS_CHANNEL;
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+
+    await expect(_test.notifySlack("test alert")).resolves.toBeUndefined();
+
+    expect(warn).toHaveBeenCalledWith(
+      "[Jira webhook keepalive] SLACK_ALERTS_CHANNEL not set; skipping alert",
+    );
+    warn.mockRestore();
+  });
+});
+
 describe("registerJiraWebhook", () => {
   test("posts the right body shape and persists webhookId into metadata", async () => {
     jiraFetchMock.mockImplementationOnce(

package/src/tests/kapso-inbound.test.ts

@@ -68,6 +68,13 @@ function fakeReqRes(rawBody: string, headers: Record<string, string>) {
   return { req, res, captured };
 }
 
+async function waitFor(predicate: () => boolean): Promise<void> {
+  for (let i = 0; i < 20; i++) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
+
 const KAPSO_PATH = ["api", "integrations", "kapso", "webhook"];
 
 beforeAll(() => {
@@ -226,9 +233,8 @@ describe("handleWebhooks — Kapso HMAC gate", () => {
       return new Response(JSON.stringify({ success: true }), { status: 200 });
     }) as typeof fetch;
 
-    const rawBody = JSON.stringify(
-      makePayload({ phoneNumberId: "pn-http", messageId: "wamid.HTTP_OK" }),
-    );
+    const messageId = `wamid.HTTP_OK_${crypto.randomUUID()}`;
+    const rawBody = JSON.stringify(makePayload({ phoneNumberId: "pn-http", messageId }));
     const { req, res, captured } = fakeReqRes(rawBody, {
       "x-webhook-signature": sign(HMAC_SECRET, rawBody),
     });
@@ -236,22 +242,37 @@ describe("handleWebhooks — Kapso HMAC gate", () => {
     expect(handled).toBe(true);
     expect(captured.status).toBe(200);
     expect(JSON.parse(captured.body)).toMatchObject({ received: true, routing: "task" });
-    expect(calls).toHaveLength(2);
+    await waitFor(
+      () =>
+        calls.some((call) => call.body.message_id === messageId) &&
+        calls.some(
+          (call) =>
+            (call.body.reaction as { message_id?: string } | undefined)?.message_id === messageId,
+        ),
+    );
+    const messageCalls = calls.filter(
+      (call) =>
+        call.body.message_id === messageId ||
+        (call.body.reaction as { message_id?: string } | undefined)?.message_id === messageId,
+    );
+    expect(messageCalls).toHaveLength(2);
     expect(
-      calls.every((call) => call.url === "https://kapso.test/meta/whatsapp/v24.0/pn-http/messages"),
+      messageCalls.every(
+        (call) => call.url === "https://kapso.test/meta/whatsapp/v24.0/pn-http/messages",
+      ),
     ).toBe(true);
-    expect(calls.map((call) => call.body)).toContainEqual({
+    expect(messageCalls.map((call) => call.body)).toContainEqual({
       messaging_product: "whatsapp",
       status: "read",
-      message_id: "wamid.HTTP_OK",
+      message_id: messageId,
       typing_indicator: { type: "text" },
     });
-    expect(calls.map((call) => call.body)).toContainEqual({
+    expect(messageCalls.map((call) => call.body)).toContainEqual({
       messaging_product: "whatsapp",
       recipient_type: "individual",
       to: "34679077777",
       type: "reaction",
-      reaction: { message_id: "wamid.HTTP_OK", emoji: "👀" },
+      reaction: { message_id: messageId, emoji: "👀" },
     });
   });
 

package/src/tests/oauth-keepalive.test.ts

@@ -0,0 +1,135 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, initDb } from "../be/db";
+import {
+  deleteOAuthTokens,
+  getOAuthTokens,
+  storeOAuthTokens,
+  upsertOAuthApp,
+} from "../be/db-queries/oauth";
+import { _test, stopOAuthKeepalive } from "../oauth/keepalive";
+
+const TEST_DB_PATH = "./test-oauth-keepalive.sqlite";
+
+const originalSlackAlertsChannel = process.env.SLACK_ALERTS_CHANNEL;
+function restoreSlackAlertsChannel(): void {
+  if (originalSlackAlertsChannel === undefined) {
+    delete process.env.SLACK_ALERTS_CHANNEL;
+    return;
+  }
+  process.env.SLACK_ALERTS_CHANNEL = originalSlackAlertsChannel;
+}
+
+const testApp = {
+  clientId: "test-client-id",
+  clientSecret: "test-client-secret",
+  authorizeUrl: "https://example.com/oauth/authorize",
+  tokenUrl: "https://example.com/oauth/token",
+  redirectUri: "http://localhost:3013/callback",
+  scopes: "read,write",
+};
+
+const originalFetch = globalThis.fetch;
+
+beforeAll(() => {
+  initDb(TEST_DB_PATH);
+  upsertOAuthApp("linear", testApp);
+  upsertOAuthApp("jira", {
+    ...testApp,
+    tokenUrl: "https://example.com/jira/oauth/token",
+  });
+});
+
+beforeEach(async () => {
+  await stopOAuthKeepalive();
+  deleteOAuthTokens("linear");
+  deleteOAuthTokens("jira");
+  globalThis.fetch = originalFetch;
+  restoreSlackAlertsChannel();
+  mock.restore();
+});
+
+afterAll(async () => {
+  await stopOAuthKeepalive();
+  globalThis.fetch = originalFetch;
+  restoreSlackAlertsChannel();
+  closeDb();
+  await unlink(TEST_DB_PATH).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-wal`).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
+});
+
+describe("OAuth keepalive", () => {
+  test("uses a 12h cadence with a 10m refresh buffer", () => {
+    expect(_test.KEEPALIVE_INTERVAL_MS).toBe(12 * 60 * 60 * 1000);
+    expect(_test.KEEPALIVE_BUFFER_MS).toBe(10 * 60 * 1000);
+  });
+
+  test("skips Slack notification when alerts channel env is unset", async () => {
+    delete process.env.SLACK_ALERTS_CHANNEL;
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+
+    await expect(_test.notifySlack("test alert")).resolves.toBeUndefined();
+
+    expect(warn).toHaveBeenCalledWith(
+      "[OAuth Keepalive] SLACK_ALERTS_CHANNEL not set; skipping alert",
+    );
+  });
+
+  test("stopOAuthKeepalive waits for in-flight Jira refresh persistence", async () => {
+    storeOAuthTokens("linear", {
+      accessToken: "linear-access",
+      refreshToken: "linear-refresh",
+      expiresAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+    });
+    storeOAuthTokens("jira", {
+      accessToken: "old-jira-access",
+      refreshToken: "old-jira-refresh",
+      expiresAt: new Date(Date.now() + 60 * 1000).toISOString(),
+    });
+
+    let releaseTokenResponse!: () => void;
+    const tokenResponseReady = new Promise<void>((resolve) => {
+      releaseTokenResponse = resolve;
+    });
+    let fetchStarted!: () => void;
+    const fetchStartedPromise = new Promise<void>((resolve) => {
+      fetchStarted = resolve;
+    });
+
+    globalThis.fetch = mock(async () => {
+      fetchStarted();
+      await tokenResponseReady;
+      return new Response(
+        JSON.stringify({
+          access_token: "new-jira-access",
+          token_type: "Bearer",
+          expires_in: 3600,
+          refresh_token: "new-jira-refresh",
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    });
+
+    const keepaliveRun = _test.runKeepalive("manual");
+    await fetchStartedPromise;
+
+    let stopResolved = false;
+    const stopPromise = stopOAuthKeepalive().then(() => {
+      stopResolved = true;
+    });
+
+    await Promise.resolve();
+    expect(stopResolved).toBe(false);
+    expect(getOAuthTokens("jira")?.refreshToken).toBe("old-jira-refresh");
+
+    releaseTokenResponse();
+    await stopPromise;
+    await keepaliveRun;
+
+    expect(stopResolved).toBe(true);
+    const tokens = getOAuthTokens("jira");
+    expect(tokens?.accessToken).toBe("new-jira-access");
+    expect(tokens?.refreshToken).toBe("new-jira-refresh");
+  });
+});

package/src/tests/task-lifecycle-telemetry.test.ts

@@ -0,0 +1,153 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import {
+  cancelTask,
+  closeDb,
+  completeTask,
+  createAgent,
+  createTaskExtended,
+  failTask,
+  getDb,
+  initDb,
+} from "../be/db";
+import { telemetry } from "../telemetry";
+
+const TEST_DB_PATH = "./test-task-lifecycle-telemetry.sqlite";
+const WORKER_ID = "bbbb0000-0000-4000-8000-000000000002";
+
+async function flushMicrotasks(): Promise<void> {
+  await Promise.resolve();
+}
+
+async function removeTestDb(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(TEST_DB_PATH + suffix);
+    } catch {
+      // File does not exist.
+    }
+  }
+}
+
+describe("task lifecycle telemetry", () => {
+  let taskEventSpy: ReturnType<typeof spyOn>;
+  let calls: Array<{ event: string; props: Parameters<typeof telemetry.taskEvent>[1] }>;
+
+  beforeEach(async () => {
+    closeDb();
+    await removeTestDb();
+    initDb(TEST_DB_PATH);
+    createAgent({ id: WORKER_ID, name: "Telemetry Worker", isLead: false, status: "idle" });
+
+    calls = [];
+    taskEventSpy = spyOn(telemetry, "taskEvent").mockImplementation((event, props) => {
+      calls.push({ event, props });
+    });
+  });
+
+  afterEach(async () => {
+    taskEventSpy.mockRestore();
+    closeDb();
+    await removeTestDb();
+  });
+
+  test("emits task.created from createTaskExtended after the task is committed", async () => {
+    const task = createTaskExtended("create telemetry", {
+      agentId: WORKER_ID,
+      source: "mcp",
+      tags: ["telemetry"],
+      priority: 60,
+    });
+
+    expect(calls).toHaveLength(0);
+
+    await flushMicrotasks();
+
+    expect(calls).toEqual([
+      {
+        event: "created",
+        props: {
+          taskId: task.id,
+          source: "mcp",
+          tags: ["telemetry"],
+          hasParent: false,
+          priority: 60,
+        },
+      },
+    ]);
+  });
+
+  test("does not emit task.created when an enclosing transaction rolls back", async () => {
+    const txn = getDb().transaction(() => {
+      createTaskExtended("rolled back telemetry", {
+        agentId: WORKER_ID,
+        source: "mcp",
+      });
+      throw new Error("rollback");
+    });
+
+    expect(() => txn()).toThrow("rollback");
+
+    await flushMicrotasks();
+
+    expect(calls).toHaveLength(0);
+  });
+
+  test("emits terminal lifecycle events from universal status helpers", async () => {
+    const completedTask = createTaskExtended("complete telemetry", {
+      agentId: WORKER_ID,
+      source: "mcp",
+    });
+    await flushMicrotasks();
+    calls = [];
+
+    completeTask(completedTask.id, "done");
+    await flushMicrotasks();
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({
+      event: "completed",
+      props: { taskId: completedTask.id, agentId: WORKER_ID },
+    });
+    expect(typeof calls[0]?.props.durationMs).toBe("number");
+
+    const failedTask = createTaskExtended("fail telemetry", {
+      agentId: WORKER_ID,
+      source: "mcp",
+    });
+    await flushMicrotasks();
+    calls = [];
+
+    failTask(failedTask.id, "nope");
+    await flushMicrotasks();
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({
+      event: "failed",
+      props: { taskId: failedTask.id, agentId: WORKER_ID },
+    });
+    expect(typeof calls[0]?.props.durationMs).toBe("number");
+
+    const cancelledTask = createTaskExtended("cancel telemetry", {
+      agentId: WORKER_ID,
+      source: "api",
+    });
+    await flushMicrotasks();
+    calls = [];
+
+    cancelTask(cancelledTask.id, "not needed");
+    await flushMicrotasks();
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({
+      event: "cancelled",
+      props: {
+        taskId: cancelledTask.id,
+        source: "api",
+        agentId: WORKER_ID,
+        previousStatus: "pending",
+      },
+    });
+    expect(typeof calls[0]?.props.durationMs).toBe("number");
+  });
+});

package/src/tests/workflow-swarm-script.test.ts

@@ -21,7 +21,13 @@ import {
   type ExecutorResult,
 } from "../workflows/executors/base";
 import { ExecutorRegistry } from "../workflows/executors/registry";
-import { SwarmScriptExecutor } from "../workflows/executors/swarm-script";
+import {
+  SWARM_SCRIPT_DEFAULT_TIMEOUT_MS,
+  SWARM_SCRIPT_MAX_TIMEOUT_MS,
+  SWARM_SCRIPT_MIN_TIMEOUT_MS,
+  SwarmScriptConfigSchema,
+  SwarmScriptExecutor,
+} from "../workflows/executors/swarm-script";
 import { interpolate } from "../workflows/template";
 
 const TEST_DB_PATH = "./test-workflow-swarm-script.sqlite";
@@ -141,6 +147,38 @@ beforeEach(() => {
 });
 
 describe("SwarmScriptExecutor", () => {
+  test("config schema validates timeoutMs bounds and applies the runtime default", () => {
+    expect(SwarmScriptConfigSchema.parse({ scriptName: "quick" }).timeoutMs).toBe(
+      SWARM_SCRIPT_DEFAULT_TIMEOUT_MS,
+    );
+
+    expect(
+      SwarmScriptConfigSchema.safeParse({
+        scriptName: "quick",
+        timeoutMs: SWARM_SCRIPT_MIN_TIMEOUT_MS - 1,
+      }).success,
+    ).toBe(false);
+    expect(
+      SwarmScriptConfigSchema.safeParse({
+        scriptName: "quick",
+        timeoutMs: SWARM_SCRIPT_MAX_TIMEOUT_MS + 1,
+      }).success,
+    ).toBe(false);
+
+    expect(
+      SwarmScriptConfigSchema.parse({
+        scriptName: "quick",
+        timeoutMs: SWARM_SCRIPT_MIN_TIMEOUT_MS,
+      }).timeoutMs,
+    ).toBe(SWARM_SCRIPT_MIN_TIMEOUT_MS);
+    expect(
+      SwarmScriptConfigSchema.parse({
+        scriptName: "quick",
+        timeoutMs: SWARM_SCRIPT_MAX_TIMEOUT_MS,
+      }).timeoutMs,
+    ).toBe(SWARM_SCRIPT_MAX_TIMEOUT_MS);
+  });
+
   test("A workflow with one swarm-script node resolves by name + runs + returns result", async () => {
     await saveScript(
       "add-one",
@@ -250,6 +288,49 @@ describe("SwarmScriptExecutor", () => {
     expect(success.status).toBe("success");
   });
 
+  test("timeoutMs not set — script completes with the default 30s window", async () => {
+    await saveScript("quick", `export default async () => ({ done: true });`);
+    const executor = new SwarmScriptExecutor(deps);
+    const wf = makeWorkflow({ nodes: [] });
+    const result = await executor.run({
+      config: { scriptName: "quick" },
+      context: {},
+      meta: {
+        runId: crypto.randomUUID(),
+        stepId: crypto.randomUUID(),
+        nodeId: "script",
+        workflowId: wf.id,
+        dryRun: false,
+      },
+    });
+
+    expect(result.status).toBe("success");
+    expect(result.output?.result).toEqual({ done: true });
+  });
+
+  test("timeoutMs set — a long-running script is killed before it finishes", async () => {
+    await saveScript(
+      "sleeper",
+      `export default async () => { await new Promise(r => setTimeout(r, 3000)); return { done: true }; };`,
+    );
+    const executor = new SwarmScriptExecutor(deps);
+    const wf = makeWorkflow({ nodes: [] });
+    const result = await executor.run({
+      config: { scriptName: "sleeper", timeoutMs: 300 },
+      context: {},
+      meta: {
+        runId: crypto.randomUUID(),
+        stepId: crypto.randomUUID(),
+        nodeId: "script",
+        workflowId: wf.id,
+        dryRun: false,
+      },
+    });
+
+    expect(result.status).toBe("failed");
+    expect(result.output?.exitCode).not.toBe(0);
+  });
+
   test("Failure in the script surfaces as a workflow-node failure", async () => {
     await saveScript("throws", `export default async () => { throw new Error("boom"); };`);
     const executor = new SwarmScriptExecutor(deps);

package/src/workflows/executors/swarm-script.ts

@@ -1,15 +1,26 @@
 import { z } from "zod";
 import { getScript, getScriptVersion } from "../../be/scripts/db";
+import { DEFAULT_SCRIPT_RESOURCES } from "../../scripts-runtime/executors/types";
 import { runScript } from "../../scripts-runtime/loader";
 import type { ExecutorMeta } from "../../types";
 import { BaseExecutor, type ExecutorResult } from "./base";
 
+export const SWARM_SCRIPT_DEFAULT_TIMEOUT_MS = DEFAULT_SCRIPT_RESOURCES.wallClockMs;
+export const SWARM_SCRIPT_MIN_TIMEOUT_MS = 1_000;
+export const SWARM_SCRIPT_MAX_TIMEOUT_MS = DEFAULT_SCRIPT_RESOURCES.cpuTimeSec * 1_000;
+
 export const SwarmScriptConfigSchema = z.object({
   scriptName: z.string().min(1),
   scope: z.enum(["global", "agent"]).optional(),
   pinHash: z.string().min(1).optional(),
   args: z.record(z.string(), z.unknown()).default({}),
   fsMode: z.enum(["none", "workspace-rw"]).default("none"),
+  timeoutMs: z
+    .number()
+    .int()
+    .min(SWARM_SCRIPT_MIN_TIMEOUT_MS)
+    .max(SWARM_SCRIPT_MAX_TIMEOUT_MS)
+    .default(SWARM_SCRIPT_DEFAULT_TIMEOUT_MS),
 });
 
 export const SwarmScriptOutputSchema = z.object({
@@ -61,6 +72,7 @@ export class SwarmScriptExecutor extends BaseExecutor<
       args: config.args,
       fsMode: "none",
       agentId: agentId ?? "workflow",
+      timeoutMs: config.timeoutMs,
     });
 
     const workflowOutput = {