@percher/core 0.3.0 → 0.4.1

package/dist/commands/publish.js

@@ -1,15 +1,18 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { PercherApiError, PercherClient, isDeployAlreadyInProgress, } from "@percher/client";
-import { parseFile } from "@percher/toml";
-import { z } from "zod/v3";
-import { classifyError } from "../error-classifier";
+import { isDeployAlreadyInProgress, PercherApiError, PercherClient, } from "@percher/client";
+import { TIMEOUTS } from "@percher/shared/timeouts";
+import { PercherTomlError, parseFile } from "@percher/toml";
+import { z } from "zod";
+import { renderDeployEvent } from "../event-renderer";
 import { pollDeployment } from "../poll-deployment";
-import { RECOVERY_NEEDS_LOGIN, RECOVERY_NONE, recoveryAsk, recoveryDoctor, recoveryEnv, recoveryFixConfig, recoveryFromErrorClass, recoveryWait, } from "../recovery";
+import { runDeployWithRetry } from "../publish-retry";
+import { RECOVERY_NEEDS_LOGIN, RECOVERY_NONE, recoveryAsk, recoveryDoctor, recoveryEnv, recoveryFixConfig, recoveryWait, } from "../recovery";
 import { createTarball } from "../tarball";
 import { scanForMissingBuildEnvRefs } from "./env-scan";
 import { init } from "./init";
 import { login } from "./login";
+import { classifyPublishApiError } from "./publish-api-error";
 import { buildFailureResult } from "./publish-failure";
 import { resolveNodeVersion } from "./publish-node";
 import { resolveReplaced } from "./wait-deploy";
@@ -159,6 +162,20 @@ export async function publish(ctx, input = {}) {
         return await publishInner(ctx, input);
     }
     catch (err) {
+        // Dogfood 2026-05-13 Fynd #2 — business-rule 403s (plan limits,
+        // rate limits, account suspension) used to land in the
+        // "Unexpected error / network issue / Percher bug" branch below,
+        // sending users on a wild goose chase when the real fix was
+        // "upgrade or delete an app". The classifier matches the known
+        // PercherApiError codes and returns a structured failure with the
+        // right title + actionable suggestion. Anything not matched falls
+        // through to the generic catch-all.
+        const classified = classifyPublishApiError(err, {
+            configPath: tomlPathFor(ctx.cwd),
+            bundle: { fileCount: 0, bytes: 0 },
+        });
+        if (classified)
+            return classified;
         // Catch-all: any uncaught exception becomes a structured failure result.
         // This guarantees agents always get JSON, never a raw stack trace.
         const message = err instanceof Error ? err.message : String(err);
@@ -187,20 +204,108 @@ export async function publish(ctx, input = {}) {
 }
 async function publishInner(ctx, input) {
     const t0 = Date.now();
+    // ── 0. Identity banner ─────────────────────────────────────────────
+    //
+    // Fas 2 F2-#7 (dogfood 2026-05-13). The CLI silently falls back to
+    // `~/.percher/config.json` when `PERCHER_TOKEN` env var is unset,
+    // which is convenient — except when env-var management is flaky
+    // (e.g. a bash session that loses the export between sub-commands)
+    // and the fallback ends up being a different user's token. The
+    // user thinks they're publishing as smoke-test@; the deploy lands
+    // on the admin account. Verified live: a Fas-2 retest cycle put
+    // two apps on the wrong account before the cause was traced.
+    //
+    // Surfacing the resolved identity as the FIRST output of `publish`
+    // makes the mismatch visible immediately. Best-effort: a network
+    // glitch or a 401 from whoami shouldn't abort publish — the
+    // downstream auth checks already handle real auth failure with
+    // proper recovery (`needs_login`). Here we only render when we
+    // can; otherwise stay silent and let the later checks speak.
+    //
+    // Skipped on dry-run: the contract there is "no API calls at all"
+    // (asserted by commands.publish.test.ts), and dry-run users
+    // typically know which account they're targeting because they
+    // just ran it locally to inspect bundle size.
+    if (!input.dryRun) {
+        try {
+            const me = await ctx.client.auth.whoami();
+            ctx.status(`Signed in as ${me.email}`);
+        }
+        catch {
+            // Swallow: whoami failure isn't a publish blocker — the actual
+            // publish steps below run their own auth and surface the right
+            // recovery shape if the token is bad.
+        }
+    }
     // ── 1. Config ──────────────────────────────────────────────────────
     ctx.status("[1/4] Reading config...");
     let config;
     try {
         config = await loadOrGenerate(ctx);
     }
-    catch {
+    catch (err) {
+        // FUTURE11 Fas 2 — differentiate by the toml package's typed error.
+        // The old catch swallowed every cause and reported the same
+        // generic "Could not generate config" for three different failure
+        // modes (parse error, schema validation, auto-detection miss).
+        // Now we surface the real reason so the user/agent gets actionable
+        // guidance (line number on parse, schema bullet list on
+        // validation, "no framework detected" only on the actual init
+        // miss).
+        if (err instanceof PercherTomlError) {
+            if (err.code === "PARSE_ERROR") {
+                return {
+                    status: "failed",
+                    fileCount: 0,
+                    bytes: 0,
+                    error: {
+                        title: "percher.toml has invalid TOML syntax",
+                        explanation: err.message,
+                        suggestion: "Fix the syntax error and retry publish.",
+                    },
+                    recovery: recoveryFixConfig({
+                        problems: [{ file: "percher.toml", message: err.message }],
+                        reasonCode: "config_invalid",
+                    }),
+                    summary: "percher.toml has invalid TOML syntax — fix and retry.",
+                    configPath: tomlPathFor(ctx.cwd),
+                    bundle: { fileCount: 0, bytes: 0 },
+                };
+            }
+            if (err.code === "VALIDATION_ERROR") {
+                const problems = (err.issues ?? []).map((i) => ({
+                    file: "percher.toml",
+                    message: `${i.path.join(".") || "(root)"}: ${i.message}`,
+                }));
+                const bullets = problems.map((p) => `  - ${p.message}`).join("\n");
+                const count = problems.length;
+                return {
+                    status: "failed",
+                    fileCount: 0,
+                    bytes: 0,
+                    error: {
+                        title: "percher.toml failed schema validation",
+                        explanation: `${count} schema issue${count === 1 ? "" : "s"}:\n${bullets}`,
+                        suggestion: "Fix the schema issues above (check the percher.toml spec for valid sections/fields) and retry.",
+                    },
+                    recovery: recoveryFixConfig({ problems, reasonCode: "config_invalid" }),
+                    summary: `percher.toml failed schema validation — ${count} issue${count === 1 ? "" : "s"}.`,
+                    configPath: tomlPathFor(ctx.cwd),
+                    bundle: { fileCount: 0, bytes: 0 },
+                };
+            }
+            // FILE_NOT_FOUND falls through to the init-failure branch below
+            // — loadOrGenerate should normally run init on FILE_NOT_FOUND,
+            // so reaching this point means init itself failed to fill the
+            // gap.
+        }
         return {
             status: "failed",
             fileCount: 0,
             bytes: 0,
             error: {
-                title: "Could not generate config",
-                explanation: "percher.toml could not be auto-generated for this project.",
+                title: "Couldn't auto-generate percher.toml",
+                explanation: "No percher.toml found and auto-detection couldn't determine your framework.",
                 suggestion: "Create a percher.toml manually with at least [app] name and runtime, then try again.",
             },
             recovery: recoveryFixConfig({
@@ -294,148 +399,256 @@ async function publishInner(ctx, input) {
         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.)`);
     }
-    // ── 4. Upload ──────────────────────────────────────────────────────
-    const uploadStart = Date.now();
-    ctx.status("[3/4] Uploading...");
-    let deployment;
+    // ── 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 deployResponse = await ctx.client.apps.deploy(app.id, {
-            tarball: tarball.stream,
-            type: input.preview ? "preview" : undefined,
-            note: input.message,
-            noCache: input.noCache,
-        });
-        // 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";
+        const preflight = await ctx.client.platform.preflight();
+        if (!preflight.accept) {
+            const reasonText = preflight.reason === "worker_circuit_breaker_open"
+                ? "platform circuit breaker is open — workers are restarting"
+                : preflight.reason === "worker_unhealthy"
+                    ? "build worker is currently unreachable"
+                    : "platform is currently unavailable";
             return {
                 status: "failed",
                 app,
                 fileCount: tarball.fileCount,
                 bytes: tarball.bytes,
                 error: {
-                    title: "Required env keys not set",
-                    explanation: `${keys.length} env ${keys.length === 1 ? "key is" : "keys are"} ${sourceText} but missing from the env store: ${keys.join(", ")}.`,
-                    suggestion: `Run \`bunx percher env set ${keys[0] ?? "KEY"}=value\` (and similarly for the rest) and re-publish.`,
-                    errorClass: "missing_env",
+                    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",
-                    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: {
+                    retryable: true,
+                    nextAction: "retry",
+                    suggestedTool: "percher_publish",
+                    args: {},
+                    reasonCode: "infra_unavailable",
                 },
-                recovery: recoveryFixConfig({
-                    problems,
-                    reasonCode: "env_key_undeclared",
-                }),
-                summary: `${uniqueKeys.length} undeclared env ${uniqueKeys.length === 1 ? "key" : "keys"} in source: ${uniqueKeys.join(", ")}.`,
+                summary: `Preflight refused — ${reasonText}.`,
                 configPath: 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",
+        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("[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,
                 }),
-                summary: `Daily ${kind}-deploy quota reached (${used}/${limit}). Resets ${resetAt}.`,
-                configPath: tomlPathFor(ctx.cwd),
-                bundle: { fileCount: tarball.fileCount, bytes: tarball.bytes },
-            };
+                onRetry: ({ attempt, decision }) => {
+                    ctx.status(`Retrying after ${Math.round(decision.delayMs / 1000)}s — ${decision.reason} (attempt ${attempt + 1}/4)…`);
+                },
+            });
+            if (deployAttempts > 1) {
+                ctx.status(`Recovered after ${deployAttempts - 1} retry${deployAttempts > 2 ? "ies" : ""}.`);
+            }
+            // 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;
         }
-        throw err;
     }
     // Surface the auto-replace one-shot signal — only the initial POST
     // response carries it, so capture before the polling loop reassigns
@@ -474,7 +687,7 @@ async function publishInner(ctx, input) {
     // ── 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;
     // Heartbeat tracking lives in the caller because pollDeployment is a
@@ -509,6 +722,16 @@ async function publishInner(ctx, input) {
                     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.
@@ -599,6 +822,7 @@ async function publishInner(ctx, input) {
     // any /events fetch failure or post-login retry path. Codex P2
     // follow-up on 9e5ceee.
     const cacheHit = deployment.cacheHit;
+    const cacheStatus = deployment.cacheStatus;
     return {
         status: "live",
         url,
@@ -616,7 +840,20 @@ async function publishInner(ctx, input) {
         replacedPreview,
         firstDeploy: firstDeploy || undefined,
         cacheHit,
+        cacheStatus,
+        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,
@@ -637,6 +874,8 @@ async function handleUnauthorized(ctx, config, tarball, input) {
         try {
             const deviceClient = new PercherClient({
                 apiUrl: ctx.client.apiUrl,
+                // FUTURE6 — preserve MCP session id across the device-code mint.
+                sessionId: ctx.client.sessionId,
             });
             const { verificationUri, userCode } = await deviceClient.auth.requestDeviceCode();
             const loginUrl = `${verificationUri}?code=${userCode}`;
@@ -675,6 +914,7 @@ async function handleUnauthorized(ctx, config, tarball, input) {
     ctx.client = new PercherClient({
         apiUrl: ctx.client.apiUrl,
         token: newToken,
+        sessionId: ctx.client.sessionId,
     });
     // Re-create tarball since stream is consumed
     const freshTarball = await createTarball({ cwd: ctx.cwd, config });
@@ -682,17 +922,32 @@ async function handleUnauthorized(ctx, config, tarball, input) {
     let app;
     ({ app, firstDeploy: firstDeployRetry } = await ensureApp(ctx, config));
     ctx.status("Uploading...");
+    // 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 deployResponse = await ctx.client.apps.deploy(app.id, {
-            tarball: freshTarball.stream,
-            // 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,
+        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
@@ -746,7 +1001,7 @@ async function handleUnauthorized(ctx, config, tarball, input) {
             bundle: { fileCount: freshTarball.fileCount, bytes: freshTarball.bytes },
         };
     }
-    const timeoutMs = 5 * 60 * 1000;
+    const timeoutMs = TIMEOUTS.clientPublishPoll;
     const start = Date.now();
     while (deployment.status !== "live" &&
         deployment.status !== "failed" &&
@@ -818,6 +1073,13 @@ async function handleUnauthorized(ctx, config, tarball, input) {
         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,