@wtfalch/foundry 0.4.0 → 0.6.0

package/dist/plan/executor.js

@@ -1,7 +1,10 @@
 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 { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
+import { ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, } from './platform-diff.js';
 // ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
@@ -79,6 +82,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;
 }
 /**
@@ -99,10 +109,11 @@ export function healthUrls(org) {
 }
 /**
  * The `OrgMailOrg` argument for `applyOrgMail`/`parkOrgMail`: an org with
- * `mail.usesDomain` off has no domain of its own, so it is level 1 on
- * `MAIL_APEX` and its mode is forced to `'hosted'` — `@wtfalch/email`'s own
- * `resolveDomain` refuses any other mode for a domain-less org, and a
- * level-1 `{slug}.{apex}` domain always has Stalwart's MX (foundry#7 "Mail").
+ * `mail.usesDomain` off has no domain of its own, so it is level 1 on the
+ * platform's own mail apex (`coolifyMail`'s `options.apex`) and its mode is
+ * forced to `'hosted'` — `@wtfalch/email`'s own `resolveDomain` refuses any
+ * other mode for a domain-less org, and a level-1 `{slug}.{apex}` domain
+ * always has Stalwart's MX (foundry#7 "Mail").
  */
 function mailOrgFor(org, usesDomain, mode) {
     return usesDomain && org.domain
@@ -121,7 +132,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 +198,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
@@ -198,13 +228,6 @@ const CMS_SITE_APP_DOCKERFILE = 'apps/site/Dockerfile';
  * restated rather than shared across the two files.
  */
 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`.
- */
-const MAIL_APEX = 'wtfalch.dev';
-const MAIL_HOST = 'mail.wtfalch.dev';
 /**
  * The recorded OIDC app's `clientId` (level-1 app-env campaign, gap P2) —
  * not a `system:kind:key` resource id (that slot already holds the app's
@@ -252,24 +275,73 @@ 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';
+/**
+ * #149 review finding: `MailPort.hasOrgRelay` only confirms Stalwart's route
+ * holds *a* secret, not that it is the one {@link FoundryStepExecutor
+ * .ensureOrgLettermintRelay} itself wrote for the project Lettermint
+ * currently lists under `<slug>-relay` -- a route a stale run wrote for a
+ * 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
+ * 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.
  */
-const RESEND_DOMAIN_ID_SCOPE_KEY = 'resend_domain_id';
+const ORG_MAIL_RELAY_SCOPE_KEY = 'mail_relay';
 /**
- * #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.
+ * #230: the role mailboxes {@link ensureRoleMailboxes} has created, as one
+ * flat scope id holding their full addresses (`local@domain`, lowercased, so a
+ * mail domain change owes the new domain its own set) joined by `,`
+ * (`validateMail` refuses a `,` in a name, so the join is unambiguous). Updated after each
+ * mailbox, so a crash part-way through never recreates the ones already
+ * made. `plan/diff.ts` keeps its own copy of this literal.
  */
-const RESEND_MAIL_DOMAIN_SCOPE_KEY = 'resend_mail_domain';
+const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
+/**
+ * #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 JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = 'jobs_registration_undelivered';
+/** How many times `jobsRegistration` tries each `deliverSecret` before giving up. */
+const JOBS_DELIVERY_ATTEMPTS = 3;
 /**
  * `coolifyCalls` provisions four resources from one `coolify:calls` step
  * (#128) — the same one-step, several-resource shape `cmsSite` already solves
@@ -342,7 +414,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 +462,20 @@ 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: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");
             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 +680,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 +844,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 };
     }
     /**
@@ -870,9 +975,10 @@ 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 (waits on an auth broker registration API) and
-     * DATABASE_URL_OWNER (a runtime-role split not built yet, `pushDatabaseUrl`'s
-     * own doc comment) are out of scope here (task brief).
+     * 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) and DATABASE_URL_OWNER (a runtime-role split not built yet,
+     * `pushDatabaseUrl`'s own doc comment) are out of scope here (task brief).
      */
     async pushAppEnv(appId, org, context) {
         const recorded = context.recordedIds();
@@ -919,32 +1025,43 @@ 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.
+     *
+     * 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 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.
+     * 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 and `org.mail.noReplyLocalPart` (#162, decided
+     * 2026-09-29 -- defaults to `'no-reply'`, restated here rather than
+     * imported from `org.ts`'s `DEFAULT_NO_REPLY_LOCAL_PART`, this file's own
+     * `LOG_DIR`-style convention).
      *
      * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
      * returned, never recorded in `serviceIds` (`recordScopeId`'s own doc
@@ -952,48 +1069,189 @@ 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 [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: `${org.mail.noReplyLocalPart ?? '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);
+        await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects);
+        for (const project of allProjects) {
+            if (project.name === appName && project.id !== keepProjectId) {
+                await this.ports.lettermint.deleteProject(project.id);
+            }
+        }
+    }
+    /**
+     * #149: mints this org's own Lettermint relay credential and writes it to
+     * Stalwart via `MailPort.applyOrgRelay`, the same mint rule
+     * {@link ensureAppLettermintMail} already uses for the org's app token --
+     * "healthy" means Stalwart's own route exists ({@link MailPort.hasOrgRelay}),
+     * AND Lettermint lists a project named `<slug>-relay` whose id
+     * {@link ORG_MAIL_RELAY_SCOPE_KEY} records for this
+     * exact mail domain (review finding: a route with a secret and a
+     * same-named project both present is not enough -- the project could be a
+     * lost-and-reprovisioned one this step never wrote a route for, and a mail
+     * domain switch must re-point the route rather than read as healthy
+     * forever because the old route still has a secret in it). A route with no
+     * live project behind it, a project the route's own secret never reached,
+     * or a recorded project id/domain that no longer matches, are all exactly
+     * as unhealthy as neither existing.
+     *
+     * A fresh project is created and its token written to Stalwart first, and
+     * only then is every other `<slug>-relay` project deleted -- a lost route
+     * and a duplicate project both end the same way. The new project's domain
+     * restriction runs before the token is written, so a failure there never
+     * touches the working route. Review finding: if either the
+     * domain-restriction step or `applyOrgRelay` throws after a
+     * fresh project was minted, that project is deleted before the error
+     * propagates -- otherwise every retry sees more than one `<slug>-relay`
+     * project and mints yet another one, growing the orphan count without
+     * bound.
+     *
+     * `coolify:mail` runs before `coolify:app` (`diff.ts`'s own step order), so
+     * this is very often the first of the two to reach the org's Lettermint
+     * domain: {@link ensureLettermintDomainRestriction} registers and restricts
+     * it the same way the app step does, rather than assuming it already
+     * exists -- the domain must never end up unrestricted, whichever step gets
+     * there first.
+     */
+    async ensureOrgLettermintRelay(org, mailOrg, mailDomain, context) {
+        const relayName = `${org.slug}-relay`;
+        const [projects, hasRelay] = await Promise.all([
+            this.ports.lettermint.listProjects(),
+            this.ports.mail.hasOrgRelay(mailOrg),
+        ]);
+        // The recorded project, not "the only one": a leftover duplicate whose
+        // delete keeps failing must not force a fresh mint on every apply.
+        const recordedRelay = context.recordedIds()[ORG_MAIL_RELAY_SCOPE_KEY];
+        const held = projects.find((p) => p.name === relayName && `${p.id}@${mailDomain}` === recordedRelay);
+        const healthy = held !== undefined && hasRelay;
+        let allProjects = projects;
+        let keepProjectId;
+        if (healthy && held) {
+            keepProjectId = held.id;
+            await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects);
+        }
+        else {
+            const created = await this.ports.lettermint.createProject(relayName);
+            keepProjectId = created.project.id;
+            allProjects = [...projects, created.project];
+            try {
+                // Everything that can fail for the new project runs before the token
+                // reaches Stalwart: a failure here leaves the working route alone.
+                // The restriction covers old and new projects, so the old one keeps
+                // sending until the route switches.
+                await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects);
+                await this.ports.mail.applyOrgRelay(mailOrg, created.token);
+            }
+            catch (err) {
+                await this.discardLettermintProject(created.project.id);
+                throw err;
+            }
+            context.recordScopeId(ORG_MAIL_RELAY_SCOPE_KEY, `${keepProjectId}@${mailDomain}`);
+            // Written now: a crash before the end-of-run write would leave the old
+            // project recorded, and the next apply would sweep the one the route uses.
+            await context.persistScopeIds();
+        }
+        for (const project of allProjects) {
+            if (project.name === relayName && project.id !== keepProjectId) {
+                await this.ports.lettermint.deleteProject(project.id);
+            }
+        }
+    }
+    /**
+     * Deletes a just-minted project from inside a `catch`. A failed delete is
+     * dropped so it never replaces the error being rethrown; the orphan is
+     * swept by the next apply's duplicate delete.
+     */
+    async discardLettermintProject(id) {
+        try {
+            await this.ports.lettermint.deleteProject(id);
+        }
+        catch {
+            // Dropped: the caller rethrows the original error.
+        }
+    }
+    /**
+     * Ensures this org's Lettermint domain exists, is restricted to exactly
+     * the `<slug>-app`/`<slug>-relay` projects live in `allProjects`, has its
+     * DNS published and a verification triggered. Shared by
+     * {@link ensureAppLettermintMail} and {@link ensureOrgLettermintRelay}
+     * (#149) -- whichever of the two steps runs first on a fresh org creates
+     * the domain, and the other then finds it (`findExactLettermintDomain`).
+     *
+     * A crash between the restriction write and the DNS publish/verify 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 (post-#140 review finding, restated here rather than only at
+     * the one call site it used to have).
+     */
+    async ensureLettermintDomainRestriction(org, mailDomain, allProjects) {
+        const appName = `${org.slug}-app`;
+        const relayName = `${org.slug}-relay`;
+        const existing = await this.findExactLettermintDomain(mailDomain);
+        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(`Lettermint for ${org.slug}: no Cloudflare zone found for ${mailDomain}`);
         }
+        await this.publishLettermintDnsRecords(zone.id, domain.dnsRecords);
+        await this.ports.lettermint.verifyDomain(domain.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,
@@ -1573,9 +1831,9 @@ export class FoundryStepExecutor {
         if (!masCredentials) {
             throw new Error(`coolify:calls-service for ${org.slug}: the calls Matrix stack's MAS client credentials are not on the MAS app yet -- retry this apply once coolify:calls has minted them`);
         }
-        const sfu = await this.ports.callsSfu.resolveCredentials();
+        const sfu = await this.ports.callsSfu.resolveCredentials(org.slug);
         if (!sfu) {
-            throw new Error(`coolify:calls-service for ${org.slug}: the shared calls SFU has no LiveKit credentials configured yet -- see https://github.com/wtfalch/foundry/issues/122`);
+            throw new Error(`coolify:calls-service for ${org.slug}: the shared calls SFU has no LiveKit credentials for this org yet -- see https://github.com/wtfalch/foundry/issues/152`);
         }
         const projectUuid = await this.ensureCoolifyProject(org, context);
         const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
@@ -1661,6 +1919,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 +2147,176 @@ 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}).
+     *
+     * #149: this step also mints the org's own Lettermint *relay* credential
+     * ({@link ensureOrgLettermintRelay}) -- the app's own *sending* credential
+     * stays in the app step (`ensureAppLettermintMail`, "Core rule"), since the
+     * first app project can only exist once the token has a home. Parking mail
+     * (mode `'off'`) reaches Lettermint too: {@link parkLettermintMail} drops
+     * the relay route, then deletes the org's own projects and its domain, so
+     * a domain never ends up restricted only to dead projects and no route
+     * ever points at a project this apply is about to remove.
+     *
+     * 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`/`<slug>-relay` projects,
+     * 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) -- and blocks the step (never plans it) while the platform's
+        // mail is off or not yet applied. So a `desired` missing either value
+        // here is not a live gap to fall back on (#205): it is a step planned
+        // before that rule existed, now stale. Fail rather than silently point an
+        // org's mail at a fixed address nothing may still be listening on; the
+        // fix is to plan this org's mail again.
+        const apex = action.desired.apex;
+        const mailHost = action.desired.mailHost;
+        if (!apex || !mailHost) {
+            throw new Error(`coolify:mail for ${org.slug}: this step's plan carries no platform mail ${!apex && !mailHost ? 'apex or host' : !apex ? 'apex' : 'host'}; plan this org's mail again`);
+        }
+        const options = { apex, mailHost };
         if (mode === 'off') {
-            await this.ports.mail.parkOrgMail(mailOrgFor(org, usesDomain, 'hosted'), options);
+            const parkedMailOrg = mailOrgFor(org, usesDomain, 'hosted');
+            await this.ports.mail.parkOrgMail(parkedMailOrg, options);
+            await this.parkLettermintMail(org, parkedMailOrg, 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, context);
+        await this.ensureOrgLettermintRelay(org, mailOrg, result.domain, context);
+        await this.ensureRoleMailboxes(org, mailOrg, result.domain, context);
         return { resourceId: result.domain };
     }
+    /**
+     * `plan/diff.ts`'s `planMailCopy` (#113): this apply's share of copying
+     * the org's old mail into Stalwart, via `mail-copy.ts`'s `runMailCopyStep`
+     * -- the only thing this method itself does is read back what the last
+     * apply recorded, hand it to that function, and record what comes back.
+     * An account that failed to copy records the progress made, never
+     * `mail_copy_done`, then throws with the failing account, phase and
+     * redacted stderr tail, so the apply reports it as not done. A missing
+     * `mailCopy` port throws too: a configuration gap a retry cannot fix.
+     */
+    async mailCopy(org, context) {
+        if (!this.ports.mailCopy) {
+            throw new NotBuiltError(`coolify:mail-copy for ${org.slug}`, 'construct FoundryStepExecutor with `mailCopy` (#113)');
+        }
+        const alreadyCompleted = new Set(parseMailCopyCompleted(context.recordedIds()[MAIL_COPY_COMPLETED_SCOPE_KEY]));
+        const result = await runMailCopyStep(org, this.ports.mailCopy, alreadyCompleted);
+        context.recordScopeId(MAIL_COPY_COMPLETED_SCOPE_KEY, JSON.stringify(result.completed));
+        if (result.done)
+            context.recordScopeId(MAIL_COPY_DONE_SCOPE_KEY, '1');
+        if (result.failure) {
+            const { account, phase, exitCode, detail } = result.failure;
+            // Written now: the throw below ends the step before the end-of-run write.
+            await context.persistScopeIds();
+            throw new Error(`coolify:mail-copy for ${org.slug}: ${phase} of ${account} ${exitCode === undefined ? 'threw' : `exited ${exitCode}`}${detail ? `: ${detail}` : ''} -- retry this apply to continue (a provider's daily limit looks the same)`);
+        }
+        return undefined;
+    }
+    /**
+     * #162 (decided 2026-09-29): gives the org's declared owner a mailbox at
+     * its declared `mail.ownerMailboxAddress` -- nothing is guessed any more
+     * (the hardcoded `owner@<domain>` PR 163 shipped first is gone). A no-op
+     * 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
+     * so a second apply never calls `MailPort.createMailbox` again, rather
+     * than relying on that port method's own duplicate refusal.
+     */
+    async ensureOwnerMailbox(org, mailOrg, 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}`,
+        });
+        context.recordScopeId(MAIL_OWNER_MAILBOX_SCOPE_KEY, address);
+    }
+    /**
+     * #230: creates each of the org's declared `mail.roleMailboxes` on its
+     * just-resolved mail domain, once. A role mailbox has no person behind it,
+     * so its display name is just its local part, and like the owner's it is
+     * created with no password: `MailPort.createMailbox` takes none, so there
+     * is no secret to store or print. A "already has a mailbox" refusal from the port counts as created. The created set is recorded under
+     * {@link MAIL_ROLE_MAILBOXES_SCOPE_KEY} after every mailbox, so a second
+     * apply (or a retry after a crash) skips what exists rather than relying
+     * on the mail server's own duplicate refusal.
+     */
+    async ensureRoleMailboxes(org, mailOrg, domain, context) {
+        const declared = org.mail.roleMailboxes ?? [];
+        if (declared.length === 0)
+            return;
+        const recorded = context.recordedIds()[MAIL_ROLE_MAILBOXES_SCOPE_KEY];
+        const created = new Set(recorded ? recorded.split(',') : []);
+        for (const local of declared) {
+            const address = `${local}@${domain}`;
+            const entry = address.toLowerCase();
+            if (created.has(entry))
+                continue;
+            try {
+                await this.ports.mail.createMailbox(mailOrg, { address, name: local });
+            }
+            catch (error) {
+                // A crash between create and record leaves the mailbox made but
+                // unrecorded; the port exposes no existence check, only the refusal.
+                if (!/already has a mailbox/i.test(error instanceof Error ? error.message : String(error)))
+                    throw error;
+            }
+            created.add(entry);
+            context.recordScopeId(MAIL_ROLE_MAILBOXES_SCOPE_KEY, [...created].join(','));
+        }
+    }
+    /**
+     * 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 +2334,55 @@ 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"). #149: first drops the
+     * Stalwart relay route with `MailPort.removeOrgRelay` -- a missing route is
+     * a no-op, per that port method's own contract, so this is safe to call
+     * even for an org whose relay was never minted -- then 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, so the route is always gone before the project it pointed at.
+     * 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, mailOrg, context) {
+        const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
+        if (!mailDomain)
+            return;
+        await this.ports.mail.removeOrgRelay(mailOrg);
+        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 +2395,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 +2415,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 +2424,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 +2437,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 +2453,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 +2570,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;