Skip to content

Write HTML. Render video. Built for agents.

34.3 KB
Raw Blame
import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { describe, expect, it, onTestFinished, vi } from "vitest";
import type { ActiveServer } from "../server/portUtils.js";
import { PreviewServerPortMismatchError } from "../utils/studioSelectionClient.js";
import {
  PreviewPortUnavailableError,
  buildBackgroundPreviewArgs,
  listBackgroundPreviewStatuses,
  previewSessionPath,
  readBackgroundPreviewStatus,
  startBackgroundPreview,
  stopBackgroundPreview,
  writePreviewSession,
} from "./previewLifecycle.js";

const projectDir = resolve("/tmp/hyperframes-preview-lifecycle-project");
const server: ActiveServer = {
  port: 3210,
  projectName: "preview-lifecycle-project",
  projectDir,
  version: "test",
  pid: "4321",
};

function tempDir(prefix: string): string {
  const dir = mkdtempSync(join(tmpdir(), prefix));
  onTestFinished(() => rmSync(dir, { recursive: true, force: true }));
  return dir;
}

function savePreviewSession(stateHome: string): void {
  writePreviewSession(
    { pid: 4321, port: 3210, projectDir, logPath: "/tmp/preview.log" },
    stateHome,
  );
}

/** Launch deps whose wrapper (PID 4321) brings up `server` (PID 9876) on spawn and takes it down on kill. */
function reachableChildDependencies(stateHome: string, { immortal = false } = {}) {
  let spawned = false;
  let killed = false;
  const liveServer = { ...server, pid: "9876" };
  return {
    scan: async () => (spawned && (immortal || !killed) ? [liveServer] : []),
    spawn: () => {
      spawned = true;
      return { pid: 4321, unref: vi.fn() };
    },
    sleep: async () => {},
    kill: vi.fn(() => {
      killed = true;
    }),
    isDescendant: (child: number, ancestor: number) => child === 9876 && ancestor === 4321,
    stateHome,
  };
}

async function expectStaleSessionRemoved(stateHome: string): Promise<void> {
  const status = await readBackgroundPreviewStatus(projectDir, 3002, {
    scan: async () => [],
    stateHome,
  });

  expect(status).toBeNull();
  expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
}

describe("background preview lifecycle", () => {
  it("keeps case-distinct project paths separate on case-sensitive platforms", () => {
    if (process.platform === "win32") return;
    const stateHome = tempDir("hf-preview-state-");

    expect(previewSessionPath("/tmp/Project", stateHome)).not.toBe(
      previewSessionPath("/tmp/project", stateHome),
    );
  });

  it("forces the detached child foreground without inheriting launcher-only flags", () => {
    expect(
      buildBackgroundPreviewArgs([
        "/opt/hyperframes/cli.js",
        "preview",
        projectDir,
        "--background",
        "--open",
        "--json",
      ]),
    ).toEqual([
      "/opt/hyperframes/cli.js",
      "preview",
      projectDir,
      "--foreground",
      "--no-open",
      "--force-new",
    ]);
  });

  it("makes the detached child start its own server, never reuse a sibling launch's", () => {
    const args = buildBackgroundPreviewArgs(["cli.js", "preview", projectDir, "--force-new"]);

    expect(args.filter((arg) => arg === "--force-new")).toHaveLength(1);
    expect(args.at(-1)).toBe("--force-new");
  });

  it("reuses an already-running server for the same project", async () => {
    const spawn = vi.fn();
    const scan = vi.fn(async () => [server]);

    const result = await startBackgroundPreview(projectDir, 3002, {
      argv: ["/opt/hyperframes/cli.js", "preview", projectDir, "--background"],
      execPath: "/usr/bin/node",
      scan,
      spawn,
      stateHome: tempDir("hf-preview-state-"),
    });

    expect(result).toMatchObject({ type: "reused", port: 3210 });
    expect(spawn).not.toHaveBeenCalled();
  });

  it("reuses a saved managed preview on a custom port without repeating --port", async () => {
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      { pid: 4321, port: 41402, projectDir, logPath: "/tmp/custom.log" },
      stateHome,
    );
    const customServer = { ...server, port: 41402, browserGpuMode: "software" as const };
    const scan = vi.fn(async (startPort?: number) => (startPort === 41402 ? [customServer] : []));
    const spawn = vi.fn();

    const result = await startBackgroundPreview(projectDir, 3002, {
      scan,
      spawn,
      stateHome,
    });

    expect(result).toMatchObject({ type: "reused", port: 41402, pid: 4321 });
    expect(scan).toHaveBeenCalledWith(41402);
    expect(spawn).not.toHaveBeenCalled();
  });

  it("throws a port-mismatch error when the caller explicitly requests a port the reused server isn't on", async () => {
    const spawn = vi.fn();
    const scan = vi.fn(async () => [server]);

    await expect(
      startBackgroundPreview(projectDir, 3002, {
        scan,
        spawn,
        stateHome: mkdtempSync(join(tmpdir(), "hf-preview-state-")),
        preferredPort: server.port + 1,
      }),
    ).rejects.toThrow(PreviewServerPortMismatchError);
    expect(spawn).not.toHaveBeenCalled();
  });

  it("reuses normally when the caller's explicit port matches the reused server", async () => {
    const spawn = vi.fn();
    const scan = vi.fn(async () => [server]);

    const result = await startBackgroundPreview(projectDir, 3002, {
      scan,
      spawn,
      stateHome: mkdtempSync(join(tmpdir(), "hf-preview-state-")),
      preferredPort: server.port,
    });

    expect(result).toMatchObject({ type: "reused", port: server.port });
    expect(spawn).not.toHaveBeenCalled();
  });

  it("discovers managed previews outside the default port scan and removes stale records", async () => {
    const stateHome = tempDir("hf-preview-state-");
    const otherProjectDir = resolve("/tmp/hyperframes-preview-managed-custom-port");
    const staleProjectDir = resolve("/tmp/hyperframes-preview-managed-stale");
    writePreviewSession(
      {
        pid: 8765,
        port: 41402,
        projectDir: otherProjectDir,
        logPath: "/tmp/custom.log",
      },
      stateHome,
    );
    writePreviewSession(
      {
        pid: 9999,
        port: 45000,
        projectDir: staleProjectDir,
        logPath: "/tmp/stale.log",
      },
      stateHome,
    );

    const statuses = await listBackgroundPreviewStatuses({
      stateHome,
      scan: async (startPort) =>
        startPort === 41402
          ? [
              {
                port: 41402,
                projectName: "managed-custom-port",
                projectDir: otherProjectDir,
                version: "test",
                pid: "8765",
              },
            ]
          : [],
    });

    expect(statuses).toEqual([
      {
        pid: 8765,
        port: 41402,
        projectDir: otherProjectDir,
        logPath: "/tmp/custom.log",
      },
    ]);
    expect(existsSync(previewSessionPath(staleProjectDir, stateHome))).toBe(false);
  });

  it("force-new waits for a different server instead of reusing the existing one", async () => {
    const replacement = { ...server, port: 3211, pid: "5432" };
    let scans = 0;
    const scan = vi.fn(async () => (++scans < 3 ? [server] : [server, replacement]));
    const spawn = vi.fn(() => ({ pid: 5432, unref: vi.fn() }));

    const result = await startBackgroundPreview(projectDir, 3002, {
      forceNew: true,
      scan,
      spawn,
      sleep: async () => {},
      stateHome: tempDir("hf-preview-state-"),
    });

    expect(result).toMatchObject({ type: "started", port: 3211, pid: 5432 });
    expect(spawn).toHaveBeenCalledOnce();
  });

  it.each([
    ["force-new", true],
    ["a GPU-policy change", false],
  ])(
    "%s replaces a previously managed server instead of orphaning it",
    async (_label, forceNew) => {
      const stateHome = tempDir("hf-preview-state-");
      const oldServer = { ...server, port: 41490, browserGpuMode: "hardware" as const };
      writePreviewSession(
        { pid: 4321, port: 41490, projectDir, logPath: "/tmp/preview.log" },
        stateHome,
      );
      const replacement = {
        ...server,
        port: 41491,
        pid: "5432",
        browserGpuMode: "software" as const,
      };
      let oldRunning = true;
      let replacementRunning = false;
      const scan = vi.fn(async () =>
        oldRunning ? [oldServer] : replacementRunning ? [replacement] : [],
      );
      const kill = vi.fn((pid: number) => {
        if (pid === 4321) oldRunning = false;
      });
      const spawn = vi.fn(() => {
        replacementRunning = true;
        return { pid: 5432, unref: vi.fn() };
      });

      const result = await startBackgroundPreview(projectDir, 41491, {
        browserGpuMode: "software",
        forceNew,
        kill,
        scan,
        sleep: async () => {},
        spawn,
        stateHome,
      });

      expect(scan).toHaveBeenNthCalledWith(1, 41490);
      expect(kill).toHaveBeenCalledWith(4321);
      expect(result).toMatchObject({ type: "started", port: 41491, pid: 5432 });
      expect(readFileSync(previewSessionPath(projectDir, stateHome), "utf8")).toContain(
        '"port": 41491',
      );
    },
  );

  it("replaces the owned preview instead of reusing an unmanaged policy-matching sibling", async () => {
    const stateHome = tempDir("hf-preview-state-");
    const owned = { ...server, port: 41490, browserGpuMode: "hardware" as const };
    const sibling = {
      ...server,
      port: 41491,
      pid: "8765",
      browserGpuMode: "software" as const,
    };
    const replacement = {
      ...server,
      port: 41492,
      pid: "5432",
      browserGpuMode: "software" as const,
    };
    writePreviewSession(
      { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },
      stateHome,
    );
    let ownedRunning = true;
    let replacementRunning = false;
    const scan = vi.fn(async () => [
      ...(ownedRunning ? [owned] : []),
      sibling,
      ...(replacementRunning ? [replacement] : []),
    ]);
    const kill = vi.fn((pid: number) => {
      if (pid === 4321) ownedRunning = false;
    });
    const spawn = vi.fn(() => {
      replacementRunning = true;
      return { pid: 5432, unref: vi.fn() };
    });

    const result = await startBackgroundPreview(projectDir, replacement.port, {
      browserGpuMode: "software",
      kill,
      scan,
      sleep: async () => {},
      spawn,
      stateHome,
    });

    expect(kill).toHaveBeenCalledWith(4321);
    expect(spawn).toHaveBeenCalledOnce();
    expect(result).toMatchObject({ type: "started", port: replacement.port, pid: 5432 });
  });

  it("launches the replacement when the owned server died on its own", async () => {
    // The owned preview crashes (or is Ctrl-C'd) between the outer scan and the
    // one inside the stop. "Nothing left to stop" is the goal state for a
    // replacement; treating it as fatal refused to start any preview at all
    // until the session record was deleted by hand.
    const stateHome = tempDir("hf-preview-state-");
    const owned = { ...server, port: 41490 };
    const replacement = { ...server, port: 41491, pid: "5432" };
    writePreviewSession(
      { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },
      stateHome,
    );
    let scans = 0;
    let replacementRunning = false;
    const scan = vi.fn(async () => {
      scans += 1;
      // Alive for the first look, gone by the time the stop path scans.
      const ownedNow = scans === 1 ? [owned] : [];
      return [...ownedNow, ...(replacementRunning ? [replacement] : [])];
    });
    const kill = vi.fn();
    const spawn = vi.fn(() => {
      replacementRunning = true;
      return { pid: 5432, unref: vi.fn() };
    });

    const result = await startBackgroundPreview(projectDir, replacement.port, {
      forceNew: true,
      kill,
      scan,
      sleep: async () => {},
      spawn,
      stateHome,
    });

    expect(kill).not.toHaveBeenCalled();
    expect(result).toMatchObject({ type: "started", port: replacement.port, pid: 5432 });
  });

  it("starts a replacement when the existing server uses a different GPU policy", async () => {
    const hardwareServer = { ...server, browserGpuMode: "hardware" as const };
    const softwareServer = {
      ...server,
      port: 3211,
      pid: "5432",
      browserGpuMode: "software" as const,
    };
    let replacementRunning = false;
    const scan = vi.fn(async () => [
      hardwareServer,
      ...(replacementRunning ? [softwareServer] : []),
    ]);
    const spawn = vi.fn(() => {
      replacementRunning = true;
      return { pid: 5432, unref: vi.fn() };
    });

    const result = await startBackgroundPreview(projectDir, 3002, {
      browserGpuMode: "software",
      scan,
      spawn,
      sleep: async () => {},
      stateHome: tempDir("hf-preview-state-"),
    });

    expect(result).toMatchObject({ type: "started", port: 3211, pid: 5432 });
    expect(spawn).toHaveBeenCalledOnce();
  });

  it("returns after a detached child becomes reachable and records its session", async () => {
    let spawned = false;
    const scan = vi.fn(async () => (spawned ? [server] : []));
    const unref = vi.fn();
    const spawn = vi.fn(() => {
      spawned = true;
      return { pid: 4321, unref };
    });
    const stateHome = tempDir("hf-preview-state-");

    const result = await startBackgroundPreview(projectDir, 3002, {
      argv: ["/opt/hyperframes/cli.js", "preview", projectDir, "--background"],
      execPath: "/usr/bin/node",
      scan,
      spawn,
      sleep: async () => {},
      stateHome,
    });

    expect(result).toMatchObject({ type: "started", port: 3210, pid: 4321 });
    expect(unref).toHaveBeenCalledOnce();
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(true);
  });

  it("reports the live server PID while retaining the wrapper PID for cleanup", async () => {
    const liveServer = { ...server, pid: "9876" };
    let spawned = false;
    const scan = vi.fn(async () => (spawned ? [liveServer] : []));
    const stateHome = tempDir("hf-preview-state-");

    const result = await startBackgroundPreview(projectDir, 3002, {
      scan,
      spawn: () => {
        spawned = true;
        return { pid: 4321, unref: vi.fn() };
      },
      isDescendant: (child, ancestor) => child === 9876 && ancestor === 4321,
      stateHome,
    });

    expect(result).toMatchObject({ type: "started", pid: 9876 });
    expect(
      JSON.parse(readFileSync(previewSessionPath(projectDir, stateHome), "utf8")),
    ).toMatchObject({ pid: 4321 });
  });

  it("reports the explicitly requested port when the detached child binds it", async () => {
    const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
    const dependencies = reachableChildDependencies(stateHome);

    const result = await startBackgroundPreview(projectDir, server.port, {
      ...dependencies,
      preferredPort: server.port,
    });

    expect(result).toMatchObject({ type: "started", port: server.port, pid: 9876 });
    expect(dependencies.kill).not.toHaveBeenCalled();
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(true);
  });

  it("reaps a detached child that could not bind the explicitly requested port", async () => {
    // The child scans upward from --port and lands on the next free port.
    const requestedPort = server.port - 1;
    const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
    const dependencies = reachableChildDependencies(stateHome);

    const launch = startBackgroundPreview(projectDir, requestedPort, {
      ...dependencies,
      preferredPort: requestedPort,
    });

    await expect(launch).rejects.toThrow(PreviewPortUnavailableError);
    await expect(launch).rejects.toMatchObject({ requestedPort, boundPort: server.port });
    // The wrapper PID is reaped, not the server's self-reported PID.
    expect(dependencies.kill).toHaveBeenCalledExactlyOnceWith(4321);
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
  });

  it("fails loudly when the reaped child keeps serving the substitute port", async () => {
    const requestedPort = server.port - 1;
    const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
    const dependencies = reachableChildDependencies(stateHome, { immortal: true });

    await expect(
      startBackgroundPreview(projectDir, requestedPort, {
        ...dependencies,
        preferredPort: requestedPort,
      }),
    ).rejects.toThrow(/did not stop after failing to bind port/);
    expect(dependencies.kill).toHaveBeenCalledExactlyOnceWith(4321);
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
  });

  it("two launches at once each keep the server their own child started", async () => {
    const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
    // A's server (3002) answers only after B's (3003) has appeared, and after A's pre-launch snapshot.
    const children: Record<number, ActiveServer & { after: number }> = {
      4321: { ...server, port: 3002, pid: "9876", after: 3 },
      5555: { ...server, port: 3003, pid: "7777", after: 0 },
    };
    const parent: Record<number, number> = { 9876: 4321, 7777: 5555 };
    const spawnedAt = new Map<number, number>();
    let scans = 0;
    let secondSpawned!: () => void;
    const secondUp = new Promise<void>((done) => (secondSpawned = done));
    const scan = async () => {
      scans++;
      return [...spawnedAt]
        .filter(([wrapper, at]) => scans - at > children[wrapper]!.after)
        .map(([wrapper]) => children[wrapper]!);
    };
    const launch = (wrapper: number, sleep: () => Promise<void>, preferredPort?: number) =>
      startBackgroundPreview(projectDir, 3002, {
        scan,
        spawn: () => {
          spawnedAt.set(wrapper, scans);
          if (wrapper === 5555) secondSpawned();
          return { pid: wrapper, unref: vi.fn() };
        },
        sleep,
        kill: vi.fn(),
        isDescendant: (child: number, ancestor: number) => parent[child] === ancestor,
        stateHome,
        preferredPort,
      });

    const first = launch(4321, () => secondUp, 3002);
    await vi.waitFor(() => expect(spawnedAt.has(4321)).toBe(true));
    const second = launch(5555, async () => {});

    await expect(first).resolves.toMatchObject({ type: "started", port: 3002, pid: 9876 });
    await expect(second).resolves.toMatchObject({ type: "started", port: 3003, pid: 7777 });
  });

  it("keeps the next free port when no explicit port was requested", async () => {
    const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
    const dependencies = reachableChildDependencies(stateHome);

    const result = await startBackgroundPreview(projectDir, server.port - 1, dependencies);

    expect(result).toMatchObject({ type: "started", port: server.port });
    expect(dependencies.kill).not.toHaveBeenCalled();
  });

  it("reuses the same-project server on the explicit port when several are running", async () => {
    const sibling = { ...server, port: server.port + 1, pid: "5555" };
    const spawn = vi.fn();

    const result = await startBackgroundPreview(projectDir, 3002, {
      scan: async () => [server, sibling],
      spawn,
      stateHome: mkdtempSync(join(tmpdir(), "hf-preview-state-")),
      preferredPort: sibling.port,
    });

    expect(result).toMatchObject({ type: "reused", port: sibling.port, pid: 5555 });
    expect(spawn).not.toHaveBeenCalled();
  });

  it("reuses the unmanaged sibling on the explicit port instead of rejecting against the owned server", async () => {
    const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
    const owned = { ...server, port: 3002 };
    const sibling = { ...server, port: 3003, pid: "5555" };
    writePreviewSession(
      { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },
      stateHome,
    );
    const spawn = vi.fn();
    const kill = vi.fn();

    const result = await startBackgroundPreview(projectDir, 3002, {
      kill,
      scan: async () => [owned, sibling],
      spawn,
      stateHome,
      preferredPort: sibling.port,
    });

    expect(result).toMatchObject({ type: "reused", port: sibling.port, pid: 5555 });
    expect(spawn).not.toHaveBeenCalled();
    expect(kill).not.toHaveBeenCalled();
  });

  it("lists every same-project server in the port-mismatch error, not just the reuse candidate", async () => {
    const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
    const owned = { ...server, port: 3002 };
    const sibling = { ...server, port: 3003, pid: "5555" };
    const foreign = {
      ...server,
      port: 3004,
      projectDir: resolve("/tmp/hyperframes-preview-lifecycle-other"),
      pid: "7777",
    };
    writePreviewSession(
      { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },
      stateHome,
    );
    const spawn = vi.fn();

    const failure = await startBackgroundPreview(projectDir, 3002, {
      scan: async () => [owned, sibling, foreign],
      spawn,
      stateHome,
      preferredPort: 3004,
    }).then(
      () => null,
      (error: unknown) => error,
    );

    expect(failure).toBeInstanceOf(PreviewServerPortMismatchError);
    expect(failure).toMatchObject({ requestedPort: 3004, ports: [3002, 3003] });
    expect((failure as Error).message).toContain("add --force-new or run --stop first");
    expect(spawn).not.toHaveBeenCalled();
  });

  it("reuses a same-project server on an explicit port outside the saved port's scan window", async () => {
    const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
    const owned = { ...server, port: 3002 };
    const farSibling = { ...server, port: 3500, pid: "5555" };
    writePreviewSession(
      { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },
      stateHome,
    );
    const spawn = vi.fn();
    const probe = vi.fn(async (port: number) => (port === farSibling.port ? farSibling : null));

    const result = await startBackgroundPreview(projectDir, farSibling.port, {
      scan: async () => [owned],
      probe,
      spawn,
      stateHome,
      preferredPort: farSibling.port,
    });

    expect(result).toMatchObject({ type: "reused", port: farSibling.port, pid: 5555 });
    expect(probe).toHaveBeenCalledExactlyOnceWith(farSibling.port);
    expect(spawn).not.toHaveBeenCalled();
  });

  it("replaces the owned server on the explicit port when the GPU policy changes", async () => {
    const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
    const owned = { ...server, port: 3002, browserGpuMode: "hardware" as const };
    const replacement = { ...server, port: 3002, pid: "5432", browserGpuMode: "software" as const };
    writePreviewSession(
      { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },
      stateHome,
    );
    let ownedRunning = true;
    let replacementRunning = false;
    const scan = vi.fn(async () => [
      ...(ownedRunning ? [owned] : []),
      ...(replacementRunning ? [replacement] : []),
    ]);
    const kill = vi.fn((pid: number) => {
      if (pid === 4321) ownedRunning = false;
    });
    const spawn = vi.fn(() => {
      replacementRunning = true;
      return { pid: 5432, unref: vi.fn() };
    });

    const result = await startBackgroundPreview(projectDir, 3002, {
      browserGpuMode: "software",
      kill,
      scan,
      sleep: async () => {},
      spawn,
      stateHome,
      preferredPort: 3002,
    });

    expect(kill).toHaveBeenCalledWith(4321);
    expect(spawn).toHaveBeenCalledOnce();
    expect(result).toMatchObject({ type: "started", port: 3002, pid: 5432 });
  });

  it("stops waiting when the detached child exits and reports its exit and log", async () => {
    const stateHome = tempDir("hf-preview-state-");
    const kill = vi.fn();
    const scan = vi.fn(async () => []);
    let onExit: ((code: number | null, signal: string | null) => void) | undefined;

    await expect(
      startBackgroundPreview(projectDir, 3002, {
        scan,
        spawn: (_command, _args, options) => {
          writeSync(
            options.stdio[1],
            "\u001b[?25hError: listen EPERM: operation not permitted 127.0.0.1:3002\n",
          );
          return { pid: 4321, unref: vi.fn(), once: (_event, listener) => (onExit = listener) };
        },
        sleep: async () => onExit?.(1, null),
        kill,
        stateHome,
      }),
    ).rejects.toThrow(/exited \(exit code 1\) before it was ready[\s\S]*\nError: listen EPERM/);

    expect(kill).not.toHaveBeenCalled();
    expect(scan.mock.calls.length).toBeLessThan(5);
  });

  it("reaps a detached child that never becomes reachable without recording ownership", async () => {
    const stateHome = tempDir("hf-preview-state-");
    const kill = vi.fn();

    await expect(
      startBackgroundPreview(projectDir, 3002, {
        scan: async () => [],
        spawn: () => ({ pid: 4321, unref: vi.fn() }),
        sleep: async () => {},
        kill,
        stateHome,
      }),
    ).rejects.toThrow(/did not become ready/i);

    expect(kill).toHaveBeenCalledOnce();
    expect(kill).toHaveBeenCalledWith(4321);
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
  });

  it("removes a stale session when no matching server or process survives", async () => {
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      { pid: 999_999, port: 3210, projectDir, logPath: "/tmp/missing.log" },
      stateHome,
    );

    await expectStaleSessionRemoved(stateHome);
  });

  it("removes stale session metadata when its PID is alive but no server proves ownership", async () => {
    const stateHome = tempDir("hf-preview-state-");
    savePreviewSession(stateHome);

    await expectStaleSessionRemoved(stateHome);
  });

  it("keeps a live preview's record when a single probe misses it", async () => {
    // A server whose event loop is briefly blocked (a Puppeteer thumbnail
    // capture will do it) answers nothing for a second or two. Retiring the
    // record on that destroys the wrapperIdentity that is the only PID-reuse
    // guard `--stop` has, and it never comes back.
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      { pid: 4321, wrapperIdentity: "posix:birth", port: 3210, projectDir, logPath: "/tmp/p.log" },
      stateHome,
    );

    const status = await readBackgroundPreviewStatus(projectDir, 3002, {
      scan: async () => [],
      identity: () => "posix:birth",
      isSignalable: () => true,
      stateHome,
    });

    expect(status).toBeNull();
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(true);
  });

  it("keeps a live preview's record when the identity lookup gives no answer", async () => {
    // `processIdentity` catches every failure into `null`, and on Windows and
    // macOS that failure is a subprocess timeout on a LIVE process — under the
    // same load that made the HTTP probe miss. Treating no-answer as
    // "recycled" destroyed the only PID-reuse guard `--stop` has.
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      { pid: 4321, wrapperIdentity: "posix:birth", port: 3210, projectDir, logPath: "/tmp/p.log" },
      stateHome,
    );

    const status = await readBackgroundPreviewStatus(projectDir, 3002, {
      scan: async () => [],
      identity: () => null,
      isSignalable: () => true,
      stateHome,
    });

    expect(status).toBeNull();
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(true);
  });

  it("retires the record when the PID cannot be signalled at all", async () => {
    // Gone is gone: no birth token needed, and no subprocess spawned for it.
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      { pid: 4321, wrapperIdentity: "posix:birth", port: 3210, projectDir, logPath: "/tmp/p.log" },
      stateHome,
    );
    const identity = vi.fn(() => "posix:birth");

    const status = await readBackgroundPreviewStatus(projectDir, 3002, {
      scan: async () => [],
      identity,
      isSignalable: () => false,
      stateHome,
    });

    expect(status).toBeNull();
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
    expect(identity).not.toHaveBeenCalled();
  });

  it("retires the record once the wrapper PID has been recycled", async () => {
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      { pid: 4321, wrapperIdentity: "posix:birth", port: 3210, projectDir, logPath: "/tmp/p.log" },
      stateHome,
    );

    const status = await readBackgroundPreviewStatus(projectDir, 3002, {
      scan: async () => [],
      identity: () => "posix:someone-else",
      isSignalable: () => true,
      stateHome,
    });

    expect(status).toBeNull();
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
  });

  it("never leaves a partial session record for a concurrent reader", () => {
    const stateHome = tempDir("hf-preview-state-");
    savePreviewSession(stateHome);
    const path = previewSessionPath(projectDir, stateHome);

    writePreviewSession({ pid: 55, port: 3211, projectDir, logPath: "/tmp/two.log" }, stateHome);

    // Written through a temp file and renamed, so a reader mid-write sees the
    // whole previous record rather than truncated JSON it would then delete.
    expect(JSON.parse(readFileSync(path, "utf8"))).toMatchObject({ pid: 55, port: 3211 });
    expect(
      readdirSync(join(stateHome, "hyperframes", "previews")).filter((n) => n.endsWith(".tmp")),
    ).toHaveLength(0);
  });

  it("uses the recorded custom port when status is called without repeating --port", async () => {
    const stateHome = tempDir("hf-preview-state-");
    savePreviewSession(stateHome);
    const scan = vi.fn(async () => [server]);

    const status = await readBackgroundPreviewStatus(projectDir, 3002, {
      scan,
      stateHome,
    });

    expect(status?.port).toBe(3210);
    expect(scan).toHaveBeenCalledWith(3210);
  });

  it("stops only the matching project server and waits until it is unreachable", async () => {
    let running = true;
    const scan = vi.fn(async () => (running ? [server] : []));
    const kill = vi.fn(() => {
      running = false;
    });

    const result = await stopBackgroundPreview(projectDir, 3002, {
      scan,
      kill,
      sleep: async () => {},
      stateHome: tempDir("hf-preview-state-"),
    });

    expect(result).toBe(true);
    expect(kill).toHaveBeenCalledWith(4321);
    expect(scan).toHaveBeenCalledTimes(2);
  });

  it("does not kill an unmatched saved PID that may have been reused", async () => {
    const stateHome = tempDir("hf-preview-state-");
    savePreviewSession(stateHome);
    const kill = vi.fn();

    const result = await stopBackgroundPreview(projectDir, 3002, {
      scan: async () => [],
      kill,
      stateHome,
    });

    expect(result).toBe(false);
    expect(kill).not.toHaveBeenCalled();
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
  });

  it("refuses to stop when the live server cannot prove its own PID", async () => {
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      { pid: 4321, port: 3210, projectDir, logPath: "/tmp/preview.log" },
      stateHome,
    );
    const scan = vi.fn(async () => [{ ...server, pid: null }]);
    const kill = vi.fn();

    await expect(
      stopBackgroundPreview(projectDir, 3002, {
        scan,
        kill,
        sleep: async () => {},
        stateHome,
      }),
    ).rejects.toThrow(/ownership/i);

    expect(kill).not.toHaveBeenCalled();
  });

  it("reaps the saved wrapper when the live server is proven to be its descendant", async () => {
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      {
        pid: 4321,
        wrapperIdentity: "wrapper-birth",
        port: 3210,
        projectDir,
        logPath: "/tmp/preview.log",
      },
      stateHome,
    );
    let running = true;
    const scan = vi.fn(async () => (running ? [{ ...server, pid: "9876" }] : []));
    const kill = vi.fn((pid: number) => {
      if (pid === 4321) running = false;
    });

    const result = await stopBackgroundPreview(projectDir, 3002, {
      scan,
      kill,
      isDescendant: (childPid, ancestorPid) => childPid === 9876 && ancestorPid === 4321,
      identity: (pid) => (pid === 4321 ? "wrapper-birth" : null),
      sleep: async () => {},
      stateHome,
    });

    expect(result).toBe(true);
    expect(kill.mock.calls).toEqual([[4321]]);
  });

  it("kills only the live server when the saved wrapper birth identity has changed", async () => {
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      {
        pid: 4321,
        wrapperIdentity: "original-wrapper-birth",
        port: 3210,
        projectDir,
        logPath: "/tmp/preview.log",
      },
      stateHome,
    );
    let running = true;
    const scan = vi.fn(async () => (running ? [{ ...server, pid: "9876" }] : []));
    const kill = vi.fn((pid: number) => {
      if (pid === 9876) running = false;
    });

    const result = await stopBackgroundPreview(projectDir, 3002, {
      scan,
      kill,
      isDescendant: () => true,
      identity: () => "reused-pid-birth",
      sleep: async () => {},
      stateHome,
    });

    expect(result).toBe(true);
    expect(kill.mock.calls).toEqual([[9876]]);
  });

  it("fails loudly when the server remains reachable after stop", async () => {
    const stateHome = tempDir("hf-preview-state-");
    writePreviewSession(
      { pid: 4321, port: 3210, projectDir, logPath: "/tmp/preview.log" },
      stateHome,
    );

    await expect(
      stopBackgroundPreview(projectDir, 3002, {
        scan: async () => [server],
        kill: vi.fn(),
        sleep: async () => {},
        stateHome,
      }),
    ).rejects.toThrow(/did not stop/i);
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(true);
  });

  it("verifies the owned port stopped even when another server serves the same project", async () => {
    const stateHome = tempDir("hf-preview-state-");
    const owned = { ...server, port: 41490 };
    const sibling = { ...server, port: 41491, pid: "8765" };
    writePreviewSession(
      { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },
      stateHome,
    );
    let ownedRunning = true;
    const scan = vi.fn(async () => [...(ownedRunning ? [owned] : []), sibling]);
    const kill = vi.fn((pid: number) => {
      if (pid === 4321) ownedRunning = false;
    });

    const stopped = await stopBackgroundPreview(projectDir, owned.port, {
      kill,
      scan,
      sleep: async () => {},
      stateHome,
    });

    expect(stopped).toBe(true);
    expect(kill).toHaveBeenCalledWith(4321);
    expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
  });
});