gencow 0.1.245 → 0.1.247

package/bin/gencow.mjs

@@ -585,6 +585,7 @@ const cmd =
       ? "version"
       : rawCmd;
 maybeCheckCliVersion({
+  args,
   command: cmd,
   currentVersion: CLI_VERSION,
   errorImpl: error,

package/core/index.js

@@ -314,17 +314,30 @@ function buildWakeAppBootFailedResult(error) {
   const publicMessage = typeof metadata.publicMessage === "string" && metadata.publicMessage.length <= 200 ? metadata.publicMessage : message;
   const reasonCode = typeof metadata.reasonCode === "string" && /^[a-z][a-z0-9_]{2,80}$/.test(metadata.reasonCode) ? metadata.reasonCode : void 0;
   const correlationId = typeof metadata.correlationId === "string" && /^rt_[A-Za-z0-9_-]{8,80}$/.test(metadata.correlationId) ? metadata.correlationId : void 0;
+  const safeCode = (value) => typeof value === "string" && /^[A-Z][A-Z0-9_]{2,99}$/.test(value) ? value : void 0;
+  const operationId = typeof metadata.operationId === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(metadata.operationId) ? metadata.operationId : void 0;
+  const operationState = metadata.operationState === "completed" || metadata.operationState === "failed" ? metadata.operationState : void 0;
   return {
     ok: false,
     status: "boot_failed",
     error: publicMessage,
+    ...typeof metadata.hint === "string" && metadata.hint.length <= 500 ? { hint: metadata.hint } : {},
+    ...typeof metadata.stage === "string" && /^[a-z][a-z0-9_]{2,40}$/.test(metadata.stage) ? { stage: metadata.stage } : {},
+    ...typeof metadata.nextAction === "string" && metadata.nextAction.length <= 200 ? { nextAction: metadata.nextAction } : {},
+    ...typeof metadata.stateChanged === "boolean" ? { stateChanged: metadata.stateChanged } : {},
+    ...Number.isSafeInteger(metadata.retryAfterSec) && Number(metadata.retryAfterSec) > 0 ? { retryAfterSec: Number(metadata.retryAfterSec) } : {},
+    ...typeof metadata.retryCondition === "string" && metadata.retryCondition.length <= 500 ? { retryCondition: metadata.retryCondition } : {},
     ...reasonCode ? { reasonCode } : {},
     ...typeof metadata.retryable === "boolean" ? { retryable: metadata.retryable } : {},
-    ...correlationId ? { correlationId } : {}
+    ...correlationId ? { correlationId } : {},
+    ...operationId ? { operationId } : {},
+    ...operationState ? { operationState } : {},
+    ...metadata.terminalResultCode === null ? { terminalResultCode: null } : safeCode(metadata.terminalResultCode) ? { terminalResultCode: safeCode(metadata.terminalResultCode) } : {},
+    ...metadata.lastFailureCode === null ? { lastFailureCode: null } : safeCode(metadata.lastFailureCode) ? { lastFailureCode: safeCode(metadata.lastFailureCode) } : {}
   };
 }
 function isWakeAppDeferredResult(result) {
-  return !result.ok && (result.status === "capacity_rejected" || result.status === "queue_timeout");
+  return !result.ok && (result.status === "capacity_rejected" || result.status === "queue_timeout" || result.status === "convergence_pending");
 }
 
 // ../core/src/platform-capacity-profile.ts

package/lib/cli-dev-runtime.mjs

@@ -158,11 +158,11 @@ export function createApiCodegenRuntime(options = {}) {
     const absoluteFunctions = resolvePathImpl(cwd, backendRoot);
     const publishDir = resolveCodegenPublishDir(cwd, config);
     const artifactsDir = resolveCodegenArtifactsDir(cwd);
-    const apiTsPath = resolvePathImpl(publishDir, "api.ts");
-    const publishRel = relative(cwd, publishDir).replace(/\\/g, "/") || ".";
-    const previousApi = captureApiSnapshot({ apiTsPath, existsSyncImpl, readFileSyncImpl });
+    const apiTsPath = publishDir === false ? null : resolvePathImpl(publishDir, "api.ts");
+    const publishRel = publishDir === false ? null : relative(cwd, publishDir).replace(/\\/g, "/") || ".";
+    const previousApi = publishDir === false ? null : captureApiSnapshot({ apiTsPath, existsSyncImpl, readFileSyncImpl });
 
-    infoImpl("Generating client API types...");
+    infoImpl(publishDir === false ? "Client generation disabled; generating server artifacts..." : "Generating client API types...");
     try {
       const { bundled } = await runCodegenWithReporting({
         config,
@@ -209,7 +209,7 @@ export function createApiCodegenRuntime(options = {}) {
       } else {
         errorImpl(`API Codegen failed: ${caught.message}`);
       }
-      try {
+      if (publishDir !== false) try {
         writeCodegenFailureStub({
           apiTsPath,
           existsSyncImpl,

package/lib/cli-project-runtime.mjs

@@ -193,7 +193,7 @@ function parseTsConfigViaRegex(src) {
   if (port !== null) result.port = port;
 
   const codegen = {};
-  const clientOutDir = extractFrom(codegenBlock, "clientOutDir");
+  const clientOutDir = extractFrom(codegenBlock, "clientOutDir") ?? extractBoolFrom(codegenBlock, "clientOutDir");
   if (clientOutDir !== null) codegen.clientOutDir = clientOutDir;
   const outDir = extractFrom(codegenBlock, "outDir");
   if (outDir !== null) codegen.outDir = outDir;
@@ -401,7 +401,7 @@ export async function loadConfig(options = {}) {
       warnImpl("[gencow] `functionsDir` is deprecated; use `rootDir` instead (same meaning).");
       functionsDirDeprecationWarned = true;
     }
-    if (trimPath(raw?.codegen?.clientOutDir) && trimPath(raw?.codegen?.outDir)) {
+    if ((raw?.codegen?.clientOutDir === false || trimPath(raw?.codegen?.clientOutDir)) && trimPath(raw?.codegen?.outDir)) {
       warnImpl(
         "[gencow] Both codegen output paths are set. Using `codegen.clientOutDir`; ignoring deprecated `codegen.outDir`.",
       );
@@ -692,6 +692,7 @@ export function buildEnv(config, options = {}) {
     NODE_PATH: nodePath,
     PORT: String(processEnv.PORT || config.port),
     GENCOW_FUNCTIONS: resolvePathImpl(cwd, config.rootDir),
+    GENCOW_APP_NAME: processEnv.GENCOW_APP_NAME || config.name || config.deploy?.app || "",
     GENCOW_DB_URL: resolvePathImpl(cwd, config.db.url),
     GENCOW_STORAGE: resolvePathImpl(cwd, config.storage),
     GENCOW_MIGRATIONS: resolvePathImpl(cwd, config.rootDir, "migrations"),

package/lib/cli-version-check.mjs

@@ -94,6 +94,7 @@ export function formatStaleCliWarning({ currentVersion, latestVersion, command }
 }
 
 export function maybeCheckCliVersion({
+  args = [],
   cacheMaxAgeMs = DEFAULT_CACHE_MAX_AGE_MS,
   command,
   currentVersion,
@@ -112,7 +113,7 @@ export function maybeCheckCliVersion({
   if (isEnabled(processEnv.GENCOW_SKIP_VERSION_CHECK)) {
     return { status: "skipped" };
   }
-  if (command === "help" || command === "version") {
+  if (command === "help" || command === "version" || args.some((arg) => arg === "--help" || arg === "-h")) {
     return { status: "skipped" };
   }
 

package/lib/codegen-command.mjs

@@ -16,7 +16,7 @@ export { formatAuthSchemaConflictMessage } from "./auth-schema-provenance-guard.
 
 export function resolveCodegenConfig(config = {}) {
   const trim = (value) => (typeof value === "string" && value.trim().length > 0 ? value.trim() : null);
-  const outDir = trim(config.codegen?.clientOutDir) ?? trim(config.codegen?.outDir);
+  const outDir = config.codegen?.clientOutDir === false ? false : trim(config.codegen?.clientOutDir) ?? trim(config.codegen?.outDir);
   const serverOutDir =
     typeof config.codegen?.serverOutDir === "string" && config.codegen.serverOutDir.trim().length > 0
       ? config.codegen.serverOutDir.trim()
@@ -43,6 +43,7 @@ function getDeclaredCodegenClients(config = {}) {
 }
 
 export function resolveCodegenPublishDir(cwd, config, options = {}) {
+  if (config?.codegen?.clientOutDir === false) return false;
   const resolvePathImpl = options.resolvePathImpl ?? resolve;
   const selectedClient = options.selectedTarget ?? options.selectedClient ?? null;
   if (selectedClient) {
@@ -155,7 +156,7 @@ export function reportCodegenArtifacts({
   successImpl,
 }) {
   const artifactsRel = relative(cwd, artifactsDir).replace(/\\/g, "/") || ".";
-  const publishRel = relative(cwd, publishDir).replace(/\\/g, "/") || ".";
+  const publishRel = publishDir === false ? null : relative(cwd, publishDir).replace(/\\/g, "/") || ".";
   const serverRel = relative(cwd, serverPublishDir).replace(/\\/g, "/") || ".";
   const DB_SCHEMA_GEN = "db-schema.gen.ts";
   for (const artifact of artifacts) {
@@ -206,7 +207,8 @@ export async function runCodegenWithReporting({
     rootDir: resolveBackendRootDir(config),
     schema: config.schema,
     outDir,
-    finalOutDir: publishDir,
+    finalOutDir: publishDir === false ? undefined : publishDir,
+    clientGeneration: publishDir !== false,
     serverPublishDir,
     cloudFeatures: config.cloudFeatures,
     authSchema: codegenResolved.authSchema
@@ -254,6 +256,7 @@ export function createCodegenCommand(deps) {
       deps.logImpl(
         `  Client: api.ts, db.d.ts, operations.d.ts → codegen.clientOutDir or clients[*].codegen.outDir.\n`,
       );
+      deps.logImpl(`  Set codegen.clientOutDir: false to disable client generation; --outdir overrides it for one run.\n`);
       deps.logImpl(
         `  Server: schema-auth.gen.ts, db-schema.gen.ts → codegen.serverOutDir (default: <functionsDir>/generated).\n`,
       );
@@ -301,13 +304,14 @@ export function createCodegenCommand(deps) {
         explicitTarget = codegenArgs[i].slice("--target=".length) || null;
       }
     }
-    const declaredCodegenClients = getDeclaredCodegenClients(config);
+    const clientDisabled = codegenResolved.clientOutDir === false && !outdir;
+    const declaredCodegenClients = codegenResolved.clientOutDir === false ? [] : getDeclaredCodegenClients(config);
     const explicitSelection = explicitTarget ?? getCliInvocationSelection()?.target ?? null;
     if (
       Array.isArray(config?.clients) &&
       config.clients.length > 0 &&
       declaredCodegenClients.length === 0 &&
-      !outdir
+      !outdir && !clientDisabled
     ) {
       deps.errorImpl(
         "No declared codegen client found. Add clients[*].codegen.outDir or pass --outdir for a one-off output.",
@@ -315,7 +319,7 @@ export function createCodegenCommand(deps) {
       deps.exitImpl(1);
       return;
     }
-    const targetSelection = selectCodegenClient(declaredCodegenClients, explicitSelection);
+    const targetSelection = codegenResolved.clientOutDir === false ? { selected: null, autoSelected: false } : selectCodegenClient(declaredCodegenClients, explicitSelection);
     if (targetSelection.error) {
       deps.errorImpl(targetSelection.error);
       deps.exitImpl(1);
@@ -330,7 +334,7 @@ export function createCodegenCommand(deps) {
         });
     const serverPublishDir = resolveCodegenServerPublishDir(projectDir, config);
     const artifactsRel = relative(projectDir, artifactsDir).replace(/\\/g, "/") || ".";
-    const publishRel = relative(projectDir, publishDir).replace(/\\/g, "/") || ".";
+    const publishRel = publishDir === false ? null : relative(projectDir, publishDir).replace(/\\/g, "/") || ".";
     const serverRel = relative(projectDir, serverPublishDir).replace(/\\/g, "/") || ".";
 
     deps.logImpl(`\n${deps.BOLD}${deps.CYAN}Gencow Codegen${deps.RESET}\n`);
@@ -341,7 +345,7 @@ export function createCodegenCommand(deps) {
       deps.infoImpl(`Codegen client: ${selectedTarget.name}${selectionNote} → ${publishRel}/`);
     }
     deps.infoImpl(`Intermediate: ${artifactsRel}/manifest.json`);
-    deps.infoImpl(`Client types:  ${publishRel}/ (api.ts, db.d.ts, operations.d.ts)`);
+    deps.infoImpl(publishDir === false ? "Client generation disabled (codegen.clientOutDir: false)" : `Client types:  ${publishRel}/ (api.ts, db.d.ts, operations.d.ts)`);
     deps.infoImpl(`Server schema: ${serverRel}/ (schema-auth.gen.ts, db-schema.gen.ts)`);
     deps.logImpl("");
 

package/lib/deploy-admission-boundary.mjs

@@ -0,0 +1,52 @@
+const DEFAULT_ADMISSION_TIMEOUT_MS = 5 * 60 * 1000;
+
+function pendingResponse({ requestId, appName, resumeCommand = null }) {
+  const response = new Response(
+    JSON.stringify({
+      error: "Deployment admission is still running. The server request was not cancelled.",
+      code: "PLATFORM_DEPLOYMENT_ADMISSION_PENDING",
+      stage: "admission",
+      retryClass: "retryable-infra",
+      userAction: "VIEW_STATUS",
+      requestId,
+      appName,
+      statusCommand: "gencow deploy status",
+      resumeCommand,
+      serverOperationContinues: "UNKNOWN",
+      databaseState: "UNKNOWN",
+      incumbentServing: "UNKNOWN",
+      operationState: "UNKNOWN",
+    }),
+    { status: 503, headers: { "Content-Type": "application/json", "Retry-After": "5" } },
+  );
+  // The caller must surface this state without replaying the same admission
+  // request as a new deployment. Keep this marker private to the in-process
+  // response path; the public body carries the stable diagnostic contract.
+  response.deploymentAdmissionPending = true;
+  return response;
+}
+
+export async function postDeploymentAdmissionWithTimeout({
+  send,
+  requestId = null,
+  appName,
+  resumeCommand = requestId ? `gencow deploy --resume ${requestId}` : null,
+  timeoutMs = DEFAULT_ADMISSION_TIMEOUT_MS,
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
+}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error("DEPLOYMENT_ADMISSION_TIMEOUT_INVALID");
+  const controller = new AbortController();
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeoutImpl(() => {
+      resolve(pendingResponse({ requestId, appName, resumeCommand }));
+    }, timeoutMs);
+    timer?.unref?.();
+  });
+  try {
+    return await Promise.race([send({ signal: controller.signal }), deadline]);
+  } finally {
+    if (timer !== undefined) clearTimeoutImpl(timer);
+  }
+}

package/lib/deploy-command.mjs

@@ -27,6 +27,7 @@ export function renderDeployHelp() {
   log(`    gencow deploy`);
   log(`    gencow deploy status`);
   log(`    gencow deploy status --deployment <operation-id>`);
+  log(`    gencow deploy status --release-attempt <attempt-id> [--prod]`);
   log(`    gencow deploy logs [-n 100] [--history]`);
   log(`    gencow deploy --static dist/`);
   log(`    gencow deploy --prod --region kr`);
@@ -45,12 +46,50 @@ export function parseDeployLogScope(deployArgs) {
   return deployArgs.includes("--history") ? "history" : "current";
 }
 
+function readReleaseAttemptStatusId(deployArgs) {
+  const indices = deployArgs.flatMap((arg, index) => (arg === "--release-attempt" ? [index] : []));
+  if (indices.length === 0) return null;
+  if (indices.length !== 1) return undefined;
+  const index = indices[0];
+  const value = deployArgs[index + 1];
+  if (
+    typeof value !== "string" ||
+    !/^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u.test(value)
+  ) {
+    return undefined;
+  }
+
+  const targetArgs = [...deployArgs.slice(1, index), ...deployArgs.slice(index + 2)];
+  let appSelected = false;
+  let prodSelected = false;
+  for (let cursor = 0; cursor < targetArgs.length; cursor += 1) {
+    if (targetArgs[cursor] === "--prod" && !prodSelected) {
+      prodSelected = true;
+      continue;
+    }
+    if ((targetArgs[cursor] === "--app" || targetArgs[cursor] === "-a") && !appSelected) {
+      const appName = targetArgs[cursor + 1];
+      if (typeof appName !== "string" || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(appName)) return undefined;
+      appSelected = true;
+      cursor += 1;
+      continue;
+    }
+    return undefined;
+  }
+  return value;
+}
+
 function readDeploymentStatusOperationId(deployArgs) {
   const index = deployArgs.findIndex((arg) => arg === "--deployment");
   if (index === -1) return null;
   const value = deployArgs[index + 1];
+  // The public diagnostic contract emits `--prod` after the operation id for
+  // production-owned deployments.  The operation endpoint is already scoped
+  // by the id, so accept that harmless target selector instead of rejecting
+  // the exact self-service command we just rendered.
+  const trailingArgs = deployArgs.slice(index + 2);
   if (
-    index + 2 !== deployArgs.length ||
+    trailingArgs.some((arg) => arg !== "--prod") ||
     typeof value !== "string" ||
     !/^[1-9][0-9]*$/u.test(value) ||
     !Number.isSafeInteger(Number(value))
@@ -69,8 +108,11 @@ function logDeploymentOperationStatus(logImpl, infoImpl, body) {
   infoImpl(`State:     ${body.state ?? "unknown"}`);
   if (body.code) infoImpl(`Code:      ${body.code}`);
   if (body.stage) infoImpl(`Stage:     ${body.stage}`);
+  if (body.capability) infoImpl(`Capability: ${body.capability}`);
   if (body.databaseState) infoImpl(`Database:  ${body.databaseState}`);
   if (body.servingState) infoImpl(`Serving:   ${body.servingState}`);
+  if (body.retryClass) infoImpl(`Retry class: ${body.retryClass}`);
+  if (body.userAction) infoImpl(`Action:    ${body.userAction}`);
   if (body.retryPrecondition) infoImpl(`Before retry: ${body.retryPrecondition}`);
   if (body.nextAction?.command) infoImpl(`Next:      ${body.nextAction.command}`);
   logImpl("");
@@ -94,6 +136,61 @@ export async function handleDeployReadonlySubcommand(params) {
   }
 
   const subcmd = deployArgs[0];
+  const releaseAttemptId = subcmd === "status" ? readReleaseAttemptStatusId(deployArgs) : null;
+  if (releaseAttemptId === undefined) {
+    errorImpl("APP_RELEASE_STATUS_ID_INVALID: use a valid --release-attempt UUID.");
+    exitImpl(1);
+    return true;
+  }
+  if (releaseAttemptId !== null) {
+    const targetArgs = deployArgs
+      .slice(1)
+      .filter((arg, index, list) => arg !== "--release-attempt" && list[index - 1] !== "--release-attempt");
+    const target = resolveCloudAppTarget(targetArgs, {
+      cwd,
+      missingAppMessage: "App not found. Run from the project root with gencow.json.",
+      missingProdMessage: "No prod app yet. Run gencow deploy --prod first.",
+    });
+    if (target.error) {
+      errorImpl(target.error);
+      exitImpl(1);
+      return true;
+    }
+    const { appId, envTarget } = target;
+    const res = await platformFetchImpl(
+      creds,
+      `/platform/apps/${encodeURIComponent(appId)}/release-attempts/${releaseAttemptId}?environment=${envTarget}`,
+      { method: "GET" },
+    );
+    const decoded = await readJsonValueResponse(res);
+    const body = decoded.parsed && decoded.value && typeof decoded.value === "object" ? decoded.value : null;
+    if (!res.ok || !body || body.attemptId !== releaseAttemptId) {
+      for (const line of renderDeployFailureDiagnosticLines(body, res.statusText, { expectedAppName: appId }))
+        errorImpl(line);
+      exitImpl(1);
+      return true;
+    }
+    logImpl("");
+    logImpl("  Release Attempt");
+    infoImpl(`Attempt:   ${body.attemptId}`);
+    infoImpl(`Target:    ${body.environment}`);
+    infoImpl(`State:     ${body.state ?? "unknown"}`);
+    infoImpl(`Terminal:  ${body.terminal === true ? "yes" : "no"}`);
+    if (Array.isArray(body.expectedComponents)) infoImpl(`Components: ${body.expectedComponents.join(", ")}`);
+    if (body.backendDeploymentId) infoImpl(`Backend deployment: ${body.backendDeploymentId}`);
+    if (body.staticDeploymentId) infoImpl(`Static deployment: ${body.staticDeploymentId}`);
+    if (body.failureCode)
+      infoImpl(`Failure:   ${body.failureCode} (${body.failureStage ?? "unknown stage"})`);
+    infoImpl(
+      "Retry:     not established by release attempt status; terminal state alone is not a retry gate.",
+    );
+    if (body.backendDeploymentId)
+      infoImpl(`Next status: gencow deploy status --deployment ${body.backendDeploymentId}`);
+    if (body.staticDeploymentId)
+      infoImpl(`Next status: gencow deploy status --deployment ${body.staticDeploymentId}`);
+    logImpl("");
+    return true;
+  }
   const deploymentId = subcmd === "status" ? readDeploymentStatusOperationId(deployArgs) : null;
   if (deploymentId === undefined) {
     errorImpl("DEPLOYMENT_OPERATION_ID_INVALID: use a positive numeric --deployment value.");

package/lib/deploy-failure-diagnostic.mjs

@@ -27,6 +27,8 @@ const STRUCTURED_CONTRACT_FIELDS = [
   "retryClass",
   "userAction",
   "correlationId",
+  "requestId",
+  "environment",
   "operationId",
   "appName",
 ];
@@ -48,7 +50,7 @@ const SELF_SERVICE_RETRY_POLICIES = new Set([
   "AFTER_STATUS",
 ]);
 const SAFE_SELF_SERVICE_COMMAND =
-  /^gencow (?:deploy status(?: --prod)?(?: --deployment [1-9][0-9]*)?|db:check(?: --prod)? --inspect-state)$/u;
+  /^gencow (?:(?:deploy status(?: --prod)?(?: --deployment [1-9][0-9]*| --release-attempt [a-f0-9-]{36})?|deploy status --app [a-z][a-z0-9]*(?:-[a-z0-9]+)*(?: --prod)? --release-attempt [a-f0-9-]{36}|deploy status --app [a-z][a-z0-9]*(?:-[a-z0-9]+)*(?: --prod)?)|(?:deploy --app [a-z][a-z0-9]*(?:-[a-z0-9]+)*(?: --prod)? --resume [A-Za-z0-9_-]{16,128})|(?:db:check(?: --prod)? --inspect-state)|whoami)$/u;
 
 function safeText(value, maxLength) {
   if (typeof value !== "string") return null;
@@ -66,6 +68,9 @@ function readDeployFailureContract(value, expectedAppName) {
   const retryClass = safeText(value.retryClass, 32);
   const userAction = safeText(value.userAction, 32);
   const correlationId = value.correlationId === undefined ? null : safeText(value.correlationId, 128);
+  const requestId = value.requestId === undefined ? null : safeText(value.requestId, 128);
+  const environment = value.environment === "dev" || value.environment === "prod" ? value.environment : null;
+  const appName = value.appName === undefined ? null : safeText(value.appName, 128);
   const operationId =
     Number.isSafeInteger(value.operationId) && value.operationId > 0
       ? String(value.operationId)
@@ -88,9 +93,18 @@ function readDeployFailureContract(value, expectedAppName) {
     !RETRY_CLASSES.has(retryClass) ||
     !userAction ||
     !USER_ACTIONS.has(userAction) ||
+    (code === "DEPLOYMENT_EXECUTOR_ADMISSION_RECONCILIATION_UNAVAILABLE" && userAction !== "VIEW_STATUS") ||
     (value.correlationId !== undefined && !correlationId) ||
     (correlationId && !/^[A-Za-z0-9_-]{8,128}$/u.test(correlationId)) ||
+    (requestId !== null && !/^[A-Za-z0-9_-]{16,128}$/u.test(requestId)) ||
+    (requestId !== null &&
+      value.correlationId !== requestId &&
+      value.code === "DEPLOYMENT_EXECUTOR_ADMISSION_RECONCILIATION_UNAVAILABLE") ||
+    (value.environment !== undefined && !environment) ||
+    (value.appName !== undefined && (!appName || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(appName))) ||
     (expectedAppName && value.appName !== undefined && value.appName !== expectedAppName) ||
+    (code === "DEPLOYMENT_EXECUTOR_ADMISSION_OUTCOME_UNKNOWN" &&
+      (!requestId || !environment || !appName || !expectedAppName || appName !== expectedAppName)) ||
     (value.blockingOperationId !== undefined && !blockingOperationId) ||
     (value.recoveredOperationId !== undefined && !recoveredOperationId) ||
     (recoveredOperationId &&
@@ -113,6 +127,9 @@ function readDeployFailureContract(value, expectedAppName) {
     userAction:
       userAction === "CONTACT_SUPPORT" || userAction === "OPERATOR_ACTION" ? "VIEW_STATUS" : userAction,
     correlationId,
+    requestId,
+    environment,
+    appName,
     operationId,
     blockingOperationId,
     recoveredOperationId,
@@ -120,7 +137,7 @@ function readDeployFailureContract(value, expectedAppName) {
   };
 }
 
-function readSelfServiceDiagnostic(responseBody, contract) {
+function readSelfServiceDiagnostic(responseBody, contract, expectedAppName) {
   const value = responseBody?.diagnostic?.selfService;
   const stateImpact = value?.stateImpact;
   const retry = value?.retry;
@@ -131,6 +148,33 @@ function readSelfServiceDiagnostic(responseBody, contract) {
   const statusCommandOperationId = /^gencow deploy status(?: --prod)? --deployment ([1-9][0-9]*)$/u.exec(
     command ?? "",
   )?.[1];
+  const statusCommandReleaseAttemptMatch =
+    /^gencow deploy status(?: --prod)? --release-attempt ([a-f0-9-]{36})$/u.exec(command ?? "") ??
+    /^gencow deploy status --app ([a-z][a-z0-9]*(?:-[a-z0-9]+)*)( --prod)? --release-attempt ([a-f0-9-]{36})$/u.exec(
+      command ?? "",
+    );
+  const statusCommandReleaseAttemptId =
+    statusCommandReleaseAttemptMatch?.[3] ?? statusCommandReleaseAttemptMatch?.[1];
+  const statusCommandReleaseAttemptAppName = statusCommandReleaseAttemptMatch?.[3]
+    ? statusCommandReleaseAttemptMatch[1]
+    : null;
+  const statusCommandReleaseAttemptEnvironment = statusCommandReleaseAttemptMatch?.[3]
+    ? statusCommandReleaseAttemptMatch[2]
+      ? "prod"
+      : "dev"
+    : null;
+  const resumeCommandMatch =
+    /^gencow deploy --app ([a-z][a-z0-9]*(?:-[a-z0-9]+)*)( --prod)? --resume ([A-Za-z0-9_-]{16,128})$/u.exec(
+      command ?? "",
+    );
+  const resumeCommandAppName = resumeCommandMatch?.[1] ?? null;
+  const resumeCommandEnvironment = resumeCommandMatch?.[2] ? "prod" : "dev";
+  const resumeCommandRequestId = resumeCommandMatch?.[3] ?? null;
+  const scopedStatusCommandMatch =
+    /^gencow deploy status --app ([a-z][a-z0-9]*(?:-[a-z0-9]+)*)( --prod)?$/u.exec(command ?? "");
+  const scopedStatusCommandAppName = scopedStatusCommandMatch?.[1] ?? null;
+  const scopedStatusCommandEnvironment = scopedStatusCommandMatch?.[2] ? "prod" : "dev";
+  const requestId = value?.requestId === undefined ? null : safeText(value.requestId, 128);
   const prerequisites = Array.isArray(action?.prerequisites)
     ? action.prerequisites.map((item) => safeText(item, 240))
     : [];
@@ -160,6 +204,53 @@ function readSelfServiceDiagnostic(responseBody, contract) {
         statusCommandOperationId !== contract.blockingOperationId &&
         statusCommandOperationId !== contract.recoveredOperationId) ||
         !Number.isSafeInteger(Number(statusCommandOperationId)))) ||
+    (statusCommandReleaseAttemptId &&
+      statusCommandReleaseAttemptId !== contract.operationId &&
+      `release-${statusCommandReleaseAttemptId}` !== contract.operationId) ||
+    (statusCommandReleaseAttemptAppName &&
+      (statusCommandReleaseAttemptAppName !== contract.appName ||
+        (expectedAppName && statusCommandReleaseAttemptAppName !== expectedAppName) ||
+        (contract.environment && statusCommandReleaseAttemptEnvironment !== contract.environment))) ||
+    (requestId !== null && !/^[A-Za-z0-9_-]{16,128}$/u.test(requestId)) ||
+    (contract.requestId !== null && requestId !== contract.requestId) ||
+    (resumeCommandRequestId !== null && contract.code !== "DEPLOYMENT_EXECUTOR_ADMISSION_OUTCOME_UNKNOWN") ||
+    (contract.code === "DEPLOYMENT_EXECUTOR_ADMISSION_RECONCILIATION_UNAVAILABLE" &&
+      (!requestId ||
+        contract.stage !== "admission" ||
+        contract.userAction !== "VIEW_STATUS" ||
+        contract.requestId !== requestId ||
+        contract.correlationId !== requestId ||
+        !contract.environment ||
+        !contract.appName ||
+        !scopedStatusCommandAppName ||
+        scopedStatusCommandAppName !== contract.appName ||
+        scopedStatusCommandEnvironment !== contract.environment ||
+        !expectedAppName ||
+        contract.appName !== expectedAppName ||
+        stateImpact.mutation !== "UNKNOWN" ||
+        stateImpact.incumbentServing !== "UNKNOWN" ||
+        stateImpact.operationState !== "BLOCKED" ||
+        retry.allowedNow !== false ||
+        retry.policy !== "AFTER_STATUS")) ||
+    (contract.code === "DEPLOYMENT_EXECUTOR_ADMISSION_OUTCOME_UNKNOWN" &&
+      (!requestId ||
+        contract.stage !== "admission" ||
+        contract.userAction !== "RETRY" ||
+        contract.requestId !== requestId ||
+        !contract.environment ||
+        !contract.appName ||
+        !expectedAppName ||
+        contract.appName !== expectedAppName ||
+        resumeCommandAppName !== contract.appName ||
+        resumeCommandEnvironment !== contract.environment ||
+        !resumeCommandRequestId ||
+        resumeCommandRequestId !== requestId ||
+        contract.correlationId !== requestId ||
+        stateImpact.mutation !== "NONE" ||
+        stateImpact.incumbentServing !== "PRESERVED" ||
+        stateImpact.operationState !== "BLOCKED" ||
+        retry.allowedNow !== true ||
+        retry.policy !== "IMMEDIATE")) ||
     prerequisites.some((item) => item === null) ||
     prerequisites.length > 8 ||
     forbiddenActions.some((item) => item === null) ||
@@ -177,6 +268,7 @@ function readSelfServiceDiagnostic(responseBody, contract) {
     action: {
       kind: action.kind,
       ...(command === null ? {} : { command }),
+      ...(requestId === null ? {} : { requestId }),
       prerequisites,
     },
     forbiddenActions,
@@ -191,6 +283,7 @@ function appendSelfServiceState(lines, selfService) {
     `Operation state: ${selfService.stateImpact.operationState}`,
     `Retry policy: ${selfService.retry.policy} — ${selfService.retry.condition}`,
   );
+  if (selfService.action.requestId) lines.push(`Request ID: ${selfService.action.requestId}`);
   for (const prerequisite of selfService.action.prerequisites) {
     lines.push(`Prerequisite: ${prerequisite}`);
   }
@@ -252,7 +345,7 @@ export function renderDeployFailureDiagnosticLines(responseBody, statusText, opt
     contract.operationId &&
     /^[1-9][0-9]*$/u.test(contract.operationId)
   ) {
-    const selfService = readSelfServiceDiagnostic(responseBody, contract);
+    const selfService = readSelfServiceDiagnostic(responseBody, contract, options.expectedAppName);
     if (
       responseBody.retryReady === true &&
       responseBody.retryReadinessReason === "READY" &&
@@ -285,9 +378,10 @@ export function renderDeployFailureDiagnosticLines(responseBody, statusText, opt
       ? PLATFORM_STATUS_MESSAGE
       : (safeText(responseBody.error, 240) ?? fallbackMessage);
     const lines = [`Deploy failed: ${publicMessage}`, `Code: ${contract.code}`, `Stage: ${contract.stage}`];
-    const selfService = readSelfServiceDiagnostic(responseBody, contract);
+    const selfService = readSelfServiceDiagnostic(responseBody, contract, options.expectedAppName);
     appendSelfServiceState(lines, selfService);
     if (contract.operationId) lines.push(`Operation ID: ${contract.operationId}`);
+    if (contract.requestId) lines.push(`Request ID: ${contract.requestId}`);
     if (contract.blockingOperationId) lines.push(`Blocking operation ID: ${contract.blockingOperationId}`);
     if (contract.recoveredOperationId) lines.push(`Recovered operation ID: ${contract.recoveredOperationId}`);
     if (
@@ -310,6 +404,34 @@ export function renderDeployFailureDiagnosticLines(responseBody, statusText, opt
       Number.isSafeInteger(Number(contract.operationId))
         ? `gencow deploy status --deployment ${contract.operationId}`
         : "gencow deploy status";
+    if (contract.code === "PLATFORM_DEPLOYMENT_ADMISSION_PENDING") {
+      lines.push(
+        `Database state: ${safeText(responseBody.databaseState, 32) ?? "UNKNOWN"}`,
+        `Incumbent serving: ${safeText(responseBody.incumbentServing, 32) ?? "UNKNOWN"}`,
+        `Operation state: ${safeText(responseBody.operationState, 32) ?? "UNKNOWN"}`,
+      );
+      const requestId = safeText(responseBody.requestId, 128);
+      if (requestId && /^[A-Za-z0-9_-]{8,128}$/u.test(requestId)) lines.push(`Request ID: ${requestId}`);
+      lines.push(
+        "Server outcome: unknown; inspect the existing request before submitting another deployment.",
+      );
+      const resumeCommand = safeText(responseBody.resumeCommand, 240);
+      const resumeMatch = resumeCommand?.match(
+        /^gencow deploy (?:--resume [A-Za-z0-9_-]{8,128}|--static(?: --prod)? --app ([A-Za-z0-9_-]{1,128})(?: --client [A-Za-z0-9_-]{1,128})? --resume [A-Za-z0-9_-]{8,128})$/u,
+      );
+      const resumeToken = resumeCommand?.match(/--resume ([A-Za-z0-9_-]{8,128})$/u)?.[1];
+      const resumeAppName = resumeMatch?.[1];
+      const expectedResumeApp = options.expectedAppName ?? responseBody.appName;
+      if (
+        resumeMatch &&
+        requestId &&
+        resumeToken === requestId &&
+        (!resumeAppName || !expectedResumeApp || resumeAppName === expectedResumeApp)
+      ) {
+        lines.push(`Next command: ${resumeCommand}`);
+        return lines;
+      }
+    }
     lines.push(`Next command: ${selfService?.action.command ?? exactStatusCommand}`);
     if (contract.blockingOperationId && responseBody.retryReadinessReason === "ACTIVE_OWNER" && selfService) {
       lines.push(`Then check retry gate: ${exactStatusCommand}`);
@@ -321,7 +443,7 @@ export function renderDeployFailureDiagnosticLines(responseBody, statusText, opt
     : (safeText(responseBody.error, 240) ?? fallbackMessage);
   const lines = [`Deploy failed: ${publicMessage}`];
   lines.push(`Code: ${contract.code}`, `Stage: ${contract.stage}`);
-  const selfService = readSelfServiceDiagnostic(responseBody, contract);
+  const selfService = readSelfServiceDiagnostic(responseBody, contract, options.expectedAppName);
   appendSelfServiceState(lines, selfService);
   if (isCliUpgradeContract(contract) && !selfService) {
     lines.push(