@desplega.ai/agent-swarm 1.145.0 → 1.147.0

package/src/tests/defer-task.test.ts

@@ -0,0 +1,389 @@
+/**
+ * Handler-level coverage for the `defer-task` MCP tool.
+ *
+ * `defer-task` completes the task the caller is working on and books a one-off
+ * schedule that wakes the same agent up later with a child task whose
+ * `parentTaskId` is the deferred task. The schedule row IS the state — there
+ * is no new task status — so every test below asserts on the schedule row and
+ * the task row together.
+ *
+ * The handler is pulled straight out of the SDK registry, same pattern as
+ * `store-progress-attachments-handler.test.ts`.
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import crypto from "node:crypto";
+import { unlink } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  closeDb,
+  completeTask,
+  createAgent,
+  createTaskExtended,
+  createWorkflow,
+  createWorkflowRun,
+  createWorkflowRunStep,
+  getScheduledTasks,
+  getTaskById,
+  initDb,
+  startTask,
+} from "../be/db";
+import { registerDeferTaskTool } from "../tools/defer-task";
+
+const TEST_DB_PATH = "./test-defer-task.sqlite";
+
+type RegisteredTool = {
+  handler: (args: unknown, extra: unknown) => Promise<unknown>;
+  // The handler is the raw callback: calling it directly bypasses the SDK's
+  // zod validation, so input-schema assertions go through this field.
+  inputSchema: { safeParse: (value: unknown) => { success: boolean } };
+};
+
+type DeferTaskResult = {
+  content: Array<{ type: string; text: string }>;
+  structuredContent: {
+    success: boolean;
+    message: string;
+    yourAgentId?: string;
+    taskId?: string;
+    scheduleId?: string;
+    nextRunAt?: string;
+    nudge?: string;
+  };
+};
+
+function buildTool(): RegisteredTool {
+  const server = new McpServer({ name: "defer-task-test", version: "1.0.0" });
+  registerDeferTaskTool(server);
+  const registered = (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+    ._registeredTools;
+  const tool = registered["defer-task"];
+  if (!tool) throw new Error("defer-task tool not registered");
+  return tool;
+}
+
+describe("defer-task handler", () => {
+  let agentId: string;
+  let otherAgentId: string;
+
+  beforeAll(async () => {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+    initDb(TEST_DB_PATH);
+    agentId = (
+      await createAgent({
+        name: "Defer Worker",
+        description: "Agent that defers tasks",
+        role: "worker",
+        isLead: false,
+        status: "busy",
+        maxTasks: 1,
+        capabilities: [],
+      })
+    ).id;
+    otherAgentId = (
+      await createAgent({
+        name: "Other Worker",
+        description: "Agent that owns a different task",
+        role: "worker",
+        isLead: false,
+        status: "busy",
+        maxTasks: 1,
+        capabilities: [],
+      })
+    ).id;
+  });
+
+  afterAll(async () => {
+    closeDb();
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+  });
+
+  function meta(callerId: string = agentId) {
+    return {
+      sessionId: `session-${crypto.randomUUID()}`,
+      requestInfo: { headers: { "x-agent-id": callerId } },
+    };
+  }
+
+  async function startedTask(
+    description: string,
+    owner: string = agentId,
+    extra: Partial<Parameters<typeof createTaskExtended>[1]> = {},
+  ) {
+    const task = await createTaskExtended(description, {
+      agentId: owner,
+      source: "mcp",
+      priority: 70,
+      modelTier: "smart",
+      ...extra,
+    });
+    await startTask(task.id);
+    return task;
+  }
+
+  async function schedulesForTask(taskId: string) {
+    return (await getScheduledTasks({ hideCompleted: false })).filter(
+      (s) => s.parentTaskId === taskId,
+    );
+  }
+
+  const SUMMARY = "pushed the config change and kicked off deploy 42";
+
+  test("delayMs path: completes the task and books a one-off wake-up schedule", async () => {
+    const task = await startedTask("wait for the deploy to finish");
+    const before = Date.now();
+
+    const result = (await buildTool().handler(
+      {
+        taskId: task.id,
+        delayMs: 1_800_000,
+        summary: SUMMARY,
+        note: "deploy 42 is still running",
+        checks: ["deploy 42 status is green", "smoke tests pass"],
+      },
+      meta(),
+    )) as DeferTaskResult;
+
+    expect(result.structuredContent.success).toBe(true);
+    expect(result.structuredContent.taskId).toBe(task.id);
+    // The NUDGES entry tells the caller to stop working on the task.
+    expect(result.structuredContent.nudge).toContain("Stop working on this task now");
+
+    const schedules = await schedulesForTask(task.id);
+    expect(schedules.length).toBe(1);
+    const schedule = schedules[0]!;
+    expect(schedule.id).toBe(result.structuredContent.scheduleId!);
+    expect(schedule.scheduleType).toBe("one_time");
+    expect(schedule.targetType).toBe("agent-task");
+    expect(schedule.targetAgentId).toBe(agentId);
+    expect(schedule.createdByAgentId).toBe(agentId);
+    expect(schedule.parentTaskId).toBe(task.id);
+    expect(schedule.taskType).toBe("deferred");
+    expect(schedule.tags).toContain("deferred");
+    expect(schedule.priority).toBe(70);
+    expect(schedule.modelTier).toBe("smart");
+    expect(schedule.taskTemplate).toContain(`Resume task ${task.id}`);
+    expect(schedule.taskTemplate).toContain("- deploy 42 status is green");
+    // The wake-up run reads the summary through the parent task's context.
+    expect(schedule.taskTemplate).not.toContain(SUMMARY);
+
+    // nextRunAt ≈ now + delay (generous window; the handler stamps its own now)
+    const nextRunMs = new Date(schedule.nextRunAt!).getTime();
+    expect(nextRunMs).toBeGreaterThanOrEqual(before + 1_800_000);
+    expect(nextRunMs).toBeLessThan(before + 1_800_000 + 60_000);
+    expect(result.structuredContent.nextRunAt).toBe(schedule.nextRunAt!);
+
+    const stored = await getTaskById(task.id);
+    expect(stored?.status).toBe("completed");
+    // Summary first, then the deferral status line, then the checks.
+    expect(stored?.output?.startsWith(`${SUMMARY}\n\n`)).toBe(true);
+    expect(stored?.output).toContain("Pending: deploy 42 is still running");
+    expect(stored?.output).toContain(schedule.nextRunAt!);
+    expect(stored?.output).toContain(schedule.id);
+    expect(stored?.output).toContain("- smoke tests pass");
+  });
+
+  test("runAt path is honoured verbatim", async () => {
+    const task = await startedTask("wait for the reply");
+    const runAt = new Date(Date.now() + 7_200_000).toISOString();
+
+    const result = (await buildTool().handler(
+      {
+        taskId: task.id,
+        runAt,
+        summary: "asked the customer",
+        note: "waiting on the customer reply",
+      },
+      meta(),
+    )) as DeferTaskResult;
+
+    expect(result.structuredContent.success).toBe(true);
+    expect(result.structuredContent.nextRunAt).toBe(runAt);
+
+    const schedules = await schedulesForTask(task.id);
+    expect(schedules.length).toBe(1);
+    expect(schedules[0]!.nextRunAt).toBe(runAt);
+    expect((await getTaskById(task.id))?.status).toBe("completed");
+  });
+
+  test("rejects both delayMs and runAt, and rejects neither", async () => {
+    const both = await startedTask("both timings");
+    const bothResult = (await buildTool().handler(
+      {
+        taskId: both.id,
+        delayMs: 60_000,
+        runAt: new Date(Date.now() + 60_000).toISOString(),
+        summary: "did some work",
+        note: "pending",
+      },
+      meta(),
+    )) as DeferTaskResult;
+    expect(bothResult.structuredContent.success).toBe(false);
+    expect(bothResult.structuredContent.message).toContain("not both");
+    expect((await schedulesForTask(both.id)).length).toBe(0);
+    expect((await getTaskById(both.id))?.status).toBe("in_progress");
+
+    const neither = await startedTask("no timing");
+    const neitherResult = (await buildTool().handler(
+      { taskId: neither.id, summary: "did some work", note: "pending" },
+      meta(),
+    )) as DeferTaskResult;
+    expect(neitherResult.structuredContent.success).toBe(false);
+    expect(neitherResult.structuredContent.message).toContain("delayMs or runAt");
+    expect((await schedulesForTask(neither.id)).length).toBe(0);
+    expect((await getTaskById(neither.id))?.status).toBe("in_progress");
+  });
+
+  test("an already-terminal task cannot be deferred and books no schedule", async () => {
+    const task = await startedTask("already done");
+    await completeTask(task.id, "finished");
+
+    const result = (await buildTool().handler(
+      { taskId: task.id, delayMs: 60_000, summary: "did some work", note: "pending" },
+      meta(),
+    )) as DeferTaskResult;
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("already completed");
+    expect((await schedulesForTask(task.id)).length).toBe(0);
+  });
+
+  test("another agent's task is refused and books no schedule", async () => {
+    const task = await startedTask("not yours", otherAgentId);
+
+    const result = (await buildTool().handler(
+      { taskId: task.id, delayMs: 60_000, summary: "did some work", note: "pending" },
+      meta(),
+    )) as DeferTaskResult;
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("not assigned to you");
+    expect((await schedulesForTask(task.id)).length).toBe(0);
+    expect((await getTaskById(task.id))?.status).toBe("in_progress");
+  });
+
+  test("summary is required by the input schema", () => {
+    const schema = buildTool().inputSchema;
+    const base = { taskId: crypto.randomUUID(), delayMs: 60_000, note: "pending" };
+    expect(schema.safeParse(base).success).toBe(false);
+    expect(schema.safeParse({ ...base, summary: "" }).success).toBe(false);
+    expect(schema.safeParse({ ...base, summary: SUMMARY }).success).toBe(true);
+  });
+
+  test("an unknown task is refused", async () => {
+    const result = (await buildTool().handler(
+      { taskId: crypto.randomUUID(), delayMs: 60_000, summary: "did some work", note: "pending" },
+      meta(),
+    )) as DeferTaskResult;
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("not found");
+  });
+
+  test("a workflow-owned task cannot be deferred and books no schedule", async () => {
+    const workflow = await createWorkflow({
+      name: `defer-race-${crypto.randomUUID()}`,
+      definition: { nodes: [] },
+    });
+    const runId = crypto.randomUUID();
+    const stepId = crypto.randomUUID();
+    await createWorkflowRun({ id: runId, workflowId: workflow.id });
+    await createWorkflowRunStep({ id: stepId, runId, nodeId: "step", nodeType: "agent-task" });
+
+    const task = await startedTask("workflow step", agentId, {
+      workflowRunId: runId,
+      workflowRunStepId: stepId,
+    });
+
+    const result = (await buildTool().handler(
+      { taskId: task.id, delayMs: 60_000, summary: "did some work", note: "pending" },
+      meta(),
+    )) as DeferTaskResult;
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("workflow");
+    expect((await schedulesForTask(task.id)).length).toBe(0);
+    expect((await getTaskById(task.id))?.status).toBe("in_progress");
+  });
+
+  test("a task with an outputSchema refuses a prose deferral and books no schedule", async () => {
+    const task = await startedTask("structured output task", agentId, {
+      outputSchema: {
+        type: "object",
+        required: ["result"],
+        properties: { result: { type: "string" } },
+      },
+    });
+
+    const result = (await buildTool().handler(
+      { taskId: task.id, delayMs: 60_000, summary: "did some work", note: "pending" },
+      meta(),
+    )) as DeferTaskResult;
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("outputSchema");
+    expect((await schedulesForTask(task.id)).length).toBe(0);
+    const stored = await getTaskById(task.id);
+    expect(stored?.status).toBe("in_progress");
+    expect(stored?.output).toBeFalsy();
+  });
+
+  test("the wake-up schedule carries modelTier but never the parent's concrete model", async () => {
+    const task = await startedTask("pinned model task", agentId, {
+      model: "claude-sonnet-5",
+    });
+
+    const result = (await buildTool().handler(
+      { taskId: task.id, delayMs: 60_000, summary: "did some work", note: "pending" },
+      meta(),
+    )) as DeferTaskResult;
+
+    expect(result.structuredContent.success).toBe(true);
+    const schedules = await schedulesForTask(task.id);
+    expect(schedules.length).toBe(1);
+    expect(schedules[0]!.modelTier).toBe("smart");
+    expect(schedules[0]!.model).toBeFalsy();
+  });
+
+  test("a competing terminal transition between schedule creation and completion aborts the loser and books no orphan schedule", async () => {
+    const task = await startedTask("race target");
+
+    const [first, second] = (await Promise.all([
+      buildTool().handler(
+        { taskId: task.id, delayMs: 60_000, summary: "first writer", note: "pending A" },
+        meta(),
+      ),
+      buildTool().handler(
+        { taskId: task.id, delayMs: 90_000, summary: "second writer", note: "pending B" },
+        meta(),
+      ),
+    ])) as [DeferTaskResult, DeferTaskResult];
+
+    const results = [first, second];
+    const succeeded = results.filter((r) => r.structuredContent.success);
+    const failed = results.filter((r) => !r.structuredContent.success);
+
+    // Both pass the early terminal check (neither has completed yet when it
+    // reads); the FIFO transaction lock serializes their writes, so exactly
+    // one wins the completeTask race and the other's completeTask() returns
+    // null and must abort rather than substitute the stale pre-write task.
+    expect(succeeded.length).toBe(1);
+    expect(failed.length).toBe(1);
+    expect(failed[0]!.structuredContent.message).toContain("terminal state");
+
+    // The loser's schedule INSERT rolled back with its transaction — only
+    // the winner's wake-up was committed. No orphan schedule.
+    const schedules = await schedulesForTask(task.id);
+    expect(schedules.length).toBe(1);
+
+    const stored = await getTaskById(task.id);
+    expect(stored?.status).toBe("completed");
+  });
+});

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

@@ -103,8 +103,8 @@ describe("docs API index footprint", () => {
     expect(spec.paths["/api/agents/{id}/runtime"]?.get).toBeDefined();
 
     const generatedKeys = await generatedOperationKeys();
-    expect(operationKeys).toHaveLength(359);
-    expect(generatedKeys).toHaveLength(359);
+    expect(operationKeys).toHaveLength(361);
+    expect(generatedKeys).toHaveLength(361);
     expect(new Set(generatedKeys)).toEqual(new Set(operationKeys));
   });
 

package/src/tests/e2e-visuals-stage.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runChild } from "./test-proc";
+
+const SCRIPT = join(import.meta.dir, "../../scripts/e2e/visuals-stage.sh");
+
+let outRoot: string;
+let stagedRoot: string;
+
+beforeEach(() => {
+  outRoot = mkdtempSync(join(tmpdir(), "visuals-stage-out-"));
+  stagedRoot = join(mkdtempSync(join(tmpdir(), "visuals-stage-target-")), "staged");
+});
+
+afterEach(() => {
+  rmSync(outRoot, { recursive: true, force: true });
+  rmSync(stagedRoot, { recursive: true, force: true });
+});
+
+function writeProfile(profile: string) {
+  const dir = join(outRoot, profile);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "index.json"), JSON.stringify({ profile }));
+  writeFileSync(join(dir, "channel.png"), "png-bytes");
+  mkdirSync(join(dir, "frames"), { recursive: true });
+  return dir;
+}
+
+function writeFrame(profileDir: string, relPath: string, contents = "frame-bytes") {
+  const full = join(profileDir, "frames", relPath);
+  mkdirSync(join(full, ".."), { recursive: true });
+  writeFileSync(full, contents);
+}
+
+async function stage() {
+  return runChild(["bash", SCRIPT, outRoot, stagedRoot]);
+}
+
+describe("visuals-stage.sh", () => {
+  test("stages nested scenario/thread frames at their original relative path", async () => {
+    const dir = writeProfile("v2");
+    writeFrame(dir, "slack-mention/mention/final-thread.png");
+    writeFrame(dir, "slack-mention/mention/final-desktop.gif");
+    writeFrame(dir, "slack-delegation/delegation-child-result/final-desktop.png");
+
+    const result = await stage();
+    expect(result.exitCode).toBe(0);
+
+    const staged = Bun.file(
+      join(stagedRoot, "v2", "frames", "slack-mention", "mention", "final-thread.png"),
+    );
+    expect(await staged.exists()).toBe(true);
+    expect(await staged.text()).toBe("frame-bytes");
+
+    const gif = Bun.file(
+      join(stagedRoot, "v2", "frames", "slack-mention", "mention", "final-desktop.gif"),
+    );
+    expect(await gif.exists()).toBe(true);
+
+    const other = Bun.file(
+      join(
+        stagedRoot,
+        "v2",
+        "frames",
+        "slack-delegation",
+        "delegation-child-result",
+        "final-desktop.png",
+      ),
+    );
+    expect(await other.exists()).toBe(true);
+  });
+
+  test("rejects a symlinked intermediate frame directory", async () => {
+    const dir = writeProfile("v2");
+    const realDir = join(dir, "frames", "real-scenario");
+    mkdirSync(realDir, { recursive: true });
+    writeFileSync(join(realDir, "thread"), "");
+    rmSync(join(realDir, "thread"));
+    mkdirSync(join(realDir, "thread"), { recursive: true });
+    writeFileSync(join(realDir, "thread", "final.png"), "frame-bytes");
+
+    // Symlink a second scenario dir's "thread" segment at the intermediate level.
+    const evilScenario = join(dir, "frames", "evil-scenario");
+    mkdirSync(evilScenario, { recursive: true });
+    symlinkSync(join(realDir, "thread"), join(evilScenario, "thread"));
+
+    const result = await stage();
+    // The good scenario still stages one frame, so overall exit is 0 — assert the symlinked
+    // one specifically never lands, either flagged or simply absent from the traversal.
+    expect(result.exitCode).toBe(0);
+    const evilStaged = Bun.file(
+      join(stagedRoot, "v2", "frames", "evil-scenario", "thread", "final.png"),
+    );
+    expect(await evilStaged.exists()).toBe(false);
+  });
+
+  // A literal ".." path component cannot exist as a real filesystem entry — the OS always
+  // resolves it to the parent directory, and `find` (without `-L`) never emits "." or ".."
+  // as traversal results. So the script's `case "/$rel_path/" in */../*)` guard is defense in
+  // depth for a rel_path construction bug, not something a crafted artifact can trigger via a
+  // real directory name. This test instead proves the adjacent, actually reachable guard: a
+  // directory segment outside the safe charset is rejected while safe siblings still stage.
+  test("rejects an unsafe directory segment but keeps safe siblings", async () => {
+    const dir = writeProfile("v2");
+    writeFrame(dir, "scenario/thread/ok.png");
+    writeFrame(dir, "scenario/th read/bad.png");
+
+    const result = await stage();
+    expect(result.exitCode).toBe(0);
+    const bad = Bun.file(join(stagedRoot, "v2", "frames", "scenario", "th read", "bad.png"));
+    expect(await bad.exists()).toBe(false);
+    const ok = Bun.file(join(stagedRoot, "v2", "frames", "scenario", "thread", "ok.png"));
+    expect(await ok.exists()).toBe(true);
+  });
+
+  test("rejects an unsafe leaf frame name but keeps safe siblings", async () => {
+    const dir = writeProfile("v2");
+    writeFrame(dir, "scenario/thread/ok.png");
+    writeFrame(dir, "scenario/thread/bad name!.png");
+
+    const result = await stage();
+    expect(result.exitCode).toBe(0);
+    const bad = Bun.file(join(stagedRoot, "v2", "frames", "scenario", "thread", "bad name!.png"));
+    expect(await bad.exists()).toBe(false);
+    const ok = Bun.file(join(stagedRoot, "v2", "frames", "scenario", "thread", "ok.png"));
+    expect(await ok.exists()).toBe(true);
+  });
+
+  test("fails the whole run when a profile stages zero frames", async () => {
+    const dir = writeProfile("v2");
+    // frames/ exists but every entry is invalid, so nothing gets staged.
+    writeFrame(dir, "scenario/thread/bad name!.png");
+
+    const result = await stage();
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("Staged zero frames");
+  });
+
+  test("fails when frames/ is missing entirely", async () => {
+    const dir = join(outRoot, "v2");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "index.json"), "{}");
+    writeFileSync(join(dir, "channel.png"), "png-bytes");
+
+    const result = await stage();
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("Missing frames directory");
+  });
+});

package/src/tests/file-lock.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setFlockForTests, withFileLock } from "../utils/file-lock";
+import { CHILD_PROCESS_TEST_BUDGET_MS, CHILD_PROCESS_TIMEOUT_MS } from "./test-proc";
+
+const HOLDER = join(import.meta.dir, "fixtures/file-lock-holder.ts");
+
+/**
+ * Start a separate process holding the lock; resolves once it has it. The child
+ * is killed at CHILD_PROCESS_TIMEOUT_MS no matter what, and waiting for its
+ * "locked" line gives up at the same deadline.
+ */
+async function holdInAnotherProcess(lockPath: string, holdMs: number) {
+  const child = Bun.spawn([process.execPath, HOLDER, lockPath, String(holdMs)], {
+    stdout: "pipe",
+    stderr: "inherit",
+    timeout: CHILD_PROCESS_TIMEOUT_MS,
+    killSignal: "SIGKILL",
+  });
+  const reader = child.stdout.getReader();
+  const deadline = Date.now() + CHILD_PROCESS_TIMEOUT_MS;
+  let out = "";
+  while (!out.includes("locked")) {
+    const next = await Promise.race([
+      reader.read(),
+      Bun.sleep(Math.max(0, deadline - Date.now())).then(() => "timeout" as const),
+    ]);
+    if (next === "timeout" || next.done) {
+      child.kill("SIGKILL");
+      throw new Error(`holder did not lock: ${out}`);
+    }
+    out += new TextDecoder().decode(next.value);
+  }
+  reader.releaseLock();
+  return child;
+}
+
+describe("withFileLock (kernel flock)", () => {
+  let root: string;
+  let lock: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "file-lock-"));
+    lock = join(root, "nested/dir/test.lock"); // parent created on demand
+  });
+
+  afterEach(async () => {
+    setFlockForTests(undefined);
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test("serializes concurrent holders", async () => {
+    const events: string[] = [];
+    const hold = (name: string) =>
+      withFileLock(lock, async () => {
+        events.push(`${name}:in`);
+        await Bun.sleep(50);
+        events.push(`${name}:out`);
+      });
+
+    await Promise.all([hold("a"), hold("b")]);
+
+    expect(events).toHaveLength(4);
+    expect(events[1]).toBe(events[0]?.replace(":in", ":out")); // no overlap
+  });
+
+  test(
+    "a live holder is never robbed, however old its lock file looks",
+    async () => {
+      // The previous lock broke any lock file older than 30 s. Backdate the file
+      // while a live process holds it: nothing may take it over.
+      const holder = await holdInAnotherProcess(lock, 2_000);
+      try {
+        const longAgo = new Date(0);
+        await utimes(lock, longAgo, longAgo);
+
+        const whileHeld = await withFileLock(lock, async () => "ran", { waitMs: 300 });
+        expect(whileHeld).toEqual({ acquired: false, reason: "busy" });
+
+        await holder.exited;
+        expect(await withFileLock(lock, async () => "ran", { waitMs: 1_000 })).toEqual({
+          acquired: true,
+          value: "ran",
+        });
+      } finally {
+        holder.kill("SIGKILL");
+      }
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "a holder killed with SIGKILL releases the lock",
+    async () => {
+      const holder = await holdInAnotherProcess(lock, 60_000);
+      try {
+        holder.kill("SIGKILL");
+        await holder.exited;
+
+        expect(await withFileLock(lock, async () => "ran", { waitMs: 1_000 })).toEqual({
+          acquired: true,
+          value: "ran",
+        });
+      } finally {
+        holder.kill("SIGKILL");
+      }
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test("releases the lock when fn throws, and never deletes the lock file", async () => {
+    await expect(
+      withFileLock(lock, async () => {
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+
+    expect(await Bun.file(lock).exists()).toBe(true); // unlinking would allow a second inode
+    expect(await withFileLock(lock, async () => "again", { waitMs: 100 })).toEqual({
+      acquired: true,
+      value: "again",
+    });
+  });
+
+  test("reports an unusable lock path as an error, not as busy", async () => {
+    await Bun.write(join(root, "file"), "not a directory");
+    const result = await withFileLock(join(root, "file/test.lock"), async () => "ran");
+
+    expect(result).toMatchObject({ acquired: false, reason: "error" });
+  });
+
+  test("without flock on the platform it never runs fn", async () => {
+    setFlockForTests(null);
+    let ran = false;
+    const result = await withFileLock(lock, async () => {
+      ran = true;
+    });
+
+    expect(result).toEqual({ acquired: false, reason: "unsupported" });
+    expect(ran).toBe(false);
+  });
+});