@wtfalch/foundry 0.16.16 → 0.17.1

package/dist/plan/platform-providers.js

@@ -7,7 +7,7 @@ import { ensureCloudflaredConnector } from './cloudflared-connector.js';
 import { waitForDeploymentFinished, waitForHealthyVersion, waitForNewDeployment, } from './deploy-health.js';
 import { ACCESS_POLICY_NAME, getDatabaseStarted, isNotFoundError, isRunningOrStarting, } from './executor.js';
 import { coolifyDomains, filesShareHostname } from './hostnames.js';
-import { AUTH_ZITADEL_RUN_OPTIONS, 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_APPLIED_OPERATOR_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_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_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, 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_ID_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_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, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, archonBootstrapOperator, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
+import { AUTH_ZITADEL_RUN_OPTIONS, 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_APPLIED_OPERATOR_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF, PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_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_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, 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_ID_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_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, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_NAMES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_NAMES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF, PLATFORM_NAMES_KEY, PLATFORM_NAMES_KEY_REF, PLATFORM_NAMES_PLATFORM_KEY_SET_SCOPE_KEY, PLATFORM_NAMES_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY, archonBootstrapOperator, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
 import { applyCallsSfuPlatformStep } from './platform-sfu.js';
 import { CreateInstanceError, createZitadelInstance, generateSystemApiKeypair, instanceWithoutBearerMessage, systemApiUsersEnv, } from './zitadel-system-api.js';
 /** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
@@ -94,6 +94,9 @@ const JOBS_SCHEDULER_REPO = 'wtfalch/jobs';
  * #172 adds `coolify:app` keyed {@link PLATFORM_AI_KEY}, the platform's AI
  * host ({@link provisionPlatformAi}), once a host passes {@link PlatformAiDeps}.
  *
+ * #478 adds `coolify:app` keyed {@link PLATFORM_NAMES_KEY}, the names host
+ * ({@link provisionPlatformNames}), once a host passes {@link PlatformNamesDeps}.
+ *
  * #175 adds `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, Archon itself
  * ({@link provisionPlatformArchon}), once a host passes
  * {@link PlatformArchonDeps}.
@@ -113,6 +116,7 @@ export class FoundryPlatformStepExecutor {
     integrations;
     files;
     ai;
+    names;
     archon;
     backup;
     constructor(cloudflare, declaredOrgStore, options = {}) {
@@ -126,6 +130,7 @@ export class FoundryPlatformStepExecutor {
         this.integrations = options.integrations;
         this.files = options.files;
         this.ai = options.ai;
+        this.names = options.names;
         this.archon = options.archon;
         this.backup = options.backup;
     }
@@ -212,6 +217,15 @@ export class FoundryPlatformStepExecutor {
             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.names.enabled && !this.names) {
+            blocked.names =
+                'the names host is blocked, not planned: the host built the platform executor without its names dependencies';
+        }
+        else if (platform.names.enabled && this.names) {
+            const namesBlocked = await namesBlockedReason(this.names);
+            if (namesBlocked)
+                blocked.names = namesBlocked;
+        }
         if (platform.archon.enabled) {
             if (!this.archon) {
                 blocked.archon =
@@ -262,7 +276,17 @@ export class FoundryPlatformStepExecutor {
             const bootstrapOperatorDrifted = !accessDrifted &&
                 !brokerDrifted &&
                 (await archonBootstrapOperatorDrifted(this.archon.coolify, recordedIds[`coolify:app:${PLATFORM_ARCHON_KEY}`], recordedIds));
-            if (accessDrifted || brokerDrifted || bootstrapOperatorDrifted)
+            // #480: re-reads the live app's rolling-update/health-check settings
+            // even once `PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY` is
+            // recorded -- that marker only ever proves one past apply patched them,
+            // and nothing else notices a later hand-edit in the Coolify UI turning
+            // `is_consistent_container_name_enabled` back on or the health check
+            // back off.
+            const rollingUpdateDrifted = !accessDrifted &&
+                !brokerDrifted &&
+                !bootstrapOperatorDrifted &&
+                (await archonRollingUpdateDrifted(this.archon.coolify, recordedIds[`coolify:app:${PLATFORM_ARCHON_KEY}`]));
+            if (accessDrifted || brokerDrifted || bootstrapOperatorDrifted || rollingUpdateDrifted)
                 result.archon = true;
         }
         if (platform.auth.enabled && this.auth) {
@@ -351,6 +375,12 @@ export class FoundryPlatformStepExecutor {
             }
             return provisionPlatformAi(context, this.ai);
         }
+        if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_NAMES_KEY) {
+            if (!this.names) {
+                throw new Error('platform:names needs FoundryPlatformStepExecutor to be constructed with its names dependencies (#478)');
+            }
+            return provisionPlatformNames(context, this.names);
+        }
         if (action.system === 'coolify' &&
             action.kind === 'app' &&
             action.key === PLATFORM_ARCHON_KEY) {
@@ -2314,6 +2344,24 @@ const PLATFORM_ARCHON_CLOUDFLARED_APP_NAME = 'platform-archon-cloudflared';
 /** https://github.com/wtfalch/archon: one Dockerfile at its root, `runner` stage on port 3000. */
 const ARCHON_REPO = 'wtfalch/archon';
 const ARCHON_PORT = '3000';
+/**
+ * #480: Archon's own health route (`@wtfalch/reporting`'s `healthHandler`,
+ * the same one `waitForHealthyVersion` below already polls over the public
+ * hostname once the tunnel exists).
+ */
+const ARCHON_HEALTH_CHECK_PATH = '/api/health';
+/**
+ * #480: Coolify stops the old container as soon as its own health check
+ * passes against the new one. Archon's container runs `migrate.mjs` (over a
+ * hundred migrations, append-only and fast individually) and then boots
+ * Next.js before it answers anything, so a check run from the moment the
+ * container starts would fail and fail again until Coolify gave up. A start
+ * period this long means Coolify does not count a failing check against the
+ * new container until this many seconds after it starts -- long enough for
+ * the slowest migration run plus boot seen so far, with margin; there is no
+ * live measurement to pin it to instead.
+ */
+const ARCHON_HEALTH_CHECK_START_PERIOD_SECONDS = 30;
 /**
  * The name of foundry's own Cloudflare Access app in front of Archon. Same
  * `foundry:<key>` convention `executor.ts`'s `cloudflareAccess` uses for an
@@ -2365,7 +2413,15 @@ export const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = 'zitadel_platform_archon_clie
  *   does not parse fails the step without printing it.
  * - For each of files, ai, integrations and jobs that the platform declares
  *   enabled: its `https://<hostname>` URL, and its management key when
- *   {@link PlatformArchonDeps.heldKeys} holds one.
+ *   {@link PlatformArchonDeps.heldKeys} holds one. Files also gets
+ *   `FILES_ORGANISATION_ID` (`platform.ownerOrgId`, Company Included's own
+ *   Files organisation -- `executor.ts`'s `filesOrganisation` provisions it
+ *   under that same id) and its signed-assertion identity
+ *   (`FILES_MANAGEMENT_ISSUER`, `_KEY_ID`, `_PRIVATE_KEY`; #436).
+ * - `COOLIFY_URL`/`COOLIFY_READ_TOKEN` for `/backups`, once a human has
+ *   created a Coolify token scoped to read only and held it under
+ *   {@link PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF} -- that ref's own doc
+ *   comment says why foundry cannot mint one itself (#436).
  *
  * The OIDC client is ZITADEL's public web client (authorization code with
  * PKCE, no client secret: `createOidcApp` never returns one, see
@@ -2397,10 +2453,7 @@ export const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = 'zitadel_platform_archon_clie
  *   steps are exported by those steps' own modules. A
  *   missing one blocks the plan (`blockedSteps`); it is never skipped. The
  *   env names `AI_*`, `INTEGRATIONS_*`, `JOBS_URL` and `JOBS_ADMIN_TOKEN` are
- *   this step's proposal; Archon reads only `FILES_URL` and
- *   `FILES_MANAGEMENT_KEY` of these today. Files' signed-assertion identity
- *   (`FILES_MANAGEMENT_ISSUER`, `_KEY_ID`, `_PRIVATE_KEY`, `_SCOPE`) and
- *   `FILES_ORGANISATION_ID` are not wired.
+ *   this step's proposal.
  * - The step plans again when the hostname, `gitRef` or the Access policy's
  *   include list changes. Env for a service enabled later is not pushed until
  *   one of those changes.
@@ -2408,6 +2461,24 @@ export const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = 'zitadel_platform_archon_clie
  *   the tunnel hostname, deletes the Access app and builds it again.
  * - #197: a `cloudflared` connector runs for this tunnel, as in `provisionPlatformAuth`.
  * - Retiring `operator.wtfalch.dev` stays a human step.
+ * - #475: deploys this app with a stable `custom_network_aliases` instead of a
+ *   fixed `custom_internal_name`, so Coolify runs its rolling update (start
+ *   the new container, wait for health, then stop the old one) instead of
+ *   stopping the old container first -- the cause of the #475 incident.
+ * - #480: also sends `health_check_enabled: true`,
+ *   `health_check_path: '/api/health'` and `health_check_port: 3000` on
+ *   every run, plus a start period long enough for Archon's migrations and
+ *   boot ({@link ARCHON_HEALTH_CHECK_START_PERIOD_SECONDS}). Without a
+ *   health check Coolify's rolling update has nothing to wait on and stops
+ *   the old container immediately -- the #475 fix alone was not enough, and
+ *   the live app only answered a health check because someone had set this
+ *   by hand outside foundry. {@link archonRollingUpdateDrifted} re-reads
+ *   these settings (and the #475 ones) at plan time, so a human turning any
+ *   of them back off in the Coolify UI is noticed and repaired, not just a
+ *   platform that applied before this patch existed. The same fix for
+ *   `platform:auth`, `platform:files`, `platform:ai` and the calls stack's
+ *   stateless app is deliberately left to a follow-up once each image's
+ *   health probe is confirmed.
  */
 async function provisionPlatformArchon(context, deps) {
     const { platform } = context;
@@ -2514,8 +2585,30 @@ async function provisionPlatformArchon(context, deps) {
     // right after the create must not leave it unnamed for good.
     // `git_branch` is patched too, so a changed `gitRef` reaches the app; the
     // deploy below is decided from the last applied `gitRef`.
+    //
+    // #475: `custom_network_aliases` (a stable Docker-network DNS name) plus
+    // `is_consistent_container_name_enabled: false`, not the old
+    // `custom_internal_name` alone -- a fixed *container* name is what disables
+    // Coolify's rolling update (the new container cannot take a name the old
+    // one still holds), while a fixed *alias* lets Coolify name each container
+    // uniquely and still answer `http://platform-archon:3000` (the tunnel
+    // ingress below) throughout the swap. Same string as before, so nothing
+    // downstream changes.
+    //
+    // #480: the health check fields too, every run -- the rolling update above
+    // has nothing to wait on without one, so Coolify stops the old container
+    // immediately regardless of the alias/consistent-name patch. This was
+    // live on platform-archon already, set by hand outside foundry; sending it
+    // here means a freshly provisioned platform gets it too, and a human
+    // turning it back off is repaired the same way `is_consistent_container_name_enabled`
+    // is (see `archonRollingUpdateDrifted`).
     await deps.coolify.updateApplication(appId, {
-        custom_internal_name: PLATFORM_ARCHON_INTERNAL_NAME,
+        custom_network_aliases: PLATFORM_ARCHON_INTERNAL_NAME,
+        is_consistent_container_name_enabled: false,
+        health_check_enabled: true,
+        health_check_path: ARCHON_HEALTH_CHECK_PATH,
+        health_check_port: Number(ARCHON_PORT),
+        health_check_start_period: ARCHON_HEALTH_CHECK_START_PERIOD_SECONDS,
         git_branch: gitRef,
     });
     // ---- sign-in client in the platform's own ZITADEL -------------------------
@@ -2581,7 +2674,8 @@ async function provisionPlatformArchon(context, deps) {
     else {
         envs.push({ key: 'DATABASE_URL_OWNER', value: db.internal_db_url });
     }
-    if (!(await currentEnvValue(deps.coolify, appId, 'REPORTING_SITE'))) {
+    const liveReportingSite = await currentEnvValue(deps.coolify, appId, 'REPORTING_SITE');
+    if (!liveReportingSite) {
         envs.push({ key: 'REPORTING_SITE', value: 'archon' });
     }
     const cookieSecret = await ensureGeneratedEnv(deps.coolify, appId, 'AUTH_COOKIE_SECRET', () => randomBytes(32).toString('base64'));
@@ -2590,6 +2684,25 @@ async function provisionPlatformArchon(context, deps) {
     const runtimeUrl = await ensureArchonRuntimeUrl(deps.coolify, appId, db.internal_db_url);
     if (runtimeUrl)
         envs.push({ key: 'DATABASE_URL', value: runtimeUrl });
+    // #467: `envs` above only ever carries these four keys on the run that
+    // generates or adopts them -- a later run that keeps them as they are
+    // pushes none of it, so `envs` itself shrinks from one run to the next
+    // with nothing having actually changed. `hashArchonEnvs` below hashes
+    // `envs` plus this map's values instead of `envs` alone, so the hash
+    // reflects the env Archon actually ends up running with, not just this
+    // run's delta.
+    const archonEnvHashOverrides = new Map([
+        ['DATABASE_URL_OWNER', liveOwnerUrl ?? db.internal_db_url],
+        ['REPORTING_SITE', liveReportingSite ?? 'archon'],
+    ]);
+    const effectiveCookieSecret = cookieSecret ?? (await currentEnvValue(deps.coolify, appId, 'AUTH_COOKIE_SECRET'));
+    if (effectiveCookieSecret) {
+        archonEnvHashOverrides.set('AUTH_COOKIE_SECRET', effectiveCookieSecret);
+    }
+    const effectiveRuntimeUrl = runtimeUrl ?? (await currentEnvValue(deps.coolify, appId, 'DATABASE_URL'));
+    if (effectiveRuntimeUrl) {
+        archonEnvHashOverrides.set('DATABASE_URL', effectiveRuntimeUrl);
+    }
     // `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
@@ -2630,8 +2743,53 @@ async function provisionPlatformArchon(context, deps) {
     // unflagged, Coolify writes it into `.env` unquoted and the container never
     // starts.
     envs.push(...inputs.envs.map((e) => (e.value.includes('\n') ? { ...e, multiline: true } : e)));
+    // #436: /backups needs a Coolify token scoped to read only, never the
+    // root token `putArchonMasterKeys` above already held. Nothing mints that
+    // token over Coolify's API (this ref's own doc comment), so until a human
+    // creates one and holds it under PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF,
+    // this pushes nothing and /backups keeps showing its own "set COOLIFY_URL
+    // and COOLIFY_READ_TOKEN" message -- never a reason to block the rest of
+    // this step.
+    const coolifyReadToken = await deps.heldKeys.resolve(PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF);
+    if (coolifyReadToken) {
+        const coolifyUrl = await deps.heldKeys.resolve(PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF);
+        if (coolifyUrl) {
+            envs.push({ key: 'COOLIFY_URL', value: coolifyUrl }, { key: 'COOLIFY_READ_TOKEN', value: coolifyReadToken });
+        }
+    }
     const changed = await envsDiffer(deps.coolify, appId, envs);
+    // #467: this run's intended env set, hashed before anything below writes
+    // it -- compared against {@link PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY}
+    // (that constant's own doc comment explains why `changed` above, which
+    // only ever reads the *live* store, cannot catch a crash or a failed
+    // deploy between this run's write and its confirmation).
+    const envsHash = hashArchonEnvs(envs, archonEnvHashOverrides);
+    const envsHashChanged = recorded[PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY] !== envsHash;
     await deps.coolify.bulkUpsertEnvs(appId, envs);
+    // #436 round 2: `bulkUpsertEnvs` only adds or updates, so the
+    // `FILES_MANAGEMENT_KEY` this step used to write before the fix above
+    // would otherwise survive on an Archon already deployed with it --
+    // `filesManagementFetch` checks that var first, so a stale copy kept
+    // steering it into the issued-key path this issue's wiring fixes, and it
+    // left a second copy of the private key sitting in Coolify. Every row
+    // under this key, including `listEnvs`'s own preview duplicate, is
+    // deleted outright -- never overwritten, which would still leave a row.
+    //
+    // #462: the deletes happen after `changed` is already computed above, so
+    // a retry that finds the envs already matching (`changed` false) but a
+    // stale `FILES_MANAGEMENT_KEY` row still present must still redeploy --
+    // the running container otherwise keeps reading the stale key out of its
+    // own process env until someone redeploys by hand. `staleKeyDeleted`
+    // feeds `archonDeployedNow` below for exactly that case; `envsHashChanged`
+    // above does not cover it, because the key's removal is never part of
+    // what either hash names (#467).
+    let staleKeyDeleted = false;
+    for (const stale of await deps.coolify.listEnvs(appId)) {
+        if (stale.key === 'FILES_MANAGEMENT_KEY' && stale.uuid) {
+            await deps.coolify.deleteEnv(appId, stale.uuid);
+            staleKeyDeleted = true;
+        }
+    }
     // ---- 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
@@ -2752,13 +2910,29 @@ async function provisionPlatformArchon(context, deps) {
     const keyUnsynced = Boolean(integrationsKeyId) &&
         Boolean(recorded[PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY]) &&
         recorded[PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY] !== integrationsKeyId;
+    // #475: a platform applied before the rolling-update fix (or an already-live
+    // app the Coolify UI set the consistent-name flag on) has this unset; force
+    // one redeploy so the `custom_network_aliases`/`is_consistent_container_name_enabled`
+    // patch above actually takes effect on the running container, not just on
+    // Coolify's stored config.
+    const rollingUpdateApplied = recorded[PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY] === '1';
     const archonDeployedNow = keyUnsynced ||
         app.justCreated ||
         !app.running ||
         changed ||
+        staleKeyDeleted ||
+        envsHashChanged ||
         appliedGitRef !== gitRef ||
+        !rollingUpdateApplied ||
         recorded[PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY] !== hostname;
     if (archonDeployedNow) {
+        // #467: cleared before the deploy below is even attempted, not after --
+        // a deploy that then fails, or a crash before `waitForHealthyVersion`
+        // passes, must leave this run's attempt unconfirmed. Recording it only
+        // on success would not do that on its own: the env content a failed
+        // retry intends is identical to what a successful one intends, so
+        // leaving the old confirmation in place would read as still correct.
+        await record(PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY, '');
         await waitForDeploymentFinished(deps.coolify, appId, runtime, 'platform:archon', `archon stays at ${appliedGitRef ?? 'no recorded ref'} on ${recorded[PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY] ?? 'no recorded hostname'}`);
     }
     // ---- tunnel and DNS ---------------------------------------------------------
@@ -2831,6 +3005,16 @@ async function provisionPlatformArchon(context, deps) {
     if (keyUnsynced && integrationsKeyId) {
         await record(PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY, integrationsKeyId);
     }
+    // #475: confirmed only now, after the health check above has passed on a
+    // container that was deployed with the alias patch in place -- the same
+    // confirm-after-health-check timing as the two records just above.
+    if (!rollingUpdateApplied) {
+        await record(PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY, '1');
+    }
+    // #467: confirmed only now, after the health check above has passed (or,
+    // when no deploy was needed this run, left exactly as it already was --
+    // `envsHashChanged` false means it already equals `envsHash`).
+    await record(PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY, envsHash);
     // Last, after every write the applied values depend on, so a run that failed
     // halfway plans again.
     await record(PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
@@ -3242,6 +3426,37 @@ async function archonBootstrapOperatorDrifted(coolify, appId, recordedIds) {
         return false;
     }
 }
+/**
+ * #480: whether the live app disagrees with the patch
+ * `provisionPlatformArchon` sends on every run -- `is_consistent_container_name_enabled`
+ * turned back on, `custom_network_aliases` missing or changed, or the health
+ * check disabled -- any of which means Coolify stops the old container
+ * before the new one is up, the #475 incident's own failure mode.
+ * `PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY` only proves one past
+ * apply sent this patch; nothing re-reads the live app afterward, so a
+ * setting changed back by hand in the Coolify UI would otherwise go
+ * unnoticed forever. A failed read is not drift, the same rule
+ * {@link archonAccessDrifted} follows: the next plan reads again.
+ *
+ * #480 PR review: `is_consistent_container_name_enabled` comes back nested
+ * under `settings`, confirmed against a live read of platform-archon on
+ * Coolify 4.3.23 -- a top-level read always came back absent, so the first
+ * version of this check never actually fired. `custom_network_aliases` and
+ * `health_check_enabled` are both top-level there.
+ */
+async function archonRollingUpdateDrifted(coolify, appId) {
+    if (!appId)
+        return false;
+    try {
+        const app = await coolify.getApplication(appId);
+        return (app.settings?.is_consistent_container_name_enabled === true ||
+            app.custom_network_aliases !== PLATFORM_ARCHON_INTERNAL_NAME ||
+            app.health_check_enabled !== true);
+    }
+    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
@@ -3309,11 +3524,31 @@ async function collectArchonServiceInputs(platform, deps, recorded) {
     const held = (ref) => heldByRef.get(ref);
     for (const service of services) {
         if (service === 'files') {
-            envs.push({
-                key: 'FILES_URL',
-                value: recorded[PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY],
-            }, {
-                key: 'FILES_MANAGEMENT_KEY',
+            envs.push(
+            // #436 round 2: not `PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY`'s
+            // internal `http://<name>:3000` -- Archon's signed path needs an
+            // exact HTTPS origin (`filesOrigin()`/`filesBaseUrl()`,
+            // `wtfalch/archon`'s `src/lib/authz/files-management.ts` and
+            // `src/lib/files-admin/client.ts`), and that origin is also the
+            // signing audience, so it must equal Files' own `APP_URL` exactly
+            // (this file, the files runner env above: `https://${platform.
+            // files.hostname}`).
+            { key: 'FILES_URL', value: `https://${platform.files.hostname}` }, 
+            // #436: Company Included's own Files organisation, provisioned by
+            // the ordinary per-org `planFilesOrganisation` step under its own
+            // org id -- `executor.ts`'s `filesOrganisation` calls
+            // `provisionOrganisation({ organisationId: org.id, ... })`, so
+            // `platform.ownerOrgId` is already that organisation's id, with no
+            // separate platform-level mint needed.
+            { key: 'FILES_ORGANISATION_ID', value: platform.ownerOrgId }, 
+            // #436: the signed-assertion identity `filesSigner()` reads
+            // (`archon`'s `src/lib/authz/files-management.ts`), not the bearer
+            // token `FILES_MANAGEMENT_KEY` used to name here -- that name made
+            // Archon take the issued-key branch of `filesManagementFetch`,
+            // which then failed on the `FILES_MANAGEMENT_SCOPE` this step never
+            // set, surfacing as "Files is not configured" (foundry#436).
+            { key: 'FILES_MANAGEMENT_ISSUER', value: FILES_MANAGEMENT_ISSUER }, { key: 'FILES_MANAGEMENT_KEY_ID', value: FILES_MANAGEMENT_KEY_ID }, {
+                key: 'FILES_MANAGEMENT_PRIVATE_KEY',
                 value: held(ARCHON_SERVICE_INPUTS.files.refs[0]),
             });
         }
@@ -4368,6 +4603,24 @@ function hashAuthApps(raw) {
         .update(raw ?? '')
         .digest('hex');
 }
+/**
+ * #467: sha256 of the full env set `provisionPlatformArchon` intends
+ * Archon to be running with, sorted by key so two calls that build the
+ * identical set in a different push order still hash the same. `overrides`
+ * replaces (never adds to) a same-named entry already in `envs` -- see its
+ * call site: `envs` itself only ever carries a handful of keys on the run
+ * that generates or adopts them, so those keys' actual values have to come
+ * from the caller's own read-back for every other run to hash the same.
+ * Paired with {@link PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY}, which records
+ * this value only once a deploy carrying it is confirmed healthy.
+ */
+function hashArchonEnvs(envs, overrides) {
+    const values = new Map(envs.map((e) => [e.key, e.value]));
+    for (const [key, value] of overrides)
+        values.set(key, value);
+    const sorted = [...values.entries()].sort(([a], [b]) => a.localeCompare(b));
+    return createHash('sha256').update(JSON.stringify(sorted)).digest('hex');
+}
 /**
  * #211 round 5: the one rule `provisionPlatformAuth` and
  * `provisionPlatformArchon` both call to decide whether the broker needs a
@@ -4852,6 +5105,320 @@ shareDomains) {
     await record(PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, gitRef);
     return { resourceId: runnerApp.appId };
 }
+/** https://github.com/wtfalch/names -- root Dockerfile, one `runner` target (see {@link provisionPlatformNames}'s own doc comment for why there is no `migration` target any more). */
+const NAMES_REPO = 'wtfalch/names';
+const PLATFORM_NAMES_PROJECT = 'platform';
+const PLATFORM_NAMES_DB_NAME = 'platform-names-db';
+const NAMES_APP_NAME = 'names';
+/** The app's fixed `custom_internal_name`, the way `platform:files`' runner names itself. */
+const NAMES_RUNNER_INTERNAL_NAME = 'platform-names';
+/** The runner's port (its Dockerfile: `PORT=3000`, `EXPOSE 3000`). */
+const NAMES_PORT = '3000';
+/** The Postgres database name, and the owner role's name per the host's own `.env.example`. */
+const NAMES_DB = 'names';
+const NAMES_OWNER_ROLE = 'names_owner';
+/** The restricted runtime role `migrate.mjs`'s own `ensureRuntimeRole` creates or syncs at every boot. */
+const NAMES_RUNTIME_ROLE = 'names_rt';
+const NAMES_TUNNEL_NAME = 'platform-names-tunnel';
+/** #197: the one Coolify app that runs `cloudflared` for {@link NAMES_TUNNEL_NAME}. */
+const NAMES_CLOUDFLARED_APP_NAME = 'platform-names-cloudflared';
+const PLATFORM_NAMES_PROJECT_SCOPE_KEY = 'coolify_project_platform_names';
+const PLATFORM_NAMES_DB_SCOPE_KEY = 'coolify_platform_names_database';
+const PLATFORM_NAMES_APP_SCOPE_KEY = 'coolify_platform_names_app';
+const PLATFORM_NAMES_TUNNEL_SCOPE_KEY = 'cloudflare_platform_names_tunnel';
+const PLATFORM_NAMES_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_names_connector_app';
+/**
+ * Written only when absent, never overwritten -- the `PLATFORM_FILES_RUNNER_DEFAULTS`
+ * convention, so an operator's own cap or rate survives every apply. Values
+ * are the host's own `.env.example` defaults.
+ */
+const PLATFORM_NAMES_RUNNER_DEFAULTS = [
+    { key: 'MAX_CLAIMS_PER_ORGANISATION', value: '100' },
+    { key: 'NAMES_RATE_BURST', value: '10' },
+    { key: 'NAMES_RATE_PER_SECOND', value: '0.5' },
+];
+/**
+ * Why `coolify:app` keyed {@link PLATFORM_NAMES_KEY} cannot be planned yet,
+ * or `null` when it can -- the host built no names dependencies (checked by
+ * the caller, `FoundryPlatformStepExecutor.blockedSteps`, before this is
+ * even called), no Cloudflare API token held under
+ * {@link PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF} (CLAUDE.md's "Human steps"),
+ * or no Cloudflare account id supplied beside it.
+ */
+async function namesBlockedReason(names) {
+    let token;
+    try {
+        token = (await names.heldKeys?.resolve(PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF)) ?? null;
+    }
+    catch {
+        token = null;
+    }
+    if (!token) {
+        return `the names host is blocked, not planned: no Cloudflare API token is held under ${PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF} yet (the names service's own token, tunnel edit + DNS edit, never the platform's) -- a human step`;
+    }
+    if (!names.cloudflareAccountId) {
+        return 'the names host is blocked, not planned: the host supplies no Cloudflare account id (PlatformNamesDeps.cloudflareAccountId) for the token above';
+    }
+    return null;
+}
+/**
+ * #478: makes `coolify:app` keyed {@link PLATFORM_NAMES_KEY} true -- the
+ * names host (https://github.com/wtfalch/names), its own database, and
+ * foundry's own platform key, reached at `platform.names.hostname` through
+ * a Cloudflare tunnel and DNS record (the public-service shape
+ * {@link provisionPlatformMail}/{@link provisionPlatformAuth} use, not
+ * `platform:files`' internal-only one -- `NAMES_URL` has to be reachable by
+ * every org's own app, which runs outside this Coolify network, and by
+ * Archon).
+ *
+ * One Coolify app only, unlike `platform:files`/`platform:ai`'s separate
+ * `migrate` app: names' own Dockerfile dropped its `migration` target
+ * (its own comment: no generated package's Coolify app ever built or ran
+ * that stage, which once shipped `wtfalch/cms` with an empty database and
+ * no runtime role). `apps/host/scripts/start.sh` now runs `migrate.mjs`
+ * inside the runner's own entrypoint, before `exec`'ing the server, so the
+ * one app's own Coolify health check (`/api/health`, a 120s start period)
+ * is the migration's own proof of success -- there is no separate
+ * `running:healthy` to wait on first.
+ *
+ * Two roles on one database, the `platform:files` pattern: Coolify creates
+ * it with `postgres_user: 'names_owner'`, which is `DATABASE_URL_OWNER` as
+ * returned (the migrate step's own connection, stripped from the server's
+ * environment before it starts, per `start.sh`'s own doc comment); the
+ * restricted `names_rt` role is never created here -- `migrate.mjs`'s own
+ * `ensureRuntimeRole` call creates or syncs it and sets its password from
+ * `DATABASE_URL` at every boot, so this function only has to mint that
+ * password once and reuse it (`ensureNamesRuntimeUrl`, the
+ * `ensureFilesRuntimeUrl` shape) -- never rotated, since the role's
+ * password is set from it on every migration.
+ *
+ * The platform key follows `platform:files`' management-key discipline
+ * (CLAUDE.md rule 1): a random secret is minted once, its id recorded
+ * undelivered and persisted before {@link PlatformNamesDeps.deliverSecret}
+ * is even tried, and the guard recorded only once delivery AND the env
+ * write (the SHA-256 hash, as `NAMES_PLATFORM_KEY_HASH`) both succeeded. The
+ * secret itself is never written to the host's own env, logged, returned
+ * or put in an error -- only its hash ever reaches names, and the full
+ * value goes to {@link PlatformNamesDeps.deliverSecret} under
+ * {@link PLATFORM_NAMES_KEY_REF} alone, for Archon's own `NamesPort` to read
+ * back later when it mints or revokes an entry's own names key.
+ *
+ * `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` on the runner are never
+ * minted here either: they are the names service's own credential (never
+ * Archon's), read back from {@link PlatformNamesDeps.heldKeys} under
+ * {@link PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF} once a human has put one there
+ * (the issue's own "Human steps") -- `blockedSteps`
+ * ({@link namesBlockedReason}) reports the step blocked, not planned, until
+ * then.
+ *
+ * Every part is safe to run again after a throw partway, `platform:files`'
+ * own rules: each id is recorded (and persisted) as soon as its resource
+ * exists, the app is deployed on every run that needs it, and the platform
+ * key is delivered before the guard that skips the mint is recorded. A
+ * changed hostname or `gitRef` (recorded as applied scope ids) plans the
+ * step again: `git_branch` and `APP_URL` are patched on every run and the
+ * app redeploys, with no new secret minted.
+ *
+ * Known gaps, left for review:
+ * - `NAMES_MAX_QUEUE_DEPTH` (the host's `.env.example`) is not set; the host
+ *   falls back to its own default.
+ * - `NAMES_TRUST_CF_CONNECTING_IP` is always written `true` rather than
+ *   left to the host's own default, since this step always puts the
+ *   runner behind the Cloudflare tunnel it also creates.
+ */
+async function provisionPlatformNames(context, deps) {
+    const { platform } = context;
+    const hostname = platform.names.hostname;
+    const gitRef = platform.names.gitRef;
+    const recorded = context.recordedIds();
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    const attempts = runtime.deliverAttempts ?? 3;
+    const cloudflareToken = await deps.heldKeys?.resolve(PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF);
+    if (!cloudflareToken || !deps.cloudflareAccountId) {
+        throw new Error(`platform:names needs the names service's own Cloudflare API token (held under ${PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF}) and account id (PlatformNamesDeps.cloudflareAccountId); names never becomes healthy without them`);
+    }
+    // Never plan-and-throw (CLAUDE.md rule 2): the planner reports a lost
+    // secret and plans nothing; this is the same rule for a caller that
+    // reaches the step anyway.
+    const lostKey = recorded[PLATFORM_NAMES_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY];
+    if (lostKey && !recorded[PLATFORM_NAMES_PLATFORM_KEY_SET_SCOPE_KEY]) {
+        throw new Error(`platform:names: the platform key (${lostKey}) was minted but never delivered; remove the recorded key ${PLATFORM_NAMES_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+    }
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    let projectUuid = recorded[PLATFORM_NAMES_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await deps.coolify.findProjectByName(PLATFORM_NAMES_PROJECT);
+        projectUuid = found
+            ? found.uuid
+            : (await deps.coolify.createProject(PLATFORM_NAMES_PROJECT)).uuid;
+        await record(PLATFORM_NAMES_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    const server = await resolvePlatformServer(deps.coolify);
+    // ---- database ----------------------------------------------------------
+    let dbId = recorded[PLATFORM_NAMES_DB_SCOPE_KEY];
+    if (!dbId) {
+        const found = (await deps.coolify.listDatabases()).find((db) => db.name === PLATFORM_NAMES_DB_NAME && db.environment_id === environment.id);
+        if (found) {
+            dbId = found.uuid;
+        }
+        else {
+            const created = await deps.coolify.createPostgresDatabase({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                name: PLATFORM_NAMES_DB_NAME,
+                postgres_db: NAMES_DB,
+                postgres_user: NAMES_OWNER_ROLE,
+            });
+            dbId = created.uuid;
+        }
+        await record(PLATFORM_NAMES_DB_SCOPE_KEY, dbId);
+    }
+    const db = await getDatabaseStarted(deps.coolify, dbId);
+    if (!db.internal_db_url) {
+        throw new Error('coolify:app for the platform (names): the database has no internal_db_url yet -- retry this apply once Coolify reports one');
+    }
+    // ---- the app -------------------------------------------------------------
+    const app = await findOrCreatePlatformApp(deps.coolify, NAMES_APP_NAME, environment, async () => {
+        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: NAMES_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name: NAMES_APP_NAME,
+        });
+    });
+    const appId = app.appId;
+    await record(PLATFORM_NAMES_APP_SCOPE_KEY, appId);
+    // Set on every run, not only after a create: a throw right after the
+    // create must not leave the app on the wrong target for good, and a
+    // changed `gitRef` has to reach an app made on an earlier one.
+    await deps.coolify.updateApplication(appId, {
+        dockerfile_target_build: 'runner',
+        custom_internal_name: NAMES_RUNNER_INTERNAL_NAME,
+        git_branch: gitRef,
+    });
+    const runtimeUrl = await ensureNamesRuntimeUrl(deps.coolify, appId, db.internal_db_url);
+    // ---- the platform key, once ----------------------------------------------
+    // The recorded `set` id *is* the hash (never read back from Coolify's own
+    // env, which can be missing or stale on a re-apply): the hash is never
+    // secret, so it doubles as both the undelivered id and the value the base
+    // env below writes, with nothing extra to compute or a live read that
+    // could fall back to a blank value.
+    let keyHash = recorded[PLATFORM_NAMES_PLATFORM_KEY_SET_SCOPE_KEY] ?? '';
+    if (!keyHash) {
+        const secret = randomBytes(32).toString('base64url');
+        keyHash = createHash('sha256').update(secret).digest('hex');
+        await record(PLATFORM_NAMES_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY, keyHash);
+        await deliverWithRetry(deps.deliverSecret, PLATFORM_NAMES_KEY_REF, secret, attempts, sleep, 'the names platform key', 'platform:names');
+        // Recorded as soon as delivery succeeds, before the env write below (the
+        // base env block, further down, is what actually writes the hash) --
+        // so a failed or crashed env write is simply retried on the next apply
+        // instead of leaving an undelivered secret with no `set` partner and no
+        // way to recover but a hand edit of the recorded ids.
+        await record(PLATFORM_NAMES_PLATFORM_KEY_SET_SCOPE_KEY, keyHash);
+    }
+    // ---- base env, written on every run --------------------------------------
+    await deps.coolify.bulkUpsertEnvs(appId, [
+        { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        { key: 'APP_URL', value: `https://${hostname}` },
+        { key: 'CLOUDFLARE_API_TOKEN', value: cloudflareToken },
+        { key: 'CLOUDFLARE_ACCOUNT_ID', value: deps.cloudflareAccountId },
+        { key: 'NAMES_TRUST_CF_CONNECTING_IP', value: 'true' },
+        { key: 'NODE_ENV', value: 'production' },
+        { key: 'NAMES_PLATFORM_KEY_HASH', value: keyHash },
+        ...(await missingEnvs(deps.coolify, appId, PLATFORM_NAMES_RUNNER_DEFAULTS)),
+    ]);
+    // ---- tunnel and DNS -------------------------------------------------------
+    const existingTunnel = await deps.cloudflare.findTunnelByName(NAMES_TUNNEL_NAME);
+    const tunnel = existingTunnel ?? (await deps.cloudflare.createTunnel(NAMES_TUNNEL_NAME));
+    await record(PLATFORM_NAMES_TUNNEL_SCOPE_KEY, tunnel.id);
+    await deps.cloudflare.putTunnelConfig(tunnel.id, {
+        ingress: [
+            { hostname, service: `http://${NAMES_RUNNER_INTERNAL_NAME}:${NAMES_PORT}` },
+            { service: 'http_status:404' },
+        ],
+    });
+    // #197: without a connector, `hostname` answers with a Cloudflare error.
+    await ensureCloudflaredConnector({
+        coolify: deps.coolify,
+        cloudflare: deps.cloudflare,
+        tunnelId: tunnel.id,
+        appName: NAMES_CLOUDFLARED_APP_NAME,
+        projectUuid,
+        environment,
+        resolveServer: async () => server,
+        recordedConnectorAppId: recorded[PLATFORM_NAMES_CONNECTOR_APP_SCOPE_KEY] ?? null,
+        recordAppId: (connectorAppId) => record(PLATFORM_NAMES_CONNECTOR_APP_SCOPE_KEY, connectorAppId),
+    });
+    const zoneId = recorded[apexZoneKey(platform.apex)] ?? (await exactZone(deps.cloudflare, platform.apex))?.id;
+    if (!zoneId) {
+        throw new Error(`platform:names: no Cloudflare zone for ${platform.apex} to put ${hostname} in`);
+    }
+    const dnsTarget = `${tunnel.id}.cfargotunnel.com`;
+    const [dnsRecord] = await deps.cloudflare.findDnsRecord(zoneId, hostname, 'CNAME');
+    if (!dnsRecord) {
+        await deps.cloudflare.createDnsRecord(zoneId, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    else if (dnsRecord.content !== dnsTarget) {
+        await deps.cloudflare.updateDnsRecord(zoneId, dnsRecord.id, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    // ---- deploy and wait -------------------------------------------------------
+    // #252: the tunnel and DNS above already route `hostname`, so the combined
+    // helper (deployment-record check, then the `/api/health` probe) can run
+    // in one call -- unlike `platform:mail`, nothing here needs to happen
+    // between the two phases.
+    await waitForNewDeployment(deps.coolify, appId, { kind: 'ready', url: `https://${hostname}/api/health` }, runtime, sleep, 'platform:names', `names stays at ${recorded[PLATFORM_NAMES_APPLIED_GIT_REF_SCOPE_KEY] ?? 'no recorded ref'}`);
+    // Last: a run that failed anywhere above is planned again.
+    context.recordScopeId(PLATFORM_NAMES_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    await record(PLATFORM_NAMES_APPLIED_GIT_REF_SCOPE_KEY, gitRef);
+    return { resourceId: appId };
+}
+/**
+ * The runtime `DATABASE_URL` the names app gets: the value already set on
+ * it, else a new `names_rt` credential on the database's host, the
+ * `ensureFilesRuntimeUrl` shape for one app instead of two. A parse failure
+ * throws a message with no part of the URL in it, since the URL carries the
+ * owner's password.
+ */
+async function ensureNamesRuntimeUrl(coolify, appId, dbInternalUrl) {
+    const existing = (await coolify.listEnvs(appId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview && e.value);
+    if (existing)
+        return existing.value;
+    let host;
+    let pathname;
+    let search;
+    try {
+        ({ host, pathname, search } = new URL(dbInternalUrl));
+    }
+    catch {
+        throw new Error("coolify:app for the platform (names): the database's internal_db_url could not be parsed to build the runtime DATABASE_URL");
+    }
+    const password = randomBytes(24).toString('base64url');
+    return `postgres://${NAMES_RUNTIME_ROLE}:${password}@${host}${pathname}${search}`;
+}
 function aiKeys(deps) {
     const keys = deps?.keys;
     return keys?.workerUrl && keys.credential && keys.verifyKeys ? keys : null;
@@ -4955,7 +5522,9 @@ async function stopIfRunning(coolify, appId) {
  * Hands `secret` to the host, retrying. The thrown error names `what` only,
  * never the secret or the cause, which could echo it.
  */
-async function deliverWithRetry(deliverSecret, ref, secret, attempts, sleep, what) {
+async function deliverWithRetry(deliverSecret, ref, secret, attempts, sleep, what, 
+/** The step name every error is prefixed with (default `'platform:files'`, this helper's first caller). */
+label = 'platform:files') {
     for (let attempt = 1;; attempt += 1) {
         try {
             await deliverSecret(ref, secret);
@@ -4963,7 +5532,7 @@ async function deliverWithRetry(deliverSecret, ref, secret, attempts, sleep, wha
         }
         catch {
             if (attempt >= attempts) {
-                throw new Error(`platform:files: ${what} could not be delivered after ${attempts} tries; the next plan reports it as lost and mints no new one`);
+                throw new Error(`${label}: ${what} could not be delivered after ${attempts} tries; the next plan reports it as lost and mints no new one`);
             }
             await sleep(1000 * attempt);
         }