gencow 0.1.243 → 0.1.245

package/core/index.js

@@ -3636,6 +3636,7 @@ var RESERVED_TENANT_RUNTIME_ENV_KEYS = [
   "GENCOW_RUNTIME_NODE_MODULES",
   "GENCOW_INTERNAL_TOKEN",
   "GENCOW_CRON_TOKEN",
+  "GENCOW_SCHEDULED_JOB_PUBLIC_KEY",
   "GENCOW_DEPLOY_ID",
   "GENCOW_AI_PROXY_URL",
   "GENCOW_AI_PROXY_URL_ALT",

package/lib/app-command.mjs

@@ -164,7 +164,7 @@ async function confirmDelete(name) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const answer = await new Promise((resolveAnswer) =>
     rl.question(
-      `\n  ${RED}!${RESET} Remove "${BOLD}${name}${RESET}" from your account? An administrator will stop it and permanently delete its data. The name remains unavailable until then.\n  Type the app name to confirm: `,
+      `\n  ${RED}!${RESET} Remove "${BOLD}${name}${RESET}" from your account? An administrator will stop it and permanently delete its data. Redeploying this project can create a new app ID with the same display name.\n  Type the app name to confirm: `,
       resolveAnswer,
     ),
   );
@@ -408,7 +408,7 @@ ${dashboardLine}
         saveCredsImpl({ ...currentCreds, currentApp: undefined });
       }
 
-      successImpl(`App "${name}" removed from your account. An administrator will permanently delete it. The name remains unavailable until then.`);
+      successImpl(`App "${name}" removed from your account. An administrator will stop it and permanently delete it. Redeploying this project can create a new app ID with the same display name.`);
       if (delData.stopErrorCode) {
         warnImpl(`App stop needs administrator review. Code: ${delData.stopErrorCode}. Handoff ID: ${delData.handoffId}`);
       }

package/lib/app-delete-diagnostic.mjs

@@ -3,6 +3,99 @@ export const APP_DELETE_OPERATION_PATTERN =
 
 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;
+const SAFE_DELETE_STATES = new Set([
+  "accepted",
+  "stopping_children",
+  "draining_runtime",
+  "stop_dispatched",
+  "runtime_absent",
+  "tenant_db_drop_pending",
+  "catalog_delete_pending",
+  "blocked_ownership_ambiguous",
+  "blocked_active_work",
+  "blocked_runtime_outcome_unknown",
+  "blocked_catalog_outcome_unknown",
+  "failed_tenant_db_cleanup",
+  "failed_catalog_cleanup",
+  "failed_delete_recovery_required",
+  "restoring",
+  "restored",
+]);
+const RESTORE_ROUTE_ACTION_PRECONDITIONS = new Map([
+  [
+    "APP_DELETE_RESTORE_ROUTE_RECOVERY_DISABLED",
+    "Platform must enable serving-route publication for this app and environment before owner wake can proceed.",
+  ],
+  [
+    "APP_DELETE_RESTORE_APP_NOT_IN_ROUTE_ALLOWLIST",
+    "Platform must include this app in the serving-route rollout allowlist before owner wake can proceed.",
+  ],
+  [
+    "APP_DELETE_RESTORE_ROUTE_CONTROL_UNAVAILABLE",
+    "Platform must restore a valid serving-route rollout configuration before owner wake can proceed.",
+  ],
+]);
+const RESTORE_ADMISSION_ACTIONS = new Map([
+  [
+    "APP_DELETE_RESTORE_TENANT_DATABASE_ABSENT",
+    {
+      retryable: false,
+      retryClass: "owner-action",
+      userAction: "RETRY_DELETE",
+      nextAction: "RETRY_DELETE",
+      retryPrecondition:
+        "The tenant database is absent. Wake cannot restore the app; retry the app deletion so catalog cleanup can finish.",
+    },
+  ],
+  [
+    "APP_DELETE_RESTORE_ACTIVE_DEPLOYMENT_ATTEMPT",
+    {
+      retryable: true,
+      retryClass: "platform-action",
+      userAction: "WAIT_THEN_RETRY_WAKE",
+      nextAction: "WAIT_FOR_PLATFORM_RECONCILIATION",
+      retryPrecondition:
+        "Wait until the active app deployment attempt finishes and its lease clears; then retry the same owner wake.",
+    },
+  ],
+  ...[
+    "APP_DELETE_RESTORE_ACTIVE_LEASE",
+    "APP_DELETE_RESTORE_ACTIVE_WORK",
+    "APP_DELETE_RESTORE_RUNTIME_NOT_ABSENT",
+    "APP_DELETE_RESTORE_TOMBSTONE_NOT_ACKNOWLEDGED",
+    "APP_DELETE_RESTORE_TENANT_DATABASE_AUTHORITY_UNAVAILABLE",
+  ].map((code) => [
+    code,
+    {
+      retryable: true,
+      retryClass: "platform-action",
+      userAction: "WAIT_THEN_RETRY_WAKE",
+      nextAction: "WAIT_FOR_PLATFORM_RECONCILIATION",
+      retryPrecondition:
+        "Wait until the stated runtime or serving-route condition is clear, then retry the same owner wake/resume operation.",
+    },
+  ]),
+  ...[
+    "APP_DELETE_RESTORE_ADMISSION_FAILED",
+    "APP_DELETE_RESTORE_CATALOG_MUTATED",
+    "APP_DELETE_RESTORE_CHILD_ACTIVE",
+    "APP_DELETE_RESTORE_HANDOFF_MISMATCH",
+    "APP_DELETE_RESTORE_IDENTITY_MISMATCH",
+    "APP_DELETE_RESTORE_RUNTIME_WAKE_MISSING",
+    "APP_DELETE_RESTORE_STATE_CONFLICT",
+    "APP_DELETE_RESTORE_TOMBSTONE_MISMATCH",
+  ].map((code) => [
+    code,
+    {
+      retryable: false,
+      retryClass: "platform-action",
+      userAction: "VIEW_DELETE_STATUS",
+      nextAction: "VIEW_DELETE_STATUS",
+      retryPrecondition:
+        "The failed delete receipt and serving-route identity require platform reconciliation before wake can proceed.",
+    },
+  ]),
+]);
 
 export function isAppDeleteDiagnosticAppId(value) {
   return APP_ID_PATTERN.test(value ?? "");
@@ -33,6 +126,158 @@ function isCanonicalTimestamp(value) {
   return Number.isFinite(date.getTime()) && date.toISOString() === value;
 }
 
+export function readRestoreRouteActionAppDeleteDiagnostic(value, expectedAppId) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const retryPrecondition = RESTORE_ROUTE_ACTION_PRECONDITIONS.get(value.code);
+  if (
+    !retryPrecondition ||
+    !isAppDeleteDiagnosticAppId(expectedAppId) ||
+    !APP_DELETE_OPERATION_PATTERN.test(value.operationId ?? "") ||
+    !CORRELATION_ID_PATTERN.test(value.correlationId ?? "") ||
+    !SAFE_DELETE_STATES.has(value.state) ||
+    value.stage !== "restore-admission" ||
+    !["runtime-resume", "runtime-reconcile"].includes(value.capability) ||
+    ![
+      "The failed delete receipt remains unchanged; the app runtime was not started.",
+      "The same restore receipt remains active; no replacement delete or restore operation was created.",
+    ].includes(value.stateImpact) ||
+    value.retryable !== false ||
+    value.retryPrecondition !== retryPrecondition ||
+    value.retryClass !== "platform-action" ||
+    value.userAction !== "WAIT_FOR_PLATFORM_RECONCILIATION" ||
+    value.nextAction !== "WAIT_FOR_PLATFORM_RECONCILIATION"
+  ) {
+    return null;
+  }
+  return {
+    code: value.code,
+    operationId: value.operationId,
+    correlationId: value.correlationId,
+    state: value.state,
+    stateImpact: value.stateImpact,
+    retryPrecondition,
+    statusCommand: `gencow app status ${expectedAppId}`,
+  };
+}
+
+export function isRestoreRouteActionAppDeleteDiagnosticCandidate(value) {
+  return Boolean(
+    value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    RESTORE_ROUTE_ACTION_PRECONDITIONS.has(value.code),
+  );
+}
+
+export function readRestoreAdmissionAppDeleteDiagnostic(value, expectedAppId) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const action = RESTORE_ADMISSION_ACTIONS.get(value.code);
+  const stateImpactByState = {
+    failed_delete_recovery_required:
+      "The failed delete receipt remains unchanged; the app runtime was not started.",
+    restoring:
+      "The same restore receipt remains active; no replacement delete or restore operation was created.",
+  };
+  const stateImpact = stateImpactByState[value.state];
+  if (
+    !action ||
+    !isAppDeleteDiagnosticAppId(expectedAppId) ||
+    value.status !== 409 ||
+    !APP_DELETE_OPERATION_PATTERN.test(value.operationId ?? "") ||
+    !CORRELATION_ID_PATTERN.test(value.correlationId ?? "") ||
+    !stateImpact ||
+    value.stage !== "restore-admission" ||
+    !["runtime-resume", "runtime-reconcile"].includes(value.capability) ||
+    value.stateImpact !== stateImpact ||
+    value.retryable !== action.retryable ||
+    value.retryClass !== action.retryClass ||
+    value.userAction !== action.userAction ||
+    value.nextAction !== action.nextAction ||
+    value.retryPrecondition !== action.retryPrecondition
+  ) {
+    return null;
+  }
+  return {
+    code: value.code,
+    operationId: value.operationId,
+    correlationId: value.correlationId,
+    state: value.state,
+    stateImpact,
+    retryable: action.retryable,
+    retryPrecondition: action.retryPrecondition,
+    nextAction: action.nextAction,
+    statusCommand: `gencow app status ${expectedAppId}`,
+    nextCommand: action.userAction === "RETRY_DELETE" ? `gencow app delete ${expectedAppId}` : null,
+  };
+}
+
+export function isRestoreAdmissionAppDeleteDiagnosticCandidate(value) {
+  return Boolean(
+    value && typeof value === "object" && !Array.isArray(value) && RESTORE_ADMISSION_ACTIONS.has(value.code),
+  );
+}
+
+export function formatRestoreAdmissionAppDeleteDiagnosticLines(diagnostic) {
+  const lines = [
+    "App wake is blocked while Gencow checks the failed delete recovery.",
+    `Code: ${diagnostic.code}`,
+    `Operation ID: ${diagnostic.operationId}`,
+    `Correlation ID: ${diagnostic.correlationId}`,
+    `State: ${diagnostic.state}`,
+    `State impact: ${diagnostic.stateImpact}`,
+    `Retryable: ${diagnostic.retryable ? "yes" : "no"}`,
+    `Retry precondition: ${diagnostic.retryPrecondition}`,
+    `Next action: ${diagnostic.nextAction}`,
+  ];
+  lines.push(`Next command: ${diagnostic.nextCommand ?? diagnostic.statusCommand}`);
+  return lines;
+}
+
+export function formatInvalidRestoreAdmissionAppDeleteDiagnosticLines(value, expectedAppId) {
+  const lines = ["App wake is blocked; the failed delete recovery diagnosis could not be verified safely."];
+  if (RESTORE_ADMISSION_ACTIONS.has(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}`);
+  }
+  if (isAppDeleteDiagnosticAppId(expectedAppId)) {
+    lines.push(`Next command: gencow app status ${expectedAppId}`);
+  }
+  return lines;
+}
+
+export function formatRestoreRouteActionAppDeleteDiagnosticLines(diagnostic) {
+  return [
+    "App wake is blocked by Platform serving-route configuration.",
+    `Code: ${diagnostic.code}`,
+    `Operation ID: ${diagnostic.operationId}`,
+    `Correlation ID: ${diagnostic.correlationId}`,
+    `State: ${diagnostic.state}`,
+    `State impact: ${diagnostic.stateImpact}`,
+    "Retryable: no",
+    `Retry precondition: ${diagnostic.retryPrecondition}`,
+    "Next action: WAIT_FOR_PLATFORM_RECONCILIATION",
+    `Next command: ${diagnostic.statusCommand}`,
+  ];
+}
+
+export function formatInvalidRestoreRouteActionAppDeleteDiagnosticLines(value, expectedAppId) {
+  const lines = [
+    "App wake is blocked; the Platform serving-route diagnosis could not be verified safely.",
+    `Next command: gencow app status ${expectedAppId}`,
+  ];
+  if (RESTORE_ROUTE_ACTION_PRECONDITIONS.has(value.code)) lines.splice(1, 0, `Code: ${value.code}`);
+  if (APP_DELETE_OPERATION_PATTERN.test(value.operationId ?? "")) {
+    lines.splice(lines.length - 1, 0, `Operation ID: ${value.operationId}`);
+  }
+  if (CORRELATION_ID_PATTERN.test(value.correlationId ?? "")) {
+    lines.splice(lines.length - 1, 0, `Correlation ID: ${value.correlationId}`);
+  }
+  return lines;
+}
+
 // 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.
@@ -64,14 +309,123 @@ export function readBlockedAppDeleteDiagnostic(value, expectedAppId) {
   };
 }
 
+export function readRestoreInProgressAppDeleteDiagnostic(value, expectedAppId) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const immediateRpc =
+    value.success === undefined &&
+    value.error === "APP_DELETE_RESTORE_IN_PROGRESS" &&
+    value.stateImpact ===
+      "The same restore receipt remains active; no replacement delete or restore operation was created." &&
+    value.userAction === "WAIT_FOR_RESTORE" &&
+    value.nextAction === "WAIT_FOR_RESTORE";
+  const statusReceipt =
+    value.success === false &&
+    value.deleted === expectedAppId &&
+    typeof value.statusPath === "string" &&
+    isAllowedAppDeleteStatusPath(value.statusPath, value.operationId, expectedAppId);
+  if (
+    !isAppDeleteDiagnosticAppId(expectedAppId) ||
+    !APP_DELETE_OPERATION_PATTERN.test(value.operationId ?? "") ||
+    !CORRELATION_ID_PATTERN.test(value.correlationId ?? "") ||
+    value.state !== "restoring" ||
+    value.code !== "APP_DELETE_RESTORE_IN_PROGRESS" ||
+    value.retryable !== false ||
+    value.retryPrecondition !==
+      "Wait until this restore receipt leaves restoring; then check the app status." ||
+    (!immediateRpc && !statusReceipt)
+  ) {
+    return null;
+  }
+  return {
+    code: value.code,
+    operationId: value.operationId,
+    correlationId: value.correlationId,
+    state: value.state,
+    stateImpact:
+      "The same restore receipt remains active; no replacement delete or restore operation was created.",
+    retryPrecondition: "Wait until this restore receipt leaves restoring; then check the app status.",
+    statusCommand: `gencow app status ${expectedAppId}`,
+  };
+}
+
+export function formatRestoreInProgressAppDeleteDiagnosticLines(diagnostic) {
+  return [
+    "App restoration is still in progress; this delete did not complete.",
+    `Code: ${diagnostic.code}`,
+    `Operation ID: ${diagnostic.operationId}`,
+    `Correlation ID: ${diagnostic.correlationId}`,
+    `State: ${diagnostic.state}`,
+    `State impact: ${diagnostic.stateImpact}`,
+    "Retryable: no",
+    `Retry precondition: ${diagnostic.retryPrecondition}`,
+    "Next action: WAIT_FOR_RESTORE",
+    `Next command: ${diagnostic.statusCommand}`,
+  ];
+}
+
+export function readRestoredAppDeleteDiagnostic(value, expectedAppId) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const immediateRpc =
+    value.success === undefined &&
+    value.error === "APP_DELETE_RESTORE_COMPLETED_NEW_DELETE_REQUIRED" &&
+    value.stateImpact ===
+      "The previous restore is complete; this request did not create a delete operation." &&
+    value.retryPrecondition ===
+      "The old delete request is terminal. Start a new delete command to create a fresh operation." &&
+    value.userAction === "RETRY_DELETE_WITH_NEW_REQUEST" &&
+    value.nextAction === "RETRY_DELETE_WITH_NEW_REQUEST";
+  const statusReceipt =
+    value.success === false &&
+    value.deleted === expectedAppId &&
+    value.failureClass === "OWNER_ACTION_REQUIRED" &&
+    value.action === "RETRY_DELETE_WITH_NEW_REQUEST" &&
+    isAllowedAppDeleteStatusPath(value.statusPath, value.operationId, expectedAppId);
+  if (
+    !isAppDeleteDiagnosticAppId(expectedAppId) ||
+    !APP_DELETE_OPERATION_PATTERN.test(value.operationId ?? "") ||
+    !CORRELATION_ID_PATTERN.test(value.correlationId ?? "") ||
+    value.state !== "restored" ||
+    value.code !== "APP_DELETE_RESTORE_COMPLETED_NEW_DELETE_REQUIRED" ||
+    value.retryable !== false ||
+    (!immediateRpc && !statusReceipt)
+  ) {
+    return null;
+  }
+  return {
+    code: value.code,
+    operationId: value.operationId,
+    correlationId: value.correlationId,
+    state: value.state,
+    stateImpact: "The previous restore is complete; this request did not create a delete operation.",
+    retryPrecondition:
+      "The old delete request is terminal. Start a new delete command to create a fresh operation.",
+    deleteCommand: `gencow app delete ${expectedAppId}`,
+  };
+}
+
+export function formatRestoredAppDeleteDiagnosticLines(diagnostic) {
+  return [
+    "The app was restored; the previous delete request did not delete it.",
+    `Code: ${diagnostic.code}`,
+    `Operation ID: ${diagnostic.operationId}`,
+    `Correlation ID: ${diagnostic.correlationId}`,
+    `State: ${diagnostic.state}`,
+    `State impact: ${diagnostic.stateImpact}`,
+    "Retryable: no",
+    `Retry precondition: ${diagnostic.retryPrecondition}`,
+    "Next action: RETRY_DELETE_WITH_NEW_REQUEST",
+    `Next command: ${diagnostic.deleteCommand}`,
+  ];
+}
+
 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"),
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    (value.code === "PLATFORM_ACTION_REQUIRED" ||
+      value.failureClass === "PLATFORM_ACTION_REQUIRED" ||
+      value.action === "VIEW_DELETE_STATUS"),
   );
 }
 

package/lib/app-delete-operation.mjs

@@ -3,6 +3,8 @@ import {
   APP_DELETE_OPERATION_PATTERN,
   isAllowedAppDeleteStatusPath,
   readBlockedAppDeleteDiagnostic,
+  readRestoredAppDeleteDiagnostic,
+  readRestoreInProgressAppDeleteDiagnostic,
 } from "./app-delete-diagnostic.mjs";
 import { readJsonObjectResponse } from "./http-response-json.mjs";
 
@@ -21,8 +23,9 @@ const APP_DELETE_ACTIVE_STATES = new Set([
   "failed_tenant_db_cleanup",
   "failed_catalog_cleanup",
   "failed_delete_recovery_required",
+  "restoring",
 ]);
-const APP_DELETE_TERMINAL_FAILURE_STATES = new Set();
+const APP_DELETE_TERMINAL_FAILURE_STATES = new Set(["restored"]);
 const APP_DELETE_RESPONSE_STATES = new Set([
   ...APP_DELETE_ACTIVE_STATES,
   ...APP_DELETE_TERMINAL_FAILURE_STATES,
@@ -98,6 +101,12 @@ export async function pollAppDeleteOperation({
   rpcQueryImpl,
   sleepImpl,
 }) {
+  if (
+    readRestoreInProgressAppDeleteDiagnostic(initialBody, name) ||
+    readRestoredAppDeleteDiagnostic(initialBody, name)
+  ) {
+    return initialBody;
+  }
   const accepted = parseAppDeleteOperationEnvelope(initialBody, name);
   if (!accepted) return null;
   if (isMatchingTerminalFailureResponse(initialBody, accepted, name)) {
@@ -147,6 +156,20 @@ export async function pollAppDeleteOperation({
   }
 
   const pollingUnavailable = successfulPollResponses === 0 && transportFailures > 0;
+  if (latest.state === "restoring") {
+    return {
+      success: false,
+      deleted: name,
+      error: "App restoration is still in progress; this delete did not complete.",
+      code: "APP_DELETE_RESTORE_IN_PROGRESS",
+      operationId: accepted.operationId,
+      correlationId: latest.correlationId ?? accepted.correlationId,
+      statusPath: `/api/apps/${encodeURIComponent(name)}/delete/${encodeURIComponent(accepted.operationId)}`,
+      state: "restoring",
+      retryable: false,
+      retryPrecondition: "Wait until this restore receipt leaves restoring; then check the app status.",
+    };
+  }
   return {
     error: pollingUnavailable
       ? "App deletion status is temporarily unavailable. Retry the command with the same app."

package/lib/app-response-error.mjs

@@ -4,8 +4,20 @@ import {
   APP_DELETE_OPERATION_PATTERN,
   formatBlockedAppDeleteDiagnosticLines,
   formatInvalidBlockedAppDeleteDiagnosticLines,
+  formatRestoreInProgressAppDeleteDiagnosticLines,
+  formatRestoreRouteActionAppDeleteDiagnosticLines,
+  formatInvalidRestoreRouteActionAppDeleteDiagnosticLines,
+  formatRestoreAdmissionAppDeleteDiagnosticLines,
+  formatInvalidRestoreAdmissionAppDeleteDiagnosticLines,
+  formatRestoredAppDeleteDiagnosticLines,
+  isRestoreAdmissionAppDeleteDiagnosticCandidate,
+  isRestoreRouteActionAppDeleteDiagnosticCandidate,
   isBlockedAppDeleteDiagnosticCandidate,
   readBlockedAppDeleteDiagnostic,
+  readRestoreInProgressAppDeleteDiagnostic,
+  readRestoreRouteActionAppDeleteDiagnostic,
+  readRestoreAdmissionAppDeleteDiagnostic,
+  readRestoredAppDeleteDiagnostic,
 } from "./app-delete-diagnostic.mjs";
 
 export { APP_DELETE_OPERATION_PATTERN } from "./app-delete-diagnostic.mjs";
@@ -35,6 +47,28 @@ export function appResponseError(body, fallback, response = null, options = {})
   if (blockedDeleteDiagnostic) {
     return formatBlockedAppDeleteDiagnosticLines(blockedDeleteDiagnostic).join("\n");
   }
+  const restoreInProgressDiagnostic = readRestoreInProgressAppDeleteDiagnostic(body, options.expectedAppId);
+  if (restoreInProgressDiagnostic) {
+    return formatRestoreInProgressAppDeleteDiagnosticLines(restoreInProgressDiagnostic).join("\n");
+  }
+  const restoreRouteActionDiagnostic = readRestoreRouteActionAppDeleteDiagnostic(body, options.expectedAppId);
+  if (restoreRouteActionDiagnostic) {
+    return formatRestoreRouteActionAppDeleteDiagnosticLines(restoreRouteActionDiagnostic).join("\n");
+  }
+  if (isRestoreRouteActionAppDeleteDiagnosticCandidate(body)) {
+    return formatInvalidRestoreRouteActionAppDeleteDiagnosticLines(body, options.expectedAppId).join("\n");
+  }
+  const restoredDeleteDiagnostic = readRestoredAppDeleteDiagnostic(body, options.expectedAppId);
+  if (restoredDeleteDiagnostic) {
+    return formatRestoredAppDeleteDiagnosticLines(restoredDeleteDiagnostic).join("\n");
+  }
+  const restoreAdmissionDiagnostic = readRestoreAdmissionAppDeleteDiagnostic(body, options.expectedAppId);
+  if (restoreAdmissionDiagnostic) {
+    return formatRestoreAdmissionAppDeleteDiagnosticLines(restoreAdmissionDiagnostic).join("\n");
+  }
+  if (isRestoreAdmissionAppDeleteDiagnosticCandidate(body)) {
+    return formatInvalidRestoreAdmissionAppDeleteDiagnosticLines(body, options.expectedAppId).join("\n");
+  }
   if (isBlockedAppDeleteDiagnosticCandidate(body)) {
     return formatInvalidBlockedAppDeleteDiagnosticLines(body, options.expectedAppId).join("\n");
   }

package/lib/deploy-app-creation.mjs

@@ -0,0 +1,71 @@
+import { resolveCreatedAppResponse } from "./app-create-response.mjs";
+import { resolveDeployAppId } from "./deploy-app-target.mjs";
+import { writeProjectMetadata } from "./deploy-project-metadata.mjs";
+import { readJsonObjectResponse } from "./http-response-json.mjs";
+import { DIM, RESET } from "./output.mjs";
+
+export function createCloudAppIfNeeded({
+  platformFetchImpl,
+  rpcMutationImpl,
+  errorImpl,
+  infoImpl,
+  exitImpl,
+  successImpl,
+  setTimeoutImpl,
+  writeFileSyncImpl,
+}) {
+  return async function createAppIfNeeded({
+    creds,
+    appId,
+    displayName,
+    envTarget = "dev",
+    gencowJsonPath,
+    allowMissingAppReplacement = true,
+  }) {
+    const resolvedAppId = await resolveDeployAppId({
+      creds,
+      appId,
+      displayName,
+      environment: envTarget,
+      platformFetchImpl,
+      allowMissingAppReplacement,
+      infoImpl,
+      errorImpl,
+      exitImpl,
+    });
+    if (resolvedAppId === false) return null;
+    if (resolvedAppId) return resolvedAppId;
+
+    infoImpl("Creating app (auto-generating ID)...");
+    const createRes = await rpcMutationImpl(creds, "apps.create", { name: displayName });
+    if (!createRes.ok) {
+      const createErr = await readJsonObjectResponse(createRes);
+      errorImpl(`App creation failed: ${createErr?.error || createRes.statusText}`);
+      exitImpl(1);
+      return null;
+    }
+
+    const createData = await readJsonObjectResponse(createRes);
+    let nextAppId;
+    try {
+      nextAppId = resolveCreatedAppResponse(createData, { platformUrl: creds.platformUrl }).appId;
+    } catch (caught) {
+      errorImpl(`App creation failed: ${caught.message}`);
+      exitImpl(1);
+      return null;
+    }
+
+    successImpl(`App "${nextAppId}" created. Waiting for provisioning...`);
+    writeProjectMetadata({
+      appId: nextAppId,
+      displayName,
+      envTarget,
+      platformUrl: creds.platformUrl,
+      gencowJsonPath,
+      writeFileSyncImpl,
+    });
+    infoImpl(`${DIM}gencow.json created (appId: ${nextAppId})${RESET}`);
+    await new Promise((resolveDelay) => setTimeoutImpl(resolveDelay, 3000));
+    return nextAppId;
+  };
+}