gencow 0.1.242 → 0.1.244

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

@@ -10,11 +10,10 @@ import {
 import { resolveCreatedAppId, resolveCreatedAppResponse } from "./app-create-response.mjs";
 import {
   appNotFoundDiagnostic,
-  isExactAppDeleteResponse,
+  isExactAppDeleteHandoffResponse,
   parseAppListResponse,
   parseAppLookupResponse,
 } from "./app-response-contract.mjs";
-import { pollAppDeleteOperation } from "./app-delete-operation.mjs";
 import { appResponseError } from "./app-response-error.mjs";
 import { readJsonObjectResponse, readJsonValueResponse } from "./http-response-json.mjs";
 import { BOLD, CYAN, DIM, GREEN, RED, RESET, error, info, log, success, warn } from "./output.mjs";
@@ -22,10 +21,6 @@ import { loadCreds, rpcMutation, rpcQuery, saveCreds, requireCreds } from "./pla
 import { resolveProjectMetadataPath, resolveProjectSelection } from "./project-context.mjs";
 import { updateEnvLocalUrl } from "./cli-project-runtime.mjs";
 
-// Covers the 60s runtime-observer restart grace, reconciliation scans, and
-// one delayed worker acquisition without reporting a completed deletion as pending.
-const DEFAULT_DELETE_POLL_ATTEMPTS = 120;
-const DELETE_POLL_INTERVAL_MS = 1_000;
 const DEFAULT_APP_CREATE_TIMEOUT_MS = 60_000;
 
 function resolveAppCreateTimeoutMs(value) {
@@ -169,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} Delete "${BOLD}${name}${RESET}"? Stops process + removes data.\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. The name remains unavailable until then.\n  Type the app name to confirm: `,
       resolveAnswer,
     ),
   );
@@ -194,8 +189,6 @@ export function createAppCommand({
   rpcQueryImpl = rpcQuery,
   saveCredsImpl = saveCreds,
   setTimeoutImpl = setTimeout,
-  sleepImpl = (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)),
-  deletePollAttempts = DEFAULT_DELETE_POLL_ATTEMPTS,
   successImpl = success,
   updateEnvLocalUrlImpl = updateEnvLocalUrl,
   warnImpl = warn,
@@ -365,12 +358,16 @@ ${dashboardLine}
 
     if (subcmd === "delete") {
       const unsupportedOption = rest.find(
-        (value) => value.startsWith("-") && value !== "--force" && value !== "-f",
+        (value) => value.startsWith("-") && value !== "--force" && value !== "-f" &&
+          !value.startsWith("--request-id="),
       );
       const force = rest.includes("--force") || rest.includes("-f");
       const name = rest.find((value) => !value.startsWith("-")) || loadCredsImpl()?.currentApp;
-      if (!name || unsupportedOption) {
-        errorImpl("Usage: gencow app delete <name> [--force]");
+      const requestIdOptions = rest.filter((value) => value.startsWith("--request-id="));
+      const suppliedRequestId = requestIdOptions[0]?.slice("--request-id=".length);
+      if (!name || unsupportedOption || requestIdOptions.length > 1 ||
+          (suppliedRequestId !== undefined && !/^[A-Za-z0-9_-]{8,128}$/u.test(suppliedRequestId))) {
+        errorImpl("Usage: gencow app delete <name> [--force] [--request-id=<id>]");
         return 1;
       }
 
@@ -382,31 +379,27 @@ ${dashboardLine}
         }
       }
 
-      infoImpl(`Deleting app "${name}"...`);
-      const requestId = createDeleteRequestIdImpl();
-      const delRes = await rpcMutationImpl(creds, "apps.delete", { name, requestId });
-      let delData = await readJsonObjectResponse(delRes);
-      if (!isExactAppDeleteResponse(delData, name)) {
-        const operationResult = await pollAppDeleteOperation({
-          creds,
-          initialBody: delData,
-          name,
-          pollAttempts: deletePollAttempts,
-          pollIntervalMs: DELETE_POLL_INTERVAL_MS,
-          rpcQueryImpl,
-          sleepImpl,
-        });
-        if (operationResult) delData = operationResult;
+      infoImpl(`Removing app "${name}" from your account...`);
+      const requestId = suppliedRequestId ?? createDeleteRequestIdImpl();
+      const retryCommand = `gencow app delete '${name.replaceAll("'", "'\\''")}' --force --request-id=${requestId}`;
+      let delRes;
+      try {
+        delRes = await rpcMutationImpl(creds, "apps.deleteAsync", { name, requestId });
+      } catch {
+        errorImpl(`APP_DELETE_ASYNC_UNCONFIRMED: The request may have completed. Retry the same request: ${retryCommand}`);
+        return 1;
       }
-      if (!isExactAppDeleteResponse(delData, name)) {
-        errorImpl(
-          appResponseError(
+      const delData = await readJsonObjectResponse(delRes);
+      if (!isExactAppDeleteHandoffResponse(delData, name, requestId)) {
+        const diagnosis = appResponseError(
             delData,
-            invalidAppResponse("app delete", delRes, delRes.ok ? "success" : "error"),
+            invalidAppResponse("app delete handoff", delRes, delRes.ok ? "success" : "error"),
             delRes,
             { expectedAppId: name },
-          ),
-        );
+          );
+        errorImpl(delRes.ok || delRes.status >= 500
+          ? `${diagnosis}\nRequest ID: ${requestId}. Retry the same request: ${retryCommand}`
+          : diagnosis);
         return 1;
       }
 
@@ -415,7 +408,10 @@ ${dashboardLine}
         saveCredsImpl({ ...currentCreds, currentApp: undefined });
       }
 
-      successImpl(`App "${name}" deleted`);
+      successImpl(`App "${name}" removed from your account. An administrator will permanently delete it. The name remains unavailable until then.`);
+      if (delData.stopErrorCode) {
+        warnImpl(`App stop needs administrator review. Code: ${delData.stopErrorCode}. Handoff ID: ${delData.handoffId}`);
+      }
       return 0;
     }
 

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-contract.mjs

@@ -56,3 +56,12 @@ export function isExactAppDeleteResponse(value, expectedAppId) {
   const body = record(value);
   return body?.success === true && body.deleted === expectedAppId;
 }
+
+export function isExactAppDeleteHandoffResponse(value, expectedAppId, expectedRequestId) {
+  const body = record(value);
+  return body?.success === true && body.name === expectedAppId &&
+    body.requestId === expectedRequestId &&
+    body.ownerTransferredTo === "todelete@gencow.dev" &&
+    nonEmptyString(body.handoffId) &&
+    Number.isSafeInteger(body.transferredApps) && body.transferredApps >= 1;
+}

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");
   }
@@ -62,6 +96,14 @@ export function appResponseError(body, fallback, response = null, options = {})
   if (/^[A-Za-z0-9_-]{8,128}$/u.test(body.correlationId ?? "")) {
     lines.push(`Correlation ID: ${body.correlationId}`);
   }
+  if (body.stage === "admission") lines.push("Stage: admission");
+  if (body.stateImpact === "This deletion request made no ownership or resource change.") {
+    lines.push(`State impact: ${body.stateImpact}`);
+  }
+  if (typeof body.retryPrecondition === "string" &&
+      /^[A-Za-z0-9 ,.;:-]{1,200}$/u.test(body.retryPrecondition)) {
+    lines.push(`Retry condition: ${body.retryPrecondition}`);
+  }
   if (APP_DELETE_OPERATION_PATTERN.test(body.operationId ?? "")) {
     lines.push(`Operation ID: ${body.operationId}`);
   }