gencow 0.1.252 → 0.1.254

package/core/index.js

@@ -4,6 +4,78 @@ function defineApi(api) {
 }
 
 // ../core/src/http-route.ts
+var discardedResponseSymbol = /* @__PURE__ */ Symbol.for("@gencow/core/http-route/discarded-response/v1");
+var discardedResponseCauseSymbol = /* @__PURE__ */ Symbol.for("@gencow/core/http-route/discarded-response-cause/v1");
+var outputValidationFailureSymbol = /* @__PURE__ */ Symbol.for("@gencow/core/http-route/output-validation-failure/v1");
+function getHttpRouteDiscardedResponse(value) {
+  if (!value || typeof value !== "object" && typeof value !== "function") return void 0;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, discardedResponseSymbol);
+    const response = descriptor && "value" in descriptor ? descriptor.value : void 0;
+    return response instanceof Response ? response : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function getHttpRouteDiscardedResponseCause(value) {
+  if (!value || typeof value !== "object" && typeof value !== "function") return void 0;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, discardedResponseCauseSymbol);
+    return descriptor && "value" in descriptor ? descriptor.value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isHttpRouteOutputValidationFailure(value) {
+  if (!value || typeof value !== "object" && typeof value !== "function") return false;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, outputValidationFailureSymbol);
+    return !!descriptor && "value" in descriptor && descriptor.value === true;
+  } catch {
+    return false;
+  }
+}
+function addDiscardedResponse(value, response) {
+  try {
+    Object.defineProperty(value, discardedResponseSymbol, {
+      configurable: false,
+      enumerable: false,
+      value: response,
+      writable: false
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function routeResultResponse(value) {
+  if (value instanceof Response) return value;
+  return value?.body instanceof Response ? value.body : void 0;
+}
+function markDroppedResponse(value, response) {
+  if (!response || routeResultResponse(value) === response) return value;
+  if (value && (typeof value === "object" || typeof value === "function")) {
+    addDiscardedResponse(value, response);
+  }
+  return value;
+}
+function markDiscardedResponseError(error, response) {
+  if (error && (typeof error === "object" || typeof error === "function")) {
+    if (addDiscardedResponse(error, response)) return error;
+  }
+  const wrapped = error instanceof HttpRouteOutputValidationError ? new HttpRouteOutputValidationError(error.message) : new Error("httpRoute output validation failed", { cause: error });
+  addDiscardedResponse(wrapped, response);
+  try {
+    Object.defineProperty(wrapped, discardedResponseCauseSymbol, {
+      configurable: false,
+      enumerable: false,
+      value: error,
+      writable: false
+    });
+  } catch {
+  }
+  return wrapped;
+}
 function hasStandardSchema(schema) {
   return !!schema && typeof schema === "object" && "~standard" in schema && !!schema["~standard"] && typeof schema["~standard"].validate === "function";
 }
@@ -65,10 +137,28 @@ async function buildInputFromRequest(method, req) {
 }
 async function maybeValidateRouteOutput(result, outputSchema) {
   if (!outputSchema) return result;
-  const isSuccessStatus = result?.status === void 0 || result.status < 400;
-  if (!isSuccessStatus) return result;
-  const validatedBody = await validateOutput(outputSchema, result?.body);
-  return { status: result?.status, headers: result?.headers, body: validatedBody };
+  const source = routeResultResponse(result);
+  try {
+    const isSuccessStatus = result instanceof Response ? result.status < 400 : result?.status === void 0 || result.status < 400;
+    if (!isSuccessStatus) return result;
+    const response = result instanceof Response ? result : void 0;
+    const validatedBody = await validateOutput(
+      outputSchema,
+      response ? response.body : result?.body
+    );
+    if (response) {
+      if (validatedBody === response.body) return result;
+      return markDroppedResponse(
+        { status: response.status, headers: response.headers, body: validatedBody },
+        source
+      );
+    }
+    const normalized = { status: result?.status, headers: result?.headers, body: validatedBody };
+    return markDroppedResponse(normalized, source);
+  } catch (error) {
+    if (source) throw markDiscardedResponseError(error, source);
+    throw error;
+  }
 }
 function composeRouteMiddlewares(middlewares, handler, inputSchema, outputSchema, inputValidationIndex, outputValidationIndex) {
   return async (initialContext, initialInput, request) => {
@@ -210,15 +300,7 @@ var HttpRouteBuilderImpl = class _HttpRouteBuilderImpl {
     const inputSchema = this.inputSchema;
     const outputSchema = this.outputSchema;
     const inputErrorMapper = this.inputErrorMapper;
-    const runRoute = composeRouteMiddlewares(
-      this.middlewares,
-      handler,
-      inputSchema,
-      outputSchema,
-      this.inputValidationIndex,
-      this.outputValidationIndex
-    );
-    const wrappedHandler = async (ctx, req) => {
+    const invokeRoute = async (ctx, req) => {
       let normalizedInput;
       try {
         normalizedInput = inputSchema ? await buildInputFromRequest(method, req) : void 0;
@@ -231,14 +313,37 @@ var HttpRouteBuilderImpl = class _HttpRouteBuilderImpl {
       }
       let result;
       try {
-        result = await runRoute(ctx, normalizedInput, req);
+        result = await composeRouteMiddlewares(
+          this.middlewares,
+          handler,
+          inputSchema,
+          outputSchema,
+          this.inputValidationIndex,
+          this.outputValidationIndex
+        )(ctx, normalizedInput, req);
       } catch (err) {
         if (err instanceof HttpRouteInputValidationError) {
           if (inputErrorMapper) return await inputErrorMapper(err.issues);
           return { status: 400, body: { error: err.message } };
         }
         if (err instanceof HttpRouteOutputValidationError) {
-          return { status: 500, body: { error: `Output validation failed: ${err.message}` } };
+          const discardedResponse = getHttpRouteDiscardedResponse(err);
+          const failure = {
+            status: 500,
+            body: {
+              error: discardedResponse ? "Output validation failed" : `Output validation failed: ${err.message}`
+            }
+          };
+          if (discardedResponse) {
+            addDiscardedResponse(failure, discardedResponse);
+            Object.defineProperty(failure, outputValidationFailureSymbol, {
+              configurable: false,
+              enumerable: false,
+              value: true,
+              writable: false
+            });
+          }
+          return failure;
         }
         throw err;
       }
@@ -248,7 +353,7 @@ var HttpRouteBuilderImpl = class _HttpRouteBuilderImpl {
       method,
       path: routePath,
       isPublic,
-      handler: wrappedHandler,
+      handler: invokeRoute,
       middlewares: [...this.middlewares],
       inputValidationIndex: this.inputValidationIndex,
       outputValidationIndex: this.outputValidationIndex,
@@ -341,90 +446,6 @@ function isWakeAppDeferredResult(result) {
   return !result.ok && (result.status === "capacity_rejected" || result.status === "queue_timeout" || result.status === "convergence_pending");
 }
 
-// ../core/src/platform-capacity-profile.ts
-var PLATFORM_CAPACITY_PROFILE_ENV = "GENCOW_CAPACITY_PROFILE";
-var PLATFORM_CAPACITY_ENV_KEYS = [
-  PLATFORM_CAPACITY_PROFILE_ENV,
-  "MAX_CONCURRENT_RUNNING",
-  "MAX_CONCURRENT_WAKE",
-  "MAX_WAKE_QUEUE_MS",
-  "MIN_AVAILABLE_RAM_MB",
-  "WAKE_RETRY_AFTER_SEC",
-  "EVICTION_THRESHOLD_MB",
-  "GENCOW_SLEEP_TIMEOUT_MINUTES",
-  "GENCOW_SLEEP_MAX_PER_CYCLE",
-  "WARM_POOL_MIN_IDLE",
-  "WARM_POOL_MAX",
-  "DEPLOY_CANDIDATE_RESERVE",
-  "GENCOW_APP_PORT_RANGE",
-  "COWBOX_WARM_POOL_PORT_RANGE"
-];
-var PLATFORM_CAPACITY_PRESETS = Object.freeze({
-  prod: Object.freeze({
-    profile: "prod",
-    maxConcurrentRunning: 600,
-    maxConcurrentWake: 20,
-    maxWakeQueueMs: 5e3,
-    minAvailableRamMB: 8192,
-    evictionThresholdMB: 16384,
-    sleepTimeoutMinutes: 15,
-    sleepMaxPerCycle: 50,
-    warmPoolMinIdle: 10,
-    warmPoolMax: 650,
-    deployCandidateReserve: 40
-  }),
-  dev: Object.freeze({
-    profile: "dev",
-    maxConcurrentRunning: 60,
-    maxConcurrentWake: 5,
-    maxWakeQueueMs: 3e3,
-    minAvailableRamMB: 2048,
-    evictionThresholdMB: 4096,
-    sleepTimeoutMinutes: 10,
-    sleepMaxPerCycle: 20,
-    warmPoolMinIdle: 3,
-    warmPoolMax: 70,
-    deployCandidateReserve: 5
-  }),
-  local: Object.freeze({
-    profile: "local",
-    maxConcurrentRunning: null,
-    maxConcurrentWake: null,
-    maxWakeQueueMs: 5e3,
-    minAvailableRamMB: null,
-    evictionThresholdMB: null,
-    sleepTimeoutMinutes: 30,
-    sleepMaxPerCycle: 10,
-    warmPoolMinIdle: 3,
-    warmPoolMax: 10,
-    deployCandidateReserve: 0
-  })
-});
-function normalizeDomain(value) {
-  return (value || "").trim().toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-}
-function detectPlatformCapacityProfile(env = process.env) {
-  const explicit = env[PLATFORM_CAPACITY_PROFILE_ENV]?.trim().toLowerCase();
-  if (explicit) {
-    if (["prod", "production", "128gb"].includes(explicit)) return "prod";
-    if (["dev", "development", "16gb"].includes(explicit)) return "dev";
-    if (["local", "test", "disabled"].includes(explicit)) return "local";
-    throw new Error(`Invalid ${PLATFORM_CAPACITY_PROFILE_ENV}: ${explicit}. Expected prod, dev, or local.`);
-  }
-  const baseDomain = normalizeDomain(env.BASE_DOMAIN);
-  if (baseDomain === "gencow.dev") return "dev";
-  if (baseDomain === "gencow.app") return "prod";
-  const platformUrl = normalizeDomain(env.GENCOW_PLATFORM_URL);
-  if (platformUrl === "gencow.dev") return "dev";
-  if (platformUrl === "gencow.app") return "prod";
-  if (env.NODE_ENV === "production" && env.IS_PLATFORM === "true") return "prod";
-  return "local";
-}
-function resolvePlatformCapacityPreset(env = process.env) {
-  const profile = detectPlatformCapacityProfile(env);
-  return { ...PLATFORM_CAPACITY_PRESETS[profile] };
-}
-
 // ../core/src/grounded-answer-types.ts
 var DEFAULT_GROUNDING_BUDGET = {
   maxVerifyLoops: 2,
@@ -1668,7 +1689,9 @@ async function validateWithSchema(schema, value, options) {
     }
     throw new GencowValidationError("Validation failed");
   }
-  throw new Error("procedure.query / procedure.mutation / procedure.internal only supports Standard Schema v1 validators");
+  throw new Error(
+    "procedure.query / procedure.mutation / procedure.internal only supports Standard Schema v1 validators"
+  );
 }
 function composeMiddlewares(middlewares, handler, inputSchema, outputSchema, inputValidationIndex, outputValidationIndex) {
   return async (initialContext, initialInput) => {
@@ -1798,14 +1821,14 @@ var GencowProcedureBuilderImpl = class _GencowProcedureBuilderImpl {
     if (!this.procedureName) {
       throw new Error("Procedure name is required. Call .name(...) before .handler(...)");
     }
-    const run = composeMiddlewares(
+    const run = (context, input) => composeMiddlewares(
       this.middlewares,
       handler,
       this.inputSchema,
       this.outputSchema,
       this.inputValidationIndex,
       this.outputValidationIndex
-    );
+    )(context, input);
     return {
       kind: this.kind,
       name: this.procedureName,
@@ -6082,9 +6105,6 @@ export {
   GencowValidationError,
   JobAdmissionError,
   MAX_FILE_SIZE,
-  PLATFORM_CAPACITY_ENV_KEYS,
-  PLATFORM_CAPACITY_PRESETS,
-  PLATFORM_CAPACITY_PROFILE_ENV,
   RLS_SESSION_KEY_RE,
   RealtimeChannelEventValidationError,
   STORAGE_LIST_DEFAULT_LIMIT,
@@ -6144,10 +6164,11 @@ export {
   defineRealtimeSubscriptions,
   deriveWorkflowStatus,
   deserializeWorkflowValue,
-  detectPlatformCapacityProfile,
   eqRlsContextColumn,
   filterTenantRuntimeEnvVars,
   formatBytes,
+  getHttpRouteDiscardedResponse,
+  getHttpRouteDiscardedResponseCause,
   getJobAdmissionStatus,
   getMinuteBucketStart,
   getMsUntilNextMinute,
@@ -6167,6 +6188,7 @@ export {
   hasMapSessionToContext,
   inferTableNameFromColumn,
   isCronJobsBuilder,
+  isHttpRouteOutputValidationFailure,
   isJobAdmissionError,
   isJobAdmissionKillSwitchActive,
   isReservedTenantRuntimeEnvKey,
@@ -6195,7 +6217,6 @@ export {
   resetRealtimeChannelRegistryForTests,
   resetRealtimeSubscriptionRegistryForTests,
   resolveExplicitRealtimeChannelKey,
-  resolvePlatformCapacityPreset,
   resolveRealtimeChannelKey,
   resolveRealtimeQueryScopeHash,
   resolveRealtimeQuerySubscriptionKey,

package/docs/packaging.md

@@ -40,11 +40,15 @@ CLI workspace source tree.
 Build from a complete repository checkout; workspace dependencies are required:
 
 ```sh
-pnpm --dir packages/cli run build
+pnpm --dir packages/cli run build:with-deps
 ```
 
-The build script runs the prerequisite workspace builds declared in the CLI
-package scripts, then produces the package runtime artifacts. After the build,
+`build:with-deps` builds the CLI's workspace dependencies (`@gencow/server`,
+`@gencow/internal`, `@gencow/core`, and the rest of the CLI closure) once each in
+topological order, then produces the package runtime artifacts. It selects packages
+with the path selector `{.}...` rather than the name `gencow...`, because the root
+package is also named `gencow` and a name selector would build the whole workspace. The plain `build`
+script does not build dependencies; it expects their `dist/` output to exist. After the build,
 from `packages/cli`, create a local tarball without running package lifecycle
 hooks, inspect its file list, and run the package integrity check:
 

package/docs/troubleshooting.md

@@ -40,7 +40,7 @@ other work before handling arguments.
   selected client target. Use the command reference for documented output options;
   do not use subcommand `--help` as a syntax probe.
 - If the CLI package build reports a missing or incompatible artifact, rebuild
-  from the repository root with `pnpm --dir packages/cli run build`, then rerun
+  from the repository root with `pnpm --dir packages/cli run build:with-deps`, then rerun
   `node scripts/pre-publish-check.mjs` from `packages/cli`.
 - For dependency resolution problems, run `pnpm install` at the workspace root
   and use the package manager declared by the project lockfile.

package/lib/app-command.mjs

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { resolve } from "path";
+import { basename, resolve } from "path";
 import {
   fetchAppDiagnosticLogsViaRpc,
   formatAppDiagnosticLogBlock,
@@ -22,6 +22,7 @@ import { resolveProjectMetadataPath, resolveProjectSelection } from "./project-c
 import { updateEnvLocalUrl } from "./cli-project-runtime.mjs";
 
 const DEFAULT_APP_CREATE_TIMEOUT_MS = 60_000;
+const SAFE_CLI_OPTION_PATTERN = /^--?[A-Za-z][A-Za-z0-9-]{0,40}$/u;
 
 function resolveAppCreateTimeoutMs(value) {
   const parsed = Number(value);
@@ -38,6 +39,11 @@ function invalidAppResponse(operation, response, kind) {
   return `CLI_APP_RESPONSE_INVALID: ${operation} returned an invalid ${kind} response (${appResponseStatus(response)})`;
 }
 
+function isTerminalAppDeleteResponse(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return false;
+  return body.retryable === false || body.retryClass === "terminal-client";
+}
+
 export function formatAppDeployedAgo(dateStr, now = Date.now()) {
   if (!dateStr) return `${DIM}never${RESET}`;
   const diff = now - new Date(dateStr).getTime();
@@ -88,6 +94,32 @@ function formatPendingReasonLines(appRow) {
   };
 }
 
+// A legacy-owner wake failure keeps the incumbent serving state and carries platform-authored guidance
+// (retry condition, exact command). Render it instead of the generic "no deployment" text, which is wrong
+// for an app that already has a legacy deployment.
+function formatLegacyRedeployDetails(appRow) {
+  const pending = formatPendingReasonLines(appRow);
+  if (!pending || appRow?.runtimeRecoveryReason !== "legacy_runtime_preparation_required") return null;
+  const correlationId = appRow?.runtimeRecoveryCorrelationId;
+  return [
+    "  Recovery: the app runtime is a legacy build the Platform cannot re-verify; the incumbent serving state was preserved.",
+    "  Data/Deployment: unchanged; no data or serving state was changed.",
+    `  Code: ${appRow?.runtimeRecoveryErrorCode || "RUNTIME_CONVERGENCE_LEGACY_REDEPLOY_REQUIRED"}`,
+    pending.reason,
+    ...(correlationId ? [`  Correlation: ${correlationId}`] : []),
+    pending.retryable,
+    pending.next,
+  ].join("\n");
+}
+
+// Platform marks an idle legacy-owner app (no wake failure recorded yet) with disposition.legacyRuntimeOwner.
+const LEGACY_OWNER_REDEPLOY_DETAILS = [
+  "  Recovery: the app runtime is a legacy build the Platform cannot re-verify; the incumbent serving state was preserved.",
+  "  Data/Deployment: unchanged; no data or serving state was changed.",
+  "  Retryable: no; deploy a new revision to move the app to the supported runtime.",
+  "  Next command: gencow deploy --prod",
+].join("\n");
+
 export function formatRecoveryDispositionDetails(appRow) {
   // The accepted delete receipt remains the lifecycle authority while the app
   // is being removed. Do not replace it with unrelated recovery or support
@@ -95,7 +127,11 @@ export function formatRecoveryDispositionDetails(appRow) {
   if (appRow?.status === "deleting") return "";
   const disposition = appRow?.recoveryDisposition;
   if (disposition?.kind === "deploy_required") {
-    return "  Recovery: no deployment is available. Run `gencow deploy` from this project.\n  Retryable: no";
+    return (
+      formatLegacyRedeployDetails(appRow) ??
+      (disposition.legacyRuntimeOwner === true ? LEGACY_OWNER_REDEPLOY_DETAILS : null) ??
+      "  Recovery: no deployment is available. Run `gencow deploy` from this project.\n  Retryable: no"
+    );
   }
   if (disposition?.kind === "owner_memory_action_required") {
     return "  Recovery: inspect logs and memory usage, then deploy a fix or explicitly Resume.\n  Retryable: no automatic retry";
@@ -286,9 +322,17 @@ export function createAppCommand({
     }
 
     if (subcmd === "create") {
-      const name = rest[0];
+      const unsupportedOption = rest.find((value) => value.startsWith("-"));
+      const name = rest.find((value) => !value.startsWith("-"));
+      if (unsupportedOption !== undefined) {
+        const optionLabel = SAFE_CLI_OPTION_PATTERN.test(unsupportedOption) ? `${unsupportedOption} ` : "";
+        errorImpl(
+          `Unknown option for app create: ${optionLabel}is not supported. The app name is the only argument.\nCode: APP_CREATE_USAGE_INVALID\nUsage: gencow app create <name>`,
+        );
+        return 1;
+      }
       if (!name) {
-        errorImpl("Usage: gencow app create <name>");
+        errorImpl("Usage: gencow app create <name>\nCode: APP_CREATE_USAGE_INVALID");
         return 1;
       }
 
@@ -354,13 +398,15 @@ export function createAppCommand({
         successImpl(`${config.rootDir}/index.ts — created (starter)`);
       }
 
-      const configPath = projectSelection.configPath ?? resolve(projectDir, "gencow.config.ts");
-      if (existsSync(configPath)) {
+      // The same resolved config file is used for the write and for the message, so the
+      // reported name always matches the file that was actually changed.
+      const configPath = projectSelection.configPath ?? null;
+      if (configPath && existsSync(configPath)) {
         const src = readFileSync(configPath, "utf8");
         const nextSrc = addDeployAppToConfigSource(src, appId);
         if (nextSrc !== src) {
           writeFileSync(configPath, nextSrc);
-          successImpl(`gencow.config.ts — added deploy.app = "${appId}"`);
+          successImpl(`${basename(configPath)} — added deploy.app = "${appId}"`);
         }
       }
 
@@ -370,8 +416,11 @@ export function createAppCommand({
   ${GREEN}▸${RESET} App ID:    ${appId}
   ${GREEN}▸${RESET} API:       ${appUrl}
 ${dashboardLine}
-  ${GREEN}▸${RESET} .env: VITE_API_URL set
-
+  ${GREEN}▸${RESET} .env: VITE_API_URL set (dev app)
+  ${GREEN}▸${RESET} Prod app: not created yet. Your first ${GREEN}gencow deploy --prod${RESET} creates it.
+`);
+      logImpl(`
+  ${DIM}gencow deploy --prod   — create the prod app and deploy to it${RESET}
   ${DIM}pnpm gencow dev   — watch & auto-deploy to cloud + live logs${RESET}
 `);
       return 0;
@@ -418,6 +467,12 @@ ${dashboardLine}
             delRes,
             { expectedAppId: name },
           );
+        // A typed terminal failure (for example APP_NOT_FOUND) is not retryable, whatever its HTTP
+        // status. Telling the user to replay the same request contradicts the server classification.
+        if (isTerminalAppDeleteResponse(delData)) {
+          errorImpl(`${diagnosis}\nNext command: gencow app list`);
+          return 1;
+        }
         errorImpl(delRes.ok || delRes.status >= 500
           ? `${diagnosis}\nRequest ID: ${requestId}. Retry the same request: ${retryCommand}`
           : diagnosis);

package/lib/backup-command.mjs

@@ -3,6 +3,7 @@ import { resolve } from "path";
 import { BOLD, CYAN, DIM, GREEN, RED, RESET, YELLOW, error, info, log, success } from "./output.mjs";
 import { platformFetch, requireCreds, rpcMutation, rpcQuery } from "./platform-client.mjs";
 import { readProjectMetadata } from "./project-context.mjs";
+import { formatRestoreFailure } from "./backup-restore-diagnostic.mjs";
 
 export function resolveBackupAppId(restArgs, gencowJson = null) {
   let appId = null;
@@ -85,6 +86,92 @@ export function parseBackupListOptions(restArgs) {
   return options;
 }
 
+// Public codes this renderer knows. Legacy BACKUP_CAPABILITY_NOT_READY rows are handled separately.
+const BACKUP_TYPED_CODES = new Set([
+  "BACKUP_ACCESS_RECONCILING",
+  "BACKUP_RLS_RESTRICTIVE_POLICY",
+  "BACKUP_RLS_SCOPE_UNAVAILABLE",
+  "BACKUP_CAPABILITY_ATTESTATION_INVALID",
+]);
+
+const BACKUP_PLATFORM_WAIT =
+  "No action is needed from you. Retry only after the backup access check reports ready; do not retry in a loop before then.";
+
+// One entry per preflight reason the platform can store. A reason missing here is dropped from the rendered
+// list, so it cannot reach the terminal under an unexplained code. Stored prose is never printed.
+const BACKUP_REASON_PRESENTATION = {
+  attestation_metadata_invalid: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  role_attestation_missing: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  backup_identity_mismatch: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  role_has_broad_cluster_privilege: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  rls_bypass_not_approved: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  relation_select_missing: { owner: "platform", nextAction: `Platform is restoring backup access. ${BACKUP_PLATFORM_WAIT}` },
+  relation_ownership_forbidden: { owner: "platform", nextAction: `Platform is restoring backup access. ${BACKUP_PLATFORM_WAIT}` },
+  sequence_defaults_mutation_forbidden: { owner: "platform", nextAction: `Platform is restoring backup access. ${BACKUP_PLATFORM_WAIT}` },
+  complete_rls_dump_not_proven: { owner: "platform", nextAction: `Platform is restoring backup access. ${BACKUP_PLATFORM_WAIT}` },
+  rls_restrictive_policy_applies: {
+    owner: "app",
+    nextAction:
+      "Add a new migration that limits the restrictive RLS policy so it no longer applies to the Gencow backup reader (do not edit applied migrations), run `gencow deploy` from your app workspace, then retry the backup.",
+  },
+  rls_dump_scope_unbound: { owner: "platform", nextAction: `Platform must bind the backup scope for this app. ${BACKUP_PLATFORM_WAIT}` },
+  rls_scope_changed: {
+    owner: "platform",
+    nextAction:
+      "This is a transient race. A single retry after the current backup attempt finishes is expected to succeed. If it fails again, Platform is restoring access; do not retry in a loop, and cite the Reference below.",
+  },
+};
+
+// Stored shape written by the platform: "CODE[ [reasons=a,b]]: prose". Only the code and reason tokens are read.
+const BACKUP_DIAGNOSIS_PATTERN = /^(BACKUP_[A-Z_]+)(?: \[reasons=([a-z_,]+)\])?: /u;
+
+function parseBackupDiagnosis(backup) {
+  if (backup.status !== "failed" || typeof backup.errorMessage !== "string") return null;
+  const match = BACKUP_DIAGNOSIS_PATTERN.exec(backup.errorMessage);
+  if (!match) return null;
+  const code = match[1];
+  // Legacy rows stored before the typed codes existed keep their original fixed rendering.
+  if (code === "BACKUP_CAPABILITY_NOT_READY") return { code, legacy: true };
+  if (!BACKUP_TYPED_CODES.has(code)) return null;
+  const reasons = [
+    ...new Set(
+      (match[2] ?? "")
+        .split(",")
+        .filter((token) => Object.prototype.hasOwnProperty.call(BACKUP_REASON_PRESENTATION, token)),
+    ),
+  ];
+  return reasons.length > 0 ? { code, reasons } : null;
+}
+
+function renderBackupDiagnosis(diagnosis, backupId) {
+  if (diagnosis.legacy) {
+    return [
+      "    BACKUP_CAPABILITY_NOT_READY: Backup preflight is not ready. The dump did not start; no data or serving state changed. Retry only after Platform confirms complete backup visibility and protected snapshot and authorization readiness for this app. Check the failed backup with `gencow backup list` from its app workspace.",
+    ];
+  }
+  const presentations = diagnosis.reasons.map((reason) => ({ reason, ...BACKUP_REASON_PRESENTATION[reason] }));
+  const appSteps = [...new Set(presentations.filter((p) => p.owner === "app").map((p) => p.nextAction))];
+  const platformReasons = presentations.filter((p) => p.owner === "platform").map((p) => p.reason);
+  const platformSteps = [...new Set(presentations.filter((p) => p.owner === "platform").map((p) => p.nextAction))];
+  const owners = [appSteps.length > 0 ? "App" : null, platformSteps.length > 0 ? "Platform" : null].filter(Boolean);
+  const lines = [
+    `    ${diagnosis.code}`,
+    `    Stage: preflight | State: unchanged (no data or serving state changed) | Owner: ${owners.join(" and ")}`,
+    `    Reasons: ${diagnosis.reasons.join(", ")}`,
+  ];
+  if (appSteps.length > 0 && platformSteps.length > 0) {
+    // Mixed refusal: the user acts on the app part only, and the Platform part is named as already in progress.
+    lines.push(`    Next (you): ${appSteps.join(" ")}`);
+    lines.push(
+      `    Platform part: Platform is restoring the Platform-owned reasons (${platformReasons.join(", ")}); no action is needed from you for them. ${platformSteps.join(" ")}`,
+    );
+  } else {
+    lines.push(`    Next: ${[...appSteps, ...platformSteps].join(" ")}`);
+  }
+  lines.push(`    Reference: backup #${backupId}`);
+  return lines;
+}
+
 function renderBackupHelp(logImpl = log, errorImpl = error, subCmd = null) {
   if (subCmd) errorImpl(`Unknown sub-command: ${subCmd}`);
   logImpl(`\n  ${BOLD}Usage:${RESET}`);
@@ -98,6 +185,10 @@ function renderBackupHelp(logImpl = log, errorImpl = error, subCmd = null) {
   logImpl(`    gencow backup download <id>       Download backup file (plan-dependent)\n`);
 }
 
+async function readErrorBody(response) {
+  return (await response.json?.().catch(() => ({}))) ?? {};
+}
+
 export function buildRestoreConfirmPrompt(sourceLabel, { includeStorageRisk = false } = {}) {
   const storageRisk = includeStorageRisk
     ? `\n  ${YELLOW}⚠ 백업 파일 복원은 DB만 교체하며 storage object/blob는 함께 이동하지 않습니다.${RESET}` +
@@ -201,16 +292,11 @@ export function createBackupCommand({
             logImpl(
               `  ${DIM}#${backup.id}${RESET}  ${statusColor}${backup.status.padEnd(10)}${RESET}  ${backup.type.padEnd(11)} ${formatBackupRetentionClass(backup).padEnd(14)} ${formatBackupSize(backup.fileSize).padStart(10)}  ${formatBackupDate(backup.createdAt)}  ${DIM}expires ${formatBackupExpiry(backup.expiresAt)}${RESET}${backup.note ? `  ${DIM}${backup.note}${RESET}` : ""}`,
             );
-            // Recognize the stable producer code, but never print legacy/raw
-            // errorMessage contents (which may contain SQL or credentials).
-            if (
-              backup.status === "failed" &&
-              typeof backup.errorMessage === "string" &&
-              backup.errorMessage.startsWith("BACKUP_CAPABILITY_NOT_READY:")
-            ) {
-              logImpl(
-                "    BACKUP_CAPABILITY_NOT_READY: Backup preflight is not ready. The dump did not start; no data or serving state changed. Retry only after Platform confirms complete backup visibility and protected snapshot and authorization readiness for this app. Check the failed backup with `gencow backup list` from its app workspace.",
-              );
+            // Recognize the stable producer code, but never print raw errorMessage contents
+            // (which may contain SQL or credentials).
+            const diagnosis = parseBackupDiagnosis(backup);
+            if (diagnosis) {
+              for (const line of renderBackupDiagnosis(diagnosis, backup.id)) logImpl(line);
             }
           }
         }
@@ -267,9 +353,7 @@ export function createBackupCommand({
         logImpl(`\n${BOLD}Restoring from backup #${backupId}...${RESET}\n`);
         const response = await rpcMutationImpl(creds, "backup.restore", { appName: appId, backupId });
         if (!response.ok) {
-          errorImpl(
-            `Restore failed: ${(await response.json().catch(() => ({}))).error || response.statusText}`,
-          );
+          errorImpl(formatRestoreFailure(await readErrorBody(response), response.statusText));
           return;
         }
         successImpl("Database restored. App restarted.");
@@ -306,9 +390,7 @@ export function createBackupCommand({
           body: form,
         });
         if (!response.ok) {
-          errorImpl(
-            `Restore failed: ${(await response.json?.().catch(() => ({}))).error || response.statusText}`,
-          );
+          errorImpl(formatRestoreFailure(await readErrorBody(response), response.statusText));
           return;
         }
         successImpl("Database restored from file. App restarted.");