@wtfalch/foundry 0.62.0 → 0.64.0

package/dist/plan/executor.js

@@ -5,16 +5,17 @@ import { EdgeApiError } from '@wtfalch/edge';
 import { coolifyImageFor } from '../bootstrap/versions.js';
 import { redactSecrets } from '../calls-sfu-deploy-support.js';
 import { resolveCallsSfuUrls } from '../calls-sfu.js';
-import { APPS_DOMAIN, APP_ENTRY_KEY, FULL_COMMIT_SHA, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, filesCollectionEnvName, heldEnvRef, isLiveEntry, isMainEntry, kosmosOn, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownsServices, sharedSecretRef, } from '../org.js';
+import { NATIVE_BUILD_KEY_BYTES, NATIVE_BUILD_KEY_ENV } from '../native-build.js';
+import { AI_ENTRY_PERMISSIONS, APPS_DOMAIN, APP_ENTRY_KEY, FILES_ENTRY_PERMISSIONS, FULL_COMMIT_SHA, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, filesCollectionEnvName, heldEnvRef, isLiveEntry, isMainEntry, kosmosOn, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownsServices, sharedSecretRef, } from '../org.js';
 import { adoptedKeysUnreadable, parseAdoptSnapshot } from './adopt.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, AGORA_CLIENT_ID_SCOPE_KEY, AGORA_DEPLOYED_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, DESKTOP_AUTH_PORT, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, chatCallsApplied, chatHasUpstreams, chatIntrospectionAppName, desiredAgoraEnv, desktopAuthInternalName, entryClientIdScopeKey, } from './agora.js';
 import { APPS_DATABASE_ADMIN_URL_ENV, applyAppsDbRoute, retireAppsDbRoute, } from './apps-db-route.js';
 import { APPS_ZONES_APPLIED_SCOPE_KEY, applyAppsZones, retireAppsZones } from './apps-zones.js';
 import { applyBlueGreenConnectors, applyBlueGreenServer, applyBlueGreenWeights, applyWorkspaceServer, } from './blue-green-apply.js';
-import { actionsKeyName, bgKey, blueGreenSubjects, colorAppName, healthTokenName, liveAppNameFor, mintActionsKey, mintPinKey, pinKeyName, splitServers, } from './blue-green.js';
+import { actionsKeyName, bgKey, blueGreenSubjects, colorAppName, healthTokenName, liveAppNameFor, mintActionsKey, mintPinKey, parseGuards, pinKeyName, splitServers, } from './blue-green.js';
 import { BouleOwnersError, httpBouleOwners } from './boule-owners-http.js';
 import { BOULE_ARCHON_CREDENTIAL_ENV, BOULE_ARCHON_PUSHED_AT_SCOPE_KEY, BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_CUSTOMERS_CREDENTIAL_ENV, BOULE_CUSTOMERS_ORG_ENV, BOULE_DATABASE_SCOPE_KEY, BOULE_DEPLOYED_SCOPE_KEY, BOULE_OWNER_SEED_SECRET_ENV, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, BOULE_TEST_CUSTOMERS_ORG_ENV, CUSTOMERS_DIRECTORY_USER_SCOPE_KEY, CUSTOMERS_ROOM_METADATA_KEY, CUSTOMERS_ROOM_SCOPE_KEY, CUSTOMERS_SIGN_IN_METADATA_KEY, CUSTOMERS_SIGN_IN_SCOPE_KEY, CUSTOMERS_SIGN_UP_SCOPE_KEY, archonCredentialRenewDue, bouleArchonCredentialRef, bouleEnvDrift, bouleHostnameFor, bouleMailWanted, bouleOwnerRefusedScopeKey, bouleOwnerSeededScopeKey, bouleOwnerSeeds, customersDirectoryRef, customersOrgIdOf, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
-import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, entryMcp, entryMcpProjectScopeKey, mcpCallbackUri, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
+import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, entryMcp, entryMcpProjectScopeKey, mcpCallbackUri, removeBrokerEntry, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { AUTH_REGISTRAR_KEY_ENV, AUTH_REGISTRAR_URL_ENV, REGISTRAR_APPLIED_SCOPE_KEY, REGISTRAR_DELIVERED_SCOPE_KEY, REGISTRAR_DEPLOY_WAITS_SCOPE_KEY, REGISTRAR_MINTED_SCOPE_KEY, REGISTRAR_REMOVAL_HELD_SCOPE_KEY, appliedRegistrarOrganization, ensureRegistrarKey, registrarAppliedValue, registrarRef, registrarWanted, wantedRegistrar, writeRegistrar, } from './broker-registrar.js';
 import { BROKER_WORKSPACES_DATABASE_SCOPE_KEY, canHoldWorkspacesDatabase, ensureBrokerWorkspacesDatabase, } from './broker-workspaces-database.js';
 import { recordBuiltCommit } from './build-record.js';
@@ -22,13 +23,13 @@ import { CallError, withTimeout as withLabelledTimeout } from './call-timeout.js
 import { MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsSynapseHomeserverYaml, masDockerfile, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
 import { CHAT_MAS_PORT, CHAT_REPO, CHAT_SERVICE_DOCKERFILE, CHAT_SERVICE_PORT, CHAT_SYNAPSE_DOCKERFILE, CHAT_SYNAPSE_PORT, assertChatServerName, chatInternalNames, chatMasConfigYaml, chatRekeyedInternalNames, chatServerName, chatServiceEnvs, chatSynapseHomeserverYaml, chatUpstreams, } from './chat-matrix.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
-import { BACKUP_POSTGRES_DATABASES_SCOPE_KEY, BACKUP_SCOPE_PREFIX, COMPANY_BACKUP_DATABASE_NAMES, backupScopeKey, } from './company-backups.js';
+import { BACKUP_POSTGRES_DATABASES_SCOPE_KEY, BACKUP_SCOPE_PREFIX, COMPANY_BACKUP_DATABASE_NAMES, backupScopeKey, companyDatabaseKeys, } from './company-backups.js';
 import { LOGIN_COOKIE_DOMAIN_SCOPE_KEY } from './cookie-domain.js';
 import { previewsOn } from './coolify-previews.js';
 import { CORE_FILES_COLLECTION_NAME, FILES_CORE_COLLECTION_SCOPE_KEY, ZITADEL_FILES_PROJECT_SCOPE_KEY, } from './core-files.js';
 import { waitForHealthyVersion, waitForNewDeployment, } from './deploy-health.js';
 import { DESKTOP_AUTH_APP_SCOPE_KEY, DESKTOP_AUTH_DEPLOYED_SCOPE_KEY, DESKTOP_AUTH_DOCKERFILE, DESKTOP_AUTH_HOME, DESKTOP_AUTH_ORIGIN_SCOPE_KEY, DESKTOP_AUTH_READY_PATH, DESKTOP_AUTH_READY_SCOPE_KEY, DESKTOP_AUTH_REDIRECT_SCOPE_KEY, DESKTOP_AUTH_REVISION_SCOPE_KEY, desktopAuthCallbackUri, desktopAuthEnv, desktopAuthInputs, desktopAuthRedirectUnsupported, desktopAuthRevision, } from './desktop-auth.js';
-import { signInCallbackAppliedValue, signInRedirectUris, unionRedirectUris, zitadelAppDesktopCallbackAppliedScopeKey, } from './desktop-callback.js';
+import { desktopCallbackUri, signInCallbackAppliedValue, signInRedirectUris, unionRedirectUris, zitadelAppDesktopCallbackAppliedScopeKey, } from './desktop-callback.js';
 import { PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, onPlatformNetwork, placed, placedByScope, placedOnPlatform, } from './destinations.js';
 import { DEFAULT_AI_LIMIT_MICROS } from './diff.js';
 import { createEdgeAccess, isNotFound as isEdgeNotFound, } from './edge-access.js';
@@ -36,7 +37,7 @@ import { EDGE_DNS_WRITE_CONCURRENCY, createEdgeDns, limiter, } from './edge-dns.
 import { createEdgeRateLimits, } from './edge-ratelimits.js';
 import { createEdgeTunnels } from './edge-tunnels.js';
 import { createEdgeZones } from './edge-zones.js';
-import { AI_ENTRY_RENEW_WINDOW_DAYS, entryAiAppliedScopeKey, entryAiClampedScopeKey, entryAiExpiresScopeKey, entryAiPendingExpiresScopeKey, entryAiRetiredScopeKey, entryAiUndeliveredScopeKey, entryAiUnrevokedScopeKey, entryAiWebhookPendingScopeKey, entryAiWrittenScopeKey, parseIdList, } from './entry-ai-key.js';
+import { AI_ENTRY_KEY_DAYS, AI_ENTRY_RENEW_WINDOW_DAYS, entryAiAppliedScopeKey, entryAiClampedScopeKey, entryAiExpiresScopeKey, entryAiPendingExpiresScopeKey, entryAiRetiredScopeKey, entryAiUndeliveredScopeKey, entryAiUnrevokedScopeKey, entryAiWebhookPendingScopeKey, entryAiWrittenScopeKey, parseIdList, } from './entry-ai-key.js';
 import { applyEntryAudit } from './entry-audit.js';
 import { CUSTOMER_GRANTS_CREDENTIAL_ENV, CUSTOMER_GRANTS_ENV, CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY, customerGrantsEntries, customerGrantsJson, customerGrantsMintedScopeKey, customerGrantsRef, customerGrantsToDrop, ensureCustomerGrantsCredential, wantedCustomerGrants, } from './entry-customer-grants.js';
 import { BOULE_EDGE_ENTRY_KEY, EDGE_ENTRY_KEY_DAYS, EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY, EDGE_SLUG_APPLIED_SCOPE_KEY, ENTRY_EDGE_KEY_DELIVERY_ATTEMPTS, bouleEdgeKeyWanted, edgeKeyAppRecordKey, edgeKeyDomain, entryEdgeMintedAtScopeKey, entryEdgeRetiredScopeKey, entryEdgeUndeliveredScopeKey, } from './entry-edge-key.js';
@@ -67,9 +68,9 @@ import { LIMITS, limited } from './own-limits.js';
 import { OWN_FILES_R2_SCOPE_KEY, OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, OWN_SERVICES_APPLIED_SCOPE_KEY, OwnServicesBlockedError, orgNetwork, orgTarget, platformTarget, scopeFromOrg, } from './own-services.js';
 import { ownSfuUrls, provisionSfuApp } from './own-sfu.js';
 import { JOBS_INTERNAL_URL_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, } from './platform-diff.js';
-import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appFolderDiffers, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, orgDeclaresMcp, resolveAppEnv, serviceDbEnvAppliedScopeKey, zitadelAppIdTokenUserinfoAppliedScopeKey, } from './platform-diff.js';
+import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appFolderDiffers, appImageAppliedScopeKey, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, entryImageFields, entryImageRef, orgDeclaresMcp, resolveAppEnv, serviceDbEnvAppliedScopeKey, zitadelAppIdTokenUserinfoAppliedScopeKey, } from './platform-diff.js';
 import { AUTH_LOGIN_PORT, PLATFORM_AUTH_BROKER_MAIL_KEY_REF, PLATFORM_AUTH_LOGIN_INTERNAL_NAME, PLATFORM_AUTH_LOGIN_SCOPE_KEY, PLATFORM_AUTH_PROJECT, PLATFORM_MAIL_SERVER_SCOPE_KEY, defaultStalwartForInstance, filesDepsInvalid, filesShareDomains, provisionAuthStack, provisionDatabaseBackup, provisionFilesHost, provisionJobsHost, provisionMailServer, resolveOwnFilesKeys, } from './platform-providers.js';
-import { companyAppPostLogoutUris, postLogoutAppliedValue, zitadelAppPostLogoutAppliedScopeKey, } from './post-logout-uris.js';
+import { companyAppPostLogoutUris, postLogoutAppliedValue, postLogoutUrisFor, zitadelAppPostLogoutAppliedScopeKey, } from './post-logout-uris.js';
 import { CLOUDFLARE_TUNNEL_APPS_HOSTNAMES_SCOPE_KEY, CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY, CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY, ENTRY_CONTAINER_LABELS, appLabelsAppliedScopeKey, builtinRoutes, entryAppsHostnames, entryLabelHash, entryLabelSpec, entryOikosHostnames, entryProxyLabels, entryRoutes, entryRoutesMarker, ownsAppsZoneName, ownsOikosName, routesWithoutToken, sameLabelSets, } from './proxy-labels.js';
 import { createReleaseHost } from './release-host.js';
 import { TUNNEL_HTTP_INGRESS_SCOPE_KEY, applyRemoteDatabase, mergeTcpIngress, recordedTcpRoutes, } from './remote-database.js';
@@ -77,7 +78,8 @@ import { editSignInBindings } from './sign-in-bindings.js';
 import { ZITADEL_ORG_DOMAIN_SCOPE_KEY, ZITADEL_ORG_REGISTRATION_CLOSED_SCOPE_KEY, closeSignInOrgRegistration, ensureSignInOrg, inviteOwnerWithLink, registerSignInDomainOrBlock, signInOrgDomain, } from './sign-in-org.js';
 import { SIGN_IN_BASE_PATH, SIGN_IN_ENV_LIVE_SCOPE_PREFIX, SIGN_IN_IN_APP_SCOPE_KEY, SIGN_IN_LOGIN_APP_SCOPE_KEY, SIGN_IN_RATE_LIMIT_DESCRIPTION, SIGN_IN_RATE_LIMIT_EXPRESSION, SIGN_IN_RATE_LIMIT_SCOPE_KEY, SIGN_IN_TRUSTED_SCOPE_KEY, SIGN_IN_UPSTREAM_ENV, inAppBindingFor, inAppSignIn, inAppStateHosts, inAppStatePairs, inAppTargets, signInEnvLiveHosts, } from './sign-in.js';
 import { moveSigninDatabase } from './signin-db-move.js';
-import { stageGateKey, stageHostname, } from './stage-guards.js';
+import { buildStageCopyHostPorts, } from './stage-copy-host.js';
+import { membersHash, stageGateEmails, stageGateKey, stageHostname, syncStageGateMembers, } from './stage-guards.js';
 import { WORKER_APP_DB_SCOPE_KEYS, provisionWorkerAppDb, workerAppDbCaPem, workerAppDbOwnerUrl, } from './worker-app-db.js';
 import { WORKER_APP_CALL_TIMEOUT_MS, applyWorkerApp, heldBrokerKey, teardownWorkerApp, withCallTimeout, } from './worker-app.js';
 import { entryWorkerAppliedScopeKey, entryWorkerExclusionsScopeKey, entryWorkerRetiredScopeKey, entryWorkerRouteIdScopeKey, entryWorkerRoutePatternScopeKey, entryWorkerRoutePendingScopeKey, entryWorkerRouteZoneScopeKey, entryWorkerUploadedScopeKey, } from './worker.js';
@@ -3165,8 +3167,33 @@ export class FoundryStepExecutor {
             ...(this.ports.runtime?.fetch ? { fetch: this.ports.runtime.fetch } : {}),
             renew,
             label: `coolify:release:${subject.id}`,
+            ...this.stageCopyFor(org, subject, context),
         });
     }
+    /**
+     * The copy's ports for one subject. Production's database is the org's (`coolify:database:<org id>`) for an
+     * entry and Boule's own for Boule; Agora has none, so its copy is refused with `no-production-database`.
+     */
+    stageCopyFor(org, subject, context) {
+        const entryDatabase = companyDatabaseKeys(org);
+        const ports = buildStageCopyHostPorts({
+            host: this.ports.stageCopy,
+            coolify: this.ports.coolify,
+            context,
+            org,
+            secret: (value) => void this.handledSecrets.add(value),
+            databaseKey: subject.builtin ?? `app.${subject.id}`,
+            databaseScopeKey: subject.builtin === 'boule'
+                ? entryDatabase.boule
+                : subject.builtin
+                    ? null
+                    : entryDatabase.app,
+            backupScopeKey: backupScopeKey(subject.builtin === 'boule' ? 'boule' : 'app'),
+            projectScopeKey: 'coolify_project',
+            serverScopeKey: COOLIFY_SERVER_SCOPE_KEY,
+        });
+        return ports ? { stageCopy: ports } : {};
+    }
     /** Whether the stage mail sink app is stopped or gone, read live. A failed read throws; the caller reads that as up. */
     async stageSinkDown(appId) {
         try {
@@ -3178,6 +3205,13 @@ export class FoundryStepExecutor {
             throw error;
         }
     }
+    /** Which stage-guard ports this executor has, for the planner (they decide the guard names in the applied hash). */
+    stageGuardPorts() {
+        return {
+            probes: this.ports.stageProbes !== undefined,
+            access: Boolean(this.ports.access || this.ports.edge),
+        };
+    }
     /** Every server Coolify lists with whether it is usable and reachable, for the planner. */
     async blueGreenServers() {
         return (await this.ports.coolify.listServers()).map((s) => ({
@@ -3297,7 +3331,8 @@ export class FoundryStepExecutor {
             primaryBlueAppId,
             logDir: LOG_DIR,
             isRunning: isRunningOrStarting,
-            stageGuards: this.stageGuards(org, subject, recorded(), action.desired.accessProviderId),
+            stageGuards: this.stageGuards(org, subject, recorded(), action.desired.accessProviderId, context),
+            guardInputs: parseGuards(action.desired.guards),
             stageSink: { slug: org.slug },
         };
         if (action.kind === 'bluegreen-lb') {
@@ -3336,6 +3371,8 @@ export class FoundryStepExecutor {
         const guards = this.ports.stageProbes ? { probes: this.ports.stageProbes } : {};
         if (gateId)
             guards.gate = { hostname: host, create: async () => ({ id: gateId }) };
+        // A workspace signs in with its own client (`workspaceStageSignIn`), never stage sign-in's: that guard is "none".
+        guards.signIn = { required: false };
         const runtime = this.ports.runtime ?? {};
         const authIssuer = action.desired.authIssuer ?? null;
         const signIn = await this.workspaceStageSignIn(org, entry, authIssuer, context);
@@ -3604,8 +3641,12 @@ export class FoundryStepExecutor {
      * the company's sign-in organisation, an owner, an Access port) and no `hosting.access` rule names the host: a
      * bypass or service-token rule there would open stage, so no gate is made and the guard stays unrecorded.
      */
-    stageGuards(org, subject, recorded, providerId) {
+    stageGuards(org, subject, recorded, providerId, context) {
         const guards = this.ports.stageProbes ? { probes: this.ports.stageProbes } : {};
+        const signIn = this.stageSignInPort(org, subject, context);
+        if (signIn)
+            guards.signIn = signIn;
+        guards.services = this.stageServicesPort(org, subject, context);
         const claimValue = recorded[ZITADEL_ORG_SCOPE_KEY];
         const emails = org.owners.map((owner) => owner.email);
         if (!org.domain || typeof providerId !== 'string' || !providerId || !claimValue)
@@ -3617,19 +3658,285 @@ export class FoundryStepExecutor {
             return guards;
         guards.gate = {
             hostname,
-            create: () => this.accessPort().createGate({
-                organisationId: org.id,
-                key: stageGateKey(subject.id),
-                entry: subject.id,
-                hostnames: [hostname],
-                providerId,
-                claimName: GATE_CLAIM_NAME,
-                claimValue,
-                emails,
-            }),
+            create: async () => {
+                const list = await stageGateEmails({
+                    label: `coolify:stage-gate:${subject.id}`,
+                    subjectId: subject.id,
+                    orgId: org.id,
+                    owners: emails,
+                    read: this.ports.releasePreviewMembers,
+                });
+                const created = await this.accessPort().createGate({
+                    organisationId: org.id,
+                    key: stageGateKey(subject.id),
+                    entry: subject.id,
+                    hostnames: [hostname],
+                    providerId,
+                    claimName: GATE_CLAIM_NAME,
+                    claimValue,
+                    emails: list.emails,
+                });
+                return list.members
+                    ? { id: created.id, membersHash: membersHash(list.emails) }
+                    : { id: created.id };
+            },
         };
         return guards;
     }
+    /**
+     * One release tick for one subject: its recorded stage gate's list follows the people holding
+     * `releases:preview`, owners always staying (`syncStageGateMembers`). Never throws.
+     */
+    async syncStageGateMembers(org, subject, context) {
+        await syncStageGateMembers({
+            label: `coolify:stage-gate:${subject.id}`,
+            subjectId: subject.id,
+            orgId: org.id,
+            owners: org.owners.map((owner) => owner.email),
+            read: this.ports.releasePreviewMembers,
+            recorded: context.recordedIds(),
+            record: (key, value) => context.recordScopeId(key, value),
+            persist: () => context.persist(),
+            setPeople: async (gateId, list) => {
+                const access = this.accessPort();
+                if (!access.setGatePeople) {
+                    const error = new Error('the Access port cannot change a gate');
+                    error.name = 'NoGatePeoplePort';
+                    throw error;
+                }
+                await access.setGatePeople(gateId, list);
+            },
+        });
+    }
+    /**
+     * Stage's own files organisation, ai organisation and jobs project (`plan/stage-services.ts`), each named
+     * for its subject (`<org id>-stage-<subject id>`, `<slug>-stage-<subject id>`: one per subject, as the recorded keys are) and built from the same ports production's steps use. A service whose port is
+     * missing or not ready answers `available() === false`, and stage then records it absent and mints nothing.
+     */
+    stageServicesPort(org, subject, context) {
+        const entry = subject.builtin
+            ? undefined
+            : org.hosting.entries.find((e) => e.key === subject.id);
+        const stageOrgId = `${org.id}-stage-${subject.id}`;
+        const keyName = `${org.slug}-${subject.id}-stage`;
+        const heldKeys = this.ports.heldKeys;
+        const held = (service) => ({
+            refFor: (envName) => sharedSecretRef(org.id, `stage-${service}-${envName.toLowerCase()}-${subject.id}`),
+            resolve: async (ref) => (await heldKeys?.resolve(ref)) ?? null,
+            put: async (ref, value) => {
+                if (typeof heldKeys?.put !== 'function')
+                    throw new Error('the held keys cannot put');
+                await heldKeys.put(ref, value);
+            },
+        });
+        const canHold = typeof heldKeys?.put === 'function';
+        const reachable = async (get) => {
+            try {
+                await get();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const owner = filesOwnerUserId(org, context.recordedIds());
+        const files = {
+            idEnv: 'FILES_ORGANISATION_ID',
+            held: held('files'),
+            available: async () => canHold && Boolean(owner) && (await reachable(() => this.filesPort())),
+            create: async () => {
+                const port = await this.filesPort();
+                const made = await port.provisionOrganisation({
+                    organisationId: stageOrgId,
+                    ceilingBytes: null,
+                    ceilingMicros: null,
+                    name: `${org.displayName}-stage`,
+                    ...(owner ? { owner } : {}),
+                });
+                return { id: made.organisationId };
+            },
+            mintKey: async (id) => {
+                const port = await this.filesPort();
+                const issued = await port.issueOrganisationKey(id, {
+                    name: keyName,
+                    kind: 'service',
+                    issuer: owner,
+                    permissions: [...(entry?.uses?.files?.permissions ?? FILES_ENTRY_PERMISSIONS)],
+                    expiresDays: FILES_KEY_DAYS,
+                });
+                return { keyIds: [issued.id], secrets: [{ env: 'FILES_API_KEY', value: issued.secret }] };
+            },
+        };
+        const ai = {
+            idEnv: 'AI_ORGANISATION_ID',
+            held: held('ai'),
+            available: async () => canHold && (await reachable(() => this.aiPort())),
+            create: async () => {
+                const port = await this.aiPort();
+                // Its own budget line, with production's limit (its declared one, else the default).
+                const limitMicros = org.ai.limitMicros ?? DEFAULT_AI_LIMIT_MICROS;
+                const made = await port.provisionOrganisation({ organisationId: stageOrgId, limitMicros });
+                await port.setOrganisationOffers(stageOrgId, [...(entry?.uses?.ai?.offerings ?? [])]);
+                await port.updateBudget(stageOrgId, { keyId: null, limitMicros });
+                return { id: made.organisationId };
+            },
+            mintKey: async (id) => {
+                const port = await this.aiPort();
+                const issued = await port.issueOrganisationKey(id, {
+                    name: keyName,
+                    expiresDays: AI_ENTRY_KEY_DAYS,
+                    permissions: [...(entry?.uses?.ai?.permissions ?? AI_ENTRY_PERMISSIONS)],
+                });
+                return { keyIds: [issued.id], secrets: [{ env: 'AI_API_KEY', value: issued.secret }] };
+            },
+        };
+        const jobs = {
+            held: held('jobs'),
+            available: async () => canHold && Boolean(org.domain) && (await reachable(() => this.jobsPort(org))),
+            create: async () => {
+                const scheduler = await this.jobsPort(org);
+                const projectName = `${org.slug}-stage-${subject.id}`;
+                const registered = await scheduler.registerProject({
+                    name: projectName,
+                    baseUrl: `https://${stageHostname(org.domain, subject.id)}`,
+                });
+                return registered.secret && registered.syncKey
+                    ? {
+                        id: registered.id,
+                        name: projectName,
+                        keyIds: [registered.id],
+                        secrets: [
+                            { env: 'JOBS_SIGNING_SECRET', value: registered.secret },
+                            { env: 'JOBS_SYNC_KEY', value: registered.syncKey },
+                        ],
+                    }
+                    : { id: registered.id, name: projectName };
+            },
+        };
+        const prodJobsProjectId = context.recordedIds()[`jobs:registration:${org.id}`];
+        return { files, ai, jobs, ...(prodJobsProjectId ? { prodJobsProjectId } : {}) };
+    }
+    /**
+     * Stage's own sign-in (`plan/stage-signin.ts`): a client named `<production client>-stage` on production's
+     * sign-in organisation and project with redirect URIs on the stage host only, a broker entry
+     * `<production entry>-stage` with a key of its own, and that key's held ref. `{ required: false }` for an entry
+     * that does not sign in. `undefined`, with one fixed log line saying why, when something it needs is missing:
+     * the guard then stays unrecorded and the copy waits. Platform-archon is not covered yet.
+     */
+    stageSignInPort(org, subject, context) {
+        const why = (reason) => {
+            console.info(`stage sign-in for ${subject.id} is not set up: ${reason}`);
+            return undefined;
+        };
+        const entry = subject.builtin
+            ? undefined
+            : org.hosting.entries.find((e) => e.key === subject.id);
+        if (!subject.builtin && !entry?.uses?.auth)
+            return { required: false };
+        const recorded = context.recordedIds();
+        if (subject.builtin === 'agora') {
+            // A static SPA: a public client named `<production client>-stage` (production's is `agora`), redirect URIs
+            // on the stage host only. No broker entry, app key or cookie secret exist for it.
+            const { zitadel } = this.ports;
+            if (!org.domain)
+                return why('the company has no domain, so stage has no host to sign in at');
+            const zitadelOrgId = recorded.zitadel_org;
+            if (!zitadelOrgId)
+                return why('no sign-in organisation is recorded');
+            const host = stageHostname(org.domain, subject.id);
+            return {
+                required: true,
+                public: true,
+                spec: {
+                    clientName: `${subject.id}-stage`,
+                    organizationId: zitadelOrgId,
+                    redirectUris: [`https://${host}/callback`],
+                    postLogoutRedirectUris: [`https://${host}/`],
+                    origins: [`https://${host}`],
+                },
+                findClient: async (name) => {
+                    const projectId = await this.ensureZitadelProject(org, zitadelOrgId, context);
+                    const { apps } = await zitadel.listApps(zitadelOrgId, projectId);
+                    const hit = apps.find((a) => a.name === name && a.state !== 'APP_STATE_REMOVED');
+                    return hit
+                        ? { appId: hit.id, ...(hit.clientId ? { clientId: hit.clientId } : {}) }
+                        : undefined;
+                },
+                createClient: async (spec) => {
+                    const projectId = await this.ensureZitadelProject(org, zitadelOrgId, context);
+                    return zitadel.createOidcApp(zitadelOrgId, projectId, {
+                        name: spec.clientName,
+                        appType: 'web',
+                        redirectUris: spec.redirectUris,
+                        postLogoutRedirectUris: spec.postLogoutRedirectUris,
+                    });
+                },
+            };
+        }
+        const wanted = entry
+            ? wantedBrokerEntry(org, entry, recorded)
+            : wantedBouleBrokerEntry(org, recorded);
+        if ('missing' in wanted)
+            return why("production's sign-in is not recorded yet");
+        const { broker, heldKeys, zitadel } = this.ports;
+        if (!broker)
+            return why('the broker port is not wired');
+        if (typeof heldKeys?.put !== 'function')
+            return why('the held keys cannot put');
+        if (!org.domain)
+            return why('the company has no domain, so stage has no host to sign in at');
+        const zitadelOrgId = recorded.zitadel_org;
+        if (!zitadelOrgId)
+            return why('no sign-in organisation is recorded');
+        const clientKey = subject.id;
+        const host = stageHostname(org.domain, subject.id);
+        const put = heldKeys.put;
+        const ref = sharedSecretRef(org.id, `stage-auth-app-key-${subject.id}`);
+        const want = wanted.want;
+        return {
+            required: true,
+            spec: {
+                clientName: `${clientKey}-stage`,
+                organizationId: want.organizationId,
+                redirectUris: [`https://${host}/auth/callback`, desktopCallbackUri(host)],
+                postLogoutRedirectUris: postLogoutUrisFor([host]),
+                brokerName: `${want.name}-stage`,
+                origins: [`https://${host}`],
+                from: want.from,
+                registration: want.registration,
+                ...(want.emailLink === undefined ? {} : { emailLink: want.emailLink }),
+            },
+            findClient: async (name) => {
+                const projectId = await this.ensureZitadelProject(org, zitadelOrgId, context);
+                const { apps } = await zitadel.listApps(zitadelOrgId, projectId);
+                const hit = apps.find((a) => a.name === name && a.state !== 'APP_STATE_REMOVED');
+                return hit
+                    ? { appId: hit.id, ...(hit.clientId ? { clientId: hit.clientId } : {}) }
+                    : undefined;
+            },
+            createClient: async (spec) => {
+                const projectId = await this.ensureZitadelProject(org, zitadelOrgId, context);
+                return zitadel.createOidcApp(zitadelOrgId, projectId, {
+                    name: spec.clientName,
+                    appType: 'web',
+                    redirectUris: spec.redirectUris,
+                    postLogoutRedirectUris: spec.postLogoutRedirectUris,
+                });
+            },
+            writeBrokerEntry: async (entryWant, appKey) => {
+                await writeBrokerEntry(broker, {
+                    want: { ...entryWant, replaces: null },
+                    appKey,
+                    previous: null,
+                });
+            },
+            held: {
+                ref,
+                resolve: async () => (await heldKeys.resolve(ref)) ?? null,
+                put: (value) => put.call(heldKeys, ref, value),
+            },
+        };
+    }
     async coolifyApp(action, org, context) {
         const recordedAppId = context.recordedIds()[`coolify:app:${action.key}`];
         if (action.desired.enabled === false) {
@@ -3656,7 +3963,7 @@ export class FoundryStepExecutor {
             throw new Error(`coolify:app for ${org.slug}: no hosting entry for ${action.key}`);
         // `planApp` blocks a `repo: null` entry at plan time; reaching here with
         // one means a stale or hand-built plan.
-        if (entry.repo === null) {
+        if (entry.repo === null && entry.image === undefined) {
             throw new Error(`coolify:app for ${org.slug}: entry '${entry.key}' has no repo`);
         }
         const appRepo = entry.repo;
@@ -3745,35 +4052,55 @@ export class FoundryStepExecutor {
         }
         else {
             const server = await this.resolveServer(org, context);
-            const githubAppUuid = await this.githubAppUuidFor(org, appRepo, context.recordedIds());
-            if (isServerWorkspace(entry)) {
-                pinnedCommit =
-                    entry.liveCommit ?? (await this.workspaceCommit(org, entry, server.uuid, context));
+            if (entry.image) {
+                // A built image: pulled by digest, nothing to build. Coolify never deploys it by itself on create.
+                const created = await this.ports.coolify.createDockerImageApplication({
+                    project_uuid: projectUuid,
+                    server_uuid: server.uuid,
+                    environment_name: environment.name,
+                    environment_uuid: environment.uuid,
+                    ...entryImageFields(entry.image),
+                    // Coolify needs a port to create the app; a helper with none listens on none, so 80 is only its label.
+                    ports_exposes: String(entry.port ?? 80),
+                    name: appName,
+                    description: `${org.slug}'s ${entry.key} app, run from a built image`,
+                    instant_deploy: false,
+                });
+                appId = created.uuid;
+                have = appSettingsOf(entry);
+                haveDomains = wantDomains;
+            }
+            else {
+                const githubAppUuid = await this.githubAppUuidFor(org, appRepo, context.recordedIds());
+                if (isServerWorkspace(entry)) {
+                    pinnedCommit =
+                        entry.liveCommit ?? (await this.workspaceCommit(org, entry, server.uuid, context));
+                }
+                const created = await this.ports.coolify.createGithubAppApplication({
+                    is_preview_deployments_enabled: false,
+                    project_uuid: projectUuid,
+                    server_uuid: server.uuid,
+                    environment_name: environment.name,
+                    environment_uuid: environment.uuid,
+                    github_app_uuid: githubAppUuid,
+                    git_repository: appRepo,
+                    git_branch: entry.branch,
+                    build_pack: entry.buildPack,
+                    name: appName,
+                    autogenerate_domain: false,
+                    // A static site is served by Coolify's own web server on port 80.
+                    ports_exposes: isStatic ? '80' : entry.port === null ? undefined : String(entry.port),
+                    is_auto_deploy_enabled: appSettingsOf(entry).autoDeploy,
+                    // Also the folder a static entry serves: Coolify's static build
+                    // copies `base_directory`, and reads `publish_directory` only for a
+                    // built app.
+                    base_directory: entry.folder === null ? undefined : `/${entry.folder}`,
+                });
+                appId = created.uuid;
+                // Create sent every setting, so nothing is left to patch.
+                have = appSettingsOf(entry);
+                haveDomains = wantDomains;
             }
-            const created = await this.ports.coolify.createGithubAppApplication({
-                is_preview_deployments_enabled: false,
-                project_uuid: projectUuid,
-                server_uuid: server.uuid,
-                environment_name: environment.name,
-                environment_uuid: environment.uuid,
-                github_app_uuid: githubAppUuid,
-                git_repository: appRepo,
-                git_branch: entry.branch,
-                build_pack: entry.buildPack,
-                name: appName,
-                autogenerate_domain: false,
-                // A static site is served by Coolify's own web server on port 80.
-                ports_exposes: isStatic ? '80' : entry.port === null ? undefined : String(entry.port),
-                is_auto_deploy_enabled: appSettingsOf(entry).autoDeploy,
-                // Also the folder a static entry serves: Coolify's static build
-                // copies `base_directory`, and reads `publish_directory` only for a
-                // built app.
-                base_directory: entry.folder === null ? undefined : `/${entry.folder}`,
-            });
-            appId = created.uuid;
-            // Create sent every setting, so nothing is left to patch.
-            have = appSettingsOf(entry);
-            haveDomains = wantDomains;
         }
         // Patch what differs from what the app has. A crash before the marker is
         // recorded below leaves the old one, so the retry patches the same
@@ -3793,6 +4120,13 @@ export class FoundryStepExecutor {
             patch.is_preview_deployments_enabled = false;
         if (pinnedCommit)
             patch.git_commit_sha = pinnedCommit;
+        // A new image reference reaches a live app: the digest is patched and the app deploys below.
+        const imageRef = entry.image ? entryImageRef(entry.image) : null;
+        const imageChanged = entry.image !== undefined &&
+            existing !== null &&
+            context.recordedIds()[appImageAppliedScopeKey(entry.key)] !== imageRef;
+        if (entry.image && imageChanged)
+            Object.assign(patch, entryImageFields(entry.image));
         // #543: the health-check quartet too, every run -- the same reason
         // Archon's own doc comment gives (without one, Coolify's rolling update
         // has nothing to wait on and stops the old container immediately). The
@@ -3841,7 +4175,8 @@ export class FoundryStepExecutor {
         if (Object.keys(patch).length > 0)
             await this.ports.coolify.updateApplication(appId, patch);
         // The container builds and listens from these only at its next deploy.
-        const settingsNeedDeploy = Boolean(patch.base_directory ||
+        const settingsNeedDeploy = Boolean(imageChanged ||
+            patch.base_directory ||
             patch.ports_exposes ||
             patch.domains !== undefined ||
             patch.custom_internal_name ||
@@ -3911,7 +4246,10 @@ export class FoundryStepExecutor {
                     entryRoutesMarker(org, context.recordedIds())
                 ? publicHealthCheck(org, context.recordedIds(), hostname, healthPath)
                 : { kind: 'deployment-only' }, runtime, runtime.sleep ?? defaultSleep, `coolify:app:${entry.key}`, `${org.slug}'s ${entry.key === APP_ENTRY_KEY ? 'app' : `${entry.key} app`} stays at its previous deploy`);
-            await recordBuiltCommit(this.ports.coolify, { appId: appId, deploymentUuid: built.deploymentUuid, name: entry.key }, (key, value) => context.recordScopeId(key, value));
+            // An image app has no commit to read: its digest is the build.
+            if (!entry.image) {
+                await recordBuiltCommit(this.ports.coolify, { appId: appId, deploymentUuid: built.deploymentUuid, name: entry.key }, (key, value) => context.recordScopeId(key, value));
+            }
         }
         else if ((appEnv.changed || dbNeedsRestart) && existing) {
             await this.ports.coolify.restart(appId);
@@ -3923,6 +4261,8 @@ export class FoundryStepExecutor {
         context.recordScopeId(settingsKey, JSON.stringify({ ...want, port: want.port ?? have.port }));
         context.recordScopeId(domainsKey, JSON.stringify(wantDomains));
         context.recordScopeId(labelsKey, wantLabelsHash);
+        if (imageRef)
+            context.recordScopeId(appImageAppliedScopeKey(entry.key), imageRef);
         if (pinnedCommit && pinnedCommit === entry.liveCommit) {
             context.recordScopeId(wsKey.liveCommit(entry.key), pinnedCommit);
         }
@@ -4849,11 +5189,27 @@ export class FoundryStepExecutor {
     async ensureBridgeSecret(appId) {
         return this.mintIfAbsent(appId, BOULE_BRIDGE_SECRET_ENV, 32);
     }
-    async mintIfAbsent(appId, key, bytes) {
+    /**
+     * `minLength`, when given, also counts a present-but-empty value as not set -- the same guard
+     * {@link ensureAuthAppKey} already applies for `AUTH_APP_KEY`, now reusable here instead of a
+     * third, bare copy of this check (foundry#970, thermo note 1 in #957). Omitted, the three existing
+     * callers below keep their original behaviour.
+     */
+    async mintIfAbsent(appId, key, bytes, minLength) {
         const envs = await this.ports.coolify.listEnvs(appId);
-        if (envs.some((e) => e.key === key && !e.is_preview))
-            return null;
-        return randomBytes(bytes).toString('base64url');
+        const already = envs.some((e) => e.key === key &&
+            !e.is_preview &&
+            (minLength === undefined || (e.value ?? '').length >= minLength));
+        return already ? null : randomBytes(bytes).toString('base64url');
+    }
+    /**
+     * Every company's Boule, F3/#970: `NATIVE_BUILD_KEY` is what Boule presents to Archon's
+     * native-build route (estate#262) to ask it to dispatch `build-app.yml`. Minted once, like
+     * {@link ensureAuthAppKey}, and never rotated; a present-but-empty value (the bug
+     * `mintNativeBuildKey`'s own read-then-generate had, see #957) is treated as not set.
+     */
+    async ensureNativeBuildKey(appId) {
+        return this.mintIfAbsent(appId, NATIVE_BUILD_KEY_ENV, NATIVE_BUILD_KEY_BYTES, 1);
     }
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
@@ -7347,6 +7703,12 @@ export class FoundryStepExecutor {
             this.handledSecrets.add(ownerSeedSecret);
             envs.push({ key: BOULE_OWNER_SEED_SECRET_ENV, value: ownerSeedSecret });
         }
+        // The key Boule presents to Archon's native-build route, for every org's Boule (foundry#970).
+        const nativeBuildKey = await this.ensureNativeBuildKey(app.appId);
+        if (nativeBuildKey) {
+            this.handledSecrets.add(nativeBuildKey);
+            envs.push({ key: NATIVE_BUILD_KEY_ENV, value: nativeBuildKey });
+        }
         // Held, minted once (C3). Compared with the live value so a changed one restarts the app.
         const credentialEnvs = [];
         let archonPushedAt = null;
@@ -7407,6 +7769,7 @@ export class FoundryStepExecutor {
                 peerPassword,
                 bridgeSecret,
                 ownerSeedSecret,
+                nativeBuildKey,
                 ...credentialEnvs.map((credential) => credential.value),
                 ...grants.secrets,
             ].filter((v) => v !== null);
@@ -7446,6 +7809,7 @@ export class FoundryStepExecutor {
                 peerPassword !== null ||
                 bridgeSecret !== null ||
                 ownerSeedSecret !== null ||
+                nativeBuildKey !== null ||
                 secretsNotRestarted ||
                 registrarUnstarted ||
                 dbPush.changed ||
@@ -10782,6 +11146,50 @@ export class FoundryStepExecutor {
                 case 'cloudflare:bg-gate':
                     await this.accessPort().deleteGate(target.id);
                     return;
+                case 'files:bg-keys':
+                case 'ai:bg-keys': {
+                    // Stage's own keys (`{ids, refs}`) in stage's own organisation, revoked before the organisation goes.
+                    const { ids } = JSON.parse(target.id);
+                    // The organisation foundry recorded; a record from before per-subject names has the shared one.
+                    const stageOrgId = recordedIds[stageServiceKey(target.key, 'org')] ?? `${org.id}-stage`;
+                    if (target.system === 'files') {
+                        const files = await this.filesPort();
+                        for (const id of ids)
+                            await files.revokeOrganisationKey(stageOrgId, id);
+                    }
+                    else {
+                        const ai = await this.aiPort();
+                        // REVOKE SEAM (ai#157): a port with no `revokeKey` leaves it to go with the organisation.
+                        if (ai.revokeKey)
+                            for (const id of ids)
+                                await ai.revokeKey(stageOrgId, id);
+                    }
+                    return;
+                }
+                case 'files:bg-org':
+                case 'ai:bg-org': {
+                    // The organisation id foundry recorded when it made it (named for its subject).
+                    const stageOrgId = target.id;
+                    const port = target.system === 'files' ? await this.filesPort() : await this.aiPort();
+                    if (!port.deleteOrganisation) {
+                        throw new Error(`${target.system}:bg-org for ${org.slug}: the ${target.system} port cannot delete an organisation, so ${stageOrgId} stays`);
+                    }
+                    await port.deleteOrganisation(stageOrgId);
+                    return;
+                }
+                case 'jobs:bg-keys':
+                    // A jobs project's keys go with the project.
+                    return;
+                case 'jobs:bg-org': {
+                    // The name recorded when the project was made; a record from before that has the shared `<slug>-stage`.
+                    const projectName = recordedIds[stageServiceKey(target.key, 'name')] ?? `${org.slug}-stage`;
+                    const scheduler = await this.jobsPort(org);
+                    if (!scheduler.deleteProject) {
+                        throw new Error(`jobs:bg-org for ${org.slug}: the jobs port cannot delete a project, so ${projectName} stays`);
+                    }
+                    await scheduler.deleteProject(projectName);
+                    return;
+                }
                 case 'ai:key': {
                     // F6a: an entry's key (`<orgId>:<entry>`). REVOKE SEAM (ai#157): a
                     // port with no `revokeKey` leaves it live until it expires.
@@ -10860,6 +11268,26 @@ export class FoundryStepExecutor {
                             throw error;
                     }
                     return;
+                case 'coolify:bg-broker': {
+                    // Stage's broker entry (`{name, organizationId}`): taken out of AUTH_APPS with its key.
+                    const broker = this.ports.broker;
+                    if (!broker) {
+                        throw new Error(`coolify:bg-broker for ${org.slug}: the broker port is not wired, cannot remove ${target.key}`);
+                    }
+                    const { name, organizationId } = JSON.parse(target.id);
+                    await removeBrokerEntry(broker, { name, organizationId });
+                    return;
+                }
+                case 'zitadel:bg-client': {
+                    // Stage's own sign-in client, in production's sign-in organisation and project.
+                    const zitadelOrgId = recordedIds.zitadel_org;
+                    const projectId = recordedIds.zitadel_project;
+                    if (!zitadelOrgId || !projectId) {
+                        throw new Error(`zitadel:bg-client for ${org.slug}: no ZITADEL org/project recorded, cannot delete ${target.key}`);
+                    }
+                    await this.ports.zitadel.deleteApp(zitadelOrgId, projectId, target.id);
+                    return;
+                }
                 case 'cloudflare:bg-access':
                     await this.accessPort().deleteAccessApp(target.id);
                     return;
@@ -11029,3 +11457,10 @@ export async function setOidcAppLoginBaseUri(zitadel, orgId, projectId, appId, l
             throw error;
     }
 }
+/** A recorded stage service key (`bg.<id>.stage<service>keys` or `...org`) with its last part swapped. */
+function stageServiceKey(key, part) {
+    const match = /^(bg\..+\.stage(?:files|ai|jobs))(?:keys|org)$/.exec(key);
+    if (!match?.[1])
+        throw new Error(`stage service key ${key} is not one`);
+    return `${match[1]}${part}`;
+}