gencow 0.1.236 → 0.1.238

package/lib/app-command.mjs

@@ -362,6 +362,7 @@ ${dashboardLine}
             delData,
             invalidAppResponse("app delete", delRes, delRes.ok ? "success" : "error"),
             delRes,
+            { expectedAppId: name },
           ),
         );
         return 1;

package/lib/app-delete-diagnostic.mjs

@@ -0,0 +1,103 @@
+export const APP_DELETE_OPERATION_PATTERN =
+  /^app_delete_(?:[a-f0-9]{32}|[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12})$/u;
+
+const APP_ID_PATTERN = /^(?=.{3,63}$)[a-z][a-z0-9]*(?:-[a-z0-9]+){2,7}$/u;
+const CORRELATION_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/u;
+
+export function isAppDeleteDiagnosticAppId(value) {
+  return APP_ID_PATTERN.test(value ?? "");
+}
+
+export function isAllowedAppDeleteStatusPath(value, operationId, expectedAppId) {
+  if (value === undefined) return true;
+  if (typeof value !== "string" || value.length > 256 || value.includes("?") || value.includes("#")) {
+    return false;
+  }
+  const match = /^\/api\/apps\/([^/]+)\/delete\/([^/]+)$/u.exec(value);
+  if (!match) return false;
+  try {
+    const appId = decodeURIComponent(match[1]);
+    return (
+      APP_ID_PATTERN.test(appId) &&
+      (!expectedAppId || appId === expectedAppId) &&
+      decodeURIComponent(match[2]) === operationId
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isCanonicalTimestamp(value) {
+  if (typeof value !== "string" || value.length > 64) return false;
+  const date = new Date(value);
+  return Number.isFinite(date.getTime()) && date.toISOString() === value;
+}
+
+// The Platform's blocked receipt is an untrusted transport value until all of
+// its identity, app scope, and safe-action fields agree. Keep that boundary in
+// one module so polling and terminal rendering cannot drift apart.
+export function readBlockedAppDeleteDiagnostic(value, expectedAppId) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (
+    value.success !== false ||
+    value.deleted !== expectedAppId ||
+    !isAppDeleteDiagnosticAppId(expectedAppId) ||
+    !APP_DELETE_OPERATION_PATTERN.test(value.operationId ?? "") ||
+    !CORRELATION_ID_PATTERN.test(value.correlationId ?? "") ||
+    value.state !== "blocked_active_work" ||
+    value.code !== "PLATFORM_ACTION_REQUIRED" ||
+    value.failureClass !== "PLATFORM_ACTION_REQUIRED" ||
+    value.action !== "VIEW_DELETE_STATUS" ||
+    typeof value.statusPath !== "string" ||
+    !isAllowedAppDeleteStatusPath(value.statusPath, value.operationId, expectedAppId) ||
+    !isCanonicalTimestamp(value.nextReconcileAt)
+  ) {
+    return null;
+  }
+  return {
+    code: value.code,
+    operationId: value.operationId,
+    correlationId: value.correlationId,
+    state: value.state,
+    nextReconcileAt: value.nextReconcileAt,
+    statusCommand: `gencow app status ${expectedAppId}`,
+  };
+}
+
+export function isBlockedAppDeleteDiagnosticCandidate(value) {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      (value.code === "PLATFORM_ACTION_REQUIRED" ||
+        value.failureClass === "PLATFORM_ACTION_REQUIRED" ||
+        value.action === "VIEW_DELETE_STATUS"),
+  );
+}
+
+export function formatBlockedAppDeleteDiagnosticLines(diagnostic) {
+  return [
+    "App deletion is blocked while Gencow reconciles the existing delete operation.",
+    `Code: ${diagnostic.code}`,
+    `Operation ID: ${diagnostic.operationId}`,
+    `Correlation ID: ${diagnostic.correlationId}`,
+    `State: ${diagnostic.state}`,
+    "State impact: deletion is not complete; current serving state is preserved.",
+    `Next reconciliation: ${diagnostic.nextReconcileAt}`,
+    "Retry class: platform-action",
+    "Next action: VIEW_DELETE_STATUS",
+    `Next command: ${diagnostic.statusCommand}`,
+  ];
+}
+
+export function formatInvalidBlockedAppDeleteDiagnosticLines(value, expectedAppId) {
+  const lines = ["App deletion status could not be verified safely. Check the app status before retrying."];
+  if (/^[A-Za-z][A-Za-z0-9_]{2,127}$/u.test(value.code ?? "")) lines.push(`Code: ${value.code}`);
+  if (APP_DELETE_OPERATION_PATTERN.test(value.operationId ?? "")) {
+    lines.push(`Operation ID: ${value.operationId}`);
+  }
+  if (CORRELATION_ID_PATTERN.test(value.correlationId ?? "")) {
+    lines.push(`Correlation ID: ${value.correlationId}`);
+  }
+  return lines;
+}

package/lib/app-delete-operation.mjs

@@ -1,5 +1,9 @@
 import { isExactAppDeleteResponse } from "./app-response-contract.mjs";
-import { APP_DELETE_OPERATION_PATTERN } from "./app-response-error.mjs";
+import {
+  APP_DELETE_OPERATION_PATTERN,
+  isAllowedAppDeleteStatusPath,
+  readBlockedAppDeleteDiagnostic,
+} from "./app-delete-diagnostic.mjs";
 import { readJsonObjectResponse } from "./http-response-json.mjs";
 
 const APP_DELETE_ACTIVE_STATES = new Set([
@@ -25,27 +29,6 @@ const APP_DELETE_RESPONSE_STATES = new Set([
 ]);
 const CORRELATION_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/u;
 const DIAGNOSTIC_CODE_PATTERN = /^[A-Za-z][A-Za-z0-9_]{2,127}$/u;
-const APP_ID_PATTERN = /^(?=.{3,63}$)[a-z][a-z0-9]*(?:-[a-z0-9]+){2,7}$/u;
-
-function isAllowedStatusPath(value, operationId, expectedAppId) {
-  if (value === undefined) return true;
-  if (typeof value !== "string" || value.length > 256 || value.includes("?") || value.includes("#")) {
-    return false;
-  }
-  const match = /^\/api\/apps\/([^/]+)\/delete\/([^/]+)$/u.exec(value);
-  if (!match) return false;
-  try {
-    const appId = decodeURIComponent(match[1]);
-    return (
-      APP_ID_PATTERN.test(appId) &&
-      (!expectedAppId || appId === expectedAppId) &&
-      decodeURIComponent(match[2]) === operationId
-    );
-  } catch {
-    return false;
-  }
-}
-
 export function parseAppDeleteOperationEnvelope(value, expectedAppId) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   if (value.success !== undefined && value.success !== false) return null;
@@ -55,7 +38,7 @@ export function parseAppDeleteOperationEnvelope(value, expectedAppId) {
     !CORRELATION_ID_PATTERN.test(value.correlationId ?? "") ||
     (value.deleted !== undefined && value.deleted !== expectedAppId) ||
     (value.code !== undefined && !DIAGNOSTIC_CODE_PATTERN.test(value.code)) ||
-    !isAllowedStatusPath(value.statusPath, value.operationId, expectedAppId)
+    !isAllowedAppDeleteStatusPath(value.statusPath, value.operationId, expectedAppId)
   ) {
     return null;
   }
@@ -89,6 +72,7 @@ function isMatchingTerminalResponse(value, accepted, expectedAppId) {
 }
 
 function isMatchingTerminalFailureResponse(value, accepted, expectedAppId) {
+  const blockedDiagnostic = readBlockedAppDeleteDiagnostic(value, expectedAppId);
   return (
     value &&
     typeof value === "object" &&
@@ -98,7 +82,9 @@ function isMatchingTerminalFailureResponse(value, accepted, expectedAppId) {
     value.operationId === accepted.operationId &&
     value.correlationId === accepted.correlationId &&
     (APP_DELETE_TERMINAL_FAILURE_STATES.has(value.state) ||
-      (value.state === "blocked_active_work" && value.code === "PLATFORM_ACTION_REQUIRED")) &&
+      (blockedDiagnostic &&
+        blockedDiagnostic.operationId === accepted.operationId &&
+        blockedDiagnostic.correlationId === accepted.correlationId)) &&
     DIAGNOSTIC_CODE_PATTERN.test(value.code ?? "")
   );
 }

package/lib/app-response-error.mjs

@@ -1,5 +1,14 @@
-export const APP_DELETE_OPERATION_PATTERN =
-  /^app_delete_(?:[a-f0-9]{32}|[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12})$/u;
+import { formatLatestCliInvocation } from "./cli-update-guidance.mjs";
+
+import {
+  APP_DELETE_OPERATION_PATTERN,
+  formatBlockedAppDeleteDiagnosticLines,
+  formatInvalidBlockedAppDeleteDiagnosticLines,
+  isBlockedAppDeleteDiagnosticCandidate,
+  readBlockedAppDeleteDiagnostic,
+} from "./app-delete-diagnostic.mjs";
+
+export { APP_DELETE_OPERATION_PATTERN } from "./app-delete-diagnostic.mjs";
 
 const RETRY_CLASSES = new Set(["operator-action", "platform-action", "retryable-infra", "terminal-client"]);
 const USER_ACTIONS = new Set([
@@ -8,19 +17,27 @@ const USER_ACTIONS = new Set([
   "INSPECT_STATE",
   "OPERATOR_ACTION",
   "RETRY",
+  "UPDATE_CLI",
   "UPGRADE_CLI",
   "VIEW_DELETE_STATUS",
   "VIEW_STATUS",
   "WAIT",
 ]);
 
-export function appResponseError(body, fallback, response = null) {
+export function appResponseError(body, fallback, response = null, options = {}) {
   if (!body || typeof body !== "object" || Array.isArray(body)) {
     if (response?.status === 503) {
       return `${fallback}\nCode: CLI_PLATFORM_UNAVAILABLE\nRetryable: yes`;
     }
     return fallback;
   }
+  const blockedDeleteDiagnostic = readBlockedAppDeleteDiagnostic(body, options.expectedAppId);
+  if (blockedDeleteDiagnostic) {
+    return formatBlockedAppDeleteDiagnosticLines(blockedDeleteDiagnostic).join("\n");
+  }
+  if (isBlockedAppDeleteDiagnosticCandidate(body)) {
+    return formatInvalidBlockedAppDeleteDiagnosticLines(body, options.expectedAppId).join("\n");
+  }
   const hasPublicCode = /^[A-Za-z][A-Za-z0-9_]{2,127}$/u.test(body.code ?? "");
   // A syntactically valid code does not authenticate the accompanying message.
   // 503 bodies can be partial upstream envelopes, so never cross that public
@@ -54,7 +71,11 @@ export function appResponseError(body, fallback, response = null) {
   if (RETRY_CLASSES.has(body.retryClass) && USER_ACTIONS.has(body.userAction)) {
     const legacySupportAction = body.userAction === "CONTACT_SUPPORT";
     lines.push(`Retry class: ${legacySupportAction ? "platform-action" : body.retryClass}`);
-    lines.push(`Next action: ${legacySupportAction ? "INSPECT_STATE" : body.userAction}`);
+    if (body.userAction === "UPDATE_CLI" || body.userAction === "UPGRADE_CLI") {
+      lines.push(`Next command: ${formatLatestCliInvocation()}`);
+    } else {
+      lines.push(`Next action: ${legacySupportAction ? "INSPECT_STATE" : body.userAction}`);
+    }
     if (Number.isSafeInteger(body.retryAfterMs) && body.retryAfterMs >= 0 && body.retryAfterMs <= 600_000) {
       lines.push(`Retry after: ${body.retryAfterMs}ms`);
     }

package/lib/cli-command-runner.mjs

@@ -6,6 +6,27 @@ const SAFE_PLATFORM_ERROR_DETAILS = new Map([
   ["APP_RELEASE_CAPABILITY_UNAVAILABLE", "Release capability is temporarily unavailable."],
   ["APP_RELEASE_POLICY_READ_UNAVAILABLE", "Release policy is temporarily unavailable."],
 ]);
+const SAFE_LOCAL_ERROR_CODES = new Map([
+  [
+    "DEPLOY_SCHEMA_SOURCE_MISSING",
+    {
+      message: "Deploy stopped before upload: configured schema source is missing.",
+      stage: "schema",
+      action: "Retryable: no — fix gencow.config.js and rerun deploy.",
+    },
+  ],
+  [
+    "DEPLOY_CAPABILITY_CONFLICT",
+    {
+      message:
+        "Deploy stopped before upload: the empty schema declaration conflicts with an Auth schema source.",
+      stage: "schema",
+      action:
+        "Retryable: no — remove the unused Auth schema or declare the schema it requires, then rerun deploy.",
+      pathLabel: "Conflicting source",
+    },
+  ],
+]);
 
 function safePlatformOrigin(value) {
   try {
@@ -17,6 +38,33 @@ function safePlatformOrigin(value) {
 }
 
 function commandErrorMessage(caught) {
+  const localDiagnostic = SAFE_LOCAL_ERROR_CODES.get(caught?.code);
+  if (localDiagnostic) {
+    const lines = [
+      localDiagnostic.message,
+      `Code: ${caught.code}`,
+      `Stage: ${localDiagnostic.stage}`,
+      "Database mutation: NONE",
+      "Incumbent serving: PRESERVED",
+      localDiagnostic.action,
+    ];
+    const diagnosticPaths = Array.isArray(caught.missingPaths)
+      ? caught.missingPaths
+      : Array.isArray(caught.conflictingPaths)
+        ? caught.conflictingPaths
+        : [];
+    const safePaths = diagnosticPaths.filter(
+      (path) =>
+        typeof path === "string" &&
+        path.length <= 240 &&
+        path.startsWith("gencow/") &&
+        !path.includes("..") &&
+        !/[\u0000-\u001f\u007f]/u.test(path),
+    );
+    const pathLabel = localDiagnostic.pathLabel ?? "Missing source";
+    for (const path of safePaths.slice(0, 8)) lines.push(`${pathLabel}: ${path}`);
+    return lines.join("\n");
+  }
   if (caught instanceof Error && (caught.message === "APP_RELEASE_AUTH_REQUIRED" || caught.status === 401)) {
     const lines = ["Login expired or invalid for this Platform."];
     const platformOrigin = safePlatformOrigin(caught.platformUrl);

package/lib/cli-project-runtime.mjs

@@ -59,13 +59,13 @@ function parseTsConfigViaRegex(src) {
     const match = src.match(new RegExp(`${key}:\\s*\\[([\\s\\S]*?)\\]`));
     if (!match) return null;
     const values = [];
-    const entryRegex = /["'`]([^"'`]+)["'`]/g;
+    const entryRegex = /["'`]([^"'`]*)["'`]/g;
     let entry = entryRegex.exec(match[1]);
     while (entry) {
       values.push(entry[1]);
       entry = entryRegex.exec(match[1]);
     }
-    return values.length > 0 ? values : null;
+    return values;
   };
   const extractTopLevelStringArray = (key) => {
     let depth = 0;
@@ -182,7 +182,8 @@ function parseTsConfigViaRegex(src) {
   if (functionsDir !== null) result.functionsDir = functionsDir;
   const envFile = extract("envFile");
   if (envFile !== null) result.envFile = envFile;
-  const schema = extractStringArray("schema") ?? extract("schema");
+  const schemaStringMatch = src.match(/\bschema:\s*["'`]([^"'`]*)["'`]/u);
+  const schema = extractStringArray("schema") ?? schemaStringMatch?.[1] ?? extract("schema");
   if (schema !== null) result.schema = schema;
   const storage = extract("storage");
   if (storage !== null) result.storage = storage;
@@ -281,6 +282,17 @@ async function loadConfigModule() {
   return configModulePromise;
 }
 
+function markConfigSource(config, { schemaDeclared }) {
+  if (!config || typeof config !== "object") return config;
+  Object.defineProperty(config, "__gencowConfigMetadata", {
+    configurable: false,
+    enumerable: false,
+    value: Object.freeze({ schemaDeclared }),
+    writable: false,
+  });
+  return config;
+}
+
 export function resolveConfiguredAuditorImplementation(config = {}) {
   return resolveConfiguredAuditorImplementationShared(config);
 }
@@ -340,12 +352,12 @@ export async function loadConfig(options = {}) {
       throw caught;
     }
     warnImpl(`${caught.message} — using defaults`);
-    return getDefaultConfig();
+    return markConfigSource(getDefaultConfig(), { schemaDeclared: false });
   }
 
   if (!path) {
     warnImpl("No gencow.config.js found — using defaults");
-    return getDefaultConfig();
+    return markConfigSource(getDefaultConfig(), { schemaDeclared: false });
   }
 
   // Per-process cache keyed by (path, mtimeMs). Same CLI invocation can call
@@ -375,7 +387,7 @@ export async function loadConfig(options = {}) {
       throw caught;
     }
     warnImpl(`${message} — using defaults`);
-    return getDefaultConfig();
+    return markConfigSource(getDefaultConfig(), { schemaDeclared: false });
   }
 
   let parsed;
@@ -402,9 +414,10 @@ export async function loadConfig(options = {}) {
       throw caught;
     }
     warnImpl(`${message} — using defaults`);
-    return getDefaultConfig();
+    return markConfigSource(getDefaultConfig(), { schemaDeclared: false });
   }
 
+  markConfigSource(parsed, { schemaDeclared: Object.hasOwn(raw ?? {}, "schema") });
   cache.set(path, { mtimeMs, parsed });
   return parsed;
 }

package/lib/cli-update-guidance.mjs

@@ -0,0 +1,7 @@
+const SAFE_CLI_COMMAND = /^[a-z][a-z0-9:-]{0,63}$/u;
+
+export function formatLatestCliInvocation(command) {
+  const safeCommand =
+    typeof command === "string" && SAFE_CLI_COMMAND.test(command) ? command : "<same command>";
+  return `bunx gencow@latest ${safeCommand}`;
+}

package/lib/cli-version-check.mjs

@@ -3,8 +3,11 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { dirname, resolve } from "path";
 
+import { formatLatestCliInvocation } from "./cli-update-guidance.mjs";
+
 const DEFAULT_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_NPM_TIMEOUT_MS = 1500;
+const RELEASE_SENSITIVE_COMMANDS = new Set(["db", "deploy", "dev", "dev:cloud", "static"]);
 
 function isEnabled(value) {
   return value === "1" || value === "true" || value === "yes";
@@ -37,6 +40,10 @@ export function shouldWarnForStaleCli({ currentVersion, latestVersion }) {
   return compareCliSemver(latestVersion, currentVersion) > 0;
 }
 
+export function shouldRepeatStaleCliWarning(command) {
+  return RELEASE_SENSITIVE_COMMANDS.has(command);
+}
+
 export function resolveVersionCheckCachePath({ homeDir = homedir(), processEnv = process.env } = {}) {
   return processEnv.GENCOW_VERSION_CHECK_CACHE || resolve(homeDir, ".gencow", "version-check.json");
 }
@@ -74,13 +81,16 @@ function fetchLatestVersion({ execFileSyncImpl = execFileSync, timeoutMs = DEFAU
 }
 
 export function formatStaleCliWarning({ currentVersion, latestVersion, command }) {
-  const suffix = command ? ` ${command}` : "";
-  return [
+  const lines = [
     `Gencow CLI is older than npm latest (current ${currentVersion}, latest ${latestVersion}).`,
-    `Use project-local/latest CLI for verification: bunx gencow@latest${suffix}`,
+    `Run: ${formatLatestCliInvocation(command)}`,
     "If this came from a global install, check: which gencow && gencow --version",
     "Skip this check with GENCOW_SKIP_VERSION_CHECK=true.",
-  ].join("\n");
+  ];
+  if (shouldRepeatStaleCliWarning(command)) {
+    lines.splice(1, 0, "This deployment or migration command may require the current CLI contract.");
+  }
+  return lines.join("\n");
 }
 
 export function maybeCheckCliVersion({
@@ -119,7 +129,9 @@ export function maybeCheckCliVersion({
       cache.checkedAt = now;
       writeCache(cachePath, cache, { mkdirSyncImpl, writeFileSyncImpl });
     } catch (caught) {
-      return { status: "unverified", error: caught };
+      if (!shouldWarnForStaleCli({ currentVersion, latestVersion })) {
+        return { status: "unverified", error: caught };
+      }
     }
   }
 
@@ -136,7 +148,7 @@ export function maybeCheckCliVersion({
 
   const warnedRecently =
     cache.warnedForVersion === latestVersion && isFresh(cache.warnedAt, now, cacheMaxAgeMs);
-  if (!warnedRecently) {
+  if (shouldRepeatStaleCliWarning(command) || !warnedRecently) {
     warnImpl(message);
     cache.warnedAt = now;
     cache.warnedForVersion = latestVersion;

package/lib/deploy-existing-bundle-candidate.mjs

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, mkdtempSync, rmSync, symlinkSync } from "fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync } from "fs";
 import { tmpdir } from "os";
 import { relative, resolve, sep } from "path";
 
@@ -17,6 +17,8 @@ export function createExistingBundleCandidate(
   {
     cpSyncImpl = cpSync,
     existsSyncImpl = existsSync,
+    mkdirSyncImpl = mkdirSync,
+    readdirSyncImpl = readdirSync,
     mkdtempSyncImpl = mkdtempSync,
     rmSyncImpl = rmSync,
     symlinkSyncImpl = symlinkSync,
@@ -32,7 +34,18 @@ export function createExistingBundleCandidate(
     });
     const sourceNodeModules = resolve(projectRoot, "node_modules");
     if (existsSyncImpl(sourceNodeModules)) {
-      symlinkSyncImpl(sourceNodeModules, resolve(candidateRoot, "node_modules"), "dir");
+      // Keep the dependency tree available to the CLI without exposing a
+      // top-level symlink to the release-source inventory. Older published
+      // CLIs correctly exclude a real node_modules directory but reject its
+      // symlink as an unsafe source entry.
+      const candidateNodeModules = resolve(candidateRoot, "node_modules");
+      mkdirSyncImpl(candidateNodeModules);
+      for (const entry of readdirSyncImpl(sourceNodeModules)) {
+        symlinkSyncImpl(
+          resolve(sourceNodeModules, entry),
+          resolve(candidateNodeModules, entry),
+        );
+      }
     }
   } catch (error) {
     rmSyncImpl(stagingParent, { recursive: true, force: true });

package/lib/deploy-failure-diagnostic.mjs

@@ -1,6 +1,7 @@
 import { MIGRATION_NEXT_ACTION_KINDS, MIGRATION_RETRY_POLICIES } from "@gencow/migration-contract";
 
 import { APP_DELETE_OPERATION_PATTERN } from "./app-response-error.mjs";
+import { formatLatestCliInvocation } from "./cli-update-guidance.mjs";
 import { formatDeployCorrelationId } from "./deploy-correlation-diagnostic.mjs";
 
 const DEPLOY_FAILURE_STAGES = new Set([
@@ -14,7 +15,12 @@ const DEPLOY_FAILURE_STAGES = new Set([
   "controller",
 ]);
 const RETRY_CLASSES = new Set(["terminal-client", "retryable-infra", "platform-action"]);
-const USER_ACTIONS = new Set([...MIGRATION_NEXT_ACTION_KINDS, "OPERATOR_ACTION", "VIEW_DELETE_STATUS"]);
+const USER_ACTIONS = new Set([
+  ...MIGRATION_NEXT_ACTION_KINDS,
+  "OPERATOR_ACTION",
+  "UPGRADE_CLI",
+  "VIEW_DELETE_STATUS",
+]);
 const STRUCTURED_CONTRACT_FIELDS = [
   "code",
   "stage",
@@ -166,6 +172,13 @@ function appendSelfServiceState(lines, selfService) {
   }
 }
 
+function isCliUpgradeContract(contract) {
+  return (
+    contract.code === "DEPLOY_CLI_UPGRADE_REQUIRED" &&
+    (contract.userAction === "UPDATE_CLI" || contract.userAction === "UPGRADE_CLI")
+  );
+}
+
 export function renderDeployFailureDiagnosticLines(responseBody, statusText, options = {}) {
   const contract = readDeployFailureContract(responseBody, options.expectedAppName);
   const fallbackMessage = safeText(statusText, 120) ?? "Request failed";
@@ -226,12 +239,21 @@ export function renderDeployFailureDiagnosticLines(responseBody, statusText, opt
   lines.push(`Code: ${contract.code}`, `Stage: ${contract.stage}`);
   const selfService = readSelfServiceDiagnostic(responseBody, contract);
   appendSelfServiceState(lines, selfService);
+  if (isCliUpgradeContract(contract) && !selfService) {
+    lines.push(
+      "Database mutation: NONE",
+      "Incumbent serving: PRESERVED",
+      "Retry policy: AFTER_FIX — Update the CLI before retrying.",
+    );
+  }
   const correlationLine = formatDeployCorrelationId(contract.correlationId);
   if (correlationLine) lines.push(correlationLine);
   lines.push(
-    selfService?.action.command
-      ? `Next command: ${selfService.action.command}`
-      : `Next action: ${contract.userAction}`,
+    isCliUpgradeContract(contract)
+      ? `Next command: ${formatLatestCliInvocation("deploy")}`
+      : selfService?.action.command
+        ? `Next command: ${selfService.action.command}`
+        : `Next action: ${contract.userAction}`,
   );
   return lines;
 }

package/lib/deploy-package-runtime.mjs

@@ -1,4 +1,5 @@
 import { execSync } from "child_process";
+import { randomUUID } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "fs";
 import { dirname, resolve } from "path";
 import { fetchAppDiagnosticLogsViaRest, normalizeDiagnosticLogLines } from "./app-diagnostics.mjs";
@@ -24,7 +25,10 @@ import { submitDeploymentWithIdempotentRetry } from "./deployment-admission-retr
 import { acquireDeployReceipt, releaseDeployReceipt } from "./deploy-receipt-store.mjs";
 import { CYAN, DIM, RED, RESET, YELLOW, error, info, log, success, warn } from "./output.mjs";
 import { platformFetch, rpcMutation } from "./platform-client.mjs";
-import { hasProjectDatabaseSchemaSource } from "./project-migration-manifest.mjs";
+import {
+  getProjectSchemaPreflightError,
+  hasProjectDatabaseSchemaSource,
+} from "./project-migration-manifest.mjs";
 import { hasWorkspaceSourceRuntime } from "./runtime-mode.mjs";
 import { verifyMigrationBundleArchiveRoundTrip } from "./migration-bundle-roundtrip.mjs";
 import { assertToolingRuntimeCapabilities, loadToolingRuntime } from "./tooling-runtime.mjs";
@@ -146,6 +150,7 @@ export function createDeployPackageRuntime({
   loadInternalBundleImpl,
   loadDeployAuditorImpl,
   runCodegenForDeployImpl,
+  randomUUIDImpl = randomUUID,
 } = {}) {
   let migrationProjectConfig = null;
   let preparedDeployCodegenArtifacts = null;
@@ -199,6 +204,26 @@ export function createDeployPackageRuntime({
     const cwd = cwdImpl();
     cleanupPreparedDeploySource();
     const { config, genEnv } = await loadMigrationGenerationContext(cwd);
+    const hasSchemaSource = hasProjectDatabaseSchemaSource({
+      cwd,
+      config: migrationProjectConfig,
+      existsSyncImpl,
+      resolvePathImpl,
+    });
+    if (!hasSchemaSource) {
+      const selection = detectProjectConfigFile({ cwd, existsSyncImpl, resolvePathImpl });
+      const preflightError = getProjectSchemaPreflightError({
+        cwd,
+        config: migrationProjectConfig,
+        hasSelectedConfigFile: Boolean(selection.selectedFile),
+        existsSyncImpl,
+        resolvePathImpl,
+      });
+      if (preflightError) throw preflightError;
+      migrationProjectConfig = null;
+      logImpl(`${DIM}  ok No schema source — migration generation not required${RESET}`);
+      return SUPPORTED_DRIZZLE_KIT_GENERATOR_VERSION;
+    }
     if (config) {
       preparedDeployCodegenArtifacts = await prepareDeployCodegenArtifacts({
         backendRoot: resolveConfiguredBackendRoot(config),
@@ -218,22 +243,6 @@ export function createDeployPackageRuntime({
         sourceRevision,
       });
     }
-    if (
-      !hasProjectDatabaseSchemaSource({
-        cwd,
-        config: migrationProjectConfig,
-        existsSyncImpl,
-        resolvePathImpl,
-      })
-    ) {
-      const selection = detectProjectConfigFile({ cwd, existsSyncImpl, resolvePathImpl });
-      if (selection.selectedFile && migrationProjectConfig?.schema) {
-        throw new Error("Configured schema source is missing from the project");
-      }
-      migrationProjectConfig = null;
-      logImpl(`${DIM}  ok No schema source — migration generation not required${RESET}`);
-      return SUPPORTED_DRIZZLE_KIT_GENERATOR_VERSION;
-    }
     const { execSync: execGen } = { execSync: execSyncImpl };
     infoImpl("Generating schema migrations...");
     try {
@@ -366,6 +375,7 @@ export function createDeployPackageRuntime({
     );
     infoImpl("Code: BACKEND_CAPABILITY_EMPTY");
     infoImpl("Stage: candidate");
+    infoImpl(`Correlation ID: deploy_${randomUUIDImpl()}`);
     infoImpl("Next action: EDIT_AND_CHECK");
     infoImpl("Add a backend procedure, or use gencow static <build-directory> for a frontend-only app.");
     exitImpl(1);

package/lib/migration-diagnostic.mjs

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { readFileSync, realpathSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 import { escapeTerminalControls, safeDiagnosticText } from "./migration-diagnostic-contract.mjs";
+import { formatLatestCliInvocation } from "./cli-update-guidance.mjs";
 
 export {
   extractActionableMigrationDiagnostic,
@@ -371,7 +372,7 @@ export function renderMigrationDiagnosticLines(diagnostic) {
               diagnostic.code === "MIGRATION_LOCAL_EXECUTION_FAILED"
                 ? "Inspect the local Drizzle journal and database catalog before retrying"
                 : "Run the platform's read-only migration-state inspection before any new mutation request",
-            UPDATE_CLI: "Update the CLI to the exact supported range shown above",
+            UPDATE_CLI: `Run ${formatLatestCliInvocation()} and then rerun the same command`,
             VIEW_STATUS: "View the exact operation receipt before any new mutation request",
             RETRY: "Regenerate a stable bundle and retry from a fresh plan",
             EDIT_AND_CHECK: "Apply one suggested fix, review the diff, and create a fresh plan",