@wtfalch/foundry 0.6.0 → 0.8.0

package/dist/plan/calls-matrix.js

@@ -1,4 +1,5 @@
 import { generateKeyPairSync, randomBytes } from 'node:crypto';
+import { VERSIONS } from '../bootstrap/versions.js';
 /**
  * The calls Matrix stack (#128, part 1 of 2 -- see that issue's "If this
  * passes about 800 changed lines, split it" note): pure config generation
@@ -46,8 +47,10 @@ import { generateKeyPairSync, randomBytes } from 'node:crypto';
  * (`executor.ts`'s `callsHostnameFor`).
  */
 export const SYNAPSE_IMAGE = 'ghcr.io/element-hq/synapse';
-export const SYNAPSE_TAG = 'v1.161.0';
-export const MAS_IMAGE = 'ghcr.io/element-hq/matrix-authentication-service:1.24.0';
+export const SYNAPSE_TAG = VERSIONS.synapse;
+export const MAS_IMAGE = `ghcr.io/element-hq/matrix-authentication-service:${VERSIONS.mas}`;
+/** #251: the version baked into {@link MAS_IMAGE}'s `FROM` line, named on its own so a version-change line can read it without re-parsing the image string. */
+export const MAS_TAG = VERSIONS.mas;
 /**
  * Never resolved by DNS and never federates (`callsSynapseHomeserverYaml`'s
  * `federation_domain_whitelist: []`) -- purely a logical identifier MAS and

package/dist/plan/cloudflared-connector.d.ts

@@ -2,9 +2,10 @@ import type { CloudflarePort, CoolifyPort } from './executor.js';
 /**
  * #197: the pinned `cloudflared` image, the same release tag as
  * `scripts/shared-ingress.mjs`'s and `calls-sfu.ts`'s own
- * `CLOUDFLARED_IMAGE_REF`. A test in each keeps the three equal.
+ * `CLOUDFLARED_IMAGE_REF`. A test in each keeps the three equal. Pinned in
+ * `versions.json` (#247).
  */
-export declare const CLOUDFLARED_IMAGE_REF = "cloudflare/cloudflared:2026.9.3";
+export declare const CLOUDFLARED_IMAGE_REF: string;
 /**
  * The inline Dockerfile a docker-image `cloudflared` app needs, copied from
  * `scripts/shared-ingress.mjs`'s `cloudflaredDockerfile()`: the published

package/dist/plan/cloudflared-connector.js

@@ -1,10 +1,12 @@
+import { VERSIONS } from '../bootstrap/versions.js';
 import { isNotFoundError } from './executor.js';
 /**
  * #197: the pinned `cloudflared` image, the same release tag as
  * `scripts/shared-ingress.mjs`'s and `calls-sfu.ts`'s own
- * `CLOUDFLARED_IMAGE_REF`. A test in each keeps the three equal.
+ * `CLOUDFLARED_IMAGE_REF`. A test in each keeps the three equal. Pinned in
+ * `versions.json` (#247).
  */
-export const CLOUDFLARED_IMAGE_REF = 'cloudflare/cloudflared:2026.9.3';
+export const CLOUDFLARED_IMAGE_REF = `cloudflare/cloudflared:${VERSIONS.cloudflared}`;
 /**
  * The inline Dockerfile a docker-image `cloudflared` app needs, copied from
  * `scripts/shared-ingress.mjs`'s `cloudflaredDockerfile()`: the published
@@ -72,7 +74,7 @@ export async function ensureCloudflaredConnector(input) {
             environment_uuid: input.environment.uuid,
             dockerfile: cloudflaredDockerfile(),
             name: input.appName,
-            description: 'cloudflared connector for this platform tunnel (#197)',
+            description: 'cloudflared connector for a Cloudflare tunnel',
             instant_deploy: false,
         });
         appId = created.uuid;

package/dist/plan/diff.d.ts

@@ -1,5 +1,5 @@
 import type { DeclaredOrg, OrgId } from '../org.js';
-import type { Plan, PlanStep, UnmanagedItem } from '../plan.js';
+import type { Plan, PlanStep, UnmanagedItem, VersionChangeItem } from '../plan.js';
 import { type AgoraHostReading } from './agora.js';
 import type { LiveResource } from './live.js';
 import { type OrgPlatformReadiness } from './platform-org.js';
@@ -26,10 +26,21 @@ export interface PlannedStep {
     step: PlanStep;
     action: StepAction;
 }
+/**
+ * Facts about the host's executor ports that an org's plan needs, so a step
+ * whose port is not wired is reported blocked instead of planned (rule 2).
+ * New ones go here, not in new positional arguments (rule 7).
+ */
+export interface PlanOrgOptions {
+    /** #267: the executor was built with a `loginHostBindings` port. */
+    loginHostBindings?: boolean;
+}
 export interface PlanDetail {
     orgId: OrgId;
     plannedSteps: PlannedStep[];
     unmanaged: UnmanagedItem[];
+    /** #251: see `VersionChangeItem` (`../plan.ts`). Never folded into `plannedSteps`. */
+    versionChanges: VersionChangeItem[];
 }
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export declare function toPlan(detail: PlanDetail): Plan;
@@ -73,7 +84,11 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * 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
@@ -81,7 +96,7 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * Company Factory end to end", which wires real readers and executors
  * against this seam.
  */
-export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>, agoraHost?: AgoraHostReading, jobsAvailable?: boolean, platformReadiness?: OrgPlatformReadiness): PlanDetail;
+export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>, agoraHost?: AgoraHostReading, jobsAvailable?: boolean, platformReadiness?: OrgPlatformReadiness, options?: PlanOrgOptions): PlanDetail;
 /** Restated from `executor.ts`, the same rule: the id of an ai key minted but not delivered. */
 export declare 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. */

package/dist/plan/diff.js

@@ -1,6 +1,8 @@
-import { NO_AGORA_HOST_VALUES, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.js';
+import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
+import { NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.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 { ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, } from './platform-diff.js';
+import { APP_ENV_APPLIED_SCOPE_KEY, CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, DB_ENV_APPLIED_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, resolveAppEnv, versionNotAppliedLine, } 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) {
@@ -8,6 +10,7 @@ export function toPlan(detail) {
         orgId: detail.orgId,
         steps: detail.plannedSteps.map((p) => p.step),
         unmanaged: detail.unmanaged,
+        versionChanges: detail.versionChanges,
     };
 }
 function resourceKey(system, kind, key) {
@@ -53,7 +56,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
@@ -61,7 +68,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 = [];
@@ -71,9 +78,29 @@ 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);
@@ -90,6 +117,22 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const callsService = planCallsService(org, byKey, claimed, platformReadiness.callsReady);
     if (callsService.step)
         plannedSteps.push(callsService.step);
+    // #251: same mechanism as the platform's own version-change lines -- see
+    // `planPlatform`'s own block in `platform-diff.ts`. Synapse and MAS never
+    // patch a running app's image tag once created, so this is
+    // `versionNotAppliedLine`, the same honest wording zitadel's own line
+    // uses, never `versionChangeLine`'s "X -> Y (redeploy)" -- nothing here
+    // ever performs that redeploy.
+    const versionChanges = [];
+    if (org.calls.enabled && !calls.blocked) {
+        const callsAppLive = Boolean(byKey.get(resourceKey('coolify', 'calls', org.id)));
+        const synapseChange = versionNotAppliedLine('synapse', callsAppLive, recordedIds[CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY], VERSIONS.synapse);
+        if (synapseChange)
+            versionChanges.push(synapseChange);
+        const masChange = versionNotAppliedLine('mas', callsAppLive, recordedIds[CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY], VERSIONS.mas);
+        if (masChange)
+            versionChanges.push(masChange);
+    }
     const filesOrganisation = planFilesOrganisation(org, byKey, claimed, platformReadiness.filesReady, platformReadiness.missingKeys.files, platformReadiness.noKeyReader);
     if (filesOrganisation.step)
         plannedSteps.push(filesOrganisation.step);
@@ -135,21 +178,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);
@@ -199,6 +257,10 @@ 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
@@ -218,7 +280,14 @@ 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' });
-    return { orgId: org.id, plannedSteps, unmanaged };
+    // #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, versionChanges };
 }
 /**
  * The org's own ZITADEL org (issuer), a per-org singleton like every other
@@ -355,6 +424,92 @@ 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, and (#274) removes the *old* host
+ * from ZITADEL's trusted domains and zitadel-login's binding, reading it
+ * back from this same recorded value before overwriting it -- no separate
+ * action field or planning step of its own needed for that half. 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, 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):
+    // `zitadelLoginHost` always advances the recorded host to the current one,
+    // so a pending removal is the only way to know one is still owed, and
+    // nothing else here would replan the step to retry it.
+    if (recordedIds[key] === host &&
+        recordedIds[LOGIN_BINDING_SCOPE_KEY] ===
+            loginBindingState(host, loginHostClientIds(recordedIds)) &&
+        pendingRemovalHosts(recordedIds).length === 0) {
+        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`
@@ -364,6 +519,10 @@ function planOwner(org, recordedIds, authReady) {
 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';
+/** #236: restated from `executor.ts`, the same rule: the domain the org tunnel's DNS was last published under. */
+const CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY = 'cloudflare_tunnel_dns_domain';
 /** 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. */
@@ -546,6 +705,10 @@ function planMailCopy(org, byKey, recordedIds) {
     };
 }
 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)
@@ -620,6 +783,26 @@ function planCalls(org, byKey, claimed, callsReady) {
             blocked: `${org.slug}'s calls Matrix stack is blocked, not planned: the platform's shared calls SFU is off`,
         };
     }
+    // #248: the two images this stack's own apply would run, checked the same
+    // way the platform's SFU checks LiveKit/cloudflared and ZITADEL checks its
+    // own tag -- a re-apply of the same declaration must not silently run a
+    // different version with no diff shown anywhere.
+    if (org.calls.enabled && !byKey.get(key)) {
+        const synapseBlocked = floatingTagBlocked('Synapse', VERSIONS.synapse, 'v1.161.0');
+        if (synapseBlocked) {
+            return {
+                step: null,
+                blocked: `${org.slug}'s calls Matrix stack is blocked, not planned: ${synapseBlocked}`,
+            };
+        }
+        const masBlocked = floatingTagBlocked('matrix-authentication-service', VERSIONS.mas, '1.24.0');
+        if (masBlocked) {
+            return {
+                step: null,
+                blocked: `${org.slug}'s calls Matrix stack is blocked, not planned: ${masBlocked}`,
+            };
+        }
+    }
     return {
         step: planHostingToggle('coolify', 'calls', org.calls.enabled, org, byKey, claimed, () => `provision ${org.slug}'s calls Matrix stack (Synapse + matrix-authentication-service)`, () => `park ${org.slug}'s calls Matrix stack (stops serving; data is retained, not deleted -- #7 corrections 1)`),
         blocked: null,
@@ -1203,23 +1386,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
@@ -1327,12 +1590,61 @@ 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;
+    // A live, enabled tunnel re-plans the same step again when either:
+    // #235, no connector recorded -- a first connector create that failed, or
+    // a tunnel that predates connectors; or #236, its DNS was last published
+    // under a domain other than the one now declared -- never published at
+    // all (unset), or the org's domain has since changed. `org.domain` is set
+    // whenever `desired` is true above, in every branch. The step itself
+    // (`executor.ts`'s `cloudflareTunnel`) finds or creates the connector by
+    // name and upserts DNS idempotently (and, on a domain change, cleans up
+    // the old one once the new one is published -- round 3: publishing first
+    // means a conflict on the new domain leaves the old one still live rather
+    // than taking the org dark), so re-running it never duplicates either.
+    const live = byKey.get(resourceKey('cloudflare', 'tunnel', org.id));
+    if (!live)
+        return null;
+    const connectorMissing = !recordedIds[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY];
+    const dnsStale = recordedIds[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY] !== org.domain;
+    if (!connectorMissing && !dnsStale)
+        return null;
+    return {
+        action: { system: 'cloudflare', kind: 'tunnel', key: org.id, desired: { enabled: true } },
+        step: {
+            description: connectorMissing
+                ? `run a cloudflared connector for ${org.slug}'s Cloudflare tunnel`
+                : `point ${org.slug}'s hostnames at its 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
@@ -1364,25 +1676,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,
     };
 }
 /**