@lizard-build/cli 0.3.92 → 0.3.94

package/src/commands/up.ts

@@ -1,7 +1,8 @@
 import chalk from "chalk";
 import ora from "ora";
 import { Command } from "commander";
-import { execSync, spawn } from "child_process";
+import { execSync } from "child_process";
+import { createTarball } from "../lib/archive.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as readline from "node:readline";
@@ -290,34 +291,6 @@ function collectFilesManually(root: string, dir: string): string[] {
   return results;
 }
 
-function createTarball(files: string[], cwd: string): Promise<Uint8Array> {
-  return new Promise((resolve, reject) => {
-    const chunks: Uint8Array[] = [];
-    // `--null` makes tar read NUL-separated paths from stdin, matching what
-    // `git ls-files -z` writes. Newline-separated input would split filenames
-    // containing `\n` across multiple entries. Both bsdtar (macOS) and GNU
-    // tar accept `--null` before `-T -`.
-    const tar = spawn("tar", ["--null", "-czf", "-", "-T", "-"], { cwd });
-    tar.stdout.on("data", (c: Buffer) => chunks.push(c));
-    tar.stderr.on("data", () => {});
-    tar.on("close", (code: number) => {
-      if (code === 0) {
-        const total = chunks.reduce((n, c) => n + c.length, 0);
-        const out = new Uint8Array(total);
-        let off = 0;
-        for (const c of chunks) {
-          out.set(c, off);
-          off += c.length;
-        }
-        resolve(out);
-      } else {
-        reject(new Error(`tar exited ${code}`));
-      }
-    });
-    if (files.length > 0) tar.stdin.write(files.join("\0") + "\0");
-    tar.stdin.end();
-  });
-}
 
 function detectLocalPort(dir: string): number | undefined {
   for (const name of ["Dockerfile", "dockerfile", "Dockerfile.production"]) {
@@ -340,7 +313,7 @@ function prompt(question: string): Promise<string> {
   });
 }
 
-async function streamBuildLogs(appId: string, ciMode: boolean = false, knownBuildId?: string) {
+export async function streamBuildLogs(appId: string, ciMode: boolean = false, knownBuildId?: string) {
   // Prefer the buildId returned by the upload/redeploy response — polling
   // builds[0] races against a still-running previous build and can attach
   // to the wrong one.
@@ -372,12 +345,16 @@ async function streamBuildLogs(appId: string, ciMode: boolean = false, knownBuil
   // idle timeout, network blips). Reconnect until the build itself reports
   // a terminal status, with a hard cap so we don't loop forever.
   const deadline = Date.now() + 15 * 60 * 1000; // 15 min max
+  let buildFailed = false;
   while (Date.now() < deadline) {
     let dropped = false;
     try {
       await streamSSE(`/api/builds/${buildId}/logs`, (event, data) => {
         if (event === "done" || event === "error") {
-          if (event === "error") emitBuildError(data);
+          if (event === "error") {
+            buildFailed = true;
+            emitBuildError(data);
+          }
           else emitBuildDone();
           return false;
         }
@@ -392,6 +369,7 @@ async function streamBuildLogs(appId: string, ciMode: boolean = false, knownBuil
     // build state — terminal status means we stop reconnecting.
     try {
       const build = await api.get<{ status: string }>(`/api/builds/${buildId}`);
+      if (build.status === "failed") buildFailed = true;
       if (build.status === "done" || build.status === "failed") break;
     } catch {}
 
@@ -399,6 +377,10 @@ async function streamBuildLogs(appId: string, ciMode: boolean = false, knownBuil
     await sleep(2000);
   }
 
+  if (buildFailed) {
+    process.exitCode = 1;
+    return;
+  }
   if (ciMode) return;
 
   const app = await api.get<App>(`/api/apps/${appId}`);
@@ -415,6 +397,7 @@ async function streamBuildLogs(appId: string, ciMode: boolean = false, knownBuil
       success(`Deployed! ${app.domain ? chalk.cyan(`https://${app.domain}`) : ""}`);
     }
   } else if (app.status === "failed") {
+    process.exitCode = 1;
     if (isJSONMode()) {
       process.stdout.write(
         JSON.stringify({ event: "failed", status: "failed" }) + "\n",

package/src/lib/archive.ts

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+
+// macOS tar otherwise creates AppleDouble ._* entries from file metadata.
+export function createTarball(files: string[], cwd: string): Promise<Uint8Array> {
+  return new Promise((resolve, reject) => {
+    const chunks: Uint8Array[] = [];
+    // `--null` makes tar read NUL-separated paths from stdin, matching what
+    // `git ls-files -z` writes. Newline-separated input would split filenames
+    // containing `\n` across multiple entries. Both bsdtar (macOS) and GNU
+    // tar accept `--null` before `-T -`.
+    const tar = spawn("tar", ["--null", "-czf", "-", "-T", "-"], { cwd, env: { ...process.env, COPYFILE_DISABLE: "1" } });
+    tar.on("error", reject);
+    tar.stdin.on("error", reject);
+    tar.stdout.on("data", (c: Buffer) => chunks.push(c));
+    tar.stderr.on("data", () => {});
+    tar.on("close", (code: number) => {
+      if (code === 0) {
+        const total = chunks.reduce((n, c) => n + c.length, 0);
+        const out = new Uint8Array(total);
+        let off = 0;
+        for (const c of chunks) {
+          out.set(c, off);
+          off += c.length;
+        }
+        resolve(out);
+      } else {
+        reject(new Error(`tar exited ${code}`));
+      }
+    });
+    if (files.length > 0) tar.stdin.write(files.join("\0") + "\0");
+    tar.stdin.end();
+  });
+}
+

package/src/lib/updater.ts

@@ -5,7 +5,7 @@ import { join, dirname } from "node:path";
 import os from "node:os";
 import { spawn } from "node:child_process";
 
-export const CURRENT_VERSION = "0.3.92";
+export const CURRENT_VERSION = "0.3.94";
 const RELEASES_API = "https://api.github.com/repos/lizard-build/lizard-cli/releases/latest";
 const RELEASE_BASE = "https://github.com/lizard-build/lizard-cli/releases/latest/download";
 

package/src/lib/wait-ready.ts

@@ -0,0 +1,127 @@
+import { api } from "./api.js";
+
+export interface AppSnapshot {
+  status?: string;
+  deployStatus?: string | null;
+  restartedAt?: number | string | null;
+  domain?: string;
+}
+
+export interface WaitResult {
+  ok: boolean;
+  /** "running" on success; "failed" | "crashed" on a reported failure; "timeout" if the
+   *  wait ran out before a terminal state for this attempt was reached. */
+  status: string;
+  /** Identifies the specific restart/deploy attempt that was waited on (the app's
+   *  restartedAt value once it changed from the pre-trigger baseline) — an old,
+   *  already-`running` read from before the trigger is never mistaken for success. */
+  attemptId: number | string | null;
+  domain?: string;
+  waitedMs: number;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Two consecutive successful checks, spaced apart, against the app's own domain.
+ * A single 200 isn't enough during a restart handover — LIZARD-174's reproduction
+ * found one healthy response immediately followed by a 502 while the old process
+ * was still finishing its shutdown. Not run for apps with no domain (workers) —
+ * platform-reported readiness is the only signal available for those.
+ */
+async function debounceHealthCheck(domain: string): Promise<boolean> {
+  for (let i = 0; i < 2; i++) {
+    try {
+      const res = await fetch(`https://${domain}/`, { signal: AbortSignal.timeout(5000) });
+      if (res.status >= 500) return false;
+    } catch {
+      return false;
+    }
+    if (i === 0) await sleep(1500);
+  }
+  return true;
+}
+
+/**
+ * Waits for a *specific* restart/deploy attempt to become ready, distinguishing
+ * it from the app simply already being `running` from before the attempt was
+ * triggered — the exact gap LIZARD-174 reports: `lizard restart --json` returned
+ * as soon as the restart was accepted, and the very next request could still hit
+ * the outgoing old process (200) or a mid-handover 502/503.
+ *
+ * `baselineRestartedAt` must be captured from GET /api/apps/:id *before* the
+ * restart call is made — readiness is only trusted once `restartedAt` has moved
+ * past that baseline, so an unrelated, still-`running` read from the old attempt
+ * never short-circuits the wait. Pass `undefined` (not `null`) for callers whose
+ * trigger doesn't touch restartedAt at all (e.g. redeploy, which is tracked by
+ * its own buildId instead) — this skips the restartedAt gate entirely and trusts
+ * deployStatus/status transitions directly, since deployStatus is flipped to
+ * building/deploying synchronously by those triggers.
+ */
+export async function waitForAppReady(
+  id: string,
+  baselineRestartedAt: number | string | null | undefined,
+  opts: { timeoutMs?: number; healthCheck?: boolean } = {},
+): Promise<WaitResult> {
+  const timeoutMs = opts.timeoutMs ?? 120_000;
+  const healthCheck = opts.healthCheck ?? true;
+  const start = Date.now();
+
+  let attemptId: number | string | null = null;
+  let sawNewAttempt = baselineRestartedAt === undefined;
+
+  while (Date.now() - start < timeoutMs) {
+    let app: AppSnapshot;
+    try {
+      app = await api.get<AppSnapshot>(`/api/apps/${id}`);
+    } catch {
+      await sleep(1500);
+      continue;
+    }
+
+    if (!sawNewAttempt) {
+      const restartedAt = app.restartedAt ?? null;
+      if (restartedAt !== null && restartedAt !== baselineRestartedAt) {
+        sawNewAttempt = true;
+        attemptId = restartedAt;
+      } else {
+        // The platform hasn't picked up this attempt yet — deployStatus/status
+        // here still describe whatever was true *before* it was triggered.
+        // Reporting "running" at this point would be exactly the false
+        // positive this function exists to prevent.
+        await sleep(1000);
+        continue;
+      }
+    } else if (app.restartedAt != null && app.restartedAt !== attemptId) {
+      // A newer attempt interleaved (e.g. someone else restarted it again)
+      // — track that one instead; it's the one that will actually land.
+      attemptId = app.restartedAt;
+    }
+
+    if (app.deployStatus === "restarting" || app.deployStatus === "building" || app.deployStatus === "deploying") {
+      await sleep(1000);
+      continue;
+    }
+    if (app.status === "failed" || app.status === "crashed") {
+      return { ok: false, status: app.status, attemptId, domain: app.domain, waitedMs: Date.now() - start };
+    }
+    if (app.status === "running") {
+      if (healthCheck && app.domain) {
+        const healthy = await debounceHealthCheck(app.domain);
+        if (!healthy) {
+          // Platform says running, but the URL isn't consistently healthy yet
+          // (mid-handover) — keep polling rather than declaring success early.
+          await sleep(1500);
+          continue;
+        }
+      }
+      return { ok: true, status: "running", attemptId, domain: app.domain, waitedMs: Date.now() - start };
+    }
+
+    await sleep(1000);
+  }
+
+  return { ok: false, status: "timeout", attemptId, waitedMs: Date.now() - start };
+}

package/test/cli.test.ts

@@ -10,7 +10,8 @@
  *     mutate services (deploy, scale) are skipped so they can never touch
  *     an arbitrary real project picked from the account.
  *
- * Run: npm test
+ * Run: LIZARD_LIVE_TESTS=1 npm run test:integration
+ * Mutations also require LIZARD_TEST_PROJECT_ID and LIZARD_TEST_ALLOW_MUTATIONS=1.
  *
  * Flag-order rules (commander):
  *   - Global flags (--json, --token, --region) go BEFORE the subcommand.
@@ -39,7 +40,7 @@ import * as os from "node:os";
 // fall back to whatever `lizard` is on PATH. Resolve to absolute path so we
 // can run from any cwd (the e2e suite drops into /tmp for fixtures).
 function resolveLizard(): string[] {
-  const raw = process.env.LIZARD_BIN ?? "lizard";
+  const raw = process.env.LIZARD_BIN ?? "dist/index.js";
   if (raw.endsWith(".js")) {
     return [process.execPath, path.resolve(raw)];
   }
@@ -110,10 +111,15 @@ let projectId: string;
 
 // Tracks created app IDs for afterAll cleanup
 const createdApps: string[] = [];
+const allowMutations = process.env.LIZARD_TEST_ALLOW_MUTATIONS === "1"
+  && Boolean(process.env.LIZARD_TEST_PROJECT_ID);
 
 // ── Setup: resolve project ID ─────────────────────────────────────────────────
 
 beforeAll(async () => {
+  if (process.env.LIZARD_LIVE_TESTS !== "1") {
+    throw new Error("Live API tests require LIZARD_LIVE_TESTS=1. Run npm test for local unit tests.");
+  }
   // Explicit override wins (CI-friendly).
   if (process.env.LIZARD_TEST_PROJECT_ID) {
     projectId = process.env.LIZARD_TEST_PROJECT_ID;
@@ -205,7 +211,7 @@ describe("projects", () => {
 
 // ── Project-scope (global) secrets ────────────────────────────────────────────
 
-describe("project secrets", () => {
+describe.skipIf(!allowMutations)("project secrets", () => {
   const KEY = `CLI_TEST_GLOBAL_${Date.now()}`;
 
   // For listing we use the bare `secret` form (no `list` subcommand) — the
@@ -265,7 +271,7 @@ describe("ps (service inventory)", () => {
 // Mutates a real app (forces replicas=1) — only safe against a dedicated,
 // explicitly pinned test project.
 
-describe.skipIf(!process.env.LIZARD_TEST_PROJECT_ID)("scale", () => {
+describe.skipIf(!allowMutations)("scale", () => {
   test("scale --replicas succeeds when an app exists", async () => {
     const services = await cliJSON("ps", "--project", projectId);
     const apps: Array<{ id: string; name: string }> = services?.apps ?? [];
@@ -313,7 +319,7 @@ describe("domain", () => {
 let DEPLOY_DIR: string | undefined;
 
 describe.skipIf(
-  process.env.LIZARD_SKIP_DEPLOY === "1" || !process.env.LIZARD_TEST_PROJECT_ID,
+  process.env.LIZARD_SKIP_DEPLOY === "1" || !allowMutations,
 )("deploy", () => {
   const appName = `cli-test-${Date.now()}`;
   let appId: string;
@@ -476,6 +482,7 @@ describe("error handling", () => {
 // ── Cleanup ───────────────────────────────────────────────────────────────────
 
 afterAll(async () => {
+  if (!allowMutations || process.env.LIZARD_LIVE_TESTS !== "1") return;
   for (const id of createdApps) {
     await execa(LIZARD_CMD, [
       ...LIZARD_ARGS_PREFIX,

package/test/unit/archive.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { createTarball } from "../../src/lib/archive.js";
+
+describe("source upload archive", () => {
+  it("preserves source bytes and unusual names through extraction", async () => {
+    const root = mkdtempSync(join(tmpdir(), "lizard-archive-"));
+    const names = ["normal.ts", "space name.ts", "line\nbreak.ts", "-flag.ts"];
+    for (const name of names) writeFileSync(join(root, name), `source: ${name}`);
+    const archive = await createTarball(names, root);
+    const output = join(root, "output");
+    mkdirSync(output);
+    execFileSync("tar", ["-xzf", "-", "-C", output], { input: archive });
+    for (const name of names) expect(readFileSync(join(output, name), "utf8")).toBe(`source: ${name}`);
+  });
+
+  it.skipIf(process.platform !== "darwin")("omits AppleDouble entries for files with macOS metadata", async () => {
+    const root = mkdtempSync(join(tmpdir(), "lizard-archive-xattr-"));
+    writeFileSync(join(root, "route.ts"), "export default 42;");
+    execFileSync("xattr", ["-w", "com.lizard.docs-test", "metadata", join(root, "route.ts")]);
+    const archive = await createTarball(["route.ts"], root);
+    const listing = execFileSync("tar", ["-tzf", "-"], { input: archive, encoding: "utf8" });
+    expect(listing.trim().split("\n")).toEqual(["route.ts"]);
+  });
+});

package/test/unit/sandbox.test.ts

@@ -0,0 +1,38 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Command } from "commander";
+import { registerSandbox } from "../../src/commands/sandbox.js";
+import { api } from "../../src/lib/api.js";
+
+vi.mock("../../src/lib/api.js", () => ({ api: { post: vi.fn() } }));
+vi.mock("../../src/lib/resolve.js", () => ({
+  resolveProjectScope: vi.fn().mockResolvedValue({ projectId: "project-test", scope: { workspaceId: "workspace-test" } }),
+}));
+vi.mock("../../src/lib/format.js", () => ({ isJSONMode: () => true, printJSON: vi.fn() }));
+
+function create(args: string[]) {
+  const program = new Command().exitOverride();
+  registerSandbox(program);
+  return program.parseAsync(["sandbox", "create", ...args], { from: "user" });
+}
+
+describe("sandbox create timeout", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(api.post).mockResolvedValue({ id: "sandbox-test" });
+  });
+
+  it("sends the documented five-minute default to the API", async () => {
+    await create([]);
+    expect(api.post).toHaveBeenCalledWith("/api/sandboxes", expect.objectContaining({ timeoutMs: 300_000 }));
+  });
+
+  it.each([0, 1000, 120_000, 2_147_483_647])("preserves an explicit timeout of %i", async (timeoutMs) => {
+    await create(["--timeout", String(timeoutMs)]);
+    expect(api.post).toHaveBeenCalledWith("/api/sandboxes", expect.objectContaining({ timeoutMs }));
+  });
+
+  it.each(["-1", "1.5", "1000ms", "Infinity", "2147483648"])("rejects %s before making a request", async (value) => {
+    await expect(create(["--timeout", value])).rejects.toThrow(/Timeout must be/);
+    expect(api.post).not.toHaveBeenCalled();
+  });
+});

package/test/unit/up-build-status.test.ts

@@ -0,0 +1,46 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({ get: vi.fn(), stream: vi.fn() }));
+vi.mock("../../src/lib/api.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../src/lib/api.js")>();
+  return { ...actual, api: { ...actual.api, get: mocks.get }, streamSSE: mocks.stream };
+});
+import { streamBuildLogs } from "../../src/commands/up.js";
+import { setJSONMode } from "../../src/lib/format.js";
+
+describe("upload build result", () => {
+  let output: string;
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.exitCode = 0;
+    setJSONMode(true);
+    output = "";
+    vi.spyOn(process.stdout, "write").mockImplementation((chunk: any) => { output += chunk; return true; });
+  });
+  afterEach(() => { process.exitCode = 0; setJSONMode(false); vi.restoreAllMocks(); });
+
+  it.each([false, true])("returns failure after an SSE build error (CI=%s)", async (ci) => {
+    mocks.stream.mockImplementation(async (_url, receive) => { receive("error", '"failed"'); });
+    mocks.get.mockResolvedValue({ status: "failed" });
+    await streamBuildLogs("app", ci, "build");
+    expect(process.exitCode).toBe(1);
+    expect(output).not.toContain('"event":"deployed"');
+    expect(mocks.get).not.toHaveBeenCalledWith("/api/apps/app");
+  });
+
+  it("uses the failed build state even when an older app is still running", async () => {
+    mocks.stream.mockResolvedValue(undefined);
+    mocks.get.mockImplementation(async (url) => url === "/api/builds/build" ? { status: "failed" } : { status: "running" });
+    await streamBuildLogs("app", false, "build");
+    expect(process.exitCode).toBe(1);
+    expect(output).not.toContain("deployed");
+  });
+
+  it("keeps a successful build and running app successful", async () => {
+    mocks.stream.mockImplementation(async (_url, receive) => { receive("done", ""); });
+    mocks.get.mockImplementation(async (url) => url === "/api/builds/build" ? { status: "done" } : { status: "running", domain: "example.test" });
+    await streamBuildLogs("app", false, "build");
+    expect(process.exitCode).toBe(0);
+    expect(output).toContain('"event":"deployed"');
+  });
+});

package/test/unit/wait-ready.test.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import * as http from "node:http";
+import type { AddressInfo } from "node:net";
+import { setBaseURL, getBaseURL } from "../../src/lib/api.js";
+import { waitForAppReady } from "../../src/lib/wait-ready.js";
+
+type Handler = (req: http.IncomingMessage, res: http.ServerResponse) => void;
+
+let server: http.Server;
+let handle: Handler;
+const originalBaseURL = getBaseURL();
+
+beforeEach(async () => {
+  server = http.createServer((req, res) => handle(req, res));
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as AddressInfo;
+  setBaseURL(`http://127.0.0.1:${port}`);
+});
+
+afterEach(async () => {
+  setBaseURL(originalBaseURL);
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+});
+
+function json(res: http.ServerResponse, body: unknown) {
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+// A queue of app snapshots, one served per GET /api/apps/:id — the last entry
+// repeats once the queue is drained, so a test only has to describe the
+// interesting transitions.
+function serveSequence(snapshots: any[]) {
+  let i = 0;
+  handle = (_req, res) => {
+    const snap = snapshots[Math.min(i, snapshots.length - 1)];
+    i++;
+    json(res, snap);
+  };
+}
+
+describe("waitForAppReady", () => {
+  test("LIZARD-174: a stale already-running read from before the restart is not mistaken for success", async () => {
+    // First poll still reflects the OLD attempt (status running, restartedAt
+    // unchanged from baseline) — this is exactly the false positive the
+    // baseline-diff exists to prevent. Only once restartedAt actually moves
+    // and settles back to running should the wait resolve.
+    serveSequence([
+      { status: "running", deployStatus: "idle", restartedAt: 1000 }, // stale — must be ignored
+      { status: "running", deployStatus: "idle", restartedAt: 1000 }, // still stale
+      { status: "running", deployStatus: "restarting", restartedAt: 2000 }, // new attempt begins
+      { status: "running", deployStatus: "restarting", restartedAt: 2000 },
+      { status: "running", deployStatus: "idle", restartedAt: 2000 }, // new attempt ready
+    ]);
+
+    const result = await waitForAppReady("app1", 1000, { timeoutMs: 15_000, healthCheck: false });
+    expect(result.ok).toBe(true);
+    expect(result.status).toBe("running");
+    expect(result.attemptId).toBe(2000);
+  });
+
+  test("reports failure for the new attempt (Pending -> CrashLoopBackOff)", async () => {
+    serveSequence([
+      { status: "running", deployStatus: "idle", restartedAt: 1000 },
+      { status: "crashed", deployStatus: "restarting", restartedAt: 2000 },
+      { status: "crashed", deployStatus: "idle", restartedAt: 2000 },
+    ]);
+
+    const result = await waitForAppReady("app1", 1000, { timeoutMs: 15_000, healthCheck: false });
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe("crashed");
+    expect(result.attemptId).toBe(2000);
+  });
+
+  test("times out with a non-ok result if the new attempt never settles", async () => {
+    serveSequence([{ status: "running", deployStatus: "restarting", restartedAt: 2000 }]);
+
+    const result = await waitForAppReady("app1", 1000, { timeoutMs: 2500, healthCheck: false });
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe("timeout");
+  });
+
+  test("late start: keeps waiting through several restarting polls before success", async () => {
+    serveSequence([
+      { status: "running", deployStatus: "restarting", restartedAt: 2000 },
+      { status: "running", deployStatus: "restarting", restartedAt: 2000 },
+      { status: "running", deployStatus: "restarting", restartedAt: 2000 },
+      { status: "running", deployStatus: "restarting", restartedAt: 2000 },
+      { status: "running", deployStatus: "idle", restartedAt: 2000 },
+    ]);
+
+    const result = await waitForAppReady("app1", null, { timeoutMs: 15_000, healthCheck: false });
+    expect(result.ok).toBe(true);
+  });
+
+  test("undefined baseline (redeploy) trusts deployStatus/status directly, no restartedAt gate", async () => {
+    // redeploy never touches restartedAt — it stays null throughout, and that
+    // must not block success the way a real restart's stale baseline would.
+    serveSequence([
+      { status: "running", deployStatus: "deploying", restartedAt: null },
+      { status: "running", deployStatus: "idle", restartedAt: null },
+    ]);
+
+    const result = await waitForAppReady("app1", undefined, { timeoutMs: 15_000, healthCheck: false });
+    expect(result.ok).toBe(true);
+  });
+
+  test("health check debounce: a single 200 mid-handover does not count as ready", async () => {
+    serveSequence([{ status: "running", deployStatus: "idle", restartedAt: 2000, domain: "app.example.test" }]);
+
+    const realFetch = globalThis.fetch;
+    let call = 0;
+    vi.stubGlobal("fetch", (url: string, opts?: any) => {
+      if (typeof url === "string" && url.includes("app.example.test")) {
+        call++;
+        // First health check: healthy. Second (1.5s later, per the debounce):
+        // 502 — the exact LIZARD-174 reproduction (old process still finishing
+        // shutdown). Must not be reported as ready on the strength of check #1 alone.
+        return Promise.resolve(new Response(null, { status: call === 1 ? 200 : 502 }));
+      }
+      return realFetch(url, opts);
+    });
+
+    try {
+      const result = await waitForAppReady("app1", 1000, { timeoutMs: 4000, healthCheck: true });
+      expect(result.ok).toBe(false);
+      expect(result.status).toBe("timeout");
+      expect(call).toBeGreaterThanOrEqual(2);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});