@arcote.tech/arc-cli 0.5.7 → 0.6.0

package/src/deploy/ansible.ts

@@ -1,4 +1,4 @@
-import { spawn } from "bun";
+import { spawn as nodeSpawn } from "node:child_process";
 import { mkdirSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
@@ -38,31 +38,34 @@ export async function runAnsible(inputs: AnsibleInputs): Promise<void> {
   ].join("\n");
   writeFileSync(join(workDir, "inventory.ini"), inventory);
 
-  const extraVars = [
-    `username=${inputs.target.user}`,
-    `ssh_port=${port}`,
-  ];
-  if (inputs.ansible?.extraAllowedIps?.length) {
-    extraVars.push(
-      `extra_allowed_ips=${JSON.stringify(inputs.ansible.extraAllowedIps)}`,
-    );
-  }
+  // JSON dict so ansible parses types correctly (key=value form makes empty
+  // arrays look like the string "[]" and trips recursive templating).
+  const extraVarsJson = JSON.stringify({
+    username: inputs.target.user,
+    ssh_port: port,
+    extra_allowed_ips: inputs.ansible?.extraAllowedIps ?? [],
+  });
 
-  const proc = spawn({
-    cmd: [
+  // Ansible aborts if its stdout/stderr fds have O_NONBLOCK set — which
+  // happens when our own process is invoked with non-blocking stdio (e.g.
+  // backgrounded by Claude harness, piped through tail). Solution: pipe
+  // stdio (always blocking, Node-managed) and forward chunks manually so the
+  // user still sees ansible output in real time.
+  const exit = await new Promise<number>((resolve, reject) => {
+    const proc = nodeSpawn(
       "ansible-playbook",
-      "-i",
-      "inventory.ini",
-      "site.yml",
-      "-e",
-      extraVars.join(" "),
-    ],
-    cwd: workDir,
-    stdout: "inherit",
-    stderr: "inherit",
-    env: { ...process.env, ANSIBLE_HOST_KEY_CHECKING: "False" },
+      ["-i", "inventory.ini", "site.yml", "-e", extraVarsJson],
+      {
+        cwd: workDir,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, ANSIBLE_HOST_KEY_CHECKING: "False" },
+      },
+    );
+    proc.stdout?.on("data", (chunk: Buffer) => process.stdout.write(chunk));
+    proc.stderr?.on("data", (chunk: Buffer) => process.stderr.write(chunk));
+    proc.on("error", reject);
+    proc.on("exit", (code) => resolve(code ?? 1));
   });
-  const exit = await proc.exited;
   if (exit !== 0) {
     throw new Error(`ansible-playbook failed (exit ${exit})`);
   }

package/src/deploy/bootstrap.ts

@@ -10,7 +10,7 @@ import { saveDeployConfig } from "./config";
 import { ok, log, err } from "../platform/shared";
 import { writeStateMarker, STATE_MARKER_PATH } from "./remote-state";
 import type { RemoteState } from "./remote-state";
-import { assertExec, scpUpload, waitForSsh } from "./ssh";
+import { assertExec, canSsh, scpUpload, waitForSsh } from "./ssh";
 
 // ---------------------------------------------------------------------------
 // Bootstrap orchestrator.
@@ -55,6 +55,7 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
       tf: cfg.provision.terraform,
       token,
       serverName: `arc-${Object.keys(cfg.envs)[0] ?? "host"}`,
+      workspaceDir: rootDir,
     });
     ok(`Server provisioned: ${tfOut.serverIp}`);
 
@@ -69,9 +70,11 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
 
   if (state.kind === "unreachable" || state.kind === "no-docker") {
     log("Running Ansible bootstrap (Docker + firewall + SSH hardening)...");
-    // On a freshly provisioned Hetzner VM, only root exists before the playbook
-    // creates the deploy user; re-use `asRoot: true` for that first shot.
-    const asRoot = state.kind === "unreachable";
+    // Run as root whenever the configured user can't SSH (covers both freshly
+    // provisioned VMs and second-attempt deploys after ansible failure).
+    const deployUserWorks =
+      state.kind === "no-docker" && (await canSsh(cfg.target));
+    const asRoot = !deployUserWorks;
     await runAnsible({
       target: cfg.target,
       ansible: cfg.provision?.ansible,
@@ -99,7 +102,10 @@ async function upStack(inputs: BootstrapInputs): Promise<void> {
   mkdirSync(workDir, { recursive: true });
 
   writeFileSync(join(workDir, "Caddyfile"), generateCaddyfile(cfg));
-  writeFileSync(join(workDir, "docker-compose.yml"), generateCompose({ cfg }));
+  writeFileSync(
+    join(workDir, "docker-compose.yml"),
+    generateCompose({ cfg, cliVersion: inputs.cliVersion }),
+  );
 
   // Ensure remoteDir exists
   await assertExec(

package/src/deploy/compose.ts

@@ -1,26 +1,34 @@
 import type { DeployConfig } from "./config";
 
 // ---------------------------------------------------------------------------
-// docker-compose.yml generator
+// docker-compose.yml generator — v0.6
 //
 // Services:
 //   - caddy (public 80/443, loopback 127.0.0.1:2019 for deploy tunnel)
-//   - arc-<env> per entry in deploy.arc.json envs (bind-mounts project dir)
+//   - arc-<env> per entry in deploy.arc.json envs
 //
-// No custom images: vanilla `caddy:2-alpine` and `oven/bun:1-alpine` from
-// Docker Hub. The Arc CLI and user's built artifacts come via the volume
-// mount at /opt/arc/<env>/ — rsynced by the deploy command.
+// arc-<env> uses `arcote/runtime:1` (generic image). CLI version is passed
+// via ARC_CLI_VERSION env var — entrypoint installs arc-cli on first boot,
+// then `arc platform start` decides between pre-deploy and full mode based
+// on volume state. No user code or node_modules on host disk (everything
+// lives in named volumes, populated via /api/deploy/* multipart pushes).
 // ---------------------------------------------------------------------------
 
 export interface ComposeOptions {
   cfg: DeployConfig;
+  /** CLI version used by entrypoint.sh to `bun add @arcote.tech/arc-cli@VER`. */
+  cliVersion: string;
 }
 
-export function generateCompose({ cfg }: ComposeOptions): string {
+const RESERVED_ENV = new Set(["PORT", "ARC_DEPLOY_API", "ARC_CLI_VERSION"]);
+
+export function generateCompose({ cfg, cliVersion }: ComposeOptions): string {
   const lines: string[] = [];
   lines.push("# Generated by `arc platform deploy` — do not edit by hand.");
   lines.push("");
   lines.push("services:");
+
+  // Caddy
   lines.push("  caddy:");
   lines.push("    image: caddy:2-alpine");
   lines.push("    restart: unless-stopped");
@@ -36,22 +44,28 @@ export function generateCompose({ cfg }: ComposeOptions): string {
   lines.push("      - arc-net");
   lines.push("");
 
+  // Per-env runtime containers
   for (const [name, env] of Object.entries(cfg.envs)) {
     lines.push(`  arc-${name}:`);
-    lines.push("    image: oven/bun:1-alpine");
+    lines.push("    image: pkrasinski/arc-runtime:1");
     lines.push("    restart: unless-stopped");
-    lines.push(`    working_dir: /app`);
     lines.push("    volumes:");
-    lines.push(`      - ${cfg.target.remoteDir}/${name}:/app`);
+    lines.push(`      - arc-platform-${name}:/app/.arc/platform`);
     lines.push(`      - arc-data-${name}:/app/.arc/data`);
+    lines.push("      - arc-cli-cache:/app/.arc/cli");
+    lines.push("      - arc-bun-cache:/root/.bun/install/cache");
     lines.push("    environment:");
     lines.push("      PORT: 5005");
-    lines.push("      ARC_DEPLOY_API: \"1\"");
-    lines.push("      NODE_ENV: production");
-    for (const [k, v] of Object.entries(env.envVars ?? {})) {
+    lines.push('      ARC_DEPLOY_API: "1"');
+    lines.push(`      ARC_CLI_VERSION: ${JSON.stringify(cliVersion)}`);
+    const userEnv = env.envVars ?? {};
+    if (!("NODE_ENV" in userEnv)) {
+      lines.push("      NODE_ENV: production");
+    }
+    for (const [k, v] of Object.entries(userEnv)) {
+      if (RESERVED_ENV.has(k)) continue;
       lines.push(`      ${k}: ${JSON.stringify(v)}`);
     }
-    lines.push("    command: [\"node_modules/.bin/arc\", \"platform\", \"start\"]");
     lines.push("    networks:");
     lines.push("      - arc-net");
     lines.push("    expose:");
@@ -59,13 +73,17 @@ export function generateCompose({ cfg }: ComposeOptions): string {
     lines.push("");
   }
 
+  // Networks + volumes
   lines.push("networks:");
   lines.push("  arc-net:");
   lines.push("");
   lines.push("volumes:");
   lines.push("  caddy_data:");
   lines.push("  caddy_config:");
+  lines.push("  arc-cli-cache:");
+  lines.push("  arc-bun-cache:");
   for (const [name] of Object.entries(cfg.envs)) {
+    lines.push(`  arc-platform-${name}:`);
     lines.push(`  arc-data-${name}:`);
   }
 

package/src/deploy/config.ts

@@ -96,10 +96,15 @@ export function loadDeployConfig(rootDir: string): DeployConfig {
 }
 
 export function saveDeployConfig(rootDir: string, cfg: DeployConfig): void {
-  writeFileSync(
-    deployConfigPath(rootDir),
-    JSON.stringify(cfg, null, 2) + "\n",
-  );
+  const path = deployConfigPath(rootDir);
+  // Re-read raw JSON so we preserve `${VAR}` placeholders and don't accidentally
+  // serialize expanded secrets back to disk. We only patch target (the only
+  // field bootstrap ever mutates — terraform-assigned host IP).
+  const raw = existsSync(path)
+    ? (JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>)
+    : {};
+  raw.target = { ...(raw.target as object | undefined), ...cfg.target };
+  writeFileSync(path, JSON.stringify(raw, null, 2) + "\n");
 }
 
 // ---------------------------------------------------------------------------

package/src/deploy/remote-state.ts

@@ -37,6 +37,13 @@ export async function detectRemoteState(
   }
 
   if (!(await canSsh(cfg.target))) {
+    // On a freshly provisioned VM, only root exists — ansible creates `deploy`
+    // later. If root SSH works but the configured user doesn't, treat as
+    // no-docker so bootstrap re-runs ansible (idempotent) instead of spinning
+    // up a duplicate server via terraform.
+    if (await canSsh({ ...cfg.target, user: "root" })) {
+      return { kind: "no-docker" };
+    }
     return { kind: "unreachable", reason: "ssh connection failed" };
   }
 

package/src/deploy/remote-sync.ts

@@ -1,27 +1,27 @@
-import { existsSync, readFileSync } from "fs";
-import { join, relative } from "path";
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { basename, join } from "path";
 import type { BuildManifest, ModuleDescriptor } from "@arcote.tech/platform";
 import type { DeployConfig } from "./config";
-import { openTunnel, rsyncDir, scpUpload } from "./ssh";
+import { assertExec, openTunnel } from "./ssh";
+import { isContextPackage } from "../builder/module-builder";
 import type { WorkspaceInfo } from "../platform/shared";
 
 // ---------------------------------------------------------------------------
-// Hot-swap logic.
+// v0.6 sync driver — API-only, per-module. No rsync of user code.
 //
 // Flow per env:
-//  1. rsync the whole project directory to /opt/arc/<env>/ so the running
-//     container's /app volume sees new code. (This is the authoritative
-//     source — node_modules, package.json, .arc/platform/ all live here.)
-//  2. Open an SSH tunnel to the Caddy loopback listener (127.0.0.1:2019).
-//  3. GET /env/<env>/api/deploy/manifest → remote BuildManifest.
-//  4. diffManifests(local, remote) → list of changed module files + shell/styles flags.
-//  5. POST each changed module (+ shell + styles) as multipart uploads.
-//  6. POST the new manifest to /api/deploy/manifest — server writes
-//     manifest.json and SSE-notifies clients to reimport.
-//
-// Because rsync in step 1 already moved the bytes, the POSTs are redundant
-// for disk writes — but they force the running server to pick up new hashes
-// and push an SSE event so connected browser clients reload without F5.
+//  1. Open SSH tunnel to Caddy 127.0.0.1:2019 (admin listener)
+//  2. GET /api/deploy/framework → remote framework depsHash
+//  3. If local hash differs → POST /api/deploy/framework (multipart
+//     package.json + bun.lock). Response needsRestart=true → close tunnel,
+//     `docker restart arc-${env}`, reopen tunnel, wait for /health.
+//  4. GET /api/deploy/manifest → remote manifest
+//  5. diffManifests → per-module list of changes
+//  6. For each changed module: POST /api/deploy/modules/<name>
+//     (browser.js + server.js? + package.json + access.json?)
+//  7. If styles changed: POST /api/deploy/styles
+//  8. POST /api/deploy/manifest (commit). Response needsRestart=true when
+//     any module had server.js change → second restart.
 // ---------------------------------------------------------------------------
 
 export interface SyncInputs {
@@ -34,9 +34,10 @@ export interface SyncInputs {
 
 export interface SyncOutcome {
   env: string;
+  frameworkChanged: boolean;
   changedModules: readonly string[];
-  shellChanged: boolean;
   stylesChanged: boolean;
+  restarts: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -45,7 +46,6 @@ export interface SyncOutcome {
 
 export interface ManifestDiff {
   changedModules: ModuleDescriptor[];
-  shellChanged: boolean;
   stylesChanged: boolean;
 }
 
@@ -59,7 +59,6 @@ export function diffManifests(
   );
   return {
     changedModules: [...changedModules],
-    shellChanged: local.shellHash !== remote.shellHash,
     stylesChanged: local.stylesHash !== remote.stylesHash,
   };
 }
@@ -69,15 +68,11 @@ export function diffManifests(
 // ---------------------------------------------------------------------------
 
 export async function syncEnv(inputs: SyncInputs): Promise<SyncOutcome> {
-  const { cfg, env, ws, projectDir } = inputs;
+  const { cfg, env, ws } = inputs;
   const envConfig = cfg.envs[env];
   if (!envConfig) throw new Error(`Unknown env: ${env}`);
 
-  // 1. Rsync the project to the host. Excludes dev-only dirs.
-  const remotePath = `${cfg.target.remoteDir}/${env}`;
-  await rsyncDir(cfg.target, projectDir, remotePath);
-
-  // 2. Read local manifest
+  // Local artifacts must exist (arc platform build was run)
   const localManifestPath = join(ws.modulesDir, "manifest.json");
   if (!existsSync(localManifestPath)) {
     throw new Error(
@@ -88,42 +83,139 @@ export async function syncEnv(inputs: SyncInputs): Promise<SyncOutcome> {
     readFileSync(localManifestPath, "utf-8"),
   ) as BuildManifest;
 
-  // 3. Open SSH tunnel to Caddy's loopback admin listener
-  const localPort = 15500 + hashEnvToOffset(env);
-  const tunnel = await openTunnel(cfg.target, localPort, "127.0.0.1", 2019);
+  // Map module name → workspace package (needed to decide if server.js exists)
+  const pkgByName = new Map(
+    ws.packages.map((p) => [p.name.includes("/") ? p.name.split("/").pop()! : p.name, p]),
+  );
+
+  let tunnel = await openTunnel(
+    cfg.target,
+    15500 + hashEnvToOffset(env),
+    "127.0.0.1",
+    2019,
+  );
+  let restarts = 0;
+  let frameworkChanged = false;
 
   try {
-    const base = `http://127.0.0.1:${localPort}/env/${env}`;
+    const base = () =>
+      `http://127.0.0.1:${tunnel.localPort}/env/${env}`;
 
-    // 4. Fetch remote manifest
-    const remoteManifestRes = await fetch(`${base}/api/deploy/manifest`);
-    if (!remoteManifestRes.ok) {
-      throw new Error(
-        `Failed to fetch remote manifest: ${remoteManifestRes.status}`,
+    // 1. Framework deps — diff and push if changed
+    const localFrameworkHash = readDepsHash(join(ws.arcDir, ".deps-hash"));
+    const remoteFwRes = await fetch(`${base()}/api/deploy/framework`);
+    const remoteFw = remoteFwRes.ok
+      ? ((await remoteFwRes.json()) as { depsHash: string | null })
+      : { depsHash: null };
+
+    if (localFrameworkHash && localFrameworkHash !== remoteFw.depsHash) {
+      console.log("[arc] Pushing framework deps...");
+      const form = new FormData();
+      form.append(
+        "package.json",
+        new Blob([readFileSync(join(ws.arcDir, "package.json"))]),
+        "package.json",
       );
+      const lockPath = join(ws.arcDir, "bun.lock");
+      if (existsSync(lockPath)) {
+        form.append(
+          "bun.lock",
+          new Blob([readFileSync(lockPath)]),
+          "bun.lock",
+        );
+      }
+      const res = await fetch(`${base()}/api/deploy/framework`, {
+        method: "POST",
+        body: form,
+      });
+      if (!res.ok) {
+        throw new Error(
+          `framework push failed: ${res.status} ${await res.text()}`,
+        );
+      }
+      frameworkChanged = true;
+      const result = (await res.json()) as { needsRestart?: boolean };
+      if (result.needsRestart) {
+        tunnel = await restartAndReopen(cfg, env, tunnel);
+        restarts += 1;
+      }
     }
-    const remoteManifest = (await remoteManifestRes.json()) as BuildManifest;
 
+    // 2. Remote manifest + diff
+    const remoteManifestRes = await fetch(`${base()}/api/deploy/manifest`);
+    const remoteManifest: BuildManifest = remoteManifestRes.ok
+      ? await remoteManifestRes.json()
+      : ({
+          modules: [],
+          shellHash: "",
+          stylesHash: "",
+          buildTime: "",
+        } satisfies BuildManifest);
     const diff = diffManifests(localManifest, remoteManifest);
 
-    // 5. Upload shell (if changed) — contains every file under .arc/platform/shell
-    if (diff.shellChanged) {
-      const shellFiles = collectFiles(ws.shellDir);
+    // 3. Per-module push
+    for (const mod of diff.changedModules) {
+      const safeName = sanitizeName(mod.name);
+      const moduleDir = join(ws.modulesDir, safeName);
+      const browserPath = join(moduleDir, "browser.js");
+      const serverPath = join(moduleDir, "server.js");
+      const pkgPath = join(moduleDir, "package.json");
+      const accessPath = join(moduleDir, "access.json");
+
+      // Fall back to legacy <name>.js path while module-builder still emits
+      // the flat layout. Same hash either way.
+      const browserActual = existsSync(browserPath)
+        ? browserPath
+        : join(ws.modulesDir, `${safeName}.js`);
+      if (!existsSync(browserActual)) {
+        throw new Error(`Missing browser bundle for module ${mod.name}`);
+      }
+
       const form = new FormData();
-      for (const absPath of shellFiles) {
-        const rel = relative(ws.shellDir, absPath);
-        form.append(rel, new Blob([readFileSync(absPath)]), rel);
+      form.append(
+        "browser.js",
+        new Blob([readFileSync(browserActual)]),
+        "browser.js",
+      );
+
+      const pkg = pkgByName.get(safeName);
+      if (pkg && isContextPackage(pkg.packageJson) && existsSync(serverPath)) {
+        form.append(
+          "server.js",
+          new Blob([readFileSync(serverPath)]),
+          "server.js",
+        );
       }
-      const res = await fetch(`${base}/api/deploy/shell`, {
+      if (existsSync(pkgPath)) {
+        form.append(
+          "package.json",
+          new Blob([readFileSync(pkgPath)]),
+          "package.json",
+        );
+      }
+      if (existsSync(accessPath)) {
+        form.append(
+          "access.json",
+          new Blob([readFileSync(accessPath)]),
+          "access.json",
+        );
+      }
+
+      console.log(`[arc] Pushing module ${safeName}...`);
+      const res = await fetch(`${base()}/api/deploy/modules/${safeName}`, {
         method: "POST",
         body: form,
       });
-      if (!res.ok)
-        throw new Error(`Shell upload failed: ${res.status} ${await res.text()}`);
+      if (!res.ok) {
+        throw new Error(
+          `module ${safeName} push failed: ${res.status} ${await res.text()}`,
+        );
+      }
     }
 
-    // 5b. Upload changed styles files alongside shell request if styles changed
+    // 4. Styles push
     if (diff.stylesChanged) {
+      console.log("[arc] Pushing styles...");
       const form = new FormData();
       for (const name of ["styles.css", "theme.css"] as const) {
         const p = join(ws.arcDir, name);
@@ -131,47 +223,40 @@ export async function syncEnv(inputs: SyncInputs): Promise<SyncOutcome> {
           form.append(name, new Blob([readFileSync(p)]), name);
         }
       }
-      const res = await fetch(`${base}/api/deploy/shell`, {
+      const res = await fetch(`${base()}/api/deploy/styles`, {
         method: "POST",
         body: form,
       });
-      if (!res.ok)
-        throw new Error(`Styles upload failed: ${res.status} ${await res.text()}`);
-    }
-
-    // 5c. Upload changed modules
-    if (diff.changedModules.length > 0) {
-      const form = new FormData();
-      for (const mod of diff.changedModules) {
-        const p = join(ws.modulesDir, mod.file);
-        form.append(mod.file, new Blob([readFileSync(p)]), mod.file);
-      }
-      const res = await fetch(`${base}/api/deploy/modules`, {
-        method: "POST",
-        body: form,
-      });
-      if (!res.ok)
+      if (!res.ok) {
         throw new Error(
-          `Modules upload failed: ${res.status} ${await res.text()}`,
+          `styles push failed: ${res.status} ${await res.text()}`,
         );
+      }
     }
 
-    // 6. Post the new manifest so the server flips getManifest() + SSE
-    const res = await fetch(`${base}/api/deploy/manifest`, {
+    // 5. Manifest commit
+    const commitRes = await fetch(`${base()}/api/deploy/manifest`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(localManifest),
     });
-    if (!res.ok)
+    if (!commitRes.ok) {
       throw new Error(
-        `Manifest update failed: ${res.status} ${await res.text()}`,
+        `manifest commit failed: ${commitRes.status} ${await commitRes.text()}`,
       );
+    }
+    const commit = (await commitRes.json()) as { needsRestart?: boolean };
+    if (commit.needsRestart) {
+      tunnel = await restartAndReopen(cfg, env, tunnel);
+      restarts += 1;
+    }
 
     return {
       env,
+      frameworkChanged,
       changedModules: diff.changedModules.map((m) => m.name),
-      shellChanged: diff.shellChanged,
       stylesChanged: diff.stylesChanged,
+      restarts,
     };
   } finally {
     tunnel.close();
@@ -182,16 +267,52 @@ export async function syncEnv(inputs: SyncInputs): Promise<SyncOutcome> {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function collectFiles(dir: string): string[] {
-  if (!existsSync(dir)) return [];
-  const { readdirSync } = require("fs") as typeof import("fs");
-  const out: string[] = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const p = join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...collectFiles(p));
-    else if (entry.isFile()) out.push(p);
+function readDepsHash(path: string): string | null {
+  if (!existsSync(path)) return null;
+  return readFileSync(path, "utf-8").trim() || null;
+}
+
+function sanitizeName(name: string): string {
+  // Strip package scope ("@ndt/auth" → "auth"); manifest already stores names
+  // this way, but be defensive.
+  return basename(name);
+}
+
+async function restartAndReopen(
+  cfg: DeployConfig,
+  env: string,
+  oldTunnel: { close: () => void; localPort: number },
+): Promise<{ close: () => void; localPort: number }> {
+  console.log(`[arc] Restarting arc-${env}...`);
+  oldTunnel.close();
+  await assertExec(cfg.target, `docker restart arc-${env}`);
+
+  const tunnel = await openTunnel(
+    cfg.target,
+    15500 + hashEnvToOffset(env),
+    "127.0.0.1",
+    2019,
+  );
+  await waitForHealthy(`http://127.0.0.1:${tunnel.localPort}/env/${env}`, 60_000);
+  return tunnel;
+}
+
+async function waitForHealthy(baseUrl: string, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastErr: unknown;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${baseUrl}/api/deploy/health`, {
+        signal: AbortSignal.timeout(2_000),
+      });
+      if (res.ok) return;
+      lastErr = `status ${res.status}`;
+    } catch (e) {
+      lastErr = e;
+    }
+    await new Promise((r) => setTimeout(r, 1_000));
   }
-  return out;
+  throw new Error(`Health check timeout: ${String(lastErr)}`);
 }
 
 /** Deterministic per-env tunnel port offset so parallel syncs don't collide. */