@percher/core 0.2.6 → 0.4.0

package/dist/commands/doctor.js

@@ -1,12 +1,56 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { PercherTomlError, parseFile } from "@percher/toml";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { readPercherTomlAppName } from "../app-name";
+import { classifyError } from "../error-classifier";
+import { buildProblemToRecoveryProblem, recoveryAsk, recoveryEnv, recoveryFixConfig, recoveryFixProblems, recoveryInspectBuildLog, recoveryLogin, recoveryNone, recoveryWait, } from "../recovery";
+import { resolveReplaced } from "./wait-deploy";
 export const doctorInputSchema = z.object({
     app: z.string().optional(),
     json: z.boolean().optional(),
+    /**
+     * FUTURE12 Phase 2b/Codex round 5 fix — accept the dispatch-mode
+     * hint emitted by `recoveryDoctor`. Public agent path defaults to
+     * `auto`; the other modes are passed through from a previous
+     * recovery's `args.mode` (e.g. `mode: "deploy"` after a build
+     * failure routes the agent back to doctor with that specific
+     * deploy in mind). When `mode` is set, doctor's dispatch breaks
+     * the otherwise-infinite `run_doctor` recursion by falling back
+     * to the right concrete recovery for the case (build_failed →
+     * inspect_build_log, runtime_crashed → ask_user with crash
+     * details). Phase 2c will replace those fallbacks with deeper
+     * mode-specific analysis (build-log fetch + classification, etc).
+     */
+    mode: z.enum(["auto", "deploy", "runtime", "config", "env", "account"]).optional(),
+    /**
+     * FUTURE12 Phase 2b/Codex round 5 fix — accept a specific deploy
+     * id to inspect. When set AND the value differs from the app's
+     * latest deploy, doctor fetches that specific deploy and uses its
+     * status as the dispatch target instead of `lastDeploy` from
+     * `/diagnostics`. Pre-fix, Zod silently stripped this field and
+     * the agent's targeted `run_doctor` recovery degraded to an
+     * untargeted `doctor(app)` call.
+     */
+    deployId: z.string().optional(),
 });
+/**
+ * Phase 6.2 — exported for tests. Returns true when a deploy is in a
+ * pre-terminal state (`queued` or `building`) AND its createdAt is
+ * more than `STUCK_DEPLOY_THRESHOLD_MS` in the past. Mirrors the
+ * platform-side stale-deploy reconciler's 15-minute window so the
+ * user-facing callout fires only once we're sure the stall isn't
+ * legitimate slow-progress.
+ */
+export const STUCK_DEPLOY_THRESHOLD_MS = 15 * 60 * 1000;
+export function isStuckDeploy(status, createdAt, now = Date.now()) {
+    if (status !== "building" && status !== "queued")
+        return false;
+    const created = Date.parse(createdAt);
+    if (Number.isNaN(created))
+        return false;
+    return now - created > STUCK_DEPLOY_THRESHOLD_MS;
+}
 export async function doctor(ctx, input = {}) {
     const checks = [];
     // 1. Auth token
@@ -17,7 +61,7 @@ export async function doctor(ctx, input = {}) {
         message: hasToken ? "Token configured" : "No token found. Run: percher login",
     });
     if (!hasToken) {
-        return summarize(checks);
+        return summarize(checks, { appProvided: !!input.app });
     }
     // 2. API reachability + user account
     try {
@@ -42,7 +86,7 @@ export async function doctor(ctx, input = {}) {
             status: "fail",
             message: `Cannot reach ${ctx.client.apiUrl}: ${err.message}`,
         });
-        return summarize(checks);
+        return summarize(checks, { appProvided: !!input.app });
     }
     // 4. percher.toml — validated *before* app resolution. readPercherTomlAppName
     // returns null on parse errors AND when the file is missing, so if we waited
@@ -100,11 +144,34 @@ export async function doctor(ctx, input = {}) {
             ? "percher.toml is invalid — fix the issues above and re-run"
             : "No app specified and no percher.toml found";
         checks.push({ name: "App", status: "skip", message: reason });
-        return summarize(checks);
+        return summarize(checks, { appProvided: !!input.app });
     }
     // 5. Fetch diagnostics from the API
+    let appStatus;
+    let lastDeployStatus;
+    let lastDeployId;
+    let containerState;
+    let containerRunning;
+    let containerHealthy;
+    let publicRouteHealthy;
+    let lastCrashSeverity;
+    let lastCrashAt;
+    let replacedResolution;
+    // FUTURE12 Phase 2c — pre-fetched deep-analysis inputs.
+    let buildLogClassification;
+    let buildProblems;
+    let crashReport;
     try {
         const diag = await ctx.client.apps.getDiagnostics(appName);
+        appStatus = diag.app.status;
+        lastDeployStatus = diag.lastDeploy?.status;
+        lastDeployId = diag.lastDeploy?.id;
+        containerState = diag.container.state;
+        containerRunning = diag.container.running;
+        containerHealthy = diag.containerHealth?.healthy;
+        publicRouteHealthy = diag.publicRoute?.healthy;
+        lastCrashSeverity = diag.lastCrash?.severity;
+        lastCrashAt = diag.lastCrash?.createdAt;
         // App status
         const appOk = diag.app.status === "live";
         checks.push({
@@ -173,6 +240,19 @@ export async function doctor(ctx, input = {}) {
                 status: deployOk ? "pass" : "warn",
                 message: `${diag.lastDeploy.status} (${diag.lastDeploy.createdAt})`,
             });
+            // Phase 6.2 — stuck-deploy callout. The platform's reconciler
+            // self-heals stale `building` rows after 15 minutes (Phase 3 of
+            // this same plan), so anything still `building` past that
+            // window means the user's local poll lost track AND the
+            // platform hasn't yet swept it. Surface a clear next-step so
+            // the user doesn't sit waiting on a deploy that won't progress.
+            if (isStuckDeploy(diag.lastDeploy.status, diag.lastDeploy.createdAt)) {
+                checks.push({
+                    name: "Deploy stuck",
+                    status: "warn",
+                    message: "Last deploy has been in-progress > 15 min — likely platform restart mid-build. Run `percher publish` again; the platform will clear the stuck row within ~2 min.",
+                });
+            }
         }
         // Last crash
         if (diag.lastCrash) {
@@ -182,6 +262,187 @@ export async function doctor(ctx, input = {}) {
                 message: `Exit code ${diag.lastCrash.exitCode}${diag.lastCrash.oomKilled ? " (OOM killed)" : ""} at ${diag.lastCrash.createdAt}`,
             });
         }
+        // Targeted deploy override — Codex round 5 P2 fix. When the
+        // caller supplied a specific deployId (e.g. echoed back from a
+        // previous `recoveryDoctor({ deployId })`), prefer that deploy's
+        // status over `diag.lastDeploy` for the verdict. Without this,
+        // the agent's targeted recovery degraded to an untargeted
+        // doctor(app) call after Zod silently stripped the field.
+        if (input.deployId && input.deployId !== diag.lastDeploy?.id) {
+            try {
+                const targeted = await ctx.client.apps.getDeployment(appName, input.deployId);
+                lastDeployStatus = targeted.status;
+                lastDeployId = targeted.id;
+                checks.push({
+                    name: `Deploy ${targeted.id}`,
+                    status: targeted.status === "live" ? "pass" : targeted.status === "failed" ? "fail" : "warn",
+                    message: `${targeted.status}${targeted.errorMessage ? ` — ${targeted.errorMessage}` : ""}`,
+                });
+            }
+            catch (err) {
+                // Codex round 7 P2: clear lastDeployStatus/Id on fetch
+                // failure so diag.lastDeploy doesn't leak into the verdict.
+                // Without this, an agent asking about a missing/stale deploy
+                // (404 from getDeployment) could still receive
+                // `replaced_by_newer` for the app's current head when
+                // diag.lastDeploy.status happened to be "replaced" — the
+                // resolver-gate would fire on the unrelated head deploy and
+                // shadow the agent's explicit request. Clearing the deploy
+                // fields means: replaced-resolver gate fails, transitional/
+                // failed-deploy branches skip, dispatch falls through to
+                // case 7 where the failed `Deploy <id>` check we just
+                // pushed drives the verdict.
+                lastDeployStatus = undefined;
+                lastDeployId = undefined;
+                checks.push({
+                    name: `Deploy ${input.deployId}`,
+                    status: "fail",
+                    message: `Could not fetch deploy: ${err.message}`,
+                });
+            }
+        }
+        // Pre-resolve `replaced` here (deriveVerdict is sync, and
+        // resolveReplaced may make an API round-trip via listDeploys).
+        // We fetch the App + full Deployment so resolveReplaced has the
+        // shape it expects — diag.lastDeploy is a thin projection without
+        // the `type` field that resolveReplaced uses to filter the lookup.
+        //
+        // Codex round 6 P2 fix: resolve against the EFFECTIVE deploy, not
+        // diag.lastDeploy. When `input.deployId` is set, the targeted
+        // override above replaced lastDeployStatus/Id with the targeted
+        // deploy's values; running the resolver against diag.lastDeploy
+        // here would let an unrelated `replaced` lastDeploy shadow the
+        // agent's specific request (e.g. `mode='deploy', deployId='dep_failed'`
+        // would return `replaced_by_newer` for the current live deploy
+        // instead of `inspect_build_log` for `dep_failed`). The simple
+        // rule: only run resolver if the EFFECTIVE deploy itself is
+        // `replaced`.
+        if (lastDeployStatus === "replaced" && lastDeployId) {
+            try {
+                const [app, replacedDeployment] = await Promise.all([
+                    ctx.client.apps.get(appName),
+                    ctx.client.apps.getDeployment(appName, lastDeployId),
+                ]);
+                const resolved = await resolveReplaced({ ctx, app, replacedDeployment });
+                replacedResolution = {
+                    recovery: resolved.recovery,
+                    url: resolved.url,
+                    summary: resolved.summary,
+                    resolvedDeployId: resolved.resolvedDeployment?.id,
+                };
+            }
+            catch (err) {
+                // Resolver fetch failed — fall through to the dispatch's
+                // generic "replaced but couldn't resolve" path so the verdict
+                // still routes the user somewhere actionable.
+                replacedResolution = {
+                    recovery: recoveryAsk({
+                        reasonCode: "replaced_by_newer",
+                        prompt: `This deploy was replaced but I couldn't determine the current state (resolver fetch failed: ${err.message}). Run \`percher doctor --app ${appName}\` to inspect, or surface to the user.`,
+                    }),
+                    summary: `Couldn't resolve the replaced deploy: ${err.message}`,
+                };
+            }
+        }
+        // FUTURE12 Phase 2c — deploy-mode deep analysis. When the agent
+        // followed our previous run_doctor recovery (input.mode='deploy')
+        // and the targeted/last deploy is failed, fetch the build log
+        // and classify it so dispatch can return a specific recovery
+        // (set_env_vars / fix_problems) instead of always handing off
+        // to inspect_build_log. Pre-fix: doctor was a polite passthrough
+        // to percher_deploys_inspect.
+        if (input.mode === "deploy" && lastDeployStatus === "failed" && lastDeployId) {
+            try {
+                // Fetch full deploy (for `errorMessage` + `problems[]`) and
+                // build log in parallel — both are inputs to classifyError.
+                const [deployment, buildLog] = await Promise.all([
+                    ctx.client.apps.getDeployment(appName, lastDeployId),
+                    ctx.client.apps.getBuildLog(appName, lastDeployId).catch((logErr) => {
+                        // Log fetch can fail transiently (404 if log was pruned,
+                        // network blip post-retries). classifyError handles
+                        // missing log; we just lose some signal.
+                        checks.push({
+                            name: `Build log ${lastDeployId}`,
+                            status: "warn",
+                            message: `Could not fetch build log: ${logErr.message}`,
+                        });
+                        return "";
+                    }),
+                ]);
+                const errorMessage = deployment.errorMessage ?? "";
+                buildLogClassification = classifyError(errorMessage, buildLog);
+                buildProblems = deployment.problems;
+            }
+            catch (err) {
+                // The deployment fetch itself failed — surface as a check
+                // so the verdict can route via the case-7 ask_user fallback.
+                checks.push({
+                    name: "Deploy classification",
+                    status: "warn",
+                    message: `Could not classify deploy ${lastDeployId}: ${err.message}`,
+                });
+                buildLogClassification = null;
+            }
+        }
+        // FUTURE12 Phase 2c — runtime-mode deep analysis. When the agent
+        // followed runtime mode to inspect a crashed app, pull the
+        // crash report so dispatch can surface the AI-generated
+        // explanation + suggestion in the ask_user prompt.
+        //
+        // Codex round 8 P2 fix (revised in round 9): mirror
+        // diagnose.ts's recency guard so doctor doesn't surface a
+        // days-old AI explanation as if it explained today's outage
+        // when the app is `live` but the container probe is failing
+        // (route blip, post-restart noise, etc).
+        //
+        // The rule is intentionally simple — round 9 removed an earlier
+        // `matchesLastCrash` bypass that was wrong in practice:
+        // /diagnostics returns `lastCrash` populated with the latest
+        // crash row, and /crash-report also returns that same row, so
+        // their timestamps ALWAYS match. The bypass effectively
+        // disabled the staleness check whenever any crash had ever
+        // happened, which was the entire common case the guard was
+        // meant to catch.
+        //
+        //   - app.status === "crashed"  → trust the report; this is the
+        //     active outage and the user's question is about it.
+        //   - app.status !== "crashed"  → only trust a report fresher
+        //     than 24h. Anything older is treated as no report.
+        if (input.mode === "runtime") {
+            try {
+                const report = await ctx.client.apps.getCrashReport(appName);
+                if (!report || appStatus === "crashed") {
+                    crashReport = report;
+                }
+                else {
+                    const recencyMs = 24 * 60 * 60 * 1000;
+                    const age = Date.now() - new Date(report.createdAt).getTime();
+                    if (age > recencyMs) {
+                        // Stale + app isn't currently crashed — drop it so
+                        // dispatch falls back to the safe "check the crash
+                        // report" framing instead of confidently pushing an
+                        // old fix at today's failing route.
+                        crashReport = null;
+                        checks.push({
+                            name: "Crash report",
+                            status: "warn",
+                            message: `Latest crash report is older than 24h and the app isn't currently crashed — ignoring as stale.`,
+                        });
+                    }
+                    else {
+                        crashReport = report;
+                    }
+                }
+            }
+            catch (err) {
+                checks.push({
+                    name: "Crash report",
+                    status: "warn",
+                    message: `Could not fetch crash report: ${err.message}`,
+                });
+                crashReport = null;
+            }
+        }
     }
     catch (err) {
         checks.push({
@@ -190,15 +451,566 @@ export async function doctor(ctx, input = {}) {
             message: err.message,
         });
     }
-    return summarize(checks);
+    return summarize(checks, {
+        appName,
+        appProvided: !!input.app,
+        appStatus,
+        lastDeployStatus,
+        lastDeployId,
+        containerState,
+        containerRunning,
+        containerHealthy,
+        publicRouteHealthy,
+        lastCrashSeverity: lastCrashSeverity ?? undefined,
+        lastCrashAt,
+        replacedResolution,
+        inputMode: input.mode,
+        buildLogClassification,
+        buildProblems,
+        crashReport,
+    });
 }
-function summarize(checks) {
+/**
+ * lastDeploy / app.status values that mean "still in motion — agent
+ * should wait, not act." `replaced` is intentionally excluded: it's
+ * terminal-but-not-failed and gets its own routing in Phase 2b.
+ */
+const TRANSITIONAL_DEPLOY_STATUSES = new Set(["queued", "building", "deploying"]);
+const TRANSITIONAL_APP_STATUSES = new Set(["provisioning"]);
+function summarize(checks, vctx = {}) {
+    const passed = checks.filter((c) => c.status === "pass").length;
+    const failed = checks.filter((c) => c.status === "fail").length;
+    const warned = checks.filter((c) => c.status === "warn").length;
+    const total = checks.filter((c) => c.status !== "skip").length;
+    const verdict = deriveVerdict(checks, vctx);
     return {
         checks,
-        passed: checks.filter((c) => c.status === "pass").length,
-        failed: checks.filter((c) => c.status === "fail").length,
-        warned: checks.filter((c) => c.status === "warn").length,
-        total: checks.filter((c) => c.status !== "skip").length,
+        passed,
+        failed,
+        warned,
+        total,
+        status: verdict.status,
+        diagnosis: verdict.diagnosis,
+        recovery: verdict.recovery,
+        summary: verdict.summary,
+    };
+}
+/**
+ * FUTURE12 Phase 2a — pattern-match the check list against the
+ * blocking cases doctor handles today. Anything we don't recognise
+ * yet falls through to a safe `needs_action` / `ask_user` so an
+ * agent doesn't think it can auto-resolve from a generic failure.
+ * Phase 2b adds the deploy/build/runtime/replaced-specific paths.
+ *
+ * Two Codex P2 fixes baked into Phase 2a (review of fc267a3):
+ *
+ *  1. An invalid cwd `percher.toml` MUST NOT block the verdict when
+ *     the caller passed `--app` — that target was resolved
+ *     independently of cwd toml. Pre-fix, `doctor --app foo` against
+ *     a healthy app would still come back blocked/config_invalid if
+ *     the local toml happened to be broken.
+ *  2. Transitional states (`lastDeploy.status` queued/building/
+ *     deploying, or `app.status` provisioning) MUST surface as
+ *     `in_progress` + `wait_deploy`, not the warn-collapsed `ok`.
+ *     Pre-fix, those states looked fully resolved to MCP agents and
+ *     the new `in_progress` doctor status was effectively
+ *     unreachable.
+ */
+function deriveVerdict(checks, vctx) {
+    const findCheck = (name) => checks.find((c) => c.name === name);
+    // Case 1 — auth missing. First check in doctor's flow; if it fails
+    // we never reach the other gates, so handle it before anything else.
+    const auth = findCheck("Auth token");
+    if (auth?.status === "fail") {
+        return {
+            status: "blocked",
+            diagnosis: {
+                title: "Authentication required",
+                explanation: "No Percher token is configured for this CLI.",
+                reasonCode: "auth_required",
+                phase: "auth",
+            },
+            recovery: recoveryLogin({ reasonCode: "auth_required" }),
+            summary: "Login required: run `percher login` (or set PERCHER_TOKEN).",
+        };
+    }
+    // Case 2 — API can't be reached. Likely-transient infra problem,
+    // but doctor can't see whether it'll recover; surface to the user.
+    const api = findCheck("API reachability");
+    if (api?.status === "fail") {
+        return {
+            status: "blocked",
+            diagnosis: {
+                title: "Percher API is unreachable",
+                explanation: api.message,
+                reasonCode: "infra_unavailable",
+                phase: "infra",
+            },
+            recovery: recoveryAsk({
+                prompt: `Percher API is unreachable (${api.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.",
+        };
+    }
+    // Case 3 — percher.toml present but invalid. Only blocks the
+    // verdict when we actually depend on it (no `--app` provided).
+    // With explicit `--app`, the cwd toml is irrelevant for the
+    // resolved target, so a broken local file shouldn't poison a
+    // healthy app's verdict. (Codex P2 #1 fix.)
+    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.",
+        };
+    }
+    // Case 4 — no app to inspect. The "App" skip-row is set when no
+    // --app was passed AND no parseable percher.toml was found in cwd.
+    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.",
+        };
+    }
+    // Case 5 — transitional state. A lastDeploy in queued/building/
+    // deploying or an app in provisioning means the right next step
+    // is to wait, not to act. Surface as `in_progress` + `wait_deploy`
+    // pointing at the live deployId so agents call
+    // percher_wait_for_deploy with the right args instead of treating
+    // warn-only checks as "ok". (Codex P2 #2 fix.)
+    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.`,
+        };
+    }
+    // For verdict purposes, drop the cwd `percher.toml` check when
+    // the caller passed --app. Without this filter, a `fail` toml
+    // would force the all-pass-or-warn check below into the
+    // `needs_action` branch (case 7) even though the resolved app is
+    // fully healthy.
+    const verdictChecks = vctx.appProvided && toml?.status === "fail"
+        ? checks.filter((c) => c.name !== "percher.toml")
+        : checks;
+    // Phase 2b — signal-driven dispatches that MUST run before the
+    // happy-path collapse below. The `Last deploy` row is rendered
+    // as `warn` for any non-live status (replaced, failed, etc), so
+    // case 6's all-pass-or-warn predicate would silently hide a
+    // failed or replaced deploy. Likewise, a suspended app may
+    // surface only as a stopped container (`fail` row) but the
+    // dispatch wants to lead with the suspended explanation, not the
+    // generic runtime fix.
+    // Replaced lastDeploy. Resolution was performed up-front in
+    // `doctor()` (deriveVerdict is sync); we just emit what
+    // resolveReplaced computed.
+    if (vctx.replacedResolution) {
+        const r = vctx.replacedResolution;
+        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,
+        };
+    }
+    // lastDeploy.status === "failed". `failed` renders as `warn` in
+    // checks[] but is unambiguously not-ok. Doctor can't classify
+    // the failure cause from /diagnostics (the build log lives at a
+    // different endpoint), so route back to itself with mode='deploy'
+    // and the deployId. Phase 4 will migrate publish/wait to the
+    // same recovery so deploy-mode expansion has a single owner of
+    // build-log inspection.
+    if (vctx.lastDeployStatus === "failed") {
+        // Loop-break (Codex round 5 P2): if we're already in mode='deploy'
+        // (the agent followed our previous run_doctor recovery), emitting
+        // run_doctor again with the same args would loop forever. Fall
+        // back to inspect_build_log — the existing low-level path that
+        // surfaces the build log to the agent. Phase 2c will replace
+        // this with deeper analysis (build-log fetch + classification
+        // here in doctor) so the agent gets a `set_env_vars` /
+        // `fix_problems` recovery directly.
+        if (vctx.inputMode === "deploy") {
+            // FUTURE12 Phase 2c — deep analysis. We pre-fetched the build
+            // log and ran classifyError in doctor() above; if it produced
+            // missing env keys or structured file-located problems, emit
+            // a specific recovery the agent can act on directly.
+            // Otherwise fall back to inspect_build_log (the agent gets
+            // the raw log via percher_deploys_inspect).
+            const cls = vctx.buildLogClassification;
+            // (a) Missing env keys → recoveryEnv. Most actionable case:
+            // agent calls percher_env_set with the exact keys.
+            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(", ")}.`,
+                };
+            }
+            // (b) Structured BuildProblems with file locations → fix_problems.
+            // The agent can patch files directly without log archeology.
+            // Codex round 8 P3 fix: route through
+            // `buildProblemToRecoveryProblem` so `BuildProblem.hint` is
+            // folded into the message — agents and CLI got `Hint: <text>`
+            // appended automatically (matters for problems where the hint
+            // carries the actionable next step, e.g. malformed
+            // package.json with no line/column).
+            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.`,
+                };
+            }
+            // (c) Fallback: classified but unactionable, or unclassified.
+            // Hand off to inspect_build_log so the agent can read the raw
+            // log. This is also the no-classification path (cls === null).
+            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.",
+            };
+        }
+        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",
+            },
+            recovery: {
+                retryable: false,
+                nextAction: "run_doctor",
+                suggestedTool: "percher_doctor",
+                args: {
+                    app: vctx.appName,
+                    mode: "deploy",
+                    ...(vctx.lastDeployId ? { deployId: vctx.lastDeployId } : {}),
+                },
+                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'.",
+        };
+    }
+    // App suspended. Suspension reason isn't on /diagnostics
+    // (lives on the App row's `suspensionReason` /
+    // `suspensionOrigin`), so doctor surfaces to the user with a
+    // concrete prompt. The reasonCode `quota_exceeded` is a proxy —
+    // most owner-resumable suspensions are quota; admin/moderation
+    // suspensions would route differently if doctor had access to
+    // suspensionOrigin (Phase 6 can plumb that through if needed).
+    if (vctx.appStatus === "suspended") {
+        return {
+            status: "needs_action",
+            diagnosis: {
+                title: "App is suspended",
+                explanation: vctx.appName
+                    ? `${vctx.appName} is currently suspended. Owner-initiated and quota suspensions can be resumed from the dashboard or via the API.`
+                    : "This app is currently suspended.",
+                reasonCode: "quota_exceeded",
+                phase: "infra",
+            },
+            recovery: recoveryAsk({
+                reasonCode: "quota_exceeded",
+                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.",
+        };
+    }
+    // Case 6 — happy path. All app-level checks passed (warns are
+    // informational, not blocking).
+    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.`,
+        };
+    }
+    // Case 7 — at least one app-level check failed. Phase 2b refines
+    // the previous catch-all `ask_user`/`unknown` into specific
+    // dispatches based on structured signals from `/diagnostics`.
+    // The signal-driven cases that case 6 would otherwise collapse
+    // (replaced/failed lastDeploy, suspended app) are handled above
+    // case 6. The remaining checks-driven cases run here:
+    // crashed/runtime-down → public-route blip → genuinely unknown.
+    // 7a. Runtime crashed. App marked crashed, OR container exited /
+    // not running (without a clearer signal), OR direct container-
+    // health probe is failing. All three converge on the same
+    // recovery: hand back to doctor with `mode: "runtime"` so the
+    // runtime-focused expansion (Phase 2 step 9) can take it from
+    // here. Self-recursion via mode hint is the explicit Phase 2
+    // contract — input mode disambiguates the dispatch.
+    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.";
+        // Loop-break (Codex round 5 P2): if we're already in
+        // mode='runtime', emit a concrete ask_user with the crash
+        // details rather than recursing into ourselves. Phase 2c will
+        // replace this with crash-report fetch + classification (the
+        // crash-handler watchdog already produces structured AI-generated
+        // explanations — doctor just needs to surface them here).
+        if (vctx.inputMode === "runtime") {
+            // FUTURE12 Phase 2c — surface the crash report's
+            // AI-generated explanation + suggestion in the prompt when
+            // available. The watchdog/crash-handler already produces
+            // these via /apps/:app/crash-report; doctor just needs to
+            // pull them through.
+            const cr = vctx.crashReport;
+            const hasAnalysis = cr && cr.analysisStatus === "completed";
+            const promptParts = [];
+            if (hasAnalysis && cr.explanation) {
+                promptParts.push(`Crash explanation: ${cr.explanation}`);
+            }
+            if (hasAnalysis && cr.suggestion) {
+                promptParts.push(`Suggested fix: ${cr.suggestion}`);
+            }
+            if (cr) {
+                const exitInfo = cr.oomKilled ? `exit ${cr.exitCode} (OOM killed)` : `exit ${cr.exitCode}`;
+                promptParts.push(`Container ${exitInfo} at ${cr.createdAt}.`);
+            }
+            // Always include the basic explanation so the user has
+            // something to read even if no crash report exists.
+            promptParts.push(explanation);
+            promptParts.push(vctx.appName
+                ? `Decide whether to redeploy, raise the memory plan, or fix the code. Use percher_diagnose_crash for ${vctx.appName} if you need the full log tail.`
+                : "Decide whether to redeploy, raise the memory plan, or fix the code.");
+            return {
+                status: "needs_action",
+                diagnosis: {
+                    title: vctx.appStatus === "crashed" ? "App crashed" : "Runtime not responding",
+                    explanation: hasAnalysis && cr.explanation ? `${cr.explanation} ${explanation}` : explanation,
+                    reasonCode: "runtime_crashed",
+                    phase: "runtime",
+                },
+                recovery: recoveryAsk({
+                    reasonCode: "runtime_crashed",
+                    prompt: promptParts.join(" "),
+                    options: cr?.severity === "critical" ? ["redeploy", "fix code", "upgrade plan"] : undefined,
+                }),
+                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'.",
+        };
+    }
+    // 7b. Public route is the only thing failing — container is up
+    // and healthy, but the external probe via Caddy/TLS/DNS isn't
+    // responding. This is usually a transient route-reconcile blip
+    // that self-heals; recommend `retry` so the agent re-runs doctor
+    // (or the user retries publish) rather than asking the user to
+    // act manually.
+    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.",
+        };
+    }
+    // 7c. Genuinely unknown — none of the structured signals above
+    // matched. Keep the safe fallback so an agent doesn't think it
+    // can auto-resolve. This is what Phase 2a shipped; Phase 2b only
+    // narrows the surface that lands here.
+    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.",
     };
 }
 //# sourceMappingURL=doctor.js.map