@percher/core 0.2.6 → 0.4.0

package/dist/commands/publish.js

@@ -1,12 +1,21 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { PercherApiError, PercherClient } from "@percher/client";
+import { PercherApiError, PercherClient, isDeployAlreadyInProgress, } from "@percher/client";
+import { TIMEOUTS } from "@percher/shared/timeouts";
 import { parseFile } from "@percher/toml";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { classifyError } from "../error-classifier";
+import { renderDeployEvent } from "../event-renderer";
+import { pollDeployment } from "../poll-deployment";
+import { runDeployWithRetry } from "../publish-retry";
+import { RECOVERY_NEEDS_LOGIN, RECOVERY_NONE, recoveryAsk, recoveryDoctor, recoveryEnv, recoveryFixConfig, recoveryFromErrorClass, recoveryWait, } from "../recovery";
 import { createTarball } from "../tarball";
+import { scanForMissingBuildEnvRefs } from "./env-scan";
 import { init } from "./init";
 import { login } from "./login";
+import { buildFailureResult } from "./publish-failure";
+import { resolveNodeVersion } from "./publish-node";
+import { resolveReplaced } from "./wait-deploy";
 export const publishInputSchema = z.object({
     force: z.boolean().optional().describe("Skip size warnings"),
     preview: z.boolean().optional().describe("Deploy as preview (does not replace the live version)"),
@@ -18,10 +27,129 @@ export const publishInputSchema = z.object({
         .boolean()
         .optional()
         .describe("Show what would be deployed (file count, bytes, top files) without uploading or building. Useful for verifying the bundle before a real deploy."),
+    noCache: z
+        .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: z
+        .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."),
 });
 const MAX_BYTES = 500 * 1024 * 1024;
 const SUSPICIOUS_BYTES = 50 * 1024 * 1024;
 const SUSPICIOUS_FILES = 10_000;
+function tomlPathFor(cwd) {
+    return join(cwd, "percher.toml");
+}
+/**
+ * FUTURE11 review P2 — sync publish path's `replaced` terminal result.
+ * `replaced` has two API code-paths: a newer live deploy succeeded, or
+ * reconcile saw the container is gone. We can't tell which from the
+ * row itself, so resolve by fetching the latest deploy and routing
+ * accordingly (live → none + url; in-flight → wait_deploy; otherwise
+ * ask_user). Matches FUTURE12 Phase 4's locked behavior for
+ * `replaced_by_newer`.
+ */
+async function buildReplacedResult(opts) {
+    const { ctx, app, deployment, tarball, cwd } = opts;
+    const resolved = await resolveReplaced({
+        ctx,
+        app,
+        replacedDeployment: deployment,
+    });
+    return {
+        status: "replaced",
+        url: resolved.url,
+        app,
+        deployment,
+        fileCount: tarball.fileCount,
+        bytes: tarball.bytes,
+        recovery: resolved.recovery,
+        summary: resolved.summary,
+        configPath: tomlPathFor(cwd),
+        bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+    };
+}
+/**
+ * FUTURE12 Phase 6d — server told us a deploy is already in flight for
+ * this app. Build a successful PublishResult that points the agent at
+ * the existing deployId via `wait_deploy` (retryable: false — the agent
+ * MUST wait, not retry).
+ */
+function buildAlreadyInProgressResult(opts) {
+    const { active, app, tarball, cwd } = opts;
+    const reasonCode = active.deployStatus === "queued"
+        ? "deploy_queued"
+        : active.deployStatus === "building"
+            ? "deploy_building"
+            : "deploy_deploying";
+    return {
+        status: "already_in_progress",
+        app,
+        fileCount: tarball.fileCount,
+        bytes: tarball.bytes,
+        recovery: recoveryWait({
+            app: app.name,
+            deployId: active.deployId,
+            reasonCode,
+        }),
+        summary: `${app.name} already has a deploy in progress (${active.deployId}, ${active.deployStatus}) — wait for it to finish instead of queueing a duplicate.`,
+        configPath: tomlPathFor(cwd),
+        bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+    };
+}
+/**
+ * FUTURE12 Phase 6d — server rejected this publish because the user
+ * already used their one auto-retry within the 10-minute window after
+ * an `infra_unavailable` failure. Build an `ask_user` recovery so the
+ * agent surfaces it to the human instead of looping.
+ */
+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: tomlPathFor(cwd),
+        bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+    };
+}
+/**
+ * Build the one-line summary echoed back to humans. Includes app name,
+ * framework when known, total seconds, and final URL — covers the
+ * "deployed `kvittakvitto` (Next.js, 47s) → kvittakvitto.percher.run"
+ * shape called out in the agent-DX plan.
+ */
+function buildLiveSummary(opts) {
+    // Suffix: "(framework, Ns)" with optional "cached" tag when the
+    // image cache matched. Cache-hit deploys are typically <10s so the
+    // tag is the load-bearing signal in the summary, not the duration.
+    const cacheTag = opts.cacheHit ? "cached, " : "";
+    const fwSuffix = opts.framework
+        ? ` (${opts.framework}, ${cacheTag}${opts.totalSeconds}s)`
+        : ` (${cacheTag}${opts.totalSeconds}s)`;
+    const verb = opts.preview ? "preview deployed" : "deployed";
+    const replaced = opts.replacedPreview ? " — replaced previous preview" : "";
+    return `${opts.appName} ${verb}${fwSuffix} → ${opts.url}${replaced}`;
+}
 /**
  * All-in-one publish command for AI agents.
  *
@@ -47,12 +175,23 @@ export async function publish(ctx, input = {}) {
                 explanation: hint ?? message,
                 suggestion: "This may be a network issue or a Percher bug. Check your connection and try again. If the problem persists, run percher_doctor for diagnostics.",
             },
+            // Network glitches surface here too, but we can't tell them apart
+            // from genuine bugs without inspecting the cause. `ask_user` keeps
+            // the agent honest — surface the explanation, don't auto-retry.
+            recovery: recoveryAsk({
+                prompt: `Unexpected publish failure: ${hint ?? message}. Run \`percher doctor\` for diagnostics or surface this to the user.`,
+                reasonCode: "unknown",
+            }),
+            summary: `Unexpected error: ${hint ?? message}`,
+            configPath: tomlPathFor(ctx.cwd),
+            bundle: { fileCount: 0, bytes: 0 },
         };
     }
 }
 async function publishInner(ctx, input) {
     const t0 = Date.now();
     // ── 1. Config ──────────────────────────────────────────────────────
+    ctx.status("[1/4] Reading config...");
     let config;
     try {
         config = await loadOrGenerate(ctx);
@@ -67,9 +206,22 @@ async function publishInner(ctx, input) {
                 explanation: "percher.toml could not be auto-generated for this project.",
                 suggestion: "Create a percher.toml manually with at least [app] name and runtime, then try again.",
             },
+            recovery: recoveryFixConfig({
+                problems: [
+                    {
+                        file: "percher.toml",
+                        message: "percher.toml could not be auto-generated for this project. Create one manually with at least [app] name and runtime.",
+                    },
+                ],
+                reasonCode: "config_missing",
+            }),
+            summary: "Could not generate percher.toml — create one manually and retry.",
+            configPath: tomlPathFor(ctx.cwd),
+            bundle: { fileCount: 0, bytes: 0 },
         };
     }
     // ── 2. Tarball ─────────────────────────────────────────────────────
+    ctx.status("[2/4] Packaging files...");
     const tarball = await createTarball({ cwd: ctx.cwd, config });
     const packageMs = Date.now() - t0;
     if (tarball.bytes > MAX_BYTES) {
@@ -82,6 +234,16 @@ async function publishInner(ctx, input) {
                 explanation: `The project is ${(tarball.bytes / 1024 / 1024).toFixed(1)} MB, which exceeds the 500 MB limit.`,
                 suggestion: `Add large files/folders to .gitignore. Biggest: ${tarball.topFiles.map((f) => f.path).join(", ")}`,
             },
+            // Not retryable, not config-invalid in the toml sense — just too big.
+            // The user has to make a manual decision (add to .gitignore, split repo,
+            // bump plan limits). `ask_user` is the honest action.
+            recovery: recoveryAsk({
+                prompt: `Repository is ${(tarball.bytes / 1024 / 1024).toFixed(1)} MB, which exceeds the 500 MB upload limit. Add large files/folders to .gitignore (biggest: ${tarball.topFiles.map((f) => f.path).join(", ")}) and try again.`,
+                reasonCode: "unknown",
+            }),
+            summary: `Repository too large (${(tarball.bytes / 1024 / 1024).toFixed(1)} MB exceeds 500 MB limit).`,
+            configPath: tomlPathFor(ctx.cwd),
+            bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
         };
     }
     if (!input.force && (tarball.fileCount > SUSPICIOUS_FILES || tarball.bytes > SUSPICIOUS_BYTES)) {
@@ -103,27 +265,289 @@ async function publishInner(ctx, input) {
             status: "dry_run",
             fileCount: tarball.fileCount,
             bytes: tarball.bytes,
+            recovery: RECOVERY_NONE,
+            summary: `Dry run: ${tarball.fileCount} files, ${(tarball.bytes / 1024).toFixed(1)} KB — no deploy performed.`,
+            configPath: tomlPathFor(ctx.cwd),
+            bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
         };
     }
     // ── 3. Auth + ensure app ───────────────────────────────────────────
     let app;
+    let firstDeploy = false;
     try {
-        app = await ensureApp(ctx, config);
+        ({ app, firstDeploy } = await ensureApp(ctx, config));
     }
     catch (err) {
         if (err instanceof PercherApiError && err.status === 401) {
-            return handleUnauthorized(ctx, config, tarball);
+            return handleUnauthorized(ctx, config, tarball, input);
         }
         throw err;
     }
+    // ── 3.5. Build-env scan ────────────────────────────────────────────
+    // Advisory-only: a transient error must never block a deploy.
+    let missingBuildEnvKeys = [];
+    try {
+        const existingEnvKeys = new Set(Object.keys(await ctx.client.env.list(app.id)));
+        missingBuildEnvKeys = scanForMissingBuildEnvRefs(ctx.cwd, existingEnvKeys);
+    }
+    catch {
+        // Degrade silently — scan failure is not a reason to abort publish.
+    }
+    if (missingBuildEnvKeys.length > 0 && !input.force) {
+        const keyList = missingBuildEnvKeys.map((k) => `  • ${k}`).join("\n");
+        ctx.status(`⚠ Source references these vars but they're not in the env store:\n${keyList}\n  They will compile to \`undefined\` in the client bundle.\n  Note: scans the full project directory, not just deployed files.\n  Fix: bunx percher env set KEY=value\n  (Re-run with --force to suppress this check.)`);
+    }
+    // ── 3.7. Preflight ─────────────────────────────────────────────────
+    // Phase 7.3 — cheap (~100 ms) probe of platform readiness so we don't
+    // burn the user's bandwidth uploading a tarball that's bound for a
+    // queue we've already lost contact with. On `accept: false` we surface
+    // a `retry` recovery and bail before reading the tarball stream.
+    // On a slow queue we emit a heads-up so the agent can manage user
+    // expectations ("queued behind 2 others, ~3min wait").
+    try {
+        const preflight = await ctx.client.platform.preflight();
+        if (!preflight.accept) {
+            const reasonText = preflight.reason === "worker_circuit_breaker_open"
+                ? "platform circuit breaker is open — workers are restarting"
+                : preflight.reason === "worker_unhealthy"
+                    ? "build worker is currently unreachable"
+                    : "platform is currently unavailable";
+            return {
+                status: "failed",
+                app,
+                fileCount: tarball.fileCount,
+                bytes: tarball.bytes,
+                error: {
+                    title: "Platform unavailable",
+                    explanation: `Preflight refused the upload: ${reasonText}.`,
+                    suggestion: "Wait ~30s and retry — the platform self-heals automatically and the auto-retry loop will pick it up on the next attempt.",
+                    errorClass: "infra_unavailable",
+                    phase: "config",
+                },
+                recovery: {
+                    retryable: true,
+                    nextAction: "retry",
+                    suggestedTool: "percher_publish",
+                    args: {},
+                    reasonCode: "infra_unavailable",
+                },
+                summary: `Preflight refused — ${reasonText}.`,
+                configPath: tomlPathFor(ctx.cwd),
+                bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+            };
+        }
+        if (preflight.queueWaitEstimateSec > 60) {
+            ctx.status(`Build queue wait: ~${preflight.queueWaitEstimateSec}s — your build is queued behind ${preflight.queueDepth} other(s).`);
+        }
+    }
+    catch {
+        // Preflight is advisory — a network error here just means the CLI
+        // proceeds and lets the retry loop (Phase 7.2) handle whatever
+        // surfaces during the actual upload.
+    }
     // ── 4. Upload ──────────────────────────────────────────────────────
     const uploadStart = Date.now();
-    ctx.status("Uploading...");
-    let deployment = await ctx.client.apps.deploy(app.id, {
-        tarball: tarball.stream,
-        type: input.preview ? "preview" : undefined,
-        note: input.message,
-    });
+    ctx.status("[3/4] Uploading...");
+    // Buffer the tarball so the retry loop (Phase 7.2) can resend the
+    // same bytes after a transient failure. createTarball returns a
+    // streaming source that's consumed-once; collecting it eagerly
+    // lets every attempt share the same payload (and the same
+    // Idempotency-Key) without re-walking the filesystem.
+    const tarballBytes = new Uint8Array(await new Response(tarball.stream).arrayBuffer());
+    // Phase 7.8 — content-hash the bundle and probe whether we've
+    // already deployed identical bytes for this app. On hit we skip the
+    // upload entirely and call /rerun on the previous deploy — the
+    // existing image_cache short-circuits the build, so the new deploy
+    // is live in seconds instead of a 90s build cycle. `--no-cache`
+    // bypasses the probe so users with a cache-correctness suspicion
+    // can force a fresh upload + build.
+    let cacheReusedDeployment = null;
+    // Phase 7.8 follow-up — content-hash from createTarball() (sorted
+    // entries, deterministic). Hashing the gzipped bytes would not
+    // work: tar/gzip headers carry mtime/OS bytes that vary per run,
+    // so the same source produced a different hash on every publish.
+    // Codex P2, 2026-05-08. Sent as `X-Tarball-Hash` on the upload so
+    // the API stores it on `deployments.tarball_hash` for the probe.
+    const contentHash = tarball.contentHash;
+    if (!input.noCache) {
+        try {
+            const probe = await ctx.client.platform.cacheProbe({
+                appId: app.id,
+                tarballHash: contentHash,
+            });
+            if (probe.hit) {
+                ctx.status(`Build cache: identical bundle deployed previously (${probe.lastDeployId}) — redeploying without re-upload.`);
+                cacheReusedDeployment = await ctx.client.apps.rerunDeploy(app.id, probe.lastDeployId);
+                ctx.status("[4/4] Building & deploying (cache reuse)...");
+            }
+        }
+        catch {
+            // Cache-probe is advisory — a network error or 404 here just
+            // means the CLI proceeds with a normal upload.
+        }
+    }
+    const idempotencyKey = crypto.randomUUID();
+    let deployment;
+    if (cacheReusedDeployment) {
+        deployment = cacheReusedDeployment;
+    }
+    else {
+        try {
+            const { result: deployResponse, attempts: deployAttempts } = await runDeployWithRetry({
+                call: (attempt) => ctx.client.apps.deploy(app.id, {
+                    tarball: tarballBytes,
+                    type: input.preview ? "preview" : undefined,
+                    note: input.message,
+                    noCache: input.noCache,
+                    idempotencyKey,
+                    tarballHash: contentHash,
+                    // Phase 7.5 — claim the count of CLI-side retries that
+                    // preceded this attempt so the API persists it on the row;
+                    // swap-stage promotes the live transition to
+                    // `retry_recovered` when > 0. `attempt` is 1-indexed; first
+                    // try has 0 retries and the client omits the header.
+                    retriedAttempts: attempt - 1,
+                }),
+                onRetry: ({ attempt, decision }) => {
+                    ctx.status(`Retrying after ${Math.round(decision.delayMs / 1000)}s — ${decision.reason} (attempt ${attempt + 1}/4)…`);
+                },
+            });
+            if (deployAttempts > 1) {
+                ctx.status(`Recovered after ${deployAttempts - 1} retry${deployAttempts > 2 ? "ies" : ""}.`);
+            }
+            // FUTURE12 Phase 6d — server-side already_in_progress short-
+            // circuit. The API returned no new deploy row because there's
+            // already one in flight for this app; emit a wait_deploy
+            // recovery pointing at the active deployId so the agent calls
+            // percher_wait_for_deploy instead of queueing a duplicate.
+            // Status code: 200 (informational), not an error.
+            if (isDeployAlreadyInProgress(deployResponse)) {
+                return buildAlreadyInProgressResult({
+                    active: deployResponse,
+                    app,
+                    tarball: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+                    cwd: ctx.cwd,
+                });
+            }
+            deployment = deployResponse;
+        }
+        catch (err) {
+            // FUTURE12 Phase 6d — retry-state guardrail. The user already
+            // burned their one auto-retry inside the 10-minute window after
+            // an `infra_unavailable` failure. Recovery is `ask_user` with
+            // retryable=false so an agent doesn't loop indefinitely against
+            // a non-transient outage.
+            if (err instanceof PercherApiError && err.code === "RETRY_LIMIT_REACHED") {
+                return buildRetryLimitReachedResult({
+                    err,
+                    app,
+                    tarball: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+                    cwd: ctx.cwd,
+                });
+            }
+            // Daily-quota gate (Fas 4) returns 429 DAILY_QUOTA_EXCEEDED with
+            // structured `extra` fields (kind/used/limit/resetAt). Surface
+            // those to the agent as ask_user — retry only makes sense after
+            // resetAt, which the message includes verbatim.
+            // FUTURE12 Phase 6c — pre-queue env gate. Two codes, both 422:
+            //   REQUIRED_ENV_MISSING → recoveryEnv (set the keys, re-publish)
+            //   ENV_KEY_UNDECLARED   → recoveryFixConfig (declare in [env])
+            // Distinct from build-failure missing_env: the gate fires BEFORE
+            // the deploy queues, so there's no deployId/buildLog to point at —
+            // the only artifact is the structured `extra` payload.
+            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: tomlPathFor(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: tomlPathFor(ctx.cwd),
+                    bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+                };
+            }
+            if (err instanceof PercherApiError && err.code === "DAILY_QUOTA_EXCEEDED") {
+                const extra = err.extra ?? {};
+                const kind = extra.kind ?? "live";
+                const used = extra.used ?? 0;
+                const limit = extra.limit ?? 0;
+                const resetAt = extra.resetAt ?? "";
+                const otherKind = kind === "live" ? "preview" : "live";
+                return {
+                    status: "failed",
+                    app,
+                    fileCount: tarball.fileCount,
+                    bytes: tarball.bytes,
+                    error: {
+                        title: "Daily deploy quota reached",
+                        explanation: `You've used ${used} of ${limit} ${kind} deploys today on this account. Counter resets at ${resetAt}.`,
+                        suggestion: `Wait until the counter resets, deploy a ${otherKind} instead, or upgrade your plan at https://percher.app/settings to raise this cap.`,
+                    },
+                    recovery: recoveryAsk({
+                        prompt: `Daily ${kind}-deploy quota reached (${used}/${limit}). Counter resets at ${resetAt}. Wait until then, deploy a ${otherKind} instead, or upgrade at https://percher.app/settings.`,
+                        options: ["wait", `deploy ${otherKind}`, "upgrade"],
+                        reasonCode: "quota_exceeded",
+                    }),
+                    summary: `Daily ${kind}-deploy quota reached (${used}/${limit}). Resets ${resetAt}.`,
+                    configPath: tomlPathFor(ctx.cwd),
+                    bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+                };
+            }
+            throw err;
+        }
+    }
     // Surface the auto-replace one-shot signal — only the initial POST
     // response carries it, so capture before the polling loop reassigns
     // `deployment` from getDeployment() (which never sees the flag).
@@ -132,53 +556,147 @@ async function publishInner(ctx, input) {
         ctx.status("Replaced previous preview...");
     }
     const uploadMs = Date.now() - uploadStart;
+    // FUTURE11 Phase 1 — async opt-in. Caller asked publish to return as
+    // soon as the deploy is queued so it can resume with
+    // percher_wait_for_deploy. The upload is finished and the server has
+    // the deploy row; the only thing left is the build, which is exactly
+    // the part agents shouldn't block on.
+    if (input.waitForLive === false) {
+        ctx.status(`Queued (${deployment.id}) — resume with percher_wait_for_deploy.`);
+        return {
+            status: "queued",
+            app,
+            deployment,
+            fileCount: tarball.fileCount,
+            bytes: tarball.bytes,
+            replacedPreview: replacedPreview || undefined,
+            firstDeploy: firstDeploy || undefined,
+            missingBuildEnvKeys: missingBuildEnvKeys.length > 0 ? missingBuildEnvKeys : 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: tomlPathFor(ctx.cwd),
+            bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+        };
+    }
     // ── 5. Poll ────────────────────────────────────────────────────────
+    ctx.status("[4/4] Building & deploying...");
     const buildStart = Date.now();
-    const timeoutMs = 5 * 60 * 1000;
+    const timeoutMs = TIMEOUTS.clientPublishPoll;
     let lastStatus;
     let nextHeartbeatMs = 15_000;
-    while (deployment.status !== "live" && deployment.status !== "failed") {
-        const elapsedMs = Date.now() - buildStart;
-        if (elapsedMs > timeoutMs) {
-            return {
-                status: "failed",
-                app,
-                deployment,
-                fileCount: tarball.fileCount,
-                bytes: tarball.bytes,
-                error: {
-                    title: "Deploy timed out",
-                    explanation: "The deployment did not complete within 5 minutes.",
-                    suggestion: "Check the build logs with percher_logs. The build may need optimization or there may be an infrastructure issue.",
-                },
-            };
-        }
-        // Only emit when the status actually changes, or every ~15s as a
-        // heartbeat with elapsed time. The previous loop printed
-        // "building..." every 2s for 90s on a Next.js cold build, which is
-        // 45 lines of zero signal. One change-event + occasional heartbeat
-        // is far easier to read.
-        if (deployment.status !== lastStatus) {
-            ctx.status(`${deployment.status}...`);
-            lastStatus = deployment.status;
-            nextHeartbeatMs = elapsedMs + 15_000;
-        }
-        else if (elapsedMs >= nextHeartbeatMs) {
-            ctx.status(`${deployment.status}... (${Math.round(elapsedMs / 1000)}s elapsed)`);
-            nextHeartbeatMs = elapsedMs + 15_000;
-        }
-        await new Promise((r) => setTimeout(r, 2000));
-        deployment = await ctx.client.apps.getDeployment(app.id, deployment.id);
+    // Heartbeat tracking lives in the caller because pollDeployment is a
+    // generic primitive. Only emit when the status actually changes, or
+    // every ~15s as a heartbeat with elapsed time. The previous loop
+    // printed "building..." every 2s for 90s on a Next.js cold build,
+    // which was 45 lines of zero signal.
+    let timedOut = null;
+    try {
+        deployment = await pollDeployment({
+            ctx,
+            appId: app.id,
+            initial: deployment,
+            intervalMs: 2000,
+            timeoutMs,
+            appName: app.name,
+            // FUTURE11 review P2: a concurrent newer deploy can mark this row
+            // `replaced` while we're still polling. The default terminal set
+            // (live/failed) wouldn't catch that, so we'd spin until the 5min
+            // timeout and surface a misleading "Deploy timed out". Treat
+            // replaced as terminal and branch on it after the poll returns.
+            terminal: ["live", "failed", "replaced"],
+            onTick: (d) => {
+                const elapsedMs = Date.now() - buildStart;
+                if (d.status !== lastStatus) {
+                    ctx.status(`${d.status}...`);
+                    lastStatus = d.status;
+                    nextHeartbeatMs = elapsedMs + 15_000;
+                }
+                else if (elapsedMs >= nextHeartbeatMs) {
+                    ctx.status(`${d.status}... (${Math.round(elapsedMs / 1000)}s elapsed)`);
+                    nextHeartbeatMs = elapsedMs + 15_000;
+                }
+            },
+            // Phase 6.1 — surface stage/sub-stage transitions as they're
+            // recorded so the user sees real progress instead of a generic
+            // "building..." spinner. renderDeployEvent returns null for
+            // hidden rows (e.g. `done/ok`, where the caller prints the
+            // final live URL line).
+            onEvent: (event) => {
+                const line = renderDeployEvent(event);
+                if (line)
+                    ctx.status(line);
+            },
+            // publish wants to return a structured PublishResult on timeout
+            // (not throw), so capture the in-flight deployment and break out
+            // via a sentinel object rather than letting the throw bubble.
+            onTimeout: (d) => {
+                timedOut = { deployment: d };
+                // biome-ignore lint/suspicious/noExplicitAny: sentinel re-thrown locally
+                throw new (class PollTimeoutSentinel extends Error {
+                })("__poll_timeout__");
+            },
+        });
+    }
+    catch (err) {
+        if (!timedOut)
+            throw err;
+    }
+    if (timedOut) {
+        const stuckDeployment = timedOut.deployment;
+        return {
+            status: "failed",
+            app,
+            deployment: stuckDeployment,
+            fileCount: tarball.fileCount,
+            bytes: tarball.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 fetch the build log, classify the state, and return a concrete next step. The build may need optimization or there may be an infrastructure issue.`,
+            },
+            // FUTURE12 Phase 4: stalled deploy is ambiguous (still in
+            // flight, infra issue, slow build). Hand off to doctor with
+            // mode='deploy' so it can read deploy state + build log and
+            // decide between retry / inspect / ask_user — instead of
+            // pushing the agent straight at the raw build log.
+            recovery: recoveryDoctor({
+                app: app.name,
+                deployId: stuckDeployment.id,
+                mode: "deploy",
+                reasonCode: "deploy_stalled",
+            }),
+            summary: `Deploy timed out after 5 minutes (${stuckDeployment.id}).`,
+            configPath: tomlPathFor(ctx.cwd),
+            bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+        };
     }
     const buildMs = Date.now() - buildStart;
     // ── 6. Result ──────────────────────────────────────────────────────
+    if (deployment.status === "replaced") {
+        return await buildReplacedResult({
+            ctx,
+            app,
+            deployment,
+            tarball: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+            cwd: ctx.cwd,
+        });
+    }
     if (deployment.status === "failed") {
-        return buildFailureResult({
+        const failResult = await buildFailureResult({
             ctx,
             app,
             deployment,
             tarball: { fileCount: tarball.fileCount, bytes: tarball.bytes },
+            input,
         });
+        if (missingBuildEnvKeys.length > 0) {
+            failResult.missingBuildEnvKeys = missingBuildEnvKeys;
+        }
+        return failResult;
     }
     const totalSeconds = (Date.now() - t0) / 1000;
     const url = deployment.previewUrl ?? deployment.url ?? app.url;
@@ -194,6 +712,14 @@ async function publishInner(ctx, input) {
             /* non-critical */
         }
     }
+    // Read cache state directly off the polled deployment row. The row
+    // is the source of truth (deploy-pipeline writes deployments.cache_hit
+    // = true on the same code path that aliases the cached image). The
+    // earlier implementation fetched /events and inferred a hit from the
+    // subStage='cache_hit' event — that worked, but lost the signal on
+    // any /events fetch failure or post-login retry path. Codex P2
+    // follow-up on 9e5ceee.
+    const cacheHit = deployment.cacheHit;
     return {
         status: "live",
         url,
@@ -209,9 +735,36 @@ async function publishInner(ctx, input) {
         fileCount: tarball.fileCount,
         bytes: tarball.bytes,
         replacedPreview,
+        firstDeploy: firstDeploy || undefined,
+        cacheHit,
+        cacheReused: cacheReusedDeployment !== null || undefined,
+        missingBuildEnvKeys: missingBuildEnvKeys.length > 0 ? missingBuildEnvKeys : undefined,
+        // Phase 7.9 — operator-facing trace key. Codex P2 follow-up on
+        // b8f469a: previously a CLI-generated UUID, but the API/worker
+        // path used `deployId` as the wire trace key (build-fetch sets
+        // X-Trace-Id: <deployId>, recent-calls indexes on it, worker
+        // log echo prefixes lines with it). Aliasing the user-facing
+        // value to deployId means `Trace: dep_xxx` in the CLI matches
+        // /internal/recent-calls?traceId=dep_xxx and a worker
+        // journalctl grep — one key end-to-end. Cache-reuse paths
+        // already get a real deployId via /rerun, so this works there
+        // too without special-casing.
+        traceId: deployment.id,
+        recovery: RECOVERY_NONE,
+        summary: buildLiveSummary({
+            appName: app.name,
+            url: url ?? app.url,
+            totalSeconds: Math.round(totalSeconds),
+            framework: config.app.framework,
+            preview: input.preview === true,
+            replacedPreview,
+            cacheHit: cacheHit === true,
+        }),
+        configPath: tomlPathFor(ctx.cwd),
+        bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
     };
 }
-async function handleUnauthorized(ctx, config, tarball) {
+async function handleUnauthorized(ctx, config, tarball, input) {
     // In MCP context we can't open a browser — return login instructions
     if (!ctx.interactiveLogin) {
         try {
@@ -226,6 +779,10 @@ async function handleUnauthorized(ctx, config, tarball) {
                 loginCode: userCode,
                 fileCount: tarball.fileCount,
                 bytes: tarball.bytes,
+                recovery: RECOVERY_NEEDS_LOGIN,
+                summary: `Login required: open ${loginUrl} (code: ${userCode}).`,
+                configPath: tomlPathFor(ctx.cwd),
+                bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
             };
         }
         catch {
@@ -238,6 +795,10 @@ async function handleUnauthorized(ctx, config, tarball) {
                     explanation: "No valid Percher token found.",
                     suggestion: "Run the percher_login tool first, or set PERCHER_TOKEN environment variable.",
                 },
+                recovery: RECOVERY_NEEDS_LOGIN,
+                summary: "Login required — run percher_login or set PERCHER_TOKEN.",
+                configPath: tomlPathFor(ctx.cwd),
+                bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
             };
         }
     }
@@ -250,14 +811,94 @@ async function handleUnauthorized(ctx, config, tarball) {
     });
     // Re-create tarball since stream is consumed
     const freshTarball = await createTarball({ cwd: ctx.cwd, config });
-    const app = await ensureApp(ctx, config);
+    let firstDeployRetry = false;
+    let app;
+    ({ app, firstDeploy: firstDeployRetry } = await ensureApp(ctx, config));
     ctx.status("Uploading...");
-    let deployment = await ctx.client.apps.deploy(app.id, {
-        tarball: freshTarball.stream,
-    });
-    const timeoutMs = 5 * 60 * 1000;
+    // Buffer for the retry loop (Phase 7.2) — same pattern as the main
+    // publishInner path; the post-login flow gets the same auto-retry
+    // protection without a parallel retry helper.
+    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,
+                // Preserve preview/note semantics across the post-login retry.
+                // Without these, an interactive `percher publish --preview -m "x"`
+                // that hits a 401 would silently downgrade to a live deploy with
+                // no note after the user logs in. Codex P1, 2026-04-29.
+                type: input.preview ? "preview" : undefined,
+                note: input.message,
+                noCache: input.noCache,
+                idempotencyKey: freshIdempotencyKey,
+                // Phase 7.5 — same X-Publish-Attempts claim as the main
+                // publish path; ensures the post-login retry chain still
+                // yields a `retry_recovered` outcome when it eventually wins.
+                retriedAttempts: attempt - 1,
+            }),
+            onRetry: ({ attempt, decision }) => {
+                ctx.status(`Retrying after ${Math.round(decision.delayMs / 1000)}s — ${decision.reason} (attempt ${attempt + 1}/4)…`);
+            },
+        });
+        // FUTURE12 Phase 6d — same already_in_progress short-circuit as
+        // the main publishInner path. Without this branch, a user who
+        // hits a 401 mid-publish and re-auths could land on the
+        // post-login deploy step and have it silently fall through into
+        // a 5-minute polling loop against the existing deploy's row.
+        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;
+    // FUTURE11 Phase 1 — same async opt-in as the main publishInner path.
+    // Without this, a caller that passed `waitForLive: false` and hit a
+    // 401 (interactive login flow) would silently fall through to the
+    // 5-minute polling loop after login, breaking the contract that
+    // waitForLive=false always returns as soon as the deploy is queued.
+    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: tomlPathFor(ctx.cwd),
+            bundle: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes },
+        };
+    }
+    const timeoutMs = TIMEOUTS.clientPublishPoll;
     const start = Date.now();
-    while (deployment.status !== "live" && deployment.status !== "failed") {
+    while (deployment.status !== "live" &&
+        deployment.status !== "failed" &&
+        deployment.status !== "replaced") {
         if (Date.now() - start > timeoutMs) {
             return {
                 status: "failed",
@@ -268,20 +909,41 @@ async function handleUnauthorized(ctx, config, tarball) {
                 error: {
                     title: "Deploy timed out",
                     explanation: "The deployment did not complete within 5 minutes.",
-                    suggestion: "Check the build logs with percher_logs.",
+                    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.`,
                 },
+                // FUTURE12 Phase 4: ambiguous stall — let doctor classify
+                // before the agent dives into the raw log.
+                recovery: recoveryDoctor({
+                    app: app.name,
+                    deployId: deployment.id,
+                    mode: "deploy",
+                    reasonCode: "deploy_stalled",
+                }),
+                summary: `Deploy timed out after 5 minutes (${deployment.id}).`,
+                configPath: tomlPathFor(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;
@@ -300,6 +962,33 @@ async function handleUnauthorized(ctx, config, tarball) {
         },
         fileCount: freshTarball.fileCount,
         bytes: freshTarball.bytes,
+        replacedPreview,
+        firstDeploy: firstDeployRetry || undefined,
+        recovery: RECOVERY_NONE,
+        cacheHit: deployment.cacheHit,
+        // Phase 7.9 — operator-facing trace key, same shape the primary
+        // success path returns. Codex P2 follow-up on daf063f: the
+        // post-login retry path was returning a PublishResult without
+        // `traceId`, so a user who started unauthenticated, logged in,
+        // and then succeeded got no `Trace: dep_xxx` line from the CLI
+        // and the correlation key was missing for that publish.
+        traceId: deployment.id,
+        summary: buildLiveSummary({
+            appName: app.name,
+            url: url ?? app.url,
+            totalSeconds: Math.round(totalSeconds),
+            framework: config.app.framework,
+            preview: input.preview === true,
+            replacedPreview,
+            // Read directly off the polled deployment row — same source of
+            // truth as the primary publish path. Codex P2 follow-up on
+            // 9e5ceee: the previous hardcoded `false` here meant the user
+            // who hit the post-login retry branch always saw "Build cache:
+            // miss" regardless of whether the build actually used the cache.
+            cacheHit: deployment.cacheHit ?? false,
+        }),
+        configPath: tomlPathFor(ctx.cwd),
+        bundle: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes },
     };
 }
 // ── Helpers ────────────────────────────────────────────────────────────
@@ -313,54 +1002,21 @@ async function loadOrGenerate(ctx) {
 }
 async function ensureApp(ctx, config) {
     try {
-        return await ctx.client.apps.get(config.app.name);
+        const app = await ctx.client.apps.get(config.app.name);
+        return { app, firstDeploy: false };
     }
     catch (err) {
         if (err.code === "APP_NOT_FOUND") {
-            return ctx.client.apps.create({
+            const app = await ctx.client.apps.create({
                 name: config.app.name,
                 runtime: config.app.runtime,
                 framework: config.app.framework,
             });
+            return { app, firstDeploy: true };
         }
         throw err;
     }
 }
-/**
- * Resolve which Node version will be used by the build, in priority order:
- *   1. user `.nvmrc` (literal contents trimmed)
- *   2. user `engines.node` from package.json
- *   3. server-side default ("Node 22 LTS" — kept in sync with
- *      packages/api/src/nixpacks/build.ts:DEFAULT_NODE_VERSION)
- * Returns null when this isn't a Node project (no package.json + no .nvmrc).
- */
-function resolveNodeVersion(cwd) {
-    const nvmrc = join(cwd, ".nvmrc");
-    if (existsSync(nvmrc)) {
-        try {
-            const v = readFileSync(nvmrc, "utf8").trim();
-            if (v)
-                return { value: v, source: ".nvmrc" };
-        }
-        catch {
-            /* fall through */
-        }
-    }
-    const pkgPath = join(cwd, "package.json");
-    if (!existsSync(pkgPath))
-        return null;
-    try {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        const engines = pkg?.engines?.node;
-        if (typeof engines === "string" && engines.length > 0) {
-            return { value: engines, source: "engines.node" };
-        }
-    }
-    catch {
-        /* fall through */
-    }
-    return { value: "22 LTS", source: "default" };
-}
 function emitPreflight(ctx, config, tarball) {
     const lines = [];
     const fw = config.app.framework ?? (config.app.runtime === "docker" ? "Dockerfile" : config.app.runtime);
@@ -387,72 +1043,4 @@ function emitPreflight(ctx, config, tarball) {
         ctx.status(line);
     }
 }
-async function buildFailureResult(opts) {
-    const { ctx, app, deployment, tarball } = opts;
-    // Try to fetch build log for diagnosis. Pre-build infra failures (worker
-    // unreachable, nixpacks couldn't fetch from cache, tarball extraction
-    // crashed) leave buildLog empty — we have to fall back to the deployment's
-    // top-level errorMessage so the user isn't left staring at "see the log
-    // below" with nothing below it.
-    let buildLogTail;
-    let fullLog = "";
-    try {
-        fullLog = await ctx.client.apps.getBuildLog(app.id, deployment.id);
-        if (fullLog) {
-            const lines = fullLog.split("\n");
-            buildLogTail = lines.slice(-50).join("\n");
-        }
-    }
-    catch {
-        // Build log fetch can fail — that's fine, we still have a basic error
-    }
-    const errorMessage = deployment.errorMessage ?? "";
-    // Classify against the build log first (post-build failures are richer),
-    // then against errorMessage as a fallback for the pre-build / infra case.
-    const classified = classifyError("Deployment failed", fullLog) ?? classifyError(errorMessage, "");
-    // Always preserve the raw upstream string when we have one and there's
-    // no build log to anchor to. The classifier replaces it with a friendly
-    // template, but the actual error often carries the load-bearing detail
-    // (port number, hostname, HTTP status) that support needs to debug.
-    // Skip when it would just duplicate the explanation we're about to print.
-    const rawErrorMessage = errorMessage && !buildLogTail && !classified?.explanation.includes(errorMessage)
-        ? errorMessage
-        : undefined;
-    const error = classified
-        ? {
-            title: classified.title,
-            explanation: classified.explanation,
-            suggestion: classified.suggestion,
-            buildLogTail,
-            rawErrorMessage,
-            errorClass: classified.errorClass,
-            phase: classified.phase,
-            cause: classified.cause,
-            relevantFiles: classified.relevantFiles,
-            missingEnvVars: classified.missingEnvVars,
-        }
-        : {
-            title: "Deployment failed",
-            explanation: errorMessage
-                ? `The deployment failed: ${errorMessage}`
-                : "The deployment failed. See the build log for details.",
-            suggestion: buildLogTail
-                ? "Check the build log below for errors. Run your build command locally to reproduce, fix, and publish again."
-                : "No build log was produced — the failure happened before the build started. Run percher publish again; if it keeps failing with the same message, contact support.",
-            buildLogTail,
-            errorClass: "build_failed",
-            phase: "build",
-            cause: "unknown",
-            relevantFiles: [],
-            missingEnvVars: [],
-        };
-    return {
-        status: "failed",
-        app,
-        deployment,
-        fileCount: tarball.fileCount,
-        bytes: tarball.bytes,
-        error,
-    };
-}
 //# sourceMappingURL=publish.js.map