@wtfalch/foundry 0.4.0 → 0.6.0

package/dist/plan/platform-providers.js

@@ -0,0 +1,4410 @@
+import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, randomUUID, sign, } from 'node:crypto';
+import { isIPv4 } from 'node:net';
+import { redactSecrets } from '../calls-sfu-deploy-support.js';
+import { ensureCloudflaredConnector } from './cloudflared-connector.js';
+import { ACCESS_POLICY_NAME, isNotFoundError, isRunningOrStarting } from './executor.js';
+import { JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
+import { applyCallsSfuPlatformStep } from './platform-sfu.js';
+/** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
+function apexZoneKey(apex) {
+    return `cloudflare:zone:${apex}`;
+}
+/** The key `runPlatformSteps` records the jobs scheduler app's id under (`system:kind:key`, #173). */
+const JOBS_APP_KEY = `coolify:jobs:${JOBS_SCHEDULER_KEY}`;
+/**
+ * #173: the jobs scheduler's own Coolify project and database, flat scope
+ * ids recorded via `PlatformStepExecutionContext.recordScopeId` -- not
+ * `system:kind:key` (that form is reserved for the one resource
+ * `runPlatformSteps` auto-records from a step's own `resourceId`, the app
+ * itself), the same distinction `executor.ts`'s `coolify_project`/
+ * `CALLS_SERVICE_DB_SCOPE_KEY` draw for an org's own steps.
+ */
+const JOBS_PROJECT_SCOPE_KEY = 'platform_coolify_project';
+const JOBS_DATABASE_SCOPE_KEY = 'coolify_jobs_database';
+/**
+ * Set (to the app's uuid) once the scheduler's `SCHEDULER_ADMIN_TOKEN` has
+ * been delivered to the host and written to the app. The token is only
+ * generated while this is unset, so a rerun of a step that failed earlier
+ * never rotates a token the host already holds.
+ */
+const JOBS_ADMIN_TOKEN_SCOPE_KEY = 'jobs_admin_token_set';
+/** How many times `coolifyJobs` tries `deliverSecret` before giving up. */
+const JOBS_ADMIN_TOKEN_DELIVERY_ATTEMPTS = 3;
+/** The ref the scheduler's admin token is delivered under: the host's real `JobsSchedulerPort` adapter reads it back. */
+export const JOBS_ADMIN_TOKEN_REF = 'jobs:scheduler:adminToken';
+/** The name of the Coolify project every platform-level service (starting with jobs, #173) lives in. */
+const PLATFORM_COOLIFY_PROJECT_NAME = 'platform';
+/** https://github.com/wtfalch/jobs -- the scheduler's own repo, Dockerfile at its root (its own `Dockerfile`'s doc comment). */
+const JOBS_SCHEDULER_REPO = 'wtfalch/jobs';
+/**
+ * The real {@link PlatformStepExecutor} for the two steps built so far:
+ * `cloudflare:zone` for the platform's apex (#167) and `coolify:jobs` for the
+ * jobs scheduler (#173). `coolify` is optional so every #167-era caller --
+ * anything that only ever plans the apex zone -- keeps constructing this with
+ * two arguments; a `coolify:jobs` step reaching this executor with no
+ * `coolify` port configured throws, naming what is missing, rather than
+ * silently doing nothing.
+ *
+ * `cloudflareZone` mirrors `executor.ts`'s `cloudflareZone`: find the zone by
+ * apex and adopt it, create it only when absent. companyincluded.com already
+ * exists on Cloudflare, empty, so the first apply adopts it. The owner org
+ * (Company Included, whose own domain is the apex) may record the same zone
+ * under its own applied state, so that owner is allowed. Any other org that
+ * recorded it makes this refuse to adopt. There is no delete here and
+ * `PlatformStepExecutor` has none: neither path ever removes the zone.
+ *
+ * `coolifyJobs` mirrors `executor.ts`'s `coolifyApp`/`coolifyDatabase`,
+ * simplified for one platform-level singleton rather than one per org: find
+ * or create a dedicated `platform` Coolify project, find or create the
+ * scheduler's own database, find or create the scheduler app itself (from
+ * https://github.com/wtfalch/jobs, one Dockerfile at its repo root, on the
+ * declared `gitRef`), then push the database's `internal_db_url` in as
+ * `DATABASE_URL`. There is no park branch yet, matching `planJobs`'s own
+ * scope note -- `platform.jobs.enabled` going from true to false plans
+ * nothing, so this method is never asked to stop or delete anything.
+ *
+ * #170 adds `sfu:livekit`, the platform's shared calls SFU. `sfu` is
+ * optional: an existing host that constructs this executor for the zone step
+ * alone keeps compiling, and a plan that includes an `sfu:livekit` step
+ * without it configured refuses clearly rather than silently doing nothing.
+ * #152: the step mints one LiveKit key per org with calls enabled rather
+ * than one shared pair, so it also needs `declaredOrgStore.list()` -- the
+ * same store this class already takes for `findOrgIdForZone`.
+ *
+ * #168 adds `coolify:app` keyed {@link PLATFORM_AUTH_KEY}, the platform's own
+ * sign-in ({@link provisionPlatformAuth}), once a host passes
+ * {@link PlatformAuthDeps}.
+ *
+ * #169 adds `coolify:app` keyed {@link PLATFORM_MAIL_KEY}, the platform's own
+ * mail server ({@link provisionPlatformMail}), once a host passes
+ * {@link PlatformMailDeps}.
+ *
+ * #174 adds `coolify:app` keyed {@link PLATFORM_INTEGRATIONS_KEY},
+ * the integrations host ({@link provisionPlatformIntegrations}), once a host
+ * passes {@link PlatformIntegrationsDeps}.
+ *
+ * #171 adds `coolify:app` keyed {@link PLATFORM_FILES_KEY}, the files host
+ * ({@link provisionPlatformFiles}), once a host passes {@link PlatformFilesDeps}.
+ *
+ * #172 adds `coolify:app` keyed {@link PLATFORM_AI_KEY}, the platform's AI
+ * host ({@link provisionPlatformAi}), once a host passes {@link PlatformAiDeps}.
+ *
+ * #175 adds `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, Archon itself
+ * ({@link provisionPlatformArchon}), once a host passes
+ * {@link PlatformArchonDeps}.
+ */
+export class FoundryPlatformStepExecutor {
+    cloudflare;
+    declaredOrgStore;
+    coolify;
+    deliverSecret;
+    sfu;
+    auth;
+    mail;
+    integrations;
+    files;
+    ai;
+    archon;
+    constructor(cloudflare, declaredOrgStore, options = {}) {
+        this.cloudflare = cloudflare;
+        this.declaredOrgStore = declaredOrgStore;
+        this.coolify = options.coolify;
+        this.deliverSecret = options.deliverSecret;
+        this.sfu = options.sfu;
+        this.auth = options.auth;
+        this.mail = options.mail;
+        this.integrations = options.integrations;
+        this.files = options.files;
+        this.ai = options.ai;
+        this.archon = options.archon;
+    }
+    async blockedSteps(platform, recordedIds = {}) {
+        const blocked = {};
+        if (platform.auth.enabled && !this.auth) {
+            blocked.auth =
+                "the platform's sign-in is blocked, not planned: the host built the platform executor without its auth dependencies";
+            // #211 round 6: its own signal, distinct from `auth` -- `planAuth` must
+            // withhold the step for this case whatever the recorded broker state
+            // says, unlike "broker created, deploy still blocked" (below).
+            blocked.authExecutorMissing = true;
+        }
+        else if (platform.auth.enabled && this.auth) {
+            const { reason: authBlocked, otherInputsMissing } = await authBrokerBlockedReason(this.auth, recordedIds);
+            if (authBlocked)
+                blocked.auth = authBlocked;
+            // #216 round 5: see `PlanPlatformOptions.blocked.authOtherInputsMissing`.
+            if (otherInputsMissing.length > 0)
+                blocked.authOtherInputsMissing = otherInputsMissing;
+        }
+        if (platform.mail.enabled) {
+            const mailBlocked = await mailBlockedReason(platform, this.mail, recordedIds);
+            if (mailBlocked)
+                blocked.mail = mailBlocked;
+        }
+        if (platform.integrations.enabled && !this.integrations) {
+            blocked.integrations =
+                'the integrations host is blocked, not planned: the host built the platform executor without its integrations dependencies';
+        }
+        else if (platform.integrations.enabled && this.integrations) {
+            const missing = INTEGRATIONS_KEYS_ENV_NAMES.filter((n) => !this.integrations?.keysEnv?.[n]);
+            if (missing.length > 0) {
+                blocked.integrations = `the integrations host is blocked, not planned: the host supplies no value for ${missing.join(', ')}, the host's own @wtfalch/keys settings`;
+            }
+        }
+        if (platform.files.enabled && !this.files) {
+            blocked.files =
+                'the files host is blocked, not planned: the host built the platform executor without its files dependencies';
+        }
+        else if (platform.files.enabled && !filesKeys(this.files)) {
+            blocked.files =
+                'the files host is blocked, not planned: the host supplies no keys worker URL and credential (KEYS_WORKER_URL, KEYS_CREDENTIAL), so files-migrate would never become healthy';
+        }
+        if (platform.ai.enabled && !this.ai) {
+            blocked.ai =
+                "the platform's AI host is blocked, not planned: the host built the platform executor without its ai dependencies";
+        }
+        else if (platform.ai.enabled &&
+            !this.ai?.managementKeyMinter &&
+            !this.ai?.heldKeys &&
+            recordedIds[PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY] &&
+            !recordedIds[PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY]) {
+            // The signing pair was pinned on an earlier apply; minting the
+            // management key needs its private half read back, and no minter was
+            // injected to skip that (#201).
+            blocked.ai =
+                "the platform's AI host is blocked, not planned: its signing key is already pinned but the host built the platform executor without a held-key reader to read back its private half (PlatformAiDeps.heldKeys)";
+        }
+        if (platform.archon.enabled) {
+            if (!this.archon) {
+                blocked.archon =
+                    'Archon is blocked, not planned: the host built the platform executor without its archon dependencies';
+            }
+            else if (this.archon.accessEmails.length === 0) {
+                blocked.archon =
+                    'Archon is blocked, not planned: the host names no email the Cloudflare Access app in front of it may let through';
+            }
+            else {
+                const inputs = await collectArchonServiceInputs(platform, this.archon, recordedIds);
+                if ('blocked' in inputs) {
+                    blocked.archon = inputs.blocked;
+                }
+                else if (!this.archon.masterKeys || !this.archon.heldKeys?.put) {
+                    // #213: Archon's own onboarding reads these back as held keys
+                    // before it can start; a host that cannot put them blocks Archon,
+                    // the same rule a missing service ref follows above.
+                    blocked.archon =
+                        'Archon is blocked, not planned: the host built the platform executor without a way to put its master keys (masterKeys, and heldKeys with a put)';
+                }
+            }
+        }
+        return blocked;
+    }
+    /**
+     * Whether Archon's live Access policy lets through anyone but the declared
+     * emails, or (#211 round 4) the broker it last registered with no longer
+     * carries its entry; or (#216 round 4) the platform's recorded
+     * login-client token is no longer the sole live PAT on its ZITADEL machine
+     * user.
+     */
+    async driftedSteps(platform, recordedIds = {}) {
+        const result = {};
+        if (platform.archon.enabled &&
+            this.archon &&
+            recordedIds[`coolify:app:${PLATFORM_ARCHON_KEY}`]) {
+            const accessDrifted = await archonAccessDrifted(this.archon.cloudflare, platform.archon.hostname, this.archon.accessEmails);
+            const brokerDrifted = !accessDrifted && (await archonBrokerRegistrationDrifted(this.archon.coolify, recordedIds));
+            if (accessDrifted || brokerDrifted)
+                result.archon = true;
+        }
+        if (platform.auth.enabled && this.auth) {
+            const loginClientDrifted = await authLoginClientDrifted(platform, this.auth, recordedIds);
+            if (loginClientDrifted)
+                result.auth = true;
+        }
+        return result;
+    }
+    async execute(action, context) {
+        if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_AUTH_KEY) {
+            if (!this.auth) {
+                throw new Error('platform:auth needs FoundryPlatformStepExecutor to be constructed with its auth dependencies (#168)');
+            }
+            return provisionPlatformAuth(context, this.auth);
+        }
+        if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_FILES_KEY) {
+            if (!this.files) {
+                throw new Error('platform:files needs FoundryPlatformStepExecutor to be constructed with its files dependencies (#171)');
+            }
+            return provisionPlatformFiles(context, this.files);
+        }
+        if (action.system === 'coolify' &&
+            action.kind === 'app' &&
+            action.key === PLATFORM_INTEGRATIONS_KEY) {
+            if (!this.integrations) {
+                throw new Error('platform:integrations needs FoundryPlatformStepExecutor to be constructed with its integrations dependencies (#174)');
+            }
+            return provisionPlatformIntegrations(action, context, this.integrations);
+        }
+        if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_AI_KEY) {
+            if (!this.ai) {
+                throw new Error('platform:ai needs FoundryPlatformStepExecutor to be constructed with its ai dependencies (#172)');
+            }
+            return provisionPlatformAi(context, this.ai);
+        }
+        if (action.system === 'coolify' &&
+            action.kind === 'app' &&
+            action.key === PLATFORM_ARCHON_KEY) {
+            if (!this.archon) {
+                throw new Error('platform:archon needs FoundryPlatformStepExecutor to be constructed with its archon dependencies (#175)');
+            }
+            return provisionPlatformArchon(context, this.archon);
+        }
+        if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_MAIL_KEY) {
+            if (!this.mail) {
+                throw new Error('platform:mail needs FoundryPlatformStepExecutor to be constructed with its mail dependencies (#169)');
+            }
+            return provisionPlatformMail(context, this.mail);
+        }
+        if (action.system === 'cloudflare' && action.kind === 'zone') {
+            return this.cloudflareZone(action, context);
+        }
+        if (action.system === 'coolify' && action.kind === 'jobs') {
+            return this.coolifyJobs(action, context);
+        }
+        if (action.system === 'sfu' && action.kind === 'livekit') {
+            return this.executeSfu();
+        }
+        throw new Error(`platform step ${action.system}:${action.kind} is not built yet`);
+    }
+    async cloudflareZone(action, context) {
+        const domain = action.key;
+        const existing = await exactZone(this.cloudflare, domain);
+        if (existing) {
+            const owner = await this.declaredOrgStore.findOrgIdForZone(existing.id);
+            if (owner !== null && owner !== context.platform.ownerOrgId) {
+                throw new Error(`cloudflare:zone for the platform: zone ${existing.id} (${domain}) is already recorded under org ${owner}; foundry does not adopt it`);
+            }
+            return { resourceId: existing.id };
+        }
+        const created = await this.cloudflare.createZone(domain);
+        return { resourceId: created.id };
+    }
+    /**
+     * #152: the platform `sfu` step owns the shared LiveKit config, so it
+     * lists every org with calls enabled itself -- `DeclaredOrgStore.list()`,
+     * filtered the same way an org's own `calls.enabled` flag gates its
+     * `coolify:calls-service` step (`executor.ts`'s `coolifyCallsService`) --
+     * rather than taking the list as an argument nothing else would supply.
+     * Sorted by slug so a re-run with the same set of enabled orgs is a no-op
+     * even before `applyCallsSfuPlatformStep`'s own sort (its doc comment).
+     */
+    async executeSfu() {
+        if (!this.sfu) {
+            throw new Error('platform step sfu:livekit is not built yet (#170: pass `sfu` to FoundryPlatformStepExecutor)');
+        }
+        const orgs = await this.declaredOrgStore.list();
+        const orgSlugs = orgs
+            .filter((org) => org.calls.enabled)
+            .map((org) => org.slug)
+            .sort();
+        await applyCallsSfuPlatformStep(this.sfu, orgSlugs);
+        return undefined;
+    }
+    async coolifyJobs(action, context) {
+        const coolify = this.coolify;
+        if (!coolify) {
+            throw new Error('platform step coolify:jobs needs a Coolify port -- construct FoundryPlatformStepExecutor with one (#173)');
+        }
+        const deliverSecret = this.deliverSecret;
+        if (!deliverSecret) {
+            throw new Error('platform step coolify:jobs needs a deliverSecret -- construct FoundryPlatformStepExecutor with one, to hand the scheduler admin token to the host (#173)');
+        }
+        const hostname = action.desired.hostname;
+        const gitRef = action.desired.gitRef;
+        const recorded = context.recordedIds();
+        let projectUuid = recorded[JOBS_PROJECT_SCOPE_KEY];
+        if (!projectUuid) {
+            const found = await coolify.findProjectByName(PLATFORM_COOLIFY_PROJECT_NAME);
+            projectUuid = found
+                ? found.uuid
+                : (await coolify.createProject(PLATFORM_COOLIFY_PROJECT_NAME)).uuid;
+            context.recordScopeId(JOBS_PROJECT_SCOPE_KEY, projectUuid);
+        }
+        const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+        let dbId = recorded[JOBS_DATABASE_SCOPE_KEY];
+        if (!dbId) {
+            const dbName = `${JOBS_SCHEDULER_KEY}-scheduler-db`;
+            const found = (await coolify.listDatabases()).find((db) => db.name === dbName && db.environment_id === environment.id);
+            if (found) {
+                dbId = found.uuid;
+            }
+            else {
+                const server = await resolvePlatformServer(coolify);
+                const created = await coolify.createPostgresDatabase({
+                    project_uuid: projectUuid,
+                    server_uuid: server.uuid,
+                    environment_name: environment.name,
+                    environment_uuid: environment.uuid,
+                    name: dbName,
+                    postgres_db: 'jobs',
+                    postgres_user: 'jobs',
+                });
+                dbId = created.uuid;
+            }
+            context.recordScopeId(JOBS_DATABASE_SCOPE_KEY, dbId);
+        }
+        const existingApp = await coolify.findApplicationByName(JOBS_SCHEDULER_KEY, {
+            environmentIds: [environment.id],
+        });
+        let appId;
+        if (existingApp) {
+            appId = existingApp.uuid;
+        }
+        else {
+            const server = await resolvePlatformServer(coolify);
+            const githubApp = await coolify.requireGithubApp();
+            const created = await coolify.createGithubAppApplication({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                github_app_uuid: githubApp.uuid,
+                git_repository: JOBS_SCHEDULER_REPO,
+                git_branch: gitRef,
+                build_pack: 'dockerfile',
+                name: JOBS_SCHEDULER_KEY,
+                domains: hostname,
+            });
+            appId = created.uuid;
+        }
+        const db = await coolify.getDatabase(dbId);
+        if (!db.internal_db_url) {
+            throw new Error(`platform step coolify:jobs: database ${dbId} has no internal_db_url yet; not deploying the scheduler without a database`);
+        }
+        const envs = [{ key: 'DATABASE_URL', value: db.internal_db_url }];
+        // SCHEDULER_ADMIN_TOKEN gates the admin API the org registrations use
+        // (jobs README, "The admin API"); unset, every admin route answers 401.
+        // Delivered to the host before it is written to the app, so a failed
+        // delivery leaves nothing set and the rerun simply generates a new one.
+        let tokenJustSet = false;
+        if (!context.recordedIds()[JOBS_ADMIN_TOKEN_SCOPE_KEY]) {
+            const token = randomBytes(32).toString('hex');
+            let delivered = false;
+            for (let attempt = 1; attempt <= JOBS_ADMIN_TOKEN_DELIVERY_ATTEMPTS && !delivered; attempt++) {
+                try {
+                    await deliverSecret(JOBS_ADMIN_TOKEN_REF, token);
+                    delivered = true;
+                }
+                catch {
+                    // Retried; the error is dropped in case it echoes the token.
+                }
+            }
+            if (!delivered) {
+                throw new Error(`platform step coolify:jobs: the scheduler admin token could not be delivered after ${JOBS_ADMIN_TOKEN_DELIVERY_ATTEMPTS} attempts`);
+            }
+            envs.push({ key: 'SCHEDULER_ADMIN_TOKEN', value: token });
+            await coolify.bulkUpsertEnvs(appId, envs);
+            context.recordScopeId(JOBS_ADMIN_TOKEN_SCOPE_KEY, appId);
+            tokenJustSet = true;
+        }
+        else {
+            await coolify.bulkUpsertEnvs(appId, envs);
+        }
+        // The app is created with `instant_deploy: false` and an env change needs
+        // a redeploy, so deploy after a create or a new token. Also when it is not
+        // running, so a deploy that failed on an earlier run is retried.
+        const running = (await coolify.getApplication(appId)).status?.startsWith('running') ?? false;
+        if (!existingApp || tokenJustSet || !running)
+            await coolify.deploy(appId);
+        return { resourceId: appId };
+    }
+}
+// ---------------------------------------------------------------------------
+// #168: the platform's own sign-in (ZITADEL)
+// ---------------------------------------------------------------------------
+const PLATFORM_AUTH_PROJECT = 'platform';
+const PLATFORM_AUTH_DB_NAME = 'platform-auth-db';
+const PLATFORM_AUTH_ZITADEL_APP_NAME = 'platform-auth-zitadel';
+const PLATFORM_AUTH_LOGIN_APP_NAME = 'platform-auth-login';
+const PLATFORM_AUTH_BROKER_APP_NAME = 'platform-auth-broker';
+/**
+ * Fixed `custom_internal_name`s (`diff.ts`'s `coolifyCalls` sets the same
+ * kind of name on Synapse/MAS) so the Cloudflare tunnel below can address
+ * each app directly, by container name, on the shared Coolify Docker network
+ * -- bypassing Coolify's own Traefik, which dispatches purely by `Host`
+ * header and so cannot give two different apps the same public hostname.
+ */
+const PLATFORM_AUTH_ZITADEL_INTERNAL_NAME = 'platform-auth-zitadel';
+const PLATFORM_AUTH_LOGIN_INTERNAL_NAME = 'platform-auth-login';
+const PLATFORM_AUTH_BROKER_INTERNAL_NAME = 'platform-auth-broker';
+const PLATFORM_AUTH_TUNNEL_NAME = 'platform-auth-tunnel';
+/** #197: the one Coolify app that runs `cloudflared` for {@link PLATFORM_AUTH_TUNNEL_NAME}. */
+const PLATFORM_AUTH_CLOUDFLARED_APP_NAME = 'platform-auth-cloudflared';
+/** `wtfalch/auth`'s `docker-compose.yml`: `image: ghcr.io/zitadel/zitadel:${ZITADEL_VERSION:-v4.17.3}`. */
+const AUTH_ZITADEL_IMAGE = 'ghcr.io/zitadel/zitadel';
+const AUTH_ZITADEL_IMAGE_TAG = 'v4.17.3';
+/** `wtfalch/auth`'s own `login/Dockerfile` -- `docs/deploy.md`'s "One compose service, four containers... Two images are built from this repository: the proxy... and the login". */
+const AUTH_REPO = 'wtfalch/auth';
+const AUTH_LOGIN_DOCKERFILE = 'login/Dockerfile';
+/** `wtfalch/auth`'s own `broker/Dockerfile` -- built from the repo root so the workspace resolves (#204). */
+const AUTH_BROKER_DOCKERFILE = 'broker/Dockerfile';
+/**
+ * `wtfalch/auth`'s login app answers on 3000 (its `Dockerfile`'s Next.js
+ * default); ZITADEL answers on 8080 -- both fixed by `docker-compose.yml`'s
+ * own `ZITADEL_PORT: 8080` and the login image's own `EXPOSE`.
+ */
+const AUTH_ZITADEL_PORT = '8080';
+const AUTH_LOGIN_PORT = '3000';
+/** `broker/Dockerfile`'s own `ENV PORT=3000` / `EXPOSE 3000`. */
+const AUTH_BROKER_PORT = '3000';
+/**
+ * Every ZITADEL OIDC/management/console/asset path -- `deploy/proxy/Caddyfile`'s
+ * own explicit list, restated here as one regex since the tunnel routes by a
+ * single `path` per ingress rule rather than a set. Anything not matching
+ * falls through to the login app's own ingress rule below (login v2 answers
+ * everything else, including the root).
+ */
+const AUTH_ZITADEL_PATH_PATTERN = '^/(oidc|oauth|saml|management|admin|system|auth|assets|ui/console|\\.well-known)(/|$)';
+/**
+ * `@wtfalch/auth`'s own `brokerUrl` default, `<issuer>/api`
+ * (`packages/auth/src/config.ts`) -- `deploy/proxy/Caddyfile`'s own
+ * `handle /api/*`. Checked before {@link AUTH_ZITADEL_PATH_PATTERN}'s
+ * catch-all-else login rule below, so it must be its own ingress rule rather
+ * than folded into it.
+ */
+const AUTH_BROKER_PATH_PATTERN = '^/api(/|$)';
+const PLATFORM_AUTH_PROJECT_SCOPE_KEY = 'coolify_project_platform_auth';
+const PLATFORM_AUTH_DB_SCOPE_KEY = 'coolify_platform_auth_database';
+const PLATFORM_AUTH_ZITADEL_SCOPE_KEY = 'coolify_platform_auth_zitadel_app';
+const PLATFORM_AUTH_LOGIN_SCOPE_KEY = 'coolify_platform_auth_login_app';
+const PLATFORM_AUTH_TUNNEL_SCOPE_KEY = 'cloudflare_platform_auth_tunnel';
+/** Recorded once the ZITADEL app has been deployed, so ZITADEL may have written to its database. */
+const PLATFORM_AUTH_ZITADEL_DEPLOYED_SCOPE_KEY = 'zitadel_platform_auth_deployed';
+const PLATFORM_AUTH_ADMIN_USER_NAME = 'foundry-admin';
+/** #216 (building on #209/#215): the narrower `IAM_LOGIN_CLIENT` machine user for the login app and the broker. */
+const PLATFORM_AUTH_LOGIN_CLIENT_USER_NAME = 'foundry-login-client';
+const PLATFORM_AUTH_ORG_NAME = 'foundry';
+/**
+ * Retries `action` up to `attempts` times, sleeping increasingly between
+ * tries -- the same shape the admin machine user's own delivery retry (just
+ * below) already uses inline, pulled out here because #216's login-client
+ * block needs it four times over (both apps' envs, both apps' deploys)
+ * rather than once. Rethrows the *last* failure unwrapped: callers that must
+ * never echo the underlying error (a Coolify validation error can include
+ * the rejected value -- here, the token itself, #216 follow-up review item
+ * 1) catch this function's own rejection and build a safe message instead of
+ * reading `.message` off what it throws.
+ */
+async function retryPlatformAuthCall(attempts, sleep, action) {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            return await action();
+        }
+        catch (e) {
+            if (attempt >= attempts)
+                throw e;
+            await sleep(1000 * attempt);
+        }
+    }
+}
+/**
+ * #216 round 5: sha256 of the exact login-client token value -- never the
+ * token itself, only its hash, the same `hashAuthApps` rule for the same
+ * reason: a recorded scope id must never leak a secret.
+ */
+function hashLoginClientToken(token) {
+    return createHash('sha256').update(token).digest('hex');
+}
+/**
+ * #216 round 4/5: encodes the {@link PlatformAuthLoginClientRecord} a
+ * successful login-client delivery writes under
+ * {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY}, replacing the plain
+ * user-id string round 2-3 wrote there. Paired with
+ * {@link parseLoginClientRecord} (`platform-diff.ts`), which `planAuth`
+ * reads back to answer whether the delivered PAT is still live, and with
+ * {@link authLoginClientDrifted} below, which (round 5) also reads `token`'s
+ * hash back to answer whether what was actually delivered is still live.
+ */
+function loginClientRecordValue(userId, patId, token) {
+    const record = {
+        userId,
+        patId,
+        tokenHash: hashLoginClientToken(token),
+    };
+    return JSON.stringify(record);
+}
+/**
+ * #216 round 4: whether the login-client PAT recorded for this platform
+ * (under {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY}) is still, right
+ * now in ZITADEL, the one and only live PAT on that machine user. `false`
+ * when nothing is recorded yet -- that is "unapplied," which `planAuth`
+ * already plans for without this function's help, not drift.
+ *
+ * Every real mint revokes every other PAT on the user first
+ * (`zitadel-machine-user.ts`), so "exactly one live PAT, and it is the
+ * recorded one" is never a false negative: a concurrent apply's own mint
+ * landing at any point -- before this platform's last delivery, after it, or
+ * anywhere in between -- always leaves the recorded PAT either gone or
+ * joined by one it isn't. This is what lets `provisionPlatformAuth` stop
+ * trying to catch that interleaving from inside the run that delivers the
+ * token (round 2's check-after, round 3's check-before-every-write, each
+ * confirmed by review to still leave a window): whichever run's write
+ * actually won, the next plan's call here sees it and replans.
+ *
+ * #216 round 5: that ZITADEL-only check is itself not enough. Ordering that
+ * breaks it (confirmed by review): run A mints PAT a and is about to
+ * deliver; run B's own mint revokes a and mints PAT b first, delivers b to
+ * both apps, and records {b}; A's slower delivery of a then lands *last*,
+ * overwriting both apps' envs with the now-dead a, and A records {a} after
+ * B. Final state: ZITADEL's only live PAT is b, which is NOT what either
+ * record ends up naming last (a) -- so a check against ZITADEL's live PATs
+ * alone, compared only to whichever record happens to be the one read, can
+ * land on either side of this by accident. The fix is to also compare what
+ * is actually live in Coolify: `record.tokenHash` is a hash of the exact
+ * token this run itself delivered, and if what is live in Coolify right now
+ * does not hash to it, the record does not describe reality, whatever
+ * ZITADEL's PAT list says. Read fresh, every plan: a corrupted Coolify env
+ * is not something minting again fixes by itself, so if this is wrong, a
+ * later apply's own mint-and-redeliver is what actually repairs it, and the
+ * only way to know to run one is to keep checking.
+ *
+ * #216 round 5: reads the ZITADEL org id back from
+ * {@link PLATFORM_ZITADEL_ORG_SCOPE_KEY} rather than calling
+ * `zitadel.findOrCreateOrg` -- a plan must not create anything, and
+ * `findOrCreateOrg`'s name says it might. `provisionPlatformAuth` records
+ * that key itself now (mirroring `provisionPlatformArchon`), so it is always
+ * present by the time a login-client record exists to check. Any of the
+ * three ids this needs (`org`, the login app, the broker) missing is not a
+ * state this function can verify against, so it reads as drifted -- the
+ * next apply's own mint-and-deliver backfills all three.
+ *
+ * #216 round 5: wrapped in `try`/`catch` -- ZITADEL or Coolify being
+ * unreachable must read as "unknown, not drifted," the same rule
+ * `archonAccessDrifted`/`archonBrokerRegistrationDrifted` already follow and
+ * for the same reason (a plan must not fail outright over a transient read),
+ * but logged here: silently treating a real outage as healthy is a worse
+ * miss for a credential-liveness check than for Archon's own Access policy.
+ */
+async function authLoginClientDrifted(platform, auth, recordedIds) {
+    const record = parseLoginClientRecord(recordedIds[PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY]);
+    if (!record)
+        return false;
+    const orgId = recordedIds[PLATFORM_ZITADEL_ORG_SCOPE_KEY];
+    const loginAppId = recordedIds[PLATFORM_AUTH_LOGIN_SCOPE_KEY];
+    const brokerAppId = recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY];
+    if (!orgId || !loginAppId || !brokerAppId)
+        return true;
+    try {
+        const zitadel = auth.zitadelForInstance?.(`https://${platform.auth.hostname}`) ?? auth.zitadel;
+        const livePats = await zitadel.listLoginClientPats(orgId, record.userId);
+        if (livePats.length !== 1 || livePats[0] !== record.patId)
+            return true;
+        const [loginHash, brokerHash] = await Promise.all([
+            liveLoginClientTokenHash(auth.coolify, loginAppId),
+            liveLoginClientTokenHash(auth.coolify, brokerAppId),
+        ]);
+        // #216 (4th PR review): compare each side on its own. Either side can
+        // come back `undefined` -- hidden, with nothing to check it against, see
+        // `liveLoginClientTokenHash`'s own doc comment -- and that side alone
+        // reads as "unknown," the same as the outer `catch` below. But returning
+        // "not drifted" as soon as *either* side was unreadable (round 3's
+        // behavior) hid a stale token on the *other*, readable app whenever this
+        // app's own read happened to fail or come back hidden -- a readable and
+        // wrong hash must still drift even when its sibling is unknown.
+        for (const hash of [loginHash, brokerHash]) {
+            if (hash !== undefined && hash !== record.tokenHash)
+                return true;
+        }
+        return false;
+    }
+    catch (e) {
+        console.error(`platform:auth: could not check the login-client token's liveness for ZITADEL machine user ${record.userId}: ${e instanceof Error ? e.message : String(e)}`);
+        return false;
+    }
+}
+/**
+ * #216 round 5: `ZITADEL_SERVICE_USER_TOKEN`'s live value on one app, hashed
+ * -- see {@link authLoginClientDrifted}. `undefined` means "could not be
+ * read as a trustworthy value, treat as unknown" -- never a reason by itself
+ * to call the token missing.
+ *
+ * #216 (second PR review, round 2): Coolify's own `GET
+ * /applications/{uuid}/envs` response carries both `value` and `real_value`
+ * per row (its documented schema for `list-envs-by-application-uuid`), but
+ * `CoolifyPort.listEnvs`'s narrower return type (`executor.ts`, this
+ * package's own) names only `value` and `is_preview`. The real client
+ * (`@wtfalch/providers`' `CoolifyClient.listEnvs`, which does `await
+ * r.json()` and returns it as-is with no field-stripping, `coolify.ts:219-
+ * 253`) returns Coolify's full JSON row regardless of what this package's
+ * own narrower type declares, so `real_value` is present on the object at
+ * runtime to read even when absent from the declared type.
+ *
+ * #216 (4th PR review): "could not be read" has one real cause, confirmed
+ * against Coolify's own source rather than guessed -- there is no masked
+ * placeholder string anywhere in it. `routes/api.php` maps `GET
+ * /applications/{uuid}/envs` to `ApplicationsController::envs()`, which maps
+ * each row through `removeSensitiveData()`. That method calls
+ * `$env->makeVisible(['value', 'real_value'])` only when the request's
+ * `can_read_sensitive` attribute is true (set from the API token's
+ * `read:sensitive`/`root` ability), and separately calls
+ * `$env->makeHidden(['value', 'real_value'])` whenever the env var's own
+ * `is_shown_once` flag is set ("the saved value is hidden in the UI and API
+ * responses," per that flag's own API doc comment), regardless of ability.
+ * Laravel omits a `makeHidden` attribute from the JSON row entirely -- it is
+ * not present as a key, let alone populated with a placeholder string. So
+ * unreadable here never looks like `value: '••••••••'`; it looks like
+ * `found.value` and `found.real_value` both being `undefined`.
+ * `@wtfalch/providers`' own `CoolifyEnvVar` type documents a `real_value` of
+ * `null` for a genuinely empty variable (`coolify.ts:84`, "Empty variables
+ * come back as `\"\"` here and `null` in `real_value`"), which is a
+ * different, readable state -- a real, verified value (of the empty
+ * string), not a hidden one -- so only `undefined` on both counts as hidden.
+ *
+ * A wrong guess in the unsafe direction is costly here specifically: reading
+ * a hidden field as the empty string would never hash to what was recorded,
+ * so every single plan afterward would see "drift" and re-mint, revoking the
+ * one live PAT and redeploying both apps, taking sign-in down on every apply
+ * rather than the one apply a real drift deserves. So this reads as unknown
+ * (logged once, the same as `authLoginClientDrifted`'s own outer
+ * `try`/`catch` already treats a transient read failure) whenever the row
+ * exists but carries neither key.
+ */
+async function liveLoginClientTokenHash(coolify, appId) {
+    const envs = await coolify.listEnvs(appId);
+    const found = envs.find((e) => e.key === 'ZITADEL_SERVICE_USER_TOKEN' && !e.is_preview);
+    if (found && found.value === undefined && found.real_value === undefined) {
+        console.error(`platform:auth: ZITADEL_SERVICE_USER_TOKEN on Coolify app ${appId} came back with neither value nor real_value -- Coolify hides both unless the caller's token has read:sensitive/root ability, or the env var's own is_shown_once flag is set; treating its liveness as unknown rather than forcing a re-mint`);
+        return undefined;
+    }
+    const value = found?.real_value ?? found?.value;
+    return hashLoginClientToken(value ?? '');
+}
+/**
+ * #168: makes `coolify:app` keyed {@link PLATFORM_AUTH_KEY} true -- a Coolify
+ * Postgres, the ZITADEL app itself, the zitadel-login app and (#204) the
+ * sign-in broker, reached through one Cloudflare tunnel and DNS record at
+ * `platform.auth.hostname`, then (only the first time) foundry's own admin
+ * machine user, handed to {@link PlatformAuthDeps.deliverSecret}. Env values
+ * and instance settings are `wtfalch/auth`'s own `docker-compose.yml`
+ * (checked 2026-09-29), with `ZITADEL_DOMAIN`/`wtfalch.dev` replaced by this
+ * platform's own `apex`/`auth.hostname` wherever the compose named one --
+ * every other setting it leaves open (login v2 required, external port 443,
+ * TLS terminated at Cloudflare, `PASSWORDCHANGEREQUIRED` false) is kept
+ * exactly as that compose has it (#168's "Decide"). The estate's old, shared
+ * sign-in host carries nothing once this runs (#204, `WTFALCH-DEV-EXIT.md`
+ * row A4).
+ *
+ * Every part is safe to run again after a throw partway: each id is recorded
+ * (and persisted) as soon as its resource exists, each app is named and
+ * deployed on every run that needs it, and the admin key is delivered before
+ * the guard that skips the mint is recorded.
+ *
+ * Three apps, one public hostname, no separate `proxy` app: `wtfalch/auth`
+ * splits ZITADEL's API, its login UI and its broker with a built Caddy proxy
+ * container inside one docker-compose stack; foundry instead gives each app a
+ * fixed `custom_internal_name` and lets the Cloudflare tunnel itself
+ * path-route between them (`AUTH_ZITADEL_PATH_PATTERN`,
+ * `AUTH_BROKER_PATH_PATTERN`), skipping Coolify's own Traefik (which can only
+ * dispatch by `Host`, not by path) rather than provisioning a fourth Coolify
+ * resource to do the same job. No app is created with a Coolify `domains`
+ * binding for the same reason -- the tunnel reaches each one directly by its
+ * `custom_internal_name`, never through Traefik.
+ *
+ * Known gaps, left for review (#168's own "the PR stays open for William's
+ * review"):
+ * - ~~Neither the login app nor the broker ever receives
+ *   `ZITADEL_SERVICE_USER_TOKEN`.~~ Closed by #216 (building on #209/#215):
+ *   this function's own login-client block below mints a dedicated
+ *   `IAM_LOGIN_CLIENT` machine user (never the admin one, which is
+ *   `IAM_OWNER`) and delivers its token to both apps, once the broker's
+ *   other required inputs are already met.
+ * - The broker never receives `RESEND_API_TOKEN` either, so it will not start
+ *   on `AUTH_APPS` alone. `wtfalch/auth#138` moves the broker's account mail
+ *   onto held keys and `@wtfalch/mailer`; until that lands there is no held
+ *   key to read here, so this stays a plain gap rather than a wired value.
+ * - `AUTH_APPS` starts unset: the broker has nothing to serve until a
+ *   platform app registers with it ({@link provisionPlatformArchon} is the
+ *   first), so it will not start (`parseApps` throws on an empty list) until
+ *   then either. Safe to run again: the next apply that registers an app
+ *   redeploys the broker with a non-empty list.
+ * - Whoever supplies `deps.zitadel` (or `zitadelForInstance`) must hold a
+ *   bearer token for the new instance, which foundry cannot read from it.
+ *
+ * #197: a `cloudflared` connector for this tunnel is run
+ * ({@link ensureCloudflaredConnector}), so `hostname` answers.
+ */
+async function provisionPlatformAuth(context, deps) {
+    const { platform } = context;
+    const hostname = platform.auth.hostname;
+    const gitRef = platform.auth.gitRef;
+    const recorded = context.recordedIds();
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    // Records an id and writes it out now, so a crash before the step ends
+    // cannot lose a resource a provider already created.
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    let projectUuid = recorded[PLATFORM_AUTH_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await deps.coolify.findProjectByName(PLATFORM_AUTH_PROJECT);
+        projectUuid = found
+            ? found.uuid
+            : (await deps.coolify.createProject(PLATFORM_AUTH_PROJECT)).uuid;
+        await record(PLATFORM_AUTH_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- database ----------------------------------------------------------
+    let dbId = recorded[PLATFORM_AUTH_DB_SCOPE_KEY];
+    // A database ZITADEL has already run against may hold data encrypted with a
+    // masterkey this run cannot see (see `ensureMasterkey`). A database that
+    // exists but was never deployed against (a throw between its create and the
+    // first deploy) is still empty, so a retry may generate the key.
+    const databaseInUse = Boolean(dbId && recorded[PLATFORM_AUTH_ZITADEL_DEPLOYED_SCOPE_KEY]);
+    if (!dbId) {
+        const server = await resolvePlatformServer(deps.coolify);
+        const created = await deps.coolify.createPostgresDatabase({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            name: PLATFORM_AUTH_DB_NAME,
+            postgres_db: 'zitadel',
+            postgres_user: 'zitadel',
+        });
+        dbId = created.uuid;
+        await record(PLATFORM_AUTH_DB_SCOPE_KEY, dbId);
+    }
+    const db = await deps.coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        // Static config check before either app is touched (`diff.ts`'s
+        // `coolifyCalls` follows the same rule for its own databases): Coolify
+        // can take a moment to report a freshly created database's
+        // `internal_db_url`, so the next apply retries from a clean state.
+        throw new Error('coolify:app for the platform (auth): the database has no internal_db_url yet -- retry this apply once Coolify reports one');
+    }
+    // ---- the ZITADEL app itself ---------------------------------------------
+    const zitadelApp = await findOrCreatePlatformApp(deps.coolify, PLATFORM_AUTH_ZITADEL_APP_NAME, environment, async () => {
+        const server = await resolvePlatformServer(deps.coolify);
+        return deps.coolify.createDockerImageApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            docker_registry_image_name: AUTH_ZITADEL_IMAGE,
+            docker_registry_image_tag: AUTH_ZITADEL_IMAGE_TAG,
+            ports_exposes: AUTH_ZITADEL_PORT,
+            name: PLATFORM_AUTH_ZITADEL_APP_NAME,
+            description: `ZITADEL for the platform's own sign-in (#168, ${AUTH_ZITADEL_IMAGE}:${AUTH_ZITADEL_IMAGE_TAG})`,
+            instant_deploy: false,
+        });
+    });
+    const zitadelAppId = zitadelApp.appId;
+    await record(PLATFORM_AUTH_ZITADEL_SCOPE_KEY, zitadelAppId);
+    // Set on every run, not only after a create: a throw right after the
+    // create must not leave the app unnamed for good, and the tunnel addresses
+    // the app by this name. (The port cannot read the current name back, and
+    // setting the same value again is harmless.)
+    await deps.coolify.updateApplication(zitadelAppId, {
+        custom_internal_name: PLATFORM_AUTH_ZITADEL_INTERNAL_NAME,
+    });
+    // ---- the zitadel-login app -----------------------------------------------
+    const loginApp = await findOrCreatePlatformApp(deps.coolify, PLATFORM_AUTH_LOGIN_APP_NAME, environment, async () => {
+        const server = await resolvePlatformServer(deps.coolify);
+        const githubApp = await deps.coolify.requireGithubApp();
+        return deps.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: AUTH_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name: PLATFORM_AUTH_LOGIN_APP_NAME,
+            dockerfile_location: AUTH_LOGIN_DOCKERFILE,
+        });
+    });
+    const loginAppId = loginApp.appId;
+    await record(PLATFORM_AUTH_LOGIN_SCOPE_KEY, loginAppId);
+    await deps.coolify.updateApplication(loginAppId, {
+        custom_internal_name: PLATFORM_AUTH_LOGIN_INTERNAL_NAME,
+    });
+    // ---- the broker app (#204) -------------------------------------------------
+    const brokerApp = await findOrCreatePlatformApp(deps.coolify, PLATFORM_AUTH_BROKER_APP_NAME, environment, async () => {
+        const server = await resolvePlatformServer(deps.coolify);
+        const githubApp = await deps.coolify.requireGithubApp();
+        return deps.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: AUTH_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name: PLATFORM_AUTH_BROKER_APP_NAME,
+            dockerfile_location: AUTH_BROKER_DOCKERFILE,
+        });
+    });
+    const brokerAppId = brokerApp.appId;
+    await record(PLATFORM_AUTH_BROKER_SCOPE_KEY, brokerAppId);
+    await deps.coolify.updateApplication(brokerAppId, {
+        custom_internal_name: PLATFORM_AUTH_BROKER_INTERNAL_NAME,
+    });
+    // ---- env -----------------------------------------------------------------
+    // Generated once, handed straight to `bulkUpsertEnvs` and nowhere else --
+    // never returned, recorded, logged or interpolated into a thrown error, the
+    // same rule `executor.ts`'s `ensureAuthCookieSecret` follows for a value
+    // this package mints itself rather than receiving from a provider.
+    const masterkey = await ensureMasterkey(deps.coolify, zitadelAppId, databaseInUse);
+    const adminPassword = await ensureGeneratedEnv(deps.coolify, zitadelAppId, 'ZITADEL_ADMIN_PASSWORD', generateAdminPassword);
+    const zitadelEnvs = [
+        { key: 'ZITADEL_PORT', value: AUTH_ZITADEL_PORT },
+        { key: 'ZITADEL_EXTERNALDOMAIN', value: hostname },
+        { key: 'ZITADEL_EXTERNALPORT', value: '443' },
+        { key: 'ZITADEL_EXTERNALSECURE', value: 'true' },
+        { key: 'ZITADEL_TLS_ENABLED', value: 'false' },
+        { key: 'ZITADEL_DATABASE_POSTGRES_DSN', value: db.internal_db_url },
+        { key: 'ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME', value: 'zitadel-admin' },
+        { key: 'ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED', value: 'false' },
+        { key: 'ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED', value: 'true' },
+        { key: 'ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI', value: `https://${hostname}/` },
+        { key: 'ZITADEL_OIDC_DEFAULTLOGINURLV2', value: `https://${hostname}/login?authRequest=` },
+        {
+            key: 'ZITADEL_OIDC_DEFAULTLOGOUTURLV2',
+            value: `https://${hostname}/logout?post_logout_redirect=`,
+        },
+        { key: 'ZITADEL_SAML_DEFAULTLOGINURLV2', value: `https://${hostname}/login?samlRequest=` },
+        { key: 'ZITADEL_LOGSTORE_ACCESS_STDOUT_ENABLED', value: 'true' },
+    ];
+    if (masterkey)
+        zitadelEnvs.push({ key: 'ZITADEL_MASTERKEY', value: masterkey });
+    if (adminPassword)
+        zitadelEnvs.push({ key: 'ZITADEL_ADMIN_PASSWORD', value: adminPassword });
+    const loginEnvs = [
+        {
+            key: 'ZITADEL_API_URL',
+            value: `http://${PLATFORM_AUTH_ZITADEL_INTERNAL_NAME}:${AUTH_ZITADEL_PORT}`,
+        },
+        { key: 'CUSTOM_REQUEST_HEADERS', value: `Host:${hostname},X-Forwarded-Proto:https` },
+        { key: 'OTEL_NODE_RESOURCE_DETECTORS', value: 'none' },
+        { key: 'API_CACHE_CONFIG', value: '{"defaultMinutes":2,"longMinutes":5}' },
+    ];
+    // `AUTH_APPS`, `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `RESEND_API_TOKEN`
+    // are not pushed here -- this function's own doc comment, "Known gaps".
+    const brokerEnvs = [
+        {
+            key: 'ZITADEL_API_URL',
+            value: `http://${PLATFORM_AUTH_ZITADEL_INTERNAL_NAME}:${AUTH_ZITADEL_PORT}`,
+        },
+        { key: 'ZITADEL_DOMAIN', value: hostname },
+    ];
+    // Compared before the write: an env change only reaches a running
+    // container on its next deploy (`diff.ts`'s `coolifyCalls` follows the
+    // identical rule).
+    const zitadelEnvsChanged = await envsDiffer(deps.coolify, zitadelAppId, zitadelEnvs);
+    const loginEnvsChanged = await envsDiffer(deps.coolify, loginAppId, loginEnvs);
+    const brokerEnvsChanged = await envsDiffer(deps.coolify, brokerAppId, brokerEnvs);
+    await deps.coolify.bulkUpsertEnvs(zitadelAppId, zitadelEnvs);
+    await deps.coolify.bulkUpsertEnvs(loginAppId, loginEnvs);
+    await deps.coolify.bulkUpsertEnvs(brokerAppId, brokerEnvs);
+    // Deploy an app that was just created, is not running (a throw after the
+    // create left it never deployed, or it stopped), or whose envs changed.
+    if (zitadelApp.justCreated || !zitadelApp.running || zitadelEnvsChanged) {
+        await deps.coolify.deploy(zitadelAppId);
+        await record(PLATFORM_AUTH_ZITADEL_DEPLOYED_SCOPE_KEY, zitadelAppId);
+    }
+    if (loginApp.justCreated || !loginApp.running || loginEnvsChanged) {
+        await deps.coolify.deploy(loginAppId);
+    }
+    // #211: the broker's own `server.ts` refuses to start without
+    // `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `RESEND_API_TOKEN` -- deploying
+    // it without them only produces a container that crash-loops behind
+    // `/api`. The app is still created and recorded above either way, so #209
+    // and #210 (or a human, directly) have something to push the env onto;
+    // only the deploy waits.
+    // #211 round 5: `brokerDeployNeeded` is its own reason to deploy (not only
+    // alongside justCreated/running/envsChanged, none of which this function's
+    // own `brokerEnvs` write above ever touches `AUTH_APPS`): it is what
+    // catches a broker recreated under a new app id, or a crash between some
+    // other step writing `AUTH_APPS` and deploying, cases none of the other
+    // three conditions see. This function never writes `AUTH_APPS` itself
+    // (this function's own doc comment, "Known gaps"), so whatever is live now
+    // (`authAppsRaw`) is the value this deploy, if it runs, puts into effect.
+    const brokerMissingInputs = await missingBrokerInputs(deps.coolify, brokerAppId);
+    const authAppsRaw = await currentEnvValue(deps.coolify, brokerAppId, 'AUTH_APPS');
+    const recordedBrokerDeploy = parseBrokerDeployRecord(recorded[PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY]);
+    if (brokerMissingInputs.length === 0 &&
+        (brokerApp.justCreated ||
+            !brokerApp.running ||
+            brokerEnvsChanged ||
+            brokerDeployNeeded(brokerMissingInputs, brokerAppId, authAppsRaw, recordedBrokerDeploy))) {
+        await deps.coolify.deploy(brokerAppId);
+        await record(PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, brokerDeployRecordValue(brokerAppId, authAppsRaw));
+    }
+    // ---- tunnel and DNS ------------------------------------------------------
+    const existingTunnel = await deps.cloudflare.findTunnelByName(PLATFORM_AUTH_TUNNEL_NAME);
+    const tunnel = existingTunnel ?? (await deps.cloudflare.createTunnel(PLATFORM_AUTH_TUNNEL_NAME));
+    await record(PLATFORM_AUTH_TUNNEL_SCOPE_KEY, tunnel.id);
+    await deps.cloudflare.putTunnelConfig(tunnel.id, {
+        ingress: [
+            {
+                hostname,
+                path: AUTH_ZITADEL_PATH_PATTERN,
+                service: `http://${PLATFORM_AUTH_ZITADEL_INTERNAL_NAME}:${AUTH_ZITADEL_PORT}`,
+            },
+            {
+                hostname,
+                path: AUTH_BROKER_PATH_PATTERN,
+                service: `http://${PLATFORM_AUTH_BROKER_INTERNAL_NAME}:${AUTH_BROKER_PORT}`,
+            },
+            { hostname, service: `http://${PLATFORM_AUTH_LOGIN_INTERNAL_NAME}:${AUTH_LOGIN_PORT}` },
+            { service: 'http_status:404' },
+        ],
+    });
+    // ---- cloudflared connector for the tunnel above (#197) --------------------
+    // Without this, `hostname` resolves to a tunnel nothing is dialed into and
+    // answers with a Cloudflare error -- the known gap #197 closes for this
+    // step's own tunnel only (see this function's doc comment).
+    await ensureCloudflaredConnector({
+        coolify: deps.coolify,
+        cloudflare: deps.cloudflare,
+        tunnelId: tunnel.id,
+        appName: PLATFORM_AUTH_CLOUDFLARED_APP_NAME,
+        projectUuid,
+        environment,
+        resolveServer: () => resolvePlatformServer(deps.coolify),
+        recordedConnectorAppId: recorded[PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY] ?? null,
+        recordAppId: (appId) => record(PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, appId),
+    });
+    // The apex zone step records the zone id before this step runs, but it
+    // creates no record for the hostname, so it is created here.
+    const zoneId = recorded[apexZoneKey(platform.apex)] ?? (await exactZone(deps.cloudflare, platform.apex))?.id;
+    if (!zoneId) {
+        throw new Error(`platform:auth: no Cloudflare zone for ${platform.apex} to put ${hostname} in`);
+    }
+    const dnsTarget = `${tunnel.id}.cfargotunnel.com`;
+    const [dnsRecord] = await deps.cloudflare.findDnsRecord(zoneId, hostname, 'CNAME');
+    if (!dnsRecord) {
+        await deps.cloudflare.createDnsRecord(zoneId, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    else if (dnsRecord.content !== dnsTarget) {
+        await deps.cloudflare.updateDnsRecord(zoneId, dnsRecord.id, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    // ---- foundry's own admin machine user, once ------------------------------
+    if (!recorded[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY]) {
+        const lost = recorded[PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY];
+        if (lost) {
+            // The planner reports this and plans nothing; this is the same rule for
+            // a caller that reaches the step anyway.
+            throw new Error(`platform:auth: the admin key of ZITADEL machine user ${lost} was minted but never delivered; delete that user and the recorded key ${PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        // Minting needs a running instance behind the tunnel: the first apply
+        // gets here right after the deploy.
+        await waitForInstance(`https://${hostname}/.well-known/openid-configuration`, runtime, sleep);
+        const zitadel = deps.zitadelForInstance?.(`https://${hostname}`) ?? deps.zitadel;
+        const { org } = await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+        // #216 round 5: recorded here too (mirroring `provisionPlatformArchon`),
+        // so `authLoginClientDrifted` (below) never needs its own ZITADEL call
+        // to resolve the org -- see that function's own doc comment.
+        if (recorded[PLATFORM_ZITADEL_ORG_SCOPE_KEY] !== org.id) {
+            await record(PLATFORM_ZITADEL_ORG_SCOPE_KEY, org.id);
+        }
+        const { userId, token } = await zitadel.mintAdminMachineUser(org.id, {
+            userName: PLATFORM_AUTH_ADMIN_USER_NAME,
+            name: 'Foundry (platform admin)',
+        });
+        // Recorded and persisted before the token leaves this function: if
+        // delivery fails for good, the next plan reports the lost key rather than
+        // skipping or minting again. Only a delivered key records the guard.
+        await record(PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, userId);
+        // Handed off once, right here, before returning -- never in the return
+        // value, `serviceIds`, the store, a log or a thrown error (see
+        // `FoundryStepExecutorPorts.deliverSecret`'s own doc comment). The error
+        // below names the user id only, never the token or the cause.
+        const attempts = runtime.deliverAttempts ?? 3;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await deps.deliverSecret('zitadel:platform:admin', token);
+                break;
+            }
+            catch {
+                if (attempt >= attempts) {
+                    throw new Error(`platform:auth: the admin key of ZITADEL machine user ${userId} was minted but could not be delivered after ${attempts} tries`);
+                }
+                await sleep(1000 * attempt);
+            }
+        }
+        await record(PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, userId);
+    }
+    // ---- foundry's own login-client machine user, once (#216, building on #209/#215) --
+    // The login app and the broker both refuse to start without
+    // `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` (this function's own doc comment,
+    // "Known gaps") -- the admin token above must never go there (it is
+    // `IAM_OWNER`), so this mints a second, narrower machine user
+    // (`IAM_LOGIN_CLIENT` only) and delivers its token into both apps' own
+    // envs, then redeploys both.
+    //
+    // Deferred, not blocked, while the broker's other required inputs
+    // (`RESEND_API_TOKEN`, `AUTH_APPS`) are still missing (composing with
+    // #211's own gating): minting and delivering here would only redeploy a
+    // broker that still refuses to start on the other missing input, spending
+    // a mint and two deploys on nothing this apply can fix. `blockedSteps`'s
+    // own `missingBrokerInputs` read already names what is still missing; once
+    // the other inputs land (#210, or Archon's own registration for
+    // `AUTH_APPS`), a later apply's fresh read of `brokerMissingInputs` clears
+    // this gate and this block runs.
+    //
+    // Unlike the admin key above, an undelivered login-client key never blocks
+    // planning or throws a "delete this user by hand" error -- #216's own fix
+    // for the bug PR #215 shipped with, which mirrored the admin pair's
+    // forever-blocking behaviour here too. Revoking a stale login-client PAT
+    // destroys nothing (unlike ZITADEL's own masterkey, nothing else was ever
+    // encrypted with it), so `mintLoginClientMachineUser`
+    // (`zitadel-machine-user.ts`) always lists and deletes every PAT the user
+    // already holds before minting a fresh one. A crash between mint and
+    // record, or every delivery retry failing, both leave this `if` still true
+    // on the next run, which re-mints (revoking the stale PAT first) and
+    // retries delivery, with no manual step.
+    //
+    // #216 round 2 and round 3 each tried to catch a concurrent apply's own
+    // mint (idempotent revoke-then-create on the same `userName`) racing this
+    // one -- round 2 checked liveness once, after every write; round 3 checked
+    // again before every write, inside each retry. Review confirmed each still
+    // left a window: a write that lands between the last check this run makes
+    // and the very next network call is never caught by either. #216 round 4
+    // drops both: this block no longer tries to detect the race from inside
+    // the run that might lose it. It mints, delivers with ordinary retries,
+    // and records whatever it actually delivered -- the user id *and* the
+    // exact PAT id (`loginClientRecordValue`). `planAuth` (`platform-diff.ts`)
+    // re-checks that recorded PAT against ZITADEL's live state on *every*
+    // plan, not only this run's: whichever run's write actually won is caught
+    // on the very next plan and replanned, however the writes interleaved.
+    // See `authLoginClientDrifted`'s own doc comment for why that check can
+    // never read a healthy delivery as drifted.
+    //
+    // Read fresh here, immediately before deciding whether to mint -- not
+    // `recorded`, the snapshot this function took at the top, several hundred
+    // lines above. A concurrent apply's own mint-deliver-record can land in
+    // that gap; deciding off a stale snapshot would mint and redeliver on top
+    // of a token another run just finished setting up.
+    //
+    // A record present is still not enough on its own: `planAuth` may have
+    // replanned this step because `authLoginClientDrifted` (the same check,
+    // reused here) found the recorded PAT no longer live -- this run has to
+    // make the same call, not just trust that a record exists, or a drifted
+    // platform would be planned again forever without ever actually healing.
+    const loginClientOtherInputsMissing = brokerMissingInputs.filter((m) => m !== 'ZITADEL_SERVICE_USER_TOKEN');
+    const freshRecordedIds = context.recordedIds();
+    const freshLoginClientRecord = parseLoginClientRecord(freshRecordedIds[PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY]);
+    const loginClientNeedsMint = !freshLoginClientRecord || (await authLoginClientDrifted(platform, deps, freshRecordedIds));
+    if (loginClientNeedsMint && loginClientOtherInputsMissing.length === 0) {
+        const loginClientZitadel = deps.zitadelForInstance?.(`https://${hostname}`) ?? deps.zitadel;
+        const { org: loginClientOrg } = await loginClientZitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+        // #216 round 5: backfills the org id for a platform whose admin block
+        // (above) ran before this recording existed and has not run since --
+        // see `authLoginClientDrifted`'s own doc comment.
+        if (freshRecordedIds[PLATFORM_ZITADEL_ORG_SCOPE_KEY] !== loginClientOrg.id) {
+            await record(PLATFORM_ZITADEL_ORG_SCOPE_KEY, loginClientOrg.id);
+        }
+        const { userId: loginClientUserId, token: loginClientToken, patId: loginClientPatId, revokedPriorPat, } = await loginClientZitadel.mintLoginClientMachineUser(loginClientOrg.id, {
+            userName: PLATFORM_AUTH_LOGIN_CLIENT_USER_NAME,
+            name: 'Foundry (platform login client)',
+        });
+        // Recorded and persisted before the token leaves this function -- the
+        // same "one mint" rule the admin block above follows. Never read back to
+        // block planning; `planAuth` (`platform-diff.ts`) reads it only to
+        // surface a non-blocking note, for the reason this block's own doc
+        // comment above gives.
+        await record(PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, loginClientUserId);
+        const deliverAttempts = runtime.deliverAttempts ?? 3;
+        try {
+            await retryPlatformAuthCall(deliverAttempts, sleep, () => deps.coolify.bulkUpsertEnvs(loginAppId, [
+                { key: 'ZITADEL_SERVICE_USER_TOKEN', value: loginClientToken },
+            ]));
+            await retryPlatformAuthCall(deliverAttempts, sleep, () => deps.coolify.bulkUpsertEnvs(brokerAppId, [
+                { key: 'ZITADEL_SERVICE_USER_TOKEN', value: loginClientToken },
+            ]));
+            // Forced: an unforced deploy answers 200 "skipped" when one for the
+            // same commit is already queued -- likely here, since this function's
+            // own deploys above may just have queued one for either app. An
+            // ignored "skipped" would let this function record delivery as
+            // succeeded while the running containers never actually see the token
+            // (#216 follow-up review, item 2).
+            await retryPlatformAuthCall(deliverAttempts, sleep, () => deps.coolify.deploy(loginAppId, true));
+            await retryPlatformAuthCall(deliverAttempts, sleep, () => deps.coolify.deploy(brokerAppId, true));
+        }
+        catch {
+            // Never echo the underlying error: Coolify's validation error can
+            // include the rejected env value -- the token itself -- in its
+            // message (#216 follow-up review, item 1). Name the user id only,
+            // never the token or the cause. Nothing records delivered, so the
+            // next apply re-mints (revoking whatever is live) and re-delivers.
+            //
+            // #216 (second PR review, round 2; third PR review, nit): on a
+            // re-mint, `mintLoginClientMachineUser` already revoked this user's
+            // prior PAT before minting the one that just failed to deliver -- see
+            // this file's own doc comment above and `zitadel-machine-user.ts`'s
+            // revoke-before-mint sweep. So on that path the login app and broker
+            // are not merely stale, they are down: neither has any live token
+            // until a later apply mints and delivers a fresh one. `revokedPriorPat`
+            // is false on a first-ever mint, where nothing was live to revoke --
+            // saying "its prior token was already revoked" there would describe a
+            // revoke that never happened, so the message only says so when it did.
+            throw new Error(revokedPriorPat
+                ? `platform:auth: the login-client token of ZITADEL machine user ${loginClientUserId} could not be delivered after ${deliverAttempts} tries; its prior token was already revoked, so the login app and broker are down until a later apply mints and delivers a fresh one`
+                : `platform:auth: the login-client token of ZITADEL machine user ${loginClientUserId} could not be delivered after ${deliverAttempts} tries; this is its first token, so the login app and broker still have none until a later apply mints and delivers one`);
+        }
+        // #216 round 4/5: records what was actually delivered -- the user id,
+        // the exact PAT id, and (round 5) a hash of the exact token -- so the
+        // next plan's `authLoginClientDrifted` check can tell a healthy delivery
+        // from one a concurrent apply has since clobbered, including the
+        // ordering round 4's own check alone could not catch. See this block's
+        // own doc comment, and `authLoginClientDrifted`'s, for why.
+        await record(PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, loginClientRecordValue(loginClientUserId, loginClientPatId, loginClientToken));
+    }
+    return { resourceId: zitadelAppId };
+}
+// ---------------------------------------------------------------------------
+// #169: the platform's own mail server (Stalwart)
+// ---------------------------------------------------------------------------
+const PLATFORM_MAIL_PROJECT = 'platform';
+const PLATFORM_MAIL_APP_NAME = 'platform-mail-stalwart';
+const PLATFORM_MAIL_INTERNAL_NAME = 'platform-mail-stalwart';
+const PLATFORM_MAIL_TUNNEL_NAME = 'platform-mail-tunnel';
+/** #197: the one Coolify app that runs `cloudflared` for {@link PLATFORM_MAIL_TUNNEL_NAME}. */
+const PLATFORM_MAIL_CLOUDFLARED_APP_NAME = 'platform-mail-cloudflared';
+/**
+ * `stalw.art/docs/install/docker`: the official image. `platform.mail.gitRef`
+ * carries its tag -- `platform.ts`'s `PlatformService.gitRef` doc comment
+ * ("the release it runs") holds for an image tag too, and Stalwart has no
+ * repo of its own to build from the way the login app does.
+ */
+const STALWART_IMAGE = 'stalwartlabs/stalwart';
+const STALWART_HTTP_PORT = '8080';
+/**
+ * SMTP (25), submission (587) and submissions (465) -- the three ports
+ * #169's own "Human steps" names. IMAP/POP3/ManageSieve are left off:
+ * nothing in this estate speaks them to Stalwart directly yet, and every
+ * port opened here is one Coolify's host firewall must also open.
+ */
+const STALWART_SMTP_PORTS = ['25', '465', '587'];
+const STALWART_PORTS_EXPOSES = [STALWART_HTTP_PORT, ...STALWART_SMTP_PORTS].join(',');
+/**
+ * `host:container`, comma separated (`CoolifyPort.createDockerImageApplication`'s
+ * own doc comment: "a mail server cannot do without" this). The HTTP port is
+ * not here -- it stays behind the tunnel, exactly like `platform:auth`'s
+ * ZITADEL/login apps.
+ */
+const STALWART_PORTS_MAPPINGS = STALWART_SMTP_PORTS.map((p) => `${p}:${p}`).join(',');
+const STALWART_DATA_MOUNT = '/opt/stalwart';
+/** `STALWART_RECOVERY_ADMIN=<user>:<password>` -- the fixed recovery account name; only the password half is generated. */
+const STALWART_RECOVERY_USER = 'admin';
+/**
+ * Stalwart's unauthenticated readiness endpoint (200 once its data store is
+ * up; `crates/http/src/request.rs`'s `healthz` route in v0.16.24). Not
+ * `/.well-known/jmap`, which answers 401 to a client with no credentials.
+ */
+const STALWART_READY_PATH = '/healthz/ready';
+/** Where the server the app was created on is recorded, so the MX record follows the app, not a later pick. */
+const PLATFORM_MAIL_SERVER_SCOPE_KEY = 'coolify_platform_mail_server';
+const PLATFORM_MAIL_PROJECT_SCOPE_KEY = 'coolify_project_platform_mail';
+const PLATFORM_MAIL_APP_SCOPE_KEY = 'coolify_platform_mail_app';
+const PLATFORM_MAIL_TUNNEL_SCOPE_KEY = 'cloudflare_platform_mail_tunnel';
+/**
+ * Recorded once the app has been deployed at least once -- same role as
+ * `PLATFORM_AUTH_ZITADEL_DEPLOYED_SCOPE_KEY`, kept for parity though nothing
+ * here reads it back the way `ensureMasterkey` does: losing
+ * `STALWART_RECOVERY_ADMIN` is not destructive the same way losing ZITADEL's
+ * masterkey is.
+ */
+const PLATFORM_MAIL_DEPLOYED_SCOPE_KEY = 'stalwart_platform_mail_deployed';
+/**
+ * The hostname and image tag the last successful deploy used, recorded right
+ * after that deploy. `provisionPlatformMail` reads these (not the applied keys
+ * the planner reads, which stay last) to decide on a redeploy, so a retry after
+ * a later failure does not stop the running server again.
+ */
+const PLATFORM_MAIL_DEPLOYED_HOSTNAME_SCOPE_KEY = 'mail_deployed_hostname';
+const PLATFORM_MAIL_DEPLOYED_GIT_REF_SCOPE_KEY = 'mail_deployed_git_ref';
+/**
+ * The fixed description Stalwart's admin API key is minted under
+ * (`StalwartClient.createApiKey`'s own signature returns only the secret,
+ * never an id) -- what a human revokes it by in Stalwart's own admin UI if
+ * it is ever lost between mint and delivery, and what
+ * {@link PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY} records in that case.
+ */
+export const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = 'foundry:platform:admin';
+/**
+ * #169: makes `coolify:app` keyed {@link PLATFORM_MAIL_KEY} true -- Stalwart
+ * on Coolify with its own persistent storage, reached at
+ * `platform.mail.hostname` through a Cloudflare tunnel for web, JMAP and its
+ * management API (mirroring #168's ZITADEL/login apps: TLS terminated at
+ * Cloudflare, plain HTTP behind the tunnel) and at `mx.<apex>` over a direct,
+ * unproxied `A` record to the Coolify server's own address for SMTP -- raw
+ * SMTP cannot ride Cloudflare's HTTP-only tunnel the way a web app does,
+ * which is exactly why #169's own "Human steps" asks a person to open ports
+ * 25, 465 and 587 on that server's host firewall. Then, once the instance
+ * answers, the OIDC directory against the platform's own sign-in and
+ * foundry's admin API key, minted once and handed to
+ * {@link PlatformMailDeps.deliverSecret}.
+ *
+ * Every part is safe to run again after a throw partway, the same rules
+ * {@link provisionPlatformAuth} follows: each id is recorded (and persisted)
+ * as soon as its resource exists, the app is deployed on every run that
+ * needs it, and the admin key is delivered before the guard that skips the
+ * mint is recorded. Unlike ZITADEL's `ZITADEL_ADMIN_PASSWORD`, the recovery
+ * credential this step generates (`STALWART_RECOVERY_ADMIN`) is read back
+ * from Coolify's own env store on every run rather than held only in memory
+ * -- `CoolifyPort.listEnvs`'s own doc comment says these values come back
+ * live -- so a retry after a delivery failure re-authenticates with the same
+ * credential instead of losing it.
+ *
+ * **Why not `@wtfalch/email/postmaster`'s `mailObjects`/`applyObjects`**, the
+ * instance-bootstrap helper `wtfalch-manage` already uses for the hand-built
+ * `mail.wtfalch.dev`: that plan also wires an `AcmeProvider` and `DnsServer`
+ * for Stalwart's own DNS-01 ACME challenge, and an `MtaRoute` that relays
+ * every outbound message through Resend -- the estate moved transactional
+ * mail off Resend onto Lettermint before this issue (`@wtfalch/mailer` ADR
+ * 0006), and this step provisions no Cloudflare DNS token for Stalwart's own
+ * ACME either. Calling it as-is would mint an outbound relay this platform
+ * does not want and a credential requirement this issue does not cover, so
+ * {@link PlatformMailAdminPort.applySettings} is a narrower, hand-built
+ * settings write instead: the default hostname and the OIDC directory only.
+ *
+ * Known gaps, left for review (like #168's own "the PR stays open for
+ * William's review"):
+ * - **No ACME/TLS for the SMTP listener.** `mx.<apex>` answers with
+ *   Stalwart's own self-signed certificate until a follow-up wires a real
+ *   one (`mailObjects`'s `AcmeProvider`/`DnsServer` shape, minus the Resend
+ *   relay it also carries).
+ * - **`oidcAudience` is supplied, not resolved.** #168 mints foundry's own
+ *   ZITADEL admin machine user but registers no resource API for Stalwart's
+ *   access-token `aud` check; whoever supplies
+ *   {@link PlatformMailDeps.oidcAudience} must have registered one by hand
+ *   until that is built.
+ * - **The Lettermint team token the org app step reads still comes from
+ *   wherever the host already reads it, not held keys.** Needs
+ *   `StepExecutionContext` to carry the platform, which `plan-apply.ts`'s
+ *   own doc comment already scoped out of #167 as more than a small change
+ *   -- a follow-up issue, not this one. (#205 removed the org step
+ *   `coolify:mail`'s own fallback to the hand-built `wtfalch.dev`
+ *   instance -- `diff.ts`'s `planMail` already blocks the step until the
+ *   platform's own mail is applied, so the fallback only ever served a
+ *   plan recorded before that, and now fails loudly instead.)
+ */
+async function provisionPlatformMail(context, deps) {
+    const { platform } = context;
+    const hostname = platform.mail.hostname;
+    const mailHost = platformMailMxHost(platform.apex);
+    const imageTag = platform.mail.gitRef;
+    const recorded = context.recordedIds();
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    let projectUuid = recorded[PLATFORM_MAIL_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await deps.coolify.findProjectByName(PLATFORM_MAIL_PROJECT);
+        projectUuid = found
+            ? found.uuid
+            : (await deps.coolify.createProject(PLATFORM_MAIL_PROJECT)).uuid;
+        await record(PLATFORM_MAIL_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- the Stalwart app itself ---------------------------------------------
+    const imageTagBlocked = mailImageTagBlocked(imageTag);
+    if (imageTagBlocked)
+        throw new Error(imageTagBlocked);
+    // One server for both the app and the MX record: recorded the first time,
+    // read back after, so a later run never points `mx.<apex>` somewhere the
+    // app is not.
+    const server = await resolveMailServer(deps.coolify, recorded[PLATFORM_MAIL_SERVER_SCOPE_KEY]);
+    await record(PLATFORM_MAIL_SERVER_SCOPE_KEY, server.uuid);
+    const serverIpBlocked = mailServerIpBlocked(server.ip);
+    if (serverIpBlocked)
+        throw new Error(serverIpBlocked);
+    const app = await findOrCreatePlatformApp(deps.coolify, PLATFORM_MAIL_APP_NAME, environment, async () => {
+        return deps.coolify.createDockerImageApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            docker_registry_image_name: STALWART_IMAGE,
+            docker_registry_image_tag: imageTag,
+            ports_exposes: STALWART_PORTS_EXPOSES,
+            ports_mappings: STALWART_PORTS_MAPPINGS,
+            name: PLATFORM_MAIL_APP_NAME,
+            description: `Stalwart for the platform's own mail (#169, ${STALWART_IMAGE}:${imageTag})`,
+            instant_deploy: false,
+        });
+    });
+    const appId = app.appId;
+    await record(PLATFORM_MAIL_APP_SCOPE_KEY, appId);
+    // Set on every run, not only after a create -- same rule `provisionPlatformAuth` follows for its own apps.
+    // The image tag too: a declared release change reaches the app here.
+    await deps.coolify.updateApplication(appId, {
+        custom_internal_name: PLATFORM_MAIL_INTERNAL_NAME,
+        docker_registry_image_tag: imageTag,
+    });
+    // #177: org steps (an org's own `coolify:mail`/`coolify:agora`) read this
+    // back instead of a literal, the same way files/ai's own internal
+    // addresses are recorded.
+    await record(PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, `http://${PLATFORM_MAIL_INTERNAL_NAME}:${STALWART_HTTP_PORT}`);
+    // ---- storage ---------------------------------------------------------------
+    const storages = await deps.coolify.listStorages(appId);
+    const hasDataVolume = (storages.persistent_storages ?? []).some((s) => s.mount_path === STALWART_DATA_MOUNT);
+    if (!hasDataVolume) {
+        await deps.coolify.createPersistentStorage(appId, {
+            name: `${PLATFORM_MAIL_APP_NAME}-data`,
+            mount_path: STALWART_DATA_MOUNT,
+        });
+    }
+    // ---- env ---------------------------------------------------------------------
+    // Generated once; unlike ZITADEL's masterkey this is never re-derived from
+    // "is the database already in use", because losing it is not destructive
+    // the same way -- worst case a later apply cannot read it back and the
+    // admin-key mint below throws, naming exactly that.
+    const recoveryGenerated = await ensureGeneratedEnv(deps.coolify, appId, 'STALWART_RECOVERY_ADMIN', () => `${STALWART_RECOVERY_USER}:${randomBytes(18).toString('base64')}`);
+    const envs = [
+        { key: 'STALWART_PUBLIC_URL', value: `https://${hostname}` },
+    ];
+    if (recoveryGenerated)
+        envs.push({ key: 'STALWART_RECOVERY_ADMIN', value: recoveryGenerated });
+    const envsChanged = await envsDiffer(deps.coolify, appId, envs);
+    await deps.coolify.bulkUpsertEnvs(appId, envs);
+    const declaredChanged = recorded[PLATFORM_MAIL_DEPLOYED_HOSTNAME_SCOPE_KEY] !== hostname ||
+        recorded[PLATFORM_MAIL_DEPLOYED_GIT_REF_SCOPE_KEY] !== imageTag;
+    if (app.justCreated || !app.running || envsChanged || declaredChanged) {
+        // A container still up from before would answer the readiness probe with
+        // the old deployment's health. Stop it and see it stopped first, so the
+        // wait below only ever reads the new deployment.
+        if (!app.justCreated && app.running) {
+            await deps.coolify.raw('POST', `/applications/${appId}/stop`);
+            await waitForMailStopped(deps.coolify, appId, runtime, sleep);
+        }
+        await deps.coolify.deploy(appId);
+        await record(PLATFORM_MAIL_DEPLOYED_SCOPE_KEY, appId);
+        // Right after the deploy, so a later failure (tunnel, DNS, readiness,
+        // settings, mint) does not make the next run stop and redeploy the app.
+        await record(PLATFORM_MAIL_DEPLOYED_HOSTNAME_SCOPE_KEY, hostname);
+        await record(PLATFORM_MAIL_DEPLOYED_GIT_REF_SCOPE_KEY, imageTag);
+    }
+    // ---- tunnel and DNS: web/JMAP/management ------------------------------------
+    const existingTunnel = await deps.cloudflare.findTunnelByName(PLATFORM_MAIL_TUNNEL_NAME);
+    const tunnel = existingTunnel ?? (await deps.cloudflare.createTunnel(PLATFORM_MAIL_TUNNEL_NAME));
+    await record(PLATFORM_MAIL_TUNNEL_SCOPE_KEY, tunnel.id);
+    await deps.cloudflare.putTunnelConfig(tunnel.id, {
+        ingress: [
+            { hostname, service: `http://${PLATFORM_MAIL_INTERNAL_NAME}:${STALWART_HTTP_PORT}` },
+            { service: 'http_status:404' },
+        ],
+    });
+    // #197: without a connector, `hostname` answers with a Cloudflare error.
+    await ensureCloudflaredConnector({
+        coolify: deps.coolify,
+        cloudflare: deps.cloudflare,
+        tunnelId: tunnel.id,
+        appName: PLATFORM_MAIL_CLOUDFLARED_APP_NAME,
+        projectUuid,
+        environment,
+        // The Stalwart app's own server, so the connector shares its Docker network.
+        resolveServer: async () => server,
+        recordedConnectorAppId: recorded[PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY] ?? null,
+        recordAppId: (appId) => record(PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, appId),
+    });
+    const zoneId = recorded[apexZoneKey(platform.apex)] ?? (await exactZone(deps.cloudflare, platform.apex))?.id;
+    if (!zoneId) {
+        throw new Error(`platform:mail: no Cloudflare zone for ${platform.apex} to put ${hostname} in`);
+    }
+    const dnsTarget = `${tunnel.id}.cfargotunnel.com`;
+    const [dnsRecord] = await deps.cloudflare.findDnsRecord(zoneId, hostname, 'CNAME');
+    if (!dnsRecord) {
+        await deps.cloudflare.createDnsRecord(zoneId, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    else if (dnsRecord.content !== dnsTarget) {
+        await deps.cloudflare.updateDnsRecord(zoneId, dnsRecord.id, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    // ---- the MX hostname: a direct, unproxied A record --------------------------
+    const serverIp = server.ip; // checked by mailServerIpBlocked above
+    const [mxRecord] = await deps.cloudflare.findDnsRecord(zoneId, mailHost, 'A');
+    if (!mxRecord) {
+        await deps.cloudflare.createDnsRecord(zoneId, {
+            type: 'A',
+            name: mailHost,
+            content: serverIp,
+            proxied: false,
+        });
+    }
+    else if (mxRecord.content !== serverIp) {
+        await deps.cloudflare.updateDnsRecord(zoneId, mxRecord.id, {
+            type: 'A',
+            name: mailHost,
+            content: serverIp,
+            proxied: false,
+        });
+    }
+    // ---- OIDC directory and foundry's own admin API key, once --------------------
+    if (!recorded[PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY]) {
+        const lost = recorded[PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY];
+        if (lost) {
+            throw new Error(`platform:mail: an admin API key ("${lost}") was minted but never delivered; revoke it in Stalwart and remove the recorded key ${PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        await waitForMailInstance(`https://${hostname}${STALWART_READY_PATH}`, runtime, sleep);
+        const recoveryEnv = (await deps.coolify.listEnvs(appId)).find((e) => e.key === 'STALWART_RECOVERY_ADMIN' && !e.is_preview);
+        if (!recoveryEnv) {
+            throw new Error('platform:mail: STALWART_RECOVERY_ADMIN is not set on the app; cannot authenticate to mint the admin key');
+        }
+        const password = recoveryEnv.value.slice(`${STALWART_RECOVERY_USER}:`.length);
+        try {
+            const admin = deps.stalwartForInstance({
+                url: `https://${hostname}`,
+                user: STALWART_RECOVERY_USER,
+                password,
+            });
+            await admin.applySettings({
+                mailHost,
+                oidc: { issuerUrl: `https://${platform.auth.hostname}`, audience: deps.oidcAudience },
+            });
+            // Recorded and persisted before the secret leaves this function: if
+            // delivery fails for good, the next plan reports the lost key rather
+            // than skipping or minting again.
+            await record(PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION);
+            const secret = await admin.createApiKey(PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, 'inherit');
+            const attempts = runtime.deliverAttempts ?? 3;
+            for (let attempt = 1;; attempt += 1) {
+                try {
+                    await deps.deliverSecret('stalwart:platform:admin', secret);
+                    break;
+                }
+                catch {
+                    if (attempt >= attempts) {
+                        throw new Error(`platform:mail: the admin API key ("${PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION}") was minted but could not be delivered after ${attempts} tries`);
+                    }
+                    await sleep(1000 * attempt);
+                }
+            }
+            await record(PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, appId);
+        }
+        catch (error) {
+            throw redactedMailError(error, [password]);
+        }
+    }
+    // Last, after every write the applied values depend on, so a run that
+    // failed halfway plans again.
+    await record(PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    await record(PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, imageTag);
+    return { resourceId: appId };
+}
+/** Why the Stalwart image tag cannot be used, or `null`. A floating tag cannot be re-pulled by comparing tags. */
+function mailImageTagBlocked(tag) {
+    if (tag.trim() === '' || tag.trim().toLowerCase() === 'latest') {
+        return `the platform's mail server is blocked, not planned: the Stalwart image tag "${tag}" floats; declare a pinned release (for example v0.16.24) as the mail gitRef`;
+    }
+    return null;
+}
+/** Why the server's address cannot be the MX A record's content, or `null`. */
+function mailServerIpBlocked(ip) {
+    if (!ip) {
+        return "the platform's mail server is blocked, not planned: the Coolify server reports no ip, so mx.<apex> has no address to point at; set the server's IP in Coolify";
+    }
+    if (!isIPv4(ip)) {
+        return `the platform's mail server is blocked, not planned: the Coolify server's ip "${ip}" is not an IPv4 address, so it cannot be the mx.<apex> A record; set the server's public IPv4 in Coolify`;
+    }
+    return null;
+}
+/** The recorded server when one is recorded and still listed, else the platform's usual pick. */
+async function resolveMailServer(coolify, recordedUuid) {
+    if (!recordedUuid)
+        return resolvePlatformServer(coolify);
+    const server = (await coolify.listServers()).find((s) => s.uuid === recordedUuid);
+    if (!server) {
+        throw new Error(`platform:mail: the Coolify server ${recordedUuid} the mail app was created on is no longer listed`);
+    }
+    return server;
+}
+/**
+ * The mail step's own reasons it cannot run yet, as fixed text: missing
+ * dependencies or audience, a floating image tag, a server with no usable
+ * address. Skipped once the step is applied at the declared values, so a
+ * live app is not blocked by a later Coolify change to the server's address.
+ */
+async function mailBlockedReason(platform, mail, recordedIds) {
+    if (!mail) {
+        return "the platform's mail server is blocked, not planned: the host built the platform executor without its mail dependencies";
+    }
+    if (recordedIds[`coolify:app:${PLATFORM_MAIL_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]) {
+        return null;
+    }
+    if (!mail.oidcAudience || mail.oidcAudience.trim() === '') {
+        return "the platform's mail server is blocked, not planned: the host supplies no oidcAudience, the ZITADEL resource id Stalwart's OIDC directory checks access tokens against";
+    }
+    const tagBlocked = mailImageTagBlocked(platform.mail.gitRef);
+    if (tagBlocked)
+        return tagBlocked;
+    try {
+        const server = await resolveMailServer(mail.coolify, recordedIds[PLATFORM_MAIL_SERVER_SCOPE_KEY]);
+        return mailServerIpBlocked(server.ip);
+    }
+    catch {
+        return "the platform's mail server is blocked, not planned: no usable Coolify server could be resolved for it";
+    }
+}
+/**
+ * #211: the broker cannot start without `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`,
+ * `RESEND_API_TOKEN` and `AUTH_APPS`. `provisionPlatformAuth` already skips
+ * deploying the broker while any is missing ({@link missingBrokerInputs});
+ * this is the same check surfaced through `blockedSteps`, so a plan says
+ * why, by name, rather than the broker simply sitting undeployed with no
+ * explanation. `null` while there is no broker app id recorded yet (nothing
+ * to check) or every input is present.
+ *
+ * #211 round 3: wraps the live read the way {@link mailBlockedReason} wraps
+ * its own Coolify call -- a transient `listEnvs` failure must report a
+ * blocked reason naming the broker app id, never throw out of
+ * `blockedSteps` and take the rest of the plan down with it.
+ *
+ * #211 round 5 addendum: when `AUTH_APPS` is the reason, names which problem
+ * it actually is ({@link authAppsProblem}) instead of always saying "it has
+ * no ... AUTH_APPS yet" -- that wording is only true when nothing has been
+ * set; a present-but-invalid value is a different failure (a person needs to
+ * go fix an entry, not merely wait for one of #209/#210/Archon's own
+ * registration to supply one), and reporting it identically hid which one
+ * was true.
+ */
+async function authBrokerBlockedReason(auth, recordedIds) {
+    const brokerAppId = recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY];
+    if (!brokerAppId)
+        return { reason: null, otherInputsMissing: [] };
+    let missing;
+    let authAppsRaw;
+    try {
+        missing = await missingBrokerInputs(auth.coolify, brokerAppId);
+        authAppsRaw = await currentEnvValue(auth.coolify, brokerAppId, 'AUTH_APPS');
+    }
+    catch {
+        return {
+            reason: `the platform's sign-in broker ${brokerAppId} is blocked, not deployed: its live env could not be read`,
+            // #216 round 5: unreadable, not "known missing" -- `planAuth` must not
+            // assume the login-client mint is blocked by anything in particular.
+            otherInputsMissing: [],
+        };
+    }
+    // #216 round 5: what `provisionPlatformAuth`'s own `loginClientOtherInputsMissing`
+    // gate is -- see `planAuth`'s own doc comment for why it needs this too.
+    const otherInputsMissing = missing.filter((m) => m !== 'ZITADEL_SERVICE_USER_TOKEN');
+    if (missing.length === 0)
+        return { reason: null, otherInputsMissing };
+    if (authAppsProblem(authAppsRaw, brokerAppId) === 'malformed') {
+        const otherMissing = missing.filter((m) => m !== 'AUTH_APPS');
+        const otherSuffix = otherMissing.length > 0
+            ? `, and it has no ${otherMissing.join(' and no ')} yet (#209, #210)`
+            : '';
+        return {
+            reason: `the platform's sign-in broker ${brokerAppId} is blocked, not deployed: its AUTH_APPS is malformed${otherSuffix}`,
+            otherInputsMissing,
+        };
+    }
+    // AUTH_APPS isn't gated on #209/#210 the way the two tokens are; only cite
+    // those issues when one of them is actually among what's missing.
+    const suffix = missing.some((m) => m !== 'AUTH_APPS') ? ' (#209, #210)' : '';
+    return {
+        reason: `the platform's sign-in broker is created but not deployed, blocked: it has no ${missing.join(' and no ')} yet${suffix}`,
+        otherInputsMissing,
+    };
+}
+/** Polls until Coolify reports the mail app stopped, so a healthy answer read afterwards is the new deployment's. */
+async function waitForMailStopped(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? 300_000;
+    const interval = runtime.readyIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        if (!status || !isRunningOrStarting(status))
+            return;
+        if (now() >= deadline) {
+            throw new Error(`platform:mail: the Stalwart app ${appId} did not stop within ${Math.round(timeout / 1000)}s (last status ${status ?? 'unknown'}); apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/** Polls `url` until it answers 2xx, or throws once `readyTimeoutMs` has passed. */
+async function waitForMailInstance(url, runtime, sleep) {
+    const fetchImpl = runtime.fetch ?? globalThis.fetch;
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? 300_000;
+    const interval = runtime.readyIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        try {
+            const response = await fetchImpl(url);
+            if (response.ok)
+                return;
+        }
+        catch {
+            // Not up yet: DNS, the tunnel or the container.
+        }
+        if (now() >= deadline) {
+            throw new Error(`platform:mail: the new Stalwart instance did not answer at ${url} within ${Math.round(timeout / 1000)}s; retry this apply`);
+        }
+        await sleep(interval);
+    }
+}
+function redactedMailError(error, secrets) {
+    const original = error instanceof Error ? error : new Error(String(error));
+    const message = redactSecrets(original.message, secrets);
+    const stack = redactSecrets(original.stack ?? message, secrets);
+    if (message === original.message && stack === original.stack)
+        return original;
+    const clean = new Error(message);
+    clean.name = original.name;
+    clean.stack = stack;
+    return clean;
+}
+const PLATFORM_ARCHON_PROJECT = 'platform';
+const PLATFORM_ARCHON_APP_NAME = 'platform-archon';
+const PLATFORM_ARCHON_DB_NAME = 'platform-archon-db';
+/**
+ * The database Coolify creates for Archon. Archon's own
+ * `drizzle/0001_runtime_role.sql` names its runtime role
+ * `current_database() || '_rt'`, so {@link ARCHON_RUNTIME_ROLE} follows.
+ */
+const ARCHON_POSTGRES_DB = 'archon';
+const ARCHON_RUNTIME_ROLE = `${ARCHON_POSTGRES_DB}_rt`;
+/** Fixed so the tunnel addresses the container directly (see `provisionPlatformAuth`). */
+const PLATFORM_ARCHON_INTERNAL_NAME = 'platform-archon';
+const PLATFORM_ARCHON_TUNNEL_NAME = 'platform-archon-tunnel';
+/** #197: the one Coolify app that runs `cloudflared` for {@link PLATFORM_ARCHON_TUNNEL_NAME}. */
+const PLATFORM_ARCHON_CLOUDFLARED_APP_NAME = 'platform-archon-cloudflared';
+/** https://github.com/wtfalch/archon: one Dockerfile at its root, `runner` stage on port 3000. */
+const ARCHON_REPO = 'wtfalch/archon';
+const ARCHON_PORT = '3000';
+/**
+ * The name of foundry's own Cloudflare Access app in front of Archon. Same
+ * `foundry:<key>` convention `executor.ts`'s `cloudflareAccess` uses for an
+ * org (`foundry:<orgId>`), with the platform's step key in the org id's place.
+ */
+export const PLATFORM_ARCHON_ACCESS_APP_NAME = `foundry:${PLATFORM_ARCHON_KEY}`;
+/** The ZITADEL project and OIDC app Archon's sign-in client lives in. */
+const PLATFORM_ARCHON_ZITADEL_PROJECT = 'archon';
+const PLATFORM_ARCHON_ZITADEL_APP = 'archon';
+const PLATFORM_ARCHON_PROJECT_SCOPE_KEY = 'coolify_project_platform_archon';
+const PLATFORM_ARCHON_DB_SCOPE_KEY = 'coolify_platform_archon_database';
+const PLATFORM_ARCHON_TUNNEL_SCOPE_KEY = 'cloudflare_platform_archon_tunnel';
+const PLATFORM_ARCHON_ACCESS_SCOPE_KEY = 'cloudflare_platform_archon_access_app';
+/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
+export const PLATFORM_ZITADEL_ORG_SCOPE_KEY = 'zitadel_platform_org';
+const PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_platform_archon_project';
+const PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY = 'zitadel_platform_archon_app';
+/** The hostname the sign-in client's redirect URIs were made for; a change makes a new client. */
+const PLATFORM_ARCHON_CLIENT_HOSTNAME_SCOPE_KEY = 'zitadel_platform_archon_client_hostname';
+/** Archon's OIDC client id: public, not a secret, so a plain scope id. */
+export const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = 'zitadel_platform_archon_client_id';
+/**
+ * #175: makes `coolify:app` keyed {@link PLATFORM_ARCHON_KEY} true: Archon
+ * from https://github.com/wtfalch/archon on `platform.archon.gitRef`, its own
+ * Postgres, a sign-in client in the platform's own ZITADEL, a Cloudflare
+ * Access app that lets only {@link PlatformArchonDeps.accessEmails} through,
+ * and a tunnel plus DNS record at `platform.archon.hostname`.
+ *
+ * One Coolify app, no separate migrate job: Archon's `Dockerfile` has no
+ * migration stage (its closing note says the old one was removed), and its
+ * `runner` starts with `scripts/migrate-and-start.sh`, which applies
+ * `drizzle/*.sql` as `DATABASE_URL_OWNER`, creates the `<database>_rt` runtime
+ * role, sets its password from `DATABASE_URL`, unsets the owner URL and only
+ * then starts the server.
+ *
+ * Order matters in two places. The Access app is created before the DNS
+ * record, so the hostname never resolves without the gate in front of it
+ * (Archon's `docs/operator-deployment.md`: "Install the Access gate before
+ * publishing DNS"). The sign-in client is created before the env push, so
+ * `AUTH_CLIENT_ID` is in the first deploy.
+ *
+ * Env written from the applied platform and held keys, never pasted:
+ * - `APP_URL`, `AUTH_ISSUER` (`https://<auth.hostname>`),
+ *   `AUTH_ORGANIZATION_ID` and `AUTH_CLIENT_ID` (both from ZITADEL, this run),
+ *   `AUTH_COOKIE_SECRET` (generated once, never rotated).
+ * - `DATABASE_URL_OWNER` (Coolify's `internal_db_url`) and `DATABASE_URL`
+ *   (the `archon_rt` runtime role, its password minted once, never rotated,
+ *   the same rule `executor.ts`'s `ensureCmsRuntimeUrl` follows). A URL that
+ *   does not parse fails the step without printing it.
+ * - For each of files, ai, integrations and jobs that the platform declares
+ *   enabled: its `https://<hostname>` URL, and its management key when
+ *   {@link PlatformArchonDeps.heldKeys} holds one.
+ *
+ * The OIDC client is ZITADEL's public web client (authorization code with
+ * PKCE, no client secret: `createOidcApp` never returns one, see
+ * `executor.ts`'s `zitadelApp`), which is what Archon's `@wtfalch/auth`
+ * sign-in reads -- it takes `AUTH_CLIENT_ID` and no client secret. So there
+ * is no one-time secret to hand to `deliverSecret` here. The three values this
+ * step does generate (cookie secret, runtime-role password, `AUTH_APP_KEY`)
+ * go straight into the app's env and nowhere else: never returned, recorded,
+ * logged or put in an error.
+ *
+ * `AUTH_APP_KEY` (#204): minted once, the same `ensureGeneratedEnv` way as
+ * the cookie secret, and registered with the broker by rewriting its
+ * `AUTH_APPS` env to include Archon's entry -- `deliverSecret` is not the
+ * right shape here, since the destination is another app's env this same
+ * function already writes to, not a human or a secret store. Requires
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} to be recorded, which
+ * `provisionPlatformAuth` guarantees by the time this step is reachable (its
+ * own resourceId records only once the broker app exists too). The broker
+ * will not actually be able to serve a request with this key until
+ * `provisionPlatformAuth`'s own "Known gaps" (`ZITADEL_SERVICE_USER_TOKEN`,
+ * `RESEND_API_TOKEN`) are closed; wiring the key here is still correct and
+ * needed so the two apps agree the moment the broker can run.
+ *
+ * Known gaps, left for review:
+ * - `AUTHZ_BOOTSTRAP_OPERATOR`: the first operator's ZITADEL subject id. A
+ *   person has to exist in the new instance first; not something foundry
+ *   mints.
+ * - Foundry's own database URL. Archon runs foundry in its panel, but foundry
+ *   does not know its own connection string at plan/apply time: that is host
+ *   config, not something `DeclaredPlatform` or held keys carry.
+ * - The refs and scope ids Archon reads from the files, ai and integrations
+ *   steps are exported by those steps' own modules. A
+ *   missing one blocks the plan (`blockedSteps`); it is never skipped. The
+ *   env names `AI_*`, `INTEGRATIONS_*`, `JOBS_URL` and `JOBS_ADMIN_TOKEN` are
+ *   this step's proposal; Archon reads only `FILES_URL` and
+ *   `FILES_MANAGEMENT_KEY` of these today. Files' signed-assertion identity
+ *   (`FILES_MANAGEMENT_ISSUER`, `_KEY_ID`, `_PRIVATE_KEY`, `_SCOPE`) and
+ *   `FILES_ORGANISATION_ID` are not wired.
+ * - The step plans again when the hostname, `gitRef` or the Access policy's
+ *   include list changes. Env for a service enabled later is not pushed until
+ *   one of those changes.
+ * - No API updates an app's Access policy, so a changed include list closes
+ *   the tunnel hostname, deletes the Access app and builds it again.
+ * - #197: a `cloudflared` connector runs for this tunnel, as in `provisionPlatformAuth`.
+ * - Retiring `operator.wtfalch.dev` stays a human step.
+ */
+async function provisionPlatformArchon(context, deps) {
+    const { platform } = context;
+    const hostname = platform.archon.hostname;
+    const gitRef = platform.archon.gitRef;
+    const recorded = context.recordedIds();
+    const issuer = `https://${platform.auth.hostname}`;
+    const appliedGitRef = recorded[PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY];
+    if (deps.accessEmails.length === 0) {
+        throw new Error('platform:archon: no Access emails given; refusing to put Archon behind an Access app nobody can pass');
+    }
+    // The sign-in client below is created inside the platform's own ZITADEL,
+    // which `platform:auth` builds. The planner orders that step first and
+    // blocks this one while auth is off; this is the same rule for a caller
+    // that reaches the step anyway.
+    if (!platform.auth.enabled || !recorded[`coolify:app:${PLATFORM_AUTH_KEY}`]) {
+        throw new Error("platform:archon: the platform's own sign-in (platform:auth) has not been applied yet; Archon's sign-in client lives in it");
+    }
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    // Every service the platform declares must have delivered what Archon reads.
+    // The planner blocks first; this is the same rule for a caller that reaches
+    // the step anyway, and it is where the values are read for the env below.
+    const inputs = await collectArchonServiceInputs(platform, deps, recorded);
+    if ('blocked' in inputs)
+        throw new Error(`platform:archon: ${inputs.blocked}`);
+    // #213: Archon's own onboarding reads these back as held keys before it
+    // can start. Put before anything below touches Coolify, so a host that
+    // cannot put them never gets a half-built app.
+    if (!deps.masterKeys || !deps.heldKeys?.put) {
+        throw new Error("platform:archon: the host built the platform executor without a way to put its master keys (masterKeys, and heldKeys with a put) -- Archon's onboarding reads them as held keys before it can start (#213)");
+    }
+    await putArchonMasterKeys(deps.heldKeys, deps.masterKeys);
+    // ---- Coolify project and database -----------------------------------------
+    let projectUuid = recorded[PLATFORM_ARCHON_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await deps.coolify.findProjectByName(PLATFORM_ARCHON_PROJECT);
+        projectUuid = found
+            ? found.uuid
+            : (await deps.coolify.createProject(PLATFORM_ARCHON_PROJECT)).uuid;
+        await record(PLATFORM_ARCHON_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    let dbId = recorded[PLATFORM_ARCHON_DB_SCOPE_KEY];
+    if (!dbId) {
+        const server = await resolvePlatformServer(deps.coolify);
+        const created = await deps.coolify.createPostgresDatabase({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            name: PLATFORM_ARCHON_DB_NAME,
+            postgres_db: ARCHON_POSTGRES_DB,
+            postgres_user: ARCHON_POSTGRES_DB,
+        });
+        dbId = created.uuid;
+        await record(PLATFORM_ARCHON_DB_SCOPE_KEY, dbId);
+    }
+    const db = await deps.coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        throw new Error('coolify:app for the platform (archon): the database has no internal_db_url yet -- retry this apply once Coolify reports one');
+    }
+    // ---- the app ----------------------------------------------------------------
+    const app = await findOrCreatePlatformApp(deps.coolify, PLATFORM_ARCHON_APP_NAME, environment, async () => {
+        const server = await resolvePlatformServer(deps.coolify);
+        const githubApp = await deps.coolify.requireGithubApp();
+        return deps.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: ARCHON_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name: PLATFORM_ARCHON_APP_NAME,
+        });
+    });
+    const appId = app.appId;
+    // Set on every run: the tunnel addresses the app by this name, and a throw
+    // right after the create must not leave it unnamed for good.
+    // `git_branch` is patched too, so a changed `gitRef` reaches the app; the
+    // deploy below is decided from the last applied `gitRef`.
+    await deps.coolify.updateApplication(appId, {
+        custom_internal_name: PLATFORM_ARCHON_INTERNAL_NAME,
+        git_branch: gitRef,
+    });
+    // ---- sign-in client in the platform's own ZITADEL -------------------------
+    const zitadel = deps.zitadelForInstance?.(issuer) ?? deps.zitadel;
+    const { org } = await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+    if (recorded[PLATFORM_ZITADEL_ORG_SCOPE_KEY] !== org.id) {
+        await record(PLATFORM_ZITADEL_ORG_SCOPE_KEY, org.id);
+    }
+    const { project } = await zitadel.findOrCreateProject(org.id, PLATFORM_ARCHON_ZITADEL_PROJECT);
+    if (recorded[PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY] !== project.id) {
+        await record(PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY, project.id);
+    }
+    // The client's redirect URIs name the hostname, and no call updates them, so
+    // a client made for another hostname is deleted and made again. Its id is
+    // public and there is no secret to lose.
+    let clientId = recorded[PLATFORM_ARCHON_CLIENT_HOSTNAME_SCOPE_KEY] === hostname
+        ? recorded[PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY]
+        : undefined;
+    if (!clientId) {
+        // An app under this name with no usable client id is one whose create
+        // response was lost, or one made for another hostname: its client id
+        // cannot be read back (`listApps` does not carry it), so it is deleted and
+        // made again, as `zitadelApp` does.
+        const orphan = (await zitadel.listApps(org.id, project.id)).find((a) => a.name === PLATFORM_ARCHON_ZITADEL_APP &&
+            a.appType === 'web' &&
+            a.state !== 'APP_STATE_REMOVED');
+        if (orphan) {
+            try {
+                await zitadel.deleteApp(org.id, project.id, orphan.id);
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+        }
+        const created = await zitadel.createOidcApp(org.id, project.id, {
+            name: PLATFORM_ARCHON_ZITADEL_APP,
+            appType: 'web',
+            // `@wtfalch/auth`'s default callback path (Archon's own
+            // `docs/operator-deployment.md`, step 4).
+            redirectUris: [`https://${hostname}/auth/callback`],
+            postLogoutRedirectUris: [`https://${hostname}/`],
+        });
+        context.recordScopeId(PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY, created.appId);
+        context.recordScopeId(PLATFORM_ARCHON_CLIENT_HOSTNAME_SCOPE_KEY, hostname);
+        await record(PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY, created.clientId);
+        clientId = created.clientId;
+    }
+    // ---- env ------------------------------------------------------------------
+    const envs = [
+        { key: 'APP_URL', value: `https://${hostname}` },
+        { key: 'AUTH_ISSUER', value: issuer },
+        { key: 'AUTH_ORGANIZATION_ID', value: org.id },
+        { key: 'AUTH_CLIENT_ID', value: clientId },
+        { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
+        { key: 'REPORTING_SITE', value: 'archon' },
+    ];
+    const cookieSecret = await ensureGeneratedEnv(deps.coolify, appId, 'AUTH_COOKIE_SECRET', () => randomBytes(32).toString('base64'));
+    if (cookieSecret)
+        envs.push({ key: 'AUTH_COOKIE_SECRET', value: cookieSecret });
+    const runtimeUrl = await ensureArchonRuntimeUrl(deps.coolify, appId, db.internal_db_url);
+    if (runtimeUrl)
+        envs.push({ key: 'DATABASE_URL', value: runtimeUrl });
+    // `AUTH_APP_KEY` (#204): minted once like the cookie secret above, but read
+    // back (never regenerated) rather than skipped when already set, since its
+    // value is needed below to keep the broker's own registration in sync even
+    // on a run that mints nothing new. `randomBytes(32)` (#211), the same
+    // random half `wtfalch/auth/broker/src/apps.ts`'s own `mintKey` gives an
+    // app key -- `parseApps` there rejects a key under 32 *characters*, and
+    // `randomBytes(24)` base64url-encodes to exactly 32, landing right on that
+    // edge with no margin for a different encoding or a trim.
+    // #211 round 5: `minLength: 32` on this call only -- a live value shorter
+    // than the broker itself will accept is exactly as unusable as one that is
+    // empty, and `readBrokerApps`/`validateBrokerAppEntry` would refuse it the
+    // moment this step tried to register it. See `ensureGeneratedEnv`'s own
+    // doc comment for why no other call site gets this argument.
+    const appKey = (await ensureGeneratedEnv(deps.coolify, appId, 'AUTH_APP_KEY', () => randomBytes(32).toString('base64url'), 32)) ?? (await currentEnvValue(deps.coolify, appId, 'AUTH_APP_KEY'));
+    if (!appKey) {
+        throw new Error(`platform:archon: app ${appId} lost its AUTH_APP_KEY between two reads`);
+    }
+    envs.push({ key: 'AUTH_APP_KEY', value: appKey });
+    envs.push(...inputs.envs);
+    const changed = await envsDiffer(deps.coolify, appId, envs);
+    await deps.coolify.bulkUpsertEnvs(appId, envs);
+    // ---- register with the broker (#204) ---------------------------------------
+    // After Archon's own `AUTH_APP_KEY` is durably written above, so a throw
+    // earlier in this function (a bad database URL, a Cloudflare failure) never
+    // touches the broker. `provisionPlatformAuth`'s own resourceId records only
+    // once the broker app exists too (it is created before that function
+    // returns), and this step is unreachable until that resourceId is recorded
+    // (the guard at the top of this function) -- so a missing id here means a
+    // caller reached this step some other way.
+    const brokerAppId = recorded[PLATFORM_AUTH_BROKER_SCOPE_KEY];
+    if (!brokerAppId) {
+        throw new Error('platform:archon: platform:auth has not recorded its broker app id yet; apply platform:auth again');
+    }
+    const brokerApps = await readBrokerApps(deps.coolify, brokerAppId);
+    // #211 round 2: merged into the matching entry, not replacing it -- the
+    // broker's own `App` (`broker/src/apps.ts`) carries fields this step never
+    // sets (`registration`, `locale`, `productName`, `emailLink`), and a
+    // previous `filter`-then-append dropped every one of them, plus every
+    // *other* app this organisation may have registered directly through the
+    // broker's own registration API. Matched on `organizationId` and `name`
+    // together: Archon is one app of possibly several this organisation runs,
+    // and only Archon's own entry is this step's to touch.
+    // #211 round 3: every entry matching Archon's org and name, not just the
+    // first -- a previous bug, or a hand-edited AUTH_APPS, can leave more than
+    // one. The first is kept (and updated below); the rest are dropped, so no
+    // duplicate carries a stale key a broker client could still present.
+    const archonMatchIndices = brokerApps
+        .map((a, i) => (a.organizationId === org.id && a.name === PLATFORM_ARCHON_ZITADEL_APP ? i : -1))
+        .filter((i) => i >= 0);
+    const archonEntryIndex = archonMatchIndices[0] ?? -1;
+    const duplicateIndices = new Set(archonMatchIndices.slice(1));
+    const archonEntry = {
+        ...(archonEntryIndex >= 0 ? brokerApps[archonEntryIndex] : {}),
+        organizationId: org.id,
+        key: appKey,
+        name: PLATFORM_ARCHON_ZITADEL_APP,
+        clientIds: [clientId],
+        origins: [`https://${hostname}`],
+        // #211: `wtfalch/auth`'s broker (`broker/src/apps.ts`'s `parseAppFields`)
+        // falls back to `wtfalch <noreply@wtfalch.dev>` for an entry with no
+        // `from`, and (`wtfalch/auth#179`) an entry with no `from` is dropped
+        // entirely -- either way, unset here means Archon's mail comes from
+        // the wrong platform or not at all.
+        from: `Company Included <noreply@${platform.apex}>`,
+    };
+    const desiredBrokerApps = archonEntryIndex >= 0
+        ? brokerApps
+            .map((a, i) => (i === archonEntryIndex ? archonEntry : a))
+            .filter((_, i) => !duplicateIndices.has(i))
+        : [...brokerApps, archonEntry];
+    const desiredAuthApps = [{ key: 'AUTH_APPS', value: JSON.stringify(desiredBrokerApps) }];
+    // Rebuilt and compared every run (not gated on a freshly minted key), so a
+    // clientId or hostname change reaches the broker too, and so a previous
+    // run that wrote Archon's own key but failed before reaching the broker is
+    // repaired by this one.
+    const authAppsChanged = await envsDiffer(deps.coolify, brokerAppId, desiredAuthApps);
+    if (authAppsChanged) {
+        await deps.coolify.bulkUpsertEnvs(brokerAppId, desiredAuthApps);
+    }
+    // #211 round 2: deploying the broker before its own `server.ts` can start
+    // (missing `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` or `RESEND_API_TOKEN`, #209,
+    // #210) only produces a container that crash-loops behind `/api` -- the
+    // same rule `provisionPlatformAuth` follows for its own deploy of this
+    // app. The env is still written either way, so the broker serves the new
+    // registration the moment it is next deployed, by either step.
+    // #211 round 5: the deploy decision is {@link brokerDeployNeeded}, the same
+    // rule `provisionPlatformAuth` uses -- it is what replaces the old
+    // `!brokerAlreadyDeployed` boolean, and with it catches both a broker
+    // recreated under a new app id (this step's own last-registered-broker
+    // check, `archonBrokerRegistrationDrifted`, is a different, already-correct
+    // mechanism for *replanning*; this is what stops the *executor* from
+    // reading a stale record as already deployed) and a crash between this
+    // run's own `AUTH_APPS` write above and its deploy -- a rerun recomputes
+    // the identical `desiredAuthApps` value, sees no recorded deploy naming
+    // that hash, and deploys again. `desiredAuthApps[0].value` (not a re-read)
+    // is the exact string now live on the app either way: written just above
+    // when `authAppsChanged`, already matching when it was not.
+    const brokerMissingInputs = await missingBrokerInputs(deps.coolify, brokerAppId);
+    const recordedBrokerDeploy = parseBrokerDeployRecord(recorded[PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY]);
+    const desiredAuthAppsRaw = desiredAuthApps[0]?.value;
+    if (brokerDeployNeeded(brokerMissingInputs, brokerAppId, desiredAuthAppsRaw, recordedBrokerDeploy)) {
+        await deps.coolify.deploy(brokerAppId);
+        await record(PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, brokerDeployRecordValue(brokerAppId, desiredAuthAppsRaw));
+    }
+    // ---- Cloudflare Access, before the hostname resolves ----------------------
+    let gateClosed = Boolean(recorded[PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY]);
+    const accessAppId = await ensureArchonAccess(deps.cloudflare, hostname, deps.accessEmails, async () => {
+        // The Access app is about to be rebuilt: answer 404 for every hostname
+        // meanwhile, so it is never served without the gate. The marker is
+        // persisted first: a failure before the real ingress is written back
+        // leaves it set, and the next plan repairs the step.
+        gateClosed = true;
+        await record(PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, '1');
+        const tunnel = await deps.cloudflare.findTunnelByName(PLATFORM_ARCHON_TUNNEL_NAME);
+        if (tunnel)
+            await deps.cloudflare.putTunnelConfig(tunnel.id, {
+                ingress: [{ service: 'http_status:404' }],
+            });
+    });
+    if (recorded[PLATFORM_ARCHON_ACCESS_SCOPE_KEY] !== accessAppId) {
+        await record(PLATFORM_ARCHON_ACCESS_SCOPE_KEY, accessAppId);
+    }
+    // ---- deploy ---------------------------------------------------------------
+    if (app.justCreated ||
+        !app.running ||
+        changed ||
+        appliedGitRef !== gitRef ||
+        recorded[PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY] !== hostname) {
+        await deps.coolify.deploy(appId);
+    }
+    // ---- tunnel and DNS ---------------------------------------------------------
+    const existingTunnel = await deps.cloudflare.findTunnelByName(PLATFORM_ARCHON_TUNNEL_NAME);
+    const tunnel = existingTunnel ?? (await deps.cloudflare.createTunnel(PLATFORM_ARCHON_TUNNEL_NAME));
+    if (recorded[PLATFORM_ARCHON_TUNNEL_SCOPE_KEY] !== tunnel.id) {
+        await record(PLATFORM_ARCHON_TUNNEL_SCOPE_KEY, tunnel.id);
+    }
+    await deps.cloudflare.putTunnelConfig(tunnel.id, {
+        ingress: [
+            { hostname, service: `http://${PLATFORM_ARCHON_INTERNAL_NAME}:${ARCHON_PORT}` },
+            { service: 'http_status:404' },
+        ],
+    });
+    if (gateClosed) {
+        await record(PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, '');
+    }
+    // #197: without a connector, `hostname` answers with a Cloudflare error.
+    await ensureCloudflaredConnector({
+        coolify: deps.coolify,
+        cloudflare: deps.cloudflare,
+        tunnelId: tunnel.id,
+        appName: PLATFORM_ARCHON_CLOUDFLARED_APP_NAME,
+        projectUuid,
+        environment,
+        resolveServer: () => resolvePlatformServer(deps.coolify),
+        recordedConnectorAppId: recorded[PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY] ?? null,
+        recordAppId: (appId) => record(PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, appId),
+    });
+    const zoneId = recorded[apexZoneKey(platform.apex)] ?? (await exactZone(deps.cloudflare, platform.apex))?.id;
+    if (!zoneId) {
+        throw new Error(`platform:archon: no Cloudflare zone for ${platform.apex} to put ${hostname} in`);
+    }
+    const dnsTarget = `${tunnel.id}.cfargotunnel.com`;
+    const [dnsRecord] = await deps.cloudflare.findDnsRecord(zoneId, hostname, 'CNAME');
+    if (!dnsRecord) {
+        await deps.cloudflare.createDnsRecord(zoneId, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    else if (dnsRecord.content !== dnsTarget) {
+        await deps.cloudflare.updateDnsRecord(zoneId, dnsRecord.id, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    // Last, after every write the applied values depend on, so a run that failed
+    // halfway plans again.
+    await record(PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    await record(PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, gitRef);
+    // #211 round 4: the broker this run actually registered Archon's entry
+    // with, so `planArchon` can tell a broker recreated under a new app id
+    // (whose AUTH_APPS never carried this registration) from one still holding
+    // it.
+    await record(PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, brokerAppId);
+    return { resourceId: appId };
+}
+// #211 round 6: mirrors `wtfalch/auth/broker/src/apps.ts`'s own `isValidFrom`
+// (and the `isSafeText`/control-character checks it shares with
+// `parseCommonAppFields`) exactly, character class for character class.
+// That module is `@wtfalch/auth-broker`, `private: true`, and exports
+// neither function, so there is nothing to import -- this has to stay a
+// faithful copy. Round 5's version only checked that an address sat inside
+// `<...>`, not the display name in front of it, so `bad<name> <a@b.co>` and
+// a name carrying a right-to-left override both passed this step's gate and
+// were then silently dropped by the broker's own parser at boot (`AUTH_APPS
+// has no usable entries` if it was the only one). Kept in lockstep by hand;
+// if the broker's rule ever changes, this one has to change with it.
+const FROM_MAX_LENGTH = 320;
+const LOCAL_PART = '[A-Za-z0-9._%+-]+';
+const DOMAIN_LABEL = '[A-Za-z0-9-]+';
+const SENDER_ADDRESS_RE = new RegExp(`^${LOCAL_PART}@${DOMAIN_LABEL}(?:\\.${DOMAIN_LABEL})*$`);
+const SENDER_NAME_CHAR = "[\\p{L}\\p{M}\\d .,'&()!\\u2019\\u2013-]";
+const SENDER_NAME_RE = new RegExp(`^${SENDER_NAME_CHAR}+$`, 'u');
+const NAMED_FROM_RE = /^(.*)<([^<>]+)>$/;
+// Every control character (`\p{Cc}`), every format character (`\p{Cf}`, how
+// an RTL override hides a reordering attack), both Unicode line/paragraph
+// separators, and the two blanks-in-disguise `trim()` cannot be trusted to
+// strip first (`\u00a0` NBSP, `\ufeff` BOM).
+const OTHER_UNSAFE_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\u00a0\ufeff]/u;
+// #218 round 2: `\p{Cf}` also matches U+200C (ZWNJ) and U+200D (ZWJ), which
+// a real name can carry -- ZWNJ joins letters into one word in
+// Persian/Arabic script, ZWJ joins separate emoji into one glyph. Rejecting
+// every `\p{Cf}` character missed that the broker's own `hasUnsafeText`
+// exempts both, but only immediately between two letters or two emoji: a
+// loose one at either end, or beside anything else, is exactly the kind of
+// invisible character this check exists to catch, same as an RTL override.
+// Hand-copied from `wtfalch/auth/broker/src/apps.ts`'s own `hasUnsafeText`,
+// character class for character class, for the same reason the rest of
+// this block is a copy: that module is `@wtfalch/auth-broker`, `private:
+// true`.
+const JOINER_CHARS = new Set(['\u200c', '\u200d']);
+const LETTER_OR_EMOJI_RE = /^[\p{L}\p{Extended_Pictographic}]$/u;
+// A real joined sequence is rarely letter-immediately-next-to-joiner on
+// both sides. Devanagari's explicit half-form writes a virama (a combining
+// mark, `\p{M}`) before the ZWJ; a multi-part emoji chains a ZWJ onto a
+// variation selector (U+FE0F) or a skin-tone modifier
+// (`\p{Emoji_Modifier}`) rather than straight onto the base character. All
+// of these sit *before* the joiner, never after it, so only the "previous
+// character" side is widened.
+const JOINER_PREV_RE = /^(?:[\p{L}\p{M}\p{Extended_Pictographic}]|\u{FE0F}|\p{Emoji_Modifier})$/u;
+function hasUnsafeText(value) {
+    const chars = Array.from(value);
+    for (let i = 0; i < chars.length; i++) {
+        const ch = chars[i]; // i < chars.length, so this index always exists
+        if (JOINER_CHARS.has(ch)) {
+            const prev = chars[i - 1];
+            const next = chars[i + 1];
+            if (!prev || !next || !JOINER_PREV_RE.test(prev) || !LETTER_OR_EMOJI_RE.test(next)) {
+                return true;
+            }
+            continue;
+        }
+        if (OTHER_UNSAFE_RE.test(ch))
+            return true;
+    }
+    return false;
+}
+function isSafeText(value, max) {
+    return value.trim().length > 0 && value.length <= max && !hasUnsafeText(value);
+}
+function isValidSenderDisplayName(value) {
+    return value.trim().length > 0 && SENDER_NAME_RE.test(value);
+}
+/**
+ * A broker app entry's `from` -- not an RFC 5322 parser, just enough to
+ * catch what the broker itself would refuse or silently drop. Accepts the
+ * two shapes this package itself ever writes (`provisionPlatformArchon`'s
+ * own `archonEntry.from`, `` `Company Included <noreply@${platform.apex}>` ``)
+ * or reads back from a hand-edited `AUTH_APPS`: `Display Name <email@domain>`
+ * (quoted or not) and a bare `email@domain` address.
+ */
+function isValidSenderFrom(from) {
+    if (from.length === 0 || from.length > FROM_MAX_LENGTH)
+        return false;
+    if (SENDER_ADDRESS_RE.test(from))
+        return true;
+    const named = NAMED_FROM_RE.exec(from);
+    if (!named)
+        return false;
+    const rawName = named[1] ?? '';
+    const address = named[2] ?? '';
+    if (!SENDER_ADDRESS_RE.test(address))
+        return false;
+    if (!isSafeText(rawName, FROM_MAX_LENGTH))
+        return false;
+    const name = rawName.trim();
+    if (name.startsWith('"') && name.endsWith('"') && name.length >= 2) {
+        return isValidSenderDisplayName(name.slice(1, -1));
+    }
+    return isValidSenderDisplayName(name);
+}
+/** #211 round 5: the two locales `@wtfalch/mailer`'s `Locale` type restricts a broker app entry's optional `locale` to. */
+const VALID_BROKER_APP_LOCALES = new Set(['en', 'nb']);
+/** #211 round 6: matches the broker's own `CLIENT_ID_MAX_LENGTH`. */
+const BROKER_CLIENT_ID_MAX_LENGTH = 200;
+/**
+ * #218: matches the broker's own `PRODUCT_NAME_MAX_LENGTH`
+ * (`broker/src/apps.ts`), which it uses as the cap for both `name` and
+ * `productName` -- `parseCommonAppFields`'s own `isSafeText(app.name,
+ * PRODUCT_NAME_MAX_LENGTH)` and `isValidProductName`'s
+ * `isSafeText(value, PRODUCT_NAME_MAX_LENGTH)`.
+ */
+const BROKER_NAME_MAX_LENGTH = 100;
+/**
+ * #211 round 5: whether `value` is already in the canonical origin form
+ * `wtfalch/auth/broker/src/apps.ts`'s own `parseApps` requires for an entry's
+ * `origins` -- http(s), and `new URL(value).origin === value` exactly, so no
+ * path, query, trailing slash or differently-cased host survives. `new URL`
+ * throws on an arbitrary string, so that failure is itself "not a URL".
+ */
+function isCanonicalOrigin(value) {
+    try {
+        const parsed = new URL(value);
+        return (parsed.protocol === 'http:' || parsed.protocol === 'https:') && parsed.origin === value;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One `AUTH_APPS[index]` entry, checked the way
+ * `wtfalch/auth/broker/src/apps.ts`'s own `parseApps`/`parseAppFields`
+ * (https://github.com/wtfalch/auth/blob/main/broker/src/apps.ts) check it at
+ * boot, in the same order: a `key` of at least 32 characters and a non-empty
+ * `organizationId`; a `name` that passes the broker's own `isSafeText` rule
+ * (#218); a `productName`, when present, that is a string and also passes it
+ * (#218); a `from` that passes {@link isValidSenderFrom}; a `locale` of
+ * `'en'` or `'nb'` when present; non-blank `clientIds`; and `origins` each in
+ * {@link isCanonicalOrigin} form. #211 round 2: on a bad
+ * entry this throws naming the broker app id and the entry's index, never
+ * the value -- `key` may hold another organisation's secret, and even
+ * `organizationId`/`name` are not this step's to print in an error only an
+ * operator reads. `entry` may be anything at all (`null`, a string, an
+ * array): every check below is a `typeof`/`Array.isArray` guard first, so a
+ * malformed entry never reaches a property read on a non-object and throws a
+ * `TypeError` instead of this named error.
+ */
+function validateBrokerAppEntry(entry, brokerAppId, index) {
+    const label = `platform:archon: broker app ${brokerAppId}'s AUTH_APPS[${index}]`;
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        throw new Error(`${label} is not an object`);
+    }
+    const app = entry;
+    if (typeof app.organizationId !== 'string' || !app.organizationId) {
+        throw new Error(`${label} has no organizationId`);
+    }
+    if (typeof app.key !== 'string' || !app.key) {
+        throw new Error(`${label} has no key`);
+    }
+    if (app.key.length < 32) {
+        throw new Error(`${label} has too short a key`);
+    }
+    if (typeof app.name !== 'string' || !app.name) {
+        throw new Error(`${label} has no name`);
+    }
+    // #218: the broker's own `parseCommonAppFields` runs `name` through
+    // `isSafeText(app.name, PRODUCT_NAME_MAX_LENGTH)` too (`name` stands in for
+    // `productName` in the mail subject whenever an entry declares no
+    // `productName` of its own, so it needs the same safety check) -- this
+    // step's own truthy check above missed a NUL, an RTL override, a line
+    // separator, or a name over 100 characters, all of which this gate reads
+    // back and keeps, and all of which the broker then throws on at boot.
+    if (!isSafeText(app.name, BROKER_NAME_MAX_LENGTH)) {
+        throw new Error(`${label} has an invalid name`);
+    }
+    if (app.productName !== undefined) {
+        // #218: `productName` is optional on the broker's own `App`, but when
+        // present it runs through `isValidProductName`
+        // (`isSafeText(value, PRODUCT_NAME_MAX_LENGTH)`) exactly like `name`
+        // above -- a non-string, a NUL, or one over 100 characters all throw at
+        // the broker's boot the same way.
+        if (typeof app.productName !== 'string') {
+            throw new Error(`${label} has a non-string productName`);
+        }
+        if (!isSafeText(app.productName, BROKER_NAME_MAX_LENGTH)) {
+            throw new Error(`${label} has an invalid productName`);
+        }
+    }
+    if (typeof app.from !== 'string' || !app.from) {
+        throw new Error(`${label} has no from`);
+    }
+    if (!isValidSenderFrom(app.from)) {
+        throw new Error(`${label} has an invalid from`);
+    }
+    if (app.locale !== undefined && !VALID_BROKER_APP_LOCALES.has(app.locale)) {
+        throw new Error(`${label} has an invalid locale`);
+    }
+    if (!Array.isArray(app.clientIds) || app.clientIds.length === 0) {
+        throw new Error(`${label} has no clientIds`);
+    }
+    if (app.clientIds.some((id) => typeof id !== 'string' || id.trim() === '')) {
+        throw new Error(`${label} has a blank clientIds entry`);
+    }
+    // #211 round 6: `clientIds:["a\u0000b"]` passed this gate before -- a
+    // control character is not blank, so the check above missed it, and the
+    // broker's own `parseCommonAppFields` throws on it at boot
+    // (`isSafeText(candidate, CLIENT_ID_MAX_LENGTH)`).
+    if (app.clientIds.some((id) => typeof id === 'string' && !isSafeText(id, BROKER_CLIENT_ID_MAX_LENGTH))) {
+        throw new Error(`${label} has an invalid clientIds entry`);
+    }
+    if (!Array.isArray(app.origins) || app.origins.length === 0) {
+        throw new Error(`${label} has no origins`);
+    }
+    if (app.origins.some((origin) => typeof origin !== 'string' || !isCanonicalOrigin(origin))) {
+        throw new Error(`${label} has an invalid origins entry`);
+    }
+    return app;
+}
+/**
+ * The broker's current `AUTH_APPS` (#204), parsed back so an entry can be
+ * merged without losing whichever other organisations -- or other apps of
+ * this same organisation -- have registered. Empty only for a broker that
+ * has never had one set. #211: an *unparseable* value (bad JSON, or JSON
+ * that is not an array) is never treated as empty -- the write that follows
+ * replaces the whole env, so silently reading it as `[]` would drop every
+ * other organisation's entry the moment this run cannot parse what is
+ * there. Throws instead, naming the broker app id (the app holding the
+ * unreadable value), never the value itself -- it may hold another
+ * organisation's key. #211 round 2: each entry is validated the same way
+ * the broker itself validates `AUTH_APPS` at boot ({@link validateBrokerAppEntry}),
+ * so a bad entry is caught here, by this step, rather than only discovered
+ * once the broker refuses to start on it.
+ */
+async function readBrokerApps(coolify, brokerAppId) {
+    const envs = await coolify.listEnvs(brokerAppId);
+    const raw = envs.find((e) => e.key === 'AUTH_APPS' && !e.is_preview)?.value;
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`platform:archon: broker app ${brokerAppId} has an AUTH_APPS that is not JSON`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`platform:archon: broker app ${brokerAppId} has an AUTH_APPS that is not a JSON array`);
+    }
+    return parsed.map((entry, index) => validateBrokerAppEntry(entry, brokerAppId, index));
+}
+/**
+ * #213: puts {@link PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF},
+ * {@link PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF} and
+ * {@link PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF} as held keys, under
+ * tenant `platform`, so Archon's own onboarding can read them back once its
+ * app is live. Each ref is resolved first; `put` runs only when that comes
+ * back empty, so an entry already held (put by an earlier apply, or by hand)
+ * is left alone and never overwritten. Values never reach a log, a record or
+ * an error: `heldKeys.put`'s own contract, mirroring `deliverSecret`'s.
+ */
+async function putArchonMasterKeys(heldKeys, masterKeys) {
+    const entries = [
+        [PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, masterKeys.coolifyUrl],
+        [PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, masterKeys.coolifyToken],
+        [PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, masterKeys.cloudflareParentToken],
+    ];
+    for (const [ref, value] of entries) {
+        const existing = await heldKeys.resolve(ref);
+        if (existing)
+            continue;
+        await heldKeys.put?.(ref, value);
+    }
+}
+/**
+ * `executor.ts`'s `cloudflareAccess`, for the platform's Archon: reuses only
+ * an Access app named {@link PLATFORM_ARCHON_ACCESS_APP_NAME}, refuses to
+ * adopt any other Access app already holding the hostname, and refuses when
+ * its own app carries a policy foundry did not create, since that policy
+ * could let others in.
+ */
+async function ensureArchonAccess(cf, domain, emails, closeGate) {
+    const onDomain = (await cf.listAccessApps()).filter((a) => a.domain === domain);
+    const foreign = onDomain.find((a) => a.name !== PLATFORM_ARCHON_ACCESS_APP_NAME);
+    if (foreign) {
+        throw new Error(`platform:archon: Access app '${foreign.name}' already holds ${domain}; foundry does not adopt it`);
+    }
+    const create = async () => {
+        const created = await cf.createAccessApp({
+            name: PLATFORM_ARCHON_ACCESS_APP_NAME,
+            domain,
+            type: 'self_hosted',
+        });
+        await cf.createAccessPolicy(created.id, archonAccessPolicy(emails));
+        return created;
+    };
+    const existing = onDomain[0];
+    if (!existing)
+        return (await create()).id;
+    const policies = await cf.listAccessPolicies(existing.id);
+    const other = policies.find((p) => p.name !== ACCESS_POLICY_NAME);
+    if (other) {
+        throw new Error(`platform:archon: Access app ${existing.id} has policy '${other.name}' that foundry did not create`);
+    }
+    if (policies.length === 0) {
+        await cf.createAccessPolicy(existing.id, archonAccessPolicy(emails));
+        return existing.id;
+    }
+    if (policies.every((p) => sameEmails(p.include, emails)))
+        return existing.id;
+    // No call updates an app's policy: rebuild the app, hostname closed meanwhile.
+    await closeGate();
+    await cf.deleteAccessApp(existing.id);
+    return (await create()).id;
+}
+function archonAccessPolicy(emails) {
+    return {
+        name: ACCESS_POLICY_NAME,
+        decision: 'allow',
+        include: emails.map((email) => ({ email: { email } })),
+    };
+}
+/** Whether an Access policy's include list is exactly `emails` (case-insensitive) and nothing else. */
+function sameEmails(include, emails) {
+    if (!Array.isArray(include))
+        return false;
+    const live = new Set();
+    for (const entry of include) {
+        const email = entry?.email?.email;
+        if (typeof email !== 'string' || Object.keys(entry).length !== 1)
+            return false;
+        live.add(email.toLowerCase());
+    }
+    const declared = new Set(emails.map((e) => e.toLowerCase()));
+    return live.size === declared.size && [...declared].every((e) => live.has(e));
+}
+/**
+ * Whether Archon's Access app or policy is gone or no longer lets through
+ * exactly the declared emails. A failed read is not drift: the next plan reads
+ * again.
+ */
+async function archonAccessDrifted(cf, domain, emails) {
+    try {
+        const app = (await cf.listAccessApps()).find((a) => a.domain === domain && a.name === PLATFORM_ARCHON_ACCESS_APP_NAME);
+        if (!app)
+            return true;
+        const policies = await cf.listAccessPolicies(app.id);
+        return !(policies.length > 0 && policies.every((p) => sameEmails(p.include, emails)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * #211 round 4: whether the broker Archon last registered with (its
+ * `AUTH_APPS`) still carries an entry for Archon's organisation.
+ * `planArchon`'s own recorded-id check
+ * ({@link PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY} against
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY}) catches the broker itself being
+ * recreated under a new app id; this catches the same broker losing the
+ * entry some other way -- a hand edit of `AUTH_APPS`, a previous write that
+ * silently failed. A failed read is not drift, the same rule
+ * {@link archonAccessDrifted} follows: the next plan reads again. Missing
+ * `recordedIds` (no broker recorded yet, or Archon's own ZITADEL org not yet
+ * recorded) is not drift either -- `planArchon`'s other checks already cover
+ * a step that has never applied.
+ */
+async function archonBrokerRegistrationDrifted(coolify, recordedIds) {
+    const brokerAppId = recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY];
+    const orgId = recordedIds[PLATFORM_ZITADEL_ORG_SCOPE_KEY];
+    if (!brokerAppId || !orgId)
+        return false;
+    try {
+        const apps = await readBrokerApps(coolify, brokerAppId);
+        return !apps.some((a) => a.organizationId === orgId && a.name === PLATFORM_ARCHON_ZITADEL_APP);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * What Archon reads from each enabled service, gathered before anything is
+ * built. Either everything is there and the env values come back, or the first
+ * missing piece comes back as one fixed sentence naming a step, scope id or
+ * held-key ref, never a value. Also read at plan time, so the text must not
+ * vary between calls.
+ */
+async function collectArchonServiceInputs(platform, deps, recorded) {
+    const block = (why) => ({ blocked: `Archon is blocked, not planned: ${why}` });
+    const envs = [];
+    const heldByRef = new Map();
+    const services = ['files', 'ai', 'integrations', 'jobs'].filter((s) => platform[s].enabled);
+    if (services.length > 0 && !deps.heldKeys) {
+        return block(`the host built the platform executor without a held-key reader, and ${services.join(', ')} ${services.length === 1 ? 'is' : 'are'} enabled`);
+    }
+    for (const service of services) {
+        const needs = service === 'jobs'
+            ? { stepKey: null, scopeKeys: [], refs: [JOBS_ADMIN_TOKEN_REF] }
+            : ARCHON_SERVICE_INPUTS[service];
+        if (needs.stepKey && !recorded[`coolify:app:${needs.stepKey}`]) {
+            return block(`the ${service} step (${needs.stepKey}) is not applied yet`);
+        }
+        for (const scopeKey of needs.scopeKeys) {
+            if (!recorded[scopeKey]) {
+                return block(`the ${service} step has not recorded the scope id ${scopeKey}`);
+            }
+        }
+        for (const ref of needs.refs) {
+            let held;
+            try {
+                held = (await deps.heldKeys?.resolve(ref)) ?? null;
+            }
+            catch {
+                // The cause is dropped in case it echoes a secret.
+                return block(`the held key ${ref} could not be read`);
+            }
+            if (!held)
+                return block(`the held key ${ref} is not held yet`);
+            heldByRef.set(ref, held);
+        }
+    }
+    const held = (ref) => heldByRef.get(ref);
+    for (const service of services) {
+        if (service === 'files') {
+            envs.push({ key: 'FILES_URL', value: recorded[PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY] }, { key: 'FILES_MANAGEMENT_KEY', value: held(ARCHON_SERVICE_INPUTS.files.refs[0]) });
+        }
+        else if (service === 'ai') {
+            envs.push({ key: 'AI_URL', value: recorded[PLATFORM_AI_INTERNAL_URL_SCOPE_KEY] }, { key: 'AI_MANAGEMENT_KEY', value: held(ARCHON_SERVICE_INPUTS.ai.refs[0]) }, {
+                key: 'AI_ORGANISATION_ID',
+                value: recorded[PLATFORM_AI_ORGANISATION_SCOPE_KEY],
+            });
+        }
+        else if (service === 'integrations') {
+            const url = `https://${platform.integrations.hostname}`;
+            envs.push({ key: 'INTEGRATIONS_URL', value: url }, {
+                key: 'INTEGRATIONS_MANAGEMENT_PRIVATE_KEY',
+                value: held(INTEGRATIONS_MANAGEMENT_KEY_REF),
+            }, { key: 'INTEGRATIONS_MANAGEMENT_ISSUER', value: INTEGRATIONS_MANAGEMENT_ISSUER }, { key: 'INTEGRATIONS_MANAGEMENT_KEY_ID', value: INTEGRATIONS_MANAGEMENT_KEY_ID }, { key: 'INTEGRATIONS_MANAGEMENT_AUDIENCE', value: url });
+        }
+        else {
+            envs.push({ key: 'JOBS_URL', value: `https://${platform.jobs.hostname}` }, { key: 'JOBS_ADMIN_TOKEN', value: held(JOBS_ADMIN_TOKEN_REF) });
+        }
+    }
+    return { envs };
+}
+/**
+ * `null` once the app already has a `DATABASE_URL`, never rotated: Archon's
+ * `db-runtime-role.sh` sets the `archon_rt` password from this URL on every
+ * boot while the previous container's pool is still open, so it must stay
+ * the same across deploys. `executor.ts`'s `ensureCmsRuntimeUrl`, with
+ * Archon's role name; see that method for why a parse failure is swallowed
+ * (Node's `ERR_INVALID_URL` carries the whole input, credential included).
+ * `base64url` fits `db-runtime-role.sh`'s password alphabet
+ * (`A-Za-z0-9_.~-`).
+ */
+async function ensureArchonRuntimeUrl(coolify, appId, dbInternalUrl) {
+    const envs = await coolify.listEnvs(appId);
+    if (envs.some((e) => e.key === 'DATABASE_URL' && !e.is_preview))
+        return null;
+    let host;
+    let pathname;
+    let search;
+    try {
+        ({ host, pathname, search } = new URL(dbInternalUrl));
+    }
+    catch {
+        // Node's `ERR_INVALID_URL` carries the whole input, credential included, so
+        // neither it nor the URL goes into this message.
+        throw new Error('platform:archon: the database internal_db_url could not be parsed; not generating DATABASE_URL. Check the database in Coolify and apply again');
+    }
+    const password = randomBytes(24).toString('base64url');
+    return `postgres://${ARCHON_RUNTIME_ROLE}:${password}@${host}${pathname}${search}`;
+}
+/**
+ * Thrown by {@link createAiManagementKeyMinter} (never by a test's own
+ * injected minter, unless it chooses to) when ai's `POST /v1/platform/keys`
+ * answers 200: a live `archon` key already exists and no secret comes back.
+ * See {@link PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY}.
+ */
+export class AiManagementKeyExistsError extends Error {
+    credentialId;
+    organisationId;
+    constructor(credentialId, organisationId) {
+        super(`ai already holds a management key named 'archon' (${credentialId}) with no secret to show`);
+        this.credentialId = credentialId;
+        this.organisationId = organisationId;
+    }
+}
+/**
+ * Thrown by {@link createAiManagementKeyMinter} on a 409: a live `archon` key
+ * already exists with different permissions or expiry than this request
+ * asked for. ai never overwrites it, so this is never retried under another
+ * name -- an operator revokes the live key in ai first.
+ */
+export class AiManagementKeyConflictError extends Error {
+    constructor() {
+        super("ai already holds a live 'archon' key minted with different permissions or expiry; revoke it in ai, then apply again");
+    }
+}
+/**
+ * Thrown by {@link createAiManagementKeyMinter} on a 401 or 403: ai does not
+ * trust foundry's signing key yet for this request. Most likely the runner
+ * has not redeployed since {@link AI_SIGNING_KEY_REF}'s public half was
+ * pinned as `MANAGEMENT_PUBLIC_KEYS`/`MANAGEMENT_ISSUER` -- a Coolify env
+ * change reaches the container only on its next deploy.
+ */
+export class AiManagementKeyUntrustedError extends Error {
+    status;
+    constructor(status) {
+        super(`ai's platform/keys route refused foundry's signing key (${status}); check MANAGEMENT_PUBLIC_KEYS/MANAGEMENT_ISSUER on the ai runner and that it has redeployed since they were pinned`);
+        this.status = status;
+    }
+}
+/**
+ * Both response bodies {@link createAiManagementKeyMinter} reads are parsed
+ * rather than cast: a malformed body (an empty 201, a 200 with no
+ * `credentialId`) must fail the mint outright rather than record an
+ * `undefined` id or hand `deliverSecret` an `undefined` "secret". Neither
+ * error message repeats the body, which could hold the very secret this
+ * function must not leak.
+ */
+function parseAiKeyExistsBody(body) {
+    const record = body;
+    if (typeof record !== 'object' ||
+        record === null ||
+        typeof record.credentialId !== 'string' ||
+        typeof record.organisationId !== 'string') {
+        throw new Error("ai's platform/keys route answered 200 with a body missing credentialId/organisationId");
+    }
+    return { credentialId: record.credentialId, organisationId: record.organisationId };
+}
+function parseAiKeyMintedBody(body) {
+    const record = body;
+    if (typeof record !== 'object' ||
+        record === null ||
+        typeof record.credentialId !== 'string' ||
+        typeof record.organisationId !== 'string' ||
+        typeof record.secret !== 'string') {
+        throw new Error("ai's platform/keys route answered 201 with a body missing credentialId/organisationId/secret");
+    }
+    return {
+        credentialId: record.credentialId,
+        organisationId: record.organisationId,
+        secret: record.secret,
+    };
+}
+/** The ref the AI management key is delivered under; the host's `AiOrganisationPort` adapter reads it back. */
+export const PLATFORM_AI_MANAGEMENT_KEY_REF = 'ai:platform:managementKey';
+/**
+ * What Archon's management key may do in ai: exactly `ai`'s own
+ * `ARCHON_AI_PERMISSIONS` (`apps/host/scripts/authz/bootstrap-archon.ts`) --
+ * configuration only (offerings, provisioning, offers, budgets, usage, cost)
+ * plus deleting (archiving) an organisation, never connections, runs or
+ * webhooks. ai's `/v1/platform/keys` route refuses any permission outside
+ * this same list, so a request for more than this is a 403, not a wider key.
+ */
+export const PLATFORM_AI_MANAGEMENT_PERMISSIONS = [
+    'ai.offerings:read',
+    'ai.offerings:create',
+    'ai.offerings:update',
+    'ai.offerings:disable',
+    'ai.organisations:provision',
+    'ai.organisations:offer',
+    'ai.organisations:delete',
+    'ai.keys:issue',
+    'ai.budgets:read',
+    'ai.budgets:update',
+    'ai.usage:read',
+    'ai.cost:read',
+];
+/** The ref the AI signing key's private half (PKCS#8 PEM) is delivered under -- the {@link INTEGRATIONS_MANAGEMENT_KEY_REF} pattern, for ai instead of integrations. */
+export const AI_SIGNING_KEY_REF = 'ai:platform:signingPrivateKey';
+/** `MANAGEMENT_ISSUER` on the ai runner: whoever signs with the delivered key signs as this issuer. */
+export const AI_MANAGEMENT_ISSUER = 'foundry';
+/** The key id the public half is pinned under in `MANAGEMENT_PUBLIC_KEYS` (ai's keyring allows `^[A-Za-z0-9_-]{1,100}$`). Fixed, since there is one key until rotation is built. */
+export const AI_MANAGEMENT_KEY_ID = 'foundry-1';
+/**
+ * ai's fixed application/platform identifier
+ * (`apps/host/src/lib/authz/policy-catalogue.ts`'s `PLATFORM_ID`), bound
+ * into every signed assertion's `platform` claim. foundry does not depend on
+ * that app, so the value is mirrored here rather than imported; a mismatch
+ * makes ai's `verifyManagementRequest` refuse every request.
+ */
+const AI_MANAGEMENT_PLATFORM_ID = 'wtfalch';
+/** The header ai's `service-assertion.ts` (`MANAGEMENT_HEADER`) reads the signed assertion from. */
+const AI_MANAGEMENT_HEADER = 'x-wtfalch-management';
+/** `service-assertion.ts`'s own signed-message prefix; the signature covers exactly `PREFIX + message`. */
+const AI_MANAGEMENT_ASSERTION_PREFIX = 'wtfalch.service-request.v1\n';
+/** `service-assertion.ts`'s own token TTL, in seconds. */
+const AI_MANAGEMENT_ASSERTION_TTL_SECONDS = 30;
+/**
+ * ai's signed-assertion `organisation` claim is required and validated as a
+ * uuid, but unused for tenant selection on the platform/keys route
+ * (`platform-keys-endpoint.ts`'s own comment: "callers may sign it as the
+ * nil uuid"). There is no organisation to name before one exists.
+ */
+const AI_MANAGEMENT_NIL_ORGANISATION = '00000000-0000-0000-0000-000000000000';
+/** ai's platform/keys route, relative to its internal address. */
+const AI_PLATFORM_KEYS_PATH = '/v1/platform/keys';
+/**
+ * Signs one request to ai's `POST /v1/platform/keys` the way ai's own
+ * `service-assertion.ts` (`signManagementRequest`) does. foundry does not
+ * depend on that app's code, so the wire format -- header, prefix, claim
+ * shape, digest -- is reproduced here exactly, rather than imported, so
+ * ai's `verifyManagementRequest` accepts it unmodified.
+ */
+function signAiManagementRequest(input) {
+    const digest = createHash('sha256').update(input.body).digest('hex');
+    const issued = Math.floor(input.now() / 1000);
+    const claims = {
+        version: 1,
+        issuer: input.issuer,
+        audience: input.audience,
+        platform: AI_MANAGEMENT_PLATFORM_ID,
+        subject: input.issuer,
+        organisation: AI_MANAGEMENT_NIL_ORGANISATION,
+        method: 'POST',
+        target: input.target,
+        contentType: input.contentType,
+        digest,
+        issued,
+        expires: issued + AI_MANAGEMENT_ASSERTION_TTL_SECONDS,
+        nonce: randomUUID(),
+    };
+    const payload = Buffer.from(JSON.stringify(claims)).toString('base64url');
+    const message = `${input.keyId}.${payload}`;
+    const signature = sign(null, Buffer.from(AI_MANAGEMENT_ASSERTION_PREFIX + message), input.privateKey).toString('base64url');
+    return `${message}.${signature}`;
+}
+/**
+ * The real {@link AiManagementKeyMinter}: signs a management assertion with
+ * `privateKeyPem` (the PKCS#8 PEM {@link provisionPlatformAi} delivers under
+ * {@link AI_SIGNING_KEY_REF} and pins on the runner under `keyId`) and calls
+ * ai's `POST /v1/platform/keys`. `audience` must be the exact origin ai's own
+ * `APP_URL` resolves to (`https://<platform.ai.hostname>`), since ai checks
+ * the claim against that env var, not against the internal address the
+ * request itself is sent to.
+ */
+export function createAiManagementKeyMinter(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const now = options.now ?? Date.now;
+    const privateKey = createPrivateKey(options.privateKeyPem);
+    return {
+        async mintManagementKey({ internalUrl, name, expiresDays, permissions }) {
+            const contentType = 'application/json';
+            const body = JSON.stringify({ name, expiresDays, permissions });
+            const token = signAiManagementRequest({
+                target: AI_PLATFORM_KEYS_PATH,
+                contentType,
+                body,
+                issuer: options.issuer,
+                audience: options.audience,
+                keyId: options.keyId,
+                privateKey,
+                now,
+            });
+            const response = await fetchImpl(`${internalUrl}${AI_PLATFORM_KEYS_PATH}`, {
+                method: 'POST',
+                headers: { 'content-type': contentType, [AI_MANAGEMENT_HEADER]: token },
+                body,
+                // A hung ai must not hold the apply open.
+                signal: AbortSignal.timeout(30_000),
+            });
+            if (response.status === 200) {
+                const existing = parseAiKeyExistsBody(await response.json());
+                throw new AiManagementKeyExistsError(existing.credentialId, existing.organisationId);
+            }
+            if (response.status === 409) {
+                throw new AiManagementKeyConflictError();
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new AiManagementKeyUntrustedError(response.status);
+            }
+            if (response.status !== 201) {
+                throw new Error(`ai's platform/keys route answered ${response.status}`);
+            }
+            return parseAiKeyMintedBody(await response.json());
+        },
+    };
+}
+const PLATFORM_AI_PROJECT = 'platform';
+const PLATFORM_AI_REPO = 'wtfalch/ai';
+const PLATFORM_AI_DB_NAME = 'ai-db';
+const PLATFORM_AI_POSTGRES_DB = 'ai';
+/**
+ * One app per build target of `wtfalch/ai`'s root Dockerfile (its
+ * `apps/host/README.md`, "Images and validation"). `target` is set as
+ * Coolify's `dockerfile_target_build`; `internalName` as the app's fixed
+ * `custom_internal_name`, the way `platform:auth` names its two apps.
+ */
+const PLATFORM_AI_MIGRATE = {
+    name: 'ai-migrate',
+    target: 'migration',
+    internalName: 'platform-ai-migrate',
+};
+const PLATFORM_AI_RUNNER = { name: 'ai', target: 'runner', internalName: 'platform-ai' };
+const PLATFORM_AI_WORKER = {
+    name: 'ai-worker',
+    target: 'worker',
+    internalName: 'platform-ai-worker',
+};
+/** The runner target's `EXPOSE 3000` / `PORT=3000`. */
+const PLATFORM_AI_PORT = '3000';
+const PLATFORM_AI_PROJECT_SCOPE_KEY = 'coolify_project_platform_ai';
+const PLATFORM_AI_DB_SCOPE_KEY = 'coolify_platform_ai_database';
+const PLATFORM_AI_MIGRATE_SCOPE_KEY = 'coolify_platform_ai_migrate_app';
+const PLATFORM_AI_RUNNER_SCOPE_KEY = 'coolify_platform_ai_app';
+const PLATFORM_AI_WORKER_SCOPE_KEY = 'coolify_platform_ai_worker_app';
+/**
+ * Written only when absent, never overwritten: an operator's own model list
+ * or worker bounds survive every apply. Values are `.env.example`'s, and
+ * `AI_MODELS=[]` is the README's "honest configuration for a host with no
+ * approved text model".
+ */
+const PLATFORM_AI_RUNNER_DEFAULTS = [
+    { key: 'AI_MODELS', value: '[]' },
+    { key: 'AI_FORGE_BINDINGS', value: '[]' },
+];
+const PLATFORM_AI_WORKER_DEFAULTS = [
+    ...PLATFORM_AI_RUNNER_DEFAULTS,
+    { key: 'AI_WORKER_BATCH', value: '10' },
+    { key: 'AI_WORKER_TIMEOUT_MS', value: '60000' },
+];
+/**
+ * #172: makes `coolify:app` keyed {@link PLATFORM_AI_KEY} true -- the ai host
+ * (https://github.com/wtfalch/ai) on the platform's Coolify, then foundry's
+ * own AI management key.
+ *
+ * The issue says to run the three parts "as `scripts/redeploy-dark.sh` in
+ * that repo runs them". No such script exists anywhere in that repo's
+ * history, so the shape here comes from what the repo does document: its
+ * root Dockerfile's `migration`, `runner` and `worker` targets and
+ * `apps/host/README.md`. One Coolify Postgres and three apps from the same
+ * repo and `gitRef`, one per target:
+ *
+ * - `ai-migrate` (`migration`) gets `DATABASE_URL_OWNER` (the database's
+ *   own superuser URL, the only app that ever sees it) and `DATABASE_URL`,
+ *   from which `db-runtime-role.sh` sets the `<database>_rt` role's password.
+ *   Its container stays up after migrating ("Coolify reads an exited
+ *   container as a failed deploy") and turns healthy once the marker file is
+ *   written, so this waits for `running:healthy` and then stops it.
+ * - `ai` (`runner`, port 3000) and `ai-worker` (`worker`, the continuously
+ *   polling `scripts/work.ts`) get only `DATABASE_URL`, the restricted
+ *   runtime role, plus the defaults in {@link PLATFORM_AI_WORKER_DEFAULTS}.
+ *
+ * Order: migrate first, wait, stop it, then the runner and worker, so neither
+ * ever starts against an unmigrated schema. A migrate job that does not turn
+ * healthy in time records {@link PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY}; the
+ * planner then reports the step blocked instead of timing out on every apply.
+ * A changed hostname or gitRef plans the step again (the applied values are
+ * recorded last): `git_branch` is patched on every run, `APP_URL` follows the
+ * hostname, and everything redeploys. The migration re-runs whenever
+ * either of the other two is (re)deployed; it is idempotent and additive.
+ * Coolify's auto-deploy on push is switched off on all three, because a push
+ * would otherwise redeploy runner and worker without the migration first.
+ *
+ * `DATABASE_URL` is minted once (a base64url password, the alphabet
+ * `db-runtime-role.sh` allows) and reused from whichever app already has it,
+ * never rotated: the role's password is set from it at every migration.
+ *
+ * The runner's internal address, `http://platform-ai:3000`, is recorded under
+ * {@link PLATFORM_AI_INTERNAL_URL_SCOPE_KEY}. Nothing public is wired: no
+ * Coolify `domains`, tunnel, DNS record or Access app. Whether ai gets
+ * `ai.<apex>` or stays internal like files is open (#172 "Decide"), and both
+ * answers only add to this. `APP_URL` is set from `platform.ai.hostname` as
+ * declared, since the host reads its own origin from it either way.
+ *
+ * The management key follows `platform:auth`'s admin-key discipline: the
+ * credential id is recorded as undelivered before the secret leaves this
+ * function, delivery is retried, and only a delivered key records the guard
+ * that skips the mint. The secret is never returned, recorded, logged or
+ * put in an error. The step's resource id is returned only after that, so
+ * the planner keeps planning the step until the key is delivered.
+ *
+ * #201 built the real minter: ai's `POST /v1/platform/keys`
+ * (github.com/wtfalch/ai/issues/141) mints the `archon` key over HTTP, signed
+ * with an Ed25519 pair this function mints and pins on the runner once
+ * ({@link ensureAiSigningKey}), the same two-key discipline as the
+ * management key itself. A test may still inject a different
+ * {@link AiManagementKeyMinter} in {@link PlatformAiDeps.managementKeyMinter},
+ * which skips the signing-key machinery entirely.
+ *
+ * Known gaps, left for review (#172 stays open for review):
+ * - Crash window: the credential id is recorded only after the minter
+ *   returns, so a crash between the mint and that record loses a key nobody
+ *   knows the id of. ai is idempotent by name, though, so the next apply's
+ *   mint call reaches the same live `archon` key rather than a second one --
+ *   it just cannot get the secret back, since ai shows it once. That is
+ *   reported as {@link PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY}, never
+ *   minted under another name.
+ * - Coolify's `dockerfile_target_build` and `is_auto_deploy_enabled` are set
+ *   through the generic application PATCH; neither has been checked against
+ *   a live instance from this package.
+ * - The key is minted for 90 days (the README's own examples); nothing
+ *   rotates it yet, so the platform loses its AI management key after 90 days.
+ * - Deploys are decided from the recorded "pending" mark and the app's own
+ *   status, not from a deployment's age: the port cannot read one.
+ * - Provider keys (`KEYS_WORKER_URL`, `KEYS_CREDENTIAL`, `KEYS_VERIFY_KEYS`)
+ *   and sign-in (`AUTH_*`) are not set: until an operator supplies them the
+ *   host answers `503 not_configured` for provider work, as its README says.
+ */
+async function provisionPlatformAi(context, deps) {
+    const { platform } = context;
+    const hostname = platform.ai.hostname;
+    const gitRef = platform.ai.gitRef;
+    const recorded = context.recordedIds();
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    const { coolify } = deps;
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    let projectUuid = recorded[PLATFORM_AI_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await coolify.findProjectByName(PLATFORM_AI_PROJECT);
+        projectUuid = found ? found.uuid : (await coolify.createProject(PLATFORM_AI_PROJECT)).uuid;
+        await record(PLATFORM_AI_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- database ----------------------------------------------------------
+    let dbId = recorded[PLATFORM_AI_DB_SCOPE_KEY];
+    if (!dbId) {
+        const found = (await coolify.listDatabases()).find((d) => d.name === PLATFORM_AI_DB_NAME && d.environment_id === environment.id);
+        if (found) {
+            dbId = found.uuid;
+        }
+        else {
+            const server = await resolvePlatformServer(coolify);
+            const created = await coolify.createPostgresDatabase({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                name: PLATFORM_AI_DB_NAME,
+                postgres_db: PLATFORM_AI_POSTGRES_DB,
+                postgres_user: PLATFORM_AI_POSTGRES_DB,
+            });
+            dbId = created.uuid;
+        }
+        await record(PLATFORM_AI_DB_SCOPE_KEY, dbId);
+    }
+    const db = await coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        throw new Error('coolify:app for the platform (ai): the database has no internal_db_url yet -- retry this apply once Coolify reports one');
+    }
+    const ownerUrl = db.internal_db_url;
+    // ---- the three apps ------------------------------------------------------
+    const ensureApp = async (spec, scopeKey) => {
+        const app = await findOrCreatePlatformApp(coolify, spec.name, environment, async () => {
+            const server = await resolvePlatformServer(coolify);
+            const githubApp = await coolify.requireGithubApp();
+            return coolify.createGithubAppApplication({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                github_app_uuid: githubApp.uuid,
+                git_repository: PLATFORM_AI_REPO,
+                git_branch: gitRef,
+                build_pack: 'dockerfile',
+                name: spec.name,
+            });
+        });
+        await record(scopeKey, app.appId);
+        // Set on every run, so a throw right after the create never leaves an app
+        // building the wrong target or deploying itself on a push.
+        const patch = {
+            custom_internal_name: spec.internalName,
+            dockerfile_target_build: spec.target,
+            is_auto_deploy_enabled: false,
+            // Every run, so a changed gitRef reaches an app that already exists.
+            git_branch: gitRef,
+        };
+        if (spec === PLATFORM_AI_RUNNER)
+            patch.ports_exposes = PLATFORM_AI_PORT;
+        await coolify.updateApplication(app.appId, patch);
+        return app;
+    };
+    const migrate = await ensureApp(PLATFORM_AI_MIGRATE, PLATFORM_AI_MIGRATE_SCOPE_KEY);
+    const runner = await ensureApp(PLATFORM_AI_RUNNER, PLATFORM_AI_RUNNER_SCOPE_KEY);
+    const worker = await ensureApp(PLATFORM_AI_WORKER, PLATFORM_AI_WORKER_SCOPE_KEY);
+    // ---- env -----------------------------------------------------------------
+    // Both database URLs are live credentials: handed to `bulkUpsertEnvs` and
+    // nowhere else, never returned, recorded, logged or put in an error.
+    const runtimeUrl = await ensureAiRuntimeUrl(coolify, [runner.appId, worker.appId, migrate.appId], ownerUrl);
+    const migrateEnvs = [
+        { key: 'DATABASE_URL_OWNER', value: ownerUrl },
+        { key: 'DATABASE_URL', value: runtimeUrl },
+    ];
+    const runnerEnvs = [
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        { key: 'APP_URL', value: `https://${hostname}` },
+        ...(await missingEnvs(coolify, runner.appId, PLATFORM_AI_RUNNER_DEFAULTS)),
+    ];
+    const workerEnvs = [
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        ...(await missingEnvs(coolify, worker.appId, PLATFORM_AI_WORKER_DEFAULTS)),
+    ];
+    // Whether anything the containers run on differs from what they last
+    // deployed with. Marked and persisted before the first write, and cleared
+    // only after the deploys below, so a run that fails halfway (the migrate
+    // wait throwing, for one) leaves the mark and the next run deploys again.
+    // #201: pin foundry's signing key before the deploy decision below, so the
+    // runner starts with MANAGEMENT_ISSUER/MANAGEMENT_PUBLIC_KEYS: Coolify env
+    // changes reach a container only on a redeploy. Only the real minter needs
+    // it; an injected one answers for its own authentication.
+    const signingKeyPem = !recorded[PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY] && !deps.managementKeyMinter
+        ? await ensureAiSigningKey(context, deps, runner.appId, runtime, sleep, record)
+        : undefined;
+    const migrateChanged = await envsDiffer(coolify, migrate.appId, migrateEnvs);
+    const runnerChanged = await envsDiffer(coolify, runner.appId, runnerEnvs);
+    const workerChanged = await envsDiffer(coolify, worker.appId, workerEnvs);
+    const declaredChanged = recorded[PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY] !== hostname ||
+        recorded[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY] !== gitRef;
+    const pending = Boolean(context.recordedIds()[PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY]) ||
+        migrateChanged ||
+        runnerChanged ||
+        workerChanged ||
+        declaredChanged;
+    if (pending)
+        await record(PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, '1');
+    await coolify.bulkUpsertEnvs(migrate.appId, migrateEnvs);
+    await coolify.bulkUpsertEnvs(runner.appId, runnerEnvs);
+    await coolify.bulkUpsertEnvs(worker.appId, workerEnvs);
+    const deployRunner = runner.justCreated || !runner.running || pending;
+    const deployWorker = worker.justCreated || !worker.running || pending;
+    const runMigration = migrate.justCreated || deployRunner || deployWorker;
+    // ---- migrate, wait, stop, then runner and worker ------------------------
+    if (runMigration) {
+        // A migrate container still up from an earlier run (one that threw before
+        // stopping it) would already read healthy. Stop it and wait until it
+        // reads stopped, so the wait below only ever sees the new deployment.
+        if (!migrate.justCreated && migrate.running) {
+            await coolify.raw('POST', `/applications/${migrate.appId}/stop`);
+            await waitForStopped(coolify, migrate.appId, runtime, sleep);
+        }
+        await coolify.deploy(migrate.appId);
+        try {
+            await waitForAiMigration(coolify, migrate.appId, runtime, sleep);
+        }
+        catch (error) {
+            if (error instanceof MigrationNotHealthyError) {
+                // Blocked from now on: the planner reports it and plans nothing until
+                // a person fixes the job and removes this key, instead of waiting out
+                // the timeout on every apply.
+                await record(PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, error.lastStatus);
+            }
+            throw error;
+        }
+        await coolify.raw('POST', `/applications/${migrate.appId}/stop`);
+    }
+    if (deployRunner)
+        await coolify.deploy(runner.appId);
+    if (deployWorker)
+        await coolify.deploy(worker.appId);
+    await record(PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, '');
+    // The deploys are done, so record what they deployed now. A later failure
+    // at the mint or delivery must not make the next apply see a changed
+    // hostname or gitRef and redeploy the live host again. The planner still
+    // plans the step until the resource id is recorded, once the key is delivered.
+    await record(PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    await record(PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, gitRef);
+    const internalUrl = `http://${PLATFORM_AI_RUNNER.internalName}:${PLATFORM_AI_PORT}`;
+    await record(PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, internalUrl);
+    // ---- Archon's AI management key, once ------------------------------------
+    const now = context.recordedIds();
+    if (!now[PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY]) {
+        const lost = now[PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY];
+        if (lost) {
+            throw new Error(`platform:ai: AI management key ${lost} was minted but never delivered; revoke it and remove the recorded key ${PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        // #201: a test injects its own minter; without one, build the real one
+        // over ai's own POST /v1/platform/keys, signed with the key pinned above.
+        const minter = deps.managementKeyMinter ??
+            createAiManagementKeyMinter({
+                privateKeyPem: signingKeyPem,
+                keyId: AI_MANAGEMENT_KEY_ID,
+                issuer: AI_MANAGEMENT_ISSUER,
+                audience: `https://${hostname}`,
+                fetchImpl: deps.fetchImpl,
+            });
+        let minted;
+        try {
+            minted = await minter.mintManagementKey({
+                internalUrl,
+                name: 'archon',
+                expiresDays: 90,
+                permissions: PLATFORM_AI_MANAGEMENT_PERMISSIONS,
+            });
+        }
+        catch (error) {
+            if (error instanceof AiManagementKeyExistsError) {
+                // ai already holds an 'archon' key this record never learned about
+                // (most likely the crash window below's own comment describes,
+                // happening one mint earlier): its secret cannot be shown again, so
+                // this is reported and never retried under another name.
+                await record(PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, error.credentialId);
+                throw new Error(`platform:ai: ai already holds a management key named 'archon' (${error.credentialId}) that foundry never recorded delivering; its secret cannot be shown again. Revoke it in ai and remove the recorded key ${PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY} to mint a new one`);
+            }
+            // Both messages below are fixed strings with no interpolated body, so
+            // safe to surface directly -- unlike the generic case, neither can
+            // ever echo a credential the minter read off the wire.
+            if (error instanceof AiManagementKeyConflictError) {
+                throw new Error(`platform:ai: ${error.message}`);
+            }
+            if (error instanceof AiManagementKeyUntrustedError) {
+                throw new Error(`platform:ai: ${error.message}`);
+            }
+            // The cause is dropped in case it echoes a credential.
+            throw new Error('platform:ai: the AI management key could not be minted (the minter failed; its error is not shown). Nothing was recorded; apply again');
+        }
+        const { credentialId, organisationId, secret } = minted;
+        await record(PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, credentialId);
+        await record(PLATFORM_AI_ORGANISATION_SCOPE_KEY, organisationId);
+        const attempts = runtime.deliverAttempts ?? 3;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await deps.deliverSecret(PLATFORM_AI_MANAGEMENT_KEY_REF, secret);
+                break;
+            }
+            catch {
+                // The cause is dropped in case it echoes the secret.
+                if (attempt >= attempts) {
+                    throw new Error(`platform:ai: AI management key ${credentialId} was minted but could not be delivered after ${attempts} tries`);
+                }
+                await sleep(1000 * attempt);
+            }
+        }
+        await record(PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, credentialId);
+    }
+    return { resourceId: runner.appId };
+}
+/**
+ * #201: ensures foundry's Ed25519 signing pair for ai's `POST
+ * /v1/platform/keys` exists, and returns the private half (PKCS#8 PEM)
+ * needed to sign the mint call that follows -- freshly minted this run, or
+ * read back via `deps.heldKeys` when an earlier run already delivered and
+ * pinned it but crashed before the management key itself was minted and
+ * delivered. Follows `platform:integrations`'s own two-key discipline
+ * exactly ({@link INTEGRATIONS_MANAGEMENT_KEY_REF}/`_ISSUER`/`_KEY_ID`): the
+ * id is recorded and persisted before the private half is delivered, the
+ * guard only once delivery and the pin on the runner both succeeded, so a
+ * crash in between never mints a second pair.
+ */
+async function ensureAiSigningKey(context, deps, runnerAppId, runtime, sleep, record) {
+    if (context.recordedIds()[PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY]) {
+        if (!deps.heldKeys) {
+            throw new Error('platform:ai: the AI management key cannot be minted: its signing key is already pinned but the host built the platform executor without a held-key reader to read back its private half (PlatformAiDeps.heldKeys)');
+        }
+        const held = await deps.heldKeys.resolve(AI_SIGNING_KEY_REF);
+        if (!held) {
+            throw new Error(`platform:ai: the AI management key cannot be minted: the signing key is pinned on the runner but its private half could not be read back (held key ${AI_SIGNING_KEY_REF})`);
+        }
+        return held;
+    }
+    if (context.recordedIds()[PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY]) {
+        throw new Error(`platform:ai: signing key ${AI_MANAGEMENT_KEY_ID} was minted but not confirmed delivered and pinned; not minting another. Check the held key and the runner's MANAGEMENT_PUBLIC_KEYS, then remove the recorded key ${PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+    }
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+    await record(PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, AI_MANAGEMENT_KEY_ID);
+    const attempts = runtime.deliverAttempts ?? 3;
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await deps.deliverSecret(AI_SIGNING_KEY_REF, privateKey);
+            break;
+        }
+        catch {
+            // The cause is dropped in case it echoes the key.
+            if (attempt >= attempts) {
+                throw new Error(`platform:ai: signing key ${AI_MANAGEMENT_KEY_ID} was minted but could not be delivered after ${attempts} attempts`);
+            }
+            await sleep(1000 * attempt);
+        }
+    }
+    // The runner reads these only after a redeploy: mark it pending first, so
+    // a crash between pinning and deploying still redeploys on the next apply.
+    await record(PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, '1');
+    await deps.coolify.bulkUpsertEnvs(runnerAppId, [
+        { key: 'MANAGEMENT_ISSUER', value: AI_MANAGEMENT_ISSUER },
+        {
+            key: 'MANAGEMENT_PUBLIC_KEYS',
+            value: JSON.stringify({ [AI_MANAGEMENT_KEY_ID]: publicKey }),
+        },
+    ]);
+    await record(PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, runnerAppId);
+    return privateKey;
+}
+/** The migrate job did not turn healthy in time; carries its last status, which holds no secret. */
+class MigrationNotHealthyError extends Error {
+    lastStatus;
+    constructor(lastStatus, message) {
+        super(message);
+        this.lastStatus = lastStatus;
+    }
+}
+/**
+ * Polls the app until Coolify reports it stopped (`exited`/`stopped`), so a
+ * healthy status read afterwards belongs to a deployment queued after this.
+ */
+async function waitForStopped(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.migrateTimeoutMs ?? 600_000;
+    const interval = runtime.migrateIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        if (status && !isRunningOrStarting(status))
+            return;
+        if (now() >= deadline) {
+            throw new Error(`platform:ai: the migrate job ${appId} did not stop within ${Math.round(timeout / 1000)}s (last status ${status ?? 'unknown'}); apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/**
+ * Polls the migrate app until Coolify reports it `running:healthy` -- the
+ * migration target's healthcheck passes only once `migrate.mjs` has finished
+ * -- or throws {@link MigrationNotHealthyError} once `migrateTimeoutMs` has
+ * passed. The caller stopped the app and saw it stopped before deploying, so
+ * a healthy status here is the new deployment's. Any other status (queued,
+ * building, exited, starting unhealthy) keeps waiting. On a timeout the job
+ * is left as it is: stopping it mid-migration is worse.
+ */
+async function waitForAiMigration(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.migrateTimeoutMs ?? 600_000;
+    const interval = runtime.migrateIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        await sleep(interval);
+        const { status } = await coolify.getApplication(appId);
+        if (status?.startsWith('running:healthy'))
+            return;
+        if (now() >= deadline) {
+            throw new MigrationNotHealthyError(status ?? 'unknown', `platform:ai: the migrate job ${appId} did not report healthy within ${Math.round(timeout / 1000)}s (last status ${status ?? 'unknown'}); the host and worker were not deployed. Check its logs; the step is blocked until the recorded key ${PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY} is removed`);
+        }
+    }
+}
+/**
+ * The runtime role's `DATABASE_URL`, reused from the first of `appIds` that
+ * already has one, else minted: `<database>_rt` (the name ai's
+ * `0001_runtime_role.sql` derives) with a fresh base64url password, on the
+ * owner URL's host, database and query string. The owner URL is parsed
+ * inside a try: Node's parse error carries the whole input, credential
+ * included, so it is replaced with a fixed message.
+ */
+async function ensureAiRuntimeUrl(coolify, appIds, ownerUrl) {
+    for (const appId of appIds) {
+        const existing = (await coolify.listEnvs(appId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview && e.value);
+        if (existing)
+            return existing.value;
+    }
+    let host;
+    let pathname;
+    let search;
+    try {
+        ({ host, pathname, search } = new URL(ownerUrl));
+    }
+    catch {
+        throw new Error("platform:ai: the database's internal_db_url could not be parsed");
+    }
+    const database = pathname.replace(/^\//, '');
+    if (!/^[A-Za-z0-9_]+$/.test(database)) {
+        throw new Error("platform:ai: the database's name cannot form a runtime role name (letters, digits and _ only)");
+    }
+    const password = randomBytes(24).toString('base64url');
+    return `postgres://${database}_rt:${password}@${host}${pathname}${search}`;
+}
+/** The entries of `defaults` whose key the app does not have yet. */
+async function missingEnvs(coolify, appId, defaults) {
+    const present = new Set((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => e.key));
+    return defaults.filter((d) => !present.has(d.key));
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Polls `url` until it answers 2xx, or throws once `readyTimeoutMs` has passed. */
+async function waitForInstance(url, runtime, sleep) {
+    const fetchImpl = runtime.fetch ?? globalThis.fetch;
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? 300_000;
+    const interval = runtime.readyIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        try {
+            const response = await fetchImpl(url);
+            if (response.ok)
+                return;
+        }
+        catch {
+            // Not up yet: DNS, the tunnel or the container.
+        }
+        if (now() >= deadline) {
+            throw new Error(`platform:auth: the new ZITADEL instance did not answer at ${url} within ${Math.round(timeout / 1000)}s; retry this apply`);
+        }
+        await sleep(interval);
+    }
+}
+async function resolvePlatformServer(coolify) {
+    const servers = await coolify.listServers();
+    const server = servers.find((s) => s.is_usable && s.is_reachable) ?? servers[0];
+    if (!server)
+        throw new Error('no usable Coolify server is registered on this instance');
+    return server;
+}
+/**
+ * `executor.ts`'s `coolifyCalls`/`findOrCreateCallsApp`, restated here rather
+ * than imported: that method is private to `FoundryStepExecutor`, and this
+ * file holds no instance of that class to call it on. `running` says whether
+ * the app was already running or starting; the caller deploys it when not.
+ */
+async function findOrCreatePlatformApp(coolify, name, environment, create) {
+    const existing = await coolify.findApplicationByName(name, { environmentIds: [environment.id] });
+    if (existing) {
+        const live = await coolify.getApplication(existing.uuid);
+        return {
+            appId: existing.uuid,
+            justCreated: false,
+            running: isRunningOrStarting(live.status),
+        };
+    }
+    const created = await create();
+    return { appId: created.uuid, justCreated: true, running: false };
+}
+/**
+ * #211: names of the envs the platform's sign-in broker (`wtfalch/auth`'s
+ * `broker/server.ts`) refuses to start without, that `provisionPlatformAuth`
+ * itself has no way to supply yet -- `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`
+ * (#209 mints and pushes this once it lands) and `RESEND_API_TOKEN` (#210,
+ * blocked on `wtfalch/auth#138`). Read from the broker's own live env, not a
+ * recorded scope id: whichever of #209/#210 lands first (or a human, setting
+ * either directly on the app) is enough to clear that one input, in either
+ * order, with no coupling to this step's own execution.
+ *
+ * #211 round 3: `AUTH_APPS` is a third required input -- the broker's own
+ * `parseApps` refuses to start with no `AUTH_APPS` set or an empty array
+ * (`wtfalch/auth/broker/src/apps.ts`), and this check used to name only the
+ * other two, so a deploy could go ahead with a broker that still would not
+ * come up. Also treat `null`/`undefined` as missing, not only `''`: the
+ * `CoolifyPort.listEnvs` doc comment already warns a live value does not
+ * always match its declared `string` type.
+ */
+async function missingBrokerInputs(coolify, brokerAppId) {
+    const envs = await coolify.listEnvs(brokerAppId);
+    const value = (key) => envs.find((e) => e.key === key && !e.is_preview && e.value != null && e.value !== '')?.value;
+    const has = (key) => value(key) !== undefined;
+    const missing = [];
+    if (!has('ZITADEL_SERVICE_USER_TOKEN') && !has('ZITADEL_SERVICE_USER_TOKEN_FILE')) {
+        missing.push('ZITADEL_SERVICE_USER_TOKEN');
+    }
+    if (!has('RESEND_API_TOKEN'))
+        missing.push('RESEND_API_TOKEN');
+    if (authAppsProblem(value('AUTH_APPS'), brokerAppId) !== null)
+        missing.push('AUTH_APPS');
+    return missing;
+}
+/**
+ * #211 round 5 addendum: why a live `AUTH_APPS` value would not pass the
+ * broker's own `parseApps` at boot, distinguishing `'missing'` (nothing set,
+ * or an empty array -- nobody has registered anything yet) from
+ * `'malformed'` (something is set and it is wrong: bad JSON, not an array, or
+ * an entry {@link validateBrokerAppEntry} itself refuses). `hasNonEmptyAuthApps`
+ * (#211 round 4) collapsed both into one `false`, so `missingBrokerInputs`
+ * (and, through it, `authBrokerBlockedReason`) always reported "it has no
+ * ... AUTH_APPS yet" even when `AUTH_APPS` held garbage a person needs to go
+ * fix, rather than an input nobody has supplied yet -- `authBrokerBlockedReason`
+ * below is what turns this distinction into different wording. `null` when
+ * the value is valid. A bad entry's own error is discarded here too: this
+ * function only classifies the problem, and the named error still surfaces
+ * wherever `readBrokerApps` is actually called.
+ */
+function authAppsProblem(raw, brokerAppId) {
+    if (raw === undefined || raw === '')
+        return 'missing';
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return 'malformed';
+    }
+    if (!Array.isArray(parsed))
+        return 'malformed';
+    if (parsed.length === 0)
+        return 'missing';
+    try {
+        parsed.forEach((entry, index) => validateBrokerAppEntry(entry, brokerAppId, index));
+    }
+    catch {
+        return 'malformed';
+    }
+    return null;
+}
+/**
+ * #211 round 5: sha256 of the exact `AUTH_APPS` string a {@link BrokerDeployRecord}
+ * names -- never the value itself, only its hash, so a recorded scope id can
+ * never leak another organisation's broker key. `undefined` (no `AUTH_APPS`
+ * set) hashes the same as `''`, both meaning "nothing deployed yet".
+ */
+function hashAuthApps(raw) {
+    return createHash('sha256')
+        .update(raw ?? '')
+        .digest('hex');
+}
+/**
+ * #211 round 5: the one rule `provisionPlatformAuth` and
+ * `provisionPlatformArchon` both call to decide whether the broker needs a
+ * (re)deploy -- replacing the two ad hoc "was it ever ostensibly deployed"
+ * booleans each function used to keep, which is what let a recreated broker,
+ * and a crash between writing `AUTH_APPS` and deploying, both go unnoticed
+ * (the round 5 issue text's own diagnosis: "they share one cause"). `false`
+ * while any required input is still missing -- deploying a broker that
+ * cannot start is pointless regardless of what changed. Otherwise `true`
+ * when nothing has ever been recorded, when the broker that was deployed is
+ * a different app (recreated under a new id), or when the `AUTH_APPS` that
+ * was deployed is not the `AUTH_APPS` that is live/about-to-be-live now.
+ * `authAppsRaw` is that exact string -- read live by `provisionPlatformAuth`,
+ * which never writes `AUTH_APPS` itself, or supplied by
+ * `provisionPlatformArchon` as the string it already knows it just wrote (or
+ * left unchanged), so neither caller needs a second read to agree with
+ * itself about what is now true of the app.
+ */
+function brokerDeployNeeded(missingInputs, brokerAppId, authAppsRaw, recordedDeploy) {
+    if (missingInputs.length > 0)
+        return false;
+    if (recordedDeploy === null)
+        return true;
+    if (recordedDeploy.brokerAppId !== brokerAppId)
+        return true;
+    return recordedDeploy.authAppsHash !== hashAuthApps(authAppsRaw);
+}
+/**
+ * #211 round 5: the {@link BrokerDeployRecord} JSON a successful deploy
+ * writes under {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} (via each
+ * caller's own `record()`), replacing the plain broker-id string round 2-4
+ * wrote there. Paired with {@link brokerDeployNeeded}, which reads it back.
+ */
+function brokerDeployRecordValue(brokerAppId, authAppsRaw) {
+    const record = { brokerAppId, authAppsHash: hashAuthApps(authAppsRaw) };
+    return JSON.stringify(record);
+}
+/** Whether any desired env is missing from the app, or set to another value. */
+async function envsDiffer(coolify, appId, desired) {
+    const live = new Map((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
+    return desired.some((e) => live.get(e.key) !== e.value);
+}
+/**
+ * `null` once the app already has this key set -- generated only the first
+ * time, never regenerated or overwritten, mirroring `executor.ts`'s
+ * `ensureAuthCookieSecret` exactly. #211 round 4: `''`, `null` and
+ * `undefined` all count as not set, the same "missing" a live Coolify
+ * response can carry despite its declared `string` type
+ * (`CoolifyPort.listEnvs`'s own doc comment) -- an entry present with one of
+ * those values used to read as "already has this key set" and return `null`,
+ * so a caller reading the value back afterwards (`provisionPlatformArchon`'s
+ * own `AUTH_APP_KEY`) threw "lost its ... between two reads" on every single
+ * apply instead of regenerating it.
+ *
+ * #211 round 5: `minLength`, when given, also counts a *present, non-empty*
+ * value shorter than it as not set -- the broker's own `parseApps`
+ * (`wtfalch/auth/broker/src/apps.ts`) refuses a `key` under 32 characters,
+ * and this package minted a 32-character `AUTH_APP_KEY` from the start
+ * (`provisionPlatformArchon`'s own comment on `randomBytes(32)`), so this
+ * only ever changes behaviour for a key that reached the app some other way
+ * -- a hand-set value, or one carried over from before that guarantee held.
+ * Optional, and unused by every other call site (`ensureMasterkey`,
+ * `ZITADEL_ADMIN_PASSWORD`, `AUTH_COOKIE_SECRET`, this file's recovery admin
+ * password): none of those have a broker-enforced minimum, so widening this
+ * check to them would reject a value that has always been fine.
+ */
+async function ensureGeneratedEnv(coolify, appId, key, generate, minLength) {
+    const envs = await coolify.listEnvs(appId);
+    const entry = envs.find((e) => e.key === key && !e.is_preview);
+    const already = entry !== undefined &&
+        entry.value != null &&
+        entry.value !== '' &&
+        (minLength === undefined || entry.value.length >= minLength);
+    if (already)
+        return null;
+    return generate();
+}
+/** The live value of `key` on `appId`, or `undefined` when unset -- `ensureGeneratedEnv`'s read half, for a caller that needs the value it already found. */
+async function currentEnvValue(coolify, appId, key) {
+    const envs = await coolify.listEnvs(appId);
+    return envs.find((e) => e.key === key && !e.is_preview)?.value;
+}
+/**
+ * {@link ensureGeneratedEnv} for `ZITADEL_MASTERKEY`, which encrypts what
+ * ZITADEL keeps in its database. A new key over a database ZITADEL has run
+ * against (one that existed before this run and had its app deployed) makes
+ * that data unreadable, so such a database never gets a generated one. The
+ * env is always written before the first deploy, so a missing key on a
+ * deployed app means someone removed it. This throws, and a person sets the key that database was
+ * initialised with (or deletes an unused database) and applies again.
+ */
+async function ensureMasterkey(coolify, appId, databaseInUse) {
+    const envs = await coolify.listEnvs(appId);
+    if (envs.some((e) => e.key === 'ZITADEL_MASTERKEY' && !e.is_preview))
+        return null;
+    if (databaseInUse) {
+        throw new Error(`platform:auth: app ${appId} has no ZITADEL_MASTERKEY but its database is already in use; not generating a new one. Set ZITADEL_MASTERKEY on that app to the key the database was initialised with, or delete the database if ZITADEL never ran on it, then apply again`);
+    }
+    return randomBytes(24).toString('base64');
+}
+/** `docs/deploy.md`: "ZITADEL_ADMIN_PASSWORD: 8+, upper, lower, digit, symbol". */
+function generateAdminPassword() {
+    return `${randomBytes(18).toString('base64')}Aa1!`;
+}
+/**
+ * #171: how the host signs a files management request with the key this step
+ * delivers under {@link FILES_MANAGEMENT_KEY_REF} (files'
+ * `signManagementRequest`'s `SigningIdentity`): `issuer` is
+ * {@link FILES_MANAGEMENT_ISSUER}, `keyId` is {@link FILES_MANAGEMENT_KEY_ID},
+ * `audience` is `https://<platform.files.hostname>` (the files host's
+ * `APP_URL`, which this step sets), and `privateKey` is the delivered PKCS#8
+ * PEM. Neither constant is a secret. The files host pins the public half
+ * through `MANAGEMENT_ISSUER`/`MANAGEMENT_PUBLIC_KEYS`, which this step sets.
+ */
+export const FILES_MANAGEMENT_ISSUER = 'foundry';
+export const FILES_MANAGEMENT_KEY_ID = 'foundry-1';
+/** The ref the management private key (PKCS#8 PEM) is delivered under. */
+export const FILES_MANAGEMENT_KEY_REF = 'files:platform:managementKey';
+/** The ref the files host's introspection client secret is delivered under. */
+export const FILES_INTROSPECTION_SECRET_REF = 'zitadel:platform:files:introspection';
+/** https://github.com/wtfalch/files -- root Dockerfile with `migration` and `runner` targets. */
+const FILES_REPO = 'wtfalch/files';
+const PLATFORM_FILES_PROJECT = 'platform';
+const PLATFORM_FILES_DB_NAME = 'platform-files-db';
+/** The two Coolify apps files' `apps/host/README.md` ("Deploying on Coolify") names. */
+const FILES_MIGRATE_APP_NAME = 'files-migrate';
+const FILES_RUNNER_APP_NAME = 'files';
+/**
+ * The runner's fixed `custom_internal_name`: the name another container on
+ * the Coolify network reaches it by, and so the host part of
+ * {@link PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY}'s recorded address.
+ */
+const FILES_RUNNER_INTERNAL_NAME = 'platform-files';
+/** The runner's port (`Dockerfile`'s `runner` stage: `PORT=3000`, `EXPOSE 3000`). */
+const FILES_PORT = '3000';
+/** The Postgres database name; files' runtime role is `<database>_rt`. */
+const FILES_DB = 'files';
+const FILES_RUNTIME_ROLE = `${FILES_DB}_rt`;
+const FILES_ZITADEL_PROJECT_NAME = 'files';
+const FILES_INTROSPECTION_APP_NAME = 'files-introspection';
+const PLATFORM_FILES_PROJECT_SCOPE_KEY = 'coolify_project_platform_files';
+const PLATFORM_FILES_DB_SCOPE_KEY = 'coolify_platform_files_database';
+const PLATFORM_FILES_MIGRATE_SCOPE_KEY = 'coolify_platform_files_migrate_app';
+const PLATFORM_FILES_RUNNER_SCOPE_KEY = 'coolify_platform_files_runner_app';
+/**
+ * #171: makes `coolify:app` keyed {@link PLATFORM_FILES_KEY} true -- the files
+ * host from https://github.com/wtfalch/files, on Coolify's internal network
+ * only, following its `apps/host/README.md` ("Deploying on Coolify"):
+ *
+ * 1. A Coolify Postgres (`files`), and two apps from the repo's root
+ *    Dockerfile: `files-migrate` (the `migration` target) and `files` (the
+ *    `runner` target, no domain, a fixed `custom_internal_name`).
+ * 2. In the platform's own sign-in: the `files` ZITADEL project (its id is the
+ *    person-token audience, `AUTH_PERSON_TOKEN_AUDIENCE`) and an API app, the
+ *    host's introspection client (`AUTH_PERSON_TOKEN_INTROSPECTION_*`).
+ * 3. Foundry's management key: an Ed25519 keypair minted here. The public
+ *    half is pinned on the runner (`MANAGEMENT_ISSUER`,
+ *    `MANAGEMENT_PUBLIC_KEYS`); the private half goes to the host as a held
+ *    key, which is what the org steps' `FilesOrganisationPort` signs with.
+ * 4. Deploy `files-migrate`, wait for it to report healthy, stop it, then
+ *    deploy `files`.
+ * 5. Record the runner's internal address and the ZITADEL project id.
+ *
+ * Both secrets are handed to {@link PlatformFilesDeps.deliverSecret} and
+ * written to the runner's env, and nowhere else: never returned, recorded,
+ * logged or put in a thrown error. Each is made only while its guard is
+ * unrecorded, and follows `platform:auth`'s admin-token pattern: an
+ * "undelivered" id is recorded and persisted the moment the secret is made,
+ * and the guard only after delivery AND the env write. A run that fails in
+ * between leaves an undelivered id with no guard; the planner reports that
+ * and never mints again, and a person clears the recorded key (and the
+ * ZITADEL client) to allow a new one.
+ *
+ * A re-run after a changed hostname or `gitRef` (recorded as applied scope
+ * ids) updates `git_branch` and the runner env and redeploys, and mints
+ * nothing.
+ *
+ * Known gaps, left for review:
+ * - The README says to wait for `files-migrate: done` in the migrate app's
+ *   logs. `CoolifyPort` cannot read logs, so this waits for Coolify to report
+ *   the app `running:healthy` instead. The `migration` stage's HEALTHCHECK
+ *   (`test -f /tmp/files-migrated`) passes on the file touched right before
+ *   that line is logged, so the two mean the same thing. The migrate app is stopped
+ *   before its deploy, so the poll cannot pass on a container left up by a
+ *   failed run. Whether Coolify's status still shows the old container for a
+ *   moment right after the deploy is not checked against a live Coolify.
+ * - The Dockerfile target is chosen by setting `dockerfile_target_build`
+ *   through `updateApplication`, since `createGithubAppApplication` has no
+ *   field for it. Not yet checked against a live Coolify.
+ * - The runner is created without `domains`, like `platform:auth`'s apps.
+ *   Whether Coolify adds a generated domain anyway is not yet checked.
+ * - Foundry sets only the env it owns: the two database URLs, `APP_URL`,
+ *   `AUTH_ISSUER`, `AUTH_PERSON_TOKEN_*`, `MANAGEMENT_*` and the two `KEYS_*`
+ *   values the host supplies through {@link PlatformFilesDeps.keys}, which
+ *   files-migrate needs to become healthy. The rest of files' `.env.example`
+ *   (`R2_*`, `KEYS_VERIFY_KEYS`, `JOBS_*`, `AUTHZ_BOOTSTRAP_OPERATOR`, ...)
+ *   is set by a person on the runner.
+ * - The files project lives in the platform's `foundry` ZITADEL org. An
+ *   org's Agora requests it as an audience scope from its own ZITADEL org;
+ *   whether that needs a project grant per org is not decided here.
+ * - The recorded address is reachable only from a container on the same
+ *   Coolify network, so the host must run there to use it for management
+ *   calls.
+ */
+async function provisionPlatformFiles(context, deps) {
+    const { platform } = context;
+    const gitRef = platform.files.gitRef;
+    const recorded = context.recordedIds();
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    const attempts = runtime.deliverAttempts ?? 3;
+    const keys = filesKeys(deps);
+    if (!keys) {
+        throw new Error('platform:files needs the keys worker URL and credential in its files dependencies (KEYS_WORKER_URL, KEYS_CREDENTIAL); files-migrate never becomes healthy without them');
+    }
+    // Never plan-and-throw: the planner reports a lost secret and plans
+    // nothing; this is the same rule for a caller that reaches the step anyway.
+    for (const [undeliveredKey, guardKey] of [
+        [PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY],
+        [PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY],
+    ]) {
+        const lost = recorded[undeliveredKey];
+        if (lost && !recorded[guardKey]) {
+            throw new Error(`platform:files: a secret (${lost}) was minted but never delivered; remove the recorded key ${undeliveredKey} to mint a new one`);
+        }
+    }
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    let projectUuid = recorded[PLATFORM_FILES_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await deps.coolify.findProjectByName(PLATFORM_FILES_PROJECT);
+        projectUuid = found
+            ? found.uuid
+            : (await deps.coolify.createProject(PLATFORM_FILES_PROJECT)).uuid;
+        await record(PLATFORM_FILES_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- database ----------------------------------------------------------
+    let dbId = recorded[PLATFORM_FILES_DB_SCOPE_KEY];
+    if (!dbId) {
+        // Found by name first, so a crash between create and record never makes
+        // a second one (`coolifyJobs` does the same).
+        const found = (await deps.coolify.listDatabases()).find((db) => db.name === PLATFORM_FILES_DB_NAME && db.environment_id === environment.id);
+        if (found) {
+            dbId = found.uuid;
+        }
+        else {
+            const server = await resolvePlatformServer(deps.coolify);
+            const created = await deps.coolify.createPostgresDatabase({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                name: PLATFORM_FILES_DB_NAME,
+                postgres_db: FILES_DB,
+                postgres_user: FILES_DB,
+            });
+            dbId = created.uuid;
+        }
+        await record(PLATFORM_FILES_DB_SCOPE_KEY, dbId);
+    }
+    const db = await deps.coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        throw new Error('coolify:app for the platform (files): the database has no internal_db_url yet -- retry this apply once Coolify reports one');
+    }
+    // ---- the two apps --------------------------------------------------------
+    const createFilesApp = (name) => async () => {
+        const server = await resolvePlatformServer(deps.coolify);
+        const githubApp = await deps.coolify.requireGithubApp();
+        return deps.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: FILES_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name,
+        });
+    };
+    const migrateApp = await findOrCreatePlatformApp(deps.coolify, FILES_MIGRATE_APP_NAME, environment, createFilesApp(FILES_MIGRATE_APP_NAME));
+    await record(PLATFORM_FILES_MIGRATE_SCOPE_KEY, migrateApp.appId);
+    // Set on every run, like `platform:auth`'s `custom_internal_name`: a throw
+    // right after a create must not leave the app on the wrong target.
+    // `git_branch` too, so a changed `gitRef` reaches an app made earlier.
+    await deps.coolify.updateApplication(migrateApp.appId, {
+        dockerfile_target_build: 'migration',
+        git_branch: gitRef,
+    });
+    const runnerApp = await findOrCreatePlatformApp(deps.coolify, FILES_RUNNER_APP_NAME, environment, createFilesApp(FILES_RUNNER_APP_NAME));
+    await record(PLATFORM_FILES_RUNNER_SCOPE_KEY, runnerApp.appId);
+    await deps.coolify.updateApplication(runnerApp.appId, {
+        dockerfile_target_build: 'runner',
+        custom_internal_name: FILES_RUNNER_INTERNAL_NAME,
+        git_branch: gitRef,
+    });
+    // ---- database env ----------------------------------------------------------
+    // The migrate app sets `files_rt`'s password from DATABASE_URL on every
+    // boot (files' `scripts/db-runtime-role.sh`), and the runner connects with
+    // the same URL, so both apps carry one value, minted once and never
+    // rotated: an existing value on either app is reused.
+    const runtimeUrl = await ensureFilesRuntimeUrl(deps.coolify, [migrateApp.appId, runnerApp.appId], db.internal_db_url);
+    // The keys worker the migrate app needs to become healthy (files' README:
+    // `DATABASE_URL_OWNER`, `DATABASE_URL`, `KEYS_WORKER_URL`, `KEYS_CREDENTIAL`).
+    const keysEnvs = [
+        { key: 'KEYS_WORKER_URL', value: keys.workerUrl },
+        { key: 'KEYS_CREDENTIAL', value: keys.credential },
+    ];
+    await deps.coolify.bulkUpsertEnvs(migrateApp.appId, [
+        { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        ...keysEnvs,
+    ]);
+    // ---- the files ZITADEL project, in the platform's sign-in ----------------
+    const issuer = `https://${platform.auth.hostname}`;
+    const zitadel = deps.zitadelForInstance?.(issuer) ?? deps.zitadel;
+    const { org } = await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+    const { project } = await zitadel.findOrCreateProject(org.id, FILES_ZITADEL_PROJECT_NAME);
+    await record(PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, project.id);
+    const runnerEnvs = [
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        // The management verifier's audience, which must be an HTTPS origin. The
+        // host has no public address, so this is a name, not a route.
+        { key: 'APP_URL', value: `https://${platform.files.hostname}` },
+        { key: 'AUTH_ISSUER', value: issuer },
+        { key: 'AUTH_PERSON_TOKEN_AUDIENCE', value: project.id },
+        ...keysEnvs,
+    ];
+    // Base env first, so a secret's own write below cannot be the only one
+    // that lands, and a re-run with a changed hostname updates `APP_URL`.
+    await deps.coolify.bulkUpsertEnvs(runnerApp.appId, runnerEnvs);
+    // ---- the introspection client, once --------------------------------------
+    if (!recorded[PLATFORM_FILES_INTROSPECTION_SCOPE_KEY]) {
+        // An app by this name here has no recorded secret (no undelivered id, or
+        // the throw above would have fired): a crash between the create and the
+        // record. Nothing was delivered, so it is deleted and made again.
+        const stale = (await zitadel.listApps(org.id, project.id)).filter((app) => app.name === FILES_INTROSPECTION_APP_NAME && app.state !== 'APP_STATE_REMOVED');
+        for (const app of stale) {
+            try {
+                await zitadel.deleteApp(org.id, project.id, app.id);
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+        }
+        const client = await zitadel.createApiApp(org.id, project.id, {
+            name: FILES_INTROSPECTION_APP_NAME,
+        });
+        // Recorded and persisted before the secret leaves this function: a failed
+        // delivery or env write is then reported by the planner, not remade.
+        await record(PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, client.appId);
+        await deliverWithRetry(deps.deliverSecret, FILES_INTROSPECTION_SECRET_REF, client.clientSecret, attempts, sleep, `the introspection client secret (ZITADEL app ${client.appId})`);
+        await deps.coolify.bulkUpsertEnvs(runnerApp.appId, [
+            { key: 'AUTH_PERSON_TOKEN_INTROSPECTION_CLIENT_ID', value: client.clientId },
+            { key: 'AUTH_PERSON_TOKEN_INTROSPECTION_CLIENT_SECRET', value: client.clientSecret },
+        ]);
+        await record(PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, client.appId);
+    }
+    // ---- foundry's management key, once --------------------------------------
+    if (!recorded[PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY]) {
+        const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+            publicKeyEncoding: { type: 'spki', format: 'pem' },
+            privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+        });
+        await record(PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, FILES_MANAGEMENT_KEY_ID);
+        await deliverWithRetry(deps.deliverSecret, FILES_MANAGEMENT_KEY_REF, privateKey, attempts, sleep, 'the files management key');
+        await deps.coolify.bulkUpsertEnvs(runnerApp.appId, [
+            { key: 'MANAGEMENT_ISSUER', value: FILES_MANAGEMENT_ISSUER },
+            {
+                key: 'MANAGEMENT_PUBLIC_KEYS',
+                value: JSON.stringify({ [FILES_MANAGEMENT_KEY_ID]: publicKey }),
+            },
+        ]);
+        await record(PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, FILES_MANAGEMENT_KEY_ID);
+    }
+    // ---- deploy: stop migrate, deploy it, wait, stop it, then the runner -----
+    // A failed run can leave `files-migrate` up and healthy from the last
+    // deploy. Stopped first, so the wait below cannot pass on the old
+    // container before the new migration has run.
+    await stopIfRunning(deps.coolify, migrateApp.appId);
+    await deps.coolify.deploy(migrateApp.appId);
+    await waitForMigration(deps.coolify, migrateApp.appId, runtime, sleep);
+    await deps.coolify.raw('POST', `/applications/${migrateApp.appId}/stop`);
+    await deps.coolify.deploy(runnerApp.appId);
+    await record(PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, `http://${FILES_RUNNER_INTERNAL_NAME}:${FILES_PORT}`);
+    // Last: a run that failed anywhere above is planned again.
+    context.recordScopeId(PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, platform.files.hostname);
+    await record(PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, gitRef);
+    return { resourceId: runnerApp.appId };
+}
+function filesKeys(deps) {
+    const keys = deps?.keys;
+    return keys?.workerUrl && keys.credential ? keys : null;
+}
+/** Stops the app when Coolify reports it running; a stop on an app that is not running can fail. */
+async function stopIfRunning(coolify, appId) {
+    const { status } = await coolify.getApplication(appId);
+    if (status?.startsWith('running'))
+        await coolify.raw('POST', `/applications/${appId}/stop`);
+}
+/**
+ * Hands `secret` to the host, retrying. The thrown error names `what` only,
+ * never the secret or the cause, which could echo it.
+ */
+async function deliverWithRetry(deliverSecret, ref, secret, attempts, sleep, what) {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await deliverSecret(ref, secret);
+            return;
+        }
+        catch {
+            if (attempt >= attempts) {
+                throw new Error(`platform:files: ${what} could not be delivered after ${attempts} tries; the next plan reports it as lost and mints no new one`);
+            }
+            await sleep(1000 * attempt);
+        }
+    }
+}
+/**
+ * The runtime `DATABASE_URL` both files apps share: the first one already set
+ * on either app, else a new `files_rt` credential on the database's host,
+ * built the way `executor.ts`'s `ensureCmsRuntimeUrl` builds `cms_rt`'s. A
+ * parse failure throws a message with no part of the URL in it, since the
+ * URL carries the superuser's password.
+ */
+async function ensureFilesRuntimeUrl(coolify, appIds, dbInternalUrl) {
+    for (const appId of appIds) {
+        const existing = (await coolify.listEnvs(appId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview && e.value);
+        if (existing)
+            return existing.value;
+    }
+    let host;
+    let pathname;
+    let search;
+    try {
+        ({ host, pathname, search } = new URL(dbInternalUrl));
+    }
+    catch {
+        throw new Error("coolify:app for the platform (files): the database's internal_db_url could not be parsed to build the runtime DATABASE_URL");
+    }
+    const password = randomBytes(24).toString('base64url');
+    return `postgres://${FILES_RUNTIME_ROLE}:${password}@${host}${pathname}${search}`;
+}
+/**
+ * Polls the migrate app until Coolify reports it `running:healthy` after
+ * first reporting anything else -- a healthy status before that is the old
+ * container, since the stop and deploy calls can return before Coolify's
+ * status catches up. The
+ * `migration` stage's HEALTHCHECK passes only once the migration has
+ * succeeded (see {@link provisionPlatformFiles}'s known gaps for why this
+ * stands in for the log line). Throws once `migrateTimeoutMs` has passed; the
+ * runner is then never deployed against an unmigrated database.
+ */
+async function waitForMigration(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.migrateTimeoutMs ?? 900_000;
+    const interval = runtime.migrateIntervalMs ?? 10_000;
+    const deadline = now() + timeout;
+    let left = false;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        if (status === 'running:healthy' && left)
+            return;
+        if (status !== 'running:healthy')
+            left = true;
+        if (now() >= deadline) {
+            throw new Error(`platform:files: files-migrate (${appId}) did not report healthy within ${Math.round(timeout / 1000)}s (last status: ${status ?? 'unknown'}); the files app was not deployed. Check its logs for "files-migrate: done" and retry this apply`);
+        }
+        await sleep(interval);
+    }
+}
+export const INTEGRATIONS_KEYS_ENV_NAMES = [
+    'KEYS_WORKER_URL',
+    'KEYS_CREDENTIAL',
+    'KEYS_VERIFY_KEYS',
+    'KEYS_AUDIT_TOKEN',
+];
+/** https://github.com/wtfalch/integrations -- one root Dockerfile, three targets. */
+const INTEGRATIONS_REPO = 'wtfalch/integrations';
+/**
+ * The three Coolify apps `apps/host/README.md`'s "Deploy: migrate, web,
+ * worker" names, each with the root Dockerfile target it builds.
+ */
+const INTEGRATIONS_MIGRATE_APP = { name: 'integrations-migrate', target: 'migration' };
+const INTEGRATIONS_RUNNER_APP = { name: 'integrations', target: 'runner' };
+const INTEGRATIONS_WORKER_APP = { name: 'integrations-worker', target: 'worker' };
+/** The runner's `EXPOSE 3000`; readiness is its own `HEALTHCHECK` on `/api/health`. */
+const INTEGRATIONS_RUNNER_PORT = '3000';
+const INTEGRATIONS_DB_NAME = 'integrations-db';
+/**
+ * The Postgres database and owner name. The host's runtime role is derived
+ * from the database, never configured: `drizzle/0001_runtime_role.sql`
+ * creates `current_database() || '_rt'`, so the runtime URL below must name
+ * exactly {@link INTEGRATIONS_RUNTIME_ROLE}.
+ */
+const INTEGRATIONS_POSTGRES_DB = 'integrations';
+const INTEGRATIONS_RUNTIME_ROLE = `${INTEGRATIONS_POSTGRES_DB}_rt`;
+/**
+ * `.env.example`'s own default. Only ever set when absent: every stored
+ * registration client secret is bound to this id, so foundry never
+ * overwrites a value a person changed.
+ */
+const INTEGRATIONS_OPERATOR_TENANT_ID = 'operator';
+/** `.env.example`'s own default for one worker pass; only ever set when absent. */
+const INTEGRATIONS_WORKER_BATCH = '50';
+const INTEGRATIONS_DATABASE_SCOPE_KEY = 'coolify_integrations_database';
+const INTEGRATIONS_MIGRATE_APP_SCOPE_KEY = 'coolify_integrations_migrate_app';
+const INTEGRATIONS_RUNNER_APP_SCOPE_KEY = 'coolify_integrations_app';
+const INTEGRATIONS_WORKER_APP_SCOPE_KEY = 'coolify_integrations_worker_app';
+/** Set (to the gitRef it migrated) once that ref's migration succeeded and the app was stopped. */
+const INTEGRATIONS_MIGRATED_SCOPE_KEY = 'integrations_migrated';
+/** The ref the management private key (PKCS#8 PEM) is delivered under. */
+export const INTEGRATIONS_MANAGEMENT_KEY_REF = 'integrations:management:privateKey';
+/** `MANAGEMENT_ISSUER` on the integrations host: whoever signs with the delivered key signs as this issuer. */
+export const INTEGRATIONS_MANAGEMENT_ISSUER = 'foundry';
+/**
+ * The key id the public half is pinned under in `MANAGEMENT_PUBLIC_KEYS`
+ * (the host's keyring allows `^[A-Za-z0-9_-]{1,100}$`). A signer names it in
+ * its signed request; fixed, since there is one key until rotation is built.
+ */
+export const INTEGRATIONS_MANAGEMENT_KEY_ID = 'foundry-1';
+/**
+ * #174: makes `coolify:app` keyed {@link PLATFORM_INTEGRATIONS_KEY} true --
+ * the integrations host (https://github.com/wtfalch/integrations) as its own
+ * `apps/host/README.md` ("Deploy: migrate, web, worker") describes it, in the
+ * shared `platform` Coolify project `coolify:jobs` uses:
+ *
+ * 1. A Postgres database (`integrations-db`), whose superuser URL is
+ *    `DATABASE_URL_OWNER` and whose `integrations_rt` runtime role gets a
+ *    password minted here once, as `DATABASE_URL` -- the same owner/runtime
+ *    split `executor.ts`'s `ensureCmsRuntimeUrl` builds for the cms app.
+ * 2. Three apps from the one repo, each on its own Dockerfile target (set by
+ *    `updateApplication`, since Coolify's create endpoint refuses
+ *    `dockerfile_target_build`): `integrations-migrate` (`migration`),
+ *    `integrations` (`runner`, at `hostname`) and `integrations-worker`
+ *    (`worker`). The host's own `@wtfalch/keys` settings
+ *    ({@link PlatformIntegrationsDeps.keysEnv}) are written to them.
+ * 3. The migrate app first, once per `gitRef`: stop it if running, deploy it,
+ *    wait until it reports healthy, stop it, and record the ref it migrated.
+ *    Only then are the runner and worker deployed.
+ * 4. The management key, once: an Ed25519 pair minted here, its id recorded
+ *    before delivery, its private half handed to
+ *    {@link PlatformIntegrationsDeps.deliverSecret} and its public half pinned
+ *    on the runner as `MANAGEMENT_PUBLIC_KEYS`, with `MANAGEMENT_ISSUER`. The
+ *    guard is recorded after both.
+ * 5. The applied `hostname` and `gitRef` are recorded last. A later change
+ *    plans the step again (`planIntegrations`), which patches `git_branch`
+ *    and the runner's `domains`, reruns the migration for a new ref, and
+ *    redeploys. It never mints the key again.
+ *
+ * Every part is safe to run again after a throw partway: each id is recorded
+ * and persisted as soon as its resource exists, and what to deploy is read
+ * from the live apps. Secrets -- the database URLs, the `KEYS_*` values and
+ * the private key -- go to `bulkUpsertEnvs`/`deliverSecret` and nowhere else:
+ * never returned, recorded, logged or put in an error.
+ *
+ * Known gaps, left for review:
+ * - "Wait for `integrations-migrate: done` in its logs" is approximated by
+ *   polling the app's Coolify `status` for `running:healthy`: `CoolifyPort`
+ *   has no way to read container logs. The `migration` target's own
+ *   `HEALTHCHECK` passes only once the file it touches right before printing
+ *   that line exists, so healthy means the same thing. `exited` never counts
+ *   as done.
+ * - The worker is created and deployed when created or changed, but nothing
+ *   schedules it. Its image runs one queue pass and exits, so Coolify's
+ *   scheduled tasks (which run a command in a *running* container) have no
+ *   container to run in, and `wtfalch/jobs` delivers a schedule as an HTTP
+ *   POST to a receiver route the integrations host does not have. Choosing
+ *   between such a route and a long-running worker image is a decision for
+ *   the integrations repo. Until then queued messages wait for a manual pass.
+ * - Changing `gitRef` to a ref that has new commits under the same name is
+ *   not seen: only a different ref name re-plans the step.
+ * - Like `coolify:jobs`, the runner is reached through its Coolify `domains`
+ *   binding; no Cloudflare tunnel or DNS record is created for `hostname`.
+ */
+async function provisionPlatformIntegrations(action, context, deps) {
+    const { coolify } = deps;
+    const hostname = action.desired.hostname;
+    const gitRef = action.desired.gitRef;
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    const recorded = context.recordedIds();
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    // ---- project and environment: the one shared `platform` project ---------
+    let projectUuid = recorded[JOBS_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await coolify.findProjectByName(PLATFORM_COOLIFY_PROJECT_NAME);
+        projectUuid = found
+            ? found.uuid
+            : (await coolify.createProject(PLATFORM_COOLIFY_PROJECT_NAME)).uuid;
+        await record(JOBS_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- database -------------------------------------------------------------
+    let dbId = recorded[INTEGRATIONS_DATABASE_SCOPE_KEY];
+    if (!dbId) {
+        const found = (await coolify.listDatabases()).find((db) => db.name === INTEGRATIONS_DB_NAME && db.environment_id === environment.id);
+        if (found) {
+            dbId = found.uuid;
+        }
+        else {
+            const server = await resolvePlatformServer(coolify);
+            const created = await coolify.createPostgresDatabase({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                name: INTEGRATIONS_DB_NAME,
+                postgres_db: INTEGRATIONS_POSTGRES_DB,
+                postgres_user: INTEGRATIONS_POSTGRES_DB,
+            });
+            dbId = created.uuid;
+        }
+        await record(INTEGRATIONS_DATABASE_SCOPE_KEY, dbId);
+    }
+    const db = await coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        throw new Error(`platform:integrations: database ${dbId} has no internal_db_url yet; not deploying the integrations host without a database`);
+    }
+    const ownerUrl = db.internal_db_url;
+    // ---- the three apps --------------------------------------------------------
+    const createApp = (name, domains) => async () => {
+        const server = await resolvePlatformServer(coolify);
+        const githubApp = await coolify.requireGithubApp();
+        return coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: INTEGRATIONS_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name,
+            ...(domains ? { domains } : {}),
+        });
+    };
+    const migrateApp = await findOrCreatePlatformApp(coolify, INTEGRATIONS_MIGRATE_APP.name, environment, createApp(INTEGRATIONS_MIGRATE_APP.name));
+    await record(INTEGRATIONS_MIGRATE_APP_SCOPE_KEY, migrateApp.appId);
+    const runnerApp = await findOrCreatePlatformApp(coolify, INTEGRATIONS_RUNNER_APP.name, environment, createApp(INTEGRATIONS_RUNNER_APP.name, hostname));
+    await record(INTEGRATIONS_RUNNER_APP_SCOPE_KEY, runnerApp.appId);
+    const workerApp = await findOrCreatePlatformApp(coolify, INTEGRATIONS_WORKER_APP.name, environment, createApp(INTEGRATIONS_WORKER_APP.name));
+    await record(INTEGRATIONS_WORKER_APP_SCOPE_KEY, workerApp.appId);
+    // Set on every run, not only after a create: a throw right after a create
+    // must not leave an app building the Dockerfile's last stage for good. The
+    // branch and the runner's domain are set here too, so a changed `gitRef` or
+    // `hostname` reaches an app that already exists.
+    const configChanged = recorded[PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY] !== hostname ||
+        recorded[PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY] !== gitRef;
+    await coolify.updateApplication(migrateApp.appId, {
+        dockerfile_target_build: INTEGRATIONS_MIGRATE_APP.target,
+        git_branch: gitRef,
+    });
+    await coolify.updateApplication(runnerApp.appId, {
+        dockerfile_target_build: INTEGRATIONS_RUNNER_APP.target,
+        ports_exposes: INTEGRATIONS_RUNNER_PORT,
+        git_branch: gitRef,
+        domains: hostname,
+    });
+    await coolify.updateApplication(workerApp.appId, {
+        dockerfile_target_build: INTEGRATIONS_WORKER_APP.target,
+        git_branch: gitRef,
+    });
+    // ---- env ---------------------------------------------------------------------
+    // One runtime URL for all three apps: the migrate job sets the role's
+    // password from it, and the runner and worker connect with it.
+    const runtimeUrl = await ensureIntegrationsRuntimeUrl(coolify, migrateApp.appId, ownerUrl);
+    const keys = INTEGRATIONS_KEYS_ENV_NAMES.map((key) => ({
+        key,
+        value: deps.keysEnv[key] ?? '',
+    }));
+    if (keys.some((k) => !k.value)) {
+        throw new Error('platform:integrations: the host supplies no value for the @wtfalch/keys settings; not deploying the integrations host');
+    }
+    const sharedEnvs = [
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        { key: 'APP_URL', value: `https://${hostname}` },
+        ...keys,
+    ];
+    const runnerEnvs = [
+        ...sharedEnvs,
+        ...(await envsIfAbsent(coolify, runnerApp.appId, [
+            { key: 'INTEGRATIONS_OPERATOR_TENANT_ID', value: INTEGRATIONS_OPERATOR_TENANT_ID },
+        ])),
+    ];
+    const workerEnvs = [
+        ...sharedEnvs,
+        ...(await envsIfAbsent(coolify, workerApp.appId, [
+            { key: 'INTEGRATIONS_OPERATOR_TENANT_ID', value: INTEGRATIONS_OPERATOR_TENANT_ID },
+            { key: 'INTEGRATIONS_WORKER_BATCH', value: INTEGRATIONS_WORKER_BATCH },
+        ])),
+    ];
+    const migrateEnvs = [
+        { key: 'DATABASE_URL_OWNER', value: ownerUrl },
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        ...keys.filter((k) => k.key === 'KEYS_WORKER_URL' || k.key === 'KEYS_CREDENTIAL'),
+    ];
+    const runnerEnvsChanged = await envsDiffer(coolify, runnerApp.appId, runnerEnvs);
+    const workerEnvsChanged = await envsDiffer(coolify, workerApp.appId, workerEnvs);
+    await coolify.bulkUpsertEnvs(migrateApp.appId, migrateEnvs);
+    await coolify.bulkUpsertEnvs(runnerApp.appId, runnerEnvs);
+    await coolify.bulkUpsertEnvs(workerApp.appId, workerEnvs);
+    // ---- migrate first, once per gitRef ---------------------------------------------
+    if (context.recordedIds()[INTEGRATIONS_MIGRATED_SCOPE_KEY] !== gitRef) {
+        // A running migrate app is stopped before the deploy is queued, so the old
+        // container's healthy status is never read as the new deployment's.
+        if (migrateApp.running)
+            await coolify.raw('POST', `/applications/${migrateApp.appId}/stop`);
+        await coolify.deploy(migrateApp.appId);
+        await waitForIntegrationsMigration(coolify, migrateApp.appId, runtime, sleep);
+        // It idles after migrating rather than exiting (the Dockerfile's own
+        // comment), so it is stopped here; a person starts it again for
+        // maintenance commands.
+        await coolify.raw('POST', `/applications/${migrateApp.appId}/stop`);
+        await record(INTEGRATIONS_MIGRATED_SCOPE_KEY, gitRef);
+    }
+    // ---- the management key, once --------------------------------------------------
+    // The pair's id is recorded and persisted before the private half is
+    // delivered. The guard is recorded only after delivery and the write of the
+    // public half. A run that dies in between leaves the id without the guard:
+    // the planner then reports the key and mints nothing, so a second pair can
+    // never replace one the host may already hold.
+    let keyJustSet = false;
+    if (!context.recordedIds()[PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY]) {
+        if (context.recordedIds()[PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY]) {
+            throw new Error(`platform:integrations: management key ${INTEGRATIONS_MANAGEMENT_KEY_ID} was minted but not confirmed delivered and pinned; not minting another. Check the held key and the runner's MANAGEMENT_PUBLIC_KEYS, then remove the recorded key ${PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+            publicKeyEncoding: { type: 'spki', format: 'pem' },
+            privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+        });
+        await record(PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, INTEGRATIONS_MANAGEMENT_KEY_ID);
+        const attempts = runtime.deliverAttempts ?? 3;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await deps.deliverSecret(INTEGRATIONS_MANAGEMENT_KEY_REF, privateKey);
+                break;
+            }
+            catch {
+                // Retried; the error is dropped in case it echoes the key.
+                if (attempt >= attempts) {
+                    throw new Error(`platform:integrations: management key ${INTEGRATIONS_MANAGEMENT_KEY_ID} was minted but could not be delivered after ${attempts} attempts`);
+                }
+                await sleep(1000 * attempt);
+            }
+        }
+        await coolify.bulkUpsertEnvs(runnerApp.appId, [
+            { key: 'MANAGEMENT_ISSUER', value: INTEGRATIONS_MANAGEMENT_ISSUER },
+            {
+                key: 'MANAGEMENT_PUBLIC_KEYS',
+                value: JSON.stringify({ [INTEGRATIONS_MANAGEMENT_KEY_ID]: publicKey }),
+            },
+        ]);
+        await record(PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, runnerApp.appId);
+        keyJustSet = true;
+    }
+    // ---- then the runner and the worker ------------------------------------------------
+    // Decided from the live state: an env change only reaches a container on its
+    // next deploy, and a stopped runner is deployed so an earlier failed deploy
+    // is retried. The worker exits after one pass by design, so "not running"
+    // says nothing about it and it is deployed only when created or changed.
+    if (runnerApp.justCreated ||
+        !runnerApp.running ||
+        runnerEnvsChanged ||
+        keyJustSet ||
+        configChanged) {
+        await coolify.deploy(runnerApp.appId);
+    }
+    if (workerApp.justCreated || workerEnvsChanged || configChanged) {
+        await coolify.deploy(workerApp.appId);
+    }
+    await record(PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    await record(PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, gitRef);
+    return { resourceId: runnerApp.appId };
+}
+/**
+ * The runtime `DATABASE_URL` already on the migrate app, or a new one:
+ * {@link INTEGRATIONS_RUNTIME_ROLE} with a password minted once from a
+ * URL-safe alphabet (the host's `db-runtime-role.sh` refuses anything but
+ * `A-Za-z0-9_.~-`), on the owner URL's host, database and query string --
+ * `executor.ts`'s `ensureCmsRuntimeUrl`, with the same rule: never rotated,
+ * because the migrate job set the live role's password from the first one.
+ * A parse failure throws a fixed message, never the URL (Node's own
+ * `ERR_INVALID_URL` carries the whole input, password included).
+ */
+async function ensureIntegrationsRuntimeUrl(coolify, migrateAppId, ownerUrl) {
+    const existing = (await coolify.listEnvs(migrateAppId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview && e.value);
+    if (existing)
+        return existing.value;
+    let host;
+    let pathname;
+    let search;
+    try {
+        ({ host, pathname, search } = new URL(ownerUrl));
+    }
+    catch {
+        throw new Error('platform:integrations: the database internal_db_url could not be parsed; not deploying the integrations host');
+    }
+    const password = randomBytes(24).toString('base64url');
+    return `postgres://${INTEGRATIONS_RUNTIME_ROLE}:${password}@${host}${pathname}${search}`;
+}
+/** The entries of `desired` whose key the app does not have yet -- never overwriting a value a person set. */
+async function envsIfAbsent(coolify, appId, desired) {
+    const live = new Set((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => e.key));
+    return desired.filter((e) => !live.has(e.key));
+}
+/**
+ * Polls the migrate app until Coolify reports it `running:healthy` after
+ * first reporting anything else -- a healthy status before that is the old
+ * container, since the stop and deploy calls can return before Coolify's
+ * status catches up. Its `HEALTHCHECK` passes only after
+ * `integrations-migrate: done` (see
+ * {@link provisionPlatformIntegrations}'s known gaps). Throws once
+ * `migrateTimeoutMs` has passed. The runner and worker are never deployed
+ * after a timeout.
+ */
+async function waitForIntegrationsMigration(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.migrateTimeoutMs ?? 20 * 60_000;
+    const interval = runtime.migratePollMs ?? 10_000;
+    const deadline = now() + timeout;
+    let left = false;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        const healthy = status?.startsWith('running:healthy') === true;
+        if (healthy && left)
+            return;
+        if (!healthy)
+            left = true;
+        if (now() >= deadline) {
+            throw new Error(`platform:integrations: integrations-migrate (${appId}) did not report healthy within ${Math.round(timeout / 1000)}s (last status: ${status ?? 'unknown'}); check its logs, then apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/**
+ * The real {@link PlatformCloudflareReader}: the platform's apex zone as
+ * `planApexZone` expects to see it, and nothing else. The zone's DNS records
+ * and tunnels belong to no declared platform step yet, so listing them would
+ * only report them unmanaged.
+ *
+ * The zone is fetched by the id the last apply recorded when there is one,
+ * because Cloudflare's zone list can lag a create; with no recorded id it is
+ * found by apex.
+ */
+export class ProvidersPlatformCloudflareReader {
+    client;
+    platformStore;
+    constructor(client, platformStore) {
+        this.client = client;
+        this.platformStore = platformStore;
+    }
+    async listResources() {
+        const platform = await this.platformStore.get();
+        if (!platform)
+            return [];
+        const recordedId = (await this.platformStore.getServiceIds())[apexZoneKey(platform.apex)];
+        const zone = (recordedId && (await recordedZone(this.client, recordedId, platform.apex))) ||
+            (await exactZone(this.client, platform.apex));
+        if (!zone)
+            return [];
+        return [
+            {
+                system: 'cloudflare',
+                kind: 'zone',
+                key: platform.apex,
+                config: { id: zone.id, status: zone.status, name_servers: zone.name_servers },
+            },
+        ];
+    }
+}
+/**
+ * #173: the real {@link PlatformCoolifyReader} for the jobs scheduler app --
+ * the recorded-id half of `ProvidersPlatformCloudflareReader`'s own strategy
+ * above, with no list-by-name fallback: unlike a Cloudflare zone (which
+ * exists before foundry ever touches it), the scheduler app has no identity
+ * to adopt until this package creates it, so "nothing recorded yet" and
+ * "nothing live yet" are the same state here. A recorded id Coolify no
+ * longer has (deleted, or moved) reads as not-live, the same "stale id never
+ * blocks planning for good" rule {@link recordedZone} follows.
+ */
+export class ProvidersPlatformCoolifyReader {
+    client;
+    platformStore;
+    constructor(client, platformStore) {
+        this.client = client;
+        this.platformStore = platformStore;
+    }
+    async listResources() {
+        const recordedId = (await this.platformStore.getServiceIds())[JOBS_APP_KEY];
+        if (!recordedId)
+            return [];
+        try {
+            const app = await this.client.getApplication(recordedId);
+            return [
+                {
+                    system: 'coolify',
+                    kind: 'jobs',
+                    key: JOBS_SCHEDULER_KEY,
+                    config: { uuid: app.uuid, status: app.status },
+                },
+            ];
+        }
+        catch {
+            return [];
+        }
+    }
+}
+/**
+ * `findZoneByApex` returns the longest suffix match, so for a subdomain it
+ * answers with the parent zone. The platform's zone is its apex exactly;
+ * any other zone is never adopted or reported as the platform's.
+ */
+async function exactZone(client, apex) {
+    const zone = await client.findZoneByApex(apex);
+    return zone && zone.name === apex ? zone : undefined;
+}
+/**
+ * The zone the last apply recorded, or `undefined` when Cloudflare no longer
+ * has it under that id (deleted, or moved to another account) or it is no
+ * longer the apex. The caller then falls back to finding it by apex, so a
+ * stale recorded id never blocks planning for good.
+ */
+async function recordedZone(client, id, apex) {
+    try {
+        const zone = await client.getZone(id);
+        return zone.name === apex ? zone : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * What Archon needs from each service before its step may run: the service's
+ * own applied step (`coolify:app:<stepKey>`), scope ids its step recorded, and
+ * held keys its step delivered. A missing one blocks Archon's plan. Archon
+ * only reads these; it never mints them.
+ */
+const ARCHON_SERVICE_INPUTS = {
+    files: {
+        stepKey: PLATFORM_FILES_KEY,
+        scopeKeys: [PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY],
+        refs: [FILES_MANAGEMENT_KEY_REF, FILES_INTROSPECTION_SECRET_REF],
+    },
+    ai: {
+        stepKey: PLATFORM_AI_KEY,
+        scopeKeys: [
+            PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY,
+            PLATFORM_AI_ORGANISATION_SCOPE_KEY,
+            PLATFORM_AI_INTERNAL_URL_SCOPE_KEY,
+        ],
+        refs: [PLATFORM_AI_MANAGEMENT_KEY_REF],
+    },
+    integrations: {
+        stepKey: PLATFORM_INTEGRATIONS_KEY,
+        scopeKeys: [],
+        refs: [INTEGRATIONS_MANAGEMENT_KEY_REF],
+    },
+};