@wtfalch/foundry 0.4.0 → 0.5.0

package/dist/plan/executor.js

@@ -1,7 +1,9 @@
 import { randomBytes } from 'node:crypto';
 import { URL } from 'node:url';
 import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
+import { AGORA_CLIENT_ID_SCOPE_KEY, agoraHostnameFor, desiredAgoraEnv, } from './agora.js';
 import { MAS_IMAGE, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
+import { ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, } from './platform-diff.js';
 // ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
@@ -79,6 +81,13 @@ function tunnelIngressHostnames(org) {
     if (org.calls.enabled && org.calls.usesDomain && org.domain) {
         hostnames.push(`calls.${org.domain}`);
     }
+    // #164: Agora always moves onto `agora.<domain>` once `org.domain` is set
+    // -- no toggle to gate this on. A level-1 org (no domain) adds nothing
+    // here: `<slug>-agora.oikos.host` rides the shared `*.oikos.host` wildcard
+    // tunnel (`scripts/shared-ingress.mjs`), not a per-org tunnel.
+    if (org.domain) {
+        hostnames.push(agoraHostnameFor(org));
+    }
     return hostnames;
 }
 /**
@@ -121,7 +130,7 @@ function mailOrgFor(org, usesDomain, mode) {
  */
 const COOLIFY_PROXY_ORIGIN = 'http://coolify-proxy:80';
 /** The one Access policy foundry puts on its own Access app (#84). */
-const ACCESS_POLICY_NAME = 'foundry: allowed emails';
+export const ACCESS_POLICY_NAME = 'foundry: allowed emails';
 /**
  * The sign-in broker's own route mount (`@wtfalch/auth`'s `NextAuth`,
  * `dist/next.d.ts`'s `handlers` doc comment: "`export const { GET, POST } =
@@ -187,6 +196,25 @@ const DEFAULT_APP_DOCKERFILE = 'apps/hestia/Dockerfile';
 const CMS_REPO = 'wtfalch/cms';
 const CMS_APP_DOCKERFILE = 'Dockerfile';
 const CMS_SITE_APP_DOCKERFILE = 'apps/site/Dockerfile';
+/**
+ * #164: the repo `coolifyAgora` builds the org's Agora from
+ * (https://github.com/wtfalch/agora) -- the issue's own "How" names this
+ * exact Dockerfile, and it is the only build strategy any app this file
+ * provisions ever uses ({@link DEFAULT_APP_DOCKERFILE}/{@link CMS_APP_DOCKERFILE}/
+ * `CALLS_SERVICE_DOCKERFILE` below are all `dockerfile_location` into a
+ * `createGithubAppApplication` build-from-repo call, never a registry
+ * image): "Coolify builds each org's Agora from the agora repo" is not a
+ * fresh product choice here, it is this file's one established convention,
+ * followed rather than reopened (#164 "Decide" 1). The agora repo's own
+ * Dockerfile (`apps/agora/Dockerfile`) already `EXPOSE`s 8080 and serves
+ * from a build built at the repository root, the same one-repo shape
+ * `CMS_REPO`'s own two apps use -- no `ports_exposes`/`PORT` env is needed
+ * the way `CALLS_SERVICE_PORT` is for the calls service's own Node process,
+ * since Coolify's github-app build already reads the exposed port the same
+ * way it does for `cmsSite`'s two apps above.
+ */
+const AGORA_REPO = 'wtfalch/agora';
+const AGORA_APP_DOCKERFILE = 'apps/agora/Dockerfile';
 /**
  * Every app foundry deploys keeps its own logs across a redeploy, so a
  * database outage does not also erase the only other copy of the evidence
@@ -199,9 +227,13 @@ const CMS_SITE_APP_DOCKERFILE = 'apps/site/Dockerfile';
  */
 const LOG_DIR = '/app/logs';
 /**
- * The one shared Stalwart apex and MX host every org's mail lives on (#7
- * "Mail"), the same values `@wtfalch/email`'s own README examples use for
- * `applyOrgMail`/`parkOrgMail`'s `OrgMailOptions`.
+ * #177: the fallback Stalwart apex and mail host `coolifyMail` uses when its
+ * own step carries none (`diff.ts`'s `planMail` always supplies one once a
+ * platform is wired -- `platform-org.ts`'s `DEFAULT_ORG_PLATFORM_READINESS`
+ * is this exact pair, so a host that has not wired `FoundryPlanApplyOptions.
+ * platform` yet keeps running on the address every org's mail always ran on
+ * before the platform existed to ask, the same values `@wtfalch/email`'s own
+ * README examples use for `applyOrgMail`/`parkOrgMail`'s `OrgMailOptions`).
  */
 const MAIL_APEX = 'wtfalch.dev';
 const MAIL_HOST = 'mail.wtfalch.dev';
@@ -252,24 +284,61 @@ const SITE_APP_SCOPE_KEY = 'coolify_site_app';
  */
 const CMS_DATABASE_SCOPE_KEY = 'coolify_cms_database';
 /**
- * #138: the Resend domain's own id (`createDomain`/`findDomain`'s result,
- * never a key or token) for this org's mail domain -- recorded so the app
- * step (#140 rework) can scope its `<slug>-app@<domainId>` key to this domain without
- * calling Resend a second time to look it up. No `system:kind:key` slot of
- * its own for the same reason {@link CMS_DATABASE_SCOPE_KEY} has none:
- * `coolify:mail`'s one step already auto-records `result.domain` as its
- * `resourceId`.
+ * #138/#140 (2026-09-28 lettermint-org-mail swap): the mail domain
+ * `coolifyMail` resolved with Stalwart -- `org.domain` when the org uses its
+ * own domain, else `<slug>.<apex>` for a domainless org (2026-09-28:
+ * domainless orgs get their own Lettermint domain too). Recorded so the app
+ * step can derive `MAIL_FROM` and drive its own Lettermint domain/project
+ * work (`ensureAppLettermintMail`) without recomputing `mailOrgFor`'s own
+ * domain choice, the same way {@link APP_CLIENT_ID_SCOPE_KEY} carries a
+ * public value out. All of that org's Lettermint work -- ensure domain,
+ * restrict, publish DNS, verify -- now happens inside the same step that
+ * reads this key (`ensureAppLettermintMail`), so unlike the Resend design
+ * this rework replaces, no separate domain-id scope key is recorded: the
+ * domain is looked up by name fresh each apply. Renamed from
+ * `resend_mail_domain`.
+ */
+const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
+/**
+ * #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';
+/**
+ * #80: the id of an ai key `aiKey` has minted but not yet delivered, a flat
+ * scope id (no `:`). `plan/diff.ts` keeps its own copy of this literal.
+ */
+const AI_KEY_UNDELIVERED_SCOPE_KEY = 'ai_key_undelivered';
+/** How many times `aiKey` tries `deliverSecret` before giving up. */
+const AI_KEY_DELIVERY_ATTEMPTS = 3;
+/**
+ * #173: the id of a jobs project `jobsRegistration` has registered but not
+ * yet delivered the credentials of, a flat scope id (no `:`). `serviceIds` is
+ * already per org, so the key needs no org in it. `plan/diff.ts` keeps its own
+ * copy of this literal.
  */
-const RESEND_DOMAIN_ID_SCOPE_KEY = 'resend_domain_id';
+const JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = 'jobs_registration_undelivered';
+/** How many times `jobsRegistration` tries each `deliverSecret` before giving up. */
+const JOBS_DELIVERY_ATTEMPTS = 3;
 /**
- * #138/#140: the mail domain `registerResendDomain` verified with Resend --
- * `org.domain` when the org uses its own domain, else `<slug>.<apex>` for a
- * domainless org (2026-09-28: domainless orgs get their own Resend domain
- * too). Recorded so the app step can derive `MAIL_FROM` without recomputing
- * `mailOrgFor`'s own domain choice, the same way {@link APP_CLIENT_ID_SCOPE_KEY}
- * carries a public value out.
+ * The one mailbox this executor mints on its own (#162) -- a plain,
+ * discoverable local part rather than anything derived from the owner's own
+ * (possibly personal) `email`, so it never collides with a name and never
+ * repeats a stranger's inbox back at them. #162's own "Decide" section
+ * leaves open whether every *other* person in the org also gets a mailbox
+ * from foundry, or only from Boule -- unresolved, on purpose, until a human
+ * picks one; this constant and {@link ensureOwnerMailbox} only ever cover
+ * the owner, which every candidate answer to that question already includes.
  */
-const RESEND_MAIL_DOMAIN_SCOPE_KEY = 'resend_mail_domain';
+const MAIL_OWNER_LOCAL_PART = 'owner';
 /**
  * `coolifyCalls` provisions four resources from one `coolify:calls` step
  * (#128) — the same one-step, several-resource shape `cmsSite` already solves
@@ -342,7 +411,7 @@ const CALLS_SERVICE_PORT = '8080';
  * same "nothing says it's off" convention `planHostingToggle` (`diff.ts`)
  * uses for the org's own app.
  */
-function isRunningOrStarting(status) {
+export function isRunningOrStarting(status) {
     if (!status)
         return true;
     return !status.startsWith('exited') && !status.startsWith('stopped');
@@ -390,12 +459,18 @@ export class FoundryStepExecutor {
                 return this.aiOrganisation(action, org);
             case 'ai:budget':
                 return this.aiBudget(action, org);
+            case 'ai:key':
+                return this.aiKey(action, org, context);
             case 'coolify:mail':
                 return this.coolifyMail(action, 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");
             case 'cms:site':
                 return this.cmsSite(action, org, context);
+            case 'coolify:agora':
+                return this.coolifyAgora(action, org, context);
+            case 'jobs:registration':
+                return this.jobsRegistration(action, org, context);
             default:
                 throw new Error(`FoundryStepExecutor has no dispatch for ${action.system}:${action.kind}`);
         }
@@ -600,27 +675,51 @@ export class FoundryStepExecutor {
         // people into the cms studio at `cms.<domain>`, not the org's own app
         // hostname -- `org.site.enabled` guarantees `org.domain` is set
         // (`org.ts`'s `validateSite`), the same guarantee `cmsHostnameFor`'s own
-        // doc comment relies on.
+        // doc comment relies on. #164: the fixed `agora` client (`diff.ts`'s
+        // `planAgoraClient`) is the same shape, always -- there is no
+        // `org.site.enabled`-style guard to check, since Agora is always on.
         const isCmsClient = action.key === 'cms' && org.site.enabled;
-        const hostname = isCmsClient ? cmsHostnameFor(org) : hostnameFor(org);
+        // The Agora client stays `appType: 'web'`: providers' `createOidcApp`
+        // makes every non-native app a public client (authorization code + PKCE,
+        // `OIDC_AUTH_METHOD_TYPE_NONE`, no secret), which is what Agora's browser
+        // SPA needs. Providers cannot create ZITADEL's `USER_AGENT` app kind.
+        const isAgoraClient = action.key === 'agora';
+        const hostname = isCmsClient
+            ? cmsHostnameFor(org)
+            : isAgoraClient
+                ? agoraHostnameFor(org)
+                : hostnameFor(org);
         // Native apps sign in via device code, with no redirect of their own
         // (auth/scripts/provision.mjs:475-497, prior art cited in the decisions
         // file) -- empty arrays rather than a web app's callback/logout URLs.
+        // #164: Agora's own callback path is `/callback`, not `/auth/callback`
+        // (agora/apps/agora/README.md, "Deploying an Agora": "The issuer's OAuth
+        // client needs `https://<agora address>/callback` as a redirect URI") --
+        // Agora is not built on `@wtfalch/auth`'s `NextAuth` mount the way every
+        // other web app this file provisions is.
+        const redirectUri = isAgoraClient
+            ? `https://${hostname}/callback`
+            : `https://${hostname}/auth/callback`;
         const created = await this.ports.zitadel.createOidcApp(zitadelOrgId, projectId, {
             name: action.key,
             appType,
-            redirectUris: appType === 'native' ? [] : [`https://${hostname}/auth/callback`],
+            redirectUris: appType === 'native' ? [] : [redirectUri],
             postLogoutRedirectUris: appType === 'native' ? [] : [`https://${hostname}/`],
         });
         if (appType === 'web') {
             // `coolifyApp`'s own `pushAppEnv` reads `APP_CLIENT_ID_SCOPE_KEY` to
             // push AUTH_CLIENT_ID (level-1 app-env campaign, gap P2); `cmsSite`
             // reads `CMS_CLIENT_ID_SCOPE_KEY` for the same env on the cms app
-            // (#139) -- public, not a secret, so a plain scope id, not
-            // `deliverSecret`. A native app signs in via device code with no
-            // cookie session of its own, so its clientId is never something an
-            // app's env needs.
-            context.recordScopeId(isCmsClient ? CMS_CLIENT_ID_SCOPE_KEY : APP_CLIENT_ID_SCOPE_KEY, created.clientId);
+            // (#139), and `coolifyAgora` reads `AGORA_CLIENT_ID_SCOPE_KEY` for
+            // `AGORA_CONFIG`'s own `clientId` (#164) -- public, not a secret, so a
+            // plain scope id, not `deliverSecret`. A native app signs in via
+            // device code with no cookie session of its own, so its clientId is
+            // never something an app's env needs.
+            context.recordScopeId(isCmsClient
+                ? CMS_CLIENT_ID_SCOPE_KEY
+                : isAgoraClient
+                    ? AGORA_CLIENT_ID_SCOPE_KEY
+                    : APP_CLIENT_ID_SCOPE_KEY, created.clientId);
         }
         return { resourceId: created.appId };
     }
@@ -740,11 +839,12 @@ export class FoundryStepExecutor {
         // unlike the database push above: every app has a hostname, and an
         // upsert of the same value on a later apply is a no-op, not a change.
         await this.pushAppEnv(appId, org, context);
-        // #140 rework: the hosted app's own Resend sending key and `MAIL_FROM`
-        // (only the app started by this same step, per the design's "only apps
-        // that send mail get it" -- cms and calls do not). A no-op until
-        // `coolify:mail` has actually registered a Resend domain for this org.
-        await this.ensureAppResendKey(appId, org, context, Boolean(existing));
+        // #140 rework (2026-09-28 lettermint-org-mail swap): the hosted app's own
+        // Lettermint project, domain restriction and `MAIL_FROM` (only the app
+        // started by this same step, per the design's "only apps that send mail
+        // get it" -- cms and calls do not). A no-op until `coolify:mail` has
+        // actually resolved a mail domain for this org.
+        await this.ensureAppLettermintMail(appId, org, context, Boolean(existing));
         return { resourceId: appId };
     }
     /**
@@ -919,32 +1019,40 @@ export class FoundryStepExecutor {
         return randomBytes(32).toString('base64');
     }
     /**
-     * #140 rework: the hosted app's own Resend sending key, pushed as
-     * `RESEND_API_KEY` straight into the app's env, the one place its token
-     * ever lives (Resend shows a key's token once, at creation). A no-op until
-     * `coolify:mail` has recorded a {@link RESEND_DOMAIN_ID_SCOPE_KEY} for this
-     * org; the next apply fills it in once `coolify:mail` runs first
+     * #140 rework (2026-09-28 lettermint-org-mail swap, "Core rule" +
+     * "Credential model"): all of the org's Lettermint work now lives here,
+     * in the app step, since the first project -- and so the first domain
+     * restriction -- can only exist once the token has a home (the app env). A
+     * no-op until `coolify:mail` has recorded {@link MAIL_DOMAIN_SCOPE_KEY} for
+     * this org; the next apply fills it in once `coolify:mail` runs first
      * (`diff.ts`'s `computePlanDetail` order).
      *
-     * The key is named `<slug>-app@<resendDomainId>`, so a key limited to a
-     * mail domain the org no longer uses (a `usesDomain` flip moves it between
-     * `org.domain` and `<slug>.<apex>`) never passes for the current one.
-     * `RESEND_API_KEY_ID` sits beside the token in the env -- an id, not a
-     * secret -- so the env can say which key its token belongs to.
+     * Order, exactly as the swap's "Core rule" states it: ensure the
+     * `<slug>-app` project, ensure the mail domain, restrict that domain to the
+     * org's own projects, publish its DNS records, trigger verification, then
+     * delete every stale `<slug>-app` project. New projects are created and the
+     * domain restricted to them before any old project is deleted, so the
+     * restriction list never becomes empty.
      *
-     * The mint rule (`.plans/2026-09-27-org-mail-resend-design.md` "One rule
-     * for minting"): healthy when the env holds a token and its
-     * `RESEND_API_KEY_ID` is the one key Resend lists under the current name.
-     * Otherwise one fresh key is minted and written to the env first, and only
-     * then is every other `<slug>-app@` key deleted -- a lost mint response, a
-     * duplicate, a hand-made key, and a previous domain's key all end the same
-     * way. An app that was already running is restarted before that delete,
-     * since a container reads its env only at start (`running`, the same
-     * reason {@link ensureLogVolume} restarts one). The restart is not
-     * awaited to completion, so the old container can briefly outlive its key.
+     * Mint rule ("Credential model"): the project is healthy when the app env
+     * holds `LETTERMINT_API_TOKEN` and Lettermint lists exactly one project
+     * named `<slug>-app` -- unlike Resend's key, a Lettermint project's name
+     * carries no domain id, since a domain switch is handled entirely by
+     * {@link LettermintPort.restrictDomainToProjects} below and never needs a
+     * fresh project. Otherwise a fresh project is created and its token
+     * written to the env first, and only then is every other `<slug>-app`
+     * project deleted -- a lost mint response and a duplicate both end the
+     * same way. An app that was already running is restarted before that
+     * delete, since a container reads its env only at start (`running`, the
+     * same reason {@link ensureLogVolume} restarts one).
+     *
+     * The domain's restriction is rebuilt from every project named `<slug>-app`
+     * or `<slug>-relay` (the relay project itself is #149, not built yet) --
+     * never patched, so it can never end up scoped only to a project about to
+     * be deleted.
      *
      * `MAIL_FROM` is upserted every time: it depends only on the mail domain
-     * `coolify:mail` resolved (`RESEND_MAIL_DOMAIN_SCOPE_KEY`).
+     * `coolify:mail` resolved.
      *
      * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
      * returned, never recorded in `serviceIds` (`recordScopeId`'s own doc
@@ -952,49 +1060,81 @@ export class FoundryStepExecutor {
      * same discipline `pushDatabaseUrl`'s doc comment states for a database's
      * own connection string.
      */
-    async ensureAppResendKey(appId, org, context, running) {
-        const recorded = context.recordedIds();
-        const domainId = recorded[RESEND_DOMAIN_ID_SCOPE_KEY];
-        if (!domainId)
+    async ensureAppLettermintMail(appId, org, context, running) {
+        const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
+        if (!mailDomain)
             return;
-        const prefix = `${org.slug}-app@`;
-        const keyName = `${prefix}${domainId}`;
-        const [ours, envs] = await Promise.all([
-            this.ports.resend.listApiKeys().then((keys) => keys.filter((k) => k.name.startsWith(prefix))),
+        const appName = `${org.slug}-app`;
+        const relayName = `${org.slug}-relay`;
+        const [projects, envs] = await Promise.all([
+            this.ports.lettermint.listProjects(),
             this.ports.coolify.listEnvs(appId),
         ]);
         const envValue = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
-        const current = ours.filter((k) => k.name === keyName);
-        const held = current.length === 1 ? current[0] : undefined;
-        const healthy = held !== undefined &&
-            Boolean(envValue('RESEND_API_KEY')) &&
-            envValue('RESEND_API_KEY_ID') === held.id;
+        const ours = projects.filter((p) => p.name === appName);
+        const held = ours.length === 1 ? ours[0] : undefined;
+        const healthy = held !== undefined && Boolean(envValue('LETTERMINT_API_TOKEN'));
+        let allProjects = projects;
+        let keepProjectId;
         const envUpdates = [];
-        let keep = healthy ? held?.id : undefined;
-        if (!healthy) {
-            const created = await this.ports.resend.createApiKey({
-                name: keyName,
-                permission: 'sending_access',
-                domainId,
-            });
-            keep = created.id;
-            envUpdates.push({ key: 'RESEND_API_KEY', value: created.token }, { key: 'RESEND_API_KEY_ID', value: created.id });
-        }
-        const mailDomain = recorded[RESEND_MAIL_DOMAIN_SCOPE_KEY];
-        if (mailDomain)
-            envUpdates.push({ key: 'MAIL_FROM', value: `no-reply@${mailDomain}` });
-        if (envUpdates.length > 0)
-            await this.ports.coolify.bulkUpsertEnvs(appId, envUpdates);
+        if (healthy && held) {
+            keepProjectId = held.id;
+        }
+        else {
+            const created = await this.ports.lettermint.createProject(appName);
+            keepProjectId = created.project.id;
+            allProjects = [...projects, created.project];
+            envUpdates.push({ key: 'LETTERMINT_API_TOKEN', value: created.token });
+        }
+        envUpdates.push({ key: 'MAIL_FROM', value: `no-reply@${mailDomain}` });
+        await this.ports.coolify.bulkUpsertEnvs(appId, envUpdates);
         // A running container read its env at start and still holds the old
-        // token, so a fresh key only reaches it through a restart -- before the
-        // old key is deleted below. A just-created app starts with the new env.
+        // token, so a fresh one only reaches it through a restart -- before the
+        // old project is deleted below. A just-created app starts with the new env.
         if (!healthy && running)
             await this.ports.coolify.restart(appId);
-        for (const key of ours) {
-            if (key.id !== keep)
-                await this.ports.resend.deleteApiKey(key.id);
+        const existing = await this.findExactLettermintDomain(mailDomain);
+        // A crash between here and `restrictDomainToProjects` below is safe even
+        // for a freshly created domain: DNS is only published, and verification
+        // only triggered, after the restriction -- so an unrestricted domain
+        // cannot verify and cannot send, whichever project owns it.
+        const domain = existing
+            ? await this.ports.lettermint.getDomain(existing.id)
+            : await this.ports.lettermint.createDomain(mailDomain);
+        const scopedProjectIds = allProjects
+            .filter((p) => p.name === appName || p.name === relayName)
+            .map((p) => p.id);
+        await this.ports.lettermint.restrictDomainToProjects(domain.id, scopedProjectIds);
+        const zone = await this.ports.cloudflare.findZoneByApex(mailDomain);
+        if (!zone) {
+            throw new Error(`coolify:app for ${org.slug}: no Cloudflare zone found for ${mailDomain}`);
+        }
+        await this.publishLettermintDnsRecords(zone.id, domain.dnsRecords);
+        await this.ports.lettermint.verifyDomain(domain.id);
+        for (const project of allProjects) {
+            if (project.name === appName && project.id !== keepProjectId) {
+                await this.ports.lettermint.deleteProject(project.id);
+            }
         }
     }
+    /**
+     * Review finding (post-#140 rework): {@link LettermintPort.findDomain}'s
+     * own match is partial and case-insensitive, so a raw result can be a
+     * lookalike (`notacme.com`, `mail.acme.com`) rather than `name` itself --
+     * and every caller here full-replaces the found domain's project
+     * restriction ({@link LettermintPort.restrictDomainToProjects}), so taking
+     * a lookalike as a match would let it be taken over. Every domain lookup
+     * in this class (`ensureAppLettermintMail`, `parkLettermintMail`,
+     * `deleteStaleLettermintDomain`) goes through this instead of the port
+     * directly, and treats anything but an exact, case-insensitive match as
+     * not found.
+     */
+    async findExactLettermintDomain(name) {
+        const found = await this.ports.lettermint.findDomain(name);
+        if (!found || found.domain.toLowerCase() !== name.toLowerCase())
+            return undefined;
+        return found;
+    }
     /**
      * `plan/diff.ts`'s `planSite` (#116, slicing #99's "provision the cms app,
      * database and site app per org"): the 2026-09-25 decision
@@ -1661,6 +1801,156 @@ export class FoundryStepExecutor {
             return null;
         return randomBytes(32).toString('hex');
     }
+    // ---- agora (#164) --------------------------------------------------------
+    /**
+     * `plan/diff.ts`'s `planAgora`: provisions the org's own Agora
+     * (https://github.com/wtfalch/agora) as one more Coolify application, from
+     * that repo's `apps/agora/Dockerfile` ({@link AGORA_REPO}'s doc comment),
+     * and pushes its env. `findOrCreateCallsApp` is reused as-is for the
+     * find-by-name-then-start-or-create shape, like {@link coolifyCallsService}.
+     * There is no park branch: Agora is always on.
+     *
+     * The env comes from `plan/agora.ts`'s `desiredAgoraEnv`, the same function
+     * the plan compares the live app against, so a re-plan after this step is
+     * empty. The step never writes a partial config: when any input is missing
+     * (the org's ZITADEL org id or Agora client id, or an issuer or
+     * mail/messaging project id the host does not supply,
+     * `AgoraHostPort`, read by the plan) it throws naming each one, before
+     * it creates anything.
+     *
+     * `AGORA_CANONICAL_HOST` is always pushed. `AGORA_MAIL_UPSTREAM`/
+     * `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.
+     */
+    async coolifyAgora(action, org, context) {
+        // The host values the plan read, carried in the step: never read again
+        // here, so the env written is the env the plan showed.
+        const host = action.desired.host;
+        if (!host) {
+            throw new Error(`Agora for ${org.slug} cannot be configured: the step carries no host values`);
+        }
+        const { env, missing } = desiredAgoraEnv(org, context.recordedIds(), host);
+        if (missing.length > 0) {
+            throw new Error(`Agora for ${org.slug} cannot be configured: missing ${missing.join(', ')}. Nothing was written.`);
+        }
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const name = `${org.slug}-agora`;
+        const server = await this.resolveServer();
+        const githubApp = await this.ports.coolify.requireGithubApp();
+        const app = await this.findOrCreateCallsApp(name, 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: AGORA_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name,
+            domains: agoraHostnameFor(org),
+            dockerfile_location: AGORA_APP_DOCKERFILE,
+        }));
+        // Every app foundry deploys keeps its own logs (#75), reused as-is here.
+        await this.ensureLogVolume(app.appId, org, app.existed);
+        await this.ports.coolify.bulkUpsertEnvs(app.appId, Object.entries(env).map(([key, value]) => ({ key, value })));
+        return { resourceId: app.appId };
+    }
+    // ---- jobs (#173) ---------------------------------------------------------
+    /**
+     * `plan/diff.ts`'s `planJobsRegistration`: registers the org's own app with
+     * the platform's jobs scheduler (`JobsSchedulerPort.registerProject`, the
+     * scheduler's `POST /admin/projects`), then hands the freshly minted
+     * `secret` and `syncKey` to the host through `deliverSecret` -- but only
+     * when this call actually minted them. The admin API is itself idempotent
+     * by `(name, baseUrl)`: a repeat call for an already-registered project
+     * resolves with just the `id`, and this never re-delivers a secret or sync
+     * key it did not just mint, the same "registers an app once" rule
+     * `diff.ts`'s own plan-level gate (recordedIds, mirroring `planOwner`)
+     * already provides on a normal re-plan -- this check is what keeps that
+     * true even if this step somehow runs twice on the same apply.
+     *
+     * Never logs, returns or records either credential (this file's own top
+     * doc comment's "a secret is never a step's return value" rule) -- only the
+     * scheduler's own non-secret project id comes back as `resourceId`.
+     */
+    /** #177: the host's own port when it supplies one, else the platform's, built from its address and held key. */
+    async filesPort() {
+        const port = this.ports.filesOrganisation ?? (await this.ports.platformOrg?.files());
+        if (!port)
+            throw new Error('files: this executor was built without a files port (#177)');
+        return port;
+    }
+    async aiPort() {
+        const port = this.ports.aiOrganisation ?? (await this.ports.platformOrg?.ai());
+        if (!port)
+            throw new Error('ai: this executor was built without an ai port (#177)');
+        return port;
+    }
+    async jobsPort(org) {
+        const port = this.ports.jobsScheduler ?? (await this.ports.platformOrg?.jobs());
+        if (!port) {
+            throw new Error(`jobs:registration for ${org.slug}: this executor was built without a jobsScheduler port (#173)`);
+        }
+        return port;
+    }
+    async jobsRegistration(action, org, context) {
+        const scheduler = await this.jobsPort(org);
+        const name = action.desired.name;
+        const baseUrl = action.desired.baseUrl;
+        const registered = await scheduler.registerProject({ name, baseUrl });
+        // A repeat call for an already-registered project carries neither
+        // credential: nothing to deliver.
+        if (!registered.secret && !registered.syncKey)
+            return { resourceId: registered.id };
+        // The project now exists and its credentials are shown exactly once, so
+        // the id is recorded before anything else can fail: a step's return value
+        // is only recorded on success, and without this a failed delivery would
+        // leave the next run's `registerProject` answering with just `{ id }`,
+        // the step recording success, and the sync key lost for good.
+        // `planJobsRegistration` reports this id as blocked instead of planning
+        // the step again.
+        context.recordScopeId(JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, registered.id);
+        // Written now, so a crash during delivery cannot lose the id either.
+        await context.persistScopeIds();
+        if (!registered.secret || !registered.syncKey) {
+            // Only one half came back; the other can never be fetched again.
+            throw new Error(`jobs:registration for ${org.slug}: project ${registered.id} was registered but the scheduler returned only one of its secret and sync key; deregister it in the scheduler before registering again`);
+        }
+        const failed = [];
+        for (const [part, value] of [
+            ['secret', registered.secret],
+            ['syncKey', registered.syncKey],
+        ]) {
+            if (!(await this.deliverWithRetry(`jobs:registration:${org.slug}:${part}`, value))) {
+                failed.push(part);
+            }
+        }
+        if (failed.length > 0) {
+            // Names the project id only; the underlying errors are dropped in case
+            // one echoes a credential.
+            throw new Error(`jobs:registration for ${org.slug}: project ${registered.id} was registered but its ${failed.join(' and ')} could not be delivered after ${JOBS_DELIVERY_ATTEMPTS} attempts; deregister it in the scheduler before registering again`);
+        }
+        return { resourceId: registered.id };
+    }
+    /** `deliverSecret`, tried up to {@link JOBS_DELIVERY_ATTEMPTS} times; true once one attempt succeeds. */
+    async deliverWithRetry(ref, value) {
+        for (let attempt = 1; attempt <= JOBS_DELIVERY_ATTEMPTS; attempt++) {
+            try {
+                await this.ports.deliverSecret(ref, value);
+                return true;
+            }
+            catch {
+                // Retried; the error is dropped in case it echoes the secret.
+            }
+        }
+        return false;
+    }
     // ---- cloudflare --------------------------------------------------------
     async cloudflareTunnel(action, org, context) {
         if (action.desired.enabled === false) {
@@ -1739,36 +2029,101 @@ export class FoundryStepExecutor {
      * `plan/diff.ts`'s `planMail`: gives an org mail, moves it between modes,
      * or parks it on the one shared Stalwart instance (`this.ports.mail`,
      * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` bound), then
-     * publishes whatever DNS records the call returns, then registers the same
-     * mail domain with Resend (#138) -- the shared Stalwart relays every
-     * outbound message through Resend, and Resend refuses mail from a domain
-     * it has not verified. No step here ever deletes the app's Resend key:
-     * `diff.ts`'s `planMail` plans nothing for mode `'off'`, so turning mail
-     * off leaves the key live, like every other resource foundry stops
-     * managing (#10). Switching the mail domain replaces the key instead
-     * (`ensureAppResendKey`).
+     * publishes whatever Stalwart DNS records the call returns, and records the
+     * resolved mail domain as a scope id ({@link MAIL_DOMAIN_SCOPE_KEY}).
+     * 2026-09-28 lettermint-org-mail swap: this step no longer calls the mail
+     * relay provider at all -- registering the domain, restricting it and
+     * publishing its own DNS records all moved to the app step
+     * (`ensureAppLettermintMail`, "Core rule"), since the first project can
+     * only exist once the token has a home. Parking mail (mode `'off'`) does
+     * still reach Lettermint, the one exception: {@link parkLettermintMail}
+     * deletes the org's own projects and then its domain, so a domain never
+     * ends up restricted only to dead projects.
+     *
+     * Review finding: a mail domain switch (`org.domain` changes, or
+     * `usesDomain` flips) must also delete the *old* Lettermint domain here,
+     * before recording the new one -- otherwise it stays registered and
+     * restricted to the org's still-live `<slug>-app` project, which could
+     * then keep sending as it forever. {@link deleteStaleLettermintDomain}
+     * does this by comparing the previously recorded domain (case-insensitive)
+     * against the one this apply just resolved.
+     *
+     * #162: once `applyOrgMail` has given the org a domain, {@link ensureOwnerMailbox}
+     * gives its declared owner a mailbox on it, so Agora's Mail section is not
+     * empty for them after the org's first apply.
      */
     async coolifyMail(action, org, context) {
         const mode = action.desired.mode;
         const usesDomain = action.desired.usesDomain;
-        const options = { apex: MAIL_APEX, mailHost: MAIL_HOST };
+        // #177: `diff.ts`'s `planMail` carries the platform's own apex/mail host
+        // in `desired` once it is wired -- "the executor writes exactly these
+        // host values, so what the plan showed is what gets applied" (`planAgora`'s
+        // own rule). `MAIL_APEX`/`MAIL_HOST` remain the fallback for a plan built
+        // without a platform (this file's own doc comment on those constants).
+        const options = {
+            apex: action.desired.apex ?? MAIL_APEX,
+            mailHost: action.desired.mailHost ?? MAIL_HOST,
+        };
         if (mode === 'off') {
             await this.ports.mail.parkOrgMail(mailOrgFor(org, usesDomain, 'hosted'), options);
+            await this.parkLettermintMail(org, context);
             return undefined;
         }
-        const result = await this.ports.mail.applyOrgMail(mailOrgFor(org, usesDomain, mode), options);
-        const zoneId = await this.publishMailDnsRecords(org, result);
-        await this.registerResendDomain(result.domain, zoneId, context);
+        const mailOrg = mailOrgFor(org, usesDomain, mode);
+        const result = await this.ports.mail.applyOrgMail(mailOrg, options);
+        await this.publishMailDnsRecords(org, result);
+        await this.deleteStaleLettermintDomain(context, result.domain);
+        context.recordScopeId(MAIL_DOMAIN_SCOPE_KEY, result.domain);
+        // #177: what this step wrote from the platform, so `planMail` can see a later change.
+        context.recordScopeId(ORG_MAIL_APPLIED_APEX_SCOPE_KEY, options.apex);
+        context.recordScopeId(ORG_MAIL_APPLIED_HOST_SCOPE_KEY, options.mailHost);
+        await this.ensureOwnerMailbox(org, mailOrg, result.domain, context);
         return { resourceId: result.domain };
     }
+    /**
+     * #162: gives the org's declared owner a mailbox on its just-resolved mail
+     * domain, the one address this executor mints on its own
+     * ({@link MAIL_OWNER_LOCAL_PART}'s own doc comment). A no-op when the org
+     * has no owner yet, or once {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is already
+     * recorded -- checked first so a second apply never calls
+     * `MailPort.createMailbox` again, rather than relying on that port method's
+     * own duplicate refusal.
+     */
+    async ensureOwnerMailbox(org, mailOrg, domain, context) {
+        if (!org.owner)
+            return;
+        if (context.recordedIds()[MAIL_OWNER_MAILBOX_SCOPE_KEY])
+            return;
+        const address = `${MAIL_OWNER_LOCAL_PART}@${domain}`;
+        await this.ports.mail.createMailbox(mailOrg, {
+            address,
+            name: `${org.owner.givenName} ${org.owner.familyName}`,
+        });
+        context.recordScopeId(MAIL_OWNER_MAILBOX_SCOPE_KEY, address);
+    }
+    /**
+     * Deletes the org's previous Lettermint domain once the mail domain it was
+     * registered under has changed -- otherwise it stays registered and
+     * restricted to the org's still-live `<slug>-app` project after the switch
+     * (review finding, post-#140 rework). A no-op on first apply (no previous
+     * domain recorded) and on a same-domain re-apply (compared
+     * case-insensitively, the same rule {@link findExactLettermintDomain}
+     * applies to the lookup itself).
+     */
+    async deleteStaleLettermintDomain(context, newDomain) {
+        const previous = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
+        if (!previous || previous.toLowerCase() === newDomain.toLowerCase())
+            return;
+        const stale = await this.findExactLettermintDomain(previous);
+        if (stale)
+            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. Returns
-     * the zone id so `registerResendDomain` publishes Resend's own records on
-     * the same zone without a second lookup.
+     * mints the key on a background task; the next apply publishes it.
      */
     async publishMailDnsRecords(org, result) {
         const cf = this.ports.cloudflare;
@@ -1786,53 +2141,50 @@ export class FoundryStepExecutor {
                 await cf.createDnsRecord(zone.id, rec);
             }
         }
-        return zone.id;
     }
     /**
-     * #138: registers `domain` with Resend -- the custom domain, or
-     * `<slug>.<apex>` for a level-1 org, exactly what `publishMailDnsRecords`
-     * just published the Stalwart records for. Idempotent by name, the same way
-     * `applyOrgMail` itself is: found by `findDomain` rather than any id this
-     * class recorded, so a crash between here and the next apply just repeats
-     * the same find-or-create. Never blocks on DNS propagation (task brief):
-     * `verifyDomain` asks Resend to re-check once, and its returned status is
-     * neither polled nor awaited -- an unverified domain here is exactly what
-     * the next apply corrects.
-     *
-     * #140 rework: mints no key of its own any more. It records the domain's
-     * own id and the resolved mail domain as scope ids so `ensureAppResendKey`
-     * (`coolifyApp`) can mint the app's own `<slug>-app@<domainId>` key once the app
-     * exists, without this step or the app step calling Resend to look the
-     * domain back up.
+     * Parking mail (2026-09-28 lettermint-org-mail swap, "Core rule": "Parking
+     * mail deletes the org's projects and then the domain itself, so no
+     * restriction points only at dead projects"). Deletes every Lettermint
+     * project named `<slug>-app` or `<slug>-relay`, then the org's own
+     * Lettermint domain, if one was found -- in that order, never the reverse.
+     * A no-op until a previous apply recorded {@link MAIL_DOMAIN_SCOPE_KEY}:
+     * nothing was ever provisioned for an org whose mail went straight from
+     * never-applied to off.
      */
-    async registerResendDomain(domain, zoneId, context) {
-        const existing = await this.ports.resend.findDomain(domain);
-        const resendDomain = existing
-            ? await this.ports.resend.getDomain(existing.id)
-            : await this.ports.resend.createDomain(domain);
-        await this.publishResendDnsRecords(zoneId, resendDomain.records ?? []);
-        await this.ports.resend.verifyDomain(resendDomain.id);
-        context.recordScopeId(RESEND_DOMAIN_ID_SCOPE_KEY, resendDomain.id);
-        context.recordScopeId(RESEND_MAIL_DOMAIN_SCOPE_KEY, domain);
+    async parkLettermintMail(org, context) {
+        const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
+        if (!mailDomain)
+            return;
+        const names = new Set([`${org.slug}-app`, `${org.slug}-relay`]);
+        const projects = await this.ports.lettermint.listProjects();
+        for (const project of projects) {
+            if (names.has(project.name))
+                await this.ports.lettermint.deleteProject(project.id);
+        }
+        const domain = await this.findExactLettermintDomain(mailDomain);
+        if (domain)
+            await this.ports.lettermint.deleteDomain(domain.id);
     }
     /**
-     * Upserts each DNS record Resend's domain names, the same find-then-upsert
-     * `publishMailDnsRecords` above uses for Stalwart's own records -- except
-     * SPF is merged into whatever record that call just published rather than
-     * created a second time (RFC 7208 treats two `v=spf1` TXT records on one
-     * name as a permerror and silently breaks SPF for every sender on the
-     * domain), and an existing `_dmarc` record is never overwritten. Prior art:
-     * `wtfalch/app-template`'s `bootstrap/steps/resend-email.ts`.
+     * Upserts each DNS record Lettermint's domain names, the same find-then-
+     * upsert `publishMailDnsRecords` above uses for Stalwart's own records --
+     * except an existing `_dmarc` record is never overwritten (a stricter
+     * policy an org already set, `p=quarantine`/`p=reject`, should not be
+     * relaxed back to Lettermint's own default). Resend's own domain also
+     * carried an apex `SPF` TXT record that had to be merged into whatever SPF
+     * record already existed there (RFC 7208: two `v=spf1` TXT records on one
+     * name is a permerror); Lettermint's own DNS records
+     * (`.plans/2026-09-28-lettermint-api.md` §3) have no such record -- its
+     * `purpose` enum is `return_path`/`dmarc`/`dkim_legacy`/`dkim_primary`/
+     * `dkim_secondary`, none of them SPF -- so that merge has no case left to
+     * handle here and is dropped rather than kept as dead code.
      */
-    async publishResendDnsRecords(zoneId, records) {
+    async publishLettermintDnsRecords(zoneId, records) {
         const cf = this.ports.cloudflare;
         for (const record of records) {
-            if (record.type === 'TXT' && record.value.toLowerCase().startsWith('v=spf1')) {
-                await this.mergeResendSpfRecord(cf, zoneId, record);
-                continue;
-            }
             if (record.type === 'TXT' && record.value.toLowerCase().startsWith('v=dmarc1')) {
-                await this.ensureResendDmarcRecord(cf, zoneId, record);
+                await this.ensureLettermintDmarcRecord(cf, zoneId, record);
                 continue;
             }
             const [existing] = await cf.findDnsRecord(zoneId, record.name, record.type);
@@ -1845,36 +2197,12 @@ export class FoundryStepExecutor {
             }
         }
     }
-    /**
-     * Inserts Resend's `include:` token into whatever SPF record
-     * `publishMailDnsRecords` already published for this name, instead of
-     * creating a second `v=spf1` TXT record -- the classic foot-gun that makes
-     * every receiver treat SPF as a permerror and skip it entirely.
-     */
-    async mergeResendSpfRecord(cf, zoneId, record) {
-        const includeToken = record.value.match(/include:\S+/i)?.[0] ?? 'include:_spf.resend.com';
-        const existingSpf = (await cf.findDnsRecord(zoneId, record.name, 'TXT')).find((r) => r.content.toLowerCase().startsWith('v=spf1'));
-        if (!existingSpf) {
-            await cf.createDnsRecord(zoneId, { type: 'TXT', name: record.name, content: record.value });
-            return;
-        }
-        if (existingSpf.content.toLowerCase().includes(includeToken.toLowerCase()))
-            return;
-        const merged = /\s+[~\-?+]all\s*$/.test(existingSpf.content)
-            ? existingSpf.content.replace(/\s+([~\-?+])all\s*$/, ` ${includeToken} $1all`)
-            : `${existingSpf.content.trim()} ${includeToken}`;
-        await cf.updateDnsRecord(zoneId, existingSpf.id, {
-            type: 'TXT',
-            name: record.name,
-            content: merged,
-        });
-    }
     /**
      * Never overwrites an existing `_dmarc` record -- a stricter policy an org
      * already set (`p=quarantine`/`p=reject`) should not be relaxed back to
-     * Resend's own `p=none` default.
+     * Lettermint's own `p=none` default.
      */
-    async ensureResendDmarcRecord(cf, zoneId, record) {
+    async ensureLettermintDmarcRecord(cf, zoneId, record) {
         const hasDmarc = (await cf.findDnsRecord(zoneId, record.name, 'TXT')).some((r) => r.content.toLowerCase().startsWith('v=dmarc1'));
         if (hasDmarc)
             return;
@@ -1889,7 +2217,8 @@ export class FoundryStepExecutor {
      * idempotent by find-or-create, not by checking `recordedIds` first.
      */
     async filesOrganisation(action, org) {
-        const provisioned = await this.ports.filesOrganisation.provisionOrganisation({
+        const files = await this.filesPort();
+        const provisioned = await files.provisionOrganisation({
             organisationId: org.id,
             ceilingBytes: action.desired.ceilingBytes ?? null,
             ceilingMicros: action.desired.ceilingMicros ?? null,
@@ -1897,9 +2226,9 @@ export class FoundryStepExecutor {
         return { resourceId: provisioned.organisationId };
     }
     async filesStorage(action, org) {
-        const limits = this.ports.filesLimitsFor(org.id);
-        await limits.setQuota(action.desired.limitBytes ?? null);
-        await limits.setBudget(action.desired.limitMicros ?? null);
+        const files = await this.filesPort();
+        await files.setQuota(org.id, action.desired.limitBytes ?? null);
+        await files.setBudget(org.id, action.desired.limitMicros ?? null);
         return { resourceId: org.id };
     }
     /**
@@ -1910,11 +2239,12 @@ export class FoundryStepExecutor {
      * every time regardless of whether they already ran.
      */
     async aiOrganisation(action, org) {
-        const provisioned = await this.ports.aiOrganisation.provisionOrganisation({
+        const ai = await this.aiPort();
+        const provisioned = await ai.provisionOrganisation({
             organisationId: org.id,
             limitMicros: action.desired.limitMicros ?? null,
         });
-        await this.ports.aiOrganisation.setOrganisationOffers(org.id, action.desired.offers ?? []);
+        await ai.setOrganisationOffers(org.id, action.desired.offers ?? []);
         return { resourceId: provisioned.organisationId };
     }
     async aiBudget(action, org) {
@@ -1925,10 +2255,48 @@ export class FoundryStepExecutor {
             // (Finding, this campaign's report).
             throw new Error(`ai:budget for ${org.slug}: AI's updateBudget has no uncapped representation (UpdateBudget.limitMicros is a required string); declare a numeric limit until AI's API adds one`);
         }
-        const limits = this.ports.aiLimitsFor(org.id);
-        await limits.updateBudget({ keyId: null, limitMicros });
+        const ai = await this.aiPort();
+        await ai.updateBudget(org.id, { keyId: null, limitMicros });
         return { resourceId: org.id };
     }
+    /**
+     * #80 step 3: mints the org's own ai key, once, and hands its one-time
+     * secret straight to {@link FoundryStepExecutorPorts.deliverSecret} --
+     * never returned, stored in `serviceIds` or logged, the same discipline
+     * `zitadelApp`'s own `created.clientSecret` follows. `diff.ts`'s
+     * `planAiKey` never plans this step again once its resource id
+     * (the key's id, not its secret) is recorded, since ai's own API offers no
+     * way to check for an already-minted key.
+     */
+    async aiKey(action, org, context) {
+        const ai = await this.aiPort();
+        const issued = await ai.issueOrganisationKey(org.id, {
+            name: action.desired.name,
+            expiresDays: action.desired.expiresDays,
+            permissions: action.desired.permissions ?? [],
+        });
+        // Recorded before the secret is delivered: a step's return value is only
+        // recorded on success, so a delivery that throws would otherwise lose
+        // the id and the retry would mint a second, orphaned key. `planAiKey`
+        // treats this id as undelivered until the returned resource id (which
+        // only a delivered key gets) is recorded too.
+        context.recordScopeId(AI_KEY_UNDELIVERED_SCOPE_KEY, issued.id);
+        // Written now, so a crash during delivery cannot lose the id either.
+        await context.persistScopeIds();
+        let lastError;
+        for (let attempt = 1; attempt <= AI_KEY_DELIVERY_ATTEMPTS; attempt++) {
+            try {
+                await this.ports.deliverSecret(`ai:key:${org.slug}`, issued.secret);
+                return { resourceId: issued.id };
+            }
+            catch (e) {
+                lastError = e;
+            }
+        }
+        // Names the key id only; the underlying error is dropped in case it
+        // 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`);
+    }
     // ---- destroy -------------------------------------------------------------
     /**
      * {@link StepDestroyer.destroy}: deletes the one resource
@@ -2004,7 +2372,7 @@ export class FoundryStepExecutor {
  * status in: the first `→ `, after the client, method and path, and before
  * `:`. It never scans the path or the response body.
  */
-function isNotFoundError(error) {
+export function isNotFoundError(error) {
     const status = error?.status;
     if (typeof status === 'number')
         return status === 404;