@wtfalch/foundry 0.18.0 → 0.19.1

package/dist/bootstrap/declare.d.ts

@@ -37,8 +37,17 @@ export interface BootstrapOwner {
  */
 export declare function ownerIdentity(owner: BootstrapOwner): OwnerIdentity;
 /**
- * Company Included's declared org: the platform's owner, running no app or
- * mail of its own. Chat is on, like every org's.
+ * Company Included's declared org: the platform's owner, tier 3 on the
+ * platform's own apex from the start (#512) -- it runs on that domain with
+ * hosted mail, not a level-1 org whose domain gets set by hand afterward.
+ * `issuer`/`calls`/`site` go on the domain too, the same tier-3 defaults
+ * archon#388 gives every company declared there. `calls` and `site` stay
+ * disabled (calls is not in v1; no site is declared), so `usesDomain` is
+ * inert on both until one is switched on. Chat stays off the domain: its
+ * re-key onto a per-org homeserver is not built yet (#463). The org's own
+ * sign-in still never collides with the shared ZITADEL instance's host --
+ * `loginHostnameFor` (#488) falls back to `<slug>-auth.oikos.host` whenever
+ * `auth.<domain>` would equal the platform's own auth hostname.
  */
 export declare function declaredCompanyOrg(company: BootstrapCompany, owner: BootstrapOwner): DeclaredOrg;
 /**

package/dist/bootstrap/declare.js

@@ -55,25 +55,34 @@ export function ownerIdentity(owner) {
     return identity;
 }
 /**
- * Company Included's declared org: the platform's owner, running no app or
- * mail of its own. Chat is on, like every org's.
+ * Company Included's declared org: the platform's owner, tier 3 on the
+ * platform's own apex from the start (#512) -- it runs on that domain with
+ * hosted mail, not a level-1 org whose domain gets set by hand afterward.
+ * `issuer`/`calls`/`site` go on the domain too, the same tier-3 defaults
+ * archon#388 gives every company declared there. `calls` and `site` stay
+ * disabled (calls is not in v1; no site is declared), so `usesDomain` is
+ * inert on both until one is switched on. Chat stays off the domain: its
+ * re-key onto a per-org homeserver is not built yet (#463). The org's own
+ * sign-in still never collides with the shared ZITADEL instance's host --
+ * `loginHostnameFor` (#488) falls back to `<slug>-auth.oikos.host` whenever
+ * `auth.<domain>` would equal the platform's own auth hostname.
  */
 export function declaredCompanyOrg(company, owner) {
     return {
         id: COMPANY_INCLUDED_ORG_ID,
         slug: company.slug,
         displayName: company.name,
-        domain: null,
+        domain: company.apex,
         mail: {
-            mode: 'off',
-            usesDomain: false,
+            mode: 'hosted',
+            usesDomain: true,
             ownerMailboxAddress: null,
             noReplyLocalPart: 'no-reply',
         },
         chat: { enabled: true, usesDomain: false },
-        calls: { enabled: false, usesDomain: false },
-        issuer: { usesDomain: false },
-        site: { enabled: false, usesDomain: false },
+        calls: { enabled: false, usesDomain: true },
+        issuer: { usesDomain: true },
+        site: { enabled: false, usesDomain: true },
         hosting: {
             enabled: false,
             usesDomain: false,

package/dist/index.d.ts

@@ -28,6 +28,8 @@ export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, LoginHostBinding, LoginHostBindingsPort, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
+export type { ScopeResolver, RecordedIds } from './plan/index.js';
+export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
 export type { ZitadelListAppsRawApp } from './plan/index.js';
 export { adaptZitadelListApps } from './plan/index.js';
 export type { MailIdentityApp, MailIdentityAudienceCheck } from './plan/index.js';

package/dist/index.js

@@ -17,6 +17,7 @@ export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesF
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
+export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
 export { adaptZitadelListApps } from './plan/index.js';
 export { checkMailIdentityAudience } from './plan/index.js';
 export { checkMailAppsAllowlist } from './plan/index.js';

package/dist/plan/agora.d.ts

@@ -110,6 +110,18 @@ export declare function agoraHostMissing(host: AgoraHostValues): string[];
 export declare function agoraHostnameFor(org: DeclaredOrg): string;
 /** The port `calls/packages/service/Dockerfile` documents (`EXPOSE 8080`); `config.mjs`'s `PORT` has no default, so the executor pushes it. */
 export declare const CALLS_SERVICE_PORT = "8080";
+/**
+ * The port `wtfalch/agora`'s `apps/agora/Dockerfile` serves Caddy on
+ * (`EXPOSE 8080`). Coolify's github-app build never reads a Dockerfile's
+ * `EXPOSE` on its own, so without this passed as `ports_exposes` Traefik is
+ * left routing to a port nothing listens on and Agora answers 502 behind the
+ * tunnel (#506, seen live on Company Included, 2026-10-05). `executor.ts`'s
+ * `coolifyAgora` sets it at create time and fixes it on a found app whose
+ * live value differs; `diff.ts`'s `planAgora` plans that fix the same way it
+ * plans an env difference, by comparing this constant against the live
+ * app's own `ports_exposes` (`providers-readers.ts`'s `withAgoraPortConfig`).
+ */
+export declare const AGORA_APP_PORTS_EXPOSES = "8080";
 /**
  * Recorded by the executor once the calls service app carries its fixed
  * internal name (`callsServiceInternalName`). `desiredAgoraEnv` waits for it,
@@ -139,6 +151,17 @@ export declare const CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY = "coolify_calls_service_
  */
 export declare const CALLS_INTROSPECTION_SCOPE_KEY = "zitadel_calls_introspection_app";
 export declare const CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY = "zitadel_calls_introspection_undelivered";
+/**
+ * The introspection API app minted for the org's chat service (once), in the
+ * messaging project, and the undelivered key recorded before its secret
+ * leaves the executor (platform rule 1). The first doubles as the marker
+ * `planChat` reads: recorded after the service's env carries the client. No
+ * `:` in either.
+ */
+export declare const CHAT_INTROSPECTION_SCOPE_KEY = "zitadel_chat_introspection_app";
+export declare const CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY = "zitadel_chat_introspection_undelivered";
+/** The chat service's introspection API app name; one per org, exact match only. */
+export declare function chatIntrospectionAppName(org: DeclaredOrg): string;
 /** What the plan hands the calls service step: the two host values the token env needs. */
 export interface CallsTokenHost {
     issuer: string;
@@ -196,6 +219,19 @@ export declare function agoraEnvDrift(desired: Readonly<Record<string, string>>,
  * against (#442's own probe: "one env write, zero restarts, zero deploys").
  */
 export declare const AGORA_ACTIVATED_ENV_SCOPE_KEY = "coolify_agora_activated_env";
+/**
+ * #504: recorded once `coolifyAgora` has actually called `deploy` on this
+ * org's Agora app -- `createGithubAppApplication` never sets
+ * `instant_deploy`, and Coolify defaults it to false, so a freshly created
+ * app (or one found by name that a previous apply created but crashed
+ * before deploying) sat at `exited:unhealthy` with zero deployments
+ * forever: nothing ever deployed it, and `restart` cannot start a container
+ * that was never built. Absent means "never deployed", regardless of
+ * whether the app is found live this run or created fresh -- unlike
+ * {@link AGORA_ACTIVATED_ENV_SCOPE_KEY}, this never changes value once set,
+ * so a later env change restarts rather than deploys again.
+ */
+export declare const AGORA_DEPLOYED_SCOPE_KEY = "coolify_agora_deployed";
 /**
  * A stable digest of `env`, for comparison against what was last recorded
  * under {@link AGORA_ACTIVATED_ENV_SCOPE_KEY}. `AGORA_CONFIG` is compared by

package/dist/plan/agora.js

@@ -118,6 +118,18 @@ export function agoraHostnameFor(org) {
 }
 /** The port `calls/packages/service/Dockerfile` documents (`EXPOSE 8080`); `config.mjs`'s `PORT` has no default, so the executor pushes it. */
 export const CALLS_SERVICE_PORT = '8080';
+/**
+ * The port `wtfalch/agora`'s `apps/agora/Dockerfile` serves Caddy on
+ * (`EXPOSE 8080`). Coolify's github-app build never reads a Dockerfile's
+ * `EXPOSE` on its own, so without this passed as `ports_exposes` Traefik is
+ * left routing to a port nothing listens on and Agora answers 502 behind the
+ * tunnel (#506, seen live on Company Included, 2026-10-05). `executor.ts`'s
+ * `coolifyAgora` sets it at create time and fixes it on a found app whose
+ * live value differs; `diff.ts`'s `planAgora` plans that fix the same way it
+ * plans an env difference, by comparing this constant against the live
+ * app's own `ports_exposes` (`providers-readers.ts`'s `withAgoraPortConfig`).
+ */
+export const AGORA_APP_PORTS_EXPOSES = '8080';
 /**
  * Recorded by the executor once the calls service app carries its fixed
  * internal name (`callsServiceInternalName`). `desiredAgoraEnv` waits for it,
@@ -151,6 +163,19 @@ export const CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY = 'coolify_calls_service_token_en
  */
 export const CALLS_INTROSPECTION_SCOPE_KEY = 'zitadel_calls_introspection_app';
 export const CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY = 'zitadel_calls_introspection_undelivered';
+/**
+ * The introspection API app minted for the org's chat service (once), in the
+ * messaging project, and the undelivered key recorded before its secret
+ * leaves the executor (platform rule 1). The first doubles as the marker
+ * `planChat` reads: recorded after the service's env carries the client. No
+ * `:` in either.
+ */
+export const CHAT_INTROSPECTION_SCOPE_KEY = 'zitadel_chat_introspection_app';
+export const CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY = 'zitadel_chat_introspection_undelivered';
+/** The chat service's introspection API app name; one per org, exact match only. */
+export function chatIntrospectionAppName(org) {
+    return `chat-introspection-${org.slug}`;
+}
 /**
  * The token env's inputs, or null while any is missing: the host's issuer and
  * messaging project id (`AgoraHostValues`) and the org's recorded ZITADEL org
@@ -305,6 +330,19 @@ export function agoraEnvDrift(desired, live) {
  * against (#442's own probe: "one env write, zero restarts, zero deploys").
  */
 export const AGORA_ACTIVATED_ENV_SCOPE_KEY = 'coolify_agora_activated_env';
+/**
+ * #504: recorded once `coolifyAgora` has actually called `deploy` on this
+ * org's Agora app -- `createGithubAppApplication` never sets
+ * `instant_deploy`, and Coolify defaults it to false, so a freshly created
+ * app (or one found by name that a previous apply created but crashed
+ * before deploying) sat at `exited:unhealthy` with zero deployments
+ * forever: nothing ever deployed it, and `restart` cannot start a container
+ * that was never built. Absent means "never deployed", regardless of
+ * whether the app is found live this run or created fresh -- unlike
+ * {@link AGORA_ACTIVATED_ENV_SCOPE_KEY}, this never changes value once set,
+ * so a later env change restarts rather than deploys again.
+ */
+export const AGORA_DEPLOYED_SCOPE_KEY = 'coolify_agora_deployed';
 /**
  * A stable digest of `env`, for comparison against what was last recorded
  * under {@link AGORA_ACTIVATED_ENV_SCOPE_KEY}. `AGORA_CONFIG` is compared by

package/dist/plan/boule.d.ts

@@ -20,6 +20,14 @@ export declare const BOULE_CLIENT_ID_SCOPE_KEY = "boule_client_id";
  * scope id, like the cms and calls databases.
  */
 export declare const BOULE_DATABASE_SCOPE_KEY = "coolify_boule_database";
+/**
+ * #504: the same marker `agora.ts`'s `AGORA_DEPLOYED_SCOPE_KEY` is, for
+ * Boule -- recorded once `coolifyBoule` has actually called `deploy` on this
+ * org's Boule app. See that constant's own doc comment for why: Coolify
+ * defaults `instant_deploy` to false, so without this a freshly created app
+ * sat built but never started, and `restart` cannot fix that.
+ */
+export declare const BOULE_DEPLOYED_SCOPE_KEY = "coolify_boule_deployed";
 /**
  * `boule.<domain>` when the org has a domain, `<slug>-boule.oikos.host`
  * otherwise (the tier rule of boule#128 and foundry#147; `../slug.ts`'s

package/dist/plan/boule.js

@@ -19,6 +19,14 @@ export const BOULE_CLIENT_ID_SCOPE_KEY = 'boule_client_id';
  * scope id, like the cms and calls databases.
  */
 export const BOULE_DATABASE_SCOPE_KEY = 'coolify_boule_database';
+/**
+ * #504: the same marker `agora.ts`'s `AGORA_DEPLOYED_SCOPE_KEY` is, for
+ * Boule -- recorded once `coolifyBoule` has actually called `deploy` on this
+ * org's Boule app. See that constant's own doc comment for why: Coolify
+ * defaults `instant_deploy` to false, so without this a freshly created app
+ * sat built but never started, and `restart` cannot fix that.
+ */
+export const BOULE_DEPLOYED_SCOPE_KEY = 'coolify_boule_deployed';
 /**
  * `boule.<domain>` when the org has a domain, `<slug>-boule.oikos.host`
  * otherwise (the tier rule of boule#128 and foundry#147; `../slug.ts`'s

package/dist/plan/chat-matrix.d.ts

@@ -90,6 +90,9 @@ export interface ChatServiceEnvInput {
     agoraHost: string;
     masClientId: string;
     masClientSecret: string;
+    /** The ZITADEL API app the service introspects Agora's opaque tokens as. */
+    introspectionClientId: string;
+    introspectionClientSecret: string;
 }
 /** Every variable `chat/apps/chat-service/src/config.ts` requires, plus the internal Synapse address and port. */
 export declare function chatServiceEnvs(input: ChatServiceEnvInput): Array<{

package/dist/plan/chat-matrix.js

@@ -195,6 +195,8 @@ export function chatServiceEnvs(input) {
         { key: 'MAS_URL', value: upstreams.mas },
         { key: 'MAS_CLIENT_ID', value: input.masClientId },
         { key: 'MAS_CLIENT_SECRET', value: input.masClientSecret },
+        { key: 'CHAT_INTROSPECTION_CLIENT_ID', value: input.introspectionClientId },
+        { key: 'CHAT_INTROSPECTION_CLIENT_SECRET', value: input.introspectionClientSecret },
         // DATABASE_URL_OWNER/DATABASE_URL are pushed by executor.ts's
         // pushDatabaseUrl instead, not here (the same split coolifyApp and
         // cmsSite follow, #239) -- that call mints a distinct <dbName>_rt

package/dist/plan/diff.js

@@ -1,6 +1,6 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.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 { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
 import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
@@ -82,7 +82,11 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
     const claimed = new Set();
     const plannedSteps = [];
-    const issuer = planIssuer(org, byKey, claimed, platformReadiness.authReady);
+    // The platform's own org: its domain is the platform apex (the same fact
+    // #491 reads for mail). It signs in on the shared instance's own host, so
+    // `issuer.usesDomain` never moves it.
+    const isPlatformOrg = isPlatformOwnOrg(org, platformReadiness.platformApex);
+    const issuer = planIssuer(org, byKey, claimed, platformReadiness.authReady, isPlatformOrg);
     if (issuer.step)
         plannedSteps.push(issuer.step);
     plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady, 'error' in agoraHost ? null : agoraHost.issuer));
@@ -94,7 +98,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // 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));
+    platformAuthHostnameFrom('error' in agoraHost ? null : agoraHost.issuer), isPlatformOrg);
     if (loginHost.step)
         plannedSteps.push(loginHost.step);
     // Planned ahead of everything that needs the zone live (#238); its own step
@@ -391,7 +395,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
  * already exists live is unaffected: its own domain-move logic runs
  * regardless, since that never re-provisions the ZITADEL org itself.
  */
-function planIssuer(org, byKey, claimed, authReady) {
+function planIssuer(org, byKey, claimed, authReady, isPlatformOrg = false) {
     const key = resourceKey('zitadel', 'issuer', org.id);
     const live = byKey.get(key);
     const desiredUsesDomain = org.issuer.usesDomain;
@@ -420,9 +424,14 @@ function planIssuer(org, byKey, claimed, authReady) {
         };
     }
     claimed.add(key);
-    const liveUsesDomain = Boolean(live.config.usesDomain);
-    if (liveUsesDomain === desiredUsesDomain)
+    // The platform's own org already signs in on the shared host: no move. A
+    // live issuer that does not say (the reader never does: foundry v1 never
+    // moves one) is not read as a different one either.
+    if (isPlatformOrg ||
+        live.config.usesDomain === undefined ||
+        Boolean(live.config.usesDomain) === desiredUsesDomain) {
         return { step: null, blocked: null };
+    }
     const domain = org.domain ?? 'the org domain';
     return {
         step: {
@@ -519,6 +528,9 @@ function planOwners(org, recordedIds, authReady, authIssuer) {
  * computed `auth.<domain>` against, so the platform's own org never plans
  * its login host equal to the shared ZITADEL instance's own.
  */
+function isPlatformOwnOrg(org, platformApex) {
+    return Boolean(org.domain && platformApex && org.domain.toLowerCase() === platformApex.toLowerCase());
+}
 function platformAuthHostnameFrom(issuer) {
     if (!issuer)
         return null;
@@ -565,16 +577,58 @@ function platformAuthHostnameFrom(issuer) {
  * 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, platformAuthHostname) {
+function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired, platformAuthHostname, isPlatformOrg) {
     const none = { step: null, blocked: null };
     const key = resourceKey('zitadel', 'login-host', org.id);
-    const host = loginHostnameFor(org, platformAuthHostname);
+    // The platform's own org signs in on the shared instance's host whatever
+    // `issuer.usesDomain` says (turning it on would move the issuer).
+    // Before that host is known, plan nothing: a guessed host would delete the
+    // working one, and a normal step would trust a domain `destroy` later deletes.
+    if (isPlatformOrg && platformAuthHostname === null) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s login host is waiting for the platform auth host`,
+        };
+    }
+    const sharedInstanceHost = isPlatformOrg && platformAuthHostname !== null;
+    const host = sharedInstanceHost ? platformAuthHostname : loginHostnameFor(org);
     // #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}`;
+    if (sharedInstanceHost) {
+        // The host is the shared instance's own: nothing to trust or bind, and an
+        // org with no recorded host already signs in there. Only an org recorded
+        // on another host (the old `<slug>-auth.oikos.host`) plans one step, to
+        // move its apps over and remove the old host; then it plans nothing.
+        const recordedHost = recordedIds[key];
+        const moving = recordedHost !== undefined && recordedHost !== host;
+        const removalOwed = pendingRemovalHosts(recordedIds).length > 0;
+        if (!authReady || !(moving || removalOwed))
+            return none;
+        // The same gates as the normal branch: the executor's shared step also
+        // needs the binding port and the ZITADEL org.
+        const waiting = loginHostWaiting(org, host, recordedIds, bindingsWired, issuerPlanned);
+        return waiting ?? stepFor(true);
+    }
+    function stepFor(shared) {
+        return {
+            step: {
+                action: {
+                    system: 'zitadel',
+                    kind: 'login-host',
+                    key: org.id,
+                    desired: shared ? { host, shared: true } : { host },
+                },
+                step: {
+                    description: shared
+                        ? `move ${org.slug}'s apps onto the platform's own sign-in host ${host}`
+                        : `set ${org.slug}'s login host to ${host}`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+        };
+    }
     // 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):
@@ -595,6 +649,10 @@ function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired
     // 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.
+    return loginHostWaiting(org, host, recordedIds, bindingsWired, issuerPlanned) ?? stepFor(false);
+}
+/** Why a login-host step cannot run yet, or `null` when nothing is missing. */
+function loginHostWaiting(org, host, recordedIds, bindingsWired, issuerPlanned) {
     if (!bindingsWired) {
         return {
             step: null,
@@ -609,24 +667,7 @@ function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired
             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: 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,
-            },
-        },
-        blocked: null,
-    };
+    return null;
 }
 /** #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';
@@ -923,6 +964,27 @@ function planChat(org, byKey, claimed, recordedIds, reading, issuerPlanned) {
                 blocked: null,
             };
         }
+        // A live chat made before its service had an introspection client
+        // answers every Agora sign-in with `token_invalid`. The marker is the
+        // client's app id, recorded after the service's env carries it.
+        if (!recordedIds[CHAT_INTROSPECTION_SCOPE_KEY]) {
+            return {
+                step: {
+                    action: {
+                        system: 'coolify',
+                        kind: 'chat',
+                        key: org.id,
+                        desired: { usesDomain: liveUsesDomain, refreshIntrospection: true },
+                    },
+                    step: {
+                        description: `give ${org.slug}'s chat service its token introspection client and redeploy it`,
+                        destroys: false,
+                        migrates: false,
+                    },
+                },
+                blocked: null,
+            };
+        }
         return none;
     }
     const domain = org.domain ?? 'its domain';
@@ -1594,6 +1656,13 @@ function planAgora(org, byKey, claimed, recordedIds, reading) {
     if (liveEnv.AGORA_CONFIG === undefined && !drift.includes('AGORA_CONFIG')) {
         drift.push('AGORA_CONFIG');
     }
+    // #506: an app Coolify never got `ports_exposes` on (or got the wrong one)
+    // answers 502 behind the tunnel even though its env already matches --
+    // exactly the Company Included incident this issue names. Compared
+    // separately from `drift` above: it is a Coolify application setting, not
+    // an env var, and `providers-readers.ts`'s `withAgoraEnvConfig` reads it
+    // from `getApplication`, never `listEnvs`.
+    const portDrift = live.config.ports_exposes !== AGORA_APP_PORTS_EXPOSES;
     // #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.
@@ -1604,14 +1673,18 @@ function planAgora(org, byKey, claimed, recordedIds, reading) {
     // 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)
+    if (drift.length === 0 && activated && !portDrift)
         return { step: null, blocked: null };
+    const reasons = [
+        ...(drift.length > 0 ? [`${drift.join(', ')} missing or different`] : []),
+        ...(portDrift ? ["ports_exposes wrong -- Traefik can't reach it"] : []),
+    ];
     return {
         step: {
             action,
             step: {
-                description: drift.length > 0
-                    ? `update ${org.slug}'s Agora config (${drift.join(', ')} missing or different)`
+                description: reasons.length > 0
+                    ? `update ${org.slug}'s Agora config (${reasons.join('; ')})`
                     : `activate ${org.slug}'s Agora config -- written but not yet confirmed restarted`,
                 destroys: false,
                 migrates: false,
@@ -1735,13 +1808,13 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
  * park-not-delete rule (#7 corrections 1) -- turning it off never deletes
  * the org's own app, database or tunnel configuration, it parks it.
  */
-function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, describeProvision, describePark, stepKey = org.id) {
+function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, describeProvision, describePark, stepKey = org.id, isOn = (live) => live.config.enabled !== false) {
     const key = resourceKey(system, kind, stepKey);
     const live = byKey.get(key);
     // A live resource is on unless it says it is parked. Providers' own
     // configs carry no `enabled` field at all, so only a park step's
     // explicit `enabled: false` reads as off.
-    const liveEnabled = live !== undefined && live.config.enabled !== false;
+    const liveEnabled = live !== undefined && isOn(live);
     if (!desiredEnabled) {
         // Nothing declared and nothing live: there is nothing to park.
         if (!live)
@@ -2192,7 +2265,18 @@ function planTunnel(org, byKey, claimed, recordedIds) {
         (org.site.enabled && Boolean(org.domain)) ||
         (org.calls.enabled && org.calls.usesDomain && Boolean(org.domain)) ||
         Boolean(org.domain);
-    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)`);
+    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)`, org.id, 
+    // Cloudflare's status, read against what is declared: a park cannot change
+    // it, so judging on/off by status alone would never let the plan empty.
+    // Wanted on: only `down` needs a repair (`inactive` is a fresh tunnel
+    // whose connector has not dialled in yet). Wanted off: only a connected
+    // tunnel needs parking; `inactive` and `down` are already parked.
+    (live) => {
+        const status = live.config.status;
+        if (typeof status !== 'string')
+            return live.config.enabled !== false;
+        return desired ? status !== 'down' : status === 'healthy' || status === 'degraded';
+    });
     if (toggled || !desired)
         return toggled;
     // A live, enabled tunnel re-plans the same step again when either:

package/dist/plan/executor.d.ts

@@ -89,6 +89,10 @@ export interface CoolifyPort {
      * `settings`, not at the top level -- confirmed against live Coolify
      * 4.3.23 (PR #482 review); `custom_network_aliases` and
      * `health_check_enabled` are both top-level there.
+     *
+     * #506: also the port Traefik routes to, so `coolifyAgora` can tell an app
+     * that predates passing `ports_exposes` at create apart from one already
+     * fixed.
      */
     getApplication(uuid: string): Promise<{
         uuid: string;
@@ -99,6 +103,7 @@ export interface CoolifyPort {
         };
         custom_network_aliases?: string | null;
         health_check_enabled?: boolean;
+        ports_exposes?: string;
     }>;
     createGithubAppApplication(input: {
         project_uuid: string;
@@ -1410,6 +1415,8 @@ export interface PlatformOrgPortSource {
     files(): Promise<FilesOrganisationPort>;
     ai(): Promise<AiOrganisationPort>;
     jobs(): Promise<JobsSchedulerPort>;
+    /** The platform's shared sign-in host, or `null` when none is declared. */
+    authHostname?(): Promise<string | null>;
 }
 export interface FoundryStepExecutorPorts {
     coolify: CoolifyPort;
@@ -2221,6 +2228,18 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * so an existing one is always re-written.
      */
     private ensureCallsFileStorage;
+    /**
+     * The chat service's introspection client: an API app in the org's
+     * messaging project (the audience Agora's token carries), so ZITADEL's
+     * introspection accepts it. The chat service authenticates as it with
+     * `client_secret_basic`. Minted once, the way {@link callsTokenEnvs} does:
+     * the id is recorded under an undelivered key and persisted before the
+     * secret leaves, the secret goes to `deliverSecret` and to the caller's env
+     * write, never to a log, error or return beyond that. A re-run reads the id
+     * and secret back from the service's own env and mints nothing. `changed`
+     * is true only for a fresh mint.
+     */
+    private ensureChatIntrospection;
     /**
      * Creates the `chat.admin` role on the org's messaging project and grants
      * it to each owner whose invite is recorded (`zitadel:owner:<orgId>:<email>`,
@@ -2331,11 +2350,25 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * actually differs, or whenever the last restart this step confirmed
      * ({@link AGORA_ACTIVATED_ENV_SCOPE_KEY}) is not this exact env (an org
      * applied before this existed, whose live env already matched desired
-     * with nothing ever confirmed running it). A brand new app has nothing
-     * running yet to restart. The activation marker is recorded last, after
-     * the restart (if any) returns without throwing, so a failed restart
-     * leaves it stale and the next plan replans this step even though
-     * Coolify's own env store already matches desired.
+     * with nothing ever confirmed running it). The activation marker is
+     * recorded last, after the restart (if any) returns without throwing, so a
+     * failed restart leaves it stale and the next plan replans this step even
+     * though Coolify's own env store already matches desired.
+     *
+     * #504: a brand new app is never restarted -- but it is deployed, once
+     * ({@link AGORA_DEPLOYED_SCOPE_KEY}). `createGithubAppApplication` never
+     * sets `instant_deploy`, and Coolify defaults it to false, so without an
+     * explicit deploy the app sat created but never built or started.
+     *
+     * #506: `ports_exposes: AGORA_APP_PORTS_EXPOSES` goes on the create call
+     * itself, so Traefik has a port to route to from the moment the app
+     * exists. An app `findOrCreateCallsApp` instead *found* may predate this
+     * fix and carry no `ports_exposes` at all (or the wrong one), so its live
+     * value is read and, when it differs, patched -- and, since the container
+     * listens on `ports_exposes` only at its next deploy (the same rule
+     * `coolifyApp`'s own `settingsNeedDeploy` follows for a port change
+     * there), redeployed even on a run that already has its one #504 deploy
+     * behind it.
      */
     private coolifyAgora;
     /**
@@ -2360,6 +2393,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      *
      * `AUTH_APP_KEY` is minted once here; its broker entry is the next step
      * (`bouleBrokerEntry`).
+     *
+     * #504: a brand new app is never restarted -- but it is deployed, once
+     * ({@link BOULE_DEPLOYED_SCOPE_KEY}), the same reason and the same marker
+     * shape {@link coolifyAgora}'s own doc comment explains.
      */
     private coolifyBoule;
     /**
@@ -2501,6 +2538,15 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * shared-hostname collision this ticket exists to refuse. An org re-running
      * its own already-recorded zone is unaffected: the store then names this
      * same org as the owner.
+     *
+     * #510: also records the zone's own id under the flat `cloudflare_zone`
+     * scope key, alongside the `cloudflare:zone:<domain>` resource id `runSteps`
+     * already records from this method's return value. Without it, nothing
+     * ever gives `ProvidersCloudflareReader` a zone id to resolve this org's
+     * scope with (`providers-readers.ts`'s `storeScopeResolver` doc comment),
+     * so that reader's `listResources` always returned `[]` and `diff.ts`'s
+     * `planZone` re-proposed "provision a Cloudflare zone" on every apply, even
+     * once the zone was live.
      */
     private cloudflareZone;
     /**