@wtfalch/foundry 0.28.0 → 0.29.0

package/dist/plan/boule.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg } from '../org.js';
+import { type DeclaredOrg } from '../org.js';
 import type { BrokerEntryInput, BrokerEntryWant } from './broker-entries.js';
 /**
  * #161 (Boule part): what both the planner (`diff.ts`) and the executor
@@ -36,8 +36,28 @@ export declare const BOULE_DEPLOYED_SCOPE_KEY = "coolify_boule_deployed";
  * issuer.
  */
 export declare function bouleHostnameFor(org: DeclaredOrg): string;
+/** The env name Boule reads its Lettermint token from (boule#266). */
+export declare const BOULE_MAIL_TOKEN_ENV = "LETTERMINT_API_TOKEN";
+/**
+ * Whether Boule should mail invites: the org's mail is hosted and
+ * `coolify:mail` has recorded its domain. Mail off, received, or no domain
+ * yet: no mail env at all, and Boule shows the invite link on screen.
+ */
+export declare function bouleMailWanted(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): boolean;
+/**
+ * Boule's `MAIL_FROM`: the org's no-reply address on its recorded mail
+ * domain. The local part falls back to `DEFAULT_NO_REPLY_LOCAL_PART`, the
+ * same default the hosted app's `MAIL_FROM` uses and the store column holds.
+ */
+export declare function bouleMailFrom(org: DeclaredOrg, mailDomain: string): string;
+/**
+ * Whether the live Boule's mail token needs writing: it holds none, or the
+ * org's hosted app holds a different one (the app's token wins). Compares
+ * values in memory only; the result names nothing secret.
+ */
+export declare function bouleMailTokenDrift(liveToken: string | undefined, appToken: string | undefined): boolean;
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
-export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "ARCHON_URL"];
+export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN"];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
  * to build them. Callers that write must refuse on a non-empty `missing`: a
@@ -55,11 +75,15 @@ export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER",
  * absent: Boule has no platform wired in every test and every org-only
  * caller, same as `issuer` before #177.
  *
+ * `mailWanted` (see {@link bouleMailWanted}) adds `MAIL_FROM`. The Lettermint
+ * token is never here: it is a secret the executor writes and the plan
+ * compares in memory ({@link bouleMailTokenDrift}).
+ *
  * Not here, and written by the executor instead: the database URLs
  * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
  * (generated once, never rotated).
  */
-export declare function desiredBouleEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null, archonUrl: string | null): {
+export declare function desiredBouleEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null, archonUrl: string | null, mailWanted?: boolean): {
     env: Record<string, string>;
     missing: string[];
 };

package/dist/plan/boule.js

@@ -1,3 +1,4 @@
+import { DEFAULT_NO_REPLY_LOCAL_PART } from '../org.js';
 import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
 /**
  * #161 (Boule part): what both the planner (`diff.ts`) and the executor
@@ -37,6 +38,34 @@ export const BOULE_DEPLOYED_SCOPE_KEY = 'coolify_boule_deployed';
 export function bouleHostnameFor(org) {
     return org.domain ? `boule.${org.domain}` : `${org.slug}-boule.oikos.host`;
 }
+/** The env name Boule reads its Lettermint token from (boule#266). */
+export const BOULE_MAIL_TOKEN_ENV = 'LETTERMINT_API_TOKEN';
+/** The scope id `coolify:mail` records the org's resolved mail domain under. */
+const MAIL_DOMAIN_RECORDED_KEY = 'mail_domain';
+/**
+ * Whether Boule should mail invites: the org's mail is hosted and
+ * `coolify:mail` has recorded its domain. Mail off, received, or no domain
+ * yet: no mail env at all, and Boule shows the invite link on screen.
+ */
+export function bouleMailWanted(org, recorded) {
+    return org.mail.mode === 'hosted' && Boolean(recorded[MAIL_DOMAIN_RECORDED_KEY]);
+}
+/**
+ * Boule's `MAIL_FROM`: the org's no-reply address on its recorded mail
+ * domain. The local part falls back to `DEFAULT_NO_REPLY_LOCAL_PART`, the
+ * same default the hosted app's `MAIL_FROM` uses and the store column holds.
+ */
+export function bouleMailFrom(org, mailDomain) {
+    return `${org.mail.noReplyLocalPart || DEFAULT_NO_REPLY_LOCAL_PART}@${mailDomain}`;
+}
+/**
+ * Whether the live Boule's mail token needs writing: it holds none, or the
+ * org's hosted app holds a different one (the app's token wins). Compares
+ * values in memory only; the result names nothing secret.
+ */
+export function bouleMailTokenDrift(liveToken, appToken) {
+    return !liveToken || (Boolean(appToken) && appToken !== liveToken);
+}
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
 export const BOULE_MANAGED_ENV_KEYS = [
     'APP_URL',
@@ -46,6 +75,8 @@ export const BOULE_MANAGED_ENV_KEYS = [
     'BOULE_ORG_NAME',
     'AUTHZ_BOOTSTRAP_OPERATOR',
     'ARCHON_URL',
+    'MAIL_FROM',
+    BOULE_MAIL_TOKEN_ENV,
 ];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
@@ -64,11 +95,15 @@ export const BOULE_MANAGED_ENV_KEYS = [
  * absent: Boule has no platform wired in every test and every org-only
  * caller, same as `issuer` before #177.
  *
+ * `mailWanted` (see {@link bouleMailWanted}) adds `MAIL_FROM`. The Lettermint
+ * token is never here: it is a secret the executor writes and the plan
+ * compares in memory ({@link bouleMailTokenDrift}).
+ *
  * Not here, and written by the executor instead: the database URLs
  * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
  * (generated once, never rotated).
  */
-export function desiredBouleEnv(org, recorded, issuer, archonUrl) {
+export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = false) {
     const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
     const clientId = recorded[BOULE_CLIENT_ID_SCOPE_KEY];
     const missing = [];
@@ -96,6 +131,9 @@ export function desiredBouleEnv(org, recorded, issuer, archonUrl) {
         : undefined;
     if (ownerUserId)
         env.AUTHZ_BOOTSTRAP_OPERATOR = ownerUserId;
+    const mailDomain = recorded[MAIL_DOMAIN_RECORDED_KEY];
+    if (mailWanted && mailDomain)
+        env.MAIL_FROM = bouleMailFrom(org, mailDomain);
     return { env, missing };
 }
 /** The `AUTH_APPS` name of an org's Boule broker entry, and the scope key suffix it records under. */

package/dist/plan/diff.js

@@ -1,7 +1,7 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
-import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
+import { BOULE_BROKER_ENTRY_KEY, BOULE_MAIL_TOKEN_ENV, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { chatInternalNames } from './chat-matrix.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
@@ -398,7 +398,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const bouleGuarded = guardApp(bouleClient);
     if (bouleGuarded)
         plannedSteps.push(bouleGuarded);
-    const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null);
+    const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null, platformReadiness);
     if (boule.step)
         plannedSteps.push(boule.step);
     // After the apps and Boule -- an edge key needs its app recorded or planned,
@@ -468,6 +468,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         unmanaged.push({ description: agora.blocked, key: 'coolify:agora' });
     if (boule.blocked)
         unmanaged.push({ description: boule.blocked, key: 'coolify:boule' });
+    if (boule.mailBlocked) {
+        unmanaged.push({ description: boule.mailBlocked, key: 'coolify:boule:mail' });
+    }
     // Same for an ai key minted but never delivered: planning a new mint would
     // orphan a second live key.
     if (aiKey.blocked)
@@ -2027,7 +2030,7 @@ function planBouleClient(org, byKey, claimed) {
  * address (the one Agora signs in at); without it the Boule is blocked, not
  * planned, so every other step still applies.
  */
-function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonUrl) {
+function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonUrl, readiness) {
     const key = resourceKey('coolify', 'boule', org.id);
     const live = byKey.get(key);
     if (live)
@@ -2042,26 +2045,59 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
     if (tooLong.length > 0) {
         return {
             step: null,
+            mailBlocked: null,
             blocked: `${org.slug}'s Boule is blocked, not planned: ${tooLong.map(([n, what]) => `${what} '${n}' is over 63 characters`).join(', ')}; shorten the slug`,
         };
     }
     if (otherSlugs.includes(`${org.slug}-boule`)) {
         return {
             step: null,
+            mailBlocked: null,
             blocked: `${org.slug}'s Boule is blocked, not planned: another declared org has the slug '${org.slug}-boule', which is this Boule's hostname`,
         };
     }
     if (!issuer) {
         return {
             step: null,
+            mailBlocked: null,
             blocked: `${org.slug}'s Boule is blocked, not planned: the host supplies no issuer`,
         };
     }
+    // Mail env, only for a hosted-mail org whose domain is recorded. Blocked,
+    // not failing: while the platform cannot yet supply the token, Boule is
+    // planned without mail and keeps showing the invite link.
+    const mailWanted = bouleMailWanted(org, recordedIds);
+    const mailDomain = recordedIds.mail_domain?.toLowerCase();
+    const isApexOrg = Boolean(mailDomain && readiness.platformApex && mailDomain === readiness.platformApex.toLowerCase());
+    let mailBlockedReason = null;
+    if (mailWanted && isApexOrg) {
+        if (!readiness.platformLettermintProjectId) {
+            mailBlockedReason = 'platform.mail.lettermintProjectId is not declared yet';
+        }
+        else if (readiness.mailKeyHeld !== true) {
+            mailBlockedReason = `the platform's Lettermint key is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`;
+        }
+    }
+    else if (mailWanted) {
+        mailBlockedReason = edgeNeeded(readiness, ['zones', 'dns']);
+    }
+    const mailBlocked = mailBlockedReason
+        ? `${org.slug}'s Boule mail is blocked, not planned: ${mailBlockedReason}`
+        : null;
+    const mailOn = mailWanted && !mailBlocked;
     const action = {
         system: 'coolify',
         kind: 'boule',
         key: org.id,
-        desired: { issuer, archonUrl },
+        // The platform values go in like the app step's: the executor writes
+        // what the plan showed and refuses a plan that carries no `platformApex`.
+        desired: {
+            issuer,
+            archonUrl,
+            platformApex: readiness.platformApex,
+            platformLettermintProjectId: readiness.platformLettermintProjectId,
+            mailBlocked: mailBlocked !== null,
+        },
     };
     if (!live) {
         return {
@@ -2070,13 +2106,19 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
                 step: { description: `provision ${org.slug}'s Boule`, destroys: false, migrates: false },
             },
             blocked: null,
+            mailBlocked,
         };
     }
     const liveEnv = (live.config.env ?? {});
-    const { env } = desiredBouleEnv(org, recordedIds, issuer, archonUrl);
+    const { env } = desiredBouleEnv(org, recordedIds, issuer, archonUrl, mailOn);
     const drift = bouleEnvDrift(env, liveEnv);
+    // The token is compared, never planned with its value.
+    if (mailOn &&
+        bouleMailTokenDrift(liveEnv[BOULE_MAIL_TOKEN_ENV], live.config.appMailToken)) {
+        drift.push(BOULE_MAIL_TOKEN_ENV);
+    }
     if (drift.length === 0)
-        return { step: null, blocked: null };
+        return { step: null, blocked: null, mailBlocked };
     return {
         step: {
             action,
@@ -2087,6 +2129,7 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
             },
         },
         blocked: null,
+        mailBlocked,
     };
 }
 /**

package/dist/plan/executor.d.ts

@@ -1957,6 +1957,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * domain restricted to them before any old project is deleted, so the
      * restriction list never becomes empty.
      *
+     * #654: the non-platform-apex part now lives in {@link ensureOrgAppMailToken},
+     * shared with Boule, which holds the same token; the rule below is its rule
+     * with the consumers read from the hosted app and Boule.
+     *
      * 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 the earlier provider's key, a Lettermint project's name
@@ -2003,6 +2007,31 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * this field existed (review round 2, finding 3).
      */
     private ensureAppLettermintMail;
+    /**
+     * The one mint rule for the org's `<slug>-app` Lettermint token, shared by
+     * the hosted app (`ensureAppLettermintMail`) and Boule
+     * (`ensureBouleMail`), which hold the same token. Lettermint shows a
+     * token once, so the token lives only in those apps' envs: the rule reads
+     * every consumer that is recorded (the hosted app first, Boule second).
+     * The project is healthy when Lettermint lists exactly one `<slug>-app`
+     * project and some consumer holds a token. A healthy rule gives `self` that
+     * token (the app's wins) when it lacks it or holds another; a peer gets it
+     * in its own step. An
+     * unhealthy one mints a fresh project and writes its token to every
+     * consumer, restarting those that run, before any other `<slug>-app`
+     * project is deleted. Either role may run first: an app added after Boule
+     * adopts Boule's token instead of deleting its project.
+     *
+     * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
+     * returned, recorded, logged or interpolated into an error. Returns
+     * whether `self`'s own token changed and whether it was restarted here.
+     *
+     * A peer recorded but gone from Coolify (404) is no consumer. A healthy
+     * company's step writes only its own env; a re-mint writes every live
+     * consumer, restarts the running ones, restricts the domain, then deletes
+     * the old projects.
+     */
+    private ensureOrgAppMailToken;
     /**
      * #149: mints this org's own Lettermint relay credential and writes it to
      * Stalwart via `MailPort.applyOrgRelay`, the same mint rule
@@ -2443,6 +2472,16 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * shape {@link coolifyAgora}'s own doc comment explains.
      */
     private coolifyBoule;
+    /**
+     * Gives Boule `LETTERMINT_API_TOKEN`: the platform's held key for an org on
+     * the platform's own apex, else the org's `<slug>-app` token through the
+     * shared mint rule ({@link ensureOrgAppMailToken}), which mints that project
+     * when no hosted app made it yet. `MAIL_FROM` is written with the rest of
+     * Boule's env. Returns whether Boule's token changed, so the caller
+     * restarts a running Boule, unless `restarted`: the shared rule then already
+     * restarted it (`running`), before it deleted the old project.
+     */
+    private ensureBouleMail;
     /**
      * `plan/diff.ts`'s `planJobsRegistration`: registers the org's own app with
      * the platform's jobs scheduler (`JobsSchedulerPort.registerProject`, the

package/dist/plan/executor.js

@@ -3,7 +3,7 @@ import { URL } from 'node:url';
 import { resolveCallsSfuUrls } from '../calls-sfu.js';
 import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, ownerMailboxRecorded, ownerMailboxes, sharedSecretRef, } from '../org.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, AGORA_CLIENT_ID_SCOPE_KEY, AGORA_DEPLOYED_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, chatIntrospectionAppName, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
-import { BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_DATABASE_SCOPE_KEY, BOULE_DEPLOYED_SCOPE_KEY, bouleEnvDrift, bouleHostnameFor, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
+import { BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_DATABASE_SCOPE_KEY, BOULE_DEPLOYED_SCOPE_KEY, bouleEnvDrift, bouleHostnameFor, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { MAS_IMAGE, MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
 import { CHAT_REPO, CHAT_SERVICE_DOCKERFILE, CHAT_SERVICE_PORT, CHAT_SYNAPSE_DOCKERFILE, CHAT_SYNAPSE_PORT, chatInternalNames, chatMasConfigYaml, chatServiceEnvs, chatSynapseHomeserverYaml, chatUpstreams, } from './chat-matrix.js';
@@ -2493,6 +2493,10 @@ export class FoundryStepExecutor {
      * domain restricted to them before any old project is deleted, so the
      * restriction list never becomes empty.
      *
+     * #654: the non-platform-apex part now lives in {@link ensureOrgAppMailToken},
+     * shared with Boule, which holds the same token; the rule below is its rule
+     * with the consumers read from the hosted app and Boule.
+     *
      * 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 the earlier provider's key, a Lettermint project's name
@@ -2545,7 +2549,6 @@ export class FoundryStepExecutor {
         if (!hasPlatformApexField) {
             throw new Error(`coolify:app for ${org.slug}: this step's plan carries no platformApex; plan this org's app again`);
         }
-        const appName = `${org.slug}-app`;
         // #491: an org whose mail domain is the platform's own apex (Company
         // Included on companyincluded.com, today) shares the platform's existing
         // Lettermint project rather than minting a `<slug>-app` one of its own --
@@ -2588,44 +2591,129 @@ export class FoundryStepExecutor {
                 await this.ports.coolify.restart(appId);
             return;
         }
-        const [projects, envs] = await Promise.all([
+        await this.ensureOrgAppMailToken({
+            org,
+            context,
+            mailDomain,
+            self: { role: 'app', id: appId, restart: running },
+            mailFrom: `${org.mail.noReplyLocalPart ?? 'no-reply'}@${mailDomain}`,
+            platformApex,
+            platformLettermintProjectId,
+        });
+    }
+    /**
+     * The one mint rule for the org's `<slug>-app` Lettermint token, shared by
+     * the hosted app (`ensureAppLettermintMail`) and Boule
+     * (`ensureBouleMail`), which hold the same token. Lettermint shows a
+     * token once, so the token lives only in those apps' envs: the rule reads
+     * every consumer that is recorded (the hosted app first, Boule second).
+     * The project is healthy when Lettermint lists exactly one `<slug>-app`
+     * project and some consumer holds a token. A healthy rule gives `self` that
+     * token (the app's wins) when it lacks it or holds another; a peer gets it
+     * in its own step. An
+     * unhealthy one mints a fresh project and writes its token to every
+     * consumer, restarting those that run, before any other `<slug>-app`
+     * project is deleted. Either role may run first: an app added after Boule
+     * adopts Boule's token instead of deleting its project.
+     *
+     * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
+     * returned, recorded, logged or interpolated into an error. Returns
+     * whether `self`'s own token changed and whether it was restarted here.
+     *
+     * A peer recorded but gone from Coolify (404) is no consumer. A healthy
+     * company's step writes only its own env; a re-mint writes every live
+     * consumer, restarts the running ones, restricts the domain, then deletes
+     * the old projects.
+     */
+    async ensureOrgAppMailToken(args) {
+        const { org, context, mailDomain, self, mailFrom } = args;
+        const appName = `${org.slug}-app`;
+        const recorded = context.recordedIds();
+        const appId = self.role === 'app' ? self.id : recorded[`coolify:app:${appStepKey(org)}`];
+        const bouleId = self.role === 'boule' ? self.id : recorded[`coolify:boule:${org.id}`];
+        const peerListEnvs = (id) => !id || id === self.id
+            ? Promise.resolve(null)
+            : // A recorded peer that Coolify no longer has is not a consumer: not
+                // read, written or restarted (same 404 rule as the retire step).
+                this.ports.coolify
+                    .listEnvs(id)
+                    .catch((error) => {
+                    if (!isNotFoundError(error))
+                        throw error;
+                    return null;
+                });
+        const [projects, selfEnvs, appEnvs, bouleEnvs] = await Promise.all([
             this.ports.lettermint.listProjects(),
-            this.ports.coolify.listEnvs(appId),
+            this.ports.coolify.listEnvs(self.id),
+            self.role === 'app' ? Promise.resolve(null) : peerListEnvs(appId),
+            self.role === 'boule' ? Promise.resolve(null) : peerListEnvs(bouleId),
         ]);
-        const envValue = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
+        const tokenOf = (envs) => envs.find((e) => e.key === 'LETTERMINT_API_TOKEN' && !e.is_preview)?.value || undefined;
+        // The hosted app first, Boule second: the app's token wins a disagreement.
+        const consumers = [];
+        const appSlot = self.role === 'app' ? selfEnvs : appEnvs;
+        const bouleSlot = self.role === 'boule' ? selfEnvs : bouleEnvs;
+        if (appSlot && appId)
+            consumers.push({ id: appId, token: tokenOf(appSlot) });
+        if (bouleSlot && bouleId)
+            consumers.push({ id: bouleId, token: tokenOf(bouleSlot) });
+        const existingToken = consumers.find((c) => c.token)?.token;
         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'));
+        const healthy = held !== undefined && existingToken !== undefined;
         let allProjects = projects;
         let keepProjectId;
-        const envUpdates = [];
-        if (healthy && held) {
+        let token;
+        if (healthy && held && existingToken) {
             keepProjectId = held.id;
+            token = existingToken;
         }
         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 });
+            token = created.token;
+        }
+        // A healthy company: this step writes only its own env; a peer that lacks
+        // the token gets it in its own step. A re-mint kills the old token, so it
+        // reaches every live consumer here.
+        const targets = consumers.filter((c) => c.token !== token && (!healthy || c.id === self.id));
+        const selfChanged = targets.some((c) => c.id === self.id);
+        for (const consumer of consumers) {
+            const updates = [];
+            if (targets.includes(consumer))
+                updates.push({ key: 'LETTERMINT_API_TOKEN', value: token });
+            if (consumer.id === self.id && mailFrom)
+                updates.push({ key: 'MAIL_FROM', value: mailFrom });
+            if (updates.length > 0)
+                await this.ports.coolify.bulkUpsertEnvs(consumer.id, updates);
         }
-        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 is deployed first (#566).
-        if (!healthy && running)
-            await this.ports.coolify.restart(appId);
-        await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects, platformApex, platformLettermintProjectId);
+        // token, so a fresh one only reaches it through a restart -- after every
+        // write and before the old project is deleted below, so a failure in
+        // between leaves the old project for the next apply to re-mint. A just-created
+        // app is deployed first (#566).
+        let selfRestarted = false;
+        for (const consumer of targets) {
+            const isSelf = consumer.id === self.id;
+            const running = isSelf
+                ? self.restart
+                : isRunningOrStarting((await this.ports.coolify.getApplication(consumer.id)).status);
+            if (!running)
+                continue;
+            await this.ports.coolify.restart(consumer.id);
+            if (isSelf)
+                selfRestarted = true;
+        }
+        await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects, args.platformApex, args.platformLettermintProjectId);
         for (const project of allProjects) {
             if (project.name === appName &&
                 project.id !== keepProjectId &&
-                project.id !== platformLettermintProjectId) {
+                project.id !== args.platformLettermintProjectId) {
                 await this.ports.lettermint.deleteProject(project.id);
             }
         }
+        return { selfChanged, selfRestarted };
     }
     /**
      * #149: mints this org's own Lettermint relay credential and writes it to
@@ -4237,7 +4325,14 @@ export class FoundryStepExecutor {
         // written is the env the plan showed.
         const issuer = action.desired.issuer ?? null;
         const archonUrl = action.desired.archonUrl ?? null;
-        const { env, missing } = desiredBouleEnv(org, context.recordedIds(), issuer, archonUrl);
+        // The plan decides blocked mail (`mailBlocked`); a plan with no
+        // `platformApex` key predates this field and is refused before any mail
+        // env is written.
+        const mailWanted = bouleMailWanted(org, context.recordedIds()) && action.desired.mailBlocked !== true;
+        if (mailWanted && !('platformApex' in action.desired)) {
+            throw new Error(`coolify:boule for ${org.slug}: this step's plan carries no platformApex; plan this org's Boule again`);
+        }
+        const { env, missing } = desiredBouleEnv(org, context.recordedIds(), issuer, archonUrl, mailWanted);
         if (missing.length > 0) {
             throw new Error(`Boule for ${org.slug} cannot be configured: missing ${missing.join(', ')}. Nothing was written.`);
         }
@@ -4288,6 +4383,12 @@ export class FoundryStepExecutor {
         if (!dbPush.pushed) {
             throw new Error(`Boule for ${org.slug}: its database has no internal_db_url yet -- retry this apply once Coolify reports one`);
         }
+        // The org's Lettermint token, the same one its hosted app holds. A no-op
+        // for an org with mail off or no mail domain recorded: Boule then shows
+        // the invite link.
+        const mail = mailWanted
+            ? await this.ensureBouleMail(app.appId, org, context, action, app.existed && Boolean(context.recordedIds()[BOULE_DEPLOYED_SCOPE_KEY]))
+            : { changed: false, restarted: false };
         // #504: see `coolifyAgora`'s own comment just above -- `createGithubAppApplication`
         // never sets `instant_deploy`, so a brand new app (or one found by name
         // that a previous apply created but crashed before deploying) sat built
@@ -4300,11 +4401,53 @@ export class FoundryStepExecutor {
             context.recordScopeId(BOULE_DEPLOYED_SCOPE_KEY, '1');
         }
         else if (app.existed &&
-            (envChanged || cookieSecret !== null || appKey !== null || dbPush.changed)) {
+            !mail.restarted &&
+            (envChanged || cookieSecret !== null || appKey !== null || dbPush.changed || mail.changed)) {
+            // A restart inside the mail rule already came after every env write above.
             await this.ports.coolify.restart(app.appId);
         }
         return { resourceId: app.appId };
     }
+    /**
+     * Gives Boule `LETTERMINT_API_TOKEN`: the platform's held key for an org on
+     * the platform's own apex, else the org's `<slug>-app` token through the
+     * shared mint rule ({@link ensureOrgAppMailToken}), which mints that project
+     * when no hosted app made it yet. `MAIL_FROM` is written with the rest of
+     * Boule's env. Returns whether Boule's token changed, so the caller
+     * restarts a running Boule, unless `restarted`: the shared rule then already
+     * restarted it (`running`), before it deleted the old project.
+     */
+    async ensureBouleMail(appId, org, context, action, running) {
+        const none = { changed: false, restarted: false };
+        const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
+        if (!mailDomain)
+            return none;
+        const platformApex = action.desired.platformApex ?? null;
+        const platformLettermintProjectId = action.desired.platformLettermintProjectId ?? null;
+        if (platformApex && mailDomain.toLowerCase() === platformApex.toLowerCase()) {
+            const heldToken = (await this.ports.heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF)) ?? null;
+            if (!heldToken) {
+                throw new Error(`coolify:boule for ${org.slug}: the platform's own Lettermint token is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`);
+            }
+            const current = (await this.ports.coolify.listEnvs(appId)).find((e) => e.key === 'LETTERMINT_API_TOKEN' && !e.is_preview)?.value;
+            if (current === heldToken)
+                return none;
+            await this.ports.coolify.bulkUpsertEnvs(appId, [
+                { key: 'LETTERMINT_API_TOKEN', value: heldToken },
+            ]);
+            return { changed: true, restarted: false };
+        }
+        const { selfChanged, selfRestarted } = await this.ensureOrgAppMailToken({
+            org,
+            context,
+            mailDomain,
+            self: { role: 'boule', id: appId, restart: running },
+            mailFrom: null,
+            platformApex,
+            platformLettermintProjectId,
+        });
+        return { changed: selfChanged, restarted: selfRestarted };
+    }
     // ---- jobs (#173) ---------------------------------------------------------
     /**
      * `plan/diff.ts`'s `planJobsRegistration`: registers the org's own app with

package/dist/plan/providers-readers.d.ts

@@ -1,7 +1,7 @@
 import type { CloudflareClient } from '@wtfalch/providers/cloudflare';
 import type { CoolifyClient } from '@wtfalch/providers/coolify';
 import { type ZitadelClient } from '@wtfalch/providers/zitadel';
-import type { OrgId } from '../org.js';
+import { type OrgId } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
 import type { AiReader, CloudflareReader, CmsReader, CoolifyReader, LiveResource, ZitadelReader } from './live.js';
 /** The `CoolifyClient` methods the readers call, so a host's own implementation needs no cast. */

package/dist/plan/providers-readers.js

@@ -1,5 +1,6 @@
 import { ZitadelError } from '@wtfalch/providers/zitadel';
-import { BOULE_MANAGED_ENV_KEYS } from './boule.js';
+import { APP_ENTRY_KEY } from '../org.js';
+import { BOULE_MAIL_TOKEN_ENV, BOULE_MANAGED_ENV_KEYS } from './boule.js';
 /**
  * A {@link ScopeResolver} backed by `AppliedState.serviceIds` (`../state.ts`)
  * — the one place foundry records a provider's own id for an org today,
@@ -247,7 +248,7 @@ async function withAgoraEnvConfig(client, resource, recorded) {
  * `executor.ts` would write. Gated and failing exactly like
  * {@link withAgoraEnvConfig}.
  */
-async function withBouleEnvConfig(client, resource, recorded) {
+async function withBouleEnvConfig(client, resource, recorded, liveKeys) {
     if (resource.kind !== 'application' || !recorded[resource.key]?.startsWith('boule:')) {
         return resource;
     }
@@ -257,7 +258,20 @@ async function withBouleEnvConfig(client, resource, recorded) {
         if (!e.is_preview && managed.includes(e.key))
             env[e.key] = e.value;
     }
-    return { ...resource, config: { ...resource.config, env } };
+    // The hosted app's Lettermint token, as `config.appMailToken`: the one
+    // Boule must hold too. In memory only, compared by `planBoule` and never
+    // written to a step, description or log.
+    const orgId = recorded[resource.key]?.slice('boule:'.length);
+    const appUuid = Object.entries(recorded).find(([, value]) => value === `app:${orgId}:${APP_ENTRY_KEY}`)?.[0];
+    // A recorded app that is not in the live listing is gone: no app token, and
+    // no read of its envs. A listed app whose read fails fails like any read.
+    const appToken = appUuid && liveKeys.has(appUuid)
+        ? (await client.listEnvs(appUuid)).find((e) => !e.is_preview && e.key === BOULE_MAIL_TOKEN_ENV)?.value
+        : undefined;
+    return {
+        ...resource,
+        config: { ...resource.config, env, ...(appToken ? { appMailToken: appToken } : {}) },
+    };
 }
 /** `@wtfalch/providers`' own `LiveResource` (`resource.ts`) has no `system` field — foundry's adds it at this boundary. */
 function toFoundryResources(system, resources) {
@@ -290,7 +304,8 @@ export class ProvidersCoolifyReader {
         const withEnvNames = await Promise.all(withHealthCheck.map((r) => withEnvNamesConfig(this.client, r, recorded)));
         const withDbUrl = await Promise.all(withEnvNames.map((r) => withDatabaseUrlConfig(this.client, r, recorded)));
         const withAgoraConfig = await Promise.all(withDbUrl.map((r) => withAgoraEnvConfig(this.client, r, recorded)));
-        const withBouleConfig = await Promise.all(withAgoraConfig.map((r) => withBouleEnvConfig(this.client, r, recorded)));
+        const liveKeys = new Set(withAgoraConfig.map((r) => r.key));
+        const withBouleConfig = await Promise.all(withAgoraConfig.map((r) => withBouleEnvConfig(this.client, r, recorded, liveKeys)));
         return applyRecordedIds(withBouleConfig, recorded);
     }
     /** The project's resources as Coolify reports them, unmapped: what adopt checks against a declaration. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",