@botcord/daemon 0.2.75 → 0.2.77

package/src/__tests__/cloud-daemon.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Integration test for {@link startCloudDaemon} — verifies wiring:
+ *
+ * - the control channel uses the `/cloud/daemon/ws` path
+ * - it authenticates with the env-injected JWT (not on-disk user-auth)
+ * - the provisioner is constructed and reachable via the channel's handler
+ * - shutdown is idempotent
+ *
+ * Per-frame `provision_agent` / `revoke_agent` semantics live in
+ * `provision.test.ts` — the cloud daemon reuses the same provisioner.
+ */
+import { EventEmitter } from "node:events";
+import { mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type WebSocket from "ws";
+import { startCloudDaemon } from "../cloud-daemon.js";
+import type { CloudModeConfig } from "../cloud-mode.js";
+import { ControlChannel } from "../control-channel.js";
+import type { DaemonConfig } from "../config.js";
+import type { Gateway, GatewayChannelConfig } from "../gateway/index.js";
+
+class FakeWebSocket extends EventEmitter {
+  public readyState = 0;
+  public sent: string[] = [];
+  public closed = false;
+  static OPEN = 1;
+  constructor(public url: string, public opts: { headers?: Record<string, string> } = {}) {
+    super();
+    setImmediate(() => {
+      this.readyState = FakeWebSocket.OPEN;
+      this.emit("open");
+    });
+  }
+  send(data: string): void {
+    this.sent.push(data);
+  }
+  ping(): void {
+    /* noop */
+  }
+  close(): void {
+    this.closed = true;
+    this.emit("close", 1000, Buffer.from("test"));
+  }
+  static readonly instances: FakeWebSocket[] = [];
+}
+
+function makeFakeCtor() {
+  function Ctor(url: string, opts: { headers?: Record<string, string> } = {}) {
+    const ws = new FakeWebSocket(url, opts);
+    FakeWebSocket.instances.push(ws);
+    return ws;
+  }
+  (Ctor as unknown as { OPEN: number }).OPEN = FakeWebSocket.OPEN;
+  return Ctor as unknown as typeof WebSocket;
+}
+
+function makeCfg(): CloudModeConfig {
+  return {
+    // Loopback host is required by `normalizeAndValidateHubUrl` for http://.
+    // Production cloud daemons use https://api.botcord.chat.
+    hubUrl: "http://localhost:9000",
+    cloudDaemonInstanceId: "cloud_dm_abc123",
+    daemonInstanceId: "dm_abc123",
+    accessToken: "tok_jwt_42",
+  };
+}
+
+function makeDaemonCfg(): DaemonConfig {
+  return {
+    defaultRoute: { adapter: "deepseek-tui", cwd: os.homedir() },
+    routes: [],
+    streamBlocks: true,
+  };
+}
+
+describe("startCloudDaemon", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    FakeWebSocket.instances.length = 0;
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "cloud-daemon-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("dials /cloud/daemon/ws with the injected access token", async () => {
+    const ctor = makeFakeCtor();
+    // Inject a ControlChannel subclass that passes our fake WS through.
+    class TestControlChannel extends ControlChannel {
+      constructor(opts: ConstructorParameters<typeof ControlChannel>[0]) {
+        super({
+          ...opts,
+          webSocketCtor: ctor,
+          hubPublicKey: null,
+        });
+      }
+    }
+
+    const handle = await startCloudDaemon({
+      cloudConfig: makeCfg(),
+      config: makeDaemonCfg(),
+      configPath: "(cloud-mode)",
+      controlChannelFactory: TestControlChannel as unknown as typeof ControlChannel,
+      sessionStorePath: path.join(tmpDir, "sessions.json"),
+      snapshotPath: path.join(tmpDir, "snapshot.json"),
+      snapshotIntervalMs: 60_000,
+    });
+    try {
+      // The control channel connects asynchronously; let microtasks flush.
+      await new Promise((r) => setImmediate(r));
+      await new Promise((r) => setImmediate(r));
+      expect(FakeWebSocket.instances.length).toBeGreaterThanOrEqual(1);
+      const ws = FakeWebSocket.instances[0]!;
+      expect(ws.url).toBe("ws://localhost:9000/cloud/daemon/ws?label=cloud%3Acloud_dm_abc123");
+      expect(ws.opts.headers?.Authorization).toBe("Bearer tok_jwt_42");
+    } finally {
+      await handle.stop("test");
+    }
+  });
+
+  it("skips the control channel when disableControlChannel=true", async () => {
+    const handle = await startCloudDaemon({
+      cloudConfig: makeCfg(),
+      config: makeDaemonCfg(),
+      configPath: "(cloud-mode)",
+      disableControlChannel: true,
+      sessionStorePath: path.join(tmpDir, "sessions.json"),
+      snapshotPath: path.join(tmpDir, "snapshot.json"),
+      snapshotIntervalMs: 60_000,
+    });
+    try {
+      await new Promise((r) => setImmediate(r));
+      expect(FakeWebSocket.instances).toHaveLength(0);
+      // Gateway should still be up — snapshot returns a sane object.
+      const snap = handle.snapshot();
+      expect(snap.channels).toEqual({});
+    } finally {
+      await handle.stop("test");
+    }
+  });
+
+  it("uses the provided provisioner factory", async () => {
+    const provisionerSpy = vi.fn();
+    const factorySpy = vi.fn(() => provisionerSpy);
+    const ctor = makeFakeCtor();
+    class TestControlChannel extends ControlChannel {
+      constructor(opts: ConstructorParameters<typeof ControlChannel>[0]) {
+        super({ ...opts, webSocketCtor: ctor, hubPublicKey: null });
+      }
+    }
+    const handle = await startCloudDaemon({
+      cloudConfig: makeCfg(),
+      config: makeDaemonCfg(),
+      configPath: "(cloud-mode)",
+      controlChannelFactory: TestControlChannel as unknown as typeof ControlChannel,
+      provisionerFactory: factorySpy as unknown as typeof import("../provision.js").createProvisioner,
+      sessionStorePath: path.join(tmpDir, "sessions.json"),
+      snapshotPath: path.join(tmpDir, "snapshot.json"),
+      snapshotIntervalMs: 60_000,
+    });
+    try {
+      expect(factorySpy).toHaveBeenCalledOnce();
+      const callArgs = factorySpy.mock.calls[0]![0] as Record<string, unknown>;
+      expect(callArgs.gateway).toBeDefined();
+      expect(callArgs.onAgentInstalled).toBeInstanceOf(Function);
+      expect(callArgs.policyResolver).toBeDefined();
+    } finally {
+      await handle.stop("test");
+    }
+  });
+
+  it.each(["telegram", "wechat", "feishu"] as const)(
+    "allows %s gateway channels to be hot-plugged in cloud mode",
+    async (type) => {
+      let gateway: Pick<Gateway, "addChannel"> | undefined;
+      const ctor = makeFakeCtor();
+      class TestControlChannel extends ControlChannel {
+        constructor(opts: ConstructorParameters<typeof ControlChannel>[0]) {
+          super({ ...opts, webSocketCtor: ctor, hubPublicKey: null });
+        }
+      }
+      const handle = await startCloudDaemon({
+        cloudConfig: makeCfg(),
+        config: makeDaemonCfg(),
+        configPath: "(cloud-mode)",
+        controlChannelFactory: TestControlChannel as unknown as typeof ControlChannel,
+        provisionerFactory: ((args: { gateway: Gateway }) => {
+          gateway = args.gateway;
+          return vi.fn();
+        }) as unknown as typeof import("../provision.js").createProvisioner,
+        sessionStorePath: path.join(tmpDir, "sessions.json"),
+        snapshotPath: path.join(tmpDir, "snapshot.json"),
+        snapshotIntervalMs: 60_000,
+      });
+      try {
+        expect(gateway).toBeDefined();
+        const cfg: GatewayChannelConfig = {
+          id: `gw_${type}_cloud`,
+          type,
+          accountId: "ag_cloud",
+          allowedSenderIds: [type === "telegram" ? "42" : "alice"],
+          secretFile: path.join(tmpDir, `missing-${type}-secret.json`),
+        };
+        if (type !== "wechat") {
+          cfg.allowedChatIds = ["111"];
+        }
+        if (type === "feishu") {
+          cfg.appId = "cli_test";
+        }
+        await expect(
+          gateway!.addChannel(cfg),
+        ).resolves.toBeUndefined();
+      } finally {
+        await handle.stop("test");
+      }
+    },
+  );
+
+  it("stop() is idempotent", async () => {
+    const handle = await startCloudDaemon({
+      cloudConfig: makeCfg(),
+      config: makeDaemonCfg(),
+      configPath: "(cloud-mode)",
+      disableControlChannel: true,
+      sessionStorePath: path.join(tmpDir, "sessions.json"),
+      snapshotPath: path.join(tmpDir, "snapshot.json"),
+      snapshotIntervalMs: 60_000,
+    });
+    await handle.stop("first");
+    await handle.stop("second");
+    // No throw is the assertion.
+  });
+});

package/src/__tests__/cloud-mode.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import {
+  CLOUD_ENV_VARS,
+  isCloudMode,
+  loadCloudModeConfig,
+} from "../cloud-mode.js";
+
+function makeEnv(overrides: Record<string, string | undefined> = {}): NodeJS.ProcessEnv {
+  return {
+    [CLOUD_ENV_VARS.HUB_URL]: "https://api.botcord.chat",
+    [CLOUD_ENV_VARS.CLOUD_DAEMON_INSTANCE_ID]: "cloud_dm_abc123def456",
+    [CLOUD_ENV_VARS.DAEMON_INSTANCE_ID]: "dm_abc123def456",
+    [CLOUD_ENV_VARS.ACCESS_TOKEN]: "tok_jwt_xxx",
+    ...overrides,
+  } as NodeJS.ProcessEnv;
+}
+
+describe("cloud-mode detection", () => {
+  it("returns true when BOTCORD_CLOUD_DAEMON_ACCESS_TOKEN is set", () => {
+    expect(isCloudMode(makeEnv())).toBe(true);
+  });
+
+  it("returns false when the access token is missing", () => {
+    expect(isCloudMode(makeEnv({ [CLOUD_ENV_VARS.ACCESS_TOKEN]: undefined }))).toBe(false);
+  });
+
+  it("returns false when the access token is empty", () => {
+    expect(isCloudMode(makeEnv({ [CLOUD_ENV_VARS.ACCESS_TOKEN]: "" }))).toBe(false);
+  });
+
+  it("treats missing other env vars as still cloud-mode (will fail at load)", () => {
+    // We only flip on the token; loadCloudModeConfig is what hard-fails. This
+    // keeps the detection check cheap and the failure message specific.
+    expect(
+      isCloudMode(makeEnv({ [CLOUD_ENV_VARS.HUB_URL]: undefined })),
+    ).toBe(true);
+  });
+});
+
+describe("loadCloudModeConfig", () => {
+  it("parses all four env vars into the resolved shape", () => {
+    const cfg = loadCloudModeConfig(makeEnv());
+    expect(cfg).toEqual({
+      hubUrl: "https://api.botcord.chat",
+      cloudDaemonInstanceId: "cloud_dm_abc123def456",
+      daemonInstanceId: "dm_abc123def456",
+      accessToken: "tok_jwt_xxx",
+    });
+  });
+
+  it.each(Object.values(CLOUD_ENV_VARS))(
+    "throws when %s is missing",
+    (name) => {
+      expect(() => loadCloudModeConfig(makeEnv({ [name]: undefined }))).toThrow(
+        new RegExp(`required env var "${name}"`),
+      );
+    },
+  );
+
+  it("throws when an env var is set to an empty string", () => {
+    expect(() =>
+      loadCloudModeConfig(makeEnv({ [CLOUD_ENV_VARS.HUB_URL]: "" })),
+    ).toThrow(/required env var "BOTCORD_HUB_URL"/);
+  });
+});

package/src/__tests__/cloud-settle.test.ts

@@ -0,0 +1,287 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildCloudRunSettleHook, postCloudRunSettle } from "../cloud-settle.js";
+
+interface CapturedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: unknown;
+}
+
+function makeFakeFetch(
+  response: { status: number; body?: unknown } = { status: 200, body: { ok: true } },
+): { fetchFn: typeof fetch; calls: CapturedRequest[] } {
+  const calls: CapturedRequest[] = [];
+  const fetchFn = (async (url: string | URL | Request, init?: RequestInit) => {
+    const body = init?.body ? JSON.parse(init.body as string) : undefined;
+    calls.push({
+      url: String(url),
+      method: init?.method ?? "GET",
+      headers: Object.fromEntries(
+        Object.entries(init?.headers ?? {}).map(([k, v]) => [k, String(v)]),
+      ),
+      body,
+    });
+    return new Response(
+      response.body !== undefined ? JSON.stringify(response.body) : "",
+      {
+        status: response.status,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }) as unknown as typeof fetch;
+  return { fetchFn, calls };
+}
+
+describe("postCloudRunSettle", () => {
+  it("POSTs the expected body to the settle endpoint", async () => {
+    const { fetchFn, calls } = makeFakeFetch();
+    const result = await postCloudRunSettle({
+      hubUrl: "https://api.botcord.chat",
+      accessToken: "tok_jwt_xxx",
+      runId: "crun_abc123",
+      provider: "deepseek",
+      model: "deepseek-chat",
+      inputCacheHitTokens: 100,
+      inputCacheMissTokens: 50,
+      outputTokens: 200,
+      sandboxSeconds: 42,
+      fetchFn,
+    });
+    expect(result.ok).toBe(true);
+    expect(result.status).toBe(200);
+    expect(calls).toHaveLength(1);
+    const call = calls[0]!;
+    expect(call.url).toBe(
+      "https://api.botcord.chat/internal/cloud-agents/runs/crun_abc123/settle",
+    );
+    expect(call.method).toBe("POST");
+    expect(call.headers.Authorization).toBe("Bearer tok_jwt_xxx");
+    expect(call.headers["Content-Type"]).toBe("application/json");
+    expect(call.body).toEqual({
+      provider: "deepseek",
+      model: "deepseek-chat",
+      input_cache_hit_tokens: 100,
+      input_cache_miss_tokens: 50,
+      output_tokens: 200,
+      sandbox_seconds: 42,
+      idempotency_key: "crun_abc123:settle",
+    });
+  });
+
+  it("uses the supplied idempotency_key when provided", async () => {
+    const { fetchFn, calls } = makeFakeFetch();
+    await postCloudRunSettle({
+      hubUrl: "https://api.botcord.chat",
+      accessToken: "tok_x",
+      runId: "crun_x",
+      provider: "deepseek",
+      model: "deepseek-chat",
+      inputCacheHitTokens: 0,
+      inputCacheMissTokens: 0,
+      outputTokens: 0,
+      sandboxSeconds: 0,
+      idempotencyKey: "custom-key-1",
+      fetchFn,
+    });
+    expect((calls[0]!.body as { idempotency_key: string }).idempotency_key).toBe(
+      "custom-key-1",
+    );
+  });
+
+  it("floors negative or fractional usage numbers", async () => {
+    const { fetchFn, calls } = makeFakeFetch();
+    await postCloudRunSettle({
+      hubUrl: "https://api.botcord.chat",
+      accessToken: "tok_x",
+      runId: "crun_x",
+      provider: "deepseek",
+      model: "deepseek-chat",
+      inputCacheHitTokens: -5,
+      inputCacheMissTokens: 1.9,
+      outputTokens: 100.5,
+      sandboxSeconds: 10.4,
+      fetchFn,
+    });
+    const body = calls[0]!.body as Record<string, number>;
+    expect(body.input_cache_hit_tokens).toBe(0);
+    expect(body.input_cache_miss_tokens).toBe(1);
+    expect(body.output_tokens).toBe(100);
+    expect(body.sandbox_seconds).toBe(10);
+  });
+
+  it("returns ok=false on non-2xx without throwing", async () => {
+    const { fetchFn } = makeFakeFetch({
+      status: 401,
+      body: { detail: "unauthorized" },
+    });
+    const result = await postCloudRunSettle({
+      hubUrl: "https://api.botcord.chat",
+      accessToken: "bad",
+      runId: "crun_x",
+      provider: "deepseek",
+      model: "deepseek-chat",
+      inputCacheHitTokens: 0,
+      inputCacheMissTokens: 0,
+      outputTokens: 0,
+      sandboxSeconds: 0,
+      fetchFn,
+    });
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe(401);
+    expect(result.body).toEqual({ detail: "unauthorized" });
+  });
+
+  it("URL-encodes the run id (defensive — Hub uses crun_ prefix today)", async () => {
+    const { fetchFn, calls } = makeFakeFetch();
+    await postCloudRunSettle({
+      hubUrl: "https://api.botcord.chat",
+      accessToken: "t",
+      runId: "crun_abc/../etc",
+      provider: "deepseek",
+      model: "deepseek-chat",
+      inputCacheHitTokens: 0,
+      inputCacheMissTokens: 0,
+      outputTokens: 0,
+      sandboxSeconds: 0,
+      fetchFn,
+    });
+    expect(calls[0]!.url).toContain("crun_abc%2F..%2Fetc");
+  });
+});
+
+
+describe("buildCloudRunSettleHook", () => {
+  function makeLogger() {
+    return {
+      info: vi.fn(),
+      warn: vi.fn(),
+    };
+  }
+
+  it("skips non-cloud_run envelopes", async () => {
+    const { fetchFn, calls } = makeFakeFetch();
+    const hook = buildCloudRunSettleHook({
+      hubUrl: "http://localhost:9000",
+      accessToken: "tok",
+      fetchFn,
+    });
+    await hook({
+      envelopeType: "message",
+      runId: "crun_skipme",
+      wallTimeMs: 1000,
+    });
+    expect(calls).toEqual([]);
+  });
+
+  it("warns and skips when run_id is missing", async () => {
+    const { fetchFn, calls } = makeFakeFetch();
+    const log = makeLogger();
+    const hook = buildCloudRunSettleHook({
+      hubUrl: "http://localhost:9000",
+      accessToken: "tok",
+      fetchFn,
+      log,
+    });
+    await hook({
+      envelopeType: "cloud_run",
+      wallTimeMs: 1000,
+      messageId: "h_xyz",
+    });
+    expect(calls).toEqual([]);
+    expect(log.warn).toHaveBeenCalledWith(
+      "cloud_run envelope missing run_id; skipping settle",
+      expect.objectContaining({ messageId: "h_xyz" }),
+    );
+  });
+
+  it("POSTs settle with sandbox_seconds rounded from wallTimeMs", async () => {
+    const { fetchFn, calls } = makeFakeFetch();
+    const log = makeLogger();
+    const hook = buildCloudRunSettleHook({
+      hubUrl: "http://localhost:9000",
+      accessToken: "tok_xyz",
+      fetchFn,
+      log,
+    });
+    await hook({
+      envelopeType: "cloud_run",
+      runId: "crun_happy",
+      wallTimeMs: 45_321,
+      tokens: { outputTokens: 800 },
+    });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toContain("/internal/cloud-agents/runs/crun_happy/settle");
+    expect(calls[0]!.headers.Authorization).toBe("Bearer tok_xyz");
+    expect(calls[0]!.body).toMatchObject({
+      provider: "deepseek",
+      model: "deepseek-v4-flash",
+      output_tokens: 800,
+      sandbox_seconds: 45,
+      idempotency_key: "crun_happy:settle",
+    });
+    expect(log.info).toHaveBeenCalledWith(
+      "cloud_run settled",
+      expect.objectContaining({ runId: "crun_happy", sandboxSeconds: 45 }),
+    );
+  });
+
+  it("floors sandbox_seconds at 1 even for sub-second runs", async () => {
+    const { fetchFn, calls } = makeFakeFetch();
+    const hook = buildCloudRunSettleHook({
+      hubUrl: "http://localhost:9000",
+      accessToken: "tok",
+      fetchFn,
+    });
+    await hook({
+      envelopeType: "cloud_run",
+      runId: "crun_quick",
+      wallTimeMs: 12,
+    });
+    expect(calls[0]!.body).toMatchObject({ sandbox_seconds: 1 });
+  });
+
+  it("warns on non-2xx settle responses without throwing", async () => {
+    const { fetchFn } = makeFakeFetch({ status: 409, body: { code: "x" } });
+    const log = makeLogger();
+    const hook = buildCloudRunSettleHook({
+      hubUrl: "http://localhost:9000",
+      accessToken: "tok",
+      fetchFn,
+      log,
+    });
+    await hook({
+      envelopeType: "cloud_run",
+      runId: "crun_409",
+      wallTimeMs: 1000,
+    });
+    expect(log.warn).toHaveBeenCalledWith(
+      "cloud_run settle returned non-2xx",
+      expect.objectContaining({ runId: "crun_409", status: 409 }),
+    );
+  });
+
+  it("warns on transport errors without throwing", async () => {
+    const fetchFn = (async () => {
+      throw new TypeError("connect ECONNREFUSED");
+    }) as unknown as typeof fetch;
+    const log = makeLogger();
+    const hook = buildCloudRunSettleHook({
+      hubUrl: "http://localhost:9000",
+      accessToken: "tok",
+      fetchFn,
+      log,
+    });
+    await expect(
+      hook({
+        envelopeType: "cloud_run",
+        runId: "crun_dead",
+        wallTimeMs: 1000,
+      }),
+    ).resolves.toBeUndefined();
+    expect(log.warn).toHaveBeenCalledWith(
+      "cloud_run settle threw — continuing",
+      expect.objectContaining({ runId: "crun_dead" }),
+    );
+  });
+});

package/src/__tests__/daemon-singleton.test.ts

@@ -0,0 +1,89 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  ensureNoOtherDaemonFromPidFile,
+  readPid,
+  removePidFile,
+  stopDaemonFromPidFileForRestart,
+  writeCurrentPid,
+} from "../daemon-singleton.js";
+
+describe("daemon singleton pid helpers", () => {
+  let tmpDir: string;
+  let children: ChildProcess[];
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "botcord-singleton-test-"));
+    children = [];
+  });
+
+  afterEach(() => {
+    for (const child of children) {
+      if (child.pid) {
+        try {
+          process.kill(child.pid, "SIGKILL");
+        } catch {
+          // ignore
+        }
+      }
+    }
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("writes and reads the current pid", () => {
+    const pidPath = path.join(tmpDir, "daemon.pid");
+
+    writeCurrentPid({ pidPath, currentPid: 12345 });
+
+    expect(readPid(pidPath)).toBe(12345);
+    expect(readFileSync(pidPath, "utf8")).toBe("12345");
+  });
+
+  it("does not report the current process as another daemon", () => {
+    const pidPath = path.join(tmpDir, "daemon.pid");
+    writeCurrentPid({ pidPath, currentPid: process.pid });
+
+    expect(ensureNoOtherDaemonFromPidFile({ pidPath, currentPid: process.pid })).toBeNull();
+  });
+
+  it("terminates the daemon recorded in the pid file before restart", async () => {
+    const pidPath = path.join(tmpDir, "daemon.pid");
+    const child = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {
+      stdio: "ignore",
+    });
+    children.push(child);
+    await waitForPid(child);
+    writeCurrentPid({ pidPath, currentPid: child.pid! });
+
+    await stopDaemonFromPidFileForRestart({ pidPath, currentPid: process.pid });
+
+    expect(existsSync(pidPath)).toBe(false);
+    await waitForExit(child);
+    expect(child.exitCode === null && child.signalCode === null).toBe(false);
+  });
+
+  it("removes stale pid files", () => {
+    const pidPath = path.join(tmpDir, "daemon.pid");
+    writeCurrentPid({ pidPath, currentPid: 99999999 });
+
+    removePidFile(pidPath);
+
+    expect(readPid(pidPath)).toBeNull();
+  });
+});
+
+async function waitForPid(child: ChildProcess): Promise<void> {
+  const deadline = Date.now() + 2_000;
+  while (!child.pid && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  if (!child.pid) throw new Error("child pid was not assigned");
+}
+
+async function waitForExit(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  await new Promise<void>((resolve) => child.once("exit", () => resolve()));
+}