@wtfalch/foundry 0.33.1 → 0.35.1

package/dist/plan/platform-diff.js

@@ -2,9 +2,12 @@ import { createHash } from 'node:crypto';
 import { VERSIONS } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY } from '../org.js';
 import { VERSION_CHANGE_KIND, } from '../plan.js';
+import { buildDriftNotes } from './build-record.js';
 import { versionChangeNeedsConfirmation } from './confirm-upgrade.js';
 import { ACCESS_PROVIDER_RECORD_KEY } from './gates.js';
 import { legacyAppHostname } from './hostnames.js';
+import { PLATFORM_MAIL_RELAY_KEY, planMailRelay } from './mail-relay.js';
+import { planOikosIngress } from './oikos-ingress.js';
 import { callsSfuAppliedFingerprint } from './platform-sfu.js';
 import { ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY, signInDomainBlockedText } from './sign-in-org.js';
 import { withStepSystem } from './step-system.js';
@@ -218,15 +221,16 @@ export const PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY = 'archon_applied_auth_o
  */
 export const PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY = 'archon_applied_rolling_update';
 /**
- * The sign-in org Archon accepts: the platform owner company's own
- * ({@link PLATFORM_OWNER_ORG_SCOPE_KEY}), else the platform's `foundry` org for
- * a platform with no owner company declared. Undefined when neither is recorded.
+ * The owner company's sign-in hostname Archon was last registered under, and
+ * the owner's files host (`<internalUrl>|<audience>`, or `none`) its env was
+ * last written with. `planArchon` plans the step again when either differs
+ * from the owner's current ones (a marker never recorded reads as `none`).
  */
-export function archonAuthOrganizationId(recorded) {
-    const owner = recorded[PLATFORM_OWNER_ORG_SCOPE_KEY];
-    if (owner && owner !== 'none')
-        return owner;
-    return recorded[PLATFORM_ZITADEL_ORG_SCOPE_KEY] || undefined;
+export const PLATFORM_ARCHON_APPLIED_AUTH_HOSTNAME_SCOPE_KEY = 'archon_applied_auth_hostname';
+export const PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY = 'archon_applied_files';
+/** The value {@link PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY} records for the owner's files host. */
+export function archonFilesMarker(files) {
+    return files ? `${files.internalUrl}|${files.audience}` : 'none';
 }
 /**
  * #175: set to '1' before the step points the tunnel at `http_status:404`
@@ -482,6 +486,26 @@ export const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = 'mail_applied_git_ref';
  * no key and creates nothing in the sign-in server.
  */
 export const PLATFORM_MAIL_ROUTE_SCOPE_KEY = 'mail_route_applied';
+/**
+ * The host ports the platform Stalwart publishes, as the mapping string the
+ * last apply set on its app. Without the shared relay it binds SMTP port 25
+ * itself; with `mail.relay` it keeps only submission, because the relay owns
+ * port 25. A missing record means the mapping it was created with, `25:25,...`.
+ */
+export const PLATFORM_MAIL_HOST_PORTS_SCOPE_KEY = 'mail_host_ports_applied';
+export const PLATFORM_MAIL_HOST_PORTS_DIRECT = '25:25,465:465,587:587';
+export const PLATFORM_MAIL_HOST_PORTS_RELAY = '465:465,587:587';
+export function platformMailHostPorts(platform) {
+    return platform.mail.relay === true
+        ? PLATFORM_MAIL_HOST_PORTS_RELAY
+        : PLATFORM_MAIL_HOST_PORTS_DIRECT;
+}
+function mailPortsApplied(platform, recordedIds) {
+    return ((recordedIds[PLATFORM_MAIL_HOST_PORTS_SCOPE_KEY] ?? PLATFORM_MAIL_HOST_PORTS_DIRECT) ===
+        platformMailHostPorts(platform));
+}
+export { PLATFORM_MAIL_RELAY_KEY };
+export { PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, } from './mail-relay.js';
 export const PLATFORM_MAIL_ROUTE_WANTED = 'local-first';
 /**
  * #177: where the mail server answers on the Coolify network
@@ -588,8 +612,78 @@ export function serviceDbEnvAppliedScopeKey(service) {
 export function zitadelAppIdTokenUserinfoAppliedScopeKey(appKey) {
     return `zitadel_app_id_token_userinfo_applied.${appKey}`;
 }
-/** The ZITADEL app id of Archon's sign-in client in the platform's own ZITADEL. */
+/**
+ * Archon's own sign-in organisation, in the owner company's ZITADEL instance
+ * and apart from the organisation that holds the company's people (and Boule's
+ * sign-in). Made by the `zitadel:archon-org` step, which runs before
+ * `platform:archon`. The first six keys below are the step's own progress:
+ * each is recorded only after its call succeeded.
+ */
+export const PLATFORM_ARCHON_ORG_SCOPE_KEY = 'zitadel_platform_archon_org';
+/** The primary domain registered on Archon's sign-in organisation. */
+export const PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY = 'zitadel_platform_archon_org_domain';
+/** The domain the sign-in server refused to make primary; set instead of failing, reported as blocked. */
+export const PLATFORM_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY = 'zitadel_platform_archon_org_domain_blocked';
+/** The Archon org id once self-registration is closed on it. */
+export const PLATFORM_ARCHON_ORG_REGISTRATION_CLOSED_SCOPE_KEY = 'zitadel_platform_archon_org_registration_closed';
+/** The Archon org id once its login policy forces a second factor. */
+export const PLATFORM_ARCHON_ORG_POLICY_SCOPE_KEY = 'zitadel_platform_archon_org_policy';
+/** The first person's user id in the Archon org (`none` when no owner is declared), recorded once the invite was mailed. */
+export const PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY = 'zitadel_platform_archon_owner_invite';
+/** The Archon org the recorded invite was made in. */
+export const PLATFORM_ARCHON_OWNER_INVITE_ORG_SCOPE_KEY = 'zitadel_platform_archon_owner_invite_org';
+/** The name of the Archon sign-in organisation: `<owner slug>-archon`. */
+export function archonOrgName(ownerSlug) {
+    return `${ownerSlug}-archon`;
+}
+/** The primary domain of the Archon sign-in organisation: `archon.` before the owner's own sign-in domain. */
+export function archonOrgDomain(ownerSignInDomain) {
+    return `archon.${ownerSignInDomain}`;
+}
+/**
+ * The CI organisation id the last Archon apply wrote as `CI_ORGANIZATION_ID`,
+ * and the `ARCHON_FIRST_OWNER_LINK` value it wrote (empty when none).
+ * `planArchon` plans the step again when either differs from what is wanted.
+ */
+export const PLATFORM_ARCHON_APPLIED_CI_ORG_SCOPE_KEY = 'archon_applied_ci_org';
+export const PLATFORM_ARCHON_APPLIED_FIRST_OWNER_LINK_SCOPE_KEY = 'archon_applied_first_owner_link';
+/**
+ * `<archonUserId>:<ciUserId>`: the first person in both organisations, which
+ * Archon seeds its link table from. Empty when either id is not known (no
+ * owner declared, or the CI-side account not recorded yet).
+ */
+export function archonFirstOwnerLink(recordedIds, ownerSignIn) {
+    const archonUserId = recordedIds[PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY];
+    const ciUserId = ownerSignIn?.firstOwnerUserId;
+    if (!archonUserId || archonUserId === 'none' || !ciUserId || ciUserId === 'none')
+        return '';
+    return `${archonUserId}:${ciUserId}`;
+}
+/**
+ * The one-time-PIN provider id the Archon Access app was last made with.
+ * Drift is read against it, because a plan must not ask edge to find or make
+ * the provider.
+ */
+export const PLATFORM_ARCHON_ACCESS_PIN_SCOPE_KEY = 'cloudflare_platform_archon_access_pin';
+/**
+ * The Archon org the `AUTH_APP_KEY` in Archon's env was minted for. A key
+ * minted for another org (the CI org, before the move) is replaced by a fresh
+ * one, so the key the CI-org broker entry held stops being Archon's.
+ */
+export const PLATFORM_ARCHON_APP_KEY_ORG_SCOPE_KEY = 'archon_app_key_org';
+/**
+ * `<org>|<project>|<app>` of Archon's old sign-in client while it still waits
+ * to be deleted. Set before the new client's ids overwrite the recorded ones,
+ * cleared once the old client is gone.
+ */
+export const PLATFORM_ARCHON_RETIRED_CLIENT_SCOPE_KEY = 'zitadel_platform_archon_retired_client';
+/** The ZITADEL app id of Archon's sign-in client in the owner company's ZITADEL. */
 export const PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY = 'zitadel_platform_archon_app';
+/** The ZITADEL project id Archon's sign-in client lives in. */
+export const PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_platform_archon_project';
+/** The ZITADEL project and client ids of the Access sign-in provider, in the owner company's ZITADEL. */
+export const PLATFORM_ACCESS_ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_platform_access_project';
+export const PLATFORM_ACCESS_ZITADEL_APP_SCOPE_KEY = 'zitadel_platform_access_app';
 /**
  * The ZITADEL app id of Archon's sign-in client once "user info inside the
  * ID token" was switched on for it. `planArchonIdTokenUserinfo` plans the
@@ -653,7 +747,7 @@ export function appliedAppDomains(org, recorded, entryKey) {
  * `coolifyApp` records as applied, so a declared change replans and no secret
  * is written into it.
  */
-export function resolveAppEnv(org, entry, recorded, available = { platformMailKey: false, sharedSecret: false }) {
+export function resolveAppEnv(org, entry, recorded, available = { sharedSecret: false }) {
     const sources = {
         filesOrganisationId: recorded[`files:organisation:${org.id}`],
         aiOrganisationId: recorded[`ai:organisation:${org.id}`],
@@ -665,15 +759,6 @@ export function resolveAppEnv(org, entry, recorded, available = { platformMailKe
     const unresolvedSecrets = [];
     const marker = {};
     for (const [name, declared] of Object.entries(entry.env).sort(([a], [b]) => (a < b ? -1 : 1))) {
-        if (typeof declared !== 'string' && declared.from === 'platformMailKey') {
-            if (available.platformMailKey) {
-                secrets.push({ name, source: 'platformMailKey' });
-                marker[name] = 'secret:platformMailKey';
-            }
-            else
-                unresolvedSecrets.push([name, 'platformMailKey']);
-            continue;
-        }
         if (typeof declared !== 'string' && declared.from === 'sharedSecret') {
             const label = `sharedSecret ${declared.name}`;
             if (available.sharedSecret) {
@@ -708,6 +793,13 @@ export const PLATFORM_AI_KEY = 'platform:ai';
  * public hostname. Holds whichever way the public-hostname decision goes.
  */
 export const PLATFORM_AI_INTERNAL_URL_SCOPE_KEY = 'ai_platform_internal_url';
+/**
+ * The id of the tunnel that carries the AI host's public hostname. Recorded once the tunnel, its
+ * connector and the DNS record are in place; an entry is given `AI_URL` only after it.
+ */
+export const PLATFORM_AI_TUNNEL_SCOPE_KEY = 'cloudflare_platform_ai_tunnel';
+/** The one Coolify app that runs `cloudflared` for the AI tunnel. */
+export const PLATFORM_AI_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_ai_connector_app';
 /**
  * #172: the same two-key discipline as the ZITADEL admin key above, for
  * foundry's AI management key (the bearer key `ai:organisation`, `ai:budget`
@@ -914,6 +1006,18 @@ export const PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY = 'hc_applied_git_ref';
  * and that implementation is where the key is actually used.
  */
 export const PLATFORM_HC_API_KEY_REF = 'hc:platform:apiKey';
+/**
+ * foundry#544: the held-key ref a human puts the *outside* Healthchecks
+ * account's project API key under, read only while
+ * `platform.heartbeatsProvider` is `'hosted'` -- {@link PLATFORM_HC_API_KEY_REF}'s
+ * own ref is for the self-hosted instance only, and the two are never
+ * conflated: switching provider needs its own key held under its own ref,
+ * never the other one silently reused. Same "this package never reads the
+ * value back" rule as {@link PLATFORM_HC_API_KEY_REF}'s own doc comment --
+ * whoever implements {@link HeartbeatsPort} against the outside service is
+ * the host.
+ */
+export const PLATFORM_HEARTBEATS_HOSTED_API_KEY_REF = 'heartbeats:platform:hostedApiKey';
 /**
  * #540: the heartbeat check named after the uptime Worker (foundry#542,
  * which is what actually pings it -- blocked today on edge#26, so nothing
@@ -1113,7 +1217,7 @@ export function uptimeRecorded(recordedIds) {
  * unchanged).
  */
 export function planPlatform(platform, live, options = {}) {
-    const { jobsObservable = true, sfuBlocked = null, callsOrgSlugs, recordedIds = {}, blocked = {}, drifted = {}, } = options;
+    const { jobsObservable = true, sfuBlocked = null, callsOrgSlugs, mailRoutes = [], mailRoutesBlocked = [], recordedIds = {}, owner, liveBuilds = {}, blocked = {}, drifted = {}, } = options;
     const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
     const claimed = new Set();
     const plannedSteps = [];
@@ -1148,6 +1252,15 @@ export function planPlatform(platform, live, options = {}) {
         : (service) => `the platform's ${service} is blocked, not planned: every DNS record is written through edge, and edge is neither applied nor planned (${platform.edge.enabled
             ? (edge.blocked ?? 'its step is not planned')
             : 'the platform does not enable edge'})`;
+    // The shared oikos.host ingress: after edge, whose DNS and tunnel calls it uses.
+    const oikosIngress = planOikosIngress(platform, recordedIds, {
+        // Only once edge is APPLIED: the zone check in `blockedSteps` needs edge's address, so a
+        // same-round plan would apply unchecked and throw on a missing zone.
+        edgeApplied,
+        executorBlocked: blocked.oikosIngress,
+    });
+    if (oikosIngress.step)
+        plannedSteps.push(oikosIngress.step);
     // #540: hc needs only edge's DNS, the same as mail and archon -- no
     // auth/ZITADEL client, so it is planned here rather than after `authReady`
     // further down.
@@ -1178,19 +1291,31 @@ export function planPlatform(platform, live, options = {}) {
     const mail = planMail(platform, recordedIds, blocked.mail ?? dnsBlocked?.('mail server'), authReady);
     if (mail.step)
         plannedSteps.push(mail.step);
+    // The shared relay owns host port 25 once `mail.relay` is on, so it runs after the
+    // mail step that gives the port up.
+    const relay = planMailRelay(platform, recordedIds, {
+        routes: mailRoutes,
+        executorBlocked: blocked.relay,
+    });
+    if (relay.step)
+        plannedSteps.push(relay.step);
     // #172: a throw halts every step after it, so this one goes late.
-    const ai = planAi(platform, recordedIds, blocked.ai);
+    const ai = planAi(platform, recordedIds, blocked.ai ?? dnsBlocked?.('AI host'));
     if (ai.step)
         plannedSteps.push(ai.step);
     // #604: after edge and sign-in, whose applied ids it reads; before Archon,
     // whose redeploy can end the run.
-    const accessProvider = planAccessProvider(platform, recordedIds, blocked.accessProvider);
+    const accessProvider = planAccessProvider(platform, recordedIds, blocked.accessProvider, owner?.signIn ?? null);
     if (accessProvider.step)
         plannedSteps.push(accessProvider.step);
+    // Archon's own sign-in organisation: before Archon, whose client, env and broker entry live in it.
+    const archonOrg = planArchonOrg(platform, recordedIds, blocked.archonOrg, blocked.archonOrgInvite, owner?.signIn ?? null);
+    if (archonOrg.step)
+        plannedSteps.push(archonOrg.step);
     // #175: last, on purpose. Archon's sign-in client lives in the sign-in
     // `planAuth` builds, and its env reads what every other service's step
     // records or delivers, so in one apply it runs after all of them.
-    const archon = planArchon(platform, recordedIds, blocked.archon ?? dnsBlocked?.('Archon'), authReady, drifted.archon, blocked.archonDeployRunning);
+    const archon = planArchon(platform, recordedIds, blocked.archon ?? dnsBlocked?.('Archon'), owner?.signIn ?? null, owner?.files ?? null, drifted.archon, blocked.archonDeployRunning, { step: archonOrg.step !== null, blocked: archonOrg.blocked });
     // The host runs inside this app: its step ends by redeploying the process
     // that runs the plan, so it goes after everything else (pushed below).
     if (archon.step && !blocked.archonRunsInsideApp)
@@ -1280,6 +1405,13 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: auth.blocked, key: 'auth' });
     if (mail.blocked)
         unmanaged.push({ description: mail.blocked, key: 'mail' });
+    if (relay.blocked)
+        unmanaged.push({ description: relay.blocked, key: 'mail-relay' });
+    if (platform.mail.relay === true) {
+        for (const description of mailRoutesBlocked) {
+            unmanaged.push({ description, key: 'mail-relay:route' });
+        }
+    }
     if (integrations.blocked)
         unmanaged.push({ description: integrations.blocked, key: 'integrations' });
     if (files.blocked)
@@ -1288,11 +1420,17 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: ai.blocked, key: 'ai' });
     if (edge.blocked)
         unmanaged.push({ description: edge.blocked, key: 'edge' });
+    // Edge's own blocked reason, just above, already names the cause when edge is what is missing.
+    if (oikosIngress.blocked && !edge.blocked) {
+        unmanaged.push({ description: oikosIngress.blocked, key: 'oikos-ingress' });
+    }
     if (accessProvider.blocked) {
         unmanaged.push({ description: accessProvider.blocked, key: 'access-provider' });
     }
     if (hc.blocked)
         unmanaged.push({ description: hc.blocked, key: 'hc' });
+    if (archonOrg.blocked)
+        unmanaged.push({ description: archonOrg.blocked, key: 'archon-org' });
     if (archon.blocked)
         unmanaged.push({ description: archon.blocked, key: 'archon' });
     // #398: the old integrations key stays pinned until Archon holds the new
@@ -1315,7 +1453,7 @@ export function planPlatform(platform, live, options = {}) {
         plannedSteps: plannedSteps.map(withStepSystem),
         unmanaged,
         versionChanges,
-        notes: uptime.notes,
+        notes: [...uptime.notes, ...buildDriftNotes(recordedIds, liveBuilds)],
     };
 }
 /**
@@ -1452,19 +1590,13 @@ function planJobs(platform, byKey, claimed, observable, recordedIds) {
  * never a wrong step.
  */
 export const PLATFORM_BACKUP_DATABASE_SCOPE_KEYS = {
-    jobs: 'coolify_jobs_database',
-    auth: 'coolify_platform_auth_database',
     archon: 'coolify_platform_archon_database',
     ai: 'coolify_platform_ai_database',
-    files: 'coolify_platform_files_database',
     integrations: 'coolify_integrations_database',
 };
 export const PLATFORM_BACKUP_SERVICE_KEYS = [
-    'jobs',
-    'auth',
     'archon',
     'ai',
-    'files',
     'integrations',
 ];
 /**
@@ -1922,7 +2054,8 @@ function planMail(platform, recordedIds, executorBlocked, authReady) {
         // #177: a mail step applied before this key existed never recorded it, and
         // org steps read it for Agora's mail upstream. Missing means unapplied.
         recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY] &&
-        recordedIds[PLATFORM_MAIL_ROUTE_SCOPE_KEY] === PLATFORM_MAIL_ROUTE_WANTED) {
+        recordedIds[PLATFORM_MAIL_ROUTE_SCOPE_KEY] === PLATFORM_MAIL_ROUTE_WANTED &&
+        mailPortsApplied(platform, recordedIds)) {
         return { step: null, blocked: null };
     }
     // Only the route is missing: say so, the app is not redeployed.
@@ -1930,7 +2063,8 @@ function planMail(platform, recordedIds, executorBlocked, authReady) {
         recordedIds[PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY] &&
         recordedIds[PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY] === platform.mail.hostname &&
         recordedIds[PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY] === platform.mail.gitRef &&
-        recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY];
+        recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY] &&
+        mailPortsApplied(platform, recordedIds);
     // Stalwart's `x:ApiKey/set` shows a secret once. An id was minted but never
     // reached the host: report it, plan nothing, the same rule {@link planAuth}
     // follows for ZITADEL's own admin key.
@@ -2341,16 +2475,16 @@ function planAuthSignInPolicy(platform, recordedIds, wired) {
  * delivered (its secret cannot be shown again), or `executorBlocked` (no
  * dependencies, or edge cannot confirm Access is ready).
  */
-function planAccessProvider(platform, recordedIds, executorBlocked) {
-    if (!platform.edge.enabled || !platform.auth.enabled)
+function planAccessProvider(platform, recordedIds, executorBlocked, ownerSignIn) {
+    if (!platform.edge.enabled)
         return { step: null, blocked: null };
     if (recordedIds[ACCESS_PROVIDER_RECORD_KEY]) {
         // The secret is not stored, so a changed address cannot be re-sent: a person remakes the client.
         const appliedHostname = recordedIds[PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY];
-        if (appliedHostname && appliedHostname !== platform.auth.hostname) {
+        if (ownerSignIn && appliedHostname && appliedHostname !== ownerSignIn.hostname) {
             return {
                 step: null,
-                blocked: `the Access sign-in provider is blocked, not planned: it was applied with the sign-in hostname ${appliedHostname} and ${platform.auth.hostname} is declared now; its secret is not stored, so delete the ZITADEL client cloudflare-access, remove the recorded keys ${ACCESS_PROVIDER_RECORD_KEY}, ${PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY} and ${PLATFORM_ACCESS_PROVIDER_APPLIED_AUTH_DOMAIN_SCOPE_KEY}, then apply again`,
+                blocked: `the Access sign-in provider is blocked, not planned: it was applied with the sign-in hostname ${appliedHostname} and ${ownerSignIn.hostname} is the owner company's now; its secret is not stored, so delete the ZITADEL client cloudflare-access, remove the recorded keys ${ACCESS_PROVIDER_RECORD_KEY}, ${PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY} and ${PLATFORM_ACCESS_PROVIDER_APPLIED_AUTH_DOMAIN_SCOPE_KEY}, then apply again`,
             };
         }
         return { step: null, blocked: null };
@@ -2362,15 +2496,10 @@ function planAccessProvider(platform, recordedIds, executorBlocked) {
             blocked: `the Access sign-in provider is blocked, not planned: its ZITADEL client (${undelivered}) was made and its secret may or may not have reached edge; it cannot be shown again, so delete that client in ZITADEL and remove the recorded keys ${PLATFORM_ACCESS_PROVIDER_UNDELIVERED_SCOPE_KEY} and ${ACCESS_PROVIDER_RECORD_KEY}, then apply again to make both anew`,
         };
     }
-    const applied = Boolean(recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]) &&
-        Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_AUTH_KEY)]) &&
-        // The sibling ZITADEL steps need the delivered admin key (or the instance it came from).
-        (Boolean(recordedIds[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY]) ||
-            Boolean(recordedIds[PLATFORM_AUTH_INSTANCE_SCOPE_KEY]));
-    if (!applied) {
+    if (!ownerSignIn || !recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]) {
         return {
             step: null,
-            blocked: 'the Access sign-in provider is blocked, not planned: edge and the platform sign-in are not both applied yet',
+            blocked: "the Access sign-in provider is blocked, not planned: edge and the owner company's sign-in are not both applied yet",
         };
     }
     if (executorBlocked)
@@ -2379,7 +2508,7 @@ function planAccessProvider(platform, recordedIds, executorBlocked) {
         step: {
             action: { system: 'cloudflare', kind: 'access-provider', key: 'platform', desired: {} },
             step: {
-                description: "make the platform's ZITADEL the sign-in provider in Cloudflare Access, for company gates",
+                description: "make the owner company's ZITADEL the sign-in provider in Cloudflare Access, for company gates",
                 destroys: false,
                 migrates: false,
             },
@@ -2469,9 +2598,24 @@ function planHc(platform, recordedIds, executorBlocked) {
  * with. Without this, a fresh platform's heartbeats step is ready
  * (`hcReady`) the same round `hc` is merely *planned*, long before anyone
  * has signed in to it to create that key.
+ *
+ * foundry#544: `platform.heartbeatsProvider === 'hosted'` skips the two
+ * checks above that are specific to the self-hosted server (`platform.hc.enabled`,
+ * `hcReady`) -- the outside service needs neither `hc` declared nor applied.
+ * `apiKeyMissing` still applies in both cases, but names a different ref
+ * depending on the provider (the caller, `platform-providers.ts`'s
+ * `blockedSteps`, resolves the right one before calling this). `desired`
+ * folds the provider in alongside the check names, so switching provider
+ * with the same checks otherwise desired is still a change from the last
+ * recorded marker -- the step plans again, creating every check fresh on
+ * the newly-chosen provider (`provisionPlatformHeartbeats` lists the new
+ * provider's own live checks, sees none of foundry's names yet, and creates
+ * all of them) rather than reading "nothing left to reconcile" against a
+ * marker that was true of the *other* provider.
  */
 function planHeartbeats(platform, recordedIds, hcReady, executorMissing, apiKeyMissing) {
-    if (!platform.hc.enabled) {
+    const hosted = platform.heartbeatsProvider === 'hosted';
+    if (!hosted && !platform.hc.enabled) {
         // Removing checks is not planned. The recorded marker names the checks
         // foundry's last reconcile wanted, so they are foundry's own; report
         // them rather than leave them unseen.
@@ -2483,7 +2627,7 @@ function planHeartbeats(platform, recordedIds, hcReady, executorMissing, apiKeyM
                 : null,
         };
     }
-    if (!hcReady) {
+    if (!hosted && !hcReady) {
         return {
             step: null,
             blocked: 'the heartbeat checks are blocked, not planned: platform:hc has not been applied yet',
@@ -2498,10 +2642,12 @@ function planHeartbeats(platform, recordedIds, hcReady, executorMissing, apiKeyM
     if (apiKeyMissing) {
         return {
             step: null,
-            blocked: `the heartbeat checks are blocked, not planned: no project API key is held yet for hc (${PLATFORM_HC_API_KEY_REF}); a human must sign in to hc, create the first superuser account and a project, mint that project's API key, and hold it under that ref (issue #540 "Human steps") before this step can call hc's check-creation API`,
+            blocked: hosted
+                ? `the heartbeat checks are blocked, not planned: no project API key is held yet for the outside Healthchecks account (${PLATFORM_HEARTBEATS_HOSTED_API_KEY_REF}); a human must create that account (or project), mint its API key, and hold it under that ref (issue #544 "Human steps") before this step can call its check-creation API`
+                : `the heartbeat checks are blocked, not planned: no project API key is held yet for hc (${PLATFORM_HC_API_KEY_REF}); a human must sign in to hc, create the first superuser account and a project, mint that project's API key, and hold it under that ref (issue #540 "Human steps") before this step can call hc's check-creation API`,
         };
     }
-    const desired = [...desiredHeartbeatCheckNames(recordedIds)].sort().join(',');
+    const desired = `${platform.heartbeatsProvider}:${[...desiredHeartbeatCheckNames(recordedIds)].sort().join(',')}`;
     if (recordedIds[PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY] === desired) {
         return { step: null, blocked: null };
     }
@@ -2656,7 +2802,9 @@ function planAi(platform, recordedIds, executorBlocked) {
     // already set then, so nothing is minted again.
     const applied = Boolean(recordedIds[key]);
     const drifted = recordedIds[PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY] !== platform.ai.hostname ||
-        recordedIds[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY] !== platform.ai.gitRef;
+        recordedIds[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY] !== platform.ai.gitRef ||
+        // The public route (tunnel, connector, DNS record) is part of the step: a host applied before it existed plans it once.
+        !recordedIds[PLATFORM_AI_TUNNEL_SCOPE_KEY];
     if (applied && !drifted)
         return { step: null, blocked: null };
     // #201: the signing pair foundry mints to authenticate its own calls to
@@ -2746,13 +2894,67 @@ function planAi(platform, recordedIds, executorBlocked) {
  * ({@link PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY}) plans the step again, as
  * {@link planAuth} does.
  */
-function planArchon(platform, recordedIds, executorBlocked, authReady, drifted, deployRunning) {
+/** Archon signs its operators in through the owner company's own sign-in; fixed text, part of the stale-plan comparison. */
+export const ARCHON_OWNER_SIGN_IN_BLOCKED = "Archon is blocked, not planned: the owner company's sign-in is not applied yet";
+/** Archon signs in from its own organisation, which the `zitadel:archon-org` step makes; fixed text, part of the stale-plan comparison. */
+export const ARCHON_ORG_BLOCKED = 'Archon is blocked, not planned: its own sign-in organisation is not applied yet';
+/**
+ * Archon's own sign-in organisation in the owner company's ZITADEL: the org,
+ * its primary domain, closed registration, the second-factor policy, and the
+ * first person's invite. One `zitadel:archon-org` step keyed
+ * {@link PLATFORM_ARCHON_KEY}, planned while any of those is not recorded
+ * against the recorded org, and always before `platform:archon`. Blocked, not
+ * planned, while the host cannot reach the instance. A refused domain is
+ * reported as a standing note (as the owner org's is) and does not hold the
+ * step; an invite that cannot be sent (no work address, no mail port) is a
+ * standing note and does not hold it either.
+ */
+function planArchonOrg(platform, recordedIds, executorBlocked, inviteBlocked, ownerSignIn) {
+    if (!platform.archon.enabled || !ownerSignIn)
+        return { step: null, blocked: null };
+    const orgId = recordedIds[PLATFORM_ARCHON_ORG_SCOPE_KEY];
+    const blockedDomain = recordedIds[PLATFORM_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY];
+    const domainDone = Boolean(recordedIds[PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY]) || Boolean(blockedDomain);
+    const inviteRecorded = recordedIds[PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY];
+    const inviteDone = Boolean(inviteBlocked) ||
+        inviteRecorded === 'none' ||
+        (Boolean(inviteRecorded) && recordedIds[PLATFORM_ARCHON_OWNER_INVITE_ORG_SCOPE_KEY] === orgId);
+    const standing = [
+        inviteBlocked,
+        blockedDomain && !recordedIds[PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY]
+            ? `Archon's sign-in domain ${blockedDomain} is blocked, not planned: the sign-in server refused to make it primary because its domain policy wants proof of ownership. Set the policy ValidateOrgDomains to false on the sign-in server, then remove the recorded key ${PLATFORM_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY}`
+            : null,
+    ].filter((v) => Boolean(v));
+    const standingNote = standing.length > 0 ? standing.join('; ') : null;
+    if (orgId &&
+        domainDone &&
+        recordedIds[PLATFORM_ARCHON_ORG_REGISTRATION_CLOSED_SCOPE_KEY] === orgId &&
+        recordedIds[PLATFORM_ARCHON_ORG_POLICY_SCOPE_KEY] === orgId &&
+        inviteDone) {
+        return { step: null, blocked: standingNote };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    return {
+        step: {
+            action: { system: 'zitadel', kind: 'archon-org', key: PLATFORM_ARCHON_KEY, desired: {} },
+            step: {
+                description: "make Archon's own sign-in organisation in the owner company's ZITADEL: close registration, force a second factor, and invite the first person",
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: standingNote,
+    };
+}
+function planArchon(platform, recordedIds, executorBlocked, ownerSignIn, ownerFiles, drifted, deployRunning, archonOrg = { step: false, blocked: null }) {
     if (!platform.archon.enabled)
         return { step: null, blocked: null };
     // A deploy the step triggered is still running: planning it again would deploy twice.
     if (deployRunning)
         return { step: null, blocked: deployRunning };
     const key = resourceKey('coolify', 'app', PLATFORM_ARCHON_KEY);
+    const archonOrgId = recordedIds[PLATFORM_ARCHON_ORG_SCOPE_KEY];
     const applied = Boolean(recordedIds[key]) &&
         Boolean(recordedIds[PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY]) &&
         recordedIds[PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY] === platform.archon.hostname &&
@@ -2761,11 +2963,20 @@ function planArchon(platform, recordedIds, executorBlocked, authReady, drifted,
         // deleted by hand, or `platform:auth` minting a fresh one) leaves
         // Archon's last registration on a broker that no longer exists, and
         // nothing else here would ever plan the step again to redo it.
-        Boolean(recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY]) &&
-        recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY] ===
-            recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY] &&
-        recordedIds[PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY] ===
-            archonAuthOrganizationId(recordedIds) &&
+        ownerSignIn !== null &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY] === ownerSignIn.brokerAppId &&
+        // Archon signs in from its own organisation, never the company's.
+        Boolean(archonOrgId) &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY] === archonOrgId &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_CI_ORG_SCOPE_KEY] === ownerSignIn.organisationId &&
+        (recordedIds[PLATFORM_ARCHON_APPLIED_FIRST_OWNER_LINK_SCOPE_KEY] ?? '') ===
+            archonFirstOwnerLink(recordedIds, ownerSignIn) &&
+        recordedIds[PLATFORM_ARCHON_APP_KEY_ORG_SCOPE_KEY] === archonOrgId &&
+        !recordedIds[PLATFORM_ARCHON_RETIRED_CLIENT_SCOPE_KEY] &&
+        Boolean(recordedIds[PLATFORM_ARCHON_ACCESS_PIN_SCOPE_KEY]) &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_AUTH_HOSTNAME_SCOPE_KEY] === ownerSignIn.hostname &&
+        (recordedIds[PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY] ?? 'none') ===
+            archonFilesMarker(ownerFiles) &&
         // #475: a platform applied before the rolling-update fix keeps planning
         // this step until a confirmed redeploy has cleared it. #480: this marker
         // alone does not catch the live app's settings changing back afterward
@@ -2797,17 +3008,11 @@ function planArchon(platform, recordedIds, executorBlocked, authReady, drifted,
                 recordedIds[PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY]);
     if (applied && !drifted)
         return { step: null, blocked: null };
-    if (!platform.auth.enabled) {
-        return {
-            step: null,
-            blocked: "Archon is blocked, not planned: its sign-in client lives in the platform's own sign-in, and auth is not enabled",
-        };
-    }
-    if (!authReady) {
-        return {
-            step: null,
-            blocked: "Archon is blocked, not planned: its sign-in client lives in the platform's own sign-in, which is neither applied nor planned",
-        };
+    if (!ownerSignIn)
+        return { step: null, blocked: ARCHON_OWNER_SIGN_IN_BLOCKED };
+    // The org is recorded, or its step runs earlier in this same plan.
+    if (!archonOrgId && !archonOrg.step) {
+        return { step: null, blocked: archonOrg.blocked ?? ARCHON_ORG_BLOCKED };
     }
     if (executorBlocked)
         return { step: null, blocked: executorBlocked };