feat(ui): a Baselines page and a device's baseline

docs/internal/DESIGN.md

@@ -133,7 +133,7 @@ put together from them and draws nothing of its own that one of them already dra
 
 - **Sidebar.** The console's navigation, on the left of every signed-in page: the "SIMLOCK"
   wordmark (`--on-accent` on an `--accent` block), one link per page in a fixed order (Overview,
-  Inbox, then the **Operate** group: Fleet, Leases, Queue; then the **Observe** group:
+  Inbox, then the **Operate** group: Fleet, Leases, Queue, Baselines; then the **Observe** group:
   Activity, Usage; each group under its small label, hidden when collapsed), then at the bottom the connection as a status,
   "Signed in as <name>" (hidden when collapsed, where the Sign out tooltip reads "Sign out (<name>)"),
   **Sign out** (absent for a proxy person with no sign-out address) and the collapse button. A link is an icon and its label in `--text-muted`; the

docs/internal/adr/0061-every-virtual-device-is-a-copy-of-a-source-and-a-baseline-is-a-named-source.md

@@ -1,6 +1,6 @@
 # 0061. Every virtual device is a copy of a source, and a baseline is a named source
 
-- **Status:** Accepted — not yet implemented
+- **Status:** Accepted
 - **Date:** 2026-11-02
 - **Issue:** [#327](https://github.com/callstackincubator/simlock/issues/327) (request [#1049](https://github.com/callstackincubator/simlock/issues/1049), points 1 and 4)
 - **Supersedes:** nothing. Narrows [ADR 0001](0001-simlock-owned-device-roots.md)

docs/internal/adr/README.md

@@ -96,4 +96,4 @@ the status is stale.
 | [0058](0058-through-a-gateway-simlock-adb-and-simctl-send-stdin-only-with-stdin.md) | Through a gateway, `simlock adb` and `simlock simctl` send stdin only with `--stdin` | Accepted; narrows 0005 §19c |
 | [0059](0059-a-worker-with-real-drivers-holds-a-per-user-lock.md) | A worker with real drivers holds a per-user lock | Accepted; narrows 0034 §1 |
 | [0060](0060-ios-slim-writes-launchd-overrides-while-the-simulator-is-shut-down.md) | iOS slim writes launchd overrides while the simulator is shut down | Accepted; supersedes 0002 §2, §3, §5, §8, §9 |
-| [0061](0061-every-virtual-device-is-a-copy-of-a-source-and-a-baseline-is-a-named-source.md) | Every virtual device is a copy of a source, and a baseline is a named source | Accepted — not yet implemented; narrows 0001 §1, §3, §4, §5, §6, 0007 §6, 0009 §2, §4, §6, 0015 §6–7, 0038 §5 and 0060 §4 |
+| [0061](0061-every-virtual-device-is-a-copy-of-a-source-and-a-baseline-is-a-named-source.md) | Every virtual device is a copy of a source, and a baseline is a named source | Accepted; narrows 0001 §1, §3, §4, §5, §6, 0007 §6, 0009 §2, §4, §6, 0015 §6–7, 0038 §5 and 0060 §4 |

e2e/console/baselines.spec.ts

@@ -0,0 +1,185 @@
+import type { Locator, Page } from "@playwright/test";
+
+import { answer } from "./stub-answers.js";
+import {
+  disposeFleet,
+  expect,
+  type RunningDaemon,
+  signIn,
+  startDaemon,
+  startFleet,
+  test,
+} from "./fixtures.js";
+
+const IOS = { availableOsVersions: ["18.4"], knownModels: ["iPhone 16"] };
+const LEASE = ["lease", "--platform", "ios", "--device", "iPhone 16", "--os", "18.4"] as const;
+
+async function leaseId(daemon: RunningDaemon, agent: string, extra: readonly string[] = []) {
+  const granted = await daemon.cli([...LEASE, "--agent-id", agent, "--detach", ...extra]);
+  expect(granted.code, granted.stderr).toBe(0);
+  return (granted.json as { lease: { id: string } }).lease.id;
+}
+
+async function save(daemon: RunningDaemon, name: string, lease: string, note?: string) {
+  const args = ["baseline", "save", name, "--lease", lease];
+  const saved = await daemon.cli(note === undefined ? args : [...args, "--note", note]);
+  expect(saved.code, saved.stderr).toBe(0);
+}
+
+async function openBaselines(page: Page, daemon: RunningDaemon): Promise<void> {
+  await page.goto(new URL("/baselines", daemon.url).toString());
+  await signIn(page, daemon.tokens.operator);
+  await expect(page.getByRole("heading", { level: 1, name: "Baselines" })).toBeVisible();
+}
+
+function row(page: Page, name: string): Locator {
+  return page.locator("main tbody tr").filter({ hasText: name });
+}
+
+test.describe("the Baselines page", () => {
+  test("lists each baseline the worker holds, a save shows its row with no reload", async ({
+    page,
+  }) => {
+    const host = await startDaemon("worker", { driverScript: { ios: IOS } });
+    try {
+      const lease = await leaseId(host, "saver");
+      await openBaselines(page, host);
+      await expect(page.getByText("No baselines.")).toBeVisible();
+
+      await save(host, "checkout", lease, "app 4.2");
+
+      const checkout = row(page, "checkout");
+      await expect(checkout).toBeVisible();
+      await expect(checkout).toContainText("iOS");
+      await expect(checkout).toContainText("iPhone 16");
+      await expect(checkout).toContainText("18.4");
+      await expect(checkout).toContainText("app 4.2");
+      await expect(checkout).toContainText("1 MiB");
+      await expect(checkout).toContainText("ago");
+    } finally {
+      await host.dispose();
+    }
+  });
+
+  test("a second save shows version 2 in place, a lease naming the baseline shows it in the device's drawer, and a removal takes the row away with no reload", async ({
+    page,
+  }) => {
+    const host = await startDaemon("worker", { driverScript: { ios: IOS } });
+    try {
+      await save(host, "checkout", await leaseId(host, "first"), "app 4.2");
+      await openBaselines(page, host);
+      await expect(row(page, "checkout").getByRole("cell").nth(1)).toHaveText("1");
+
+      await save(host, "checkout", await leaseId(host, "second"));
+      await expect(row(page, "checkout").getByRole("cell").nth(1)).toHaveText("2");
+      await expect(page.locator("main tbody tr")).toHaveCount(1);
+
+      const copy = await leaseId(host, "copier", ["--baseline", "checkout"]);
+      const plain = await leaseId(host, "plain");
+      const view = await workers(host);
+      const onCopy = view.leases.find((held) => held.id === copy);
+      const onPlain = view.leases.find((held) => held.id === plain);
+      await openDrawer(page, host, view.id, onCopy?.deviceId ?? "");
+      await expect(fact(page, "Baseline")).toHaveText("checkout v2");
+      await openDrawer(page, host, view.id, onPlain?.deviceId ?? "");
+      await expect(page.getByRole("dialog").locator("dt", { hasText: "Runtime" })).toBeVisible();
+      await expect(page.getByRole("dialog").locator("dt", { hasText: "Baseline" })).toHaveCount(0);
+
+      await page.goto(new URL("/baselines", host.url).toString());
+      for (const id of [copy, plain]) {
+        const released = await host.cli(["release", id]);
+        expect(released.code, released.stderr).toBe(0);
+      }
+      const removed = await host.cli(["baseline", "remove", "checkout", "--yes"]);
+      expect(removed.code, removed.stderr).toBe(0);
+      await expect(page.getByText("No baselines.")).toBeVisible();
+    } finally {
+      await host.dispose();
+    }
+  });
+
+  test("on a gateway, the Worker column names each worker's baseline and a relayed save shows its row", async ({
+    page,
+  }) => {
+    const fleet = await startFleet([
+      { driverScript: { ios: IOS }, label: "worker-a" },
+      { driverScript: { ios: IOS }, label: "worker-b" },
+    ]);
+    try {
+      const [first, second] = fleet.workers as [RunningDaemon, RunningDaemon];
+      await openBaselines(page, fleet.gateway);
+
+      await save(first, "alpha", await leaseId(first, "a"));
+      await expect(page.getByRole("columnheader", { name: "Worker" })).toBeVisible();
+      await expect(row(page, "alpha")).toContainText("worker-a");
+      await save(second, "beta", await leaseId(second, "b"));
+      await expect(row(page, "beta")).toContainText("worker-b");
+      await expect(page.locator("main tbody tr")).toHaveCount(2);
+    } finally {
+      await disposeFleet(fleet);
+    }
+  });
+
+  test("a stale baseline shows the square, stale and its reason word for word, an entry with no size shows a dash, and 26 entries page at 25", async ({
+    page,
+  }) => {
+    const host = await startDaemon("worker", { driverScript: { ios: IOS } });
+    try {
+      const reason = "runtime com.apple.CoreSimulator.SimRuntime.iOS-27-0 is not installed";
+      const entries = Array.from({ length: 26 }, (_, index) => ({
+        mode: "full",
+        model: "iPhone 16",
+        name: `base-${String(index).padStart(2, "0")}`,
+        osVersion: "18.4",
+        platform: "ios",
+        savedAt: new Date(Date.now() - 3_600_000).toISOString(),
+        version: 1,
+        ...(index === 0 ? { staleReason: reason } : { sizeBytes: 2 ** 20 }),
+      }));
+      await answer(page, "/v1/baselines", () => ({ baselines: entries }));
+      await openBaselines(page, host);
+
+      await expect(page.locator("main tbody tr")).toHaveCount(25);
+      await expect(row(page, "base-25")).toHaveCount(0);
+      const stale = row(page, "base-00");
+      await expect(stale).toContainText(`stale · ${reason}`);
+      await expect(stale.locator(".status.status-warn")).toHaveText("stale");
+      await expect(stale).toContainText("—");
+      await page.getByRole("button", { name: "Next" }).click();
+      await expect(row(page, "base-25")).toBeVisible();
+    } finally {
+      await host.dispose();
+    }
+  });
+});
+
+interface WorkerFacts {
+  readonly id: string;
+  readonly leases: readonly { readonly id: string; readonly deviceId: string }[];
+}
+
+async function workers(daemon: RunningDaemon): Promise<WorkerFacts> {
+  const listed = await daemon.cli(["worker", "list", "--json"]);
+  expect(listed.code, listed.stderr).toBe(0);
+  const [view] = (listed.json as { workers: WorkerFacts[] }).workers;
+  if (view === undefined) throw new Error("no worker");
+  return view;
+}
+
+async function openDrawer(
+  page: Page,
+  daemon: RunningDaemon,
+  workerId: string,
+  deviceId: string,
+): Promise<void> {
+  const path = `/fleet/${encodeURIComponent(workerId)}/${encodeURIComponent(deviceId)}?tab=devices`;
+  await page.goto(new URL(path, daemon.url).toString());
+  await expect(page.getByRole("dialog")).toBeVisible();
+}
+
+function fact(scope: Page, label: string): Locator {
+  return scope
+    .getByRole("dialog")
+    .locator("dt", { hasText: label })
+    .locator("xpath=following-sibling::dd[1]");
+}

e2e/console/big-fleet.spec.ts

@@ -40,7 +40,7 @@ function isCounted(request: Request): boolean {
 }
 
 test.describe("big fleet", () => {
-  test("an idle console on a big fleet stays quiet: for each of the seven pages, in the 60 s after its first reads, at most 40 requests to /v1 other than the event stream", async ({
+  test("an idle console on a big fleet stays quiet: for each of the eight pages, in the 60 s after its first reads, at most 40 requests to /v1 other than the event stream", async ({
     gateway,
     page,
   }) => {

e2e/console/fixtures.ts

@@ -752,12 +752,13 @@ export const NAV = [
   { label: "Fleet", path: "/fleet" },
   { label: "Leases", path: "/leases" },
   { label: "Queue", path: "/queue" },
+  { label: "Baselines", path: "/baselines" },
   { label: "Activity", path: "/activity" },
   { label: "Usage", path: "/usage" },
 ] as const;
 
 export const NAV_GROUPS = [
-  { label: "Operate", links: ["Fleet", "Leases", "Queue"] },
+  { label: "Operate", links: ["Fleet", "Leases", "Queue", "Baselines"] },
   { label: "Observe", links: ["Activity", "Usage"] },
 ] as const;
 

e2e/console/shell.spec.ts

@@ -165,6 +165,7 @@ test.describe("the shell", () => {
       "Fleet /fleet",
       "Leases /leases",
       "Queue /queue",
+      "Baselines /baselines",
       "Activity /activity",
       "Usage /usage",
     ]);

e2e/helpers/env.test.ts

@@ -11,9 +11,13 @@ const execFileAsync = promisify(execFile);
 
 // why: teardown after a failure is seen only from a vitest run of its own. Its flows fail as the
 // slow-lane runs of #1102 did (a shared daemon's beforeAll, as warmUp; a per-test daemon's test)
-// and record each socket path, which the daemon's "Daemon started" log line names.
+// and record each socket path, which the daemon's "Daemon started" log line names. The shared
+// daemon's home is torn down twice, the second time over an empty daemon.log, as in a slow-lane
+// run whose suite teardown failed on an emulator still writing into the home and the file's
+// afterAll then tore it down again.
 const FAILING_FLOWS = `
-import { appendFile } from "node:fs/promises";
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { withDaemon, withSharedDaemon } from ${JSON.stringify(join(REPO_ROOT, "e2e/helpers/env.ts"))};
 
 const record = (env) => appendFile(process.env.FIXTURE_SOCKETS, env.socketPath + "\\n");
@@ -28,7 +32,10 @@ describe("a suite whose beforeAll fails, as warmUp does", () => {
     throw new Error("waitFor timed out (2 warm-up devices ready; last observed: shutdown,ready)");
   });
   afterAll(async () => {
-    await env?.teardown();
+    await env.teardown();
+    await mkdir(env.dataDirectory, { recursive: true });
+    await writeFile(join(env.dataDirectory, "daemon.log"), "");
+    await env.teardown();
   });
   it("never runs", () => {});
 });
@@ -52,7 +59,7 @@ async function filesUnder(directory: string): Promise<string[]> {
 }
 
 describe("withDaemon and withSharedDaemon teardown", () => {
-  it("after a run whose flows fail, leaves the log of each daemon it started in SIMLOCK_E2E_LOG_DIR", async () => {
+  it("after a run whose flows fail, leaves the log of each daemon it started in SIMLOCK_E2E_LOG_DIR, and a second teardown of the same home does not replace it", async () => {
     const work = await mkdtemp(join(tmpdir(), "simlock-e2e-kept-logs-"));
     try {
       const logDirectory = join(work, "daemon-logs");

e2e/helpers/env.ts

@@ -478,7 +478,9 @@ interface PidDiscoveryResult {
 
 /**
  * why: a failed run's daemon logs are the evidence of why it failed, and teardown deletes the
- * home they live in. A failed copy is swallowed so it never hides teardown's own error.
+ * home they live in. A failed copy is swallowed so it never hides teardown's own error. A copy
+ * already kept is never replaced: a teardown that runs again (the file's afterAll after a suite's
+ * failed one) finds only what was written into the home after the first, often an empty log.
  */
 async function keepDaemonLogs(dataDirectory: string, home: string): Promise<void> {
   const logDirectory = process.env.SIMLOCK_E2E_LOG_DIR;
@@ -487,7 +489,9 @@ async function keepDaemonLogs(dataDirectory: string, home: string): Promise<void
     const target = join(logDirectory, basename(home));
     await mkdir(target, { recursive: true });
     for (const name of await readdir(dataDirectory)) {
-      if (name.startsWith("daemon.log")) await cp(join(dataDirectory, name), join(target, name));
+      if (name.startsWith("daemon.log")) {
+        await cp(join(dataDirectory, name), join(target, name), { force: false });
+      }
     }
   } catch {
     // why: see above; the copy is best effort.
@@ -588,8 +592,9 @@ async function waitForDaemonSocketRemoval(
 ): Promise<unknown> {
   if (discovery.pids.length === 0 && discovery.error === undefined) return undefined;
   try {
+    // why: `daemon stop` answers when the stop starts; the daemon first settles the boot of the pool's next device and shuts idle devices down, which takes 15 s on a real simulator.
     await waitFor(() => !existsSync(socketPath), {
-      timeout: 5_000,
+      timeout: 60_000,
       label: "daemon socket removed during teardown",
     });
     return undefined;

e2e/slow-agent-device.test.ts

@@ -208,7 +208,8 @@ function defineSuite(target: Target): void {
     const released = await env.cli(["release", "--all", "--yes"], { timeout: 60_000 });
     expect(released.code, released.stderr).toBe(0);
     await waitForFree(env);
-  }, 300_000);
+    // why: longer than the cleanup (up to 100 s), the release (60 s) and waitForFree's own DEVICE_READY_MS together, so a device that never turns ready fails on waitForFree's label, which names what it last saw, instead of on a bare hook timeout.
+  }, DEVICE_READY_MS + 180_000);
 
   it(
     "an agent opens a device, installs the Appduct fixture app as an upload, opens it by its bundle id, takes a snapshot that shows tab-status, clicks tab-status, saves a PNG screenshot and closes; within 240 s the device is free",

e2e/slow-android-smoke.test.ts

@@ -312,8 +312,14 @@ describe.skipIf(!hasAndroidSdk)(
               { timeout: DEVICE_READY_MS },
             );
             expect(granted.code, `lease failed: ${granted.stderr}`).toBe(0);
-            return granted.json as { device: { driverDeviceId: string }; lease: { id: string } };
+            return granted.json as {
+              device: { address?: string; driverDeviceId: string };
+              lease: { id: string };
+            };
           };
+          // why: a worker's `simlock adb` has no lease to aim at (`--lease` is a gateway's), and its adb server lists every emulator, so each call names the lease's own serial.
+          const adbOn = (grant: { device: { address?: string } }, ...args: string[]) =>
+            env.cli(["adb", "-s", grant.device.address ?? "", ...args]);
 
           const [first, second] = await Promise.all([lease("seed-one"), lease("seed-two")]);
 
@@ -324,14 +330,7 @@ describe.skipIf(!hasAndroidSdk)(
           for (const grant of [first, second]) {
             expect(existsSync(join(root, grant.device.driverDeviceId, "simlock.avd"))).toBe(true);
           }
-          const touched = await env.cli([
-            "adb",
-            "--lease",
-            first.lease.id,
-            "shell",
-            "touch",
-            "/data/local/tmp/t2",
-          ]);
+          const touched = await adbOn(first, "shell", "touch", "/data/local/tmp/t2");
           expect(touched.code, touched.stderr).toBe(0);
 
           for (const grant of [first, second]) {
@@ -348,14 +347,7 @@ describe.skipIf(!hasAndroidSdk)(
           expect([first, second].map((grant) => grant.device.driverDeviceId)).not.toContain(
             third.device.driverDeviceId,
           );
-          const listed = await env.cli([
-            "adb",
-            "--lease",
-            third.lease.id,
-            "shell",
-            "ls",
-            "/data/local/tmp/t2",
-          ]);
+          const listed = await adbOn(third, "shell", "ls", "/data/local/tmp/t2");
           expect(listed.code, "the file written on the first lease is not on a later one").not.toBe(
             0,
           );

e2e/slow-android-tunnel.test.ts

@@ -608,11 +608,18 @@ describe.skipIf(!hasAndroidSdk)(
                   .filter((line) => line.startsWith(`${lease.serial} `))
                   .join("\n"),
               };
-              return devices.code === 0 && forward.code === 0;
+              // why: adb lists a killed emulator as `offline` for a few seconds, so the read ends when it is gone, not when adb first answers.
+              return (
+                devices.code === 0 &&
+                forward.code === 0 &&
+                left.devices === "" &&
+                left.forward === ""
+              );
             },
             {
               interval: 2_000,
-              label: "the worker's adb server answering after the emulator was deleted",
+              label: () =>
+                `the worker's adb server listing nothing of the lease's serial; last read ${JSON.stringify(left)}`,
               timeout: 120_000,
             },
           );