@wtfalch/foundry 0.5.0 → 0.7.1

package/dist/plan/platform-providers.js

@@ -1,9 +1,10 @@
-import { generateKeyPairSync, randomBytes } from 'node:crypto';
+import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, randomUUID, sign, } from 'node:crypto';
 import { isIPv4 } from 'node:net';
+import { VERSIONS } from '../bootstrap/versions.js';
 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_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_MINTER_BLOCKED, PLATFORM_AI_ORGANISATION_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_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_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, platformMailMxHost, } from './platform-diff.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) {
@@ -67,6 +68,9 @@ const JOBS_SCHEDULER_REPO = 'wtfalch/jobs';
  * 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
@@ -120,6 +124,18 @@ export class FoundryPlatformStepExecutor {
         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);
@@ -150,8 +166,14 @@ export class FoundryPlatformStepExecutor {
         }
         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]) {
-            blocked.ai = PLATFORM_AI_MINTER_BLOCKED;
+            // 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) {
@@ -164,20 +186,43 @@ export class FoundryPlatformStepExecutor {
             }
             else {
                 const inputs = await collectArchonServiceInputs(platform, this.archon, recordedIds);
-                if ('blocked' in inputs)
+                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. */
+    /**
+     * 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 = {}) {
-        if (!platform.archon.enabled || !this.archon)
-            return {};
-        if (!recordedIds[`coolify:app:${PLATFORM_ARCHON_KEY}`])
-            return {};
-        const drifted = await archonAccessDrifted(this.archon.cloudflare, platform.archon.hostname, this.archon.accessEmails);
-        return drifted ? { archon: true } : {};
+        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) {
@@ -244,11 +289,25 @@ export class FoundryPlatformStepExecutor {
         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)');
         }
-        await applyCallsSfuPlatformStep(this.sfu);
+        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) {
@@ -367,6 +426,7 @@ 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
@@ -376,15 +436,18 @@ const PLATFORM_AUTH_LOGIN_APP_NAME = 'platform-auth-login';
  */
 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}`. */
+/** `wtfalch/auth`'s `docker-compose.yml`: `image: ghcr.io/zitadel/zitadel:${ZITADEL_VERSION:-v4.17.3}`. Pinned in `versions.json` (#247). */
 const AUTH_ZITADEL_IMAGE = 'ghcr.io/zitadel/zitadel';
-const AUTH_ZITADEL_IMAGE_TAG = 'v4.17.3';
+const AUTH_ZITADEL_IMAGE_TAG = VERSIONS.zitadel;
 /** `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
@@ -392,6 +455,8 @@ const AUTH_LOGIN_DOCKERFILE = 'login/Dockerfile';
  */
 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
@@ -400,6 +465,14 @@ const AUTH_LOGIN_PORT = '3000';
  * 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';
@@ -408,43 +481,252 @@ 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 and the zitadel-login app, 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").
+ * 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.
  *
- * Two apps, one public hostname, no third `proxy` app: `wtfalch/auth` splits
- * ZITADEL's API from its login UI 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`), 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. Neither 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.
+ * 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"):
- * - The login app never receives `ZITADEL_SERVICE_USER_TOKEN`. `wtfalch/auth`
- *   reads it from a bootstrap file two containers share inside one compose
- *   stack; two Coolify apps share none. The minted admin token must not go
- *   there (it is `IAM_OWNER`); a dedicated `IAM_LOGIN_CLIENT` machine user
- *   would need its own mint, delivery and redeploy. Sign-in through the login
- *   app is not proven working until that is wired.
+ * - ~~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.
  *
@@ -549,6 +831,28 @@ async function provisionPlatformAuth(context, deps) {
     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
@@ -588,13 +892,24 @@ async function provisionPlatformAuth(context, deps) {
         { 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) {
@@ -604,6 +919,31 @@ async function provisionPlatformAuth(context, deps) {
     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));
@@ -615,6 +955,11 @@ async function provisionPlatformAuth(context, deps) {
                 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' },
         ],
@@ -671,6 +1016,12 @@ async function provisionPlatformAuth(context, deps) {
         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)',
@@ -698,6 +1049,132 @@ async function provisionPlatformAuth(context, deps) {
         }
         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 };
 }
 // ---------------------------------------------------------------------------
@@ -818,13 +1295,15 @@ export const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = 'foundry:platform:admin';
  *   access-token `aud` check; whoever supplies
  *   {@link PlatformMailDeps.oidcAudience} must have registered one by hand
  *   until that is built.
- * - **The org step `coolify:mail`'s `MAIL_APEX`/`MAIL_HOST` constants
- *   (`executor.ts`) still point at the hand-built `wtfalch.dev` instance,
- *   not this one**, and the Lettermint team token it reads still comes from
- *   wherever the host already reads it, not held keys. Both need
+ * - **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.
+ *   -- 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;
@@ -1098,6 +1577,69 @@ async function mailBlockedReason(platform, mail, recordedIds) {
         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;
@@ -1222,15 +1764,25 @@ export const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = 'zitadel_platform_archon_clie
  * 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 two values this
- * step does generate (cookie secret, runtime-role password) go straight into
- * the app's env and nowhere else: never returned, recorded, logged or put in
- * an error.
+ * 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:
- * - `AUTH_APP_KEY`: the `auth.wtfalch.dev` broker's per-organisation
- *   registry key. The platform's new sign-in has no broker registration API,
- *   the same gap `executor.ts`'s `pushAppEnv` names for an org's app.
  * - `AUTHZ_BOOTSTRAP_OPERATOR`: the first operator's ZITADEL subject id. A
  *   person has to exist in the new instance first; not something foundry
  *   mints.
@@ -1280,6 +1832,13 @@ async function provisionPlatformArchon(context, deps) {
     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) {
@@ -1290,19 +1849,32 @@ async function provisionPlatformArchon(context, deps) {
         await record(PLATFORM_ARCHON_PROJECT_SCOPE_KEY, projectUuid);
     }
     const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // #265: a database already named `platform-archon-db` (the hand-deployed
+    // one) is adopted, never built a second time. One of that name in another
+    // environment is refused: adopting or duplicating it would split the data.
     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;
+        const named = (await deps.coolify.listDatabases()).filter((d) => d.name === PLATFORM_ARCHON_DB_NAME);
+        const found = named.find((d) => d.environment_id === environment.id);
+        if (!found && named.length > 0) {
+            throw new Error(`platform:archon: a database named ${PLATFORM_ARCHON_DB_NAME} exists outside the ${PLATFORM_ARCHON_PROJECT} project's production environment; refusing to adopt or duplicate it. Move or rename it in Coolify and apply again`);
+        }
+        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_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);
@@ -1311,6 +1883,12 @@ async function provisionPlatformArchon(context, deps) {
     }
     // ---- the app ----------------------------------------------------------------
     const app = await findOrCreatePlatformApp(deps.coolify, PLATFORM_ARCHON_APP_NAME, environment, async () => {
+        // #265: the lookup above is scoped to this environment, so a same-named
+        // app elsewhere is invisible to it. Making another one would give two
+        // `platform-archon` apps; refuse instead.
+        if (await deps.coolify.findApplicationByName(PLATFORM_ARCHON_APP_NAME)) {
+            throw new Error(`platform:archon: an application named ${PLATFORM_ARCHON_APP_NAME} exists outside the ${PLATFORM_ARCHON_PROJECT} project's production environment; refusing to create a second one. Move or rename it in Coolify and apply again`);
+        }
         const server = await resolvePlatformServer(deps.coolify);
         const githubApp = await deps.coolify.requireGithubApp();
         return deps.coolify.createGithubAppApplication({
@@ -1386,18 +1964,130 @@ async function provisionPlatformArchon(context, deps) {
         { 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' },
     ];
+    // #265: an owner URL or reporting site already on the app is kept as it is.
+    // The owner URL must name the adopted database's host, or the app's two
+    // database URLs would point at different databases.
+    const liveOwnerUrl = await currentEnvValue(deps.coolify, appId, 'DATABASE_URL_OWNER');
+    if (liveOwnerUrl) {
+        assertSameDatabaseHost('DATABASE_URL_OWNER', liveOwnerUrl, db.internal_db_url);
+    }
+    else {
+        envs.push({ key: 'DATABASE_URL_OWNER', value: db.internal_db_url });
+    }
+    if (!(await currentEnvValue(deps.coolify, appId, 'REPORTING_SITE'))) {
+        envs.push({ 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 () => {
@@ -1477,8 +2167,280 @@ async function provisionPlatformArchon(context, deps) {
     // 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
@@ -1558,6 +2520,33 @@ async function archonAccessDrifted(cf, domain, emails) {
         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
@@ -1633,10 +2622,34 @@ async function collectArchonServiceInputs(platform, deps, recorded) {
  * `base64url` fits `db-runtime-role.sh`'s password alphabet
  * (`A-Za-z0-9_.~-`).
  */
+/**
+ * #265: throws when `liveUrl` points at another host than the adopted
+ * database. Names both hosts and nothing else: a URL carries a credential, and
+ * Node's parse error echoes its whole input.
+ */
+function assertSameDatabaseHost(key, liveUrl, dbInternalUrl) {
+    const hostOf = (url) => {
+        try {
+            return new URL(url).host;
+        }
+        catch {
+            return null;
+        }
+    };
+    const liveHost = hostOf(liveUrl);
+    const dbHost = hostOf(dbInternalUrl);
+    if (liveHost !== dbHost) {
+        throw new Error(`platform:archon: ${key} on the app points at host ${liveHost ?? '(unparseable)'}, but the adopted database ${PLATFORM_ARCHON_DB_NAME} is at host ${dbHost ?? '(unparseable)'}; refusing to leave the app's database URLs on different databases`);
+    }
+}
 async function ensureArchonRuntimeUrl(coolify, appId, dbInternalUrl) {
     const envs = await coolify.listEnvs(appId);
-    if (envs.some((e) => e.key === 'DATABASE_URL' && !e.is_preview))
+    const live = envs.find((e) => e.key === 'DATABASE_URL' && !e.is_preview);
+    if (live) {
+        // #265: kept as it is, but it must name the adopted database's host.
+        assertSameDatabaseHost('DATABASE_URL', live.value, dbInternalUrl);
         return null;
+    }
     let host;
     let pathname;
     let search;
@@ -1651,22 +2664,213 @@ async function ensureArchonRuntimeUrl(coolify, appId, dbInternalUrl) {
     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 foundry's management key may do: exactly the grants `ai`'s README
- * ("Archon's first key", by-hand form) gives archon's key, which are the
- * ones `ai:organisation`, `ai:budget`, `ai:key` and the org destroy call.
+ * 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 message {@link provisionPlatformAi} throws when no {@link AiManagementKeyMinter} was supplied. */
-export const PLATFORM_AI_MINTER_MISSING = "platform:ai: the AI host is deployed but foundry's AI management key cannot be minted: no AiManagementKeyMinter was supplied (PlatformAiDeps.managementKeyMinter). ai mints its first platform credential only through its keys:issue-archon script run against the database (apps/host/scripts/authz/bootstrap-archon.ts); it has no HTTP route for that, and CoolifyPort cannot run a command inside a container (#172)";
+/** 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';
@@ -1761,22 +2965,22 @@ const PLATFORM_AI_WORKER_DEFAULTS = [
  * 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):
- * - No minter ships, so the step is blocked in the planner (nothing is
- *   deployed) until a host supplies an {@link AiManagementKeyMinter}. It
- *   cannot be built over ai's admin API: ai issues its first platform-tenant
- *   credential only from `apps/host/scripts/authz/bootstrap-archon.ts`
- *   (`keys:issue-archon`), a script that writes to the database directly and
- *   needs `AUTHZ_BOOTSTRAP_OPERATOR` and the `KEYS_*` settings. Its HTTP
- *   routes cannot bootstrap one: `POST /v1/organisations/{id}/keys` needs an
- *   existing `ai.keys:issue` key and refuses the platform tenant, and a
- *   signed management proof needs a human who already holds authority there.
- *   `CoolifyPort` has no call that runs a command in a container.
  * - 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 has no name or idempotency key on that path to find
- *   it again by; {@link AiManagementKeyMinter} therefore requires a minter to
- *   look up an existing key named `foundry` and return it before issuing one.
+ *   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.
@@ -1890,12 +3094,19 @@ async function provisionPlatformAi(context, deps) {
     // 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(recorded[PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY]) ||
+    const pending = Boolean(context.recordedIds()[PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY]) ||
         migrateChanged ||
         runnerChanged ||
         workerChanged ||
@@ -1945,28 +3156,50 @@ async function provisionPlatformAi(context, deps) {
     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);
-    // ---- foundry's AI management key, once -----------------------------------
+    // ---- 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`);
         }
-        const minter = deps.managementKeyMinter;
-        // The planner blocks the step while there is no minter; this is for a
-        // caller that reaches the step anyway.
-        if (!minter)
-            throw new Error(PLATFORM_AI_MINTER_MISSING);
+        // #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: 'foundry',
+                name: 'archon',
                 expiresDays: 90,
                 permissions: PLATFORM_AI_MANAGEMENT_PERMISSIONS,
             });
         }
-        catch {
+        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');
         }
@@ -1991,6 +3224,64 @@ async function provisionPlatformAi(context, deps) {
     }
     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;
@@ -2126,6 +3417,123 @@ async function findOrCreatePlatformApp(coolify, name, environment, create) {
     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]));
@@ -2134,15 +3542,43 @@ async function envsDiffer(coolify, appId, desired) {
 /**
  * `null` once the app already has this key set -- generated only the first
  * time, never regenerated or overwritten, mirroring `executor.ts`'s
- * `ensureAuthCookieSecret` exactly.
+ * `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) {
+async function ensureGeneratedEnv(coolify, appId, key, generate, minLength) {
     const envs = await coolify.listEnvs(appId);
-    const already = envs.some((e) => e.key === key && !e.is_preview);
+    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