@percher/core 0.4.2 → 0.4.3

package/dist/commands/doctor.js

@@ -189,23 +189,27 @@ export async function doctor(ctx, input = {}) {
                     ? "No container found"
                     : `State: ${diag.container.state}`,
         });
-        // Container health — direct HTTP to container
+        // Container health — direct HTTP to container. The API omits
+        // latencyMs when it has no fresh probe sample — skip the suffix
+        // rather than rendering "(nullms)".
         if (diag.containerHealth) {
+            const latency = diag.containerHealth.latencyMs != null ? ` (${diag.containerHealth.latencyMs}ms)` : "";
             checks.push({
                 name: "Container health",
                 status: diag.containerHealth.healthy ? "pass" : "fail",
                 message: diag.containerHealth.healthy
-                    ? `${diag.containerHealth.path} OK (${diag.containerHealth.latencyMs}ms)`
+                    ? `${diag.containerHealth.path} OK${latency}`
                     : `${diag.containerHealth.path} — not responding`,
             });
         }
         // Public route — tests actual Caddy/TLS/DNS path
         if (diag.publicRoute) {
+            const latency = diag.publicRoute.latencyMs != null ? ` (${diag.publicRoute.latencyMs}ms)` : "";
             checks.push({
                 name: "Public route",
                 status: diag.publicRoute.healthy ? "pass" : "fail",
                 message: diag.publicRoute.healthy
-                    ? `${diag.publicRoute.url} (${diag.publicRoute.latencyMs}ms)`
+                    ? `${diag.publicRoute.url}${latency}`
                     : `${diag.publicRoute.url} — not responding`,
             });
         }
@@ -495,7 +499,84 @@ function summarize(checks, vctx = {}) {
         summary: verdict.summary,
     };
 }
+export function buildVerdictRuleContext(checks, vctx) {
+    const findCheck = (name) => checks.find((c) => c.name === name);
+    // 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 toml = findCheck("percher.toml");
+    const verdictChecks = vctx.appProvided && toml?.status === "fail"
+        ? checks.filter((c) => c.name !== "percher.toml")
+        : checks;
+    const containerDown = (vctx.containerRunning === false &&
+        vctx.containerState !== undefined &&
+        vctx.containerState !== "not-found") ||
+        vctx.containerHealthy === false;
+    return { checks, vctx, findCheck, verdictChecks, containerDown };
+}
 /**
+ * Shared by the two runtime-crashed rules — assembles the human
+ * explanation from the failing container/health/crash checks.
+ */
+function runtimeCrashExplanation({ vctx, findCheck }) {
+    const containerCheck = findCheck("Container");
+    const healthCheck = findCheck("Container health");
+    const lastCrashCheck = findCheck("Last crash");
+    const explanationBits = [];
+    if (vctx.appStatus === "crashed")
+        explanationBits.push("App is in crashed state.");
+    if (containerCheck?.status === "fail")
+        explanationBits.push(containerCheck.message);
+    if (healthCheck?.status === "fail")
+        explanationBits.push(healthCheck.message);
+    if (lastCrashCheck)
+        explanationBits.push(lastCrashCheck.message);
+    return explanationBits.length > 0
+        ? explanationBits.join(" ")
+        : "Runtime is not responding — container or health check is failing.";
+}
+// 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.
+//
+// Defined as a named const (and appended as the table's last rule)
+// so narrowing-guard verdicts and `deriveVerdict` can delegate to it.
+const FALLBACK_RULE = {
+    id: "unknown-fallback",
+    when: () => true,
+    verdict: ({ verdictChecks }) => {
+        const firstFailed = verdictChecks.find((c) => c.status === "fail");
+        return {
+            status: "needs_action",
+            diagnosis: firstFailed
+                ? {
+                    title: firstFailed.name,
+                    explanation: firstFailed.message,
+                    reasonCode: "unknown",
+                }
+                : undefined,
+            recovery: recoveryAsk({
+                prompt: firstFailed
+                    ? `Doctor flagged a problem: ${firstFailed.name} — ${firstFailed.message}. Review the checks list and surface the failing item to the user.`
+                    : "Doctor reported one or more issues. Review the checks list and surface the failing items to the user.",
+                reasonCode: "unknown",
+            }),
+            summary: firstFailed
+                ? `${firstFailed.name} failed: ${firstFailed.message}`
+                : "Doctor reported issues — review the checks list.",
+        };
+    },
+};
+/**
+ * Verdict rule table — evaluated top-to-bottom, FIRST MATCH WINS.
+ * Array order is load-bearing: earlier rules shadow later ones, and
+ * several rules are only correct because a more specific rule sits
+ * above them. Each rule carries its ordering rationale as a comment;
+ * insert new rules at a justified position, never just append.
+ *
  * 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
@@ -516,13 +597,13 @@ function summarize(checks, vctx = {}) {
  *     the new `in_progress` doctor status was effectively
  *     unreachable.
  */
-function deriveVerdict(checks, vctx) {
-    const findCheck = (name) => checks.find((c) => c.name === name);
+export const VERDICT_RULES = [
     // 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 {
+    {
+        id: "auth-missing",
+        when: ({ findCheck }) => findCheck("Auth token")?.status === "fail",
+        verdict: () => ({
             status: "blocked",
             diagnosis: {
                 title: "Authentication required",
@@ -532,127 +613,138 @@ function deriveVerdict(checks, vctx) {
             },
             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.",
-        };
-    }
+    {
+        id: "api-unreachable",
+        when: ({ findCheck }) => findCheck("API reachability")?.status === "fail",
+        verdict: ({ findCheck }) => {
+            const message = findCheck("API reachability")?.message ?? "";
+            return {
+                status: "blocked",
+                diagnosis: {
+                    title: "Percher API is unreachable",
+                    explanation: message,
+                    reasonCode: "infra_unavailable",
+                    phase: "infra",
+                },
+                recovery: recoveryAsk({
+                    prompt: `Percher API is unreachable (${message}). This is usually a transient network issue — wait a moment and try again, or check status.percher.app.`,
+                    reasonCode: "infra_unavailable",
+                    retryable: true,
+                }),
+                summary: "Cannot reach the Percher API — try again in a moment.",
+            };
+        },
+    },
     // 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.",
-        };
-    }
+    {
+        id: "toml-invalid",
+        when: ({ vctx, findCheck }) => findCheck("percher.toml")?.status === "fail" && !vctx.appProvided,
+        verdict: ({ findCheck }) => {
+            const message = findCheck("percher.toml")?.message ?? "";
+            return {
+                status: "blocked",
+                diagnosis: {
+                    title: "Invalid percher.toml",
+                    explanation: message,
+                    reasonCode: "config_invalid",
+                    phase: "config",
+                },
+                recovery: recoveryFixConfig({
+                    problems: [
+                        {
+                            file: "percher.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.",
-        };
-    }
+    {
+        id: "app-unresolved",
+        when: ({ findCheck }) => findCheck("App")?.status === "skip",
+        verdict: ({ findCheck }) => {
+            const message = findCheck("App")?.message ?? "";
+            return {
+                status: "blocked",
+                diagnosis: {
+                    title: "No app specified",
+                    explanation: message,
+                    reasonCode: "config_missing",
+                    phase: "config",
+                },
+                recovery: recoveryAsk({
+                    prompt: `${message} — pass \`--app <name>\` or run \`percher init\` in a project directory to generate a percher.toml.`,
+                    reasonCode: "config_missing",
+                }),
+                summary: "No percher.toml found and no --app supplied — pass --app or run percher init.",
+            };
+        },
+    },
     // 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;
+    //
+    // Sits above the replaced/failed rules: a provisioning app with a
+    // stale terminal lastDeploy should wait, not act.
+    {
+        id: "deploy-transitional",
+        when: ({ vctx }) => (!!vctx.lastDeployStatus && TRANSITIONAL_DEPLOY_STATUSES.has(vctx.lastDeployStatus)) ||
+            (!!vctx.appStatus && TRANSITIONAL_APP_STATUSES.has(vctx.appStatus)),
+        verdict: ({ vctx }) => {
+            const inTransitionalApp = !!vctx.appStatus && TRANSITIONAL_APP_STATUSES.has(vctx.appStatus);
+            const reasonCode = vctx.lastDeployStatus === "queued"
+                ? "deploy_queued"
+                : vctx.lastDeployStatus === "building"
+                    ? "deploy_building"
+                    : vctx.lastDeployStatus === "deploying"
+                        ? "deploy_deploying"
+                        : "deploy_queued";
+            const what = inTransitionalApp
+                ? `App ${vctx.appName ?? ""} is provisioning`
+                : `Last deploy is ${vctx.lastDeployStatus}`;
+            const recovery = vctx.lastDeployId && vctx.appName
+                ? recoveryWait({
+                    app: vctx.appName,
+                    deployId: vctx.lastDeployId,
+                    reasonCode,
+                })
+                : recoveryAsk({
+                    prompt: `${what.trim()} for ${vctx.appName ?? "this app"}. Wait for it to finish before retrying — there's no deployId to track yet.`,
+                    reasonCode,
+                });
+            return {
+                status: "in_progress",
+                diagnosis: {
+                    title: what.trim(),
+                    explanation: vctx.lastDeployId
+                        ? `${what.trim()} (deploy ${vctx.lastDeployId}). Wait for it to finish before retrying.`
+                        : `${what.trim()}. Wait for it to finish before retrying.`,
+                    reasonCode,
+                    phase: "deploy",
+                },
+                recovery,
+                summary: vctx.lastDeployId
+                    ? `${what.trim()} — wait for deploy ${vctx.lastDeployId}.`
+                    : `${what.trim()} — wait a moment and re-run.`,
+            };
+        },
+    },
     // 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
@@ -664,29 +756,36 @@ function deriveVerdict(checks, vctx) {
     // 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) {
+    {
+        id: "deploy-replaced",
+        when: ({ vctx }) => !!vctx.replacedResolution,
+        verdict: (ctx) => {
+            const r = ctx.vctx.replacedResolution;
+            // Unreachable: `when` requires replacedResolution.
+            if (!r)
+                return FALLBACK_RULE.verdict(ctx);
+            const isResolvedLive = r.recovery.nextAction === "none" && !!r.url;
+            if (isResolvedLive) {
+                return {
+                    status: "ok",
+                    recovery: { ...r.recovery, reasonCode: "replaced_by_newer" },
+                    summary: r.summary,
+                };
+            }
+            const status = r.recovery.nextAction === "wait_deploy" ? "in_progress" : "needs_action";
             return {
-                status: "ok",
+                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,
             };
-        }
-        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
@@ -694,76 +793,106 @@ function deriveVerdict(checks, vctx) {
     // 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).
+    //
+    // 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.
+    //
+    // 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).
+    //
+    // The three mode='deploy' rules below are ordered most- to
+    // least-actionable, and all sit above the no-mode dispatch rule.
+    // (a) Missing env keys → recoveryEnv. Most actionable case:
+    // agent calls percher_env_set with the exact keys.
+    {
+        id: "deploy-failed-missing-env",
+        when: ({ vctx }) => {
+            const cls = vctx.buildLogClassification;
+            return (vctx.lastDeployStatus === "failed" &&
+                vctx.inputMode === "deploy" &&
+                !!cls &&
+                cls.errorClass === "missing_env" &&
+                cls.missingEnvVars.length > 0);
+        },
+        verdict: (ctx) => {
+            const { vctx } = ctx;
+            const cls = vctx.buildLogClassification;
+            // Unreachable: `when` requires the classification.
+            if (!cls)
+                return FALLBACK_RULE.verdict(ctx);
+            return {
+                status: "needs_action",
+                diagnosis: {
+                    title: cls.title,
+                    explanation: cls.explanation,
+                    reasonCode: "missing_env",
+                    phase: "build",
+                },
+                recovery: recoveryEnv({
+                    app: vctx.appName,
+                    keys: cls.missingEnvVars,
+                }),
+                summary: vctx.appName
+                    ? `Build failed — missing env vars on ${vctx.appName}: ${cls.missingEnvVars.join(", ")}.`
+                    : `Build failed — missing env vars: ${cls.missingEnvVars.join(", ")}.`,
+            };
+        },
+    },
+    // (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).
+    {
+        id: "deploy-failed-file-problems",
+        when: ({ vctx }) => vctx.lastDeployStatus === "failed" &&
+            vctx.inputMode === "deploy" &&
+            (vctx.buildProblems ?? []).filter((p) => p.file).length > 0,
+        verdict: ({ vctx }) => {
             const cls = vctx.buildLogClassification;
-            // (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 ?? "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).
+    {
+        id: "deploy-failed-inspect-log",
+        when: ({ vctx }) => vctx.lastDeployStatus === "failed" && vctx.inputMode === "deploy",
+        verdict: ({ vctx }) => {
+            const cls = vctx.buildLogClassification;
             return {
                 status: "needs_action",
                 diagnosis: {
@@ -785,8 +914,14 @@ function deriveVerdict(checks, vctx) {
                     ? `Deploy ${vctx.lastDeployId} failed — inspect the build log.`
                     : "Last deploy failed — inspect the latest failed deploy's build log.",
             };
-        }
-        return {
+        },
+    },
+    // No mode hint — route the agent back to doctor with mode='deploy'
+    // so the deep-analysis rules above run on the follow-up call.
+    {
+        id: "deploy-failed-dispatch",
+        when: ({ vctx }) => vctx.lastDeployStatus === "failed",
+        verdict: ({ vctx }) => ({
             status: "needs_action",
             diagnosis: {
                 title: "Last deploy failed",
@@ -810,8 +945,8 @@ function deriveVerdict(checks, vctx) {
             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
@@ -819,8 +954,13 @@ function deriveVerdict(checks, vctx) {
     // 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 {
+    //
+    // Sits above the runtime-crashed rules: a suspended app's stopped
+    // container must lead with the suspension, not a crash fix.
+    {
+        id: "app-suspended",
+        when: ({ vctx }) => vctx.appStatus === "suspended",
+        verdict: ({ vctx }) => ({
             status: "needs_action",
             diagnosis: {
                 title: "App is suspended",
@@ -839,21 +979,25 @@ function deriveVerdict(checks, vctx) {
             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.`,
-        };
-    }
+    {
+        id: "all-healthy",
+        when: ({ verdictChecks }) => verdictChecks.every((c) => c.status === "pass" || c.status === "skip" || c.status === "warn"),
+        verdict: ({ vctx, verdictChecks }) => {
+            const passing = verdictChecks.filter((c) => c.status === "pass").length;
+            const noun = passing === 1 ? "check" : "checks";
+            return {
+                status: "ok",
+                recovery: recoveryNone({ reasonCode: "none" }),
+                summary: vctx.appName
+                    ? `All ${passing} ${noun} passed for ${vctx.appName}.`
+                    : `All ${passing} ${noun} passed.`,
+            };
+        },
+    },
     // 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`.
@@ -868,33 +1012,19 @@ function deriveVerdict(checks, vctx) {
     // 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") {
+    //
+    // 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).
+    {
+        id: "runtime-crashed-report",
+        when: ({ vctx, containerDown }) => (vctx.appStatus === "crashed" || containerDown) && vctx.inputMode === "runtime",
+        verdict: (ctx) => {
+            const { vctx } = ctx;
+            const explanation = runtimeCrashExplanation(ctx);
             // FUTURE12 Phase 2c — surface the crash report's
             // AI-generated explanation + suggestion in the prompt when
             // available. The watchdog/crash-handler already produces
@@ -946,79 +1076,81 @@ function deriveVerdict(checks, vctx) {
                         : `${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'.",
-        };
-    }
+        },
+    },
+    // No mode hint — route the agent back to doctor with mode='runtime'
+    // so the crash-report rule above runs on the follow-up call.
+    {
+        id: "runtime-crashed-dispatch",
+        when: ({ vctx, containerDown }) => vctx.appStatus === "crashed" || containerDown,
+        verdict: (ctx) => {
+            const { vctx } = ctx;
+            const explanation = runtimeCrashExplanation(ctx);
+            return {
+                status: "needs_action",
+                diagnosis: {
+                    title: vctx.appStatus === "crashed" ? "App crashed" : "Runtime not responding",
+                    explanation,
+                    reasonCode: "runtime_crashed",
+                    phase: "runtime",
+                },
+                recovery: {
+                    retryable: false,
+                    nextAction: "run_doctor",
+                    suggestedTool: "percher_doctor",
+                    args: { app: vctx.appName, mode: "runtime" },
+                    reasonCode: "runtime_crashed",
+                },
+                summary: vctx.appName
+                    ? `${vctx.appName} runtime needs investigation — call percher_doctor with mode='runtime'.`
+                    : "Runtime needs investigation — call percher_doctor with mode='runtime'.",
+            };
+        },
+    },
     // 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.",
-    };
+    {
+        id: "public-route-unhealthy",
+        when: ({ vctx }) => vctx.publicRouteHealthy === false,
+        verdict: ({ vctx, findCheck }) => {
+            const routeCheck = findCheck("Public route");
+            return {
+                status: "needs_action",
+                diagnosis: {
+                    title: "Public route is not responding",
+                    explanation: routeCheck?.message ??
+                        "Container looks healthy but the public URL isn't responding — route reconcile usually self-heals.",
+                    reasonCode: "infra_transient",
+                    phase: "infra",
+                },
+                recovery: {
+                    retryable: true,
+                    nextAction: "retry",
+                    suggestedTool: "percher_doctor",
+                    args: { app: vctx.appName },
+                    reasonCode: "infra_transient",
+                },
+                summary: vctx.appName
+                    ? `${vctx.appName} public route is failing — likely transient, re-run doctor in a moment.`
+                    : "Public route is failing — likely transient, re-run doctor in a moment.",
+            };
+        },
+    },
+    FALLBACK_RULE,
+];
+/**
+ * Walk VERDICT_RULES top-to-bottom and return the first matching
+ * rule's verdict. The fallback rule matches everything, so the `??`
+ * arm is unreachable in practice — it exists so a future table edit
+ * that drops the fallback can't make this function partial.
+ */
+function deriveVerdict(checks, vctx) {
+    const ctx = buildVerdictRuleContext(checks, vctx);
+    const rule = VERDICT_RULES.find((r) => r.when(ctx)) ?? FALLBACK_RULE;
+    return rule.verdict(ctx);
 }
 //# sourceMappingURL=doctor.js.map