percher 0.4.2 → 0.5.0

package/dist/bin/percher.js

@@ -103988,8 +103988,46 @@ function date4(params) {
 
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
-// ../toml/dist/schema.js
+// ../shared/dist/app-name.js
 var APP_NAME_RE = /^[a-z][a-z0-9-]{2,39}$/;
+// ../shared/dist/limits.js
+var MAX_TARBALL_BYTES = 500 * 1024 * 1024;
+// ../shared/dist/logs.js
+var MAX_LOG_SEARCH_LENGTH = 256;
+// ../shared/dist/platform-env.js
+var PERCHER_INJECTED_ENV_KEYS = new Set([
+  "NODE_ENV",
+  "PORT",
+  "DATABASE_URL",
+  "POCKETBASE_URL",
+  "POCKETBASE_ADMIN_EMAIL",
+  "POCKETBASE_ADMIN_PASSWORD",
+  "PERCHER_APP_NAME",
+  "PERCHER_APP_URL",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "NODE_USE_ENV_PROXY"
+]);
+var PROXY_LOWERCASE_ALIASES = new Set([
+  "http_proxy",
+  "https_proxy",
+  "no_proxy"
+]);
+// ../shared/dist/runtime.js
+var DEFAULT_NODE_VERSION_MAJOR = "24";
+var DEFAULT_NODE_VERSION_LABEL = `${DEFAULT_NODE_VERSION_MAJOR} LTS`;
+// ../shared/dist/timeouts.js
+var TIMEOUTS = {
+  workerBuildSubprocess: 10 * 60000,
+  apiToWorkerBuildFetch: 11 * 60000,
+  clientPublishPoll: 12 * 60000,
+  workerHealthcheck: 5000,
+  watchdogList: 15000,
+  mcpWaitDeployDefault: 30000,
+  mcpWaitDeployMax: 12 * 60000
+};
+// ../toml/dist/schema.js
 var appSchema = exports_external.object({
   name: exports_external.string().regex(APP_NAME_RE, "must be 3–40 chars, lowercase, start with a letter, [a-z0-9-] only"),
   runtime: exports_external.enum(["node", "bun", "python", "static", "docker"]),
@@ -104030,6 +104068,7 @@ var buildSchema = exports_external.object({
 var webSchema = exports_external.object({
   port: exports_external.number().int().min(1024).max(65535),
   health: exports_external.string().optional(),
+  command: exports_external.string().min(1).max(1000).optional(),
   password: exports_external.boolean().optional(),
   spa: exports_external.boolean().optional()
 }).strict();
@@ -104205,6 +104244,15 @@ var cronSchema = exports_external.object({
   command: exports_external.string().min(1),
   description: exports_external.string().max(200).optional()
 }).strict();
+var cronsSchema = exports_external.record(exports_external.string(), cronSchema).superRefine((jobs, ctx) => {
+  if (Object.hasOwn(jobs, "")) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      path: [""],
+      message: "cron job name must not be empty"
+    });
+  }
+});
 var addonsSchema = exports_external.object({
   pocketbase: exports_external.object({ enabled: exports_external.boolean().optional() }).strict().optional(),
   cron: exports_external.object({ enabled: exports_external.boolean().optional() }).strict().optional(),
@@ -104229,7 +104277,7 @@ var percherConfigSchema = exports_external.object({
   resources: resourcesSchema.optional(),
   dev: devSchema.optional(),
   required_env: requiredEnvSchema.optional(),
-  crons: exports_external.record(exports_external.string(), cronSchema).optional(),
+  crons: cronsSchema.optional(),
   addons: addonsSchema.optional(),
   checks: exports_external.record(exports_external.string(), checkSchema).optional()
 }).strict();
@@ -104900,6 +104948,20 @@ var billingUpgradeInputSchema = exports_external.object({
   plan: exports_external.enum(["starter", "maker", "pro"])
 });
 var billingPortalInputSchema = exports_external.object({});
+// ../core/dist/commands/cache.js
+var cacheResetInputSchema = exports_external.object({
+  app: exports_external.string().optional()
+});
+async function cacheReset(ctx, input = {}) {
+  const name = input.app ?? readPercherTomlAppName(ctx.cwd);
+  if (!name) {
+    throw new PercherCoreError("No app specified and no percher.toml found", {
+      code: "env.no-app",
+      hint: "Pass an app name or run from a directory with percher.toml."
+    });
+  }
+  return ctx.client.apps.resetCache(name);
+}
 // ../core/dist/commands/create.js
 import { join as join6, resolve as resolve4 } from "node:path";
 
@@ -104959,9 +105021,8 @@ function scaffoldTemplate(input) {
 }
 
 // ../core/dist/commands/create.js
-var APP_NAME_RE2 = /^[a-z][a-z0-9-]{2,39}$/;
 var createInputSchema = exports_external.object({
-  name: exports_external.string().regex(APP_NAME_RE2, "must be 3-40 chars, lowercase, start with a letter, [a-z0-9-] only"),
+  name: exports_external.string().regex(APP_NAME_RE, "must be 3-40 chars, lowercase, start with a letter, [a-z0-9-] only"),
   template: exports_external.string().min(1, "Template is required"),
   directory: exports_external.string().optional(),
   force: exports_external.boolean().optional()
@@ -105016,6 +105077,7 @@ var dashboardInputSchema = exports_external.object({
 });
 var DEFAULT_BASE = "https://percher.app";
 var TAB_SHAPE = /^[a-z][a-z0-9-]{0,31}$/;
+var SETTINGS_ANCHOR_TABS = new Set(["github", "env", "domains", "crash-diagnosis"]);
 async function dashboard(ctx, input = {}) {
   const name = input.app ?? readPercherTomlAppName(ctx.cwd);
   if (!name) {
@@ -105032,7 +105094,8 @@ async function dashboard(ctx, input = {}) {
     });
   }
   const base = ctx.env.PERCHER_DASHBOARD_URL ?? DEFAULT_BASE;
-  const url2 = `${base}/apps/${encodeURIComponent(name)}?tab=${tab}`;
+  const appBase = `${base}/apps/${encodeURIComponent(name)}`;
+  const url2 = SETTINGS_ANCHOR_TABS.has(tab) ? `${appBase}/settings#${tab}` : `${appBase}?tab=${tab}`;
   await ctx.openUrl(url2);
   return url2;
 }
@@ -105124,6 +105187,28 @@ async function deleteApp(ctx, input) {
   }
   await ctx.client.apps.delete(name);
 }
+// ../client/dist/abortable-sleep.js
+function abortableSleep(ms, signal) {
+  return new Promise((resolve6) => {
+    if (!signal) {
+      setTimeout(resolve6, ms);
+      return;
+    }
+    if (signal.aborted) {
+      resolve6();
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(t);
+      resolve6();
+    };
+    const t = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve6();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
 // ../client/dist/build-env-prefixes.js
 var AUTO_FORWARD_PREFIXES = [
   "NEXT_PUBLIC_",
@@ -105196,6 +105281,21 @@ class PercherApiError extends Error {
     this.extra = options.extra;
   }
 }
+
+class NetworkError extends Error {
+  constructor(message, options) {
+    super(`network error: ${message}`, options);
+    this.name = "NetworkError";
+  }
+}
+var TRANSIENT_NETWORK_MESSAGE = /network error|fetch failed|ECONNRESET|ENOTFOUND|ETIMEDOUT/i;
+function isTransientNetworkError(err) {
+  if (err instanceof NetworkError)
+    return true;
+  if (err instanceof PercherApiError)
+    return false;
+  return err instanceof Error && TRANSIENT_NETWORK_MESSAGE.test(err.message);
+}
 var RESTORE_JOB_STATUSES_FOR_ERROR = [
   "preparing",
   "quiescing",
@@ -105244,6 +105344,11 @@ function isSunsetGateBody(body) {
 }
 
 // ../client/dist/http.js
+var BODY_SNIPPET_MAX = 120;
+function bodySnippet(body) {
+  return body.length <= BODY_SNIPPET_MAX ? body : `${body.slice(0, BODY_SNIPPET_MAX)}…`;
+}
+
 class Http {
   apiUrl;
   token;
@@ -105257,8 +105362,8 @@ class Http {
     this.clientVersion = options.clientVersion;
     this.sessionId = options.sessionId;
   }
-  get(path) {
-    return this.request("GET", path);
+  get(path, opts) {
+    return this.request("GET", path, undefined, opts?.signal);
   }
   post(path, body) {
     return this.request("POST", path, body);
@@ -105296,7 +105401,7 @@ class Http {
     try {
       res = await this.fetchImpl(`${this.apiUrl}${path}`, { method: "GET", headers });
     } catch (err) {
-      throw new Error(`network error: ${err.message}`, { cause: err });
+      throw new NetworkError(err.message, { cause: err });
     }
     if (!res.ok)
       throw await this.parseError(res);
@@ -105322,15 +105427,15 @@ class Http {
     try {
       res = await this.fetchImpl(`${this.apiUrl}${path}`, init);
     } catch (err) {
-      throw new Error(`network error: ${err.message}`, { cause: err });
+      throw new NetworkError(err.message, { cause: err });
     }
     if (!res.ok)
       throw await this.parseError(res);
     return await res.json();
   }
-  async request(method, path, body) {
+  async request(method, path, body, signal) {
     const headers = this.buildHeaders();
-    const init = { method, headers };
+    const init = { method, headers, signal };
     if (body !== undefined) {
       headers["Content-Type"] = "application/json";
       init.body = JSON.stringify(body);
@@ -105339,7 +105444,7 @@ class Http {
     try {
       res = await this.fetchImpl(`${this.apiUrl}${path}`, init);
     } catch (err) {
-      throw new Error(`network error: ${err.message}`, { cause: err });
+      throw new NetworkError(err.message, { cause: err });
     }
     if (!res.ok)
       throw await this.parseError(res);
@@ -105350,7 +105455,10 @@ class Http {
       return await res.json();
     if (contentType.startsWith("text/"))
       return await res.text();
-    return;
+    const raw = await res.text();
+    if (raw.length === 0)
+      return;
+    throw new PercherApiError(`unexpected content-type "${contentType || "none"}" on ${method} ${path}: ${bodySnippet(raw)}`, { status: res.status, code: "UNEXPECTED_CONTENT_TYPE" });
   }
   buildHeaders() {
     const headers = {
@@ -105451,11 +105559,12 @@ class AlertsResource {
   }
 }
 
-// ../client/dist/resources/apps.js
+// ../client/dist/resources/apps-types.js
 function isDeployAlreadyInProgress(res) {
   return res.status === "already_in_progress";
 }
 
+// ../client/dist/resources/apps.js
 class AppsResource {
   http;
   constructor(http) {
@@ -105470,8 +105579,8 @@ class AppsResource {
   listLight() {
     return this.http.get("/apps?light=1");
   }
-  get(id) {
-    return this.http.get(`/apps/${encodeURIComponent(id)}`);
+  get(id, opts) {
+    return this.http.get(`/apps/${encodeURIComponent(id)}`, opts);
   }
   async deploy(id, input) {
     const params = new URLSearchParams;
@@ -105510,6 +105619,12 @@ class AppsResource {
       enabled
     });
   }
+  setPreviewBranch(appRef, branch) {
+    return this.http.put(`/apps/${encodeURIComponent(appRef)}/preview-branch`, { branch });
+  }
+  unsetPreviewBranch(appRef) {
+    return this.http.deleteJson(`/apps/${encodeURIComponent(appRef)}/preview-branch`);
+  }
   setDescription(appRef, description) {
     return this.http.patch(`/apps/${encodeURIComponent(appRef)}/description`, {
       description
@@ -105548,8 +105663,8 @@ class AppsResource {
   discardPreview(appRef, deployId) {
     return this.http.post(`/apps/${encodeURIComponent(appRef)}/deploys/${encodeURIComponent(deployId)}/discard`, {});
   }
-  getDeployment(appRef, deployId) {
-    return this.http.get(`/apps/${encodeURIComponent(appRef)}/deploys/${encodeURIComponent(deployId)}`);
+  getDeployment(appRef, deployId, opts) {
+    return this.http.get(`/apps/${encodeURIComponent(appRef)}/deploys/${encodeURIComponent(deployId)}`, opts);
   }
   listDeploys(appRef, opts) {
     const params = new URLSearchParams;
@@ -105558,32 +105673,36 @@ class AppsResource {
     if (opts?.limit)
       params.set("limit", String(opts.limit));
     const qs = params.toString();
-    return this.http.get(`/apps/${encodeURIComponent(appRef)}/deploys${qs ? `?${qs}` : ""}`);
+    return this.http.get(`/apps/${encodeURIComponent(appRef)}/deploys${qs ? `?${qs}` : ""}`, opts?.signal ? { signal: opts.signal } : undefined);
   }
-  async getBuildLog(appRef, deployId) {
+  async getBuildLog(appRef, deployId, opts) {
     const path = `/apps/${encodeURIComponent(appRef)}/deploys/${encodeURIComponent(deployId)}/build-log`;
     let attempt = 0;
     const maxRetries = 5;
     while (true) {
       try {
-        const res = await this.http.get(path);
+        const res = await this.http.get(path, opts);
         if (typeof res === "string")
           return res;
         return res?.buildLog ?? "";
       } catch (err) {
         attempt++;
-        const msg = err.message ?? String(err);
-        const isNetwork = msg.startsWith("network error:");
-        if (!isNetwork || attempt >= maxRetries)
+        if (opts?.signal?.aborted || !isTransientNetworkError(err) || attempt >= maxRetries) {
           throw err;
+        }
         const backoffMs = 1000 * 2 ** (attempt - 1);
-        await new Promise((r) => setTimeout(r, backoffMs));
+        await abortableSleep(backoffMs, opts?.signal);
+        if (opts?.signal?.aborted)
+          throw err;
       }
     }
   }
   unsuspend(appRef) {
     return this.http.post(`/apps/${encodeURIComponent(appRef)}/unsuspend`, {});
   }
+  resetCache(appRef) {
+    return this.http.post(`/apps/${encodeURIComponent(appRef)}/cache/reset`, {});
+  }
   delete(id) {
     return this.http.delete(`/apps/${encodeURIComponent(id)}`);
   }
@@ -106003,6 +106122,9 @@ class SecurityResource {
   overview() {
     return this.http.get("/admin/security/overview");
   }
+  platformBaseOverview() {
+    return this.http.get("/admin/security/platform-base");
+  }
   rescanAllAsAdmin() {
     return this.http.post("/admin/security/rescan", {});
   }
@@ -106192,17 +106314,6 @@ async function deploysInspect(ctx, input) {
 import { existsSync as existsSync7 } from "node:fs";
 import { join as join10 } 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/tarball.js
 var import_ignore = __toESM(require_ignore(), 1);
 import { createHash as createHash2 } from "node:crypto";
@@ -107159,15 +107270,17 @@ function trimMessage(raw) {
 function tomlPathFor(cwd) {
   return join11(cwd, "percher.toml");
 }
-async function buildFailureError(ctx, app, deployment) {
+async function buildFailureError(ctx, app, deployment, signal) {
   let buildLogTail;
   let buildLogFetchFailed = false;
   let fullLog = "";
   try {
-    fullLog = await ctx.client.apps.getBuildLog(app.id, deployment.id);
-    if (!fullLog) {
-      await new Promise((r) => setTimeout(r, 1500));
-      fullLog = await ctx.client.apps.getBuildLog(app.id, deployment.id);
+    fullLog = await ctx.client.apps.getBuildLog(app.id, deployment.id, { signal });
+    if (!fullLog && !signal?.aborted) {
+      await abortableSleep(1500, signal);
+      if (!signal?.aborted) {
+        fullLog = await ctx.client.apps.getBuildLog(app.id, deployment.id, { signal });
+      }
     }
     if (fullLog) {
       const lines = fullLog.split(`
@@ -107213,7 +107326,7 @@ async function buildFailureError(ctx, app, deployment) {
 }
 async function classifyDeploymentFailure(opts) {
   const { ctx, app, deployment, publishInput } = opts;
-  const error48 = await buildFailureError(ctx, app, deployment);
+  const error48 = await buildFailureError(ctx, app, deployment, opts.signal);
   const recovery = error48.errorClass ? recoveryFromErrorClass(error48.errorClass, {
     missingEnvVars: error48.missingEnvVars,
     deployId: deployment.id,
@@ -107259,6 +107372,100 @@ var waitForDeployInputSchema = exports_external.object({
   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 waitForDeploy(ctx, input, opts) {
+  const timeoutSeconds = input.timeoutSeconds ?? TIMEOUTS.mcpWaitDeployDefault / 1000;
+  const pollIntervalSeconds = input.pollIntervalSeconds ?? 2;
+  const startedAt = Date.now();
+  const deadlineMs = startedAt + timeoutSeconds * 1000;
+  const controller = new AbortController;
+  const abortTimer = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+  const onExternalAbort = () => controller.abort();
+  opts?.signal?.addEventListener("abort", onExternalAbort, { once: true });
+  if (opts?.signal?.aborted)
+    controller.abort();
+  try {
+    let app;
+    let initial;
+    try {
+      [app, initial] = await Promise.all([
+        ctx.client.apps.get(input.app, { signal: controller.signal }),
+        ctx.client.apps.getDeployment(input.app, input.deployId, { signal: controller.signal })
+      ]);
+    } catch (err) {
+      if (controller.signal.aborted) {
+        throw new PercherCoreError(`wait-for-deploy timed out after ${timeoutSeconds}s before the first status fetch completed`, {
+          code: "wait.timeout",
+          hint: "The API is slow or unreachable. Retry with a larger timeout, or run percher doctor."
+        });
+      }
+      throw err;
+    }
+    let deployment = initial;
+    while (!isTerminal(deployment.status)) {
+      if (controller.signal.aborted || Date.now() >= deadlineMs) {
+        return buildStillRunningResult(app, deployment, startedAt);
+      }
+      const sleepMs = Math.min(pollIntervalSeconds * 1000, deadlineMs - Date.now());
+      await abortableSleep(sleepMs, controller.signal);
+      if (controller.signal.aborted || Date.now() >= deadlineMs) {
+        return buildStillRunningResult(app, deployment, startedAt);
+      }
+      try {
+        deployment = await ctx.client.apps.getDeployment(input.app, input.deployId, {
+          signal: controller.signal
+        });
+      } catch (err) {
+        if (controller.signal.aborted) {
+          return buildStillRunningResult(app, deployment, startedAt, "status fetch exceeded the wait budget");
+        }
+        if (isTransientNetworkError(err)) {
+          const msg = err.message ?? String(err);
+          return buildStillRunningResult(app, deployment, startedAt, msg);
+        }
+        throw err;
+      }
+    }
+    if (deployment.status === "failed") {
+      const { error: error48, recovery, summary } = await classifyDeploymentFailure({
+        ctx,
+        app,
+        deployment,
+        signal: opts?.signal
+      });
+      return {
+        status: "failed",
+        app: { id: app.id, name: app.name, url: app.url },
+        deployment,
+        elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+        totalElapsedSeconds: secondsSinceCreated(deployment),
+        error: error48,
+        recovery,
+        summary
+      };
+    }
+    if (deployment.status === "replaced") {
+      return await buildReplacedResult({ ctx, app, deployment, startedAt, signal: opts?.signal });
+    }
+    const url2 = deployment.previewUrl ?? deployment.url ?? app.url;
+    return {
+      status: "live",
+      app: { id: app.id, name: app.name, url: app.url },
+      deployment,
+      url: url2,
+      elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+      totalElapsedSeconds: secondsSinceCreated(deployment),
+      recovery: RECOVERY_NONE,
+      summary: `${app.name} deploy ${deployment.id} is live → ${url2}`
+    };
+  } finally {
+    clearTimeout(abortTimer);
+    controller.abort();
+    opts?.signal?.removeEventListener("abort", onExternalAbort);
+  }
+}
+function isTerminal(status) {
+  return status === "live" || status === "failed" || status === "replaced";
+}
 async function resolveReplaced(opts) {
   const { ctx, app, replacedDeployment } = opts;
   const deployType = replacedDeployment.type ?? "live";
@@ -107266,7 +107473,8 @@ async function resolveReplaced(opts) {
   try {
     const deploys = await ctx.client.apps.listDeploys(app.name, {
       limit: 5,
-      type: deployType
+      type: deployType,
+      signal: opts.signal
     });
     latest = deploys.find((d) => d.id !== replacedDeployment.id);
   } catch {
@@ -107313,6 +107521,46 @@ async function resolveReplaced(opts) {
     summary: `${app.name} deploy ${replacedDeployment.id} was replaced; the latest deploy ${latest.id} is ${latest.status}. Surface to user.`
   };
 }
+async function buildReplacedResult(opts) {
+  const { ctx, app, deployment, startedAt } = opts;
+  const resolved = await resolveReplaced({
+    ctx,
+    app,
+    replacedDeployment: deployment,
+    signal: opts.signal
+  });
+  return {
+    status: "replaced",
+    app: { id: app.id, name: app.name, url: app.url },
+    deployment,
+    url: resolved.url,
+    elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+    totalElapsedSeconds: secondsSinceCreated(deployment),
+    recovery: resolved.recovery,
+    summary: resolved.summary
+  };
+}
+function buildStillRunningResult(app, deployment, startedAt, networkHint) {
+  return {
+    status: "still_running",
+    app: { id: app.id, name: app.name, url: app.url },
+    deployment,
+    elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+    totalElapsedSeconds: secondsSinceCreated(deployment),
+    recovery: recoveryWait({
+      app: app.name,
+      deployId: deployment.id,
+      reasonCode: deployment.status === "queued" ? "deploy_queued" : deployment.status === "building" ? "deploy_building" : deployment.status === "deploying" ? "deploy_deploying" : "deploy_timeout"
+    }),
+    summary: networkHint ? `${app.name} deploy ${deployment.id} still ${deployment.status} (transient: ${networkHint}) — call percher_wait_for_deploy again.` : `${app.name} deploy ${deployment.id} still ${deployment.status} — call percher_wait_for_deploy again.`
+  };
+}
+function secondsSinceCreated(deployment) {
+  const t = Date.parse(deployment.createdAt);
+  if (Number.isNaN(t))
+    return 0;
+  return Math.max(0, Math.round((Date.now() - t) / 1000));
+}
 
 // ../core/dist/commands/doctor.js
 var doctorInputSchema = exports_external.object({
@@ -107440,17 +107688,19 @@ async function doctor(ctx, input = {}) {
       message: diag.container.running ? "Running" : diag.container.state === "not-found" ? "No container found" : `State: ${diag.container.state}`
     });
     if (diag.containerHealth) {
+      const latency = diag.containerHealth.latencyMs != null ? ` (${diag.containerHealth.latencyMs}ms)` : "";
       checks3.push({
         name: "Container health",
         status: diag.containerHealth.healthy ? "pass" : "fail",
-        message: diag.containerHealth.healthy ? `${diag.containerHealth.path} OK (${diag.containerHealth.latencyMs}ms)` : `${diag.containerHealth.path} — not responding`
+        message: diag.containerHealth.healthy ? `${diag.containerHealth.path} OK${latency}` : `${diag.containerHealth.path} — not responding`
       });
     }
     if (diag.publicRoute) {
+      const latency = diag.publicRoute.latencyMs != null ? ` (${diag.publicRoute.latencyMs}ms)` : "";
       checks3.push({
         name: "Public route",
         status: diag.publicRoute.healthy ? "pass" : "fail",
-        message: diag.publicRoute.healthy ? `${diag.publicRoute.url} (${diag.publicRoute.latencyMs}ms)` : `${diag.publicRoute.url} — not responding`
+        message: diag.publicRoute.healthy ? `${diag.publicRoute.url}${latency}` : `${diag.publicRoute.url} — not responding`
       });
     }
     if (diag.pocketbase) {
@@ -107636,11 +107886,53 @@ function summarize(checks3, vctx = {}) {
     summary: verdict.summary
   };
 }
-function deriveVerdict(checks3, vctx) {
+function buildVerdictRuleContext(checks3, vctx) {
   const findCheck = (name) => checks3.find((c) => c.name === name);
-  const auth = findCheck("Auth token");
-  if (auth?.status === "fail") {
+  const toml = findCheck("percher.toml");
+  const verdictChecks = vctx.appProvided && toml?.status === "fail" ? checks3.filter((c) => c.name !== "percher.toml") : checks3;
+  const containerDown = vctx.containerRunning === false && vctx.containerState !== undefined && vctx.containerState !== "not-found" || vctx.containerHealthy === false;
+  return { checks: checks3, vctx, findCheck, verdictChecks, containerDown };
+}
+function runtimeCrashExplanation({ vctx, findCheck }) {
+  const containerCheck = findCheck("Container");
+  const healthCheck = findCheck("Container health");
+  const lastCrashCheck = findCheck("Last crash");
+  const explanationBits = [];
+  if (vctx.appStatus === "crashed")
+    explanationBits.push("App is in crashed state.");
+  if (containerCheck?.status === "fail")
+    explanationBits.push(containerCheck.message);
+  if (healthCheck?.status === "fail")
+    explanationBits.push(healthCheck.message);
+  if (lastCrashCheck)
+    explanationBits.push(lastCrashCheck.message);
+  return explanationBits.length > 0 ? explanationBits.join(" ") : "Runtime is not responding — container or health check is failing.";
+}
+var FALLBACK_RULE = {
+  id: "unknown-fallback",
+  when: () => true,
+  verdict: ({ verdictChecks }) => {
+    const firstFailed = verdictChecks.find((c) => c.status === "fail");
     return {
+      status: "needs_action",
+      diagnosis: firstFailed ? {
+        title: firstFailed.name,
+        explanation: firstFailed.message,
+        reasonCode: "unknown"
+      } : undefined,
+      recovery: recoveryAsk({
+        prompt: firstFailed ? `Doctor flagged a problem: ${firstFailed.name} — ${firstFailed.message}. Review the checks list and surface the failing item to the user.` : "Doctor reported one or more issues. Review the checks list and surface the failing items to the user.",
+        reasonCode: "unknown"
+      }),
+      summary: firstFailed ? `${firstFailed.name} failed: ${firstFailed.message}` : "Doctor reported issues — review the checks list."
+    };
+  }
+};
+var VERDICT_RULES = [
+  {
+    id: "auth-missing",
+    when: ({ findCheck }) => findCheck("Auth token")?.status === "fail",
+    verdict: () => ({
       status: "blocked",
       diagnosis: {
         title: "Authentication required",
@@ -107650,173 +107942,215 @@ function deriveVerdict(checks3, vctx) {
       },
       recovery: recoveryLogin({ reasonCode: "auth_required" }),
       summary: "Login required: run `percher login` (or set PERCHER_TOKEN)."
-    };
-  }
-  const api2 = findCheck("API reachability");
-  if (api2?.status === "fail") {
-    return {
-      status: "blocked",
-      diagnosis: {
-        title: "Percher API is unreachable",
-        explanation: api2.message,
-        reasonCode: "infra_unavailable",
-        phase: "infra"
-      },
-      recovery: recoveryAsk({
-        prompt: `Percher API is unreachable (${api2.message}). This is usually a transient network issue — wait a moment and try again, or check status.percher.app.`,
-        reasonCode: "infra_unavailable",
-        retryable: true
-      }),
-      summary: "Cannot reach the Percher API — try again in a moment."
-    };
-  }
-  const toml = findCheck("percher.toml");
-  if (toml?.status === "fail" && !vctx.appProvided) {
-    return {
-      status: "blocked",
-      diagnosis: {
-        title: "Invalid percher.toml",
-        explanation: toml.message,
-        reasonCode: "config_invalid",
-        phase: "config"
-      },
-      recovery: recoveryFixConfig({
-        problems: [
-          {
-            file: "percher.toml",
-            message: toml.message
-          }
-        ],
-        reasonCode: "config_invalid"
-      }),
-      summary: "percher.toml is invalid — fix the issues and re-run."
-    };
-  }
-  const app = findCheck("App");
-  if (app?.status === "skip") {
-    return {
-      status: "blocked",
-      diagnosis: {
-        title: "No app specified",
-        explanation: app.message,
-        reasonCode: "config_missing",
-        phase: "config"
-      },
-      recovery: recoveryAsk({
-        prompt: `${app.message} — pass \`--app <name>\` or run \`percher init\` in a project directory to generate a percher.toml.`,
-        reasonCode: "config_missing"
-      }),
-      summary: "No percher.toml found and no --app supplied — pass --app or run percher init."
-    };
-  }
-  const inTransitionalDeploy = !!vctx.lastDeployStatus && TRANSITIONAL_DEPLOY_STATUSES.has(vctx.lastDeployStatus);
-  const inTransitionalApp = !!vctx.appStatus && TRANSITIONAL_APP_STATUSES.has(vctx.appStatus);
-  if (inTransitionalDeploy || inTransitionalApp) {
-    const reasonCode = vctx.lastDeployStatus === "queued" ? "deploy_queued" : vctx.lastDeployStatus === "building" ? "deploy_building" : vctx.lastDeployStatus === "deploying" ? "deploy_deploying" : "deploy_queued";
-    const what = inTransitionalApp ? `App ${vctx.appName ?? ""} is provisioning` : `Last deploy is ${vctx.lastDeployStatus}`;
-    const recovery = vctx.lastDeployId && vctx.appName ? recoveryWait({
-      app: vctx.appName,
-      deployId: vctx.lastDeployId,
-      reasonCode
-    }) : recoveryAsk({
-      prompt: `${what.trim()} for ${vctx.appName ?? "this app"}. Wait for it to finish before retrying — there's no deployId to track yet.`,
-      reasonCode
-    });
-    return {
-      status: "in_progress",
-      diagnosis: {
-        title: what.trim(),
-        explanation: vctx.lastDeployId ? `${what.trim()} (deploy ${vctx.lastDeployId}). Wait for it to finish before retrying.` : `${what.trim()}. Wait for it to finish before retrying.`,
-        reasonCode,
-        phase: "deploy"
-      },
-      recovery,
-      summary: vctx.lastDeployId ? `${what.trim()} — wait for deploy ${vctx.lastDeployId}.` : `${what.trim()} — wait a moment and re-run.`
-    };
-  }
-  const verdictChecks = vctx.appProvided && toml?.status === "fail" ? checks3.filter((c) => c.name !== "percher.toml") : checks3;
-  if (vctx.replacedResolution) {
-    const r = vctx.replacedResolution;
-    const isResolvedLive = r.recovery.nextAction === "none" && !!r.url;
-    if (isResolvedLive) {
+    })
+  },
+  {
+    id: "api-unreachable",
+    when: ({ findCheck }) => findCheck("API reachability")?.status === "fail",
+    verdict: ({ findCheck }) => {
+      const message = findCheck("API reachability")?.message ?? "";
       return {
-        status: "ok",
-        recovery: { ...r.recovery, reasonCode: "replaced_by_newer" },
-        summary: r.summary
+        status: "blocked",
+        diagnosis: {
+          title: "Percher API is unreachable",
+          explanation: message,
+          reasonCode: "infra_unavailable",
+          phase: "infra"
+        },
+        recovery: recoveryAsk({
+          prompt: `Percher API is unreachable (${message}). This is usually a transient network issue — wait a moment and try again, or check status.percher.app.`,
+          reasonCode: "infra_unavailable",
+          retryable: true
+        }),
+        summary: "Cannot reach the Percher API — try again in a moment."
       };
     }
-    const status = r.recovery.nextAction === "wait_deploy" ? "in_progress" : "needs_action";
-    return {
-      status,
-      diagnosis: {
-        title: "Last deploy was replaced",
-        explanation: r.summary,
-        reasonCode: "replaced_by_newer",
-        phase: "deploy"
-      },
-      recovery: { ...r.recovery, reasonCode: "replaced_by_newer" },
-      summary: r.summary
-    };
-  }
-  if (vctx.lastDeployStatus === "failed") {
-    if (vctx.inputMode === "deploy") {
-      const cls = vctx.buildLogClassification;
-      if (cls && cls.errorClass === "missing_env" && cls.missingEnvVars.length > 0) {
-        return {
-          status: "needs_action",
-          diagnosis: {
-            title: cls.title,
-            explanation: cls.explanation,
-            reasonCode: "missing_env",
-            phase: "build"
-          },
-          recovery: recoveryEnv({
-            app: vctx.appName,
-            keys: cls.missingEnvVars
-          }),
-          summary: vctx.appName ? `Build failed — missing env vars on ${vctx.appName}: ${cls.missingEnvVars.join(", ")}.` : `Build failed — missing env vars: ${cls.missingEnvVars.join(", ")}.`
-        };
-      }
-      const fileProblems = (vctx.buildProblems ?? []).filter((p) => p.file).map(buildProblemToRecoveryProblem);
-      if (fileProblems.length > 0) {
-        return {
-          status: "needs_action",
-          diagnosis: {
-            title: cls?.title ?? "Build failed with file-located problems",
-            explanation: cls?.explanation ?? `Build extracted ${fileProblems.length} structured problem${fileProblems.length === 1 ? "" : "s"} with file locations. Patch the files directly.`,
-            reasonCode: "build_failed",
-            phase: "build"
-          },
-          recovery: recoveryFixProblems({
-            problems: fileProblems,
-            reasonCode: "build_failed"
-          }),
-          summary: vctx.lastDeployId ? `Deploy ${vctx.lastDeployId} failed — ${fileProblems.length} structured problem${fileProblems.length === 1 ? "" : "s"} to patch.` : `Build failed — ${fileProblems.length} structured problem${fileProblems.length === 1 ? "" : "s"} to patch.`
-        };
-      }
+  },
+  {
+    id: "toml-invalid",
+    when: ({ vctx, findCheck }) => findCheck("percher.toml")?.status === "fail" && !vctx.appProvided,
+    verdict: ({ findCheck }) => {
+      const message = findCheck("percher.toml")?.message ?? "";
       return {
-        status: "needs_action",
+        status: "blocked",
         diagnosis: {
-          title: cls?.title ?? "Last deploy failed",
-          explanation: cls ? `${cls.explanation} Doctor couldn't extract a structured fix; fall back to the build log.` : vctx.lastDeployId ? `Deploy ${vctx.lastDeployId} terminated in failed state. Doctor couldn't classify the cause from the build log; inspect it directly.` : "The most recent deploy ended in failed state. Doctor couldn't classify the cause; inspect the build log.",
-          reasonCode: "build_failed",
-          phase: "build"
+          title: "Invalid percher.toml",
+          explanation: message,
+          reasonCode: "config_invalid",
+          phase: "config"
         },
-        recovery: recoveryInspectBuildLog({
-          deployId: vctx.lastDeployId,
-          app: vctx.appName,
-          reasonCode: "build_failed"
+        recovery: recoveryFixConfig({
+          problems: [
+            {
+              file: "percher.toml",
+              message
+            }
+          ],
+          reasonCode: "config_invalid"
         }),
-        summary: vctx.lastDeployId ? `Deploy ${vctx.lastDeployId} failed — inspect the build log.` : "Last deploy failed — inspect the latest failed deploy's build log."
+        summary: "percher.toml is invalid — fix the issues and re-run."
       };
     }
-    return {
-      status: "needs_action",
-      diagnosis: {
-        title: "Last deploy failed",
-        explanation: vctx.lastDeployId ? `Deploy ${vctx.lastDeployId} terminated in failed state. Inspect the build log to find the cause.` : "The most recent deploy ended in failed state. Inspect the build log to find the cause.",
-        reasonCode: "build_failed",
-        phase: "build"
+  },
+  {
+    id: "app-unresolved",
+    when: ({ findCheck }) => findCheck("App")?.status === "skip",
+    verdict: ({ findCheck }) => {
+      const message = findCheck("App")?.message ?? "";
+      return {
+        status: "blocked",
+        diagnosis: {
+          title: "No app specified",
+          explanation: message,
+          reasonCode: "config_missing",
+          phase: "config"
+        },
+        recovery: recoveryAsk({
+          prompt: `${message} — pass \`--app <name>\` or run \`percher init\` in a project directory to generate a percher.toml.`,
+          reasonCode: "config_missing"
+        }),
+        summary: "No percher.toml found and no --app supplied — pass --app or run percher init."
+      };
+    }
+  },
+  {
+    id: "deploy-transitional",
+    when: ({ vctx }) => !!vctx.lastDeployStatus && TRANSITIONAL_DEPLOY_STATUSES.has(vctx.lastDeployStatus) || !!vctx.appStatus && TRANSITIONAL_APP_STATUSES.has(vctx.appStatus),
+    verdict: ({ vctx }) => {
+      const inTransitionalApp = !!vctx.appStatus && TRANSITIONAL_APP_STATUSES.has(vctx.appStatus);
+      const reasonCode = vctx.lastDeployStatus === "queued" ? "deploy_queued" : vctx.lastDeployStatus === "building" ? "deploy_building" : vctx.lastDeployStatus === "deploying" ? "deploy_deploying" : "deploy_queued";
+      const what = inTransitionalApp ? `App ${vctx.appName ?? ""} is provisioning` : `Last deploy is ${vctx.lastDeployStatus}`;
+      const recovery = vctx.lastDeployId && vctx.appName ? recoveryWait({
+        app: vctx.appName,
+        deployId: vctx.lastDeployId,
+        reasonCode
+      }) : recoveryAsk({
+        prompt: `${what.trim()} for ${vctx.appName ?? "this app"}. Wait for it to finish before retrying — there's no deployId to track yet.`,
+        reasonCode
+      });
+      return {
+        status: "in_progress",
+        diagnosis: {
+          title: what.trim(),
+          explanation: vctx.lastDeployId ? `${what.trim()} (deploy ${vctx.lastDeployId}). Wait for it to finish before retrying.` : `${what.trim()}. Wait for it to finish before retrying.`,
+          reasonCode,
+          phase: "deploy"
+        },
+        recovery,
+        summary: vctx.lastDeployId ? `${what.trim()} — wait for deploy ${vctx.lastDeployId}.` : `${what.trim()} — wait a moment and re-run.`
+      };
+    }
+  },
+  {
+    id: "deploy-replaced",
+    when: ({ vctx }) => !!vctx.replacedResolution,
+    verdict: (ctx) => {
+      const r = ctx.vctx.replacedResolution;
+      if (!r)
+        return FALLBACK_RULE.verdict(ctx);
+      const isResolvedLive = r.recovery.nextAction === "none" && !!r.url;
+      if (isResolvedLive) {
+        return {
+          status: "ok",
+          recovery: { ...r.recovery, reasonCode: "replaced_by_newer" },
+          summary: r.summary
+        };
+      }
+      const status = r.recovery.nextAction === "wait_deploy" ? "in_progress" : "needs_action";
+      return {
+        status,
+        diagnosis: {
+          title: "Last deploy was replaced",
+          explanation: r.summary,
+          reasonCode: "replaced_by_newer",
+          phase: "deploy"
+        },
+        recovery: { ...r.recovery, reasonCode: "replaced_by_newer" },
+        summary: r.summary
+      };
+    }
+  },
+  {
+    id: "deploy-failed-missing-env",
+    when: ({ vctx }) => {
+      const cls = vctx.buildLogClassification;
+      return vctx.lastDeployStatus === "failed" && vctx.inputMode === "deploy" && !!cls && cls.errorClass === "missing_env" && cls.missingEnvVars.length > 0;
+    },
+    verdict: (ctx) => {
+      const { vctx } = ctx;
+      const cls = vctx.buildLogClassification;
+      if (!cls)
+        return FALLBACK_RULE.verdict(ctx);
+      return {
+        status: "needs_action",
+        diagnosis: {
+          title: cls.title,
+          explanation: cls.explanation,
+          reasonCode: "missing_env",
+          phase: "build"
+        },
+        recovery: recoveryEnv({
+          app: vctx.appName,
+          keys: cls.missingEnvVars
+        }),
+        summary: vctx.appName ? `Build failed — missing env vars on ${vctx.appName}: ${cls.missingEnvVars.join(", ")}.` : `Build failed — missing env vars: ${cls.missingEnvVars.join(", ")}.`
+      };
+    }
+  },
+  {
+    id: "deploy-failed-file-problems",
+    when: ({ vctx }) => vctx.lastDeployStatus === "failed" && vctx.inputMode === "deploy" && (vctx.buildProblems ?? []).filter((p) => p.file).length > 0,
+    verdict: ({ vctx }) => {
+      const cls = vctx.buildLogClassification;
+      const fileProblems = (vctx.buildProblems ?? []).filter((p) => p.file).map(buildProblemToRecoveryProblem);
+      return {
+        status: "needs_action",
+        diagnosis: {
+          title: cls?.title ?? "Build failed with file-located problems",
+          explanation: cls?.explanation ?? `Build extracted ${fileProblems.length} structured problem${fileProblems.length === 1 ? "" : "s"} with file locations. Patch the files directly.`,
+          reasonCode: "build_failed",
+          phase: "build"
+        },
+        recovery: recoveryFixProblems({
+          problems: fileProblems,
+          reasonCode: "build_failed"
+        }),
+        summary: vctx.lastDeployId ? `Deploy ${vctx.lastDeployId} failed — ${fileProblems.length} structured problem${fileProblems.length === 1 ? "" : "s"} to patch.` : `Build failed — ${fileProblems.length} structured problem${fileProblems.length === 1 ? "" : "s"} to patch.`
+      };
+    }
+  },
+  {
+    id: "deploy-failed-inspect-log",
+    when: ({ vctx }) => vctx.lastDeployStatus === "failed" && vctx.inputMode === "deploy",
+    verdict: ({ vctx }) => {
+      const cls = vctx.buildLogClassification;
+      return {
+        status: "needs_action",
+        diagnosis: {
+          title: cls?.title ?? "Last deploy failed",
+          explanation: cls ? `${cls.explanation} Doctor couldn't extract a structured fix; fall back to the build log.` : vctx.lastDeployId ? `Deploy ${vctx.lastDeployId} terminated in failed state. Doctor couldn't classify the cause from the build log; inspect it directly.` : "The most recent deploy ended in failed state. Doctor couldn't classify the cause; inspect the build log.",
+          reasonCode: "build_failed",
+          phase: "build"
+        },
+        recovery: recoveryInspectBuildLog({
+          deployId: vctx.lastDeployId,
+          app: vctx.appName,
+          reasonCode: "build_failed"
+        }),
+        summary: vctx.lastDeployId ? `Deploy ${vctx.lastDeployId} failed — inspect the build log.` : "Last deploy failed — inspect the latest failed deploy's build log."
+      };
+    }
+  },
+  {
+    id: "deploy-failed-dispatch",
+    when: ({ vctx }) => vctx.lastDeployStatus === "failed",
+    verdict: ({ vctx }) => ({
+      status: "needs_action",
+      diagnosis: {
+        title: "Last deploy failed",
+        explanation: vctx.lastDeployId ? `Deploy ${vctx.lastDeployId} terminated in failed state. Inspect the build log to find the cause.` : "The most recent deploy ended in failed state. Inspect the build log to find the cause.",
+        reasonCode: "build_failed",
+        phase: "build"
       },
       recovery: {
         retryable: false,
@@ -107830,10 +108164,12 @@ function deriveVerdict(checks3, vctx) {
         reasonCode: "build_failed"
       },
       summary: vctx.lastDeployId ? `Deploy ${vctx.lastDeployId} failed — call percher_doctor with mode='deploy'.` : "Last deploy failed — call percher_doctor with mode='deploy'."
-    };
-  }
-  if (vctx.appStatus === "suspended") {
-    return {
+    })
+  },
+  {
+    id: "app-suspended",
+    when: ({ vctx }) => vctx.appStatus === "suspended",
+    verdict: ({ vctx }) => ({
       status: "needs_action",
       diagnosis: {
         title: "App is suspended",
@@ -107846,33 +108182,27 @@ function deriveVerdict(checks3, vctx) {
         prompt: vctx.appName ? `${vctx.appName} is suspended. Resume the app from the dashboard (or call the unsuspend API) before retrying.` : "This app is suspended. Resume it from the dashboard before retrying."
       }),
       summary: vctx.appName ? `${vctx.appName} is suspended — resume the app before retrying.` : "App is suspended — resume it before retrying."
-    };
-  }
-  if (verdictChecks.every((c) => c.status === "pass" || c.status === "skip" || c.status === "warn")) {
-    const passing = verdictChecks.filter((c) => c.status === "pass").length;
-    const noun = passing === 1 ? "check" : "checks";
-    return {
-      status: "ok",
-      recovery: recoveryNone({ reasonCode: "none" }),
-      summary: vctx.appName ? `All ${passing} ${noun} passed for ${vctx.appName}.` : `All ${passing} ${noun} passed.`
-    };
-  }
-  const containerDown = vctx.containerRunning === false && vctx.containerState !== undefined && vctx.containerState !== "not-found" || vctx.containerHealthy === false;
-  if (vctx.appStatus === "crashed" || containerDown) {
-    const containerCheck = findCheck("Container");
-    const healthCheck = findCheck("Container health");
-    const lastCrashCheck = findCheck("Last crash");
-    const explanationBits = [];
-    if (vctx.appStatus === "crashed")
-      explanationBits.push("App is in crashed state.");
-    if (containerCheck?.status === "fail")
-      explanationBits.push(containerCheck.message);
-    if (healthCheck?.status === "fail")
-      explanationBits.push(healthCheck.message);
-    if (lastCrashCheck)
-      explanationBits.push(lastCrashCheck.message);
-    const explanation = explanationBits.length > 0 ? explanationBits.join(" ") : "Runtime is not responding — container or health check is failing.";
-    if (vctx.inputMode === "runtime") {
+    })
+  },
+  {
+    id: "all-healthy",
+    when: ({ verdictChecks }) => verdictChecks.every((c) => c.status === "pass" || c.status === "skip" || c.status === "warn"),
+    verdict: ({ vctx, verdictChecks }) => {
+      const passing = verdictChecks.filter((c) => c.status === "pass").length;
+      const noun = passing === 1 ? "check" : "checks";
+      return {
+        status: "ok",
+        recovery: recoveryNone({ reasonCode: "none" }),
+        summary: vctx.appName ? `All ${passing} ${noun} passed for ${vctx.appName}.` : `All ${passing} ${noun} passed.`
+      };
+    }
+  },
+  {
+    id: "runtime-crashed-report",
+    when: ({ vctx, containerDown }) => (vctx.appStatus === "crashed" || containerDown) && vctx.inputMode === "runtime",
+    verdict: (ctx) => {
+      const { vctx } = ctx;
+      const explanation = runtimeCrashExplanation(ctx);
       const cr = vctx.crashReport;
       const hasAnalysis = cr && cr.analysisStatus === "completed";
       const promptParts = [];
@@ -107909,58 +108239,62 @@ ${cr.logs.join(`
         summary: vctx.appName ? hasAnalysis ? `${vctx.appName} crashed — ${cr.suggestion ?? cr.explanation ?? "surface the crash details to the user."}` : `${vctx.appName} runtime is unhealthy — surface the crash details to the user.` : "Runtime is unhealthy — surface the crash details to the user."
       };
     }
-    return {
-      status: "needs_action",
-      diagnosis: {
-        title: vctx.appStatus === "crashed" ? "App crashed" : "Runtime not responding",
-        explanation,
-        reasonCode: "runtime_crashed",
-        phase: "runtime"
-      },
-      recovery: {
-        retryable: false,
-        nextAction: "run_doctor",
-        suggestedTool: "percher_doctor",
-        args: { app: vctx.appName, mode: "runtime" },
-        reasonCode: "runtime_crashed"
-      },
-      summary: vctx.appName ? `${vctx.appName} runtime needs investigation — call percher_doctor with mode='runtime'.` : "Runtime needs investigation — call percher_doctor with mode='runtime'."
-    };
-  }
-  if (vctx.publicRouteHealthy === false) {
-    const routeCheck = findCheck("Public route");
-    return {
-      status: "needs_action",
-      diagnosis: {
-        title: "Public route is not responding",
-        explanation: routeCheck?.message ?? "Container looks healthy but the public URL isn't responding — route reconcile usually self-heals.",
-        reasonCode: "infra_transient",
-        phase: "infra"
-      },
-      recovery: {
-        retryable: true,
-        nextAction: "retry",
-        suggestedTool: "percher_doctor",
-        args: { app: vctx.appName },
-        reasonCode: "infra_transient"
-      },
-      summary: vctx.appName ? `${vctx.appName} public route is failing — likely transient, re-run doctor in a moment.` : "Public route is failing — likely transient, re-run doctor in a moment."
-    };
-  }
-  const firstFailed = verdictChecks.find((c) => c.status === "fail");
-  return {
-    status: "needs_action",
-    diagnosis: firstFailed ? {
-      title: firstFailed.name,
-      explanation: firstFailed.message,
-      reasonCode: "unknown"
-    } : undefined,
-    recovery: recoveryAsk({
-      prompt: firstFailed ? `Doctor flagged a problem: ${firstFailed.name} — ${firstFailed.message}. Review the checks list and surface the failing item to the user.` : "Doctor reported one or more issues. Review the checks list and surface the failing items to the user.",
-      reasonCode: "unknown"
-    }),
-    summary: firstFailed ? `${firstFailed.name} failed: ${firstFailed.message}` : "Doctor reported issues — review the checks list."
-  };
+  },
+  {
+    id: "runtime-crashed-dispatch",
+    when: ({ vctx, containerDown }) => vctx.appStatus === "crashed" || containerDown,
+    verdict: (ctx) => {
+      const { vctx } = ctx;
+      const explanation = runtimeCrashExplanation(ctx);
+      return {
+        status: "needs_action",
+        diagnosis: {
+          title: vctx.appStatus === "crashed" ? "App crashed" : "Runtime not responding",
+          explanation,
+          reasonCode: "runtime_crashed",
+          phase: "runtime"
+        },
+        recovery: {
+          retryable: false,
+          nextAction: "run_doctor",
+          suggestedTool: "percher_doctor",
+          args: { app: vctx.appName, mode: "runtime" },
+          reasonCode: "runtime_crashed"
+        },
+        summary: vctx.appName ? `${vctx.appName} runtime needs investigation — call percher_doctor with mode='runtime'.` : "Runtime needs investigation — call percher_doctor with mode='runtime'."
+      };
+    }
+  },
+  {
+    id: "public-route-unhealthy",
+    when: ({ vctx }) => vctx.publicRouteHealthy === false,
+    verdict: ({ vctx, findCheck }) => {
+      const routeCheck = findCheck("Public route");
+      return {
+        status: "needs_action",
+        diagnosis: {
+          title: "Public route is not responding",
+          explanation: routeCheck?.message ?? "Container looks healthy but the public URL isn't responding — route reconcile usually self-heals.",
+          reasonCode: "infra_transient",
+          phase: "infra"
+        },
+        recovery: {
+          retryable: true,
+          nextAction: "retry",
+          suggestedTool: "percher_doctor",
+          args: { app: vctx.appName },
+          reasonCode: "infra_transient"
+        },
+        summary: vctx.appName ? `${vctx.appName} public route is failing — likely transient, re-run doctor in a moment.` : "Public route is failing — likely transient, re-run doctor in a moment."
+      };
+    }
+  },
+  FALLBACK_RULE
+];
+function deriveVerdict(checks3, vctx) {
+  const ctx = buildVerdictRuleContext(checks3, vctx);
+  const rule = VERDICT_RULES.find((r) => r.when(ctx)) ?? FALLBACK_RULE;
+  return rule.verdict(ctx);
 }
 // ../core/dist/commands/domains.js
 var domainAddInputSchema = exports_external.object({
@@ -108994,31 +109328,6 @@ async function login(ctx, input = {}) {
     code: "login.expired"
   });
 }
-// ../shared/dist/logs.js
-var MAX_LOG_SEARCH_LENGTH = 256;
-// ../shared/dist/platform-env.js
-var PERCHER_INJECTED_ENV_KEYS = new Set([
-  "NODE_ENV",
-  "PORT",
-  "DATABASE_URL",
-  "POCKETBASE_URL",
-  "POCKETBASE_ADMIN_EMAIL",
-  "POCKETBASE_ADMIN_PASSWORD",
-  "PERCHER_APP_NAME",
-  "PERCHER_APP_URL",
-  "HTTP_PROXY",
-  "HTTPS_PROXY",
-  "NO_PROXY",
-  "NODE_USE_ENV_PROXY"
-]);
-var PROXY_LOWERCASE_ALIASES = new Set([
-  "http_proxy",
-  "https_proxy",
-  "no_proxy"
-]);
-// ../shared/dist/runtime.js
-var DEFAULT_NODE_VERSION_MAJOR = "24";
-var DEFAULT_NODE_VERSION_LABEL = `${DEFAULT_NODE_VERSION_MAJOR} LTS`;
 // ../core/dist/commands/logs.js
 var logsInputSchema = exports_external.object({
   app: exports_external.string().optional(),
@@ -110661,6 +110970,45 @@ async function open(ctx, input = {}) {
   await ctx.openUrl(app.url);
   return app.url;
 }
+// ../core/dist/commands/preview-branch.js
+var previewBranchSetInputSchema = exports_external.object({
+  app: exports_external.string().optional(),
+  branch: exports_external.string().min(1, "Branch is required")
+});
+var previewBranchInputSchema = exports_external.object({
+  app: exports_external.string().optional()
+});
+function resolveApp3(ctx, app) {
+  const name = app ?? readPercherTomlAppName(ctx.cwd);
+  if (!name) {
+    throw new PercherCoreError("No app specified and no percher.toml found", {
+      code: "env.no-app",
+      hint: "Pass an app name or run from a directory with percher.toml."
+    });
+  }
+  return name;
+}
+async function previewBranchSet(ctx, input) {
+  const appRef = resolveApp3(ctx, input.app);
+  return ctx.client.apps.setPreviewBranch(appRef, input.branch);
+}
+async function previewBranchUnset(ctx, input = {}) {
+  const appRef = resolveApp3(ctx, input.app);
+  return ctx.client.apps.unsetPreviewBranch(appRef);
+}
+var setPreviewBranchToolInputSchema = exports_external.object({
+  app: exports_external.string().optional(),
+  branch: exports_external.string().nullable().describe("Branch to pin as the preview address; pass null to clear it.")
+});
+async function previewBranchShow(ctx, input = {}) {
+  const appRef = resolveApp3(ctx, input.app);
+  const app = await ctx.client.apps.get(appRef);
+  return {
+    previewBranch: app.previewBranch ?? null,
+    previewUrl: app.previewUrl ?? null,
+    status: app.previewStatus ?? "disabled"
+  };
+}
 // ../core/dist/commands/publish.js
 import { existsSync as existsSync14 } from "node:fs";
 import { join as join20 } from "node:path";
@@ -110796,10 +111144,10 @@ async function pollDeployment(opts) {
         polled = true;
       } catch (err) {
         attempt++;
-        const msg = err.message ?? String(err);
-        const isNetwork = msg.startsWith("network error:");
+        const isNetwork = isTransientNetworkError(err);
         if (!isNetwork || attempt >= maxRetries) {
           if (isNetwork) {
+            const msg = err.message ?? String(err);
             throw new Error(`${msg}
 
 The deploy may already be live — your network connection dropped mid-poll. Check with: percher deploys list ${opts.appName}`, { cause: err });
@@ -110961,7 +111309,7 @@ function classifyDeployRetry(err, attempt) {
       category: "non_retryable"
     };
   }
-  if (err instanceof Error && /network error|fetch failed|ECONNRESET|ENOTFOUND|ETIMEDOUT/i.test(err.message)) {
+  if (isTransientNetworkError(err)) {
     const delay = NETWORK_BACKOFF_MS[idx];
     if (delay === undefined) {
       return {
@@ -111096,6 +111444,12 @@ function* walkDir(dir, base) {
 }
 
 // ../core/dist/commands/publish-api-error.js
+var DEPLOY_GATE_CODES = new Set([
+  "RETRY_LIMIT_REACHED",
+  "REQUIRED_ENV_MISSING",
+  "ENV_KEY_UNDECLARED",
+  "DAILY_QUOTA_EXCEEDED"
+]);
 function classifyPublishApiError(err, input) {
   if (!(err instanceof PercherApiError))
     return null;
@@ -111120,6 +111474,18 @@ function classifyPublishApiError(err, input) {
   const auth = matchAuthError(err);
   if (auth)
     return buildResult(auth, input);
+  const retryLimit = matchRetryLimitReached(err, input);
+  if (retryLimit)
+    return buildResult(retryLimit, input);
+  const requiredEnv = matchRequiredEnvMissing(err, input);
+  if (requiredEnv)
+    return buildResult(requiredEnv, input);
+  const undeclaredEnv = matchEnvKeyUndeclared(err, input);
+  if (undeclaredEnv)
+    return buildResult(undeclaredEnv, input);
+  const dailyQuota = matchDailyQuotaExceeded(err, input);
+  if (dailyQuota)
+    return buildResult(dailyQuota, input);
   const clientError = matchGenericClientError(err);
   if (clientError)
     return buildResult(clientError, input);
@@ -111128,12 +111494,17 @@ function classifyPublishApiError(err, input) {
 function buildResult(c, input) {
   return {
     status: "failed",
+    ...input.app !== undefined ? { app: input.app } : {},
     fileCount: input.bundle.fileCount,
     bytes: input.bundle.bytes,
     error: {
       title: c.title,
       explanation: c.explanation,
-      suggestion: c.suggestion
+      suggestion: c.suggestion,
+      ...c.errorClass !== undefined ? { errorClass: c.errorClass } : {},
+      ...c.phase !== undefined ? { phase: c.phase } : {},
+      ...c.missingEnvVars !== undefined ? { missingEnvVars: c.missingEnvVars } : {},
+      ...c.relevantFiles !== undefined ? { relevantFiles: c.relevantFiles } : {}
     },
     recovery: c.recovery,
     summary: c.summary,
@@ -111152,9 +111523,9 @@ function matchPlanLimit(err) {
   return {
     title: "Plan limit reached",
     explanation: err.message,
-    suggestion: "Upgrade your plan at https://percher.app/settings, or delete unused apps with `percher delete <name>`.",
+    suggestion: "Upgrade your plan at https://percher.app/account/billing, or delete unused apps with `percher delete <name>`.",
     recovery: recoveryAsk({
-      prompt: `${err.message}. Upgrade at https://percher.app/settings, or delete an unused app with \`percher delete <name>\`.`,
+      prompt: `${err.message}. Upgrade at https://percher.app/account/billing, or delete an unused app with \`percher delete <name>\`.`,
       options: ["upgrade", "delete unused app", "cancel"],
       reasonCode: "quota_exceeded"
     }),
@@ -111172,7 +111543,7 @@ function matchRateLimit(err) {
   return {
     title: "Rate limit hit",
     explanation: err.message,
-    suggestion: "Wait a few minutes and try again. If you need a higher cap, upgrade at https://percher.app/settings.",
+    suggestion: "Wait a few minutes and try again. If you need a higher cap, upgrade at https://percher.app/account/billing.",
     recovery: recoveryAsk({
       prompt: `Rate limit: ${err.message}. Wait a few minutes then retry, or upgrade your plan.`,
       options: ["wait and retry", "upgrade", "cancel"],
@@ -111190,7 +111561,7 @@ function matchConcurrentLimit(err) {
     explanation: err.message,
     suggestion: "Wait for one of your in-flight deploys to finish, or upgrade your plan to raise the concurrency cap.",
     recovery: recoveryAsk({
-      prompt: `${err.message} Wait for one to finish, or upgrade at https://percher.app/settings.`,
+      prompt: `${err.message} Wait for one to finish, or upgrade at https://percher.app/account/billing.`,
       options: ["wait", "upgrade", "cancel"],
       reasonCode: "deploy_already_in_progress"
     }),
@@ -111265,7 +111636,7 @@ function matchEmailNotVerified(err) {
   return {
     title: "Email not verified",
     explanation: err.message,
-    suggestion: "Open the verification link in your inbox, or visit https://percher.app/settings to resend the email. Re-publish after verifying.",
+    suggestion: "Open the verification link in your inbox, or visit https://percher.app/account to resend the email. Re-publish after verifying.",
     recovery: recoveryAsk({
       prompt: `${err.message} Verify the email, then retry publish.`,
       options: ["check inbox", "open settings"],
@@ -111299,6 +111670,94 @@ function matchAuthError(err) {
     summary: `Permission denied (${err.status} ${err.code || "—"}): ${err.message}`
   };
 }
+function matchRetryLimitReached(err, input) {
+  if (err.code !== "RETRY_LIMIT_REACHED" || input.app === undefined)
+    return null;
+  const appName = input.app.name;
+  const extra = err.extra ?? {};
+  const resetAtStr = extra.resetAt ?? "";
+  const resetAtForPrompt = resetAtStr || "the cooldown window expires";
+  return {
+    title: "Retry limit reached",
+    explanation: "Percher already auto-retried once after an `infra_unavailable` failure for this app within the last 10 minutes. We won't auto-retry again — the next attempt should be a deliberate user decision.",
+    suggestion: `Wait until ${resetAtForPrompt}, then re-run \`percher publish\`. If the failure persists past that, the underlying issue is probably not transient — run \`percher doctor\` to diagnose.`,
+    recovery: recoveryAsk({
+      prompt: `Percher already retried once after an infrastructure failure for ${appName}. Wait until ${resetAtForPrompt} or surface to the user.`,
+      options: ["wait before retrying", "inspect status"],
+      reasonCode: "retry_limit_reached",
+      retryable: false
+    }),
+    summary: `Retry limit reached for ${appName}${resetAtStr ? ` — wait until ${resetAtStr}` : ""}.`
+  };
+}
+function matchRequiredEnvMissing(err, input) {
+  if (err.code !== "REQUIRED_ENV_MISSING" || input.app === undefined)
+    return null;
+  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 {
+    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: input.app.name,
+      keys,
+      reasonCode: "missing_env"
+    }),
+    summary: `Missing required env ${keys.length === 1 ? "key" : "keys"}: ${keys.join(", ")}.`
+  };
+}
+function matchEnvKeyUndeclared(err, input) {
+  if (err.code !== "ENV_KEY_UNDECLARED" || input.app === undefined)
+    return null;
+  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 {
+    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(", ")}.`
+  };
+}
+function matchDailyQuotaExceeded(err, input) {
+  if (err.code !== "DAILY_QUOTA_EXCEEDED" || input.app === undefined)
+    return null;
+  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 {
+    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/account/billing 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/account/billing.`,
+      options: ["wait", `deploy ${otherKind}`, "upgrade"],
+      reasonCode: "quota_exceeded"
+    }),
+    summary: `Daily ${kind}-deploy quota reached (${used}/${limit}). Resets ${resetAt}.`
+  };
+}
 function matchGenericClientError(err) {
   if (err.status < 400 || err.status >= 500)
     return null;
@@ -111362,13 +111821,12 @@ var publishInputSchema = exports_external.object({
   noCache: exports_external.boolean().optional().describe("Skip the image-cache lookup and force a fresh build. Use this when you suspect the cached image doesn't reflect your latest source — the new build's resulting image still gets cached, so future deploys benefit."),
   waitForLive: exports_external.boolean().optional().describe("If true (default), publish blocks until the deploy is live or failed. If false, publish returns as soon as the deploy is queued and the agent can resume with percher_wait_for_deploy. Recommended for AI agents — gives back control quickly with a deployId so they can decide between waiting, asking the user, or working on something else.")
 });
-var MAX_BYTES = 500 * 1024 * 1024;
 var SUSPICIOUS_BYTES = 50 * 1024 * 1024;
 var SUSPICIOUS_FILES = 1e4;
 function tomlPathFor2(cwd) {
   return join20(cwd, "percher.toml");
 }
-async function buildReplacedResult(opts) {
+async function buildReplacedResult2(opts) {
   const { ctx, app, deployment, tarball, cwd } = opts;
   const resolved = await resolveReplaced({
     ctx,
@@ -111406,33 +111864,6 @@ function buildAlreadyInProgressResult(opts) {
     bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes }
   };
 }
-function buildRetryLimitReachedResult(opts) {
-  const { err, app, tarball, cwd } = opts;
-  const extra = err.extra ?? {};
-  const resetAtStr = extra.resetAt ?? "";
-  const resetAtForPrompt = resetAtStr || "the cooldown window expires";
-  const prompt = `Percher already retried once after an infrastructure failure for ${app.name}. Wait until ${resetAtForPrompt} or surface to the user.`;
-  return {
-    status: "failed",
-    app,
-    fileCount: tarball.fileCount,
-    bytes: tarball.bytes,
-    error: {
-      title: "Retry limit reached",
-      explanation: "Percher already auto-retried once after an `infra_unavailable` failure for this app within the last 10 minutes. We won't auto-retry again — the next attempt should be a deliberate user decision.",
-      suggestion: `Wait until ${resetAtForPrompt}, then re-run \`percher publish\`. If the failure persists past that, the underlying issue is probably not transient — run \`percher doctor\` to diagnose.`
-    },
-    recovery: recoveryAsk({
-      prompt,
-      options: ["wait before retrying", "inspect status"],
-      reasonCode: "retry_limit_reached",
-      retryable: false
-    }),
-    summary: `Retry limit reached for ${app.name}${resetAtStr ? ` — wait until ${resetAtStr}` : ""}.`,
-    configPath: tomlPathFor2(cwd),
-    bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes }
-  };
-}
 function buildLiveSummary(opts) {
   const cacheTag = opts.cacheHit ? "cached, " : "";
   const fwSuffix = opts.framework ? ` (${opts.framework}, ${cacheTag}${opts.totalSeconds}s)` : ` (${cacheTag}${opts.totalSeconds}s)`;
@@ -111555,7 +111986,7 @@ ${bullets}`,
   ctx.status("[2/4] Packaging files...");
   const tarball = await createTarball({ cwd: ctx.cwd, config: config2 });
   const packageMs = Date.now() - t0;
-  if (tarball.bytes > MAX_BYTES) {
+  if (tarball.bytes > MAX_TARBALL_BYTES) {
     return {
       status: "failed",
       fileCount: tarball.fileCount,
@@ -111650,12 +112081,26 @@ ${keyList}
       ctx.status(`Build queue wait: ~${preflight.queueWaitEstimateSec}s — your build is queued behind ${preflight.queueDepth} other(s).`);
     }
   } catch {}
+  return executeDeploy({
+    ctx,
+    config: config2,
+    input,
+    app,
+    firstDeploy,
+    tarball,
+    t0,
+    packageMs,
+    missingBuildEnvKeys
+  });
+}
+async function executeDeploy(opts) {
+  const { ctx, config: config2, input, app, firstDeploy, tarball, t0, packageMs, missingBuildEnvKeys } = opts;
   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) {
+  if (!input.noCache && !input.preview) {
     try {
       const probe = await ctx.client.platform.cacheProbe({
         appId: app.id,
@@ -111701,99 +112146,14 @@ ${keyList}
       }
       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}.`,
+      if (err instanceof PercherApiError && DEPLOY_GATE_CODES.has(err.code)) {
+        const classified = classifyPublishApiError(err, {
           configPath: tomlPathFor2(ctx.cwd),
-          bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes }
-        };
+          bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+          app
+        });
+        if (classified)
+          return classified;
       }
       throw err;
     }
@@ -111891,7 +112251,7 @@ ${keyList}
   }
   const buildMs = Date.now() - buildStart;
   if (deployment.status === "replaced") {
-    return await buildReplacedResult({
+    return await buildReplacedResult2({
       ctx,
       app,
       deployment,
@@ -112003,150 +112363,21 @@ async function handleUnauthorized(ctx, config2, tarball, input) {
     token: newToken,
     sessionId: ctx.client.sessionId
   });
+  const t0 = Date.now();
   const freshTarball = await createTarball({ cwd: ctx.cwd, config: config2 });
-  let firstDeployRetry = false;
-  let app;
-  ({ app, firstDeploy: firstDeployRetry } = await ensureApp2(ctx, config2));
-  ctx.status("Uploading...");
-  const freshTarballBytes = new Uint8Array(await new Response(freshTarball.stream).arrayBuffer());
-  const freshIdempotencyKey = crypto.randomUUID();
-  let deployment;
-  try {
-    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({
-        active: deployResponse,
-        app,
-        tarball: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes },
-        cwd: ctx.cwd
-      });
-    }
-    deployment = deployResponse;
-  } catch (err) {
-    if (err instanceof PercherApiError && err.code === "RETRY_LIMIT_REACHED") {
-      return buildRetryLimitReachedResult({
-        err,
-        app,
-        tarball: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes },
-        cwd: ctx.cwd
-      });
-    }
-    throw err;
-  }
-  const replacedPreview = deployment.replacedPreview === true;
-  if (input.waitForLive === false) {
-    ctx.status(`Queued (${deployment.id}) — resume with percher_wait_for_deploy.`);
-    return {
-      status: "queued",
-      app,
-      deployment,
-      fileCount: freshTarball.fileCount,
-      bytes: freshTarball.bytes,
-      replacedPreview: replacedPreview || undefined,
-      firstDeploy: firstDeployRetry || undefined,
-      recovery: recoveryWait({
-        app: app.name,
-        deployId: deployment.id,
-        reasonCode: "deploy_queued"
-      }),
-      summary: `${app.name} deploy ${deployment.id} queued — resume with percher_wait_for_deploy.`,
-      configPath: tomlPathFor2(ctx.cwd),
-      bundle: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes }
-    };
-  }
-  const timeoutMs = TIMEOUTS.clientPublishPoll;
-  const start = Date.now();
-  while (deployment.status !== "live" && deployment.status !== "failed" && deployment.status !== "replaced") {
-    if (Date.now() - start > timeoutMs) {
-      return {
-        status: "failed",
-        app,
-        deployment,
-        fileCount: freshTarball.fileCount,
-        bytes: freshTarball.bytes,
-        error: {
-          title: "Deploy timed out",
-          explanation: "The deployment did not complete within 5 minutes.",
-          suggestion: `Run \`percher doctor --app ${app.name}\` (CLI) or the percher_doctor tool (MCP) to diagnose the stall. Doctor will read deploy state + build log and return a concrete next step.`
-        },
-        recovery: recoveryDoctor({
-          app: app.name,
-          deployId: deployment.id,
-          mode: "deploy",
-          reasonCode: "deploy_stalled"
-        }),
-        summary: `Deploy timed out after 5 minutes (${deployment.id}).`,
-        configPath: tomlPathFor2(ctx.cwd),
-        bundle: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes }
-      };
-    }
-    ctx.status(`${deployment.status}...`);
-    await new Promise((r) => setTimeout(r, 2000));
-    deployment = await ctx.client.apps.getDeployment(app.id, deployment.id);
-  }
-  if (deployment.status === "replaced") {
-    return await buildReplacedResult({
-      ctx,
-      app,
-      deployment,
-      tarball: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes },
-      cwd: ctx.cwd
-    });
-  }
-  if (deployment.status === "failed") {
-    return buildFailureResult({
-      ctx,
-      app,
-      deployment,
-      tarball: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes },
-      input
-    });
-  }
-  const totalSeconds = (Date.now() - start) / 1000;
-  const url2 = deployment.previewUrl ?? deployment.url ?? app.url;
-  ctx.status(`Live at ${url2} (${totalSeconds.toFixed(0)}s)`);
-  return {
-    status: "live",
-    url: url2,
+  const packageMs = Date.now() - t0;
+  const { app, firstDeploy } = await ensureApp2(ctx, config2);
+  return executeDeploy({
+    ctx,
+    config: config2,
+    input,
     app,
-    deployment,
-    timing: {
-      totalSeconds: Math.round(totalSeconds),
-      packageMs: 0,
-      uploadMs: 0,
-      buildMs: 0
-    },
-    fileCount: freshTarball.fileCount,
-    bytes: freshTarball.bytes,
-    replacedPreview,
-    firstDeploy: firstDeployRetry || undefined,
-    recovery: RECOVERY_NONE,
-    cacheHit: deployment.cacheHit,
-    traceId: deployment.id,
-    summary: buildLiveSummary({
-      appName: app.name,
-      url: url2 ?? app.url,
-      totalSeconds: Math.round(totalSeconds),
-      framework: config2.app.framework,
-      preview: input.preview === true,
-      replacedPreview,
-      cacheHit: deployment.cacheHit ?? false
-    }),
-    configPath: tomlPathFor2(ctx.cwd),
-    bundle: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes }
-  };
+    firstDeploy,
+    tarball: freshTarball,
+    t0,
+    packageMs,
+    missingBuildEnvKeys: []
+  });
 }
 async function loadOrGenerate(ctx) {
   const tomlPath = join20(ctx.cwd, "percher.toml");
@@ -112207,7 +112438,6 @@ var pushInputSchema = exports_external.object({
   preview: exports_external.boolean().optional(),
   noCache: exports_external.boolean().optional().describe("Skip the image-cache lookup and force a fresh build.")
 });
-var MAX_BYTES2 = 500 * 1024 * 1024;
 var SUSPICIOUS_BYTES2 = 50 * 1024 * 1024;
 var SUSPICIOUS_FILES2 = 1e4;
 var PLACEHOLDER_PREFIXES = ["add-your-", "your-key-here"];
@@ -112281,7 +112511,7 @@ async function push(ctx, input = {}, internals = {}) {
   await checkPlaceholders(ctx, config2);
   await checkByoSecrets(ctx, config2);
   const tarball = await createTarball({ cwd: ctx.cwd, config: config2 });
-  if (tarball.bytes > MAX_BYTES2) {
+  if (tarball.bytes > MAX_TARBALL_BYTES) {
     throw new PercherCoreError(`Repository is larger than 500 MB (current: ${(tarball.bytes / 1024 / 1024).toFixed(1)} MB)`, {
       code: "push.too-large",
       hint: `Biggest files: ${tarball.topFiles.map((f) => f.path).join(", ")}`,
@@ -112436,10 +112666,10 @@ async function push(ctx, input = {}, internals = {}) {
       const resetAt = extra.resetAt ?? "";
       throw new PercherCoreError(`Daily ${kind}-deploy quota reached (${used}/${limit}). Resets at ${resetAt}.`, {
         code: "push.quota-exceeded",
-        hint: `Wait until ${resetAt} or upgrade your plan at https://percher.app/settings.`,
+        hint: `Wait until ${resetAt} or upgrade your plan at https://percher.app/account/billing.`,
         recovery: {
           ...recoveryAsk({
-            prompt: `Daily ${kind}-deploy quota reached (${used}/${limit}). Counter resets at ${resetAt}. Wait until then or upgrade at https://percher.app/settings.`,
+            prompt: `Daily ${kind}-deploy quota reached (${used}/${limit}). Counter resets at ${resetAt}. Wait until then or upgrade at https://percher.app/account/billing.`,
             reasonCode: "quota_exceeded"
           })
         }
@@ -112593,10 +112823,10 @@ async function redeploy(ctx, input = {}) {
             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.`
+              suggestion: `Wait until the counter resets, deploy a ${otherKind} instead, or upgrade your plan at https://percher.app/account/billing 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.`,
+              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/account/billing.`,
               options: ["wait", `deploy ${otherKind}`, "upgrade"],
               reasonCode: "quota_exceeded"
             }),
@@ -112609,7 +112839,7 @@ async function redeploy(ctx, input = {}) {
           return failureResult({
             title: "Deploy rate limit reached",
             explanation: err.message,
-            suggestion: "Wait a minute or two and try again. Hourly limits scale with your plan; upgrade at https://percher.app/settings to raise it."
+            suggestion: "Wait a minute or two and try again. Hourly limits scale with your plan; upgrade at https://percher.app/account/billing to raise it."
           });
         case "DEPLOY_RATE_LIMITED": {
           const extra = err.extra ?? {};
@@ -112836,6 +113066,8 @@ function failureResult(error48) {
   };
 }
 // ../core/dist/commands/rename.js
+import { existsSync as existsSync16, readFileSync as readFileSync12, writeFileSync as writeFileSync8 } from "node:fs";
+import { join as join22 } from "node:path";
 var renameInputSchema = exports_external.object({
   app: exports_external.string().optional(),
   name: exports_external.string().min(3).max(40)
@@ -112848,12 +113080,33 @@ async function rename(ctx, input) {
       hint: "Pass an app name or run from a directory with percher.toml."
     });
   }
-  return ctx.client.apps.rename(appRef, input.name);
+  const result = await ctx.client.apps.rename(appRef, input.name);
+  return {
+    ...result,
+    tomlUpdated: updateLocalTomlName(ctx.cwd, result.previousName, result.name)
+  };
+}
+function updateLocalTomlName(cwd, oldName, newName) {
+  const p = join22(cwd, "percher.toml");
+  if (!existsSync16(p))
+    return false;
+  try {
+    const src = readFileSync12(p, "utf8");
+    if (parse5(src).app.name !== oldName)
+      return false;
+    const next = src.replace(new RegExp(`(name\\s*=\\s*")${oldName}(")`), `$1${newName}$2`);
+    if (next === src || parse5(next).app.name !== newName)
+      return false;
+    writeFileSync8(p, next);
+    return true;
+  } catch {
+    return false;
+  }
 }
 // ../core/dist/commands/reproduce.js
-import { mkdtempSync, writeFileSync as writeFileSync8 } from "node:fs";
+import { mkdtempSync, writeFileSync as writeFileSync9 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join as join22 } from "node:path";
+import { join as join23 } from "node:path";
 var reproduceInputSchema = exports_external.object({
   app: exports_external.string().optional().describe("App name. Defaults to the [app].name in the current directory's percher.toml."),
   deployId: exports_external.string().describe("Deploy id (e.g. dep_abc123) to reproduce. Required — usually the failed deploy you want to debug.")
@@ -112937,9 +113190,9 @@ async function reproduce(ctx, input) {
     const envMap = await ctx.client.env.list(app.id);
     currentAppEnvKeys = Object.keys(envMap).sort();
   } catch {}
-  const tmpDir = mkdtempSync(join22(tmpdir(), `percher-reproduce-${input.deployId}-`));
-  const tarballPath = join22(tmpDir, "source.tar.gz");
-  writeFileSync8(tarballPath, bytes);
+  const tmpDir = mkdtempSync(join23(tmpdir(), `percher-reproduce-${input.deployId}-`));
+  const tarballPath = join23(tmpDir, "source.tar.gz");
+  writeFileSync9(tarballPath, bytes);
   let extracted = false;
   try {
     const proc = Bun.spawn(["tar", "-xzf", tarballPath, "-C", tmpDir], {
@@ -113177,7 +113430,7 @@ async function rollback(ctx, input, internals = {}) {
 }
 // ../core/dist/commands/sharing.js
 var ShareRoleSchema = exports_external.enum(["viewer", "admin"]);
-function resolveApp3(ctx, app) {
+function resolveApp4(ctx, app) {
   const name = app ?? readPercherTomlAppName(ctx.cwd);
   if (!name) {
     throw new PercherCoreError("No app specified and no percher.toml found", {
@@ -113205,19 +113458,19 @@ var shareRevokeInputSchema = exports_external.object({
   shareId: exports_external.string().min(1, "shareId is required")
 });
 async function shareList(ctx, input = {}) {
-  const appRef = resolveApp3(ctx, input.app);
+  const appRef = resolveApp4(ctx, input.app);
   return ctx.client.sharing.list(appRef);
 }
 async function shareInvite(ctx, input) {
-  const appRef = resolveApp3(ctx, input.app);
+  const appRef = resolveApp4(ctx, input.app);
   return ctx.client.sharing.create(appRef, { email: input.email, role: input.role });
 }
 async function shareSetRole(ctx, input) {
-  const appRef = resolveApp3(ctx, input.app);
+  const appRef = resolveApp4(ctx, input.app);
   return ctx.client.sharing.setRole(appRef, input.shareId, input.role);
 }
 async function shareRevoke(ctx, input) {
-  const appRef = resolveApp3(ctx, input.app);
+  const appRef = resolveApp4(ctx, input.app);
   await ctx.client.sharing.revoke(appRef, input.shareId);
 }
 var invitesListInputSchema = exports_external.object({});
@@ -113283,7 +113536,7 @@ function summarize2(verdict, health) {
   return "API responded but reported a non-ok status";
 }
 // ../core/dist/commands/transfers.js
-function resolveApp4(ctx, app) {
+function resolveApp5(ctx, app) {
   const name = app ?? readPercherTomlAppName(ctx.cwd);
   if (!name) {
     throw new PercherCoreError("No app specified and no percher.toml found", {
@@ -113305,15 +113558,15 @@ var transferListForAppInputSchema = exports_external.object({
   app: exports_external.string().optional()
 });
 async function transferInitiate(ctx, input) {
-  const appRef = resolveApp4(ctx, input.app);
+  const appRef = resolveApp5(ctx, input.app);
   return ctx.client.transfers.initiate(appRef, { email: input.email });
 }
 async function transferCancel(ctx, input) {
-  const appRef = resolveApp4(ctx, input.app);
+  const appRef = resolveApp5(ctx, input.app);
   await ctx.client.transfers.cancel(appRef, input.transferId);
 }
 async function transferListForApp(ctx, input = {}) {
-  const appRef = resolveApp4(ctx, input.app);
+  const appRef = resolveApp5(ctx, input.app);
   return ctx.client.transfers.listForApp(appRef);
 }
 var transfersIncomingInputSchema = exports_external.object({});
@@ -114215,6 +114468,67 @@ function registerAppsCommands(cli, ctx) {
     const timing = result.timing ? ` (${result.timing.totalSeconds.toFixed(0)}s)` : "";
     await writeLine(ctx, `${import_picocolors4.default.green("✓")} Redeployed to ${result.url}${timing}`);
   });
+  cli.command("wait-for-deploy <deployId>", "Wait for an in-flight deploy to finish").option("--app <name>", "App name (defaults to percher.toml app.name)").option("--timeout <seconds>", "Max seconds to wait (default: 600)").action(async (deployId, options) => {
+    const appName = options.app ?? readPercherTomlAppName(ctx.cwd);
+    if (!appName) {
+      await writeLine(ctx, `${import_picocolors4.default.red("✗")} No app specified — pass --app <name> or run from a directory with percher.toml.`);
+      throw new SilentExitError(1);
+    }
+    const timeoutSec = Number.parseInt(options.timeout ?? "600", 10);
+    if (!Number.isFinite(timeoutSec) || timeoutSec <= 0) {
+      await writeLine(ctx, `${import_picocolors4.default.red("✗")} --timeout must be a positive number of seconds.`);
+      throw new SilentExitError(1);
+    }
+    const deadline = Date.now() + timeoutSec * 1000;
+    let lastStatus = "";
+    for (;; ) {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        await writeLine(ctx, `${import_picocolors4.default.yellow("!")} Still running after the timeout — re-run: percher wait-for-deploy ${deployId} --app ${appName}`);
+        throw new SilentExitError(1);
+      }
+      let raceTimer;
+      let result = null;
+      const callController = new AbortController;
+      try {
+        result = await Promise.race([
+          waitForDeploy(ctx, {
+            app: appName,
+            deployId,
+            timeoutSeconds: Math.min(Math.ceil(remainingMs / 1000), 30)
+          }, { signal: callController.signal }),
+          new Promise((resolve7) => {
+            raceTimer = setTimeout(() => resolve7(null), remainingMs);
+          })
+        ]);
+      } finally {
+        clearTimeout(raceTimer);
+      }
+      if (result === null) {
+        callController.abort();
+        await writeLine(ctx, `${import_picocolors4.default.yellow("!")} Still running after the timeout — re-run: percher wait-for-deploy ${deployId} --app ${appName}`);
+        throw new SilentExitError(1);
+      }
+      if (result.deployment.status !== lastStatus) {
+        lastStatus = result.deployment.status;
+        await writeLine(ctx, import_picocolors4.default.dim(`${lastStatus}...`));
+      }
+      if (result.status === "live") {
+        await writeLine(ctx, `${import_picocolors4.default.green("✓")} ${result.summary}`);
+        return;
+      }
+      if (result.status === "failed" || result.status === "replaced") {
+        const mark = result.status === "failed" ? import_picocolors4.default.red("✗") : import_picocolors4.default.yellow("!");
+        await writeLine(ctx, `${mark} ${result.summary}`);
+        if (result.error?.suggestion) {
+          await writeLine(ctx, `  ${import_picocolors4.default.dim(result.error.suggestion)}`);
+        }
+        if (result.status === "failed")
+          throw new SilentExitError(1);
+        return;
+      }
+    }
+  });
   cli.command("push", "Package and deploy this project").option("--dry-run", "Show what would be deployed, don't upload").option("--force", "Skip size warnings").option("--preview", "Deploy as preview (does not replace the live version)").option("--no-cache", "Skip image-cache lookup and force a fresh build (use when you suspect cached image is stale)").action(async (options) => {
     const result = await push(ctx, {
       dryRun: options.dryRun,
@@ -114245,6 +114559,11 @@ function registerAppsCommands(cli, ctx) {
     const result = await rename(ctx, { app, name });
     await writeLine(ctx, `${import_picocolors4.default.green("✓")} Renamed to ${result.name} — now live at ${result.url}`);
     await writeLine(ctx, `  Previous name: ${result.previousName} (reserved for 60 days)`);
+    if (result.tomlUpdated) {
+      await writeLine(ctx, `  percher.toml updated: name = "${result.name}"`);
+    } else {
+      await writeLine(ctx, `  ${import_picocolors4.default.yellow("!")} Update percher.toml before the next publish: name = "${result.name}"`);
+    }
     await writeLine(ctx, `  ${import_picocolors4.default.dim(`Next rename available in ${result.cooldownDays} days`)}`);
   });
   cli.command("open [app]", "Open the app URL in your browser").action(async (app) => {
@@ -114306,6 +114625,17 @@ function registerAppsCommands(cli, ctx) {
     const result = await resume(ctx, { app });
     await writeLine(ctx, `${import_picocolors4.default.green("✓")} ${result.message}`);
   });
+  cli.command("cache <action> [app]", "Manage the app's build cache (reset)").action(async (action, app) => {
+    if (action !== "reset") {
+      throw new Error(`Unknown cache action "${action}". Use: percher cache reset [app]`);
+    }
+    const result = await cacheReset(ctx, { app });
+    await writeLine(ctx, `${import_picocolors4.default.green("✓")} ${result.message}`);
+  });
+  cli.command("cache reset [app]", "Reset the app's build cache (next deploy runs cold)").action(async (app) => {
+    const result = await cacheReset(ctx, { app });
+    await writeLine(ctx, `${import_picocolors4.default.green("✓")} ${result.message}`);
+  });
   cli.command("doctor [app]", "Check app health and connectivity").option("--json", "Output as JSON").action(async (app, options) => {
     const result = await doctor(ctx, { app, json: options.json });
     if (options.json) {
@@ -114586,24 +114916,60 @@ function registerDeploysCommands(cli, ctx, argv) {
       await writeLine(ctx, `${v.sha}  ${v.timestamp}  ${message}`);
     }
   });
-  cli.command("preview <action> [deployId]", "Manage preview deploys (promote | discard)").option("--app <name>", "App name (overrides percher.toml)").action(async (action, deployId, options) => {
+  cli.command("preview <action> [arg] [arg2]", "Preview deploys: promote <id> | discard <id> | branch set <branch> | branch unset | branch show").option("--app <name>", "App name (overrides percher.toml)").action(async (action, arg, arg2, options) => {
+    if (action === "branch") {
+      await runPreviewBranch(arg, arg2, options.app);
+      return;
+    }
     const appRef = options.app ?? readPercherTomlAppName(ctx.cwd);
-    if (!appRef)
+    if (!appRef) {
       throw new Error("App name required. Use --app or run from a project directory.");
+    }
     if (action === "promote") {
-      if (!deployId)
+      if (!arg)
         throw new Error("Deploy ID required. Usage: percher preview promote <id>");
-      const result = await ctx.client.apps.promotePreview(appRef, deployId);
+      const result = await ctx.client.apps.promotePreview(appRef, arg);
       await writeLine(ctx, `${import_picocolors7.default.green("✓")} Preview promoted to live. Status: ${result.status}`);
     } else if (action === "discard") {
-      if (!deployId)
+      if (!arg)
         throw new Error("Deploy ID required. Usage: percher preview discard <id>");
-      await ctx.client.apps.discardPreview(appRef, deployId);
+      await ctx.client.apps.discardPreview(appRef, arg);
       await writeLine(ctx, `${import_picocolors7.default.green("✓")} Preview discarded.`);
     } else {
-      throw new Error(`Unknown preview action "${action}". Use promote | discard.`);
+      throw new Error(`Unknown preview action "${action}". Use promote | discard | branch.`);
     }
   });
+  async function runPreviewBranch(sub, branch, app) {
+    if (sub === "set") {
+      if (!branch)
+        throw new Error("Branch required. Usage: percher preview branch set <branch>");
+      const r = await previewBranchSet(ctx, { app, branch });
+      await writeLine(ctx, `${import_picocolors7.default.green("✓")} Preview branch set to "${branch}".`);
+      if (r.previewUrl)
+        await writeLine(ctx, `  Your preview address: ${import_picocolors7.default.bold(r.previewUrl)}`);
+      await writeLine(ctx, r.status === "error" ? import_picocolors7.default.yellow("  ⚠  The initial deploy failed — push to the branch to retry.") : import_picocolors7.default.dim("  Building now — live within ~90s."));
+      return;
+    }
+    if (sub === "unset") {
+      await previewBranchUnset(ctx, { app });
+      await writeLine(ctx, `${import_picocolors7.default.green("✓")} Preview branch cleared.`);
+      return;
+    }
+    if (sub === "show" || sub === undefined) {
+      const s = await previewBranchShow(ctx, { app });
+      if (!s.previewBranch) {
+        await writeLine(ctx, "No preview branch set.");
+        await writeLine(ctx, import_picocolors7.default.dim("  Set one: percher preview branch set <branch>"));
+        return;
+      }
+      await writeLine(ctx, `Preview branch: ${import_picocolors7.default.bold(s.previewBranch)}`);
+      if (s.previewUrl)
+        await writeLine(ctx, `  Address: ${s.previewUrl}`);
+      await writeLine(ctx, `  Status:  ${s.status}`);
+      return;
+    }
+    throw new Error(`Unknown preview branch action "${sub}". Use set <branch> | unset | show.`);
+  }
 }
 
 // src/commands/env.ts
@@ -115198,7 +115564,7 @@ async function renderError(stderr, error48) {
 // package.json
 var package_default = {
   name: "percher",
-  version: "0.4.2",
+  version: "0.5.0",
   description: "CLI for the Percher hosting platform — publish apps with one command",
   type: "module",
   bin: {
@@ -115279,18 +115645,18 @@ async function showTelemetryNotice() {
   if (isDisabled())
     return;
   const { homedir: homedir2 } = await import("node:os");
-  const { existsSync: existsSync16, mkdirSync: mkdirSync6, writeFileSync: writeFileSync9 } = await import("node:fs");
-  const { join: join23 } = await import("node:path");
-  const configDir = join23(homedir2(), ".percher");
-  const markerFile = join23(configDir, ".telemetry-notice-shown");
-  if (existsSync16(markerFile))
+  const { existsSync: existsSync17, mkdirSync: mkdirSync6, writeFileSync: writeFileSync10 } = await import("node:fs");
+  const { join: join24 } = await import("node:path");
+  const configDir = join24(homedir2(), ".percher");
+  const markerFile = join24(configDir, ".telemetry-notice-shown");
+  if (existsSync17(markerFile))
     return;
   console.log("Percher sends non-account-linked usage stats (command, result, error type, OS, Bun version).");
   console.log(`Disable with PERCHER_NO_TELEMETRY=1
 `);
   try {
     mkdirSync6(configDir, { recursive: true });
-    writeFileSync9(markerFile, new Date().toISOString());
+    writeFileSync10(markerFile, new Date().toISOString());
   } catch {}
 }