@wtfalch/foundry 0.5.0 → 0.7.1

package/dist/plan/executor.js

@@ -1,9 +1,12 @@
 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 { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_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';
+import { ensureCloudflaredConnector } from './cloudflared-connector.js';
+import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, } from './login-host.js';
+import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
+import { APP_ENV_APPLIED_SCOPE_KEY, DB_ENV_APPLIED_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, resolveAppEnv, } from './platform-diff.js';
 // ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
@@ -108,10 +111,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
@@ -226,38 +230,6 @@ const AGORA_APP_DOCKERFILE = 'apps/agora/Dockerfile';
  * restated rather than shared across the two files.
  */
 const LOG_DIR = '/app/logs';
-/**
- * #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';
-/**
- * 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
- * `appId`, `zitadelApp`'s own `resourceId`) and not a secret (`deliverSecret`
- * is for that), so a flat scope id like `zitadel_org`/`zitadel_project`
- * above. A level-1 org declares exactly one web `issuerApps` entry for its
- * one standard app, so one flat key is enough; an org with more than one web
- * app would need a richer key, not built here (Finding, this campaign's
- * report).
- */
-const APP_CLIENT_ID_SCOPE_KEY = 'zitadel_app_client_id';
-/**
- * #139: the `cms` app's own ZITADEL web client's `clientId`, recorded
- * separately from {@link APP_CLIENT_ID_SCOPE_KEY} -- that key belongs to the
- * org's own hosted app (`diff.ts`'s `planIssuerApps`), a different
- * `zitadel:app` step from the fixed `cms` client `diff.ts`'s `planCmsClient`
- * plans. `cmsSite` reads this key to push `AUTH_CLIENT_ID` onto the cms app,
- * the same way `pushAppEnv` reads `APP_CLIENT_ID_SCOPE_KEY` for the hosted
- * app.
- */
-const CMS_CLIENT_ID_SCOPE_KEY = 'cms_client_id';
 /**
  * `cmsSite` provisions two applications from one `cms:site` step, but
  * `execute`'s own return value auto-records only one `resourceId`, under
@@ -299,6 +271,13 @@ const CMS_DATABASE_SCOPE_KEY = 'coolify_cms_database';
  * `resend_mail_domain`.
  */
 const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
+/**
+ * #235: the Coolify app running `cloudflared` for this org's own tunnel --
+ * one connector per org tunnel (Decided, William, 2026-10-01), the same
+ * `ensureCloudflaredConnector` every platform tunnel step already calls
+ * (`platform-providers.ts`), never a shared tunnel with appended ingress.
+ */
+const CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY = 'cloudflare_tunnel_connector_app';
 /**
  * #162: the owner's own mailbox, created once inside `coolify:mail` after
  * `applyOrgMail` succeeds, alongside {@link MAIL_DOMAIN_SCOPE_KEY} -- another
@@ -312,6 +291,29 @@ const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
  * 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 ORG_MAIL_RELAY_SCOPE_KEY = 'mail_relay';
+/**
+ * #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 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.
@@ -328,17 +330,6 @@ const AI_KEY_DELIVERY_ATTEMPTS = 3;
 const JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = 'jobs_registration_undelivered';
 /** How many times `jobsRegistration` tries each `deliverSecret` before giving up. */
 const JOBS_DELIVERY_ATTEMPTS = 3;
-/**
- * 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 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
@@ -431,6 +422,8 @@ export class FoundryStepExecutor {
                 return this.zitadelIssuer(action, org, context);
             case 'zitadel:owner':
                 return this.zitadelOwner(action, org, context);
+            case 'zitadel:login-host':
+                return this.zitadelLoginHost(action, org, context);
             case 'zitadel:app':
                 return this.zitadelApp(action, org, context);
             case 'zitadel:customers':
@@ -463,6 +456,8 @@ export class FoundryStepExecutor {
                 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':
@@ -598,6 +593,54 @@ export class FoundryStepExecutor {
         });
         return { resourceId: userId };
     }
+    /**
+     * `plan/diff.ts`'s `planLoginHost` (#267): adds the org's own company
+     * login host (`action.desired.host`) to the ZITADEL instance's trusted
+     * domains, writes zitadel-login's binding, then repoints the apps whose
+     * client id that binding holds. Apps created later are not in it yet:
+     * the next run replans (`diff.ts`'s `planLoginHost`) and moves them.
+     */
+    async zitadelLoginHost(action, org, context) {
+        const recorded = context.recordedIds();
+        const zitadelOrgId = recorded.zitadel_org;
+        if (!zitadelOrgId) {
+            throw new Error(`zitadel:login-host for ${org.slug}: no ZITADEL org recorded yet -- the issuer must be provisioned first`);
+        }
+        // `planLoginHost` blocks the step while this port is not wired.
+        const bindings = this.ports.loginHostBindings;
+        if (!bindings) {
+            throw new Error(`zitadel:login-host for ${org.slug}: the loginHostBindings port is not wired`);
+        }
+        const host = action.desired.host;
+        await this.ports.zitadel.ensureTrustedDomain(host);
+        // zitadel-login's own routing table, written before any app is repointed
+        // so no app ever points at a host with no binding.
+        const clientIds = loginHostClientIds(recorded);
+        await bindings.upsertBinding({ host, organizationId: zitadelOrgId, clientIds });
+        // Only apps whose client id the binding now holds: any other app in the
+        // project would lose sign-in. The rest move on a later run, once the
+        // recorded client ids differ from the binding and replan this step.
+        const boundAppIds = new Set([
+            ...(recorded[APP_CLIENT_ID_SCOPE_KEY]
+                ? org.hosting.issuerApps.filter((a) => a.kind === 'web').map((a) => a.name)
+                : []),
+            ...(recorded[CMS_CLIENT_ID_SCOPE_KEY] ? ['cms'] : []),
+            ...(recorded[AGORA_CLIENT_ID_SCOPE_KEY] ? ['agora'] : []),
+        ].map((name) => recorded[`zitadel:app:${name}`]));
+        const projectId = recorded.zitadel_project;
+        if (projectId) {
+            const apps = await this.ports.zitadel.listApps(zitadelOrgId, projectId);
+            for (const app of apps) {
+                if (app.state === 'APP_STATE_REMOVED' || !boundAppIds.has(app.id))
+                    continue;
+                await this.ports.zitadel.updateOidcAppLoginBaseUri(zitadelOrgId, projectId, app.id, `https://${host}/`);
+            }
+        }
+        // Last, so a crash above reruns the whole step. A client id recorded
+        // after this point differs from it and replans the step next run.
+        context.recordScopeId(LOGIN_BINDING_SCOPE_KEY, loginBindingState(host, clientIds));
+        return { resourceId: host };
+    }
     /**
      * `plan/diff.ts`'s `planCustomers` (plan gap A9): the org's customers sign
      * in through a second ZITADEL org, `<slug> customers`, with
@@ -822,11 +865,17 @@ export class FoundryStepExecutor {
         // resource id is already recorded by the time this runs -- but this also
         // covers the database being turned on after the app already exists (the
         // app step still ran this apply, found the app by name, and lands here).
+        let dbPush = { pushed: false, changed: false };
         if (org.hosting.database) {
             const dbId = context.recordedIds()[`coolify:database:${action.key}`];
-            if (dbId)
-                await this.pushDatabaseUrl(appId, dbId);
+            if (dbId) {
+                dbPush = await this.pushDatabaseUrl(appId, dbId, org.slug.replace(/-/g, '_'));
+            }
         }
+        // Restart when the push changed something, or when no earlier run got as
+        // far as restarting after one (marker missing): a crash between the push
+        // and the restart leaves the env right and the container stale.
+        const dbNeedsRestart = dbPush.pushed && (dbPush.changed || !context.recordedIds()[DB_ENV_APPLIED_SCOPE_KEY]);
         // Every app keeps its own logs across a redeploy (#75). Unconditional,
         // like the env push below: found by mount path before create, so a
         // re-run (or the drift step `diff.ts`'s `planApp` plans for an app that
@@ -838,7 +887,17 @@ export class FoundryStepExecutor {
         // The app receives whatever it needs to sign in (gap P2). Unconditional,
         // 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);
+        const appEnv = await this.pushAppEnv(appId, org, context);
+        // Rule 4 (#239, #243): a container reads its env only at start, so an app
+        // that was already there is restarted, once, when its database URLs or its
+        // declared appEnv changed.
+        if ((appEnv.changed || dbNeedsRestart) && existing)
+            await this.ports.coolify.restart(appId);
+        // Recorded only after the restart succeeded: a failed restart leaves the
+        // old value, so the next plan replans (rule 3). The db marker is not a URL.
+        context.recordScopeId(APP_ENV_APPLIED_SCOPE_KEY, appEnv.applied);
+        if (dbPush.pushed)
+            context.recordScopeId(DB_ENV_APPLIED_SCOPE_KEY, '1');
         // #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
@@ -922,39 +981,80 @@ export class FoundryStepExecutor {
         // (`coolifyApp`'s own push handles the more common order, database
         // before app on the same apply -- `diff.ts`'s `computePlanDetail`).
         const appId = context.recordedIds()[`coolify:app:${action.key}`];
-        if (appId)
-            await this.pushDatabaseUrl(appId, dbId);
+        if (appId) {
+            const push = await this.pushDatabaseUrl(appId, dbId, org.slug.replace(/-/g, '_'));
+            if (push.pushed) {
+                if (push.changed || !context.recordedIds()[DB_ENV_APPLIED_SCOPE_KEY]) {
+                    await this.ports.coolify.restart(appId);
+                }
+                context.recordScopeId(DB_ENV_APPLIED_SCOPE_KEY, '1');
+            }
+        }
         return { resourceId: dbId };
     }
     /**
-     * Pushes the database's connection string into the app's environment as
-     * `DATABASE_URL` -- never also as `DATABASE_URL_OWNER` (Decision, this
-     * campaign's report). Archon's own boot script
-     * (`archon/scripts/migrate-and-start.sh`) treats a bare `DATABASE_URL` with
-     * no `DATABASE_URL_OWNER` as "before the split": it migrates and serves as
-     * the one role it has, which is exactly what a database Coolify just
-     * created (one superuser role, no separate runtime role yet) is. Setting
-     * both to the *same* superuser URL would instead take the split branch --
-     * `db-role-guard.sh` then refuses to boot, since `DATABASE_URL_OWNER` being
-     * set means it expects `DATABASE_URL` to connect as a distinct,
-     * non-superuser runtime role (`<database>_rt`), which nothing here creates.
-     * Minting that role's own password and URL is a provisioning step of its
-     * own, not built here (Finding, this campaign's report).
+     * Pushes the database's connection string into the app's environment,
+     * split the same way `cmsSite`'s own database is (#117, #239): the
+     * superuser connection as `DATABASE_URL_OWNER`, and a distinct, restricted
+     * `<dbName>_rt` role's connection as `DATABASE_URL`. Archon's and manage's
+     * own boot scripts (`db-role-guard.sh`) refuse to start against a
+     * superuser `DATABASE_URL`, and lokessmie's refuses to start without
+     * `DATABASE_URL_OWNER` at all -- a bare superuser `DATABASE_URL` with no
+     * `DATABASE_URL_OWNER` is "before the split" there too.
      *
-     * The connection string is a live credential
-     * (`postgres://user:password@host/db`): it is read from
-     * `CoolifyPort.getDatabase` and handed straight to `bulkUpsertEnvs` and
-     * nowhere else in this class -- never returned, never recorded in
-     * `serviceIds` (hence never in the store or an audit record), never logged,
-     * never interpolated into a thrown error.
+     * Both connection strings are live credentials
+     * (`postgres://user:password@host/db`): read from `CoolifyPort.getDatabase`
+     * (or minted here, for the runtime one) and handed straight to
+     * `bulkUpsertEnvs` and nowhere else in this class -- never returned, never
+     * recorded in `serviceIds` (hence never in the store or an audit record),
+     * never logged, never interpolated into a thrown error.
      */
-    async pushDatabaseUrl(appId, dbId) {
+    async pushDatabaseUrl(appId, dbId, dbName) {
         const db = await this.ports.coolify.getDatabase(dbId);
+        // Nothing to push; `planApp` reports this as blocked from the live reader.
         if (!db.internal_db_url)
-            return;
-        await this.ports.coolify.bulkUpsertEnvs(appId, [
-            { key: 'DATABASE_URL', value: db.internal_db_url },
-        ]);
+            return { pushed: false, changed: false };
+        const envs = [
+            { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
+        ];
+        const runtimeUrl = await this.ensureAppRuntimeUrl(appId, db.internal_db_url, dbName);
+        if (runtimeUrl)
+            envs.push({ key: 'DATABASE_URL', value: runtimeUrl });
+        // True when a value actually changed, so the caller restarts the app only
+        // then (the owner URL is upserted on every apply).
+        const ownerBefore = (await this.ports.coolify.listEnvs(appId)).find((e) => e.key === 'DATABASE_URL_OWNER' && !e.is_preview)?.value;
+        await this.ports.coolify.bulkUpsertEnvs(appId, envs);
+        return { pushed: true, changed: runtimeUrl !== null || ownerBefore !== db.internal_db_url };
+    }
+    /**
+     * `null` once the app already has a `DATABASE_URL` -- never rotated, the
+     * same rule `ensureCmsRuntimeUrl` follows and for the same reason: the
+     * app's own boot script creates or updates the live `<dbName>_rt` Postgres
+     * role from exactly the username/password this method mints, once:
+     * overwriting `DATABASE_URL` on a later apply would leave that
+     * already-created role's real password out of sync with whatever foundry
+     * hands the app next. See `ensureCmsRuntimeUrl`'s own doc comment for the
+     * parsing and encoding choices this mirrors exactly.
+     */
+    async ensureAppRuntimeUrl(appId, dbInternalUrl, dbName) {
+        const envs = await this.ports.coolify.listEnvs(appId);
+        // An existing `DATABASE_URL` that is still the superuser string is what an
+        // app got before the split (#239): treat it as absent so the runtime role
+        // is minted and replaces it, or the app's db-role-guard refuses to boot.
+        const already = envs.some((e) => e.key === 'DATABASE_URL' && !e.is_preview && e.value !== dbInternalUrl);
+        if (already)
+            return null;
+        let host;
+        let pathname;
+        let search;
+        try {
+            ({ host, pathname, search } = new URL(dbInternalUrl));
+        }
+        catch {
+            return null;
+        }
+        const password = randomBytes(24).toString('base64url');
+        return `postgres://${dbName}_rt:${password}@${host}${pathname}${search}`;
     }
     /**
      * Pushes what the org's app needs to sign a user in through ZITADEL (gap
@@ -970,9 +1070,12 @@ 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) is out of scope here (task brief). `DATABASE_URL_OWNER`/
+     * `DATABASE_URL` are pushed by `pushDatabaseUrl` instead, not here --
+     * that call runs only once `hosting.database` is declared and
+     * provisioned, where this one is unconditional (#239).
      */
     async pushAppEnv(appId, org, context) {
         const recorded = context.recordedIds();
@@ -1003,7 +1106,21 @@ export class FoundryStepExecutor {
         const cookieSecret = await this.ensureAuthCookieSecret(appId);
         if (cookieSecret)
             envs.push({ key: 'AUTH_COOKIE_SECRET', value: cookieSecret });
+        // #243: the app's own declared map from its env var names to values the
+        // plan already mints for this org (Files, AI, mail) -- each bespoke app
+        // names these differently (lokessmie uses STORAGE_*/AI_*). Nothing is
+        // minted here; a source with no value yet (its own step has not run,
+        // or has not run for this apply) is simply omitted, the same way every
+        // other optional entry above is.
+        const appEnv = resolveAppEnv(org, recorded).values;
+        for (const [key, value] of Object.entries(appEnv))
+            envs.push({ key, value });
         await this.ports.coolify.bulkUpsertEnvs(appId, envs);
+        // `coolifyApp` records `applied` once the restart succeeded, so `planApp`
+        // replans this step when the declared map changes (rule 3). Ids and a
+        // domain, never a secret.
+        const applied = JSON.stringify(appEnv);
+        return { changed: applied !== (recorded[APP_ENV_APPLIED_SCOPE_KEY] ?? '{}'), applied };
     }
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
@@ -1052,7 +1169,10 @@ export class FoundryStepExecutor {
      * be deleted.
      *
      * `MAIL_FROM` is upserted every time: it depends only on the mail domain
-     * `coolify:mail` resolved.
+     * `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
@@ -1065,7 +1185,6 @@ export class FoundryStepExecutor {
         if (!mailDomain)
             return;
         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),
@@ -1086,18 +1205,133 @@ export class FoundryStepExecutor {
             allProjects = [...projects, created.project];
             envUpdates.push({ key: 'LETTERMINT_API_TOKEN', value: created.token });
         }
-        envUpdates.push({ key: 'MAIL_FROM', value: `no-reply@${mailDomain}` });
+        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 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);
+        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);
-        // 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);
@@ -1107,15 +1341,10 @@ export class FoundryStepExecutor {
         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}`);
+            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);
-        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
@@ -1713,9 +1942,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');
@@ -1963,6 +2192,19 @@ export class FoundryStepExecutor {
             await this.ports.cloudflare.putTunnelConfig(tunnelId, {
                 ingress: [{ service: 'http_status:404' }],
             });
+            // #235: park stops the connector too -- an ingress with nothing
+            // routed is still a running container dialed into the tunnel.
+            const connectorAppId = context.recordedIds()[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY];
+            if (connectorAppId) {
+                try {
+                    await this.ports.coolify.raw('POST', `/applications/${connectorAppId}/stop`);
+                }
+                catch (error) {
+                    // Already gone (destroyed out of band): nothing left to stop.
+                    if (!isNotFoundError(error))
+                        throw error;
+                }
+            }
             return { resourceId: tunnelId };
         }
         const tunnelName = `${org.slug}-tunnel`;
@@ -1992,6 +2234,29 @@ export class FoundryStepExecutor {
         await this.ports.cloudflare.putTunnelConfig(tunnel.id, {
             ingress: [...ingress, { service: 'http_status:404' }],
         });
+        // #235: a connector for this org's own tunnel, the same call every
+        // platform tunnel step already makes (Decided, William, 2026-10-01:
+        // one connector per org tunnel, never a shared tunnel with appended
+        // ingress). Without this, the tunnel exists and is configured but
+        // nothing is dialed into it, so `hostname` answers with a Cloudflare
+        // error -- #197's own gap, for an org's tunnel rather than a platform
+        // one.
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        await ensureCloudflaredConnector({
+            coolify: this.ports.coolify,
+            cloudflare: this.ports.cloudflare,
+            tunnelId: tunnel.id,
+            appName: `${org.slug}-cloudflared`,
+            projectUuid,
+            environment,
+            resolveServer: () => this.resolveServer(),
+            recordedConnectorAppId: context.recordedIds()[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY] ?? null,
+            recordAppId: async (appId) => {
+                context.recordScopeId(CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY, appId);
+                await context.persistScopeIds();
+            },
+        });
         return { resourceId: tunnel.id };
     }
     /**
@@ -2031,20 +2296,21 @@ export class FoundryStepExecutor {
      * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` bound), then
      * 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.
+     *
+     * #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` project, which could
-     * then keep sending as it forever. {@link deleteStaleLettermintDomain}
+     * 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.
      *
@@ -2058,15 +2324,22 @@ export class FoundryStepExecutor {
         // #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,
-        };
+        // 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);
-            await this.parkLettermintMail(org, context);
+            const parkedMailOrg = mailOrgFor(org, usesDomain, 'hosted');
+            await this.ports.mail.parkOrgMail(parkedMailOrg, options);
+            await this.parkLettermintMail(org, parkedMailOrg, context);
             return undefined;
         }
         const mailOrg = mailOrgFor(org, usesDomain, mode);
@@ -2077,30 +2350,97 @@ export class FoundryStepExecutor {
         // #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);
+        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 };
     }
     /**
-     * #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.
+     * `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 ensureOwnerMailbox(org, mailOrg, domain, context) {
+    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;
-        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);
     }
+    /**
+     * #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
@@ -2145,17 +2485,22 @@ export class FoundryStepExecutor {
     /**
      * 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.
+     * 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 parkLettermintMail(org, context) {
+    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) {
@@ -2309,9 +2654,24 @@ export class FoundryStepExecutor {
         const { org, recordedIds } = context;
         try {
             switch (`${target.system}:${target.kind}`) {
-                case 'cloudflare:tunnel':
+                case 'cloudflare:tunnel': {
+                    // #235: the connector app first, its own 404 handled locally --
+                    // a retry where this already succeeded must still reach
+                    // `deleteTunnel` below, which the outer catch's own 404 handling
+                    // would otherwise short-circuit before it ran.
+                    const connectorAppId = recordedIds[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY];
+                    if (connectorAppId) {
+                        try {
+                            await this.ports.coolify.deleteApplication(connectorAppId);
+                        }
+                        catch (error) {
+                            if (!isNotFoundError(error))
+                                throw error;
+                        }
+                    }
                     await this.ports.cloudflare.deleteTunnel(target.id);
                     return;
+                }
                 case 'cloudflare:access':
                     await this.ports.cloudflare.deleteAccessApp(target.id);
                     return;