@wtfalch/foundry 0.16.16 → 0.17.1

package/dist/plan/diff.js

@@ -1,17 +1,20 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
-import { CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
+import { AGORA_ACTIVATED_ENV_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_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 { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
+import { planEdgeWorkers } from './edge-worker.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
 import { planFilesKeys } from './entry-files-key.js';
+import { planEntryNamesKeys, planNamesReservedLabels } from './entry-names-key.js';
 import { appHostname, entryHostnames, tunnelDnsHostnames } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHostnameFor, pendingRemovalHosts, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } from './mail-copy.js';
-import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, versionNotAppliedLine, } from './platform-diff.js';
+import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, serviceDbEnvAppliedScopeKey, versionNotAppliedLine, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec } from './proxy-labels.js';
+import { withStepSystem } from './step-system.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
     return {
@@ -42,9 +45,8 @@ function resourceKey(system, kind, key) {
  * `hosting.issuerApps[]` entry rather than a single singleton, since an org
  * can declare more than one ZITADEL app. #80 adds two more singletons,
  * modeled on {@link planIssuer}: `planFilesOrganisation` and
- * `planAiOrganisation`, each planned before its own system's limit step
- * ({@link planStorage}, {@link planAiBudget}) so an org has somewhere for a
- * limit to land, and AI use is switched on, before either limit is ever set.
+ * `planAiOrganisation`, the second planned before {@link planAiBudget} so AI
+ * use is switched on before its own limit is ever set.
  * `planOwners` below adds one more singleton, in a different shape from the
  * rest: the org's owner, invited by ZITADEL email, idempotent on the
  * *recorded* resource id (`recordedIds`, sourced from
@@ -87,7 +89,12 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // #267: after the ZITADEL org step, before any app's own issuer
     // application. Apps created later in this run are not in the binding yet;
     // the next run replans this step and repoints them.
-    const loginHost = planLoginHost(org, recordedIds, platformReadiness.authReady, issuer.step !== null, options.loginHostBindings ?? false);
+    const loginHost = planLoginHost(org, recordedIds, platformReadiness.authReady, issuer.step !== null, options.loginHostBindings ?? false, 
+    // #488: `agoraHost.issuer` is the shared ZITADEL instance's own issuer
+    // URL (`https://<platform.auth.hostname>`), the same value every org's
+    // sign-in already reads through `planOwners` above -- no separate port
+    // or plumbing needed to know the platform's own auth hostname.
+    platformAuthHostnameFrom('error' in agoraHost ? null : agoraHost.issuer));
     if (loginHost.step)
         plannedSteps.push(loginHost.step);
     // Planned ahead of everything that needs the zone live (#238); its own step
@@ -95,7 +102,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const zone = planZone(org, byKey, claimed);
     const zoneWaiting = zone.blocked !== null;
     const zoneBlocked = [];
-    const mail = planMail(org, byKey, claimed, recordedIds, platformReadiness.mailHost);
+    const mail = planMail(org, byKey, claimed, recordedIds, platformReadiness.mailHost, platformReadiness.platformApex, platformReadiness.platformLettermintProjectId);
     // #238: own-domain mail publishes DNS records into the zone, so it waits for
     // an active zone -- blocked, not planned (rule 2).
     if (mail.step && zoneWaiting && org.mail.usesDomain && org.domain) {
@@ -142,9 +149,6 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const filesOrganisation = planFilesOrganisation(org, byKey, claimed, platformReadiness.filesReady, platformReadiness.missingKeys.files, platformReadiness.noKeyReader);
     if (filesOrganisation.step)
         plannedSteps.push(filesOrganisation.step);
-    const storage = planStorage(org, byKey, claimed, platformReadiness.filesReady, platformReadiness.missingKeys.files, platformReadiness.noKeyReader);
-    if (storage.step)
-        plannedSteps.push(storage.step);
     const aiOrganisation = planAiOrganisation(org, byKey, claimed, platformReadiness.aiReady, platformReadiness.missingKeys.ai, platformReadiness.noKeyReader);
     if (aiOrganisation.step)
         plannedSteps.push(aiOrganisation.step);
@@ -200,6 +204,16 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // F6b: after the owner, the apps and the files organisation it needs.
     const filesKeys = planFilesKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
     plannedSteps.push(...filesKeys.steps);
+    // F7 (#317): reserved labels before any entry's own key, so a label is
+    // never claimable by a customer in the gap between an entry's key going
+    // live and its siblings' labels reaching names.
+    const namesReservedLabels = planNamesReservedLabels(org, recordedIds, platformReadiness);
+    if (namesReservedLabels.step)
+        plannedSteps.push(namesReservedLabels.step);
+    // After the apps -- a names key needs the entry's app recorded, the same
+    // dependency `planEntryAiKeys`/`planFilesKeys` have.
+    const entryNamesKeys = planEntryNamesKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
+    plannedSteps.push(...entryNamesKeys.steps);
     const tunnel = planTunnel(org, byKey, claimed, recordedIds);
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
@@ -257,6 +271,26 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const jobsRegistration = planJobsRegistration(org, recordedIds, jobsAvailable || platformReadiness.jobsReady, platformReadiness.missingKeys.jobs, platformReadiness.noKeyReader);
     if (jobsRegistration.step)
         plannedSteps.push(jobsRegistration.step);
+    // F8 (#318), after Agora and Boule, not right after the zone: a route
+    // already bound by a hand-made entry, another entry's route, a taken
+    // script name, or no Workers token all throw at apply, and `runSteps`
+    // stops at the first failure -- planned this early, a failing edge step
+    // stopped Agora (and everything after it) from provisioning at all
+    // (#318 re-review). `cloudflareWorker` still resolves the zone by apex
+    // domain the same way `planRateLimit` does, so a deploy (never a
+    // retire, which needs no new zone) still waits for it.
+    const edgeWorkers = planEdgeWorkers(org, recordedIds, options.edgeWorkers ?? false);
+    for (const step of edgeWorkers.steps) {
+        if (zoneWaiting && step.action.desired.mode === 'apply') {
+            zoneBlocked.push({
+                description: `${org.slug}'s ${step.action.key.slice(org.id.length + 1)} edge Worker is blocked, not planned: the zone for ${org.domain} is not active yet`,
+                key: step.action.key,
+            });
+        }
+        else {
+            plannedSteps.push(step);
+        }
+    }
     // #10 (resolved): "foundry manages only what the declared org names";
     // anything left unclaimed is listed, never proposed for deletion.
     const unmanaged = live
@@ -277,6 +311,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         unmanaged.push({ description: aiKey.blocked, key: 'ai:key' });
     unmanaged.push(...filesKeys.blocked);
     unmanaged.push(...entryAiKeys.blocked);
+    unmanaged.push(...edgeWorkers.blocked);
+    unmanaged.push(...entryNamesKeys.blocked);
+    unmanaged.push(...namesReservedLabels.blocked);
     // Same for a jobs registration that cannot run (no scheduler wired) or must
     // not run again (minted, never delivered).
     if (jobsRegistration.blocked) {
@@ -313,8 +350,6 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     if (aiOrganisation.blocked) {
         unmanaged.push({ description: aiOrganisation.blocked, key: 'ai:organisation' });
     }
-    if (storage.blocked)
-        unmanaged.push({ description: storage.blocked, key: 'files:storage' });
     if (aiBudget.blocked)
         unmanaged.push({ description: aiBudget.blocked, key: 'ai:budget' });
     // #238: a pending zone, reported here with its nameservers rather than
@@ -326,7 +361,12 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     unmanaged.push(...app.blocked);
     unmanaged.push(...brokerEntries.blocked);
     unmanaged.push(...bouleBroker.blocked);
-    return { orgId: org.id, plannedSteps, unmanaged, versionChanges };
+    return {
+        orgId: org.id,
+        plannedSteps: plannedSteps.map(withStepSystem),
+        unmanaged,
+        versionChanges,
+    };
 }
 /**
  * The org's own ZITADEL org (issuer), a per-org singleton like every other
@@ -471,6 +511,24 @@ function planOwners(org, recordedIds, authReady, authIssuer) {
     });
     return steps;
 }
+/**
+ * #488: the bare hostname out of an issuer URL (`https://<hostname>`, the
+ * only shape {@link agoraHostValuesFromPlatform} or a host-supplied
+ * `AgoraHostPort` ever hands back), or `null` when there is no issuer to
+ * read one from. What {@link loginHostnameFor} compares the org's own
+ * computed `auth.<domain>` against, so the platform's own org never plans
+ * its login host equal to the shared ZITADEL instance's own.
+ */
+function platformAuthHostnameFrom(issuer) {
+    if (!issuer)
+        return null;
+    try {
+        return new URL(issuer).hostname;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * #267: the org's own company login host (`login-host.ts`'s
  * `loginHostnameFor`) -- `auth.<domain>` once the org has one,
@@ -501,11 +559,22 @@ function planOwners(org, recordedIds, authReady, authIssuer) {
  * runs well before `planIssuerApps`/`planCmsClient`/`planAgoraClient`
  * create any app under the org's project -- #267's own "before any app's
  * issuer application".
+ *
+ * `platformAuthHostname` (#488) is threaded through to {@link
+ * loginHostnameFor} so the platform's own org, declared with-domain on the
+ * platform's own domain, never plans the shared ZITADEL instance's own login
+ * host as its own -- `auth.companyincluded.com` colliding with itself.
  */
-function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired) {
+function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired, platformAuthHostname) {
     const none = { step: null, blocked: null };
     const key = resourceKey('zitadel', 'login-host', org.id);
-    const host = loginHostnameFor(org);
+    const host = loginHostnameFor(org, platformAuthHostname);
+    // #488: the guard in `loginHostnameFor` fired -- the org's own domain host
+    // would have been the platform's shared ZITADEL instance host.
+    const sharedInstanceHost = Boolean(org.domain) &&
+        org.issuer.usesDomain &&
+        `auth.${org.domain}` === platformAuthHostname &&
+        host !== `auth.${org.domain}`;
     // Already applied -- a re-run plans nothing unless the host changed, an app
     // client id appeared since the binding was last written (#267, rule 4), or
     // an earlier host change still has a removal owed (#274 fix round 2):
@@ -549,7 +618,9 @@ function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired
                 desired: { host },
             },
             step: {
-                description: `set ${org.slug}'s login host to ${host}`,
+                description: sharedInstanceHost
+                    ? `set ${org.slug}'s login host to ${host}: its domain host (auth.${org.domain}) is the platform's own shared ZITADEL instance host, so it stays on oikos.host`
+                    : `set ${org.slug}'s login host to ${host}`,
                 destroys: false,
                 migrates: false,
             },
@@ -577,9 +648,14 @@ export const JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = 'jobs_registration_undeli
  * off this step's own `desired`, the same "the executor writes exactly these
  * host values, so what the plan showed is what gets applied" rule
  * `planAgora` already follows for its own host values -- never rebuilding
- * them itself from a literal or a second lookup.
+ * them itself from a literal or a second lookup. #491: `platformApex` and
+ * `platformLettermintProjectId` go into `desired` the same way, so the
+ * executor can recognise the platform's own org without needing the whole
+ * `DeclaredPlatform`.
  */
-function planMail(org, byKey, claimed, recordedIds, mailHost) {
+function planMail(org, byKey, claimed, recordedIds, mailHost, 
+/** #491 (review round 2): read off `platformReadiness` directly, not off `mailHost` -- see `OrgPlatformReadiness.platformApex`'s own doc comment for why. */
+platformApex, platformLettermintProjectId) {
     const key = resourceKey('coolify', 'mail', org.id);
     const live = byKey.get(key);
     // `off` means mail is not foundry's concern here (org.ts's MailMode doc);
@@ -599,11 +675,32 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
             mailboxBlocked: null,
         };
     }
+    // #491: this org's own declared domain is the platform's apex (Company
+    // Included on companyincluded.com, today) -- it shares the platform's
+    // existing Lettermint project rather than minting a `<slug>-app` one of
+    // its own, and `executor.ts` must never touch Lettermint for it until an
+    // operator has said which project that is. Blocked whole, not planned
+    // half-ready: "Blocked, not failing" (foundry's own CLAUDE.md).
+    const resolvedMailDomain = org.mail.usesDomain ? org.domain : null;
+    const isPlatformApexOrg = Boolean(resolvedMailDomain &&
+        platformApex &&
+        resolvedMailDomain.toLowerCase() === platformApex.toLowerCase());
+    if (isPlatformApexOrg && !platformLettermintProjectId) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s mail is blocked, not planned: its domain ${resolvedMailDomain} is the platform's own apex, and platform.mail.lettermintProjectId is not declared yet (#491)`,
+            mailboxBlocked: null,
+        };
+    }
     const desired = {
         mode: org.mail.mode,
         usesDomain: org.mail.usesDomain,
         apex: mailHost.apex,
         mailHost: mailHost.mailHost,
+        // #491: non-null whenever `mailHost` is -- both require a declared
+        // platform (`orgPlatformReadinessFrom`'s own doc comment).
+        platformApex,
+        platformLettermintProjectId,
     };
     // #162 (decided 2026-09-29): an owner's mailbox is minted inside the same
     // `coolify:mail` step, after `applyOrgMail` -- so as long as one is still
@@ -799,8 +896,35 @@ function planChat(org, byKey, claimed, recordedIds, reading, issuerPlanned) {
         };
     }
     const liveUsesDomain = Boolean(live.config.usesDomain);
-    if (liveUsesDomain === desiredUsesDomain)
+    if (liveUsesDomain === desiredUsesDomain) {
+        // #456: a live chat app made before the owner/runtime database split
+        // (#239) otherwise never gets another `coolify:chat` step at all --
+        // nothing else here ever differs for it again -- and its service keeps
+        // running on the bare superuser `DATABASE_URL` its own startup script
+        // now refuses. `coolifyChat` throws on any other action against an
+        // already-live chat (re-keying is not built, #7 amendment 3), so this
+        // step carries a distinct flag telling the executor to push only the
+        // split, never to replay the full provision.
+        if (!recordedIds[serviceDbEnvAppliedScopeKey('chat')]) {
+            return {
+                step: {
+                    action: {
+                        system: 'coolify',
+                        kind: 'chat',
+                        key: org.id,
+                        desired: { usesDomain: liveUsesDomain, refreshDatabaseSplit: true },
+                    },
+                    step: {
+                        description: `give ${org.slug}'s chat service its owner and runtime database URLs and redeploy it (#239, #456)`,
+                        destroys: false,
+                        migrates: false,
+                    },
+                },
+                blocked: null,
+            };
+        }
         return none;
+    }
     const domain = org.domain ?? 'its domain';
     if (!liveUsesDomain && desiredUsesDomain) {
         return {
@@ -933,17 +1057,19 @@ function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlo
         : step;
     if (toggle)
         return { step: withHost(toggle), blocked: null };
-    // A live, enabled app made before the internal name or the token env
-    // existed has no step from the toggle. Run the step again until the
-    // executor has recorded both markers, but only while it can succeed: the
-    // SFU ready and the Matrix stack not blocked.
+    // A live, enabled app made before the internal name, the token env or the
+    // owner/runtime database split (#239, #456) existed has no step from the
+    // toggle. Run the step again until the executor has recorded every marker,
+    // but only while it can succeed: the SFU ready and the Matrix stack not
+    // blocked.
     const missingName = !callsServiceHasName(org, recordedIds);
     const missingTokenEnv = !callsServiceHasTokenEnv(tokenHost, recordedIds);
+    const missingDbSplit = !recordedIds[serviceDbEnvAppliedScopeKey('calls-service')];
     if (org.calls.enabled &&
         callsReady &&
         !callsBlocked &&
         byKey.has(key) &&
-        (missingName || missingTokenEnv)) {
+        (missingName || missingTokenEnv || missingDbSplit)) {
         return {
             step: withHost({
                 action: {
@@ -955,7 +1081,9 @@ function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlo
                 step: {
                     description: missingName
                         ? `set the calls service's internal name for ${org.slug}`
-                        : `set the calls service's ZITADEL token env for ${org.slug}`,
+                        : missingTokenEnv
+                            ? `set the calls service's ZITADEL token env for ${org.slug}`
+                            : `give the calls service's owner and runtime database URLs for ${org.slug} and redeploy it (#239, #456)`,
                     destroys: false,
                     migrates: false,
                 },
@@ -976,6 +1104,32 @@ function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlo
  * explicit opt-in this default deliberately leaves out.
  */
 const AI_DEFAULT_OFFERS = ['ai.offerings:invoke', 'ai.runs:create'];
+/**
+ * #484: the spend cap foundry applies when an org declares no AI limit
+ * (`org.ai.limitMicros === null`) -- Archon creates every company that way,
+ * and AI's own `updateBudget` has no uncapped representation
+ * (`UpdateBudget.limitMicros` is a required string), so a null limit used to
+ * throw `ai:budget` out of every apply. William's Decision, 2026-10-05: 100
+ * EUR, in `ai`'s own USD-micros unit (`usdToMicros`,
+ * `ai/packages/service/src/money.ts`), billing to revisit the number later.
+ * 100 EUR at the ECB reference rate for 2 October 2026 (1.1225 USD/EUR, the
+ * most recent published rate as of the decision) is 112.25 USD = 112,250,000
+ * micros. A declared numeric limit always wins over this default --
+ * {@link effectiveAiLimitMicros} is the one place that substitutes it.
+ */
+export const DEFAULT_AI_LIMIT_MICROS = '112250000';
+/**
+ * #484: the limit foundry actually plans and applies for an org -- its own
+ * declared `ai.limitMicros` when it declares one, else {@link DEFAULT_AI_LIMIT_MICROS}.
+ * Both {@link planAiOrganisation} and {@link planAiBudget} fill
+ * `action.desired.limitMicros` through this one function, so a company with
+ * no declared limit gets the same 100 EUR cap whichever step sets it, and
+ * never reaches `executor.ts`'s `aiBudget` with a null `desired.limitMicros`
+ * for `updateBudget` to choke on.
+ */
+function effectiveAiLimitMicros(limitMicros) {
+    return limitMicros ?? DEFAULT_AI_LIMIT_MICROS;
+}
 /**
  * Why an org step on a shared platform service is blocked: a key that is not
  * held, no held-keys reader given at all, or the service off or not applied.
@@ -990,11 +1144,8 @@ function notReadyReason(service, keyName, missingKeyRef, noKeyReader) {
         : `the platform's ${service} host is off or not yet applied`;
 }
 /**
- * #80: every org's own organisation on Files, a per-org singleton resource
- * planned before {@link planStorage} -- `setQuota`/`setBudget` 404 against an
- * org Files has never provisioned (`files/packages/sdk/src/client.ts`'s
- * tenant routes need the row `provisionOrganisation` creates). Modeled on
- * {@link planIssuer}: nothing to diff once it exists -- Files' own
+ * #80: every org's own organisation on Files, a per-org singleton resource.
+ * Modeled on {@link planIssuer}: nothing to diff once it exists -- Files' own
  * `provisionOrganisation` is safely repeatable (`executor.ts`'s
  * `filesOrganisation` calls it every time regardless), so the only planned
  * state is "not provisioned yet". The operator-driven `ceilingBytes`/
@@ -1076,9 +1227,14 @@ function planFilesOrganisation(org, byKey, claimed, filesReady, missingKeyRef, n
  * regardless), so the only planned state is "not provisioned yet".
  * `AI_DEFAULT_OFFERS` is this campaign's Decision for what "AI use is
  * switched on" means by default; `limitMicros` seeds the organisation's
- * first budget row with whatever the org already declares (including
- * `null` for uncapped), so a brand new org never needs a follow-up
- * {@link planAiBudget} step just to reach its own declared default.
+ * first budget row with the org's own declared limit, or
+ * {@link DEFAULT_AI_LIMIT_MICROS} when it declares none (#484) --
+ * {@link effectiveAiLimitMicros} either way, the same value
+ * {@link planAiBudget} independently plans from `live` -- so a brand new
+ * org's first plan always carries both steps (same shape as any other
+ * declared limit, `ai:organisation` before `ai:budget`), and once that one
+ * apply run has pushed both, a later plan finds no further drift to
+ * replan.
  *
  * #177: blocked, not planned, while `aiReady` is false -- the platform's own
  * AI host (#172) is off or not yet applied.
@@ -1104,12 +1260,14 @@ function planAiOrganisation(org, byKey, claimed, aiReady, missingKeyRef, noKeyRe
                 key: org.id,
                 desired: {
                     provision: true,
-                    limitMicros: org.ai.limitMicros,
+                    limitMicros: effectiveAiLimitMicros(org.ai.limitMicros),
                     offers: [...AI_DEFAULT_OFFERS],
                 },
             },
             step: {
-                description: `provision ${org.slug}'s own organisation on AI and switch AI use on`,
+                description: org.ai.limitMicros === null
+                    ? `provision ${org.slug}'s own organisation on AI and switch AI use on, capped at the default of ${DEFAULT_AI_LIMIT_MICROS} micros (no limit declared)`
+                    : `provision ${org.slug}'s own organisation on AI and switch AI use on`,
                 destroys: false,
                 migrates: false,
             },
@@ -1117,56 +1275,20 @@ function planAiOrganisation(org, byKey, claimed, aiReady, missingKeyRef, noKeyRe
         blocked: null,
     };
 }
-/**
- * #27: the org's own spend limit on Files, a per-org singleton resource in
- * the same shape as issuer/mail/chat above. Setting a limit is a config
- * write, never destructive or migrating (#27 "Notes": "safe, idempotent and
- * reversible"). A missing live resource reads as uncapped (`null`), the same
- * value a freshly-declared org's `storage` starts at, so a brand new org with
- * no limits declared produces no step.
- *
- * #177: silently plans nothing while there is no organisation to size a limit
- * on yet and `filesReady` is false -- {@link planFilesOrganisation} already
- * reports the platform's files host as missing once.
- */
-function planStorage(org, byKey, claimed, filesReady, missingKeyRef, noKeyReader = false) {
-    const key = resourceKey('files', 'storage', org.id);
-    const live = byKey.get(key);
-    if (live)
-        claimed.add(key);
-    if (!filesReady && !live)
-        return { step: null, blocked: null };
-    const desired = { limitBytes: org.storage.limitBytes, limitMicros: org.storage.limitMicros };
-    const liveLimitBytes = live ? (live.config.limitBytes ?? null) : null;
-    const liveLimitMicros = live ? (live.config.limitMicros ?? null) : null;
-    if (liveLimitBytes === desired.limitBytes && liveLimitMicros === desired.limitMicros) {
-        return { step: null, blocked: null };
-    }
-    // A live resource with drift needs the platform's key to change; blocked, not planned to throw at apply.
-    if (!filesReady) {
-        return {
-            step: null,
-            blocked: `${org.slug}'s storage limit change is blocked, not planned: ${notReadyReason('files', 'files management key', missingKeyRef, noKeyReader)}`,
-        };
-    }
-    return {
-        blocked: null,
-        step: {
-            action: { system: 'files', kind: 'storage', key: org.id, desired },
-            step: {
-                description: `set ${org.slug}'s storage limit to ${desired.limitBytes ?? 'uncapped'} bytes / ${desired.limitMicros ?? 'uncapped'} micros`,
-                destroys: false,
-                migrates: false,
-            },
-        },
-    };
-}
 /**
  * #27: the org's own spend limit on AI, a per-org singleton resource in the
- * same shape as {@link planStorage}. Planned after {@link planAiOrganisation}
+ * same singleton shape as issuer/mail/chat above. Planned after {@link planAiOrganisation}
  * (#80), which already seeds a brand new org's first budget row from this
- * same `org.ai.limitMicros` -- this planner only fires again once that row's
- * live value has drifted from what is declared.
+ * same `org.ai.limitMicros` (or {@link DEFAULT_AI_LIMIT_MICROS}, #484) --
+ * this planner only fires again once that row's live value has drifted from
+ * what is declared (or defaulted).
+ *
+ * #484: `desired.limitMicros` goes through {@link effectiveAiLimitMicros},
+ * never the bare `org.ai.limitMicros` -- `executor.ts`'s `aiBudget` calls
+ * AI's `updateBudget`, whose `limitMicros` is a required string with no
+ * uncapped representation, so a step that reached it with `null` always
+ * threw. The description names the default explicitly when it is the one in
+ * effect, so an operator reading the plan sees which cap applies.
  *
  * #177: silently plans nothing while there is no organisation to size a
  * budget on yet and `aiReady` is false -- {@link planAiOrganisation} already
@@ -1179,7 +1301,8 @@ function planAiBudget(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader =
         claimed.add(key);
     if (!aiReady && !live)
         return { step: null, blocked: null };
-    const desired = { limitMicros: org.ai.limitMicros };
+    const isDefault = org.ai.limitMicros === null;
+    const desired = { limitMicros: effectiveAiLimitMicros(org.ai.limitMicros) };
     const liveLimitMicros = live ? (live.config.limitMicros ?? null) : null;
     if (liveLimitMicros === desired.limitMicros)
         return { step: null, blocked: null };
@@ -1194,7 +1317,9 @@ function planAiBudget(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader =
         step: {
             action: { system: 'ai', kind: 'budget', key: org.id, desired },
             step: {
-                description: `set ${org.slug}'s AI budget limit to ${desired.limitMicros ?? 'uncapped'} micros`,
+                description: isDefault
+                    ? `set ${org.slug}'s AI budget limit to the default of ${desired.limitMicros} micros (no limit declared)`
+                    : `set ${org.slug}'s AI budget limit to ${desired.limitMicros} micros`,
                 destroys: false,
                 migrates: false,
             },
@@ -1469,13 +1594,25 @@ function planAgora(org, byKey, claimed, recordedIds, reading) {
     if (liveEnv.AGORA_CONFIG === undefined && !drift.includes('AGORA_CONFIG')) {
         drift.push('AGORA_CONFIG');
     }
-    if (drift.length === 0)
+    // #442: `drift` alone, once this step has ever run, is comparing `env`
+    // against Coolify's own env store -- which the executor's `bulkUpsertEnvs`
+    // leaves matching `env` the moment the write succeeds, restarted or not.
+    // So once applied, drift reads empty forever even if the running process
+    // was never restarted onto it (a crash between the write and the restart,
+    // or simply never restarting at all). `AGORA_ACTIVATED_ENV_SCOPE_KEY` is
+    // the executor's own record that a restart confirmed the process is
+    // actually serving this exact `env`; while it disagrees, the step stays
+    // planned no matter what Coolify's env store already shows.
+    const activated = recordedIds[AGORA_ACTIVATED_ENV_SCOPE_KEY] === agoraEnvRevision(env);
+    if (drift.length === 0 && activated)
         return { step: null, blocked: null };
     return {
         step: {
             action,
             step: {
-                description: `update ${org.slug}'s Agora config (${drift.join(', ')} missing or different)`,
+                description: drift.length > 0
+                    ? `update ${org.slug}'s Agora config (${drift.join(', ')} missing or different)`
+                    : `activate ${org.slug}'s Agora config -- written but not yet confirmed restarted`,
                 destroys: false,
                 migrates: false,
             },
@@ -1692,6 +1829,32 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             key: blockedKey(`env:${name}`),
         })))
         : [];
+    // #491: the `app` entry's own Lettermint work (`executor.ts`'s
+    // `ensureAppLettermintMail`) reads `MAIL_DOMAIN_SCOPE_KEY` directly, which
+    // can already be recorded from before this org's domain became the
+    // platform's apex -- so this is checked here too, independently of
+    // whether `coolify:mail` itself is blocked this run (`planMail` above).
+    // Reported, not fatal: the rest of this entry's own plan is unaffected.
+    // Review round 2: reads `readiness.platformApex` directly, not
+    // `readiness.mailHost?.platformApex` -- the platform's own apex is a fact
+    // independent of whether its mail server happens to be enabled or applied
+    // right now, and gating this on `mailHost` let a platform-apex org with an
+    // already-recorded domain take the unprotected path the moment platform
+    // mail went back to off.
+    if (entryKey === APP_ENTRY_KEY) {
+        const mailDomain = recordedIds[MAIL_DOMAIN_SCOPE_KEY];
+        const platformApex = readiness.platformApex;
+        const platformLettermintProjectId = readiness.platformLettermintProjectId;
+        if (mailDomain &&
+            platformApex &&
+            mailDomain.toLowerCase() === platformApex.toLowerCase() &&
+            !platformLettermintProjectId) {
+            blocked.push({
+                description: `${org.slug}'s app Lettermint mail is blocked, not planned: its mail domain is the platform's own apex, and platform.mail.lettermintProjectId is not declared yet (#491)`,
+                key: blockedKey('lettermint-project'),
+            });
+        }
+    }
     const toggled = planHostingToggle('coolify', 'app', entry !== undefined, org, byKey, claimed, () => `provision ${org.slug}'s ${label}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
     if (toggled)
         return { step: toggled, blocked };
@@ -1894,6 +2057,21 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, re
             if (signsIn)
                 app.step.action.desired = { ...app.step.action.desired, authIssuer };
         }
+        // #491: only the `app` entry's own step runs `ensureAppLettermintMail`
+        // (`executor.ts`'s own `entry.key === APP_ENTRY_KEY` gate). Unlike
+        // `secretSources`/`authIssuer` above, these two are set unconditionally
+        // -- `null` when no platform is declared, never omitted -- because
+        // `executor.ts` treats the key being *absent* as a stale plan predating
+        // this field and refuses to run (review round 2, finding 3): an omitted
+        // key here would read identically to a stale plan and silently fall
+        // back to the unprotected pre-#491 path instead.
+        if (key === APP_ENTRY_KEY && app.step && app.step.action.desired.enabled !== false) {
+            app.step.action.desired = {
+                ...app.step.action.desired,
+                platformApex: readiness.platformApex,
+                platformLettermintProjectId: readiness.platformLettermintProjectId,
+            };
+        }
         if (app.step)
             steps.push(app.step);
         blocked.push(...app.blocked);