@desplega.ai/agent-swarm 1.76.1 → 1.76.3

package/src/tests/pi-mono-extension.test.ts

@@ -0,0 +1,347 @@
+/**
+ * Unit tests for `summarizeSessionForPi` in `src/providers/pi-mono-extension.ts`.
+ *
+ * Plan: thoughts/taras/plans/2026-05-10-fix-session-summarization-workers.md
+ * → Phase 1 § "Test coverage"
+ *
+ * Uses explicit dependency injection (the `deps` parameter on
+ * `summarizeSessionForPi`) instead of `bun:test`'s `mock.module()` because the
+ * latter installs a process-wide override that leaks across test files in the
+ * same `bun test` run (`buildRatingsFromLlm` siblings + Phase-0 internal-ai
+ * tests would break).
+ *
+ * Mocks:
+ *   - `runSummarize`           — captures args + returns canned result
+ *   - `fetchRetrievalsForTask` — returns canned retrievals
+ *   - `postRatings`            — captures args, asserts `events:` key
+ *   - `buildRatingsFromLlm`    — minimal pass-through unless overridden
+ *   - `globalThis.fetch`       — captures `/api/memory/index` POSTs
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { SummarizeSessionForPiDeps, SwarmHooksConfig } from "../providers/pi-mono-extension";
+import { summarizeSessionForPi } from "../providers/pi-mono-extension";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function makeConfig(): SwarmHooksConfig {
+  return {
+    apiUrl: "http://localhost:3013",
+    apiKey: "test-key",
+    agentId: "agent-pi-1",
+    taskId: "task-pi-1",
+    isLead: false,
+  };
+}
+
+/** Build a transcript with > 100 chars so the degenerate gate doesn't trip. */
+function longTranscript(extra = "") {
+  return "User: do a thing\nAssistant: doing thing\nTool[write]: ok\n".repeat(5) + extra;
+}
+
+/**
+ * Write a temp file under /tmp containing `content`. The SUT's
+ * `Bun.file(sessionFile).text()` reads it back without further mocking.
+ */
+async function writeTempTranscript(content: string): Promise<string> {
+  const path = `/tmp/pi-mono-test-transcript-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`;
+  await Bun.write(path, content);
+  return path;
+}
+
+// ── test state ────────────────────────────────────────────────────────────────
+
+type RunSummarizeArgs = Parameters<NonNullable<SummarizeSessionForPiDeps["runSummarize"]>>[0];
+type RunSummarizeResult = Awaited<
+  ReturnType<NonNullable<SummarizeSessionForPiDeps["runSummarize"]>>
+>;
+type FetchRetrievalsArgs = Parameters<
+  NonNullable<SummarizeSessionForPiDeps["fetchRetrievalsForTask"]>
+>[0];
+type FetchRetrievalsResult = Awaited<
+  ReturnType<NonNullable<SummarizeSessionForPiDeps["fetchRetrievalsForTask"]>>
+>;
+type PostRatingsArgs = Parameters<NonNullable<SummarizeSessionForPiDeps["postRatings"]>>[0];
+
+const fetchCalls: Array<{ url: string; init?: RequestInit }> = [];
+type FetchHandlerResp = {
+  ok: boolean;
+  status: number;
+  text: () => Promise<string>;
+  json: () => Promise<unknown>;
+};
+let fetchHandler: ((url: string, init?: RequestInit) => Promise<FetchHandlerResp>) | null = null;
+const consoleErrors: unknown[][] = [];
+
+const origFetch = globalThis.fetch;
+const origConsoleError = console.error;
+
+beforeEach(() => {
+  fetchCalls.length = 0;
+  consoleErrors.length = 0;
+  fetchHandler = null;
+  // Default fetch: 202 for /api/memory/index, 200 otherwise (so non-test fetches
+  // like fetchTaskDetails don't crash with an undefined handler).
+  fetchHandler = async (url) => {
+    if (url.includes("/api/memory/index")) {
+      return {
+        ok: true,
+        status: 202,
+        text: async () => "",
+        json: async () => ({ queued: true, memoryIds: ["mem-1"] }),
+      };
+    }
+    return { ok: true, status: 200, text: async () => "", json: async () => ({}) };
+  };
+  globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+    const urlStr = typeof url === "string" ? url : url.toString();
+    fetchCalls.push({ url: urlStr, init });
+    if (!fetchHandler) return new Response("{}", { status: 200 });
+    return fetchHandler(urlStr, init) as unknown as Response;
+  }) as typeof fetch;
+  console.error = (...args: unknown[]) => {
+    consoleErrors.push(args);
+  };
+  delete process.env.MEMORY_RATERS;
+});
+
+afterEach(() => {
+  globalThis.fetch = origFetch;
+  console.error = origConsoleError;
+});
+
+// ── tests ─────────────────────────────────────────────────────────────────────
+
+describe("summarizeSessionForPi", () => {
+  test("happy path — long transcript + valid summary → POSTs to /api/memory/index", async () => {
+    const transcript = longTranscript("Some real-looking work here\n");
+    const sessionFile = await writeTempTranscript(transcript);
+
+    let lastRunSummarizeArgs: RunSummarizeArgs | null = null;
+    const deps: SummarizeSessionForPiDeps = {
+      runSummarize: async (args) => {
+        lastRunSummarizeArgs = args;
+        return {
+          summary: "Learned X about Y — concrete reusable fact.",
+          ratings: [],
+        } as RunSummarizeResult;
+      },
+    };
+
+    await summarizeSessionForPi(makeConfig(), sessionFile, deps);
+
+    expect(lastRunSummarizeArgs).not.toBeNull();
+    expect(lastRunSummarizeArgs!.harness).toBe("pi");
+    expect(lastRunSummarizeArgs!.taskContext.sourceTaskId).toBe("task-pi-1");
+    expect(lastRunSummarizeArgs!.taskContext.agentId).toBe("agent-pi-1");
+    expect(lastRunSummarizeArgs!.apiUrl).toBe("http://localhost:3013");
+    expect(lastRunSummarizeArgs!.apiKey).toBe("test-key");
+
+    const indexCalls = fetchCalls.filter((c) => c.url.endsWith("/api/memory/index"));
+    expect(indexCalls.length).toBe(1);
+    const body = JSON.parse(indexCalls[0]!.init?.body as string) as Record<string, unknown>;
+    expect(body.scope).toBe("agent");
+    expect(body.source).toBe("session_summary");
+    expect(body.sourceTaskId).toBe("task-pi-1");
+    expect(body.agentId).toBe("agent-pi-1");
+    expect(body.name).toBe("session-summary");
+    expect(body.content).toBe("Learned X about Y — concrete reusable fact.");
+
+    expect(consoleErrors.length).toBe(0);
+  });
+
+  test("empty transcript (≤100 chars) → no POST, no error", async () => {
+    const sessionFile = await writeTempTranscript("short");
+
+    const deps: SummarizeSessionForPiDeps = {
+      runSummarize: async () => {
+        throw new Error("should not be called");
+      },
+    };
+    await summarizeSessionForPi(makeConfig(), sessionFile, deps);
+
+    expect(fetchCalls.length).toBe(0);
+    expect(consoleErrors.length).toBe(0);
+  });
+
+  test("no sessionFile → no POST, no error", async () => {
+    const deps: SummarizeSessionForPiDeps = {
+      runSummarize: async () => {
+        throw new Error("should not be called");
+      },
+    };
+    await summarizeSessionForPi(makeConfig(), undefined, deps);
+
+    expect(fetchCalls.length).toBe(0);
+    expect(consoleErrors.length).toBe(0);
+  });
+
+  test("no credentials (runSummarize returns null) → no POST, no error log", async () => {
+    const sessionFile = await writeTempTranscript(longTranscript());
+
+    const deps: SummarizeSessionForPiDeps = {
+      runSummarize: async () => null,
+    };
+    await summarizeSessionForPi(makeConfig(), sessionFile, deps);
+
+    const indexCalls = fetchCalls.filter((c) => c.url.endsWith("/api/memory/index"));
+    expect(indexCalls.length).toBe(0);
+    // wrapper logs internally; the pi wrapper itself should not log on null return
+    expect(consoleErrors.length).toBe(0);
+  });
+
+  test("length gate — summary too short → no POST", async () => {
+    const sessionFile = await writeTempTranscript(longTranscript());
+
+    const deps: SummarizeSessionForPiDeps = {
+      runSummarize: async () => ({ summary: "tiny", ratings: [] }) as RunSummarizeResult,
+    };
+    await summarizeSessionForPi(makeConfig(), sessionFile, deps);
+
+    const indexCalls = fetchCalls.filter((c) => c.url.endsWith("/api/memory/index"));
+    expect(indexCalls.length).toBe(0);
+    expect(consoleErrors.length).toBe(0);
+  });
+
+  test("'no significant learnings' gate → no POST", async () => {
+    const sessionFile = await writeTempTranscript(longTranscript());
+
+    const deps: SummarizeSessionForPiDeps = {
+      runSummarize: async () =>
+        ({ summary: "No significant learnings.", ratings: [] }) as RunSummarizeResult,
+    };
+    await summarizeSessionForPi(makeConfig(), sessionFile, deps);
+
+    const indexCalls = fetchCalls.filter((c) => c.url.endsWith("/api/memory/index"));
+    expect(indexCalls.length).toBe(0);
+    expect(consoleErrors.length).toBe(0);
+  });
+
+  test("POST 500 → exactly one console.error('session_summary: /api/memory/index POST failed (pi):', ...)", async () => {
+    const sessionFile = await writeTempTranscript(longTranscript());
+
+    fetchHandler = async (url) => {
+      if (url.includes("/api/memory/index")) {
+        return {
+          ok: false,
+          status: 500,
+          text: async () => "internal server error",
+          json: async () => ({}),
+        };
+      }
+      return { ok: true, status: 200, text: async () => "", json: async () => ({}) };
+    };
+
+    const deps: SummarizeSessionForPiDeps = {
+      runSummarize: async () =>
+        ({
+          summary: "A valid long-enough summary that passes the length gate.",
+          ratings: [],
+        }) as RunSummarizeResult,
+    };
+    await summarizeSessionForPi(makeConfig(), sessionFile, deps);
+
+    const matching = consoleErrors.filter(
+      (args) =>
+        typeof args[0] === "string" &&
+        (args[0] as string).startsWith("session_summary: /api/memory/index POST failed (pi):"),
+    );
+    expect(matching.length).toBe(1);
+    expect(matching[0]![1]).toBe(500);
+  });
+
+  test("fetch throws → exactly one console.error('session_summary failed (pi):', ...)", async () => {
+    const sessionFile = await writeTempTranscript(longTranscript());
+
+    fetchHandler = async (url) => {
+      if (url.includes("/api/memory/index")) {
+        throw new Error("network down");
+      }
+      return { ok: true, status: 200, text: async () => "", json: async () => ({}) };
+    };
+
+    const deps: SummarizeSessionForPiDeps = {
+      runSummarize: async () =>
+        ({
+          summary: "A valid long-enough summary that passes the length gate.",
+          ratings: [],
+        }) as RunSummarizeResult,
+    };
+    await summarizeSessionForPi(makeConfig(), sessionFile, deps);
+
+    const matching = consoleErrors.filter(
+      (args) =>
+        typeof args[0] === "string" &&
+        (args[0] as string).startsWith("session_summary failed (pi):"),
+    );
+    expect(matching.length).toBe(1);
+  });
+
+  test("ratings path — MEMORY_RATERS=llm + retrievals + ratings → postRatings called with `events:` key (NOT `ratings:`)", async () => {
+    process.env.MEMORY_RATERS = "llm";
+    const sessionFile = await writeTempTranscript(longTranscript());
+
+    const retrievalRow = {
+      id: "mem-A",
+      name: "memory A",
+      content: "...",
+    };
+    const fetchRetrievalsMock: SummarizeSessionForPiDeps["fetchRetrievalsForTask"] = async (
+      _args: FetchRetrievalsArgs,
+    ) => [retrievalRow] as unknown as FetchRetrievalsResult;
+
+    let lastPostRatingsArgs: PostRatingsArgs | null = null;
+    const postRatingsMock: SummarizeSessionForPiDeps["postRatings"] = async (args) => {
+      lastPostRatingsArgs = args;
+      return { ok: true, status: 200 };
+    };
+
+    const deps: SummarizeSessionForPiDeps = {
+      runSummarize: async (args) => {
+        expect(args.retrievals.length).toBe(1);
+        expect(args.retrievals[0]!.id).toBe("mem-A");
+        return {
+          summary: "Long-enough summary with real content for the index POST.",
+          ratings: [{ id: "mem-A", score: 0.8, reasoning: "useful" }],
+        } as RunSummarizeResult;
+      },
+      fetchRetrievalsForTask: fetchRetrievalsMock,
+      postRatings: postRatingsMock,
+      buildRatingsFromLlm: (ratings, retrievals) => {
+        // Smoke-check: only keep ratings present in retrievals (mirrors real impl)
+        const allowed = new Set(retrievals.map((r) => r.id));
+        return ratings
+          .filter((r) => allowed.has(r.id))
+          .map((r) => ({
+            memoryId: r.id,
+            signal: 2 * r.score - 1,
+            weight: 0.8,
+            source: "llm",
+            reasoning: r.reasoning,
+          }));
+      },
+    };
+
+    await summarizeSessionForPi(makeConfig(), sessionFile, deps);
+
+    // Index POST happened
+    const indexCalls = fetchCalls.filter((c) => c.url.endsWith("/api/memory/index"));
+    expect(indexCalls.length).toBe(1);
+
+    // postRatings was called with `events:` key, not `ratings:` — guards against
+    // the orchestrator-flagged plan/signature mismatch
+    expect(lastPostRatingsArgs).not.toBeNull();
+    expect(lastPostRatingsArgs!.apiUrl).toBe("http://localhost:3013");
+    expect(lastPostRatingsArgs!.agentId).toBe("agent-pi-1");
+    expect(lastPostRatingsArgs!.taskId).toBe("task-pi-1");
+    expect(Array.isArray(lastPostRatingsArgs!.events)).toBe(true);
+    expect(lastPostRatingsArgs!.events.length).toBe(1);
+    expect(lastPostRatingsArgs!.events[0]!.memoryId).toBe("mem-A");
+    expect(lastPostRatingsArgs!.events[0]!.source).toBe("llm");
+
+    // Guard against accidentally passing a `ratings:` key (plan example bug)
+    expect((lastPostRatingsArgs as unknown as Record<string, unknown>).ratings).toBeUndefined();
+
+    expect(consoleErrors.length).toBe(0);
+  });
+});

package/src/tests/reload-config.test.ts

@@ -1,10 +1,16 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { unlink } from "node:fs/promises";
 import { createServer as createHttpServer, type Server } from "node:http";
 import { initAgentMail, resetAgentMail } from "../agentmail";
-import { closeDb, getDb, initDb, upsertSwarmConfig } from "../be/db";
+import { closeDb, deleteSwarmConfig, getDb, initDb, upsertSwarmConfig } from "../be/db";
 import { initGitHub, resetGitHub } from "../github";
-import { loadGlobalConfigsIntoEnv } from "../http/core";
+import {
+  _autoReloadStatsForTests,
+  _resetAutoReloadForTests,
+  flushPendingIntegrationsReload,
+  loadGlobalConfigsIntoEnv,
+  scheduleIntegrationsReload,
+} from "../http/core";
 
 const TEST_DB_PATH = "./test-reload-config.sqlite";
 const TEST_PORT = 13023;
@@ -199,3 +205,145 @@ describe("reload-config", () => {
     expect(res.status).toBe(404);
   });
 });
+
+describe("auto-reload debouncer", () => {
+  // The reload calls into stopSlackApp/startSlackApp + GH/Linear/Jira/AgentMail
+  // init. They are no-ops without credentials, so we explicitly disable Slack
+  // (it has its own DISABLE switch) and rely on the others being unconfigured.
+  let originalSlackDisable: string | undefined;
+
+  beforeAll(() => {
+    originalSlackDisable = process.env.SLACK_DISABLE;
+    process.env.SLACK_DISABLE = "true";
+  });
+
+  afterAll(() => {
+    if (originalSlackDisable === undefined) {
+      delete process.env.SLACK_DISABLE;
+    } else {
+      process.env.SLACK_DISABLE = originalSlackDisable;
+    }
+  });
+
+  beforeEach(async () => {
+    // Drain any reload state that leaked from earlier test files in the full
+    // suite (e.g. swarm-config-reserved-keys.test.ts does global PUT/DELETE on
+    // /api/config, which schedules a 250ms reload). If we reset() while a
+    // prior timer was still mid-flight, the leaked .finally() can race against
+    // our test body and stomp the module state — first symptom is
+    // `expect(pending).toBe(true)` failing because `inFlightReload` was still
+    // truthy when `scheduleIntegrationsReload` ran. Flush first, then reset.
+    await flushPendingIntegrationsReload();
+    _resetAutoReloadForTests();
+  });
+
+  test("scheduleIntegrationsReload runs reload after the debounce window", async () => {
+    const testKey = `__TEST_AUTO_RELOAD_RUNS_${Date.now()}`;
+    upsertSwarmConfig({ scope: "global", key: testKey, value: "fresh" });
+    delete process.env[testKey];
+
+    scheduleIntegrationsReload(50);
+    expect(_autoReloadStatsForTests().pending).toBe(true);
+
+    await flushPendingIntegrationsReload();
+
+    expect(_autoReloadStatsForTests().invocations).toBe(1);
+    expect(process.env[testKey]).toBe("fresh");
+
+    delete process.env[testKey];
+  });
+
+  test("rapid scheduleIntegrationsReload calls coalesce into one reload", async () => {
+    const testKey = `__TEST_COALESCE_${Date.now()}`;
+    upsertSwarmConfig({ scope: "global", key: testKey, value: "v1" });
+
+    scheduleIntegrationsReload(100);
+    scheduleIntegrationsReload(100);
+    scheduleIntegrationsReload(100);
+    scheduleIntegrationsReload(100);
+
+    expect(_autoReloadStatsForTests().invocations).toBe(0);
+
+    await flushPendingIntegrationsReload();
+
+    expect(_autoReloadStatsForTests().invocations).toBe(1);
+
+    delete process.env[testKey];
+  });
+
+  test("schedule during in-flight reload triggers exactly one rerun", async () => {
+    const testKey = `__TEST_RERUN_${Date.now()}`;
+    upsertSwarmConfig({ scope: "global", key: testKey, value: "first" });
+
+    scheduleIntegrationsReload(20);
+    // Wait just past the debounce so the first reload is in-flight, then
+    // schedule again. The second call should defer to a rerun, not a parallel
+    // reload.
+    await new Promise((r) => setTimeout(r, 25));
+    scheduleIntegrationsReload(20);
+    scheduleIntegrationsReload(20); // collapses with the rerun-pending flag
+
+    await flushPendingIntegrationsReload();
+
+    // First run + one rerun = 2 invocations total.
+    expect(_autoReloadStatsForTests().invocations).toBe(2);
+
+    delete process.env[testKey];
+  });
+
+  test("flushPendingIntegrationsReload is a no-op when nothing is queued", async () => {
+    expect(_autoReloadStatsForTests().pending).toBe(false);
+    await flushPendingIntegrationsReload();
+    expect(_autoReloadStatsForTests().invocations).toBe(0);
+  });
+
+  test("auto-reload picks up a brand-new config row at runtime", async () => {
+    const testKey = `__TEST_NEW_ROW_${Date.now()}`;
+    delete process.env[testKey];
+
+    // Simulate the upsert path's behavior: write the row, then schedule.
+    upsertSwarmConfig({ scope: "global", key: testKey, value: "live-update" });
+    scheduleIntegrationsReload(20);
+
+    await flushPendingIntegrationsReload();
+
+    expect(process.env[testKey]).toBe("live-update");
+    delete process.env[testKey];
+  });
+
+  test("auto-reload reflects an updated value (override semantics)", async () => {
+    const testKey = `__TEST_OVERRIDE_LIVE_${Date.now()}`;
+    process.env[testKey] = "shipped-by-deploy";
+
+    // Pre-existing env should win at startup, but reload uses override=true.
+    upsertSwarmConfig({ scope: "global", key: testKey, value: "from-config" });
+    scheduleIntegrationsReload(20);
+
+    await flushPendingIntegrationsReload();
+
+    expect(process.env[testKey]).toBe("from-config");
+    delete process.env[testKey];
+  });
+
+  test("delete + reload removes value from active env (well, doesn't re-inject it)", async () => {
+    const testKey = `__TEST_DELETE_${Date.now()}`;
+    delete process.env[testKey];
+
+    const config = upsertSwarmConfig({ scope: "global", key: testKey, value: "to-be-deleted" });
+    scheduleIntegrationsReload(20);
+    await flushPendingIntegrationsReload();
+    expect(process.env[testKey]).toBe("to-be-deleted");
+
+    deleteSwarmConfig(config.id);
+    // Mimic the delete handler in src/http/config.ts.
+    scheduleIntegrationsReload(20);
+    await flushPendingIntegrationsReload();
+
+    // Caveat: process.env keeps the previously-injected value. Reload only
+    // overwrites keys that still exist in DB. This test pins that behavior so
+    // anyone changing the loader has to make a deliberate decision about
+    // whether to also unset removed keys.
+    expect(process.env[testKey]).toBe("to-be-deleted");
+    delete process.env[testKey];
+  });
+});

package/src/tests/status.test.ts

@@ -77,6 +77,7 @@ async function removeDbFiles(path: string): Promise<void> {
 const ENV_KEYS_TO_RESET = [
   "SWARM_CLOUD",
   "SWARM_ORG_NAME",
+  "SWARM_ORG_ID",
   "SWARM_ORG_LOGO_URL",
   "SWARM_BRAND_COLOR",
   "SWARM_MARKETING_URL",
@@ -161,12 +162,14 @@ describe("buildStatusPayload — identity", () => {
       is_cloud: false,
       marketing_url: null,
       hide_cloud_promo: false,
+      org_id: null,
     });
   });
 
   test("reflects SWARM_* envs when all set", () => {
     process.env.SWARM_CLOUD = "true";
     process.env.SWARM_ORG_NAME = "Acme";
+    process.env.SWARM_ORG_ID = "org_acme_123";
     process.env.SWARM_ORG_LOGO_URL = "https://acme.example/logo.png";
     process.env.SWARM_BRAND_COLOR = "#ff5500";
     process.env.SWARM_MARKETING_URL = "https://swarm.acme.example";
@@ -180,6 +183,7 @@ describe("buildStatusPayload — identity", () => {
       is_cloud: true,
       marketing_url: "https://swarm.acme.example",
       hide_cloud_promo: true,
+      org_id: "org_acme_123",
     });
   });
 

package/src/tests/telemetry-init.test.ts

@@ -1,8 +1,9 @@
-import { beforeEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import {
   _getInstallationIdForTests,
   _resetTelemetryStateForTests,
   initTelemetry,
+  track,
 } from "../telemetry";
 
 // initTelemetry no-ops when ANONYMIZED_TELEMETRY=false. The CI env or local
@@ -76,6 +77,141 @@ describe("initTelemetry", () => {
     expect(writes).toEqual([]);
   });
 
+  describe("track() org identity in metadata", () => {
+    const originalFetch = globalThis.fetch;
+    let captured: Record<string, unknown> | null = null;
+
+    beforeEach(() => {
+      captured = null;
+      globalThis.fetch = (async (_url: string, init?: { body?: string }) => {
+        captured = init?.body ? JSON.parse(init.body) : null;
+        return new Response(null, { status: 204 });
+      }) as typeof fetch;
+    });
+
+    afterEach(() => {
+      globalThis.fetch = originalFetch;
+      delete process.env.SWARM_ORG_ID;
+      delete process.env.SWARM_ORG_NAME;
+      delete process.env.SWARM_CLOUD;
+    });
+
+    test("omits organization_* keys from metadata when SWARM_ORG_* unset", async () => {
+      delete process.env.SWARM_ORG_ID;
+      delete process.env.SWARM_ORG_NAME;
+      await initTelemetry(
+        "api-server",
+        async () => undefined,
+        async () => {},
+        {
+          generateIfMissing: true,
+        },
+      );
+
+      track({ event: "test.event", properties: {} });
+      // Wait one microtask for the fire-and-forget fetch.
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.organization_id).toBeUndefined();
+      expect(metadata.organization_name).toBeUndefined();
+    });
+
+    test("includes organization_id + organization_name when SWARM_ORG_* set", async () => {
+      process.env.SWARM_ORG_ID = "org_acme_123";
+      process.env.SWARM_ORG_NAME = "Acme Engineering";
+      await initTelemetry(
+        "api-server",
+        async () => undefined,
+        async () => {},
+        {
+          generateIfMissing: true,
+        },
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.organization_id).toBe("org_acme_123");
+      expect(metadata.organization_name).toBe("Acme Engineering");
+    });
+
+    test("metadata.is_cloud === false when SWARM_CLOUD unset", async () => {
+      delete process.env.SWARM_CLOUD;
+      await initTelemetry(
+        "api-server",
+        async () => undefined,
+        async () => {},
+        {
+          generateIfMissing: true,
+        },
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.is_cloud).toBe(false);
+    });
+
+    test("metadata.is_cloud === true when SWARM_CLOUD=true", async () => {
+      process.env.SWARM_CLOUD = "true";
+      await initTelemetry(
+        "api-server",
+        async () => undefined,
+        async () => {},
+        {
+          generateIfMissing: true,
+        },
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.is_cloud).toBe(true);
+    });
+
+    test("metadata.is_cloud === true when SWARM_CLOUD=1 (mirrors buildIdentity)", async () => {
+      process.env.SWARM_CLOUD = "1";
+      await initTelemetry(
+        "api-server",
+        async () => undefined,
+        async () => {},
+        {
+          generateIfMissing: true,
+        },
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.is_cloud).toBe(true);
+    });
+
+    test("includes only the keys that are set (org_id alone)", async () => {
+      process.env.SWARM_ORG_ID = "org_solo";
+      delete process.env.SWARM_ORG_NAME;
+      await initTelemetry(
+        "api-server",
+        async () => undefined,
+        async () => {},
+        {
+          generateIfMissing: true,
+        },
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.organization_id).toBe("org_solo");
+      expect(metadata.organization_name).toBeUndefined();
+    });
+  });
+
   test("existing config → reuses regardless of generateIfMissing flag", async () => {
     const existing = "install_deadbeefcafebabe";