@desplega.ai/agent-swarm 2.6.0 → 2.7.1

package/src/tests/ui-logs-parser.test.ts

@@ -1,10 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import { normalizeSessionLogs as normalizeEvalLogs } from "../../apps/evals/ui/src/logs-parser";
 import {
+  cacheHitRatio,
   extractSubagentRuns,
   normalizeSessionLogs,
   parseSessionLogs,
   type SessionLogRecord,
+  sumItemCallUsage,
   unwrapResult,
 } from "../../apps/ui/src/logs-parser";
 
@@ -1696,3 +1698,181 @@ describe.each([
     expect(item?.meta).toMatchObject({ type: "codex_error", isError: true });
   });
 });
+
+describe("per-call usage", () => {
+  const claudeUsage = {
+    input_tokens: 6,
+    cache_read_input_tokens: 90_000,
+    cache_creation_input_tokens: 684,
+    output_tokens: 120,
+  };
+  function claudeLine(
+    id: string,
+    line: number,
+    messageId: string,
+    block: unknown,
+    extra: Record<string, unknown> = {},
+  ) {
+    return log(id, "claude", line, {
+      type: "assistant",
+      message: { id: messageId, role: "assistant", content: [block], usage: claudeUsage },
+      ...extra,
+    });
+  }
+  const usages = (logs: SessionLogRecord[]) =>
+    normalizeSessionLogs(logs)
+      .items.filter((item) => item.kind === "call_usage")
+      .map((item) => item.usage);
+
+  test("claude: one call_usage per message.id, not per content-block line", () => {
+    const result = usages([
+      claudeLine("a1", 1, "msg_1", { type: "thinking", thinking: "" }),
+      claudeLine("a2", 2, "msg_1", { type: "text", text: "Looking." }),
+      claudeLine("a3", 3, "msg_1", { type: "tool_use", id: "t1", name: "Read", input: {} }),
+      claudeLine(
+        "s1",
+        4,
+        "msg_2",
+        { type: "text", text: "sub" },
+        {
+          parent_tool_use_id: "toolu_agent",
+        },
+      ),
+    ]);
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({
+      callId: "msg_1",
+      promptTokens: 90_690,
+      cacheReadTokens: 90_000,
+      cacheWriteTokens: 684,
+      uncachedInputTokens: 6,
+      outputTokens: 120,
+      sidechain: false,
+      harness: "claude",
+      reportedAt: "start",
+    });
+    expect(result[1]).toMatchObject({ callId: "msg_2", sidechain: true });
+    expect(cacheHitRatio(result[0]!)).toBeCloseTo(90_000 / 90_690);
+  });
+
+  test("claude: an assistant line without usage emits no call_usage", () => {
+    const result = usages([
+      log("a1", "claude", 1, {
+        type: "assistant",
+        message: { id: "msg_1", role: "assistant", content: [{ type: "text", text: "hi" }] },
+      }),
+    ]);
+    expect(result).toEqual([]);
+  });
+
+  test("the call_usage block shares the call's message, ahead of its content", () => {
+    const messages = parseSessionLogs([
+      claudeLine("a1", 1, "msg_1", { type: "text", text: "Looking." }),
+    ]);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]?.role).toBe("assistant");
+    expect(messages[0]?.content.map((b) => b.type)).toEqual(["provider_meta", "text"]);
+    expect(messages[0]?.content[0]).toMatchObject({
+      kind: "helper",
+      data: { helperType: "call_usage" },
+    });
+  });
+
+  test("codex: context.updated input_tokens already includes cached tokens", () => {
+    const result = usages([
+      log("c1", "codex", 1, {
+        type: "context.updated",
+        usage: {
+          input_tokens: 49_300,
+          cached_input_tokens: 12_000,
+          cache_write_input_tokens: 0,
+          output_tokens: 300,
+          reasoning_output_tokens: 40,
+        },
+        contextWindow: 272_000,
+      }),
+    ]);
+    expect(result).toEqual([
+      {
+        callId: "c1",
+        promptTokens: 49_300,
+        cacheReadTokens: 12_000,
+        cacheWriteTokens: 0,
+        uncachedInputTokens: 37_300,
+        outputTokens: 300,
+        reasoningTokens: 40,
+        sidechain: false,
+        harness: "codex",
+        reportedAt: "end",
+      },
+    ]);
+    expect(cacheHitRatio(result[0]!)).toBeCloseTo(12_000 / 49_300);
+  });
+
+  test("opencode: session.step.ended input excludes cache", () => {
+    const result = usages([
+      log("o1", "opencode", 1, {
+        type: "session.step.ended",
+        data: {
+          sessionID: "ses_1",
+          tokens: { input: 200, output: 50, reasoning: 5, cache: { read: 9_000, write: 800 } },
+        },
+      }),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      promptTokens: 10_000,
+      cacheReadTokens: 9_000,
+      cacheWriteTokens: 800,
+      uncachedInputTokens: 200,
+      harness: "opencode",
+      reportedAt: "end",
+    });
+    expect(cacheHitRatio(result[0]!)).toBeCloseTo(0.9);
+  });
+
+  test("pi: the adapter's call_usage line", () => {
+    const result = usages([
+      log("p1", "pi", 1, {
+        type: "call_usage",
+        harness: "pi",
+        usage: { input: 100, cacheRead: 300, cacheWrite: 100, output: 20, reasoning: 0 },
+      }),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      promptTokens: 500,
+      cacheReadTokens: 300,
+      harness: "pi",
+      reportedAt: "start",
+    });
+    expect(cacheHitRatio(result[0]!)).toBeCloseTo(0.6);
+  });
+
+  test("session totals: Σ read / Σ prompt, and no-cache sessions say so", () => {
+    const totals = sumItemCallUsage(
+      normalizeSessionLogs([
+        claudeLine("a1", 1, "msg_1", { type: "text", text: "one" }),
+        claudeLine("a2", 2, "msg_2", { type: "text", text: "two" }),
+      ]).items,
+    );
+    expect(totals).toMatchObject({
+      calls: 2,
+      promptTokens: 181_380,
+      cacheReadTokens: 180_000,
+      cacheReported: true,
+    });
+    expect(totals?.ratio).toBeCloseTo(180_000 / 181_380);
+
+    const uncached = sumItemCallUsage(
+      normalizeSessionLogs([
+        log("o1", "opencode", 1, {
+          type: "session.step.ended",
+          data: { tokens: { input: 500, output: 5, reasoning: 0, cache: { read: 0, write: 0 } } },
+        }),
+      ]).items,
+    );
+    expect(uncached).toMatchObject({ calls: 1, cacheReported: false, ratio: 0 });
+    expect(sumItemCallUsage([])).toBeNull();
+  });
+});

package/src/tests/whoami-route.test.ts

@@ -17,6 +17,7 @@ import {
   type ServerResponse,
 } from "node:http";
 import { closeDb, createUser, initDb, updateUser } from "../be/db";
+import { ensureRbacSeedsSynced, setUserRoles } from "../be/rbac-roles";
 import { type IdentityActor, mintToken, revokeToken } from "../be/users";
 import { handleCore } from "../http/core";
 import { handleUsers } from "../http/users";
@@ -30,6 +31,7 @@ const ACTOR: IdentityActor = { kind: "operator", id: "op:test" };
 interface WhoamiBody {
   kind: "operator" | "user";
   user: { id: string; name: string; status: string } | null;
+  grants?: { grantsAll: boolean; verbs: string[]; roles: string[] };
 }
 
 function createTestServer(): Server {
@@ -61,6 +63,7 @@ describe("GET /api/whoami", () => {
   beforeAll(async () => {
     cleanupDb();
     initDb(TEST_DB_PATH);
+    ensureRbacSeedsSynced({ quiet: true });
     server = createTestServer();
     port = await listenOnFreePort(server);
   });
@@ -82,6 +85,7 @@ describe("GET /api/whoami", () => {
     const body = (await res.json()) as WhoamiBody;
     expect(body.kind).toBe("operator");
     expect(body.user).toBeNull();
+    expect(body.grants?.grantsAll).toBe(true);
   });
 
   test("active user token resolves to its bound user", async () => {
@@ -96,6 +100,43 @@ describe("GET /api/whoami", () => {
     expect(body.user?.name).toBe("Whoami User");
   });
 
+  test("requester token reports its role and verbs, without grantsAll", async () => {
+    const user = await createUser({ name: "Requester User", email: "req@example.com" });
+    await setUserRoles(user.id, ["requester"], null);
+    const { plaintext } = await mintToken(user.id, "rest", ACTOR);
+
+    const body = (await (await whoami(plaintext)).json()) as WhoamiBody;
+    expect(body.grants?.grantsAll).toBe(false);
+    expect(body.grants?.roles).toEqual(["requester"]);
+    expect(body.grants?.verbs).toContain("task.create.own");
+    expect(body.grants?.verbs).not.toContain("config.write.any");
+  });
+
+  test("a new user holds admin by default: grantsAll", async () => {
+    const user = await createUser({ name: "Default Admin" });
+    const { plaintext } = await mintToken(user.id, "rest", ACTOR);
+
+    const body = (await (await whoami(plaintext)).json()) as WhoamiBody;
+    expect(body.grants?.grantsAll).toBe(true);
+    expect(body.grants?.roles).toEqual(["admin"]);
+  });
+
+  test("RBAC_ENABLED=false reports grantsAll for a viewer", async () => {
+    const user = await createUser({ name: "Viewer User" });
+    await setUserRoles(user.id, ["viewer"], null);
+    const { plaintext } = await mintToken(user.id, "rest", ACTOR);
+    const previous = process.env.RBAC_ENABLED;
+    process.env.RBAC_ENABLED = "false";
+    try {
+      const body = (await (await whoami(plaintext)).json()) as WhoamiBody;
+      expect(body.grants?.grantsAll).toBe(true);
+      expect(body.grants?.roles).toEqual(["viewer"]);
+    } finally {
+      if (previous === undefined) delete process.env.RBAC_ENABLED;
+      else process.env.RBAC_ENABLED = previous;
+    }
+  });
+
   test("revoked token is rejected at auth (401)", async () => {
     const user = await createUser({ name: "Revoked User" });
     const { plaintext, tokenId } = await mintToken(user.id, "rest", ACTOR);

package/src/tests/workflow-engine-v2.test.ts

@@ -21,7 +21,7 @@ import {
   getWorkflowRunStepsByRunId,
   initDb,
 } from "../be/db";
-import type { Workflow, WorkflowDefinition } from "../types";
+import type { ExecutorMeta, Workflow, WorkflowDefinition } from "../types";
 import { shouldSkipCooldown } from "../workflows/cooldown";
 import {
   findReadyNodes,
@@ -143,6 +143,45 @@ class SlowExecutor extends BaseExecutor<typeof SlowExecutor.schema, typeof SlowE
   }
 }
 
+/** What the last `signal-probe` step saw: its abort signal and whether it got to its side effect. */
+const signalProbe: { signal?: AbortSignal; sideEffect: boolean } = { sideEffect: false };
+
+class SignalProbeExecutor extends BaseExecutor<
+  typeof SignalProbeExecutor.schema,
+  typeof SignalProbeExecutor.outSchema
+> {
+  static readonly schema = z.object({ delayMs: z.number() });
+  static readonly outSchema = z.object({ finished: z.boolean() });
+
+  readonly type = "signal-probe";
+  readonly mode = "instant" as const;
+  readonly configSchema = SignalProbeExecutor.schema;
+  readonly outputSchema = SignalProbeExecutor.outSchema;
+
+  protected async execute(
+    config: z.infer<typeof SignalProbeExecutor.schema>,
+    _context: Readonly<Record<string, unknown>>,
+    meta: ExecutorMeta,
+  ): Promise<ExecutorResult<z.infer<typeof SignalProbeExecutor.outSchema>>> {
+    const signal = meta.signal;
+    signalProbe.signal = signal;
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, config.delayMs);
+      signal?.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        { once: true },
+      );
+    });
+    // A one-shot action, like the review trigger a claim script fires.
+    if (!signal?.aborted) signalProbe.sideEffect = true;
+    return { status: "success", output: { finished: true } };
+  }
+}
+
 class FailingExecutor extends BaseExecutor<
   typeof FailingExecutor.schema,
   typeof FailingExecutor.outSchema
@@ -216,6 +255,7 @@ function createTestRegistry(): ExecutorRegistry {
   registry.register(new SlowExecutor(mockDeps));
   registry.register(new FailingExecutor(mockDeps));
   registry.register(new ValidatePassExecutor(mockDeps));
+  registry.register(new SignalProbeExecutor(mockDeps));
   return registry;
 }
 
@@ -561,6 +601,41 @@ describe("Workflow Engine v2 (Phase 3)", () => {
       expect(run!.error).toContain("timed out");
     }, 5_000); // Allow test up to 5s
 
+    test("a timed-out step aborts its executor, so the side effect never happens", async () => {
+      signalProbe.signal = undefined;
+      signalProbe.sideEffect = false;
+      const registry = createTestRegistry();
+      const workflow = await makeWorkflow({
+        nodes: [{ id: "probe", type: "signal-probe", config: { delayMs: 600, timeoutMs: 100 } }],
+      });
+
+      const runId = await startWorkflowExecution(workflow, {}, registry);
+
+      const run = await getWorkflowRun(runId);
+      expect(run!.status).toBe("failed");
+      expect(run!.error).toContain("Step timed out after 100ms");
+      expect(signalProbe.signal?.aborted).toBe(true);
+      // Past the executor's own delay: without the abort it would have fired.
+      await Bun.sleep(700);
+      expect(signalProbe.sideEffect).toBe(false);
+    }, 5_000);
+
+    test("a step that finishes in budget is never aborted afterwards", async () => {
+      signalProbe.signal = undefined;
+      signalProbe.sideEffect = false;
+      const registry = createTestRegistry();
+      const workflow = await makeWorkflow({
+        nodes: [{ id: "probe", type: "signal-probe", config: { delayMs: 10, timeoutMs: 150 } }],
+      });
+
+      const runId = await startWorkflowExecution(workflow, {}, registry);
+
+      expect((await getWorkflowRun(runId))!.status).toBe("completed");
+      expect(signalProbe.sideEffect).toBe(true);
+      await Bun.sleep(250);
+      expect(signalProbe.signal?.aborted).toBe(false);
+    }, 5_000);
+
     // The inline runtime's ulimit preamble fails on macOS (no usable
     // RLIMIT_AS), so the script dies before the watchdog behavior under test.
     // Linux CI is the enforcing environment; the skip only unblocks local
@@ -598,6 +673,46 @@ describe("Workflow Engine v2 (Phase 3)", () => {
 
   // ─── Validation ───────────────────────────────────────────
 
+  describe("Detached start", () => {
+    test("detach returns once the run is committed and walks its instant steps in the background", async () => {
+      const registry = createTestRegistry();
+      const workflow = await makeWorkflow({
+        nodes: [
+          { id: "slow", type: "slow", config: { delayMs: 400 }, next: "after" },
+          { id: "after", type: "echo", config: { message: "done" } },
+        ],
+      });
+
+      const started = performance.now();
+      const runId = await startWorkflowExecution(workflow, {}, registry, { detach: true });
+      const returnedAfterMs = performance.now() - started;
+
+      expect(returnedAfterMs).toBeLessThan(300);
+      expect((await getWorkflowRun(runId))!.status).toBe("running");
+
+      const deadline = Date.now() + 3_000;
+      while ((await getWorkflowRun(runId))!.status === "running" && Date.now() < deadline) {
+        await Bun.sleep(25);
+      }
+      expect((await getWorkflowRun(runId))!.status).toBe("completed");
+      const steps = await getWorkflowRunStepsByRunId(runId);
+      expect(steps.map((step) => step.nodeId).sort()).toEqual(["after", "slow"]);
+    }, 5_000);
+
+    test("without detach the start resolves only after the instant steps ran", async () => {
+      const registry = createTestRegistry();
+      const workflow = await makeWorkflow({
+        nodes: [{ id: "slow", type: "slow", config: { delayMs: 300 } }],
+      });
+
+      const started = performance.now();
+      const runId = await startWorkflowExecution(workflow, {}, registry);
+
+      expect(performance.now() - started).toBeGreaterThanOrEqual(290);
+      expect((await getWorkflowRun(runId))!.status).toBe("completed");
+    }, 5_000);
+  });
+
   describe("Validation", () => {
     test("validation pass allows step to complete", async () => {
       const registry = createTestRegistry();

package/src/tests/workflow-mcp-trigger-schema.test.ts

@@ -10,6 +10,7 @@ import {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
   closeDb,
+  countWorkflowRuns,
   createAgent,
   createTaskExtended,
   createUser,
@@ -20,10 +21,13 @@ import {
   getWorkflowRun,
   getWorkflowRunStepsByRunId,
   initDb,
+  updateWorkflow,
 } from "../be/db";
 import { getPathSegments, parseQueryParams } from "../http/utils";
 import { handleWorkflows } from "../http/workflows";
 import { SCRIPT_LONG_TIMEOUT_HINT_MS } from "../scripts-runtime/executors/types";
+import { SwarmConfig } from "../scripts-runtime/swarm-config";
+import { createSwarmSdk } from "../scripts-runtime/swarm-sdk";
 import { WORKFLOW_LONG_SCRIPT_TIMEOUT_NUDGE } from "../tools/utils";
 import { registerCreateWorkflowTool } from "../tools/workflows/create-workflow";
 import { registerPatchWorkflowTool } from "../tools/workflows/patch-workflow";
@@ -56,6 +60,8 @@ type ToolResult = {
     versionCreated?: number;
     runId?: string;
     skipped?: boolean;
+    replayed?: boolean;
+    idempotencyConflict?: boolean;
     validationErrors?: string[];
     triggerSchema?: Record<string, unknown>;
   };
@@ -627,6 +633,209 @@ describe("MCP create-workflow / update-workflow / patch-workflow accept triggerS
     expect((await getTaskByWorkflowRunStepId(step!.id))?.requestedByUserId).toBe(requester.id);
   });
 
+  test("trigger-workflow wait:false returns the runId before the run's instant steps finish", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("mcp-trigger-detach"),
+      definition: {
+        nodes: [
+          {
+            id: "slow",
+            type: "script",
+            config: { runtime: "bash", script: "sleep 0.6; echo done", timeout: 10_000 },
+          },
+        ],
+      },
+    });
+    createdWorkflowIds.push(workflow.id);
+
+    const started = performance.now();
+    const triggered = await tools.callTrigger({ id: workflow.id, triggerData: {}, wait: false });
+    const elapsedMs = performance.now() - started;
+
+    expect(triggered.structuredContent?.success).toBe(true);
+    expect(triggered.structuredContent?.skipped).toBe(false);
+    const runId = triggered.structuredContent?.runId;
+    expect(runId).toBeString();
+    expect(elapsedMs).toBeLessThan(500);
+    expect((await getWorkflowRun(runId!))?.status).toBe("running");
+
+    const deadline = Date.now() + 10_000;
+    while ((await getWorkflowRun(runId!))?.status === "running" && Date.now() < deadline) {
+      await Bun.sleep(50);
+    }
+    expect((await getWorkflowRun(runId!))?.status).toBe("completed");
+  }, 15_000);
+
+  // A caller killed after its trigger committed (or while its request was in
+  // flight) retries with the same key: the retry must return that run and
+  // start no second one. Before idempotencyKey, the only guard was a separate
+  // claim the caller wrote first, which a kill between the two left held.
+  test("trigger-workflow idempotencyKey: a retry replays the accepted run and starts no second one", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("mcp-trigger-idempotent"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+    });
+    createdWorkflowIds.push(workflow.id);
+    const agentId = crypto.randomUUID();
+    const args = {
+      id: workflow.id,
+      triggerData: { pr: 7, sha: "a".repeat(40) },
+      wait: false,
+      idempotencyKey: "pr-review/repo/pr/7/aaaa",
+    };
+
+    const first = await tools.callTrigger(args, agentId);
+    expect(first.structuredContent?.success).toBe(true);
+    const runId = first.structuredContent?.runId;
+    expect(runId).toBeString();
+    expect(first.structuredContent?.replayed).toBeUndefined();
+
+    // The caller never saw `first` (killed): its retry replays it.
+    const retry = await tools.callTrigger(args, agentId);
+    expect(retry.structuredContent?.success).toBe(true);
+    expect(retry.structuredContent?.runId).toBe(runId);
+    expect(retry.structuredContent?.replayed).toBe(true);
+
+    // The same key with other data starts nothing either.
+    const conflict = await tools.callTrigger(
+      { ...args, triggerData: { pr: 7, sha: "b".repeat(40) } },
+      agentId,
+    );
+    expect(conflict.structuredContent?.success).toBe(false);
+    expect(conflict.structuredContent?.idempotencyConflict).toBe(true);
+
+    // The key is scoped to the caller: another agent's key does not collide.
+    const other = await tools.callTrigger(args, crypto.randomUUID());
+    expect(other.structuredContent?.runId).not.toBe(runId);
+
+    expect(await countWorkflowRuns(workflow.id)).toBe(2);
+  });
+
+  test("trigger-workflow idempotencyKey: concurrent triggers with one key start exactly one run", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("mcp-trigger-idempotent-race"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+    });
+    createdWorkflowIds.push(workflow.id);
+    const agentId = crypto.randomUUID();
+    const args = { id: workflow.id, triggerData: { pr: 8 }, idempotencyKey: "race-key" };
+
+    const results = await Promise.all(
+      Array.from({ length: 6 }, () => tools.callTrigger(args, agentId)),
+    );
+    const runIds = new Set(results.map((r) => r.structuredContent?.runId));
+    expect(results.every((r) => r.structuredContent?.success === true)).toBe(true);
+    expect(runIds.size).toBe(1);
+    expect(results.filter((r) => r.structuredContent?.replayed !== true)).toHaveLength(1);
+    expect(await countWorkflowRuns(workflow.id)).toBe(1);
+  });
+
+  test("trigger-workflow idempotencyKey: a key rejected before acceptance is not used up", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("mcp-trigger-idempotent-disabled"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+      enabled: false,
+    });
+    createdWorkflowIds.push(workflow.id);
+    const agentId = crypto.randomUUID();
+    const args = { id: workflow.id, triggerData: {}, idempotencyKey: "after-enable" };
+
+    expect((await tools.callTrigger(args, agentId)).structuredContent?.success).toBe(false);
+    expect(await countWorkflowRuns(workflow.id)).toBe(0);
+
+    await updateWorkflow(workflow.id, { enabled: true });
+    const accepted = await tools.callTrigger(args, agentId);
+    expect(accepted.structuredContent?.success).toBe(true);
+    expect(accepted.structuredContent?.replayed).toBeUndefined();
+    expect(await countWorkflowRuns(workflow.id)).toBe(1);
+  });
+
+  // `ctx.swarm.workflow_trigger` in a script calls the REST trigger route, not
+  // the MCP tool, so `wait` and `idempotencyKey` must reach that route too.
+  const scriptSdk = (agentId: string) =>
+    createSwarmSdk(
+      new SwarmConfig({
+        system: {
+          apiKey: { value: "sdk-test-key", isSecret: true },
+          agentId: { value: agentId, isSecret: false },
+          mcpBaseUrl: { value: `http://127.0.0.1:${TEST_PORT}`, isSecret: false },
+        },
+        user: {},
+      }),
+    );
+  type SdkTriggerResult = { success: boolean; status: number; data: { runId?: string } };
+
+  test("ctx.swarm.workflow_trigger idempotencyKey: a retry after a kill replays the run", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("sdk-trigger-idempotent"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+    });
+    createdWorkflowIds.push(workflow.id);
+    const sdk = scriptSdk(crypto.randomUUID());
+    const args = {
+      id: workflow.id,
+      triggerData: { pr: 9 },
+      wait: false,
+      idempotencyKey: "pr-review/repo/pr/9/sha",
+    };
+
+    const first = (await sdk.workflow_trigger(args)) as SdkTriggerResult;
+    const retry = (await sdk.workflow_trigger(args)) as SdkTriggerResult;
+    expect(first.success).toBe(true);
+    expect(first.data.runId).toBeString();
+    expect(retry.success).toBe(true);
+    expect(retry.data.runId).toBe(first.data.runId);
+    expect(await countWorkflowRuns(workflow.id)).toBe(1);
+
+    // Two concurrent calls (a killed attempt's in-flight request and its retry).
+    const racing = await createWorkflow({
+      name: uniqueName("sdk-trigger-idempotent-race"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+    });
+    createdWorkflowIds.push(racing.id);
+    const raced = (await Promise.all(
+      Array.from({ length: 4 }, () => sdk.workflow_trigger({ ...args, id: racing.id })),
+    )) as SdkTriggerResult[];
+    expect(new Set(raced.map((r) => r.data.runId)).size).toBe(1);
+    expect(await countWorkflowRuns(racing.id)).toBe(1);
+  });
+
+  test("ctx.swarm.workflow_trigger wait:false returns before the run's instant steps finish", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("sdk-trigger-detach"),
+      definition: {
+        nodes: [
+          {
+            id: "slow",
+            type: "script",
+            config: { runtime: "bash", script: "sleep 0.6; echo done", timeout: 10_000 },
+          },
+        ],
+      },
+    });
+    createdWorkflowIds.push(workflow.id);
+
+    const started = performance.now();
+    const triggered = (await scriptSdk(crypto.randomUUID()).workflow_trigger({
+      id: workflow.id,
+      triggerData: {},
+      wait: false,
+    })) as SdkTriggerResult;
+    const elapsedMs = performance.now() - started;
+
+    expect(triggered.success).toBe(true);
+    const runId = triggered.data.runId;
+    expect(runId).toBeString();
+    expect(elapsedMs).toBeLessThan(500);
+    expect((await getWorkflowRun(runId!))?.status).toBe("running");
+
+    const deadline = Date.now() + 10_000;
+    while ((await getWorkflowRun(runId!))?.status === "running" && Date.now() < deadline) {
+      await Bun.sleep(50);
+    }
+    expect((await getWorkflowRun(runId!))?.status).toBe("completed");
+  }, 15_000);
+
   test("trigger-workflow with missing required field → structured TriggerSchemaError", async () => {
     const triggerSchema: Record<string, unknown> = {
       type: "object",