@wtfalch/foundry 0.15.0 → 0.16.1

package/dist/plan/executor.js

@@ -1,15 +1,19 @@
 import { randomBytes } from 'node:crypto';
 import { URL } from 'node:url';
 import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
-import { APP_ENTRY_KEY, appEntry } from '../org.js';
-import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_ORG_SCOPE_KEY, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
+import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, ownerMailboxRecorded, ownerMailboxes, } from '../org.js';
+import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { MAS_IMAGE, MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
+import { CHAT_REPO, CHAT_SERVICE_DOCKERFILE, CHAT_SERVICE_PORT, CHAT_SYNAPSE_DOCKERFILE, CHAT_SYNAPSE_PORT, chatInternalNames, chatMasConfigYaml, chatServiceEnvs, chatSynapseHomeserverYaml, chatUpstreams, } from './chat-matrix.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
-import { appHostname, entryHostnames, tunnelDnsHostnames, tunnelIngressHostnames, } from './hostnames.js';
+import { AI_ENTRY_RENEW_WINDOW_DAYS, entryAiAppliedScopeKey, entryAiClampedScopeKey, entryAiExpiresScopeKey, entryAiPendingExpiresScopeKey, entryAiRetiredScopeKey, entryAiUndeliveredScopeKey, entryAiUnrevokedScopeKey, entryAiWebhookPendingScopeKey, entryAiWrittenScopeKey, parseIdList, } from './entry-ai-key.js';
+import { FILES_AGORA_KEY_SCOPE_KEY, FILES_AGORA_UNDELIVERED_SCOPE_KEY, FILES_KEY_DAYS, FILES_KEY_RENEW_WINDOW_DAYS, FILES_ORG_OWNER_SCOPE_KEY, FILES_ROOT_EXPIRES_SCOPE_KEY, FILES_ROOT_PREVIOUS_SCOPE_KEY, FILES_ROOT_UNDELIVERED_SCOPE_KEY, FILES_ROOT_UNREVOKED_SCOPE_KEY, entryFilesAppliedScopeKey, entryFilesExpiresScopeKey, entryFilesMinterScopeKey, entryFilesPendingExpiresScopeKey, entryFilesRetiredScopeKey, entryFilesUndeliveredScopeKey, entryFilesUnrevokedScopeKey, entryFilesWrittenScopeKey, filesOwnerUserId, parseIdList as parseFilesIdList, } from './entry-files-key.js';
+import { appHostname, coolifyDomains, entryHostnames, tunnelDnsHostnames, tunnelIngressHostnames, } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY, loginBindingState, loginHostClientIds, pendingRemovalHosts, pendingRemovalState, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.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, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, } from './platform-diff.js';
+import { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec, entryProxyLabels, sameLabelSets, } from './proxy-labels.js';
 /**
  * #274 fix round 4: bridges `@wtfalch/providers`' real `ZitadelClient.
  * listApps` -- a plain array, with no `loginBaseUri` or completeness signal
@@ -36,8 +40,8 @@ export function adaptZitadelListApps(client) {
 // ---------------------------------------------------------------------------
 /**
  * Thrown by name for a step this executor deliberately does not implement:
- * chat (no admin API exists yet), plus moving the issuer onto or off the
- * org's domain (built, but not in v1 — domain verification and passkey
+ * moving chat or the issuer onto or off the org's domain (chat's re-key is
+ * not built; the issuer's is built, but not in v1 — domain verification and passkey
  * invalidation need their own design). Never carries a token, secret or key
  * (task brief: "errors carry the step and the provider's status only").
  */
@@ -274,6 +278,15 @@ const CMS_DATABASE_SCOPE_KEY = 'coolify_cms_database';
  * `resend_mail_domain`.
  */
 const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
+/**
+ * A `TXT` record's leading tag, lowercased: `v=spf1`, `v=dkim1`, `v=dmarc1`,
+ * or for an untagged value its first word. Cloudflare may hand content back
+ * wrapped in quotes, so those are dropped first.
+ */
+function txtRecordTag(content) {
+    const bare = content.trim().replace(/^"/, '').trimStart();
+    return (bare.split(/[\s;]/, 1)[0] ?? '').toLowerCase();
+}
 /**
  * #235: the Coolify app running `cloudflared` for this org's own tunnel --
  * one connector per org tunnel (Decided, William, 2026-10-01), the same
@@ -397,19 +410,8 @@ function parseTunnelPreviousIds(recorded) {
 function tunnelPreviousIdsState(ids) {
     return [...ids].sort().join(',');
 }
-/**
- * #162: the owner's own mailbox, created once inside `coolify:mail` after
- * `applyOrgMail` succeeds, alongside {@link MAIL_DOMAIN_SCOPE_KEY} -- another
- * flat scope id for the same reason, no `:`. Recorded with the address
- * itself (not just a boolean) so a future step could read it back the same
- * way {@link MAIL_DOMAIN_SCOPE_KEY} lets `ensureAppLettermintMail` read the
- * domain back; `ensureOwnerMailbox` only ever checks that this key is set at
- * all before deciding whether to call `MailPort.createMailbox` again.
- * `plan/diff.ts` keeps its own copy of this literal (`MAIL_OWNER_MAILBOX_SCOPE_KEY`
- * there) rather than importing it, the same restated-not-shared rule this
- * file's own `LOG_DIR` doc comment names for `diff.ts`.
- */
-const MAIL_OWNER_MAILBOX_SCOPE_KEY = 'mail_owner_mailbox';
+/** The role on the org's `<slug>-messaging` project that opens /_chat/manage. */
+const CHAT_ADMIN_ROLE = 'chat.admin';
 /**
  * #149 review finding: `MailPort.hasOrgRelay` only confirms Stalwart's route
  * holds *a* secret, not that it is the one {@link FoundryStepExecutor
@@ -418,7 +420,7 @@ const MAIL_OWNER_MAILBOX_SCOPE_KEY = 'mail_owner_mailbox';
  * project that has since been lost and reprovisioned under the same name
  * would otherwise read as healthy. Recorded as `<project id>@<mail domain>`
  * right after a successful `MailPort.applyOrgRelay`, a flat scope id (no
- * `:`) the same way {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is. The domain half
+ * `:`) the same way `mail_owner_mailbox` is. The domain half
  * also catches a domain switch: the healthy branch never calls
  * `applyOrgRelay` again, so without this the Stalwart route would stay
  * restricted to the org's previous domain forever.
@@ -440,6 +442,12 @@ const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
 const AI_KEY_UNDELIVERED_SCOPE_KEY = 'ai_key_undelivered';
 /** How many times `aiKey` tries `deliverSecret` before giving up. */
 const AI_KEY_DELIVERY_ATTEMPTS = 3;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** What a failed files call says about itself: its HTTP status, never its message, which can echo a value. */
+function filesErrorCause(error) {
+    const status = error?.status;
+    return typeof status === 'number' ? `HTTP ${status}` : 'no HTTP status';
+}
 /**
  * #173: the id of a jobs project `jobsRegistration` has registered but not
  * yet delivered the credentials of, a flat scope id (no `:`). `serviceIds` is
@@ -491,6 +499,25 @@ const CALLS_SECRET_ENV_KEYS = {
     masRsaKeyPem: 'CALLS_MATRIX_MAS_RSA_KEY_PEM',
     masEcKeyPem: 'CALLS_MATRIX_MAS_EC_KEY_PEM',
 };
+/**
+ * `coolifyChat`'s flat scope ids, for the same reason as the calls stack's
+ * above: this step's one auto-recorded `resourceId` (under
+ * `coolify:chat:<orgId>`) is the MAS app's id, the one every secret lives on.
+ */
+const CHAT_SYNAPSE_SCOPE_KEY = 'coolify_chat_synapse';
+const CHAT_SERVICE_SCOPE_KEY = 'coolify_chat_service';
+const CHAT_SYNAPSE_DB_SCOPE_KEY = 'coolify_chat_synapse_database';
+const CHAT_MAS_DB_SCOPE_KEY = 'coolify_chat_mas_database';
+const CHAT_SERVICE_DB_SCOPE_KEY = 'coolify_chat_service_database';
+/** {@link CALLS_SECRET_ENV_KEYS}' counterpart on chat's own MAS app. */
+const CHAT_SECRET_ENV_KEYS = {
+    masSynapseSharedSecret: 'CHAT_MATRIX_MAS_SYNAPSE_SHARED_SECRET',
+    masClientId: 'CHAT_MATRIX_MAS_CLIENT_ID',
+    masClientSecret: 'CHAT_MATRIX_MAS_CLIENT_SECRET',
+    masEncryptionKey: 'CHAT_MATRIX_MAS_ENCRYPTION_KEY',
+    masRsaKeyPem: 'CHAT_MATRIX_MAS_RSA_KEY_PEM',
+    masEcKeyPem: 'CHAT_MATRIX_MAS_EC_KEY_PEM',
+};
 /** `FROM ${MAS_IMAGE}` plus the entry command its published image needs (chat's own `MAS_DOCKERFILE`, same reason: no arguments by default). */
 const CALLS_MAS_DOCKERFILE = [
     `FROM ${MAS_IMAGE}`,
@@ -564,7 +591,12 @@ export class FoundryStepExecutor {
             case 'cloudflare:ratelimit':
                 return this.cloudflareRateLimit(org);
             case 'files:organisation':
-                return this.filesOrganisation(action, org);
+                return this.filesOrganisation(action, org, context);
+            case 'files:key':
+                // The org's own key is keyed `<orgId>`, an entry's `<orgId>:<entry>` (F6b).
+                return action.key.includes(':')
+                    ? this.filesEntryKey(action, org, context)
+                    : this.filesRootKey(action, org, context);
             case 'files:storage':
                 return this.filesStorage(action, org);
             case 'ai:organisation':
@@ -572,13 +604,16 @@ export class FoundryStepExecutor {
             case 'ai:budget':
                 return this.aiBudget(action, org);
             case 'ai:key':
-                return this.aiKey(action, org, context);
+                // The org's own key is keyed `<orgId>`, an entry's `<orgId>:<entry>` (F6a).
+                return action.key.includes(':')
+                    ? this.aiEntryKey(action, org, context)
+                    : this.aiKey(action, org, context);
             case 'coolify:mail':
                 return this.coolifyMail(action, org, context);
             case 'coolify:mail-copy':
                 return this.mailCopy(org, context);
             case 'coolify:chat':
-                throw new NotBuiltError(`coolify:chat for ${org.slug}`, "chat's per-org Synapse+MAS has no admin API yet; tracked at https://github.com/wtfalch/chat/issues/40");
+                return this.coolifyChat(action, org, context);
             case 'cms:site':
                 return this.cmsSite(action, org, context);
             case 'coolify:agora':
@@ -701,7 +736,7 @@ export class FoundryStepExecutor {
      * `plan/diff.ts`'s `planOwner`: invites the org's owner into its ZITADEL
      * org by email. Never logs, returns or throws the email itself -- only the
      * invited user id, handed back as `resourceId` so `runSteps` records it
-     * under `zitadel:owner:<orgId>`, which is exactly what makes the next
+     * under `zitadel:owner:<orgId>:<email>`, which is exactly what makes the next
      * `plan()` call idempotent (`planOwner` plans nothing once that key is
      * recorded).
      */
@@ -715,6 +750,18 @@ export class FoundryStepExecutor {
             familyName: action.desired.familyName,
             email: action.desired.email,
         });
+        // An owner invited after chat was built never reaches `coolifyChat`
+        // again, so the role is granted here once the messaging project exists.
+        const messagingProjectId = context.recordedIds()[ZITADEL_MESSAGING_PROJECT_SCOPE_KEY];
+        if (org.chat.enabled && messagingProjectId) {
+            await this.ports.zitadel.ensureProjectRole(zitadelOrgId, messagingProjectId, {
+                key: CHAT_ADMIN_ROLE,
+                displayName: 'Chat admin',
+            });
+            await this.ports.zitadel.grantProjectRoles(zitadelOrgId, userId, messagingProjectId, [
+                CHAT_ADMIN_ROLE,
+            ]);
+        }
         return { resourceId: userId };
     }
     /**
@@ -1161,7 +1208,7 @@ export class FoundryStepExecutor {
                 git_branch: entry.branch,
                 build_pack: entry.buildPack,
                 name: appNameFor(org, entry),
-                domains: names.length > 0 ? names.join(',') : undefined,
+                domains: names.length > 0 ? coolifyDomains(names) : undefined,
                 autogenerate_domain: names.length > 0 ? undefined : 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),
@@ -1192,10 +1239,31 @@ export class FoundryStepExecutor {
         // here (rule 3). The internal name is set after create, as the calls
         // stack's apps do.
         if (JSON.stringify(names) !== JSON.stringify(haveNames))
-            patch.domains = names.join(',');
+            patch.domains = coolifyDomains(names);
         if (names.length === 0 && (!existing || patch.domains !== undefined)) {
             patch.custom_internal_name = appNameFor(org, entry);
         }
+        // A `*` entry's proxy labels: Coolify takes `custom_labels` base64 encoded
+        // and uses them instead of the labels it generates from `domains`. Rule 4:
+        // decided from the live app. A created app has none, so it is always
+        // patched; a live app is patched when its labels differ from the wanted
+        // set (a hand edit included). Only when Coolify does not report
+        // `custom_labels` does the recorded hash decide. The hash is recorded
+        // below, after the redeploy, so a failed run repeats this.
+        const labelsKey = appLabelsAppliedScopeKey(entry.key);
+        const haveLabelsHash = context.recordedIds()[labelsKey];
+        const labelSpec = entryLabelSpec(org, entry, haveLabelsHash !== undefined);
+        const wantLabelsHash = labelSpec ? entryLabelHash(labelSpec) : undefined;
+        const wantLabels = labelSpec ? entryProxyLabels(appId, labelSpec) : undefined;
+        const liveLabels = existing ? live?.custom_labels : undefined;
+        const labelsDiffer = wantLabels !== undefined &&
+            (!existing ||
+                (liveLabels !== undefined
+                    ? !sameLabelSets(Buffer.from(liveLabels ?? '', 'base64').toString('utf8'), wantLabels)
+                    : wantLabelsHash !== haveLabelsHash));
+        if (wantLabels !== undefined && labelsDiffer) {
+            patch.custom_labels = Buffer.from(wantLabels).toString('base64');
+        }
         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.
@@ -1203,7 +1271,8 @@ export class FoundryStepExecutor {
             patch.publish_directory ||
             patch.ports_exposes ||
             patch.domains !== undefined ||
-            patch.custom_internal_name);
+            patch.custom_internal_name ||
+            patch.custom_labels);
         // The database plans before the app (`diff.ts`'s `computePlanDetail`,
         // hosting-wiring campaign) so that, on the same apply, the database's
         // resource id is already recorded by the time this runs -- but this also
@@ -1247,6 +1316,8 @@ export class FoundryStepExecutor {
         // one and `planApp` reports it instead of planning it.
         context.recordScopeId(settingsKey, JSON.stringify({ ...want, port: want.port ?? have.port }));
         context.recordScopeId(domainsKey, JSON.stringify(names));
+        if (wantLabelsHash)
+            context.recordScopeId(labelsKey, wantLabelsHash);
         context.recordScopeId(appEnvAppliedScopeKey(entry.key), appEnv.applied);
         if (entry.uses?.auth) {
             context.recordScopeId(entryAuthEnvAppliedScopeKey(entry.key), appEnv.authApplied);
@@ -1431,9 +1502,9 @@ export class FoundryStepExecutor {
      * `zitadel:issuer` (`AUTH_ORGANIZATION_ID`), `zitadel:owner`
      * (`OWNER_USER_ID`, gap P3) and every `zitadel:app` step
      * (`AUTH_CLIENT_ID`), all ordered before `coolify:app` for exactly this
-     * reason. `AUTH_APP_KEY` (#206 -- which broker an org's app registers with
-     * is its own design question, left out of #204's own "How" rather than
-     * guessed) is out of scope here (task brief). `DATABASE_URL_OWNER`/
+     * reason. `AUTH_APP_KEY` is pushed here too, for an entry that declares
+     * `uses: [auth]` (`ensureAuthAppKey`); the host's `BrokerPort` decides which
+     * broker the org's app registers with (#206). `DATABASE_URL_OWNER`/
      * `DATABASE_URL` are pushed by `pushDatabaseUrl` instead, not here --
      * that call runs only once the `app` entry's `database` is declared and
      * provisioned, where this one is unconditional (#239).
@@ -1477,7 +1548,10 @@ export class FoundryStepExecutor {
         // them its own owner in authz on first sign-in. `runSteps` records this
         // under the same `system:kind:key` shape every step's `resourceId` uses
         // (`zitadelOwner`'s own doc comment), not a scope id.
-        const ownerUserId = recorded[`zitadel:owner:${org.id}`];
+        const firstOwner = org.owners[0];
+        const ownerUserId = firstOwner
+            ? recorded[`zitadel:owner:${org.id}:${firstOwner.email.toLowerCase()}`]
+            : undefined;
         if (ownerUserId)
             envs.push({ key: 'OWNER_USER_ID', value: ownerUserId });
         // Idempotent the same way `pushDatabaseUrl`'s credential is treated:
@@ -2104,7 +2178,7 @@ export class FoundryStepExecutor {
             git_branch: 'main',
             build_pack: 'dockerfile',
             name: input.name,
-            domains: input.domain,
+            domains: coolifyDomains([input.domain]),
             dockerfile_location: input.dockerfileLocation,
         });
         return { appId: created.uuid, existed: false };
@@ -2271,14 +2345,19 @@ export class FoundryStepExecutor {
      * by `coolifyCallsService` (#145) for the calls service app itself -- the
      * same find-by-name-then-start-or-create shape applies unchanged.
      */
-    async findOrCreateCallsApp(name, environmentId, create) {
+    async findOrCreateCallsApp(name, environmentId, create, options = {}) {
         const existing = await this.ports.coolify.findApplicationByName(name, {
             environmentIds: [environmentId],
         });
         if (existing) {
-            const live = await this.ports.coolify.getApplication(existing.uuid);
-            if (!isRunningOrStarting(live.status)) {
-                await this.ports.coolify.raw('POST', `/applications/${existing.uuid}/start`);
+            // `startIfStopped: false` (chat): the caller writes the app's config
+            // first and lets its own deploy start it, so a stopped app is never
+            // started with config that is not there yet.
+            if (options.startIfStopped !== false) {
+                const live = await this.ports.coolify.getApplication(existing.uuid);
+                if (!isRunningOrStarting(live.status)) {
+                    await this.ports.coolify.raw('POST', `/applications/${existing.uuid}/start`);
+                }
             }
             return { appId: existing.uuid, existed: true };
         }
@@ -2324,10 +2403,10 @@ export class FoundryStepExecutor {
      * still treated as "mint fresh", since MAS's shared secret and Synapse's
      * copy of it must always agree.
      */
-    async ensureCallsMatrixSecrets(masAppId) {
+    async ensureCallsMatrixSecrets(masAppId, secretEnvKeys = CALLS_SECRET_ENV_KEYS) {
         const envs = await this.ports.coolify.listEnvs(masAppId);
         const read = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
-        const fields = Object.entries(CALLS_SECRET_ENV_KEYS);
+        const fields = Object.entries(secretEnvKeys);
         const existing = {};
         for (const [field, envKey] of fields) {
             const value = read(envKey);
@@ -2365,6 +2444,209 @@ export class FoundryStepExecutor {
             });
         }
     }
+    // ---- chat -----------------------------------------------------------------
+    /**
+     * Creates the `chat.admin` role on the org's messaging project and grants
+     * it to each owner whose invite is recorded (`zitadel:owner:<orgId>:<email>`,
+     * email lowercased).
+     */
+    async ensureChatAdmins(org, zitadelOrgId, projectId, recorded) {
+        await this.ports.zitadel.ensureProjectRole(zitadelOrgId, projectId, {
+            key: CHAT_ADMIN_ROLE,
+            displayName: 'Chat admin',
+        });
+        for (const owner of org.owners) {
+            const userId = recorded[`zitadel:owner:${org.id}:${owner.email.toLowerCase()}`];
+            if (userId) {
+                await this.ports.zitadel.grantProjectRoles(zitadelOrgId, userId, projectId, [
+                    CHAT_ADMIN_ROLE,
+                ]);
+            }
+        }
+    }
+    /**
+     * `plan/diff.ts`'s `planChat`: the org's chat stack at level 1 -- three
+     * Coolify-managed Postgres databases (Synapse, MAS, chat), Synapse with the
+     * `wtfalch_chat_gate` module and MAS (both with a config file this step
+     * writes, `chat-matrix.ts`), and the chat service. All four apps are
+     * internal: Agora is the one public origin and proxies to them
+     * (`AGORA_CHAT_UPSTREAM`, `AGORA_MATRIX_UPSTREAM`, `AGORA_MAS_UPSTREAM`).
+     * It also finds or creates the org's ZITADEL messaging project, the
+     * audience the chat service requires, and records its id for Agora.
+     *
+     * Idempotent: every resource is found by name or recorded id before it is
+     * created, minted secrets are read back from the MAS app's envs, and an app
+     * is deployed when it is new, its config was freshly minted, or it is not running. A
+     * recorded chat resource means the stack already exists, so a second
+     * `coolify:chat` step for it is a re-key (onto the company domain, or back)
+     * and neither is built: both are refused by name, before anything is touched.
+     * No secret reaches an error: errors name the org and the missing input only.
+     */
+    async coolifyChat(action, org, context) {
+        const recorded = context.recordedIds();
+        if (recorded[`coolify:chat:${action.key}`]) {
+            if (action.desired.usesDomain === false) {
+                throw new NotBuiltError(`coolify:chat reverse re-key for ${org.slug}`, 'moving its chat back onto the original server_name is not built (#7 amendment 3)');
+            }
+            throw new NotBuiltError(`coolify:chat re-key for ${org.slug}`, 'moving its chat onto the company domain is not built; chat stays on its level-1 server_name');
+        }
+        const issuer = action.desired.issuer;
+        if (typeof issuer !== 'string' || issuer === '') {
+            throw new Error(`coolify:chat for ${org.slug}: the step carries no issuer`);
+        }
+        const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+        if (!zitadelOrgId) {
+            throw new Error(`coolify:chat for ${org.slug}: the org has no ZITADEL org recorded yet -- zitadel:issuer must run first`);
+        }
+        // Found or created by name, so a re-run after a crash reuses it. Its id is
+        // not a secret.
+        const { project } = await this.ports.zitadel.findOrCreateProject(zitadelOrgId, `${org.slug}-messaging`);
+        context.recordScopeId(ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, project.id);
+        // The chat service gates /_chat/manage on this role. Without it nobody
+        // passes. Every owner already invited gets it; an owner invited later
+        // gets it from `zitadelOwner`. Both are idempotent.
+        await this.ensureChatAdmins(org, zitadelOrgId, project.id, recorded);
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const server = await this.resolveServer();
+        const names = chatInternalNames(org.slug);
+        const synapseDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.synapseDb, 'synapse', CHAT_SYNAPSE_DB_SCOPE_KEY, CALLS_SYNAPSE_DB_INITDB_ARGS);
+        context.recordScopeId(CHAT_SYNAPSE_DB_SCOPE_KEY, synapseDbId);
+        const masDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.masDb, 'mas', CHAT_MAS_DB_SCOPE_KEY);
+        context.recordScopeId(CHAT_MAS_DB_SCOPE_KEY, masDbId);
+        const serviceDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.serviceDb, 'chat', CHAT_SERVICE_DB_SCOPE_KEY);
+        context.recordScopeId(CHAT_SERVICE_DB_SCOPE_KEY, serviceDbId);
+        const [synapseDbRow, masDbRow, serviceDbRow] = await Promise.all([
+            this.ports.coolify.getDatabase(synapseDbId),
+            this.ports.coolify.getDatabase(masDbId),
+            this.ports.coolify.getDatabase(serviceDbId),
+        ]);
+        const synapseDb = synapseDbRow.internal_db_url
+            ? parseCallsDbUrl(synapseDbRow.internal_db_url)
+            : null;
+        const masDb = masDbRow.internal_db_url ? parseCallsDbUrl(masDbRow.internal_db_url) : null;
+        if (!synapseDb || !masDb || !serviceDbRow.internal_db_url) {
+            // Before any app is touched: Coolify can take a moment to report a new
+            // database's url, and the next apply retries from a clean state.
+            throw new Error(`coolify:chat for ${org.slug}: a database has no internal_db_url yet -- retry this apply once Coolify reports one`);
+        }
+        const githubApp = await this.ports.coolify.requireGithubApp();
+        const synapse = await this.findOrCreateCallsApp(names.synapse, environment.id, () => this.ports.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: CHAT_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name: names.synapse,
+            dockerfile_location: CHAT_SYNAPSE_DOCKERFILE,
+            ports_exposes: CHAT_SYNAPSE_PORT,
+            autogenerate_domain: false,
+        }), { startIfStopped: false });
+        const mas = await this.findOrCreateCallsApp(names.mas, environment.id, () => this.ports.coolify.createDockerfileApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            dockerfile: CALLS_MAS_DOCKERFILE,
+            name: names.mas,
+            description: `matrix-authentication-service for ${org.slug}'s chat`,
+            instant_deploy: false,
+        }), { startIfStopped: false });
+        const service = await this.findOrCreateCallsApp(names.service, environment.id, () => this.ports.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: CHAT_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name: names.service,
+            dockerfile_location: CHAT_SERVICE_DOCKERFILE,
+            ports_exposes: CHAT_SERVICE_PORT,
+            autogenerate_domain: false,
+        }), { startIfStopped: false });
+        // Fixed internal names, set on every run: the three apps and Agora
+        // address each other by them. Neither Synapse's nor MAS's health check
+        // can pass before the other is up, so both are off (the calls stack's own
+        // rule).
+        await this.ports.coolify.updateApplication(synapse.appId, {
+            custom_internal_name: names.synapse,
+            ...(synapse.existed ? {} : { health_check_enabled: false }),
+        });
+        await this.ports.coolify.updateApplication(mas.appId, {
+            custom_internal_name: names.mas,
+            ...(mas.existed ? {} : { health_check_enabled: false }),
+        });
+        await this.ports.coolify.updateApplication(service.appId, {
+            custom_internal_name: names.service,
+        });
+        context.recordScopeId(CHAT_SYNAPSE_SCOPE_KEY, synapse.appId);
+        context.recordScopeId(CHAT_SERVICE_SCOPE_KEY, service.appId);
+        const synapseStorages = await this.ports.coolify.listStorages(synapse.appId);
+        if (!(synapseStorages.persistent_storages ?? []).some((s) => s.mount_path === '/data')) {
+            await this.ports.coolify.createPersistentStorage(synapse.appId, {
+                name: `${names.synapse}-data`,
+                mount_path: '/data',
+            });
+        }
+        const secrets = await this.ensureCallsMatrixSecrets(mas.appId, CHAT_SECRET_ENV_KEYS);
+        const agoraHost = agoraHostnameFor(org);
+        await this.ensureCallsFileStorage(synapse.appId, '/data/homeserver.yaml', chatSynapseHomeserverYaml({
+            orgSlug: org.slug,
+            db: synapseDb,
+            masHost: names.mas,
+            masSharedSecret: secrets.value.masSynapseSharedSecret,
+        }));
+        await this.ports.coolify.bulkUpsertEnvs(synapse.appId, [
+            { key: 'SYNAPSE_CONFIG_PATH', value: '/data/homeserver.yaml' },
+            { key: 'UID', value: '0' },
+            { key: 'GID', value: '0' },
+        ]);
+        await this.ensureCallsFileStorage(mas.appId, '/config/config.yaml', chatMasConfigYaml({
+            orgSlug: org.slug,
+            publicHost: agoraHost,
+            db: masDb,
+            synapseHost: names.synapse,
+            sharedSecret: secrets.value.masSynapseSharedSecret,
+            clientId: secrets.value.masClientId,
+            clientSecret: secrets.value.masClientSecret,
+            encryptionKey: secrets.value.masEncryptionKey,
+            rsaKeyPem: secrets.value.masRsaKeyPem,
+            ecKeyPem: secrets.value.masEcKeyPem,
+        }));
+        await this.ports.coolify.bulkUpsertEnvs(service.appId, chatServiceEnvs({
+            orgSlug: org.slug,
+            companyName: org.displayName,
+            issuer,
+            audience: project.id,
+            zitadelOrgId,
+            agoraHost,
+            masClientId: secrets.value.masClientId,
+            masClientSecret: secrets.value.masClientSecret,
+            databaseUrl: serviceDbRow.internal_db_url,
+        }));
+        // A file-storage write alone never reaches a running container. Deploy an
+        // app that is new, whose config was freshly minted, or that is not
+        // running now. The last test reads the live status, not what this run
+        // did, so a run that failed after creating the apps (or after deploying
+        // only some of them) is repaired by the next one. An unchanged, running
+        // stack is not redeployed, or this step would never converge. MAS first:
+        // Synapse asks it for token introspection.
+        for (const app of [mas, synapse, service]) {
+            if (!app.existed ||
+                secrets.changed ||
+                !isRunningOrStarting((await this.ports.coolify.getApplication(app.appId)).status)) {
+                await this.ports.coolify.deploy(app.appId);
+            }
+        }
+        // Last: the marker tells `desiredAgoraEnv` the names and envs are in place.
+        context.recordScopeId(CHAT_SERVICE_URL_SCOPE_KEY, chatUpstreams(org.slug).chat);
+        return { resourceId: mas.appId };
+    }
     // ---- calls service (#145, part 2 of #128) -------------------------------
     /**
      * `plan/diff.ts`'s `planCallsService`: the org's own calls service --
@@ -2426,7 +2708,7 @@ export class FoundryStepExecutor {
             git_branch: 'main',
             build_pack: 'dockerfile',
             name,
-            domains: callsHostnameFor(org),
+            domains: coolifyDomains([callsHostnameFor(org)]),
             dockerfile_location: CALLS_SERVICE_DOCKERFILE,
         }));
         // A fixed internal name, like Synapse and MAS above, so the org's Agora
@@ -2618,10 +2900,12 @@ export class FoundryStepExecutor {
      * `AGORA_FILES_UPSTREAM` are pushed once the platform's own mail/files
      * hosts are on and applied (#177's `platform-org.ts`'s
      * `agoraHostValuesFromPlatform`, read by `plan-apply.ts` when no host
-     * `agora` port overrides it) -- absent otherwise. The chat upstreams are
-     * still never pushed: chat has no admin API yet
-     * (https://github.com/wtfalch/chat/issues/40). Agora answers 502 on those
-     * routes rather than serving anything wrong. `AGORA_CALLS_UPSTREAM` is
+     * `agora` port overrides it) -- absent otherwise. `AGORA_CHAT_UPSTREAM`,
+     * `AGORA_MATRIX_UPSTREAM` and `AGORA_MAS_UPSTREAM` are pushed together once
+     * chat is on and `coolifyChat` has recorded that its apps carry their
+     * internal names (`CHAT_SERVICE_URL_SCOPE_KEY`); absent otherwise, and Agora
+     * answers 502 on those routes rather than serving anything wrong.
+     * `messagingProjectId` falls back to the project `coolifyChat` recorded. `AGORA_CALLS_UPSTREAM` is
      * pushed once calls are on and this org's calls service app carries its
      * internal name (`desiredAgoraEnv` reads that marker from the recorded ids,
      * not the host values).
@@ -2652,7 +2936,7 @@ export class FoundryStepExecutor {
             git_branch: 'main',
             build_pack: 'dockerfile',
             name,
-            domains: agoraHostnameFor(org),
+            domains: coolifyDomains([agoraHostnameFor(org)]),
             dockerfile_location: AGORA_APP_DOCKERFILE,
         }));
         // Every app foundry deploys keeps its own logs (#75), reused as-is here.
@@ -3259,23 +3543,21 @@ export class FoundryStepExecutor {
      * when the org has no owner yet, when no address is declared yet
      * (`plan/diff.ts`'s `planMail` reports that case as blocked, not planned,
      * so this step's own mode/domain work still runs), or once
-     * {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is already recorded -- checked last
+     * `mail_owner_mailbox` is already recorded -- checked last
      * so a second apply never calls `MailPort.createMailbox` again, rather
      * than relying on that port method's own duplicate refusal.
      */
     async ensureOwnerMailbox(org, mailOrg, options, context) {
-        if (!org.owner)
-            return;
-        const address = org.mail.ownerMailboxAddress ?? null;
-        if (!address)
-            return;
-        if (context.recordedIds()[MAIL_OWNER_MAILBOX_SCOPE_KEY])
-            return;
-        await this.ports.mail.createMailbox(mailOrg, {
-            address,
-            name: `${org.owner.givenName} ${org.owner.familyName}`,
-        }, options);
-        context.recordScopeId(MAIL_OWNER_MAILBOX_SCOPE_KEY, address);
+        for (const box of ownerMailboxes(org)) {
+            const { owner, address, scopeKey } = box;
+            if (!address)
+                continue;
+            if (ownerMailboxRecorded(box, context.recordedIds()))
+                continue;
+            await this.ports.mail.createMailbox(mailOrg, { address, name: `${owner.givenName} ${owner.familyName}` }, options);
+            // Recorded after each mailbox, so a crash between two owners repeats only the second.
+            context.recordScopeId(scopeKey, address);
+        }
     }
     /**
      * #230: creates each of the org's declared `mail.roleMailboxes` on its
@@ -3329,27 +3611,57 @@ export class FoundryStepExecutor {
             await this.ports.lettermint.deleteDomain(stale.id);
     }
     /**
-     * Upserts each DNS record `applyOrgMail` says foundry must publish, found
-     * by an exact name+type match (`CloudflarePort.findDnsRecord`'s own doc
-     * comment) so update never mistakes a stale record of a different type for
-     * a match. A `DKIM` record can be absent on the first call, since Stalwart
-     * mints the key on a background task; the next apply publishes it.
+     * Upserts each DNS record `applyOrgMail` says foundry must publish through
+     * {@link upsertMailDnsRecord}. A `DKIM` record can be absent on the first
+     * call, since Stalwart mints the key on a background task; the next apply
+     * publishes it.
      */
     async publishMailDnsRecords(org, result) {
-        const cf = this.ports.cloudflare;
-        const zone = await cf.findZoneByApex(result.domain);
+        const zone = await this.ports.cloudflare.findZoneByApex(result.domain);
         if (!zone) {
             throw new Error(`coolify:mail for ${org.slug}: no Cloudflare zone found for ${result.domain}`);
         }
         for (const record of result.records) {
-            const [existing] = await cf.findDnsRecord(zone.id, record.name, record.type);
-            const rec = { type: record.type, name: record.name, content: record.value };
-            if (existing) {
-                await cf.updateDnsRecord(zone.id, existing.id, rec);
-            }
-            else {
-                await cf.createDnsRecord(zone.id, rec);
-            }
+            await this.upsertMailDnsRecord(zone.id, record);
+        }
+    }
+    /**
+     * Creates or updates one mail record (Stalwart's or Lettermint's).
+     *
+     * Always DNS-only: Cloudflare proxies only `A`, `AAAA` and `CNAME`, and a
+     * proxied `CNAME` answers with Cloudflare's own addresses instead of its
+     * target, so Lettermint's return-path and DKIM names would stop resolving
+     * to Lettermint. `@wtfalch/providers`' `createDnsRecord` proxies by
+     * default, so `proxied: false` is sent on every write, update included, so
+     * a record someone proxied by hand is put back. An `MX` record carries the
+     * priority it was given, which Cloudflare requires.
+     *
+     * Found by an exact name+type match (`CloudflarePort.findDnsRecord`'s own
+     * doc comment) so a stale record of a different type is never taken for a
+     * match. A name can hold several `TXT` records (an apex often holds a site
+     * verification beside SPF), so a `TXT` record only replaces one that
+     * starts with the same tag (`v=spf1`, `v=DKIM1`); with none, it is added
+     * beside them. Before this, the first `TXT` on the name was overwritten,
+     * whatever it was.
+     */
+    async upsertMailDnsRecord(zoneId, record) {
+        const cf = this.ports.cloudflare;
+        const found = await cf.findDnsRecord(zoneId, record.name, record.type);
+        const existing = record.type === 'TXT'
+            ? found.find((r) => txtRecordTag(r.content) === txtRecordTag(record.value))
+            : found[0];
+        const rec = {
+            type: record.type,
+            name: record.name,
+            content: record.value,
+            proxied: false,
+            ...(record.priority === undefined ? {} : { priority: record.priority }),
+        };
+        if (existing) {
+            await cf.updateDnsRecord(zoneId, existing.id, rec);
+        }
+        else {
+            await cf.createDnsRecord(zoneId, rec);
         }
     }
     /**
@@ -3398,20 +3710,12 @@ export class FoundryStepExecutor {
      * handle here and is dropped rather than kept as dead code.
      */
     async publishLettermintDnsRecords(zoneId, records) {
-        const cf = this.ports.cloudflare;
         for (const record of records) {
             if (record.type === 'TXT' && record.value.toLowerCase().startsWith('v=dmarc1')) {
-                await this.ensureLettermintDmarcRecord(cf, zoneId, record);
+                await this.ensureLettermintDmarcRecord(this.ports.cloudflare, zoneId, record);
                 continue;
             }
-            const [existing] = await cf.findDnsRecord(zoneId, record.name, record.type);
-            const rec = { type: record.type, name: record.name, content: record.value };
-            if (existing) {
-                await cf.updateDnsRecord(zoneId, existing.id, rec);
-            }
-            else {
-                await cf.createDnsRecord(zoneId, rec);
-            }
+            await this.upsertMailDnsRecord(zoneId, record);
         }
     }
     /**
@@ -3420,10 +3724,15 @@ export class FoundryStepExecutor {
      * Lettermint's own `p=none` default.
      */
     async ensureLettermintDmarcRecord(cf, zoneId, record) {
-        const hasDmarc = (await cf.findDnsRecord(zoneId, record.name, 'TXT')).some((r) => r.content.toLowerCase().startsWith('v=dmarc1'));
+        const hasDmarc = (await cf.findDnsRecord(zoneId, record.name, 'TXT')).some((r) => txtRecordTag(r.content) === 'v=dmarc1');
         if (hasDmarc)
             return;
-        await cf.createDnsRecord(zoneId, { type: 'TXT', name: record.name, content: record.value });
+        await cf.createDnsRecord(zoneId, {
+            type: 'TXT',
+            name: record.name,
+            content: record.value,
+            proxied: false,
+        });
     }
     // ---- files / ai --------------------------------------------------------
     /**
@@ -3433,15 +3742,62 @@ export class FoundryStepExecutor {
      * this is called every time regardless of whether it already ran --
      * idempotent by find-or-create, not by checking `recordedIds` first.
      */
-    async filesOrganisation(action, org) {
+    async filesOrganisation(action, org, context) {
         const files = await this.filesPort();
+        // F6b: an org whose entries use files needs an owner member in its files
+        // organisation, which its own key is minted below. Only a new
+        // organisation takes one, so it is passed when the owner is known now.
+        const owner = org.hosting.entries.some((e) => e.uses?.files)
+            ? filesOwnerUserId(org, context.recordedIds())
+            : undefined;
         const provisioned = await files.provisionOrganisation({
             organisationId: org.id,
             ceilingBytes: action.desired.ceilingBytes ?? null,
             ceilingMicros: action.desired.ceilingMicros ?? null,
+            ...(owner ? { name: org.displayName, owner } : {}),
         });
+        // Recorded now, so the org key is minted below the member files made.
+        if (owner && provisioned.created)
+            context.recordScopeId(FILES_ORG_OWNER_SCOPE_KEY, owner);
+        if (provisioned.agoraKey) {
+            await this.deliverFilesAgoraKey(files, org, provisioned.agoraKey, context);
+        }
         return { resourceId: provisioned.organisationId };
     }
+    /**
+     * Files onboards Agora when it provisions an organisation with an owner and
+     * returns Agora's service key once. Foundry holds no other files key for
+     * Agora, so this is the only one: its secret goes straight to
+     * `deliverSecret`, its id is recorded as undelivered first, and a delivery
+     * that fails revokes the key again instead of leaving a live key nobody holds.
+     */
+    async deliverFilesAgoraKey(files, org, key, context) {
+        const at = `files:organisation for ${org.slug}`;
+        context.recordScopeId(FILES_AGORA_UNDELIVERED_SCOPE_KEY, key.id);
+        await context.persistScopeIds();
+        let cause = 'no HTTP status';
+        for (let attempt = 1; attempt <= AI_KEY_DELIVERY_ATTEMPTS; attempt++) {
+            try {
+                await this.ports.deliverSecret(`files:agora-key:${org.slug}`, key.secret);
+                context.recordScopeId(FILES_AGORA_KEY_SCOPE_KEY, key.id);
+                return;
+            }
+            catch (error) {
+                cause = filesErrorCause(error);
+            }
+        }
+        let revoked = false;
+        try {
+            await files.revokeOrganisationKey(org.id, key.id);
+            revoked = true;
+        }
+        catch {
+            // Left on the undelivered id, which the plan reports.
+        }
+        if (revoked)
+            context.recordScopeId(FILES_AGORA_UNDELIVERED_SCOPE_KEY, '');
+        throw new Error(`${at}: Agora's key ${key.id} could not be delivered after ${AI_KEY_DELIVERY_ATTEMPTS} attempts (${cause}); ${revoked ? 'it was revoked again' : 'revoke it in files'}`);
+    }
     async filesStorage(action, org) {
         const files = await this.filesPort();
         await files.setQuota(org.id, action.desired.limitBytes ?? null);
@@ -3514,6 +3870,418 @@ export class FoundryStepExecutor {
         // echoes the secret.
         throw new Error(`ai:key for ${org.slug}: key ${issued.id} was minted but its secret could not be delivered after ${AI_KEY_DELIVERY_ATTEMPTS} attempts (${lastError instanceof Error ? lastError.name : 'error'}); revoke it in ai before a new one is minted`);
     }
+    /**
+     * F6a: mints, renews, finishes, re-writes or retires one entry's ai key.
+     *
+     * Order keeps the app on a valid key throughout: the new key is minted below
+     * the org's key, its id is recorded and persisted as undelivered, the env is
+     * written (up to three tries), that write is recorded, the app is restarted,
+     * and only then is the old key revoked. A failed write keeps the old key in
+     * use and the planner blocks instead of minting again. A failed restart
+     * after the write plans `finish`, which restarts and records, minting
+     * nothing. The webhook secret, which ai shows once, is written the same way
+     * before the mint. A secret reaches `bulkUpsertEnvs` and nothing else:
+     * errors name ids, never the cause, which can echo one.
+     */
+    async aiEntryKey(action, org, context) {
+        const entryKey = action.key.slice(org.id.length + 1);
+        const at = `ai:key for ${org.slug} entry '${entryKey}'`;
+        const desired = action.desired;
+        const ai = await this.aiPort();
+        if (desired.mode === 'retire') {
+            const keyId = context.recordedIds()[`ai:key:${action.key}`];
+            if (!keyId)
+                return {};
+            await this.revokeEntryKey(ai, org, entryKey, keyId, context);
+            context.recordScopeId(entryAiRetiredScopeKey(entryKey), keyId);
+            return {};
+        }
+        const entry = org.hosting.entries.find((e) => e.key === entryKey && e.uses?.ai);
+        if (!entry)
+            throw new Error(`${at}: the entry no longer declares uses.ai`);
+        const d = action.desired;
+        const recorded = context.recordedIds();
+        const appId = recorded[`coolify:app:${action.key}`];
+        if (!appId)
+            throw new Error(`${at}: the entry's app is not recorded yet`);
+        const writeEnvs = async (what, ids, envs) => {
+            for (let attempt = 1; attempt <= AI_KEY_DELIVERY_ATTEMPTS; attempt++) {
+                try {
+                    await this.ports.coolify.bulkUpsertEnvs(appId, envs.map((e) => ({ ...e, literal: true })));
+                    return;
+                }
+                catch {
+                    // The error can echo a value; it is dropped.
+                }
+            }
+            throw new Error(`${at}: ${what} ${ids} could not be written to the app's env after ${AI_KEY_DELIVERY_ATTEMPTS} attempts`);
+        };
+        const previousKeyId = recorded[`ai:key:${action.key}`];
+        let resourceId = previousKeyId;
+        let expiresAt;
+        if (d.mode === 'finish') {
+            // The env already holds the key recorded as undelivered (`planEntryAiKeys`).
+            resourceId = recorded[entryAiUndeliveredScopeKey(entryKey)];
+            expiresAt = recorded[entryAiPendingExpiresScopeKey(entryKey)];
+            await this.ports.coolify.restart(appId);
+        }
+        else {
+            const appliedBefore = recorded[entryAiAppliedScopeKey(entryKey)];
+            let webhookBefore;
+            try {
+                webhookBefore = appliedBefore
+                    ? JSON.parse(appliedBefore).webhook
+                    : undefined;
+            }
+            catch {
+                webhookBefore = undefined;
+            }
+            if (d.webhook && d.webhook !== webhookBefore) {
+                const pending = entryAiWebhookPendingScopeKey(entryKey);
+                // Kept only while a secret could be lost: from here until the
+                // registration answers without one or the secret is in the env.
+                context.recordScopeId(pending, '1');
+                await context.persistScopeIds();
+                let registered;
+                try {
+                    registered = await ai.setWebhookAddress(org.id, d.webhook);
+                }
+                catch (error) {
+                    // Refused: no secret exists to lose.
+                    context.recordScopeId(pending, '');
+                    await context.persistScopeIds();
+                    throw error;
+                }
+                if (registered.secret) {
+                    await writeEnvs('the webhook secret', 'of the registered webhook', [
+                        { key: 'AI_WEBHOOK_SECRET', value: registered.secret },
+                    ]);
+                }
+                context.recordScopeId(pending, '');
+                await context.persistScopeIds();
+            }
+            const envs = [
+                { key: 'AI_URL', value: d.aiUrl },
+                { key: 'AI_ORGANISATION_ID', value: org.id },
+                { key: 'AI_OFFERINGS_JSON', value: JSON.stringify(d.offerings) },
+            ];
+            if (d.mode !== 'settings') {
+                const minterKeyId = recorded[`ai:key:${org.id}`];
+                if (!minterKeyId)
+                    throw new Error(`${at}: the org's own ai key is not recorded yet`);
+                const minted = await ai.mintNestedKey({
+                    organisationId: org.id,
+                    minterKeyId,
+                    name: d.name,
+                    expiresDays: d.expiresDays,
+                    permissions: d.permissions,
+                });
+                context.recordScopeId(entryAiUndeliveredScopeKey(entryKey), minted.id);
+                context.recordScopeId(entryAiPendingExpiresScopeKey(entryKey), minted.expiresAt);
+                await context.persistScopeIds();
+                await writeEnvs('key', minted.id, [...envs, { key: 'AI_API_KEY', value: minted.secret }]);
+                // The env holds the key now; a restart that fails from here plans `finish`.
+                context.recordScopeId(entryAiWrittenScopeKey(entryKey), minted.id);
+                await context.persistScopeIds();
+                resourceId = minted.id;
+                expiresAt = minted.expiresAt;
+            }
+            else {
+                await writeEnvs('settings', 'of the entry', envs);
+            }
+            await this.ports.coolify.restart(appId);
+        }
+        if (expiresAt) {
+            context.recordScopeId(entryAiExpiresScopeKey(entryKey), expiresAt);
+            // ai clamps the expiry to the org key's; a key already inside the
+            // renewal window must not be replaced by another as short.
+            const minter = recorded[`ai:key:${org.id}`] ?? '';
+            const clamped = !(Date.parse(expiresAt) - Date.now() >=
+                AI_ENTRY_RENEW_WINDOW_DAYS * 24 * 60 * 60 * 1000);
+            context.recordScopeId(entryAiClampedScopeKey(entryKey), clamped ? JSON.stringify({ expiresAt, minter }) : '');
+            context.recordScopeId(entryAiUndeliveredScopeKey(entryKey), '');
+            context.recordScopeId(entryAiWrittenScopeKey(entryKey), '');
+        }
+        // Follows the wanted state, so a removed `webhookPath` plans nothing again.
+        context.recordScopeId(entryAiAppliedScopeKey(entryKey), JSON.stringify({
+            permissions: d.permissions,
+            offerings: d.offerings,
+            webhook: d.webhook,
+            aiUrl: d.aiUrl,
+        }));
+        if (expiresAt && previousKeyId && previousKeyId !== resourceId) {
+            await this.revokeEntryKey(ai, org, entryKey, previousKeyId, context);
+        }
+        return { resourceId };
+    }
+    /**
+     * REVOKE SEAM (ai#157): revokes through `revokeKey` when the port has one.
+     * Without it, or when it fails, the id joins the entry's list of keys left
+     * live, which the plan shows, and the step goes on: the app already has its
+     * new key.
+     */
+    async revokeEntryKey(ai, org, entryKey, keyId, context) {
+        if (ai.revokeKey) {
+            try {
+                await ai.revokeKey(org.id, keyId);
+                return;
+            }
+            catch {
+                // Listed below instead; the cause is dropped.
+            }
+        }
+        const listKey = entryAiUnrevokedScopeKey(entryKey);
+        const ids = parseIdList(context.recordedIds()[listKey]);
+        if (!ids.includes(keyId))
+            ids.push(keyId);
+        context.recordScopeId(listKey, JSON.stringify(ids));
+    }
+    /**
+     * F6b: mints or renews the org's own files key, or revokes the ones a
+     * renewal replaced. The key is minted below the files organisation's owner
+     * (the member `files_org_owner` records) and its one-time secret goes
+     * straight to {@link FoundryStepExecutorPorts.deliverSecret}. The id is
+     * recorded as undelivered first, so a delivery that fails never leads to a
+     * second mint. Entries are minted below it with `issueKeyBelow`, which needs
+     * no secret.
+     *
+     * A renewal keeps the old key live: its id goes to `files_key_previous`, the
+     * entries are re-minted below the new key by their own steps, and
+     * `revoke-previous` revokes the old key only when every entry holds a key
+     * below the new one. A failed revoke is listed, not retried.
+     */
+    async filesRootKey(action, org, context) {
+        const at = `files:key for ${org.slug}`;
+        const files = await this.filesPort();
+        const mode = action.desired.mode ?? 'mint';
+        const recorded = context.recordedIds();
+        if (mode === 'revoke-previous') {
+            const previous = parseFilesIdList(recorded[FILES_ROOT_PREVIOUS_SCOPE_KEY]);
+            const rootId = recorded[`files:key:${org.id}`];
+            if (previous.length === 0 || !rootId)
+                return {};
+            // Every entry must already hold a key below the new org key; otherwise
+            // an app would lose its key. The next plan asks again.
+            const ready = org.hosting.entries
+                .filter((e) => e.uses?.files)
+                .every((e) => recorded[`files:key:${org.id}:${e.key}`] &&
+                recorded[entryFilesMinterScopeKey(e.key)] === rootId &&
+                !recorded[entryFilesUndeliveredScopeKey(e.key)]);
+            if (!ready)
+                return {};
+            const unrevoked = parseFilesIdList(recorded[FILES_ROOT_UNREVOKED_SCOPE_KEY]);
+            for (const id of previous) {
+                try {
+                    await files.revokeOrganisationKey(org.id, id);
+                }
+                catch {
+                    if (!unrevoked.includes(id))
+                        unrevoked.push(id);
+                }
+            }
+            context.recordScopeId(FILES_ROOT_UNREVOKED_SCOPE_KEY, unrevoked.length ? JSON.stringify(unrevoked) : '');
+            context.recordScopeId(FILES_ROOT_PREVIOUS_SCOPE_KEY, '');
+            return {};
+        }
+        const issuer = recorded[FILES_ORG_OWNER_SCOPE_KEY];
+        if (!issuer) {
+            throw new Error(`${at}: the files organisation has no recorded owner to mint the key below`);
+        }
+        let issued;
+        try {
+            issued = await files.issueOrganisationKey(org.id, {
+                name: action.desired.name,
+                kind: 'service',
+                issuer,
+                permissions: action.desired.permissions,
+                expiresDays: action.desired.expiresDays,
+            });
+        }
+        catch (error) {
+            throw new Error(`${at}: files refused the key (${filesErrorCause(error)})`);
+        }
+        context.recordScopeId(FILES_ROOT_UNDELIVERED_SCOPE_KEY, issued.id);
+        await context.persistScopeIds();
+        let cause = 'no HTTP status';
+        for (let attempt = 1; attempt <= AI_KEY_DELIVERY_ATTEMPTS; attempt++) {
+            try {
+                await this.ports.deliverSecret(`files:key:${org.slug}`, issued.secret);
+                // The expiry and the replaced id follow the delivery: before it, the
+                // recorded key is still the one in use.
+                context.recordScopeId(FILES_ROOT_EXPIRES_SCOPE_KEY, issued.expiresAt);
+                const replaced = recorded[`files:key:${org.id}`];
+                if (mode === 'renew' && replaced) {
+                    const previous = parseFilesIdList(recorded[FILES_ROOT_PREVIOUS_SCOPE_KEY]);
+                    if (!previous.includes(replaced))
+                        previous.push(replaced);
+                    context.recordScopeId(FILES_ROOT_PREVIOUS_SCOPE_KEY, JSON.stringify(previous));
+                }
+                return { resourceId: issued.id };
+            }
+            catch (error) {
+                cause = filesErrorCause(error);
+            }
+        }
+        throw new Error(`${at}: key ${issued.id} was minted but its secret could not be delivered after ${AI_KEY_DELIVERY_ATTEMPTS} attempts (${cause}); revoke it in files before a new one is minted`);
+    }
+    /**
+     * F6b: mints, renews, finishes, re-writes or retires one entry's files key.
+     *
+     * Same order as the ai entry key: the collections are ensured first (they
+     * hold no secret and can be repeated), the new key is minted below the
+     * org's own key, its id is recorded and persisted as undelivered, the env
+     * is written (up to three tries), that write is recorded, the app is
+     * restarted, and only then is the old key revoked. A failed write keeps the
+     * old key in use and the planner blocks instead of minting again. A failed
+     * restart after the write plans `finish`, which restarts and records,
+     * minting nothing. A secret reaches `bulkUpsertEnvs` and nothing else.
+     */
+    async filesEntryKey(action, org, context) {
+        const entryKey = action.key.slice(org.id.length + 1);
+        const at = `files:key for ${org.slug} entry '${entryKey}'`;
+        const desired = action.desired;
+        const files = await this.filesPort();
+        if (desired.mode === 'retire') {
+            const recordedNow = context.recordedIds();
+            const keyId = recordedNow[`files:key:${action.key}`];
+            // A key minted but not delivered, or written but not yet restarted, is live too.
+            const looseId = recordedNow[entryFilesUndeliveredScopeKey(entryKey)];
+            for (const id of new Set([keyId, looseId].filter((v) => Boolean(v)))) {
+                await this.revokeFilesEntryKey(files, org, entryKey, id, context);
+            }
+            if (keyId)
+                context.recordScopeId(entryFilesRetiredScopeKey(entryKey), keyId);
+            context.recordScopeId(entryFilesUndeliveredScopeKey(entryKey), '');
+            context.recordScopeId(entryFilesWrittenScopeKey(entryKey), '');
+            return {};
+        }
+        const entry = org.hosting.entries.find((e) => e.key === entryKey && e.uses?.files);
+        if (!entry)
+            throw new Error(`${at}: the entry no longer declares uses.files`);
+        const d = action.desired;
+        const recorded = context.recordedIds();
+        const appId = recorded[`coolify:app:${action.key}`];
+        if (!appId)
+            throw new Error(`${at}: the entry's app is not recorded yet`);
+        const writeEnvs = async (what, ids, envs) => {
+            let cause = 'no HTTP status';
+            for (let attempt = 1; attempt <= AI_KEY_DELIVERY_ATTEMPTS; attempt++) {
+                try {
+                    await this.ports.coolify.bulkUpsertEnvs(appId, envs.map((e) => ({ ...e, literal: true })));
+                    return;
+                }
+                catch (error) {
+                    // Only the status is kept: the message can echo a value.
+                    cause = filesErrorCause(error);
+                }
+            }
+            throw new Error(`${at}: ${what} ${ids} could not be written to the app's env after ${AI_KEY_DELIVERY_ATTEMPTS} attempts (${cause})`);
+        };
+        const previousKeyId = recorded[`files:key:${action.key}`];
+        let resourceId = previousKeyId;
+        let expiresAt;
+        if (d.mode === 'finish') {
+            // The env already holds the key recorded as undelivered (`planFilesKeys`).
+            resourceId = recorded[entryFilesUndeliveredScopeKey(entryKey)];
+            expiresAt = recorded[entryFilesPendingExpiresScopeKey(entryKey)];
+            await this.ports.coolify.restart(appId);
+        }
+        else {
+            // Repeatable by name, so each apply asks again and a collection is never created twice.
+            const envs = [
+                { key: 'FILES_URL', value: d.filesUrl },
+                { key: 'FILES_ORGANISATION_ID', value: org.id },
+            ];
+            for (const name of d.collections) {
+                let collection;
+                try {
+                    collection = await files.ensureCollection(org.id, name);
+                }
+                catch (error) {
+                    throw new Error(`${at}: collection ${name} could not be ensured (${filesErrorCause(error)})`);
+                }
+                envs.push({ key: filesCollectionEnvName(name), value: collection.id });
+            }
+            if (d.mode !== 'settings') {
+                const minterId = recorded[`files:key:${org.id}`];
+                if (!minterId)
+                    throw new Error(`${at}: the org's own files key is not recorded yet`);
+                // files refuses a key that outlives its minter. A minute is held back
+                // so the call, which files dates later, still lands inside it.
+                const rootExpires = Date.parse(recorded[FILES_ROOT_EXPIRES_SCOPE_KEY] ?? '');
+                if (Number.isNaN(rootExpires)) {
+                    throw new Error(`${at}: the org's own files key expiry is not recorded`);
+                }
+                const expiresDays = Math.min(FILES_KEY_DAYS, Math.floor((rootExpires - (context.now?.() ?? Date.now()) - 60_000) / DAY_MS));
+                if (expiresDays < FILES_KEY_RENEW_WINDOW_DAYS) {
+                    throw new Error(`${at}: the org's own files key leaves under ${FILES_KEY_RENEW_WINDOW_DAYS} days; mint a new org key first`);
+                }
+                let minted;
+                try {
+                    minted = await files.issueKeyBelow(org.id, minterId, {
+                        name: d.name,
+                        kind: 'service',
+                        permissions: d.permissions,
+                        expiresDays,
+                    });
+                }
+                catch (error) {
+                    throw new Error(`${at}: files refused the key (${filesErrorCause(error)})`);
+                }
+                context.recordScopeId(entryFilesUndeliveredScopeKey(entryKey), minted.id);
+                context.recordScopeId(entryFilesPendingExpiresScopeKey(entryKey), minted.expiresAt);
+                await context.persistScopeIds();
+                await writeEnvs('key', minted.id, [
+                    ...envs,
+                    { key: 'FILES_API_KEY', value: minted.secret },
+                ]);
+                // The env holds the key now; a restart that fails from here plans `finish`.
+                context.recordScopeId(entryFilesWrittenScopeKey(entryKey), minted.id);
+                context.recordScopeId(entryFilesMinterScopeKey(entryKey), minterId);
+                await context.persistScopeIds();
+                resourceId = minted.id;
+                expiresAt = minted.expiresAt;
+            }
+            else {
+                await writeEnvs('settings', 'of the entry', envs);
+            }
+            await this.ports.coolify.restart(appId);
+        }
+        if (expiresAt) {
+            context.recordScopeId(entryFilesExpiresScopeKey(entryKey), expiresAt);
+            context.recordScopeId(entryFilesUndeliveredScopeKey(entryKey), '');
+            context.recordScopeId(entryFilesWrittenScopeKey(entryKey), '');
+        }
+        // Follows the wanted state, so an unchanged declaration plans nothing again.
+        context.recordScopeId(entryFilesAppliedScopeKey(entryKey), JSON.stringify({
+            permissions: d.permissions,
+            collections: d.collections,
+            filesUrl: d.filesUrl,
+        }));
+        if (expiresAt && previousKeyId && previousKeyId !== resourceId) {
+            await this.revokeFilesEntryKey(files, org, entryKey, previousKeyId, context);
+        }
+        return { resourceId };
+    }
+    /**
+     * Revokes one entry key. When the call fails the id joins the entry's list
+     * of keys left live, which the plan shows, and the step goes on: the app
+     * already has its new key.
+     */
+    async revokeFilesEntryKey(files, org, entryKey, keyId, context) {
+        try {
+            await files.revokeOrganisationKey(org.id, keyId);
+            return;
+        }
+        catch {
+            // Listed below instead; the cause is dropped.
+        }
+        const listKey = entryFilesUnrevokedScopeKey(entryKey);
+        const ids = parseFilesIdList(context.recordedIds()[listKey]);
+        if (!ids.includes(keyId))
+            ids.push(keyId);
+        context.recordScopeId(listKey, JSON.stringify(ids));
+    }
     // ---- destroy -------------------------------------------------------------
     /**
      * {@link StepDestroyer.destroy}: deletes the one resource
@@ -3652,6 +4420,20 @@ export class FoundryStepExecutor {
                 case 'cloudflare:access':
                     await this.ports.cloudflare.deleteAccessApp(target.id);
                     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.
+                    const ai = await this.aiPort();
+                    if (ai.revokeKey)
+                        await ai.revokeKey(org.id, target.id);
+                    return;
+                }
+                case 'files:key': {
+                    // F6b: an entry's key (`<orgId>:<entry>`); the org's own key is left alone.
+                    const files = await this.filesPort();
+                    await files.revokeOrganisationKey(org.id, target.id);
+                    return;
+                }
                 case 'coolify:app':
                     await this.ports.coolify.deleteApplication(target.id);
                     return;