percher 0.3.0 → 0.4.0

package/dist/bin/percher.js

@@ -10237,6 +10237,7 @@ function refineBunRuntime(detected, cwd) {
 }
 // ../core/dist/tarball.js
 var import_ignore = __toESM(require_ignore(), 1);
+import { createHash } from "node:crypto";
 import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, statSync } from "node:fs";
 import { join as join2, relative, sep } from "node:path";
 import { Readable } from "node:stream";
@@ -10287,18 +10288,29 @@ async function createTarball(options) {
   }
   if (options.extraIgnore)
     ig.add(options.extraIgnore);
-  const files = [];
+  const fileBuffers = [];
   for (const rel of walk(options.cwd, options.cwd, ig)) {
-    const stats = statSync(join2(options.cwd, rel));
-    files.push({ path: rel, size: stats.size });
+    const data = readFileSync2(join2(options.cwd, rel));
+    fileBuffers.push({ path: rel, size: data.length, data });
+  }
+  fileBuffers.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const totalBytes = fileBuffers.reduce((sum, f) => sum + f.size, 0);
+  const contentHasher = createHash("sha256");
+  for (const f of fileBuffers) {
+    contentHasher.update(`PATH:${f.path.length}:${f.path}
+`);
+    contentHasher.update(`SIZE:${f.size}
+`);
+    contentHasher.update(f.data);
+    contentHasher.update(`
+`);
   }
-  const totalBytes = files.reduce((sum, f) => sum + f.size, 0);
+  const contentHash = contentHasher.digest("hex");
   const pack = $pack();
   (async () => {
-    for (const file of files) {
-      const data = readFileSync2(join2(options.cwd, file.path));
+    for (const file of fileBuffers) {
       await new Promise((resolve, reject) => {
-        pack.entry({ name: file.path, size: data.length }, data, (err) => err ? reject(err) : resolve());
+        pack.entry({ name: file.path, size: file.data.length }, file.data, (err) => err ? reject(err) : resolve());
       });
     }
     pack.finalize();
@@ -10306,12 +10318,13 @@ async function createTarball(options) {
   const gzip = createGzip();
   const nodeStream = pack.pipe(gzip);
   const webStream = Readable.toWeb(nodeStream);
-  const topFiles = [...files].sort((a, b) => b.size - a.size).slice(0, 5);
+  const topFiles = [...fileBuffers].sort((a, b) => b.size - a.size).slice(0, 5).map((f) => ({ path: f.path, size: f.size }));
   return {
     stream: webStream,
     bytes: totalBytes,
-    fileCount: files.length,
-    topFiles
+    fileCount: fileBuffers.length,
+    topFiles,
+    contentHash
   };
 }
 // ../core/dist/env-scan-source.js
@@ -14652,10 +14665,160 @@ function readPercherTomlAppName(cwd) {
     return null;
   }
 }
+// ../core/dist/event-renderer.js
+function renderDeployEvent(event) {
+  if (event.stage === "queue") {
+    if (event.status === "started") {
+      return `Queued behind ${event.message ?? "other builds"} — your turn shortly`;
+    }
+    return null;
+  }
+  if (event.stage === "build")
+    return renderBuildEvent(event);
+  if (event.stage === "start") {
+    if (event.status === "started")
+      return "Starting container";
+    if (event.status === "ok")
+      return "Container started";
+    if (event.status === "failed")
+      return "Container failed to start";
+    return null;
+  }
+  if (event.stage === "health") {
+    if (event.status === "started")
+      return "Checking health";
+    if (event.status === "ok")
+      return "Health check passed";
+    if (event.status === "failed")
+      return "Health check failed";
+    return null;
+  }
+  if (event.stage === "swap") {
+    if (event.status === "ok")
+      return "Traffic swapped to new version";
+    if (event.status === "failed")
+      return "Traffic swap failed";
+    return null;
+  }
+  if (event.stage === "canary") {
+    if (event.status === "started")
+      return "Canary monitor running";
+    if (event.status === "ok")
+      return "Canary monitor passed";
+    if (event.status === "failed")
+      return "Canary failed — rolling back";
+    return null;
+  }
+  if (event.stage === "rollback") {
+    if (event.status === "ok")
+      return "Rolled back to previous version";
+    if (event.status === "failed")
+      return "Rollback failed";
+    return null;
+  }
+  return null;
+}
+function renderBuildEvent(event) {
+  if (event.subStage === "cache_hit" && event.status === "ok") {
+    return "Build cache hit (reused image)";
+  }
+  if (event.subStage === "deps_install" && event.status === "ok") {
+    return withDuration("Dependencies installed", event.durationMs);
+  }
+  if (event.subStage === "build_command" && event.status === "ok") {
+    return withDuration("Build command finished", event.durationMs);
+  }
+  if (event.subStage === "image_finalize" && event.status === "ok") {
+    return withDuration("Image built", event.durationMs);
+  }
+  if (event.subStage === "docker_layers" && event.status === "ok") {
+    return withDuration("Docker layers built", event.durationMs);
+  }
+  if (event.subStage !== null) {
+    if (event.status === "started")
+      return `${labelForSubStage(event.subStage)}…`;
+    if (event.status === "failed")
+      return `${labelForSubStage(event.subStage)} failed`;
+    return null;
+  }
+  if (event.status === "started")
+    return "Build started";
+  if (event.status === "failed")
+    return "Build failed";
+  return null;
+}
+function labelForSubStage(subStage) {
+  switch (subStage) {
+    case "deps_install":
+      return "Installing dependencies";
+    case "build_command":
+      return "Running build command";
+    case "image_finalize":
+      return "Finalizing image";
+    case "docker_layers":
+      return "Building Docker layers";
+    case "cache_hit":
+      return "Reusing cached image";
+  }
+}
+function withDuration(label, durationMs) {
+  if (durationMs === null || durationMs <= 0)
+    return label;
+  if (durationMs < 1000)
+    return `${label} (${durationMs}ms)`;
+  const seconds = (durationMs / 1000).toFixed(1);
+  return `${label} (${seconds}s)`;
+}
 // ../core/dist/commands/whoami.js
 async function whoami(ctx) {
   return ctx.client.auth.whoami();
 }
+// ../core/dist/commands/status.js
+var statusInputSchema = exports_external.object({
+  json: exports_external.boolean().optional()
+});
+async function status(ctx, _input = {}) {
+  let health;
+  try {
+    health = await ctx.client.platform.health();
+  } catch (err) {
+    return {
+      verdict: "unreachable",
+      summary: `API unreachable (${err.message})`,
+      health: null,
+      reachError: err.message
+    };
+  }
+  const verdict = deriveVerdict(health);
+  return {
+    verdict,
+    summary: summarize(verdict, health),
+    health
+  };
+}
+function deriveVerdict(health) {
+  if (health.status !== "ok")
+    return "worker-degraded";
+  if (health.worker?.circuitBreaker?.open)
+    return "worker-degraded";
+  if (health.worker?.health && health.worker.health.ok === false)
+    return "worker-degraded";
+  return "operational";
+}
+function summarize(verdict, health) {
+  if (verdict === "operational")
+    return "All systems operational";
+  const breaker = health.worker?.circuitBreaker;
+  const workerHealth = health.worker?.health;
+  if (breaker?.open) {
+    return `Worker circuit breaker open (${breaker.failuresInWindow}/${breaker.threshold} failures in last ${Math.round(breaker.windowMs / 1000)}s) — deploys will fail fast until it recovers`;
+  }
+  if (workerHealth && workerHealth.ok === false) {
+    const lastErr = workerHealth.lastErr ? ` — last error: ${workerHealth.lastErr}` : "";
+    return `Worker unreachable (${workerHealth.consecutiveErrs} consecutive failed health checks)${lastErr}`;
+  }
+  return "API responded but reported a non-ok status";
+}
 // ../core/dist/commands/account.js
 import { mkdir, writeFile } from "node:fs/promises";
 import { join as join4, resolve } from "node:path";
@@ -14882,9 +15045,13 @@ class Http {
     const ab = await res.arrayBuffer();
     return new Uint8Array(ab);
   }
-  async postBinary(path, body) {
+  async postBinary(path, body, extraHeaders) {
     const headers = this.buildHeaders();
     headers["Content-Type"] = "application/octet-stream";
+    if (extraHeaders) {
+      for (const [k, v] of Object.entries(extraHeaders))
+        headers[k] = v;
+    }
     const init = {
       method: "POST",
       headers,
@@ -14893,7 +15060,12 @@ class Http {
     if (body instanceof ReadableStream) {
       init.duplex = "half";
     }
-    const res = await this.fetchImpl(`${this.apiUrl}${path}`, init);
+    let res;
+    try {
+      res = await this.fetchImpl(`${this.apiUrl}${path}`, init);
+    } catch (err) {
+      throw new Error(`network error: ${err.message}`, { cause: err });
+    }
     if (!res.ok)
       throw await this.parseError(res);
     return await res.json();
@@ -15011,7 +15183,17 @@ class AppsResource {
     if (input.noCache)
       params.set("noCache", "1");
     const qs = params.toString();
-    return this.http.postBinary(`/apps/${encodeURIComponent(id)}/deploys${qs ? `?${qs}` : ""}`, input.tarball);
+    const headers = {};
+    if (input.idempotencyKey)
+      headers["Idempotency-Key"] = input.idempotencyKey;
+    if (input.traceId)
+      headers["X-Trace-Id"] = input.traceId;
+    if (input.tarballHash)
+      headers["X-Tarball-Hash"] = input.tarballHash;
+    if (typeof input.retriedAttempts === "number" && input.retriedAttempts > 0) {
+      headers["X-Publish-Attempts"] = String(input.retriedAttempts);
+    }
+    return this.http.postBinary(`/apps/${encodeURIComponent(id)}/deploys${qs ? `?${qs}` : ""}`, input.tarball, headers);
   }
   promotePreview(appRef, deployId) {
     return this.http.post(`/apps/${encodeURIComponent(appRef)}/deploys/${encodeURIComponent(deployId)}/promote`, {});
@@ -15355,6 +15537,23 @@ class LogsResource {
   }
 }
 
+// ../client/dist/resources/platform.js
+class PlatformResource {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  health() {
+    return this.http.get("/health");
+  }
+  preflight() {
+    return this.http.get("/publish/preflight");
+  }
+  cacheProbe(input) {
+    return this.http.post("/publish/cache-probe", input);
+  }
+}
+
 // ../client/dist/client.js
 class PercherClient {
   apiUrl;
@@ -15366,6 +15565,7 @@ class PercherClient {
   auth;
   billing;
   account;
+  platform;
   constructor(options = {}) {
     const defaults = loadConfig();
     this.apiUrl = options.apiUrl ?? defaults.apiUrl;
@@ -15383,6 +15583,7 @@ class PercherClient {
     this.auth = new AuthResource(http);
     this.billing = new BillingResource(http);
     this.account = new AccountResource(http);
+    this.platform = new PlatformResource(http);
   }
 }
 // ../client/dist/build-env-prefixes.js
@@ -15636,6 +15837,17 @@ var unsuspendInputSchema = exports_external.object({
 import { existsSync as existsSync6 } from "node:fs";
 import { join as join7 } from "node:path";
 
+// ../shared/dist/timeouts.js
+var TIMEOUTS = {
+  workerBuildSubprocess: 10 * 60000,
+  apiToWorkerBuildFetch: 11 * 60000,
+  clientPublishPoll: 12 * 60000,
+  workerHealthcheck: 5000,
+  watchdogList: 15000,
+  mcpWaitDeployDefault: 30000,
+  mcpWaitDeployMax: 12 * 60000
+};
+
 // ../core/dist/error-classifier.js
 function extractEnvVarsFromLog(combined) {
   const envVarPattern = /process\.env\.(\w+)\s*(?:is\s+)?(?:undefined|not set)|(?:missing|undefined).*?(\b[A-Z][A-Z0-9_]{2,}\b)/gi;
@@ -15666,7 +15878,7 @@ var patterns = [
     }
   },
   {
-    pattern: /Unable to connect.*?(access the url|cache\.nixos)|Could not resolve host|getaddrinfo ENOTFOUND|Worker \/[\w-]+(\/[\w-]+)? failed \(50\d\)|Failed to fetch.*?worker|deployer\/(run|build) failed|The socket connection was closed unexpectedly|WORKER_UNAVAILABLE:/i,
+    pattern: /Unable to connect.*?(access the url|cache\.nixos)|Could not resolve host|getaddrinfo ENOTFOUND|Worker \/[\w-]+(\/[\w-]+)? failed \(50\d\)|Failed to fetch.*?worker|deployer\/(run|build) failed|The socket connection was closed unexpectedly|WORKER_UNAVAILABLE(_PERSISTENT)?:/i,
     result: {
       title: "Build infrastructure unavailable",
       explanation: "The Percher build server couldn't reach an upstream service it needs (Nix cache, worker daemon, or registry). This is a platform-side problem, not your app code. These failures are usually transient and clear within 1–2 minutes.",
@@ -15907,10 +16119,14 @@ ${buildLog ?? ""}`;
 async function pollDeployment(opts) {
   const terminal = opts.terminal ?? ["live", "failed"];
   const intervalMs = opts.intervalMs ?? 2000;
-  const timeoutMs = opts.timeoutMs ?? 5 * 60 * 1000;
+  const timeoutMs = opts.timeoutMs ?? TIMEOUTS.clientPublishPoll;
   const maxRetries = opts.maxRetries ?? 5;
   let deployment = opts.initial;
   const startedAt = Date.now();
+  const seenEventIds = new Set;
+  if (opts.onEvent) {
+    await drainNewEvents(opts, deployment.id, seenEventIds);
+  }
   while (!terminal.includes(deployment.status)) {
     if (Date.now() - startedAt > timeoutMs) {
       opts.onTimeout(deployment);
@@ -15939,9 +16155,204 @@ The deploy may already be live — your network connection dropped mid-poll. Che
         await new Promise((r) => setTimeout(r, backoff));
       }
     }
+    if (opts.onEvent) {
+      await drainNewEvents(opts, deployment.id, seenEventIds);
+    }
   }
   return deployment;
 }
+async function drainNewEvents(opts, deployId, seenEventIds) {
+  if (!opts.onEvent)
+    return;
+  try {
+    const { events } = await opts.ctx.client.apps.getDeployEvents(opts.appId, deployId);
+    for (const event of events) {
+      if (seenEventIds.has(event.id))
+        continue;
+      seenEventIds.add(event.id);
+      opts.onEvent(event);
+    }
+  } catch {}
+}
+
+// ../core/dist/publish-retry.js
+var NON_RETRYABLE_CODES = new Set([
+  "WORKER_UNAVAILABLE_PERSISTENT",
+  "BUILD_FAILED",
+  "BUILD_TIMEOUT",
+  "DEPLOY_STALLED",
+  "REQUIRED_ENV_MISSING",
+  "ENV_KEY_UNDECLARED",
+  "DAILY_QUOTA_EXCEEDED",
+  "RETRY_LIMIT_REACHED",
+  "ACCOUNT_SUSPENDED",
+  "APP_SUSPENDED",
+  "EMAIL_NOT_VERIFIED",
+  "PREVIEW_LIMIT_REACHED",
+  "VALIDATION_ERROR",
+  "PLATFORM_DOWN"
+]);
+var WORKER_UNAVAILABLE_BACKOFF_MS = [5000, 15000, 45000];
+var NETWORK_BACKOFF_MS = [2000, 8000, 24000];
+var HTTP_5XX_BACKOFF_MS = [5000, 20000];
+function classifyDeployRetry(err, attempt) {
+  const idx = attempt - 1;
+  if (err instanceof PercherApiError) {
+    if (err.code === "WORKER_UNAVAILABLE_PERSISTENT") {
+      return {
+        retryable: false,
+        delayMs: 0,
+        reason: "platform circuit breaker open — surfacing as incident",
+        category: "persistent"
+      };
+    }
+    if (err.code === "WORKER_UNAVAILABLE") {
+      const delay = WORKER_UNAVAILABLE_BACKOFF_MS[idx];
+      if (delay === undefined) {
+        return {
+          retryable: false,
+          delayMs: 0,
+          reason: "worker unavailable after 3 attempts",
+          category: "worker_unavailable"
+        };
+      }
+      return {
+        retryable: true,
+        delayMs: delay,
+        reason: "worker was restarting",
+        category: "worker_unavailable"
+      };
+    }
+    if (err.code === "DEPLOY_RATE_LIMITED") {
+      if (idx >= 2) {
+        return {
+          retryable: false,
+          delayMs: 0,
+          reason: "rate-limited after 2 attempts",
+          category: "rate_limited"
+        };
+      }
+      const retryAfterSec = typeof err.extra?.retryAfterSec === "number" ? err.extra.retryAfterSec : 5;
+      return {
+        retryable: true,
+        delayMs: Math.min(60000, Math.max(1000, retryAfterSec * 1000)),
+        reason: "per-app rate limit",
+        category: "rate_limited"
+      };
+    }
+    if (err.code === "USER_CONCURRENT_LIMIT") {
+      if (idx >= 1) {
+        return {
+          retryable: false,
+          delayMs: 0,
+          reason: "concurrent-deploy cap still saturated after one wait",
+          category: "rate_limited"
+        };
+      }
+      const retryAfterSec = typeof err.extra?.retryAfterSec === "number" ? err.extra.retryAfterSec : 60;
+      return {
+        retryable: true,
+        delayMs: Math.min(2 * 60000, Math.max(5000, retryAfterSec * 1000)),
+        reason: "per-user concurrent-deploy cap",
+        category: "rate_limited"
+      };
+    }
+    if (err.code === "PLATFORM_OVERLOADED") {
+      if (idx >= 3) {
+        return {
+          retryable: false,
+          delayMs: 0,
+          reason: "platform overloaded after 3 attempts",
+          category: "rate_limited"
+        };
+      }
+      const retryAfterSec = typeof err.extra?.retryAfterSec === "number" ? err.extra.retryAfterSec : 30;
+      return {
+        retryable: true,
+        delayMs: Math.min(5 * 60000, Math.max(5000, retryAfterSec * 1000)),
+        reason: "platform overloaded — queue-depth backpressure",
+        category: "rate_limited"
+      };
+    }
+    if (NON_RETRYABLE_CODES.has(err.code)) {
+      return {
+        retryable: false,
+        delayMs: 0,
+        reason: `non-retryable: ${err.code}`,
+        category: "non_retryable"
+      };
+    }
+    if (err.status >= 500 && err.status < 600) {
+      const delay = HTTP_5XX_BACKOFF_MS[idx];
+      if (delay === undefined) {
+        return {
+          retryable: false,
+          delayMs: 0,
+          reason: `HTTP ${err.status} after 2 attempts`,
+          category: "http_5xx"
+        };
+      }
+      return {
+        retryable: true,
+        delayMs: delay,
+        reason: `HTTP ${err.status}`,
+        category: "http_5xx"
+      };
+    }
+    return {
+      retryable: false,
+      delayMs: 0,
+      reason: `HTTP ${err.status} ${err.code}`,
+      category: "non_retryable"
+    };
+  }
+  if (err instanceof Error && /network error|fetch failed|ECONNRESET|ENOTFOUND|ETIMEDOUT/i.test(err.message)) {
+    const delay = NETWORK_BACKOFF_MS[idx];
+    if (delay === undefined) {
+      return {
+        retryable: false,
+        delayMs: 0,
+        reason: "network error after 3 attempts",
+        category: "network"
+      };
+    }
+    return {
+      retryable: true,
+      delayMs: delay,
+      reason: "network blip",
+      category: "network"
+    };
+  }
+  return {
+    retryable: false,
+    delayMs: 0,
+    reason: "unknown error",
+    category: "non_retryable"
+  };
+}
+var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function runDeployWithRetry(opts) {
+  const max = opts.maxAttempts ?? 4;
+  const sleep = opts.sleep ?? defaultSleep;
+  let attempt = 0;
+  let lastErr;
+  while (attempt < max) {
+    attempt += 1;
+    try {
+      const result = await opts.call(attempt);
+      return { result, attempts: attempt };
+    } catch (err) {
+      lastErr = err;
+      const decision = classifyDeployRetry(err, attempt);
+      if (!decision.retryable || attempt >= max) {
+        throw err;
+      }
+      opts.onRetry?.({ attempt, decision, err });
+      await sleep(decision.delayMs);
+    }
+  }
+  throw lastErr;
+}
 
 // ../core/dist/recovery.js
 function recoveryNone(opts = {}) {
@@ -15969,7 +16380,7 @@ function recoveryWait(opts) {
     args: {
       app: opts.app,
       deployId: opts.deployId,
-      timeoutSeconds: opts.timeoutSeconds ?? 30
+      timeoutSeconds: opts.timeoutSeconds ?? TIMEOUTS.mcpWaitDeployDefault / 1000
     },
     reasonCode: opts.reasonCode
   };
@@ -16299,12 +16710,21 @@ async function push(ctx, input = {}, internals = {}) {
     }
   }
   ctx.status("Uploading...");
+  const tarballBytes = new Uint8Array(await new Response(tarball.stream).arrayBuffer());
+  const idempotencyKey = crypto.randomUUID();
   let initialDeployment;
   try {
-    const deployResponse = await ctx.client.apps.deploy(app.id, {
-      tarball: tarball.stream,
-      type: input.preview ? "preview" : undefined,
-      noCache: input.noCache
+    const { result: deployResponse } = await runDeployWithRetry({
+      call: (attempt) => ctx.client.apps.deploy(app.id, {
+        tarball: tarballBytes,
+        type: input.preview ? "preview" : undefined,
+        noCache: input.noCache,
+        idempotencyKey,
+        retriedAttempts: attempt - 1
+      }),
+      onRetry: ({ attempt, decision }) => {
+        ctx.status(`Retrying after ${Math.round(decision.delayMs / 1000)}s — ${decision.reason} (attempt ${attempt + 1}/4)…`);
+      }
     });
     if (isDeployAlreadyInProgress(deployResponse)) {
       throw new PercherCoreError(`${app.name} already has a deploy in progress (${deployResponse.deployId}, ${deployResponse.deployStatus}).`, {
@@ -16386,7 +16806,7 @@ async function push(ctx, input = {}, internals = {}) {
     throw err;
   }
   const pollInterval = internals.pollIntervalMs ?? 2000;
-  const timeoutMs = internals.timeoutMs ?? 5 * 60 * 1000;
+  const timeoutMs = internals.timeoutMs ?? TIMEOUTS.clientPublishPoll;
   const startedAt = Date.now();
   const deployment = await pollDeployment({
     ctx,
@@ -16541,6 +16961,82 @@ function* walkDir(dir, base) {
 
 // ../core/dist/commands/publish-failure.js
 import { join as join9 } from "node:path";
+
+// ../core/dist/structured-error-codes.js
+var MAPPINGS = {
+  WORKER_UNAVAILABLE: {
+    errorClass: "infra_unavailable",
+    phase: "infra",
+    cause: "worker_fetch_failed",
+    title: "Build worker is unreachable",
+    explanation: (raw) => raw ? `The Percher build worker did not respond in time: ${trimMessage(raw)}. This is a platform-side issue, not your code.` : "The Percher build worker did not respond in time. This is a platform-side issue, not your code.",
+    suggestion: "Wait 30 seconds and run `percher publish` again. If retry #2 also fails, pause 5 minutes before the next attempt — back-to-back retries during a partial outage just waste your time. After 3 spaced-out retries, check status.percher.app or contact support. Your build never started."
+  },
+  WORKER_UNAVAILABLE_PERSISTENT: {
+    errorClass: "infra_unavailable",
+    phase: "infra",
+    cause: "worker_circuit_breaker_open",
+    title: "Build worker is in a crash loop",
+    explanation: () => "The Percher build worker has failed repeatedly in the last minute and the platform's circuit breaker has flipped open. Retrying immediately would just queue more failures.",
+    suggestion: "Wait 2-3 minutes for the platform to recover, then retry. If it persists past 5 minutes check status.percher.app or contact support — this is a platform incident, not your code."
+  },
+  BUILD_TIMEOUT: {
+    errorClass: "build_failed",
+    phase: "build",
+    cause: "build_timeout",
+    title: "Build timed out",
+    explanation: () => "The build ran longer than the 10-minute platform limit and was aborted.",
+    suggestion: "Common causes: a slow `postinstall` hook, very large dependency tree, or a Dockerfile that pulls a huge base image. Try `bun install` locally and check what's slow. If it's legitimately a heavy build, contact support to discuss raising the limit for your account."
+  },
+  BUILD_FAILED: {
+    errorClass: "build_failed",
+    phase: "build",
+    cause: "build_nonzero_exit",
+    title: "Build failed",
+    explanation: (raw) => raw ? `The build process returned a non-zero exit code: ${trimMessage(raw)}. Read the build log below for the exact error.` : "The build process returned a non-zero exit code. Read the build log below for the exact error.",
+    suggestion: "Run your build locally to reproduce: `bun install && bun run build`. The error in the build log usually points to a missing dependency, a TypeScript/syntax error, or a misconfigured framework setting."
+  },
+  WORKER_ERROR: {
+    errorClass: "infra_unavailable",
+    phase: "infra",
+    cause: "worker_internal_error",
+    title: "Platform error inside the build worker",
+    explanation: (raw) => raw ? `The build worker hit an internal error: ${trimMessage(raw)}. This is a Percher bug, not your code.` : "The build worker hit an internal error. This is a Percher bug, not your code.",
+    suggestion: "Retry once — transient platform errors usually clear within a minute. If it repeats, please report it: include the deploy ID and we'll investigate. Your account is not at fault."
+  },
+  DEPLOY_STALLED: {
+    errorClass: "infra_unavailable",
+    phase: "infra",
+    cause: "deploy_stalled",
+    title: "Deploy stalled",
+    explanation: () => "The platform abandoned this deploy — likely because the API or build worker restarted mid-build. Your code is fine; the build never finished.",
+    suggestion: "Run `percher publish` again. The new deploy will start fresh. If you see this repeatedly across multiple publishes, check status.percher.app — it implies a recurring platform issue."
+  }
+};
+function classifyByErrorCode(code, rawMessage) {
+  if (!code)
+    return null;
+  const mapping = MAPPINGS[code];
+  if (!mapping)
+    return null;
+  return {
+    title: mapping.title,
+    explanation: mapping.explanation(rawMessage),
+    suggestion: mapping.suggestion,
+    errorClass: mapping.errorClass,
+    phase: mapping.phase,
+    cause: mapping.cause,
+    relevantFiles: [],
+    missingEnvVars: []
+  };
+}
+function trimMessage(raw) {
+  const firstLine = raw.split(`
+`)[0] ?? "";
+  return firstLine.length > 200 ? `${firstLine.slice(0, 200)}…` : firstLine;
+}
+
+// ../core/dist/commands/publish-failure.js
 function tomlPathFor(cwd) {
   return join9(cwd, "percher.toml");
 }
@@ -16564,7 +17060,7 @@ async function buildFailureError(ctx, app, deployment) {
     buildLogFetchFailed = true;
   }
   const errorMessage = deployment.errorMessage ?? "";
-  const classified = classifyError("Deployment failed", fullLog) ?? classifyError(errorMessage, "");
+  const classified = classifyByErrorCode(deployment.errorCode, errorMessage) ?? classifyError("Deployment failed", fullLog) ?? classifyError(errorMessage, "");
   const rawErrorMessage = errorMessage && !buildLogTail && !classified?.explanation.includes(errorMessage) ? errorMessage : undefined;
   const problems = deployment.problems && deployment.problems.length > 0 ? deployment.problems : undefined;
   if (classified) {
@@ -16640,6 +17136,12 @@ async function buildFailureResult(opts) {
 // ../core/dist/commands/publish-node.js
 import { existsSync as existsSync7, readFileSync as readFileSync6 } from "node:fs";
 import { join as join10 } from "node:path";
+
+// ../shared/dist/runtime.js
+var DEFAULT_NODE_VERSION_MAJOR = "24";
+var DEFAULT_NODE_VERSION_LABEL = `${DEFAULT_NODE_VERSION_MAJOR} LTS`;
+
+// ../core/dist/commands/publish-node.js
 function resolveNodeVersion(cwd) {
   const nvmrc = join10(cwd, ".nvmrc");
   if (existsSync7(nvmrc)) {
@@ -16659,14 +17161,14 @@ function resolveNodeVersion(cwd) {
       return { value: engines, source: "engines.node" };
     }
   } catch {}
-  return { value: "22 LTS", source: "default" };
+  return { value: DEFAULT_NODE_VERSION_LABEL, source: "default" };
 }
 
 // ../core/dist/commands/wait-deploy.js
 var waitForDeployInputSchema = exports_external.object({
   app: exports_external.string().describe("App name (the value of [app].name in percher.toml)"),
   deployId: exports_external.string().describe("Deploy id returned by percher_publish (e.g. dep_abc123)"),
-  timeoutSeconds: exports_external.number().int().min(1).max(120).optional().describe("Maximum wall-clock seconds to wait before returning still_running (default 30, max 120). Keeping this short is the point — the agent can resume in another short call without holding a long-lived connection."),
+  timeoutSeconds: exports_external.number().int().min(1).max(TIMEOUTS.mcpWaitDeployMax / 1000).optional().describe(`Maximum wall-clock seconds to wait before returning still_running (default ${TIMEOUTS.mcpWaitDeployDefault / 1000}, max ${TIMEOUTS.mcpWaitDeployMax / 1000}). Keeping this short is the point — the agent can resume in another short call without holding a long-lived connection.`),
   pollIntervalSeconds: exports_external.number().int().min(1).max(30).optional().describe("Seconds between polls (default 2).")
 });
 async function resolveReplaced(opts) {
@@ -16932,121 +17434,185 @@ ${keyList}
   Fix: bunx percher env set KEY=value
   (Re-run with --force to suppress this check.)`);
   }
-  const uploadStart = Date.now();
-  ctx.status("[3/4] Uploading...");
-  let deployment;
   try {
-    const deployResponse = await ctx.client.apps.deploy(app.id, {
-      tarball: tarball.stream,
-      type: input.preview ? "preview" : undefined,
-      note: input.message,
-      noCache: input.noCache
-    });
-    if (isDeployAlreadyInProgress(deployResponse)) {
-      return buildAlreadyInProgressResult({
-        active: deployResponse,
-        app,
-        tarball: { fileCount: tarball.fileCount, bytes: tarball.bytes },
-        cwd: ctx.cwd
-      });
-    }
-    deployment = deployResponse;
-  } catch (err) {
-    if (err instanceof PercherApiError && err.code === "RETRY_LIMIT_REACHED") {
-      return buildRetryLimitReachedResult({
-        err,
-        app,
-        tarball: { fileCount: tarball.fileCount, bytes: tarball.bytes },
-        cwd: ctx.cwd
-      });
-    }
-    if (err instanceof PercherApiError && err.code === "REQUIRED_ENV_MISSING") {
-      const extra = err.extra ?? {};
-      const keys = extra.keys ?? [];
-      const source = extra.source ?? "contract";
-      const sourceText = source === "contract" ? "declared in your [env].required" : source === "discovered" ? "learned from a previous build failure" : "both declared and learned from a previous build failure";
+    const preflight = await ctx.client.platform.preflight();
+    if (!preflight.accept) {
+      const reasonText = preflight.reason === "worker_circuit_breaker_open" ? "platform circuit breaker is open — workers are restarting" : preflight.reason === "worker_unhealthy" ? "build worker is currently unreachable" : "platform is currently unavailable";
       return {
         status: "failed",
         app,
         fileCount: tarball.fileCount,
         bytes: tarball.bytes,
         error: {
-          title: "Required env keys not set",
-          explanation: `${keys.length} env ${keys.length === 1 ? "key is" : "keys are"} ${sourceText} but missing from the env store: ${keys.join(", ")}.`,
-          suggestion: `Run \`bunx percher env set ${keys[0] ?? "KEY"}=value\` (and similarly for the rest) and re-publish.`,
-          errorClass: "missing_env",
-          phase: "config",
-          missingEnvVars: keys
+          title: "Platform unavailable",
+          explanation: `Preflight refused the upload: ${reasonText}.`,
+          suggestion: "Wait ~30s and retry — the platform self-heals automatically and the auto-retry loop will pick it up on the next attempt.",
+          errorClass: "infra_unavailable",
+          phase: "config"
         },
-        recovery: recoveryEnv({
-          app: app.name,
-          keys,
-          reasonCode: "missing_env"
-        }),
-        summary: `Missing required env ${keys.length === 1 ? "key" : "keys"}: ${keys.join(", ")}.`,
-        configPath: tomlPathFor2(ctx.cwd),
-        bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes }
-      };
-    }
-    if (err instanceof PercherApiError && err.code === "ENV_KEY_UNDECLARED") {
-      const extra = err.extra ?? {};
-      const apiProblems = extra.problems ?? [];
-      const problems = apiProblems.map((p) => ({
-        file: p.file,
-        line: p.line,
-        message: `Source references env key '${p.key}' which is not declared in [env]. Add it to [env].required, [env].optional, or [env].ignore in percher.toml. Context: ${p.context ?? "(unavailable)"}`
-      }));
-      const uniqueKeys = [...new Set(apiProblems.map((p) => p.key))];
-      return {
-        status: "failed",
-        app,
-        fileCount: tarball.fileCount,
-        bytes: tarball.bytes,
-        error: {
-          title: "Undeclared env key",
-          explanation: `Source references ${uniqueKeys.length} env ${uniqueKeys.length === 1 ? "key" : "keys"} that aren't classified in percher.toml's [env] table: ${uniqueKeys.join(", ")}.`,
-          suggestion: "Add each key to [env].required (must exist before deploy), [env].optional (may be referenced), or [env].ignore (intentionally unset). See https://percher.app/docs/env for the contract.",
-          errorClass: "config_invalid",
-          phase: "config",
-          relevantFiles: ["percher.toml"]
+        recovery: {
+          retryable: true,
+          nextAction: "retry",
+          suggestedTool: "percher_publish",
+          args: {},
+          reasonCode: "infra_unavailable"
         },
-        recovery: recoveryFixConfig({
-          problems,
-          reasonCode: "env_key_undeclared"
-        }),
-        summary: `${uniqueKeys.length} undeclared env ${uniqueKeys.length === 1 ? "key" : "keys"} in source: ${uniqueKeys.join(", ")}.`,
+        summary: `Preflight refused — ${reasonText}.`,
         configPath: tomlPathFor2(ctx.cwd),
         bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes }
       };
     }
-    if (err instanceof PercherApiError && err.code === "DAILY_QUOTA_EXCEEDED") {
-      const extra = err.extra ?? {};
-      const kind = extra.kind ?? "live";
-      const used = extra.used ?? 0;
-      const limit = extra.limit ?? 0;
-      const resetAt = extra.resetAt ?? "";
-      const otherKind = kind === "live" ? "preview" : "live";
-      return {
-        status: "failed",
-        app,
-        fileCount: tarball.fileCount,
-        bytes: tarball.bytes,
-        error: {
-          title: "Daily deploy quota reached",
-          explanation: `You've used ${used} of ${limit} ${kind} deploys today on this account. Counter resets at ${resetAt}.`,
-          suggestion: `Wait until the counter resets, deploy a ${otherKind} instead, or upgrade your plan at https://percher.app/settings to raise this cap.`
-        },
-        recovery: recoveryAsk({
-          prompt: `Daily ${kind}-deploy quota reached (${used}/${limit}). Counter resets at ${resetAt}. Wait until then, deploy a ${otherKind} instead, or upgrade at https://percher.app/settings.`,
-          options: ["wait", `deploy ${otherKind}`, "upgrade"],
-          reasonCode: "quota_exceeded"
+    if (preflight.queueWaitEstimateSec > 60) {
+      ctx.status(`Build queue wait: ~${preflight.queueWaitEstimateSec}s — your build is queued behind ${preflight.queueDepth} other(s).`);
+    }
+  } catch {}
+  const uploadStart = Date.now();
+  ctx.status("[3/4] Uploading...");
+  const tarballBytes = new Uint8Array(await new Response(tarball.stream).arrayBuffer());
+  let cacheReusedDeployment = null;
+  const contentHash = tarball.contentHash;
+  if (!input.noCache) {
+    try {
+      const probe = await ctx.client.platform.cacheProbe({
+        appId: app.id,
+        tarballHash: contentHash
+      });
+      if (probe.hit) {
+        ctx.status(`Build cache: identical bundle deployed previously (${probe.lastDeployId}) — redeploying without re-upload.`);
+        cacheReusedDeployment = await ctx.client.apps.rerunDeploy(app.id, probe.lastDeployId);
+        ctx.status("[4/4] Building & deploying (cache reuse)...");
+      }
+    } catch {}
+  }
+  const idempotencyKey = crypto.randomUUID();
+  let deployment;
+  if (cacheReusedDeployment) {
+    deployment = cacheReusedDeployment;
+  } else {
+    try {
+      const { result: deployResponse, attempts: deployAttempts } = await runDeployWithRetry({
+        call: (attempt) => ctx.client.apps.deploy(app.id, {
+          tarball: tarballBytes,
+          type: input.preview ? "preview" : undefined,
+          note: input.message,
+          noCache: input.noCache,
+          idempotencyKey,
+          tarballHash: contentHash,
+          retriedAttempts: attempt - 1
         }),
-        summary: `Daily ${kind}-deploy quota reached (${used}/${limit}). Resets ${resetAt}.`,
-        configPath: tomlPathFor2(ctx.cwd),
-        bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes }
-      };
+        onRetry: ({ attempt, decision }) => {
+          ctx.status(`Retrying after ${Math.round(decision.delayMs / 1000)}s — ${decision.reason} (attempt ${attempt + 1}/4)…`);
+        }
+      });
+      if (deployAttempts > 1) {
+        ctx.status(`Recovered after ${deployAttempts - 1} retry${deployAttempts > 2 ? "ies" : ""}.`);
+      }
+      if (isDeployAlreadyInProgress(deployResponse)) {
+        return buildAlreadyInProgressResult({
+          active: deployResponse,
+          app,
+          tarball: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+          cwd: ctx.cwd
+        });
+      }
+      deployment = deployResponse;
+    } catch (err) {
+      if (err instanceof PercherApiError && err.code === "RETRY_LIMIT_REACHED") {
+        return buildRetryLimitReachedResult({
+          err,
+          app,
+          tarball: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+          cwd: ctx.cwd
+        });
+      }
+      if (err instanceof PercherApiError && err.code === "REQUIRED_ENV_MISSING") {
+        const extra = err.extra ?? {};
+        const keys = extra.keys ?? [];
+        const source = extra.source ?? "contract";
+        const sourceText = source === "contract" ? "declared in your [env].required" : source === "discovered" ? "learned from a previous build failure" : "both declared and learned from a previous build failure";
+        return {
+          status: "failed",
+          app,
+          fileCount: tarball.fileCount,
+          bytes: tarball.bytes,
+          error: {
+            title: "Required env keys not set",
+            explanation: `${keys.length} env ${keys.length === 1 ? "key is" : "keys are"} ${sourceText} but missing from the env store: ${keys.join(", ")}.`,
+            suggestion: `Run \`bunx percher env set ${keys[0] ?? "KEY"}=value\` (and similarly for the rest) and re-publish.`,
+            errorClass: "missing_env",
+            phase: "config",
+            missingEnvVars: keys
+          },
+          recovery: recoveryEnv({
+            app: app.name,
+            keys,
+            reasonCode: "missing_env"
+          }),
+          summary: `Missing required env ${keys.length === 1 ? "key" : "keys"}: ${keys.join(", ")}.`,
+          configPath: tomlPathFor2(ctx.cwd),
+          bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes }
+        };
+      }
+      if (err instanceof PercherApiError && err.code === "ENV_KEY_UNDECLARED") {
+        const extra = err.extra ?? {};
+        const apiProblems = extra.problems ?? [];
+        const problems = apiProblems.map((p) => ({
+          file: p.file,
+          line: p.line,
+          message: `Source references env key '${p.key}' which is not declared in [env]. Add it to [env].required, [env].optional, or [env].ignore in percher.toml. Context: ${p.context ?? "(unavailable)"}`
+        }));
+        const uniqueKeys = [...new Set(apiProblems.map((p) => p.key))];
+        return {
+          status: "failed",
+          app,
+          fileCount: tarball.fileCount,
+          bytes: tarball.bytes,
+          error: {
+            title: "Undeclared env key",
+            explanation: `Source references ${uniqueKeys.length} env ${uniqueKeys.length === 1 ? "key" : "keys"} that aren't classified in percher.toml's [env] table: ${uniqueKeys.join(", ")}.`,
+            suggestion: "Add each key to [env].required (must exist before deploy), [env].optional (may be referenced), or [env].ignore (intentionally unset). See https://percher.app/docs/env for the contract.",
+            errorClass: "config_invalid",
+            phase: "config",
+            relevantFiles: ["percher.toml"]
+          },
+          recovery: recoveryFixConfig({
+            problems,
+            reasonCode: "env_key_undeclared"
+          }),
+          summary: `${uniqueKeys.length} undeclared env ${uniqueKeys.length === 1 ? "key" : "keys"} in source: ${uniqueKeys.join(", ")}.`,
+          configPath: tomlPathFor2(ctx.cwd),
+          bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes }
+        };
+      }
+      if (err instanceof PercherApiError && err.code === "DAILY_QUOTA_EXCEEDED") {
+        const extra = err.extra ?? {};
+        const kind = extra.kind ?? "live";
+        const used = extra.used ?? 0;
+        const limit = extra.limit ?? 0;
+        const resetAt = extra.resetAt ?? "";
+        const otherKind = kind === "live" ? "preview" : "live";
+        return {
+          status: "failed",
+          app,
+          fileCount: tarball.fileCount,
+          bytes: tarball.bytes,
+          error: {
+            title: "Daily deploy quota reached",
+            explanation: `You've used ${used} of ${limit} ${kind} deploys today on this account. Counter resets at ${resetAt}.`,
+            suggestion: `Wait until the counter resets, deploy a ${otherKind} instead, or upgrade your plan at https://percher.app/settings to raise this cap.`
+          },
+          recovery: recoveryAsk({
+            prompt: `Daily ${kind}-deploy quota reached (${used}/${limit}). Counter resets at ${resetAt}. Wait until then, deploy a ${otherKind} instead, or upgrade at https://percher.app/settings.`,
+            options: ["wait", `deploy ${otherKind}`, "upgrade"],
+            reasonCode: "quota_exceeded"
+          }),
+          summary: `Daily ${kind}-deploy quota reached (${used}/${limit}). Resets ${resetAt}.`,
+          configPath: tomlPathFor2(ctx.cwd),
+          bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes }
+        };
+      }
+      throw err;
     }
-    throw err;
   }
   const replacedPreview = deployment.replacedPreview === true;
   if (replacedPreview) {
@@ -17076,7 +17642,7 @@ ${keyList}
   }
   ctx.status("[4/4] Building & deploying...");
   const buildStart = Date.now();
-  const timeoutMs = 5 * 60 * 1000;
+  const timeoutMs = TIMEOUTS.clientPublishPoll;
   let lastStatus;
   let nextHeartbeatMs = 15000;
   let timedOut = null;
@@ -17100,6 +17666,11 @@ ${keyList}
           nextHeartbeatMs = elapsedMs + 15000;
         }
       },
+      onEvent: (event) => {
+        const line = renderDeployEvent(event);
+        if (line)
+          ctx.status(line);
+      },
       onTimeout: (d) => {
         timedOut = { deployment: d };
         throw new class PollTimeoutSentinel extends Error {
@@ -17185,7 +17756,9 @@ ${keyList}
     replacedPreview,
     firstDeploy: firstDeploy || undefined,
     cacheHit,
+    cacheReused: cacheReusedDeployment !== null || undefined,
     missingBuildEnvKeys: missingBuildEnvKeys.length > 0 ? missingBuildEnvKeys : undefined,
+    traceId: deployment.id,
     recovery: RECOVERY_NONE,
     summary: buildLiveSummary({
       appName: app.name,
@@ -17247,13 +17820,22 @@ async function handleUnauthorized(ctx, config, tarball, input) {
   let app;
   ({ app, firstDeploy: firstDeployRetry } = await ensureApp2(ctx, config));
   ctx.status("Uploading...");
+  const freshTarballBytes = new Uint8Array(await new Response(freshTarball.stream).arrayBuffer());
+  const freshIdempotencyKey = crypto.randomUUID();
   let deployment;
   try {
-    const deployResponse = await ctx.client.apps.deploy(app.id, {
-      tarball: freshTarball.stream,
-      type: input.preview ? "preview" : undefined,
-      note: input.message,
-      noCache: input.noCache
+    const { result: deployResponse } = await runDeployWithRetry({
+      call: (attempt) => ctx.client.apps.deploy(app.id, {
+        tarball: freshTarballBytes,
+        type: input.preview ? "preview" : undefined,
+        note: input.message,
+        noCache: input.noCache,
+        idempotencyKey: freshIdempotencyKey,
+        retriedAttempts: attempt - 1
+      }),
+      onRetry: ({ attempt, decision }) => {
+        ctx.status(`Retrying after ${Math.round(decision.delayMs / 1000)}s — ${decision.reason} (attempt ${attempt + 1}/4)…`);
+      }
     });
     if (isDeployAlreadyInProgress(deployResponse)) {
       return buildAlreadyInProgressResult({
@@ -17296,7 +17878,7 @@ async function handleUnauthorized(ctx, config, tarball, input) {
       bundle: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes }
     };
   }
-  const timeoutMs = 300000;
+  const timeoutMs = TIMEOUTS.clientPublishPoll;
   const start = Date.now();
   while (deployment.status !== "live" && deployment.status !== "failed" && deployment.status !== "replaced") {
     if (Date.now() - start > timeoutMs) {
@@ -17364,6 +17946,7 @@ async function handleUnauthorized(ctx, config, tarball, input) {
     firstDeploy: firstDeployRetry || undefined,
     recovery: RECOVERY_NONE,
     cacheHit: deployment.cacheHit,
+    traceId: deployment.id,
     summary: buildLiveSummary({
       appName: app.name,
       url: url ?? app.url,
@@ -17646,7 +18229,7 @@ Context: ${p.context}` : ""}`
     throw err;
   }
   const buildStart = Date.now();
-  const timeoutMs = 5 * 60 * 1000;
+  const timeoutMs = TIMEOUTS.clientPublishPoll;
   let lastStatus;
   let nextHeartbeatMs = 15000;
   let deployment = initial;
@@ -17696,10 +18279,10 @@ Context: ${p.context}` : ""}`
   const totalSeconds = (Date.now() - t0) / 1000;
   const url = deployment.previewUrl ?? deployment.url ?? app.url;
   if (deployment.status === "failed") {
-    const recovery = recoveryFromErrorClass("build_failed", {
-      deployId: deployment.id,
-      appName: app.name,
-      problems: deployment.problems
+    const { error, recovery, summary } = await classifyDeploymentFailure({
+      ctx,
+      app,
+      deployment
     });
     return {
       status: "failed",
@@ -17707,14 +18290,9 @@ Context: ${p.context}` : ""}`
       deployment,
       fileCount: 0,
       bytes: 0,
-      error: {
-        title: "Redeploy failed",
-        explanation: deployment.errorMessage ?? "The redeploy did not succeed.",
-        suggestion: `Inspect with \`bunx percher deploys inspect ${deployment.id}\`.`,
-        problems: deployment.problems
-      },
+      error,
       recovery,
-      summary: `${appName} redeploy failed (${deployment.id}).`,
+      summary,
       configPath: "",
       bundle: { fileCount: 0, bytes: 0 }
     };
@@ -17956,7 +18534,7 @@ async function rollback(ctx, input, internals = {}) {
   }
   let deployment = await ctx.client.apps.rollback(name, input.commitSha);
   const pollInterval = internals.pollIntervalMs ?? 2000;
-  const timeoutMs = internals.timeoutMs ?? 5 * 60 * 1000;
+  const timeoutMs = internals.timeoutMs ?? TIMEOUTS.clientPublishPoll;
   const startedAt = Date.now();
   while (deployment.status !== "live" && deployment.status !== "failed") {
     if (Date.now() - startedAt > timeoutMs) {
@@ -18076,8 +18654,8 @@ function resolveSource(backups, source) {
   }
   return sorted.find((b) => b.backup_id === source) ?? null;
 }
-function humanizeStatus(status) {
-  switch (status) {
+function humanizeStatus(status2) {
+  switch (status2) {
     case "preparing":
       return "Preparing";
     case "quiescing":
@@ -18091,7 +18669,7 @@ function humanizeStatus(status) {
     case "rolling_back":
       return "Rolling back";
     default:
-      return status;
+      return status2;
   }
 }
 // ../core/dist/commands/deploys.js
@@ -18195,6 +18773,15 @@ var doctorInputSchema = exports_external.object({
   mode: exports_external.enum(["auto", "deploy", "runtime", "config", "env", "account"]).optional(),
   deployId: exports_external.string().optional()
 });
+var STUCK_DEPLOY_THRESHOLD_MS = 15 * 60 * 1000;
+function isStuckDeploy(status2, createdAt, now = Date.now()) {
+  if (status2 !== "building" && status2 !== "queued")
+    return false;
+  const created = Date.parse(createdAt);
+  if (Number.isNaN(created))
+    return false;
+  return now - created > STUCK_DEPLOY_THRESHOLD_MS;
+}
 async function doctor(ctx, input = {}) {
   const checks = [];
   const hasToken = !!ctx.client.token;
@@ -18204,7 +18791,7 @@ async function doctor(ctx, input = {}) {
     message: hasToken ? "Token configured" : "No token found. Run: percher login"
   });
   if (!hasToken) {
-    return summarize(checks, { appProvided: !!input.app });
+    return summarize2(checks, { appProvided: !!input.app });
   }
   try {
     const start = Date.now();
@@ -18226,7 +18813,7 @@ async function doctor(ctx, input = {}) {
       status: "fail",
       message: `Cannot reach ${ctx.client.apiUrl}: ${err.message}`
     });
-    return summarize(checks, { appProvided: !!input.app });
+    return summarize2(checks, { appProvided: !!input.app });
   }
   const tomlPath = join13(ctx.cwd, "percher.toml");
   const tomlExists = existsSync9(tomlPath);
@@ -18267,7 +18854,7 @@ async function doctor(ctx, input = {}) {
   if (!appName) {
     const reason = tomlExists && !tomlValid ? "percher.toml is invalid — fix the issues above and re-run" : "No app specified and no percher.toml found";
     checks.push({ name: "App", status: "skip", message: reason });
-    return summarize(checks, { appProvided: !!input.app });
+    return summarize2(checks, { appProvided: !!input.app });
   }
   let appStatus;
   let lastDeployStatus;
@@ -18344,6 +18931,13 @@ async function doctor(ctx, input = {}) {
         status: deployOk ? "pass" : "warn",
         message: `${diag.lastDeploy.status} (${diag.lastDeploy.createdAt})`
       });
+      if (isStuckDeploy(diag.lastDeploy.status, diag.lastDeploy.createdAt)) {
+        checks.push({
+          name: "Deploy stuck",
+          status: "warn",
+          message: "Last deploy has been in-progress > 15 min — likely platform restart mid-build. Run `percher publish` again; the platform will clear the stuck row within ~2 min."
+        });
+      }
     }
     if (diag.lastCrash) {
       checks.push({
@@ -18455,7 +19049,7 @@ async function doctor(ctx, input = {}) {
       message: err.message
     });
   }
-  return summarize(checks, {
+  return summarize2(checks, {
     appName,
     appProvided: !!input.app,
     appStatus,
@@ -18476,12 +19070,12 @@ async function doctor(ctx, input = {}) {
 }
 var TRANSITIONAL_DEPLOY_STATUSES = new Set(["queued", "building", "deploying"]);
 var TRANSITIONAL_APP_STATUSES = new Set(["provisioning"]);
-function summarize(checks, vctx = {}) {
+function summarize2(checks, vctx = {}) {
   const passed = checks.filter((c) => c.status === "pass").length;
   const failed = checks.filter((c) => c.status === "fail").length;
   const warned = checks.filter((c) => c.status === "warn").length;
   const total = checks.filter((c) => c.status !== "skip").length;
-  const verdict = deriveVerdict(checks, vctx);
+  const verdict = deriveVerdict2(checks, vctx);
   return {
     checks,
     passed,
@@ -18494,7 +19088,7 @@ function summarize(checks, vctx = {}) {
     summary: verdict.summary
   };
 }
-function deriveVerdict(checks, vctx) {
+function deriveVerdict2(checks, vctx) {
   const findCheck = (name) => checks.find((c) => c.name === name);
   const auth = findCheck("Auth token");
   if (auth?.status === "fail") {
@@ -18603,9 +19197,9 @@ function deriveVerdict(checks, vctx) {
         summary: r.summary
       };
     }
-    const status = r.recovery.nextAction === "wait_deploy" ? "in_progress" : "needs_action";
+    const status2 = r.recovery.nextAction === "wait_deploy" ? "in_progress" : "needs_action";
     return {
-      status,
+      status: status2,
       diagnosis: {
         title: "Last deploy was replaced",
         explanation: r.summary,
@@ -18920,7 +19514,7 @@ async function doPush(ctx, config, callbacks) {
   }
   let deployment = deployResponse;
   const startedAt = Date.now();
-  const timeoutMs = 5 * 60 * 1000;
+  const timeoutMs = TIMEOUTS.clientPublishPoll;
   const pollInterval = 2000;
   let lastStatus = "";
   while (deployment.status !== "live" && deployment.status !== "failed") {
@@ -19062,7 +19656,7 @@ async function data(ctx, input = {}) {
       hint: "Pass an app name or run from a directory with percher.toml."
     });
   }
-  const status = await ctx.client.data.getStatus(name);
+  const status2 = await ctx.client.data.getStatus(name);
   const adminLink = await ctx.client.data.getAdminLink(name);
   let collections = [];
   let stats = { collections: 0, totalRecords: 0 };
@@ -19080,9 +19674,9 @@ async function data(ctx, input = {}) {
     }
   }
   return {
-    mode: status.mode,
-    status: status.status,
-    version: status.version ?? null,
+    mode: status2.mode,
+    status: status2.status,
+    version: status2.version ?? null,
     collections,
     stats,
     adminUrl: adminLink.adminUrl ?? null,
@@ -19801,7 +20395,8 @@ var PLAN_CATALOG = {
       kvStorageMb: 10,
       uptimeIntervalSec: 0,
       dailyLiveDeploys: 50,
-      dailyPreviewDeploys: 25
+      dailyPreviewDeploys: 25,
+      userConcurrentDeploys: 2
     }
   },
   starter: {
@@ -19831,7 +20426,8 @@ var PLAN_CATALOG = {
       kvStorageMb: 50,
       uptimeIntervalSec: 300,
       dailyLiveDeploys: 100,
-      dailyPreviewDeploys: 50
+      dailyPreviewDeploys: 50,
+      userConcurrentDeploys: 3
     }
   },
   maker: {
@@ -19861,7 +20457,8 @@ var PLAN_CATALOG = {
       kvStorageMb: 200,
       uptimeIntervalSec: 60,
       dailyLiveDeploys: 200,
-      dailyPreviewDeploys: 100
+      dailyPreviewDeploys: 100,
+      userConcurrentDeploys: 5
     }
   },
   pro: {
@@ -19891,7 +20488,8 @@ var PLAN_CATALOG = {
       kvStorageMb: 1000,
       uptimeIntervalSec: 30,
       dailyLiveDeploys: 1000,
-      dailyPreviewDeploys: 500
+      dailyPreviewDeploys: 500,
+      userConcurrentDeploys: 20
     }
   }
 };
@@ -19901,7 +20499,7 @@ import { existsSync as existsSync16, mkdirSync as mkdirSync5, readFileSync as re
 import { dirname as dirname3, join as join21 } from "node:path";
 
 // ../core/dist/ai-files-manifest.js
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync15, lstatSync, mkdirSync as mkdirSync4, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "node:fs";
 import { dirname as dirname2, join as join20, resolve as resolve5 } from "node:path";
 var MANIFEST_REL = ".percher/ai-files-state.json";
@@ -19909,7 +20507,7 @@ var EMPTY_MANIFEST = { version: 1, files: {} };
 function hashContent(content) {
   const normalised = content.replace(/\r\n/g, `
 `);
-  return createHash("sha256").update(normalised, "utf8").digest("hex");
+  return createHash2("sha256").update(normalised, "utf8").digest("hex");
 }
 function manifestPath(projectRoot) {
   return join20(projectRoot, MANIFEST_REL);
@@ -20371,12 +20969,12 @@ function formatDeployTimestamp(iso) {
   const pad = (n) => n.toString().padStart(2, "0");
   return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
 }
-function formatStatus(status) {
-  if (status === "live")
-    return import_picocolors.default.green(status);
-  if (status === "failed")
-    return import_picocolors.default.red(status);
-  return import_picocolors.default.yellow(status);
+function formatStatus(status2) {
+  if (status2 === "live")
+    return import_picocolors.default.green(status2);
+  if (status2 === "failed")
+    return import_picocolors.default.red(status2);
+  return import_picocolors.default.yellow(status2);
 }
 function firstNonFlagAfter(argv, from, valueFlags = new Set) {
   let i = from + 1;
@@ -20657,8 +21255,8 @@ function registerAccountCommands(cli, ctx) {
 
 // src/commands/apps.ts
 var import_picocolors3 = __toESM(require_picocolors(), 1);
-function assertNever(status, summary) {
-  throw new Error(`Unhandled publish status: ${JSON.stringify(status)}${summary ? ` (${summary})` : ""}`);
+function assertNever(status2, summary) {
+  throw new Error(`Unhandled publish status: ${JSON.stringify(status2)}${summary ? ` (${summary})` : ""}`);
 }
 async function handlePublishResult(ctx, result, options = {}) {
   switch (result.status) {
@@ -20760,7 +21358,12 @@ async function handlePublishResult(ctx, result, options = {}) {
     case "live": {
       const timing = result.timing ? ` (${result.timing.totalSeconds}s)` : "";
       await writeLine(ctx, `${import_picocolors3.default.green("✓")} Published to ${result.url}${timing}`);
-      if (result.cacheHit === true) {
+      if (result.traceId) {
+        await writeLine(ctx, import_picocolors3.default.dim(`  Trace: ${result.traceId}`));
+      }
+      if (result.cacheReused) {
+        await writeLine(ctx, import_picocolors3.default.dim("  Build cache: reused — identical bundle, redeployed without re-upload (--no-cache to force a fresh build)"));
+      } else if (result.cacheHit === true) {
         await writeLine(ctx, import_picocolors3.default.dim("  Build cache: hit (reused image — re-run with --no-cache if your changes aren't reflected)"));
       } else if (result.cacheHit === false) {
         await writeLine(ctx, import_picocolors3.default.dim("  Build cache: miss (fresh build)"));
@@ -21116,11 +21719,11 @@ function registerDeploysCommands(cli, ctx, argv) {
     await writeLine(ctx, `${import_picocolors6.default.bold("ID".padEnd(22))}  ${import_picocolors6.default.bold("STATUS".padEnd(10))}  ${import_picocolors6.default.bold("CREATED".padEnd(20))}  ${import_picocolors6.default.bold("ERROR")}`);
     for (const d of list) {
       const id = d.id.padEnd(22);
-      const status = d.status.padEnd(10);
+      const status2 = d.status.padEnd(10);
       const created = formatDeployTimestamp(d.createdAt).padEnd(20);
       const err = d.errorMessage ? d.errorMessage.split(`
 `)[0]?.slice(0, 60) ?? "—" : import_picocolors6.default.dim("—");
-      const colored = d.status === "live" ? import_picocolors6.default.green(status) : d.status === "failed" ? import_picocolors6.default.red(status) : import_picocolors6.default.yellow(status);
+      const colored = d.status === "live" ? import_picocolors6.default.green(status2) : d.status === "failed" ? import_picocolors6.default.red(status2) : import_picocolors6.default.yellow(status2);
       await writeLine(ctx, `${import_picocolors6.default.dim(id)}  ${colored}  ${import_picocolors6.default.dim(created)}  ${err}`);
     }
   });
@@ -21338,6 +21941,49 @@ function registerGithubCommands(cli, ctx) {
   cli.command("github setup-webhook", "Regenerate the GitHub webhook secret for an app (use after a failed `github connect`)").option("--app <name>", "App name (overrides percher.toml)").action(async () => {});
 }
 
+// src/commands/status.ts
+var import_picocolors9 = __toESM(require_picocolors(), 1);
+function registerStatusCommands(cli, ctx) {
+  cli.command("status", "Show Percher platform status (API + worker health)").option("--json", "Output JSON instead of formatted text").action(async (options) => {
+    const result = await status(ctx, { json: Boolean(options.json) });
+    if (options.json) {
+      await writeLine(ctx, JSON.stringify(result, null, 2));
+      if (result.verdict === "unreachable")
+        throw new SilentExitError(1);
+      return;
+    }
+    await renderHumanStatus(ctx, result);
+    if (result.verdict === "unreachable")
+      throw new SilentExitError(1);
+  });
+}
+async function renderHumanStatus(ctx, result) {
+  const symbol = result.verdict === "operational" ? import_picocolors9.default.green("✓") : result.verdict === "worker-degraded" ? import_picocolors9.default.yellow("⚠") : import_picocolors9.default.red("✗");
+  await writeLine(ctx, `${symbol} ${result.summary}`);
+  if (!result.health)
+    return;
+  const worker = result.health.worker;
+  if (!worker) {
+    await writeLine(ctx, import_picocolors9.default.dim("  worker: not configured (local Docker socket)"));
+    return;
+  }
+  if (worker.health) {
+    const ok = worker.health.ok;
+    const symbol2 = ok ? import_picocolors9.default.green("✓") : import_picocolors9.default.red("✗");
+    const lastOk = worker.health.lastOkAt ?? "never";
+    await writeLine(ctx, `  ${symbol2} worker health: ${ok ? "ok" : `failing (${worker.health.consecutiveErrs} consecutive)`}  last-ok=${import_picocolors9.default.dim(lastOk)}`);
+  }
+  if (worker.circuitBreaker) {
+    const breaker = worker.circuitBreaker;
+    const symbol2 = breaker.open ? import_picocolors9.default.red("✗") : import_picocolors9.default.green("✓");
+    const state = breaker.open ? "open (deploys fail fast)" : "closed";
+    await writeLine(ctx, `  ${symbol2} circuit breaker: ${state}  ${breaker.failuresInWindow}/${breaker.threshold} failures in last ${Math.round(breaker.windowMs / 1000)}s`);
+  }
+  if (result.health.version) {
+    await writeLine(ctx, import_picocolors9.default.dim(`  api version: ${result.health.version}`));
+  }
+}
+
 // src/open.ts
 import { spawn } from "node:child_process";
 async function openUrl(url) {
@@ -21397,40 +22043,40 @@ async function createCliContext() {
 }
 
 // src/output.ts
-var import_picocolors9 = __toESM(require_picocolors(), 1);
+var import_picocolors10 = __toESM(require_picocolors(), 1);
 async function renderError(stderr, error) {
   const writer = stderr.getWriter();
   const encoder = new TextEncoder;
   const lines = [];
   if (error instanceof PercherTomlError) {
-    lines.push(`${import_picocolors9.default.red(`error (${error.code}):`)} ${error.message}`);
+    lines.push(`${import_picocolors10.default.red(`error (${error.code}):`)} ${error.message}`);
     if (error.tomlLine !== undefined) {
-      lines.push(import_picocolors9.default.dim(`  at percher.toml line ${error.tomlLine}`));
+      lines.push(import_picocolors10.default.dim(`  at percher.toml line ${error.tomlLine}`));
     }
     for (const issue of error.issues ?? []) {
-      lines.push(`${import_picocolors9.default.dim("  · ") + import_picocolors9.default.yellow(issue.path.join("."))}: ${issue.message}`);
+      lines.push(`${import_picocolors10.default.dim("  · ") + import_picocolors10.default.yellow(issue.path.join("."))}: ${issue.message}`);
     }
   } else if (error instanceof PercherApiError) {
     if (error.status === 502 || error.status === 503) {
-      lines.push(`${import_picocolors9.default.red("error:")} Percher API is temporarily unavailable (HTTP ${error.status}). Try again in a few seconds.`);
+      lines.push(`${import_picocolors10.default.red("error:")} Percher API is temporarily unavailable (HTTP ${error.status}). Try again in a few seconds.`);
     } else {
-      lines.push(`${import_picocolors9.default.red("error:")} ${error.message}`);
-      lines.push(import_picocolors9.default.dim(`  ${error.code} (HTTP ${error.status})`));
+      lines.push(`${import_picocolors10.default.red("error:")} ${error.message}`);
+      lines.push(import_picocolors10.default.dim(`  ${error.code} (HTTP ${error.status})`));
     }
     if (error.requestId)
-      lines.push(import_picocolors9.default.dim(`  request: ${error.requestId}`));
+      lines.push(import_picocolors10.default.dim(`  request: ${error.requestId}`));
   } else if (error instanceof PercherCoreError) {
-    lines.push(`${import_picocolors9.default.red(`error (${error.code}):`)} ${error.message}`);
+    lines.push(`${import_picocolors10.default.red(`error (${error.code}):`)} ${error.message}`);
     if (error.hint)
-      lines.push(import_picocolors9.default.dim(`  ${error.hint}`));
+      lines.push(import_picocolors10.default.dim(`  ${error.hint}`));
   } else if (error instanceof Error) {
-    lines.push(`${import_picocolors9.default.red("unexpected error:")} ${error.message}`);
+    lines.push(`${import_picocolors10.default.red("unexpected error:")} ${error.message}`);
     if (error.stack)
-      lines.push(import_picocolors9.default.dim(error.stack.split(`
+      lines.push(import_picocolors10.default.dim(error.stack.split(`
 `).slice(1, 4).join(`
 `)));
   } else {
-    lines.push(`${import_picocolors9.default.red("unexpected error:")} ${String(error)}`);
+    lines.push(`${import_picocolors10.default.red("unexpected error:")} ${String(error)}`);
   }
   try {
     await writer.write(encoder.encode(`${lines.join(`
@@ -21443,7 +22089,7 @@ async function renderError(stderr, error) {
 // package.json
 var package_default = {
   name: "percher",
-  version: "0.3.0",
+  version: "0.4.0",
   description: "CLI for the Percher hosting platform — publish apps with one command",
   type: "module",
   bin: {
@@ -21466,7 +22112,7 @@ var package_default = {
   },
   dependencies: {
     "@percher/client": "^0.2.7",
-    "@percher/core": "^0.3.0",
+    "@percher/core": "^0.4.0",
     "@percher/toml": "^0.1.3",
     cac: "^7.0.0",
     picocolors: "^1.1.1"
@@ -21476,7 +22122,7 @@ var package_default = {
   },
   engines: {
     bun: ">=1.0.0",
-    node: ">=20.19.0"
+    node: ">=22.0.0"
   },
   license: "MIT",
   author: "Mattias Malmborg",
@@ -21531,7 +22177,7 @@ async function showTelemetryNotice() {
 }
 
 // src/version-check.ts
-var import_picocolors10 = __toESM(require_picocolors(), 1);
+var import_picocolors11 = __toESM(require_picocolors(), 1);
 async function checkForUpdates() {
   try {
     const res = await fetch("https://registry.npmjs.org/percher/latest", {
@@ -21542,9 +22188,9 @@ async function checkForUpdates() {
     const data2 = await res.json();
     const latest = data2.version;
     if (latest && latest !== VERSION) {
-      console.error(import_picocolors10.default.yellow(`
+      console.error(import_picocolors11.default.yellow(`
 Update available: ${VERSION} → ${latest}`));
-      console.error(import_picocolors10.default.dim(`Run: bunx percher@latest
+      console.error(import_picocolors11.default.dim(`Run: bunx percher@latest
 `));
     }
   } catch {}
@@ -21561,6 +22207,7 @@ async function run(argv, ctxOverride) {
   registerAuthCommands(cli, ctx);
   registerAccountCommands(cli, ctx);
   registerGithubCommands(cli, ctx);
+  registerStatusCommands(cli, ctx);
   cli.help();
   cli.version(VERSION);
   const command = argv[0] ?? "help";