@wtfalch/foundry 0.5.0 → 0.7.1

package/dist/plan/diff.js

@@ -1,5 +1,7 @@
-import { NO_AGORA_HOST_VALUES, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.js';
-import { ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, } from './platform-diff.js';
+import { NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.js';
+import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHostnameFor, } from './login-host.js';
+import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } 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';
 import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
@@ -52,7 +54,11 @@ function resourceKey(system, kind, key) {
  * app with the platform's jobs scheduler, idempotent on the *recorded*
  * resource id like {@link planOwner} rather than a live resource, since
  * nothing in `live` can report a scheduler registration (no reader exists for
- * it). Everything
+ * it). #267 adds one more, right after {@link planOwner} and before every
+ * app-creating step below: {@link planLoginHost}, the org's own company
+ * login host -- also idempotent on the *recorded* resource id, since
+ * `live` has no notion of a ZITADEL trusted domain or a login binding
+ * either. Everything
  * else in `live` that none of these eighteen singletons and however many
  * declared issuer apps claim is unmanaged. The full field-by-field provisioning surface (SSO,
  * guests, calls on the org's own domain, adopted/bespoke apps, the actual
@@ -60,7 +66,7 @@ function resourceKey(system, kind, key) {
  * Company Factory end to end", which wires real readers and executors
  * against this seam.
  */
-export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AGORA_HOST_VALUES, jobsAvailable = false, platformReadiness = DEFAULT_ORG_PLATFORM_READINESS) {
+export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AGORA_HOST_VALUES, jobsAvailable = false, platformReadiness = DEFAULT_ORG_PLATFORM_READINESS, options = {}) {
     const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
     const claimed = new Set();
     const plannedSteps = [];
@@ -70,9 +76,32 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const owner = planOwner(org, recordedIds, platformReadiness.authReady);
     if (owner)
         plannedSteps.push(owner);
+    // #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);
+    if (loginHost.step)
+        plannedSteps.push(loginHost.step);
+    // Planned ahead of everything that needs the zone live (#238); its own step
+    // is still pushed in its usual place below.
+    const zone = planZone(org, byKey, claimed);
+    const zoneWaiting = zone.blocked !== null;
+    const zoneBlocked = [];
     const mail = planMail(org, byKey, claimed, recordedIds, platformReadiness.mailHost);
-    if (mail.step)
+    // #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) {
+        zoneBlocked.push({
+            description: `${org.slug}'s mail is blocked, not planned: the zone for ${org.domain} is not active yet`,
+            key: 'coolify:mail:zone',
+        });
+    }
+    else if (mail.step) {
         plannedSteps.push(mail.step);
+    }
+    const mailCopy = planMailCopy(org, byKey, recordedIds);
+    if (mailCopy)
+        plannedSteps.push(mailCopy);
     const chat = planChat(org, byKey, claimed);
     if (chat)
         plannedSteps.push(chat);
@@ -131,21 +160,36 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const database = planDatabase(org, byKey, claimed);
     if (database)
         plannedSteps.push(database);
-    const app = planApp(org, byKey, claimed);
-    if (app)
-        plannedSteps.push(app);
-    const tunnel = planTunnel(org, byKey, claimed);
-    if (tunnel)
+    const app = planApp(org, byKey, claimed, recordedIds, plannedSteps);
+    if (app.step)
+        plannedSteps.push(app.step);
+    const tunnel = planTunnel(org, byKey, claimed, recordedIds);
+    // #238: a tunnel that is being provisioned waits for an active zone; parking
+    // one never does.
+    if (tunnel && zoneWaiting && tunnel.action.desired.enabled !== false) {
+        zoneBlocked.push({
+            description: `${org.slug}'s Cloudflare tunnel is blocked, not planned: the zone for ${org.domain} is not active yet`,
+            key: 'cloudflare:tunnel',
+        });
+    }
+    else if (tunnel) {
         plannedSteps.push(tunnel);
-    const zone = planZone(org, byKey, claimed);
-    if (zone)
-        plannedSteps.push(zone);
+    }
+    if (zone.step)
+        plannedSteps.push(zone.step);
     // Right after the zone (#43): `cloudflareRateLimit` resolves the zone by
     // apex domain, so the zone step above must already have run (or the zone
     // must already exist live) by the time this one's action executes.
     const rateLimit = planRateLimit(org, recordedIds);
-    if (rateLimit)
+    if (rateLimit && zoneWaiting) {
+        zoneBlocked.push({
+            description: `${org.slug}'s sign-in rate limit is blocked, not planned: the zone for ${org.domain} is not active yet`,
+            key: 'cloudflare:ratelimit',
+        });
+    }
+    else if (rateLimit) {
         plannedSteps.push(rateLimit);
+    }
     // After the apps: the customers org is granted the project the first app
     // step creates.
     const customers = planCustomers(org, live, claimed, recordedIds);
@@ -195,8 +239,17 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // budget, key) would otherwise also have nothing to act on.
     if (issuer.blocked)
         unmanaged.push({ description: issuer.blocked, key: 'zitadel:issuer' });
+    // #267 (rule 2): a login host with no ZITADEL org to trust it in is blocked, not planned to throw.
+    if (loginHost.blocked) {
+        unmanaged.push({ description: loginHost.blocked, key: 'zitadel:login-host' });
+    }
     if (mail.blocked)
         unmanaged.push({ description: mail.blocked, key: 'coolify:mail' });
+    // #162: reported separately from `mail.blocked` -- missing an owner
+    // mailbox address never blocks the rest of this org's mail.
+    if (mail.mailboxBlocked) {
+        unmanaged.push({ description: mail.mailboxBlocked, key: 'coolify:mail:owner-mailbox' });
+    }
     if (calls.blocked)
         unmanaged.push({ description: calls.blocked, key: 'coolify:calls' });
     if (filesOrganisation.blocked) {
@@ -209,6 +262,13 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         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
+    // silently treated as converged.
+    if (zone.blocked)
+        unmanaged.push({ description: zone.blocked, key: 'cloudflare:zone' });
+    unmanaged.push(...zoneBlocked);
+    // #243: an appEnv source nothing will record is reported, not silently skipped.
+    unmanaged.push(...app.blocked);
     return { orgId: org.id, plannedSteps, unmanaged };
 }
 /**
@@ -346,6 +406,83 @@ function planOwner(org, recordedIds, authReady) {
         },
     };
 }
+/**
+ * #267: the org's own company login host (`login-host.ts`'s
+ * `loginHostnameFor`) -- `auth.<domain>` once the org has one,
+ * `<slug>-auth.oikos.host` for tier 1. Idempotent on the *recorded*
+ * resource id, the same shape `planOwner` above uses and for the same
+ * reason: `ZitadelReader.listResources` has no notion of a trusted domain
+ * or a login binding, so there is nothing in `live` this step could ever
+ * claim or compare against.
+ *
+ * Unlike `planOwner`, a re-run is not simply "already done or not": the
+ * recorded value is compared against {@link loginHostnameFor}'s own value
+ * for *this* apply, so an org moving from tier 1 onto its own domain (or
+ * losing one) replans this step rather than staying silent forever once
+ * first applied -- `executor.ts`'s `zitadelLoginHost` then also moves every
+ * already-live app onto the new base URI. Mints nothing either way: adding
+ * a trusted domain is not a one-time secret, so there is no "undelivered"
+ * guard to check the way `planJobsRegistration`'s own does.
+ *
+ * Ordered right after `planOwner` (not after mail, chat, or any hosting
+ * step), for the same reason `planOwner`'s own doc comment gives: on a
+ * first-ever apply the ZITADEL org this step's executor needs
+ * (`context.recordedIds().zitadel_org`) has already been recorded by the
+ * issuer step two steps before it in the same run, and this step itself
+ * runs well before `planIssuerApps`/`planCmsClient`/`planAgoraClient`
+ * create any app under the org's project -- #267's own "before any app's
+ * issuer application".
+ */
+function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired) {
+    const none = { step: null, blocked: null };
+    const key = resourceKey('zitadel', 'login-host', org.id);
+    const host = loginHostnameFor(org);
+    // Already applied -- a re-run plans nothing unless the host changed or an app
+    // client id appeared since the binding was last written (#267, rule 4).
+    if (recordedIds[key] === host &&
+        recordedIds[LOGIN_BINDING_SCOPE_KEY] ===
+            loginBindingState(host, loginHostClientIds(recordedIds))) {
+        return none;
+    }
+    // #177: nothing to add a trusted domain to yet -- `planIssuer` already
+    // reports the platform's sign-in as blocked, so this step stays silent
+    // rather than repeating it, the same rule `planOwner` follows.
+    if (!authReady)
+        return none;
+    // Isolation between orgs rests on zitadel-login's binding, and repointing
+    // an app at a host with no binding breaks its sign-in: trust nothing and
+    // repoint nothing until the port that writes the binding is wired.
+    if (!bindingsWired) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s login host ${host} waits for the loginHostBindings port, which the host has not wired`,
+        };
+    }
+    // No ZITADEL org to trust the host in: wait for it, unless the issuer step
+    // in this very plan creates it first (it runs before this one).
+    if (!recordedIds[ZITADEL_ORG_SCOPE_KEY] && !issuerPlanned) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s login host ${host} waits for its ZITADEL org, which is not recorded yet`,
+        };
+    }
+    return {
+        step: {
+            action: {
+                system: 'zitadel',
+                kind: 'login-host',
+                key: org.id,
+                desired: { host },
+            },
+            step: {
+                description: `set ${org.slug}'s login host to ${host}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 /**
  * #162: the flat scope id `executor.ts`'s `ensureOwnerMailbox` records once
  * it has given the org's owner a mailbox (`MAIL_OWNER_MAILBOX_SCOPE_KEY`
@@ -353,6 +490,12 @@ function planOwner(org, recordedIds, authReady) {
  * `LOG_DIR` precedent follows for a value shared with `executor.ts`.
  */
 const MAIL_OWNER_MAILBOX_SCOPE_KEY = 'mail_owner_mailbox';
+/** #230: restated from `executor.ts`'s `MAIL_ROLE_MAILBOXES_SCOPE_KEY`, same rule: comma-joined local parts already created. */
+const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
+/** Restated from `executor.ts`, the same rule: the app id of the org tunnel's cloudflared connector. */
+const CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY = 'cloudflare_tunnel_connector_app';
+/** Restated from `executor.ts`, the same rule: the mail domain the last apply resolved. */
+const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
 /** Restated from `executor.ts`, the same rule: the id of an ai key minted but not delivered. */
 export const AI_KEY_UNDELIVERED_SCOPE_KEY = 'ai_key_undelivered';
 /** Restated from `executor.ts`, the same rule: the id of a jobs project registered but not delivered. */
@@ -376,13 +519,14 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
     // after having it would silently hide its own leftover mail resource from
     // the unmanaged list.
     if (org.mail.mode === 'off')
-        return { step: null, blocked: null };
+        return { step: null, blocked: null, mailboxBlocked: null };
     if (live)
         claimed.add(key);
     if (!mailHost) {
         return {
             step: null,
             blocked: `${org.slug}'s mail is blocked, not planned: the platform's mail server is off or not yet applied`,
+            mailboxBlocked: null,
         };
     }
     const desired = {
@@ -391,12 +535,33 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
         apex: mailHost.apex,
         mailHost: mailHost.mailHost,
     };
-    // #162: an owner's mailbox is minted inside the same `coolify:mail` step,
-    // after `applyOrgMail` -- so as long as one is still owed, this step must
-    // keep showing up even once mode/usesDomain themselves have nothing left
-    // to change, or the operator would apply and never see it happen.
-    const mailboxOwed = Boolean(org.owner) && !recordedIds[MAIL_OWNER_MAILBOX_SCOPE_KEY];
-    const mailboxNote = mailboxOwed ? ` and give ${org.slug}'s owner a mailbox` : '';
+    // #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
+    // owed, this step must keep showing up even once mode/usesDomain
+    // themselves have nothing left to change, or the operator would apply and
+    // never see it happen. Nothing is guessed any more: without a declared
+    // `mail.ownerMailboxAddress`, the mailbox alone is reported blocked below
+    // (`mailboxBlocked`), the same "blocked, not planned" pattern a blocked
+    // Agora already follows (PR 180) -- the rest of this step, and every
+    // other step in the org's plan, is unaffected.
+    const mailboxAlreadyGiven = Boolean(recordedIds[MAIL_OWNER_MAILBOX_SCOPE_KEY]);
+    const hasOwner = Boolean(org.owner);
+    const ownerMailboxAddress = org.mail.ownerMailboxAddress ?? null;
+    const mailboxBlocked = hasOwner && !mailboxAlreadyGiven && !ownerMailboxAddress
+        ? `${org.slug}'s owner mailbox is blocked, not planned: mail.ownerMailboxAddress is not declared`
+        : null;
+    const mailboxOwed = hasOwner && !mailboxAlreadyGiven && ownerMailboxAddress !== null;
+    // #230: declared role mailboxes not yet recorded as created. Names only
+    // ever count here, never appear in a description, same as the owner's address.
+    // Recorded per address, so a changed mail domain owes its own set. A hosted
+    // org's domain is only known once recorded; until then every role is owed.
+    const createdRoles = new Set((recordedIds[MAIL_ROLE_MAILBOXES_SCOPE_KEY] ?? '').split(','));
+    const roleDomain = (org.mail.usesDomain && org.domain) || recordedIds[MAIL_DOMAIN_SCOPE_KEY];
+    const rolesOwed = (org.mail.roleMailboxes ?? []).filter((r) => !roleDomain || !createdRoles.has(`${r}@${roleDomain}`.toLowerCase())).length;
+    const ownerNote = mailboxOwed ? `give ${org.slug}'s owner a mailbox` : '';
+    const roleNote = rolesOwed > 0 ? `create ${rolesOwed} role mailbox(es) for ${org.slug}` : '';
+    const mailboxWork = [ownerNote, roleNote].filter(Boolean).join(' and ');
+    const mailboxNote = mailboxWork ? ` and ${mailboxWork}` : '';
     if (!live) {
         return {
             step: {
@@ -408,6 +573,7 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
                 },
             },
             blocked: null,
+            mailboxBlocked,
         };
     }
     const liveMode = live.config.mode;
@@ -417,20 +583,21 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
         // them (or it never recorded them). Re-applying is idempotent.
         const addressMoved = recordedIds[ORG_MAIL_APPLIED_APEX_SCOPE_KEY] !== mailHost.apex ||
             recordedIds[ORG_MAIL_APPLIED_HOST_SCOPE_KEY] !== mailHost.mailHost;
-        if (!mailboxOwed && !addressMoved)
-            return { step: null, blocked: null };
+        if (!mailboxWork && !addressMoved)
+            return { step: null, blocked: null, mailboxBlocked };
         return {
             step: {
                 action: { system: 'coolify', kind: 'mail', key: org.id, desired },
                 step: {
                     description: addressMoved
                         ? `re-apply ${org.slug}'s mail on the platform's mail host ${mailHost.mailHost}${mailboxNote}`
-                        : `give ${org.slug}'s owner a mailbox`,
+                        : mailboxWork,
                     destroys: false,
                     migrates: false,
                 },
             },
             blocked: null,
+            mailboxBlocked,
         };
     }
     if (liveUsesDomain && !desired.usesDomain) {
@@ -446,6 +613,21 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
                 },
             },
             blocked: null,
+            mailboxBlocked,
+        };
+    }
+    // #113: moving from `received` to `hosted` is an MX cutover, and foundry
+    // never cuts over before an org's old mail has copied into Stalwart --
+    // `planMailCopy`'s own step is what runs that copy. Blocked, not planned,
+    // the same "withhold the step rather than apply it half-ready" rule
+    // `mailboxBlocked` already follows just above.
+    if (liveMode === 'received' &&
+        desired.mode === 'hosted' &&
+        !recordedIds[MAIL_COPY_DONE_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s mail cannot move to hosted yet: its old mail is still being copied into Stalwart (coolify:mail-copy, #113)`,
+            mailboxBlocked,
         };
     }
     // A mode transition (#7 "Transitions") or turning a domain on is a
@@ -460,9 +642,44 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
             },
         },
         blocked: null,
+        mailboxBlocked,
+    };
+}
+/**
+ * #113: the one-time copy of an org's old mail into Stalwart that must
+ * finish before `planMail` allows the `received` -> `hosted` MX cutover
+ * above. Planned only for that exact transition -- a fresh org declared
+ * `hosted` from the start, or one moving between any other pair of modes,
+ * has nothing to migrate from and never sees this step. Never matched
+ * against a live resource: like `platform-diff.ts`'s `planSfu`, there is no
+ * live state to probe here (`runMailCopyStep`'s own progress is recorded
+ * state, not something a reader lists), so this plans again on every apply
+ * until {@link MAIL_COPY_DONE_SCOPE_KEY} is recorded.
+ */
+function planMailCopy(org, byKey, recordedIds) {
+    if (org.mail.mode !== 'hosted')
+        return null;
+    if (recordedIds[MAIL_COPY_DONE_SCOPE_KEY])
+        return null;
+    const live = byKey.get(resourceKey('coolify', 'mail', org.id));
+    if (!live || live.config.mode !== 'received')
+        return null;
+    const completed = parseMailCopyCompleted(recordedIds[MAIL_COPY_COMPLETED_SCOPE_KEY]);
+    const progress = completed.length > 0 ? ` (${completed.length} account(s) already copied)` : '';
+    return {
+        action: { system: 'coolify', kind: 'mail-copy', key: org.id, desired: {} },
+        step: {
+            description: `copy ${org.slug}'s old mail into Stalwart before the MX cutover${progress} -- re-apply again to continue, or tomorrow if a provider's daily limit was hit`,
+            destroys: false,
+            migrates: false,
+        },
     };
 }
 function planChat(org, byKey, claimed) {
+    // Chat off (not in v1): plan nothing, and leave any live chat unclaimed so
+    // it is reported in `unmanaged` and never adopted or destroyed.
+    if (!org.chat.enabled)
+        return null;
     const key = resourceKey('coolify', 'chat', org.id);
     const live = byKey.get(key);
     if (live)
@@ -1120,23 +1337,103 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
  * resource's `enabled` field -- a live resource nothing has actually
  * checked yet is assumed fine rather than replanned every time.
  */
-function planApp(org, byKey, claimed) {
+function planApp(org, byKey, claimed, recordedIds, plannedSteps) {
+    // #243: an `appEnv` source with no recorded value and no step planned to
+    // record one this run has nothing to push, now or after this apply.
+    const sourceStep = {
+        filesOrganisationId: ['files', 'organisation'],
+        aiOrganisationId: ['ai', 'organisation'],
+        mailDomain: ['coolify', 'mail'],
+    };
+    const { values: wantedEnv, unresolved } = resolveAppEnv(org, recordedIds);
+    const blocked = org.hosting.enabled
+        ? unresolved
+            .filter(([, source]) => !plannedSteps.some((p) => p.action.system === sourceStep[source][0] &&
+            p.action.kind === sourceStep[source][1]))
+            .map(([name, source]) => ({
+            description: `${org.slug}'s app env ${name} is blocked, not planned: its source ${source} has no recorded value yet`,
+            key: `coolify:app:env:${name}`,
+        }))
+        : [];
     const toggled = planHostingToggle('coolify', 'app', org.hosting.enabled, org, byKey, claimed, () => `provision ${org.slug}'s app`, () => `park ${org.slug}'s app (stops serving; app data is retained, not deleted -- #7 corrections 1)`);
     if (toggled)
-        return toggled;
+        return { step: toggled, blocked };
     if (!org.hosting.enabled)
-        return null;
+        return { step: null, blocked };
     const live = byKey.get(resourceKey('coolify', 'app', org.id));
-    if (!live || live.config.hasLogVolume !== false)
-        return null;
-    return {
-        action: { system: 'coolify', kind: 'app', key: org.id, desired: { enabled: true } },
-        step: {
-            description: `add a durable log directory to ${org.slug}'s app (persistent volume at /app/logs + LOG_DIR) so a database outage does not erase the evidence (#75)`,
-            destroys: false,
-            migrates: false,
-        },
+    if (!live)
+        return { step: null, blocked };
+    const action = {
+        system: 'coolify',
+        kind: 'app',
+        key: org.id,
+        desired: { enabled: true },
     };
+    if (live.config.hasLogVolume === false) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `add a durable log directory to ${org.slug}'s app (persistent volume at /app/logs + LOG_DIR) so a database outage does not erase the evidence (#75)`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    // #239 (rule 4), from live state: an app with a database but no
+    // `DATABASE_URL_OWNER` env still has the pre-split superuser URL, or never
+    // got the push. Names only, never values. A reader that did not list env
+    // names (`envNames` absent) reads as compliant, like `hasLogVolume`.
+    const envNames = live.config.envNames;
+    const dbLive = byKey.get(resourceKey('coolify', 'database', org.id));
+    const dbReady = org.hosting.database && Boolean(recordedIds[`coolify:database:${org.id}`]);
+    if (dbReady && dbLive?.config.hasInternalUrl === false) {
+        // Rule 2: the push cannot succeed yet, so report it rather than replan
+        // forever.
+        blocked.push({
+            description: `${org.slug}'s app database URLs are blocked, not planned: the database reports no internal connection URL yet`,
+            key: 'coolify:app:database-url',
+        });
+    }
+    else if (dbReady &&
+        // Only a read that saw the URL replans: an unread database (a failed
+        // read) would plan a step that pushes nothing, forever.
+        dbLive?.config.hasInternalUrl === true &&
+        ((Array.isArray(envNames) && !envNames.includes('DATABASE_URL_OWNER')) ||
+            // A crash between the push and the restart leaves the env right and no
+            // marker: replan once more to restart and set it.
+            !recordedIds[DB_ENV_APPLIED_SCOPE_KEY])) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `give ${org.slug}'s app its owner and runtime database URLs and restart it (#239)`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    // #243 (rule 3): a changed `hosting.appEnv` reaches an app that is already
+    // live. `pushAppEnv` records what it pushed, so this plans the same step
+    // again, with a redeploy, only once the resolved map differs from that.
+    if (JSON.stringify(wantedEnv) !== (recordedIds[APP_ENV_APPLIED_SCOPE_KEY] ?? '{}')) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `push ${org.slug}'s changed app env (appEnv) and redeploy the app`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    return { step: null, blocked };
 }
 /**
  * #173: register the org's own app with the platform's jobs scheduler
@@ -1244,12 +1541,48 @@ function planDatabase(org, byKey, claimed) {
  * domain) plans no per-org tunnel for Agora: `<slug>-agora.oikos.host` rides
  * the shared `*.oikos.host` wildcard tunnel (`scripts/shared-ingress.mjs`).
  */
-function planTunnel(org, byKey, claimed) {
+function planTunnel(org, byKey, claimed, recordedIds) {
     const desired = (org.hosting.tunnel && org.hosting.usesDomain && Boolean(org.domain)) ||
         (org.site.enabled && Boolean(org.domain)) ||
         (org.calls.enabled && org.calls.usesDomain && Boolean(org.domain)) ||
         Boolean(org.domain);
-    return planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`);
+    const toggled = planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`);
+    if (toggled || !desired)
+        return toggled;
+    // #235: a live, enabled tunnel with no connector recorded -- a first
+    // connector create that failed, or a tunnel that predates connectors --
+    // plans the same step again. The step finds or creates the connector by
+    // name, so it never makes a second one.
+    const live = byKey.get(resourceKey('cloudflare', 'tunnel', org.id));
+    if (!live || recordedIds[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY])
+        return null;
+    return {
+        action: { system: 'cloudflare', kind: 'tunnel', key: org.id, desired: { enabled: true } },
+        step: {
+            description: `run a cloudflared connector for ${org.slug}'s Cloudflare tunnel`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/**
+ * #238: the org's own zone's live `status`/`name_servers`, read from the
+ * same `kind: 'zone'` {@link LiveResource} `planZone` already matches by key
+ * -- `@wtfalch/providers/cloudflare`'s `CloudflareClient.listResources`
+ * already returns both (`config: { id, status, name_servers }`), so nothing
+ * new has to be fetched; this just reads what was already there. `null`
+ * means no zone is live yet at all (not a readiness problem `planZone`
+ * itself reports -- it is still planning the zone's own creation).
+ */
+function zoneReadiness(domain, byKey) {
+    const zone = byKey.get(resourceKey('cloudflare', 'zone', domain));
+    if (!zone)
+        return null;
+    const config = zone.config;
+    return {
+        active: config.status === 'active',
+        nameServers: config.name_servers ?? [],
+    };
 }
 /**
  * The org's Cloudflare zone for its own domain (`org.ts`'s
@@ -1281,25 +1614,40 @@ function planZone(org, byKey, claimed) {
         (org.calls.enabled && org.calls.usesDomain) ||
         Boolean(org.domain);
     if (!usesDomain || !org.domain)
-        return null;
+        return { step: null, blocked: null };
     const key = resourceKey('cloudflare', 'zone', org.domain);
     const live = byKey.get(key);
-    if (live)
+    if (live) {
         claimed.add(key);
-    if (live)
-        return null;
+        const readiness = zoneReadiness(org.domain, byKey);
+        // #238: a zone stays pending until the customer changes nameservers at
+        // their registrar -- reported here, not silently treated as converged,
+        // so an apply says what it is waiting for. A later apply, once
+        // Cloudflare marks the zone active, reports nothing and the DNS- and
+        // mail-dependent steps below (`planMail`) resume.
+        if (readiness && !readiness.active) {
+            return {
+                step: null,
+                blocked: `${org.slug}'s zone for ${org.domain} is waiting for nameservers: ${readiness.nameServers.join(', ')}`,
+            };
+        }
+        return { step: null, blocked: null };
+    }
     return {
-        action: {
-            system: 'cloudflare',
-            kind: 'zone',
-            key: org.domain,
-            desired: { domain: org.domain },
-        },
         step: {
-            description: `provision a Cloudflare zone for ${org.domain}`,
-            destroys: false,
-            migrates: false,
+            action: {
+                system: 'cloudflare',
+                kind: 'zone',
+                key: org.domain,
+                desired: { domain: org.domain },
+            },
+            step: {
+                description: `provision a Cloudflare zone for ${org.domain}`,
+                destroys: false,
+                migrates: false,
+            },
         },
+        blocked: null,
     };
 }
 /**