@wtfalch/foundry 0.16.7 → 0.16.9

package/dist/plan/platform-providers.js

@@ -178,7 +178,19 @@ export class FoundryPlatformStepExecutor {
         }
         else if (platform.files.enabled && !filesKeys(this.files)) {
             blocked.files =
-                'the files host is blocked, not planned: the host supplies no keys worker URL and credential (KEYS_WORKER_URL, KEYS_CREDENTIAL), so files-migrate would never become healthy';
+                'the files host is blocked, not planned: the host supplies no keys worker URL, credential and verify keys (KEYS_WORKER_URL, KEYS_CREDENTIAL, KEYS_VERIFY_KEYS), so files would never become healthy';
+        }
+        else if (platform.files.enabled && !filesR2(this.files)) {
+            // #380: the platform files host's own gap -- it deployed and recorded
+            // applied, but never turned healthy, because nothing set R2_BUCKET or
+            // R2_ENDPOINT on the runner.
+            blocked.files =
+                'the files host is blocked, not planned: the host supplies no R2 bucket and endpoint (R2_BUCKET, R2_ENDPOINT), so files would never become healthy';
+        }
+        else if (platform.files.enabled) {
+            const invalid = filesDepsInvalid(this.files);
+            if (invalid)
+                blocked.files = `the files host is blocked, not planned: ${invalid}`;
         }
         if (platform.ai.enabled && !this.ai) {
             blocked.ai =
@@ -254,6 +266,23 @@ export class FoundryPlatformStepExecutor {
             if (loginClientDrifted)
                 result.auth = true;
         }
+        // #380: once the runner app is recorded, re-check its live env against
+        // every setting `ensureStarted()` requires -- the gap that left the
+        // platform's own files host `running:unhealthy` from the day it first
+        // deployed, with no live reader ever telling the planner so. Reported as
+        // drift so `planFiles` replans the step despite the hostname/gitRef
+        // match, and `provisionPlatformFiles` (which redeploys unconditionally
+        // on every run) fills in whatever is still missing.
+        if (platform.files.enabled && this.files && recordedIds[`coolify:app:${PLATFORM_FILES_KEY}`]) {
+            // A Coolify read error must not fail the whole plan: treat it as not drifted.
+            try {
+                if (await filesRunnerEnvDrifted(this.files.coolify, recordedIds))
+                    result.files = true;
+            }
+            catch {
+                // Nothing logged: the error can carry Coolify's response.
+            }
+        }
         // #257 fix round 2: only once a platform database actually exists to
         // back up -- the same "nothing to report yet" gate `blockedSteps`'s own
         // `backupExecutorMissing` check follows above, so a platform that has
@@ -976,13 +1005,22 @@ async function provisionPlatformAuth(context, deps) {
         { key: 'ZITADEL_DATABASE_POSTGRES_DSN', value: db.internal_db_url },
         { key: 'ZITADEL_FIRSTINSTANCE_SKIP', value: 'true' },
         { key: 'ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED', value: 'true' },
-        { key: 'ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI', value: `https://${hostname}/` },
-        { key: 'ZITADEL_OIDC_DEFAULTLOGINURLV2', value: `https://${hostname}/login?authRequest=` },
+        {
+            key: 'ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI',
+            value: `https://${hostname}/`,
+        },
+        {
+            key: 'ZITADEL_OIDC_DEFAULTLOGINURLV2',
+            value: `https://${hostname}/login?authRequest=`,
+        },
         {
             key: 'ZITADEL_OIDC_DEFAULTLOGOUTURLV2',
             value: `https://${hostname}/logout?post_logout_redirect=`,
         },
-        { key: 'ZITADEL_SAML_DEFAULTLOGINURLV2', value: `https://${hostname}/login?samlRequest=` },
+        {
+            key: 'ZITADEL_SAML_DEFAULTLOGINURLV2',
+            value: `https://${hostname}/login?samlRequest=`,
+        },
         { key: 'ZITADEL_LOGSTORE_ACCESS_STDOUT_ENABLED', value: 'true' },
     ];
     if (masterkey)
@@ -998,7 +1036,10 @@ async function provisionPlatformAuth(context, deps) {
             key: 'ZITADEL_API_URL',
             value: `http://${PLATFORM_AUTH_ZITADEL_INTERNAL_NAME}:${AUTH_ZITADEL_PORT}`,
         },
-        { key: 'CUSTOM_REQUEST_HEADERS', value: `Host:${hostname},X-Forwarded-Proto:https` },
+        {
+            key: 'CUSTOM_REQUEST_HEADERS',
+            value: `Host:${hostname},X-Forwarded-Proto:https`,
+        },
         { key: 'OTEL_NODE_RESOURCE_DETECTORS', value: 'none' },
         { key: 'API_CACHE_CONFIG', value: '{"defaultMinutes":2,"longMinutes":5}' },
     ];
@@ -1073,7 +1114,10 @@ async function provisionPlatformAuth(context, deps) {
                 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}` },
+            {
+                hostname,
+                service: `http://${PLATFORM_AUTH_LOGIN_INTERNAL_NAME}:${AUTH_LOGIN_PORT}`,
+            },
             { service: 'http_status:404' },
         ],
     });
@@ -1137,7 +1181,10 @@ async function provisionPlatformAuth(context, deps) {
                     privateKey: systemKeys.privateKey,
                     instanceName: PLATFORM_AUTH_ORG_NAME,
                     firstOrgName: PLATFORM_AUTH_ORG_NAME,
-                    owner: { userName: PLATFORM_AUTH_BEARER_USER_NAME, name: 'Foundry (instance owner)' },
+                    owner: {
+                        userName: PLATFORM_AUTH_BEARER_USER_NAME,
+                        name: 'Foundry (instance owner)',
+                    },
                 }, { fetch: runtime.fetch, now: runtime.now ?? Date.now });
             }
             catch (error) {
@@ -1366,7 +1413,20 @@ const STALWART_PORTS_EXPOSES = [STALWART_HTTP_PORT, ...STALWART_SMTP_PORTS].join
  * ZITADEL/login apps.
  */
 const STALWART_PORTS_MAPPINGS = STALWART_SMTP_PORTS.map((p) => `${p}:${p}`).join(',');
-const STALWART_DATA_MOUNT = '/opt/stalwart';
+/**
+ * The v0.16 image's two VOLUMEs (its Dockerfile): the data store, and the
+ * `config.json` Stalwart writes when bootstrap completes. The pre-0.16 image
+ * used `/opt/stalwart`, which v0.16 does not use. Each is a Coolify
+ * persistent storage (a Docker named volume, not a host path), so Docker
+ * seeds it from the image on first use and keeps the image's UID 2000
+ * ownership, which the container needs to write it.
+ */
+// Suffixes differ from the pre-0.16 storage's `-data` (still attached at
+// /opt/stalwart on apps created before), so a new storage never shares its name.
+const STALWART_STORAGES = [
+    { suffix: 'var-lib', mount_path: '/var/lib/stalwart' },
+    { suffix: 'etc', mount_path: '/etc/stalwart' },
+];
 /** `STALWART_RECOVERY_ADMIN=<user>:<password>` -- the fixed recovery account name; only the password half is generated. */
 const STALWART_RECOVERY_USER = 'admin';
 /**
@@ -1420,9 +1480,27 @@ export const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = 'foundry:platform:admin';
  * `stalwartForInstance` fake.
  */
 export function defaultStalwartForInstance(input) {
-    const instance = openInstance({ url: input.url, secret: input.password, user: input.user });
+    const instance = openInstance({
+        url: input.url,
+        secret: input.password,
+        user: input.user,
+    });
     return {
         async applySettings({ mailHost, apex, oidc }) {
+            // A fresh Stalwart (0.16) is in bootstrap mode and refuses every write
+            // but the `Bootstrap` object, so complete that first. A server already
+            // past it skips this. `update` drops the response, which carries the
+            // generated `admin@<apex>` secret: this step signs in with the
+            // recovery admin and never needs it.
+            if ((await instance.client.probe()) === 'bootstrap') {
+                await instance.client.update('Bootstrap', 'singleton', {
+                    serverHostname: mailHost,
+                    defaultDomain: apex,
+                    // The server sits behind a tunnel; no ACME challenge can reach it.
+                    requestTlsCertificate: false,
+                });
+                await instance.client.waitFor('ready');
+            }
             await applyObjects(instance.client, platformMailSettingsObjects({ apex, mailHost, oidc }), () => { });
         },
         createApiKey: (description, permissions) => instance.client.createApiKey(description, permissions),
@@ -1525,7 +1603,7 @@ async function provisionPlatformMail(context, deps) {
     // app is not.
     const server = await resolveMailServer(deps.coolify, recorded[PLATFORM_MAIL_SERVER_SCOPE_KEY]);
     await record(PLATFORM_MAIL_SERVER_SCOPE_KEY, server.uuid);
-    const serverIpBlocked = mailServerIpBlocked(server.ip);
+    const serverIpBlocked = mailServerIpBlocked(server.ip, platform.serverIpv4);
     if (serverIpBlocked)
         throw new Error(serverIpBlocked);
     const app = await findOrCreatePlatformApp(deps.coolify, PLATFORM_MAIL_APP_NAME, environment, async () => {
@@ -1557,12 +1635,19 @@ async function provisionPlatformMail(context, deps) {
     await record(PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, `http://${PLATFORM_MAIL_INTERNAL_NAME}:${STALWART_HTTP_PORT}`);
     // ---- storage ---------------------------------------------------------------
     const storages = await deps.coolify.listStorages(appId);
-    const hasDataVolume = (storages.persistent_storages ?? []).some((s) => s.mount_path === STALWART_DATA_MOUNT);
-    if (!hasDataVolume) {
+    // An app made before this release only has the old `/opt/stalwart` volume.
+    // That one is left in place (empty and unused; detaching it needs a call this
+    // step has no port for) and the two real ones are added.
+    let storagesAdded = false;
+    for (const wanted of STALWART_STORAGES) {
+        if ((storages.persistent_storages ?? []).some((st) => st.mount_path === wanted.mount_path)) {
+            continue;
+        }
         await deps.coolify.createPersistentStorage(appId, {
-            name: `${PLATFORM_MAIL_APP_NAME}-data`,
-            mount_path: STALWART_DATA_MOUNT,
+            name: `${PLATFORM_MAIL_APP_NAME}-${wanted.suffix}`,
+            mount_path: wanted.mount_path,
         });
+        storagesAdded = true;
     }
     // ---- env ---------------------------------------------------------------------
     // Generated once; unlike ZITADEL's masterkey this is never re-derived from
@@ -1579,7 +1664,8 @@ async function provisionPlatformMail(context, deps) {
     await deps.coolify.bulkUpsertEnvs(appId, envs);
     const declaredChanged = recorded[PLATFORM_MAIL_DEPLOYED_HOSTNAME_SCOPE_KEY] !== hostname ||
         recorded[PLATFORM_MAIL_DEPLOYED_GIT_REF_SCOPE_KEY] !== imageTag;
-    if (app.justCreated || !app.running || envsChanged || declaredChanged) {
+    // A new storage binds into the container only at its next start.
+    if (app.justCreated || !app.running || envsChanged || declaredChanged || storagesAdded) {
         // A container still up from before would answer the readiness probe with
         // the old deployment's health. Stop it and see it stopped first, so the
         // wait below only ever reads the new deployment.
@@ -1600,7 +1686,10 @@ async function provisionPlatformMail(context, deps) {
     await record(PLATFORM_MAIL_TUNNEL_SCOPE_KEY, tunnel.id);
     await deps.cloudflare.putTunnelConfig(tunnel.id, {
         ingress: [
-            { hostname, service: `http://${PLATFORM_MAIL_INTERNAL_NAME}:${STALWART_HTTP_PORT}` },
+            {
+                hostname,
+                service: `http://${PLATFORM_MAIL_INTERNAL_NAME}:${STALWART_HTTP_PORT}`,
+            },
             { service: 'http_status:404' },
         ],
     });
@@ -1640,7 +1729,7 @@ async function provisionPlatformMail(context, deps) {
         });
     }
     // ---- the MX hostname: a direct, unproxied A record --------------------------
-    const serverIp = server.ip; // checked by mailServerIpBlocked above
+    const serverIp = (platform.serverIpv4 ?? server.ip); // checked by mailServerIpBlocked above
     const [mxRecord] = await deps.cloudflare.findDnsRecord(zoneId, mailHost, 'A');
     if (!mxRecord) {
         await deps.cloudflare.createDnsRecord(zoneId, {
@@ -1774,13 +1863,19 @@ function mailImageTagBlocked(tag) {
         ? `the platform's mail server is blocked, not planned: ${reason} as the mail gitRef`
         : null;
 }
-/** Why the server's address cannot be the MX A record's content, or `null`. */
-function mailServerIpBlocked(ip) {
+/**
+ * Why no address can be the MX A record's content, or `null`. The declared
+ * `platform.serverIpv4` wins; else the Coolify server's own ip, when it is an
+ * IPv4 (the localhost server reports `host.docker.internal`, which is not).
+ */
+function mailServerIpBlocked(ip, declared) {
+    if (declared)
+        return null; // validatePlatform already refused a non-IPv4
     if (!ip) {
-        return "the platform's mail server is blocked, not planned: the Coolify server reports no ip, so mx.<apex> has no address to point at; set the server's IP in Coolify";
+        return "the platform's mail server is blocked, not planned: the Coolify server reports no ip, so mx.<apex> has no address to point at; declare the server's public IPv4 as serverIpv4 in the platform config";
     }
     if (!isIPv4(ip)) {
-        return `the platform's mail server is blocked, not planned: the Coolify server's ip "${ip}" is not an IPv4 address, so it cannot be the mx.<apex> A record; set the server's public IPv4 in Coolify`;
+        return `the platform's mail server is blocked, not planned: the Coolify server's ip "${ip}" is not an IPv4 address, so it cannot be the mx.<apex> A record; declare the server's public IPv4 as serverIpv4 in the platform config`;
     }
     return null;
 }
@@ -1815,7 +1910,7 @@ async function mailBlockedReason(platform, mail, recordedIds) {
         return tagBlocked;
     try {
         const server = await resolveMailServer(mail.coolify, recordedIds[PLATFORM_MAIL_SERVER_SCOPE_KEY]);
-        return mailServerIpBlocked(server.ip);
+        return mailServerIpBlocked(server.ip, platform.serverIpv4);
     }
     catch {
         return "the platform's mail server is blocked, not planned: no usable Coolify server could be resolved for it";
@@ -2366,7 +2461,10 @@ async function provisionPlatformArchon(context, deps) {
     }
     await deps.cloudflare.putTunnelConfig(tunnel.id, {
         ingress: [
-            { hostname, service: `http://${PLATFORM_ARCHON_INTERNAL_NAME}:${ARCHON_PORT}` },
+            {
+                hostname,
+                service: `http://${PLATFORM_ARCHON_INTERNAL_NAME}:${ARCHON_PORT}`,
+            },
             { service: 'http_status:404' },
         ],
     });
@@ -2799,7 +2897,9 @@ async function archonBrokerRegistrationDrifted(coolify, recordedIds) {
  * vary between calls.
  */
 async function collectArchonServiceInputs(platform, deps, recorded) {
-    const block = (why) => ({ blocked: `Archon is blocked, not planned: ${why}` });
+    const block = (why) => ({
+        blocked: `Archon is blocked, not planned: ${why}`,
+    });
     const envs = [];
     const heldByRef = new Map();
     const services = ['files', 'ai', 'integrations', 'jobs'].filter((s) => platform[s].enabled);
@@ -2808,7 +2908,11 @@ async function collectArchonServiceInputs(platform, deps, recorded) {
     }
     for (const service of services) {
         const needs = service === 'jobs'
-            ? { stepKey: null, scopeKeys: [], refs: [JOBS_ADMIN_TOKEN_REF] }
+            ? {
+                stepKey: null,
+                scopeKeys: [],
+                refs: [JOBS_ADMIN_TOKEN_REF],
+            }
             : ARCHON_SERVICE_INPUTS[service];
         if (needs.stepKey && !recorded[`coolify:app:${needs.stepKey}`]) {
             return block(`the ${service} step (${needs.stepKey}) is not applied yet`);
@@ -2835,10 +2939,22 @@ 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', value: held(ARCHON_SERVICE_INPUTS.files.refs[0]) });
+            envs.push({
+                key: 'FILES_URL',
+                value: recorded[PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY],
+            }, {
+                key: 'FILES_MANAGEMENT_KEY',
+                value: held(ARCHON_SERVICE_INPUTS.files.refs[0]),
+            });
         }
         else if (service === 'ai') {
-            envs.push({ key: 'AI_URL', value: recorded[PLATFORM_AI_INTERNAL_URL_SCOPE_KEY] }, { key: 'AI_MANAGEMENT_KEY', value: held(ARCHON_SERVICE_INPUTS.ai.refs[0]) }, {
+            envs.push({
+                key: 'AI_URL',
+                value: recorded[PLATFORM_AI_INTERNAL_URL_SCOPE_KEY],
+            }, {
+                key: 'AI_MANAGEMENT_KEY',
+                value: held(ARCHON_SERVICE_INPUTS.ai.refs[0]),
+            }, {
                 key: 'AI_ORGANISATION_ID',
                 value: recorded[PLATFORM_AI_ORGANISATION_SCOPE_KEY],
             });
@@ -2848,7 +2964,13 @@ async function collectArchonServiceInputs(platform, deps, recorded) {
             envs.push({ key: 'INTEGRATIONS_URL', value: url }, {
                 key: 'INTEGRATIONS_MANAGEMENT_PRIVATE_KEY',
                 value: held(INTEGRATIONS_MANAGEMENT_KEY_REF),
-            }, { key: 'INTEGRATIONS_MANAGEMENT_ISSUER', value: INTEGRATIONS_MANAGEMENT_ISSUER }, { key: 'INTEGRATIONS_MANAGEMENT_KEY_ID', value: INTEGRATIONS_MANAGEMENT_KEY_ID }, { key: 'INTEGRATIONS_MANAGEMENT_AUDIENCE', value: url });
+            }, {
+                key: 'INTEGRATIONS_MANAGEMENT_ISSUER',
+                value: INTEGRATIONS_MANAGEMENT_ISSUER,
+            }, {
+                key: 'INTEGRATIONS_MANAGEMENT_KEY_ID',
+                value: INTEGRATIONS_MANAGEMENT_KEY_ID,
+            }, { key: 'INTEGRATIONS_MANAGEMENT_AUDIENCE', value: url });
         }
         else {
             envs.push({ key: 'JOBS_URL', value: `https://${platform.jobs.hostname}` }, { key: 'JOBS_ADMIN_TOKEN', value: held(JOBS_ADMIN_TOKEN_REF) });
@@ -2964,7 +3086,10 @@ function parseAiKeyExistsBody(body) {
         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 };
+    return {
+        credentialId: record.credentialId,
+        organisationId: record.organisationId,
+    };
 }
 function parseAiKeyMintedBody(body) {
     const record = body;
@@ -3093,7 +3218,10 @@ export function createAiManagementKeyMinter(options) {
             });
             const response = await fetchImpl(`${internalUrl}${AI_PLATFORM_KEYS_PATH}`, {
                 method: 'POST',
-                headers: { 'content-type': contentType, [AI_MANAGEMENT_HEADER]: token },
+                headers: {
+                    'content-type': contentType,
+                    [AI_MANAGEMENT_HEADER]: token,
+                },
                 body,
                 // A hung ai must not hold the apply open.
                 signal: AbortSignal.timeout(30_000),
@@ -3130,7 +3258,11 @@ const PLATFORM_AI_MIGRATE = {
     target: 'migration',
     internalName: 'platform-ai-migrate',
 };
-const PLATFORM_AI_RUNNER = { name: 'ai', target: 'runner', internalName: 'platform-ai' };
+const PLATFORM_AI_RUNNER = {
+    name: 'ai',
+    target: 'runner',
+    internalName: 'platform-ai',
+};
 const PLATFORM_AI_WORKER = {
     name: 'ai-worker',
     target: 'worker',
@@ -3156,10 +3288,7 @@ const PLATFORM_AI_RUNNER_DEFAULTS = [
     { key: 'AI_FORGE_BINDINGS', value: '[]' },
     { key: 'AI_WORKER_TIMEOUT_MS', value: '60000' },
 ];
-const PLATFORM_AI_WORKER_DEFAULTS = [
-    ...PLATFORM_AI_RUNNER_DEFAULTS,
-    { key: 'AI_WORKER_BATCH', value: '10' },
-];
+const PLATFORM_AI_WORKER_DEFAULTS = [...PLATFORM_AI_RUNNER_DEFAULTS, { key: 'AI_WORKER_BATCH', value: '10' }];
 /**
  * #172: makes `coolify:app` keyed {@link PLATFORM_AI_KEY} true -- the ai host
  * (https://github.com/wtfalch/ai) on the platform's Coolify, then foundry's
@@ -3712,9 +3841,14 @@ async function ensureAiRuntimeUrl(coolify, appIds, ownerUrl) {
     const password = randomBytes(24).toString('base64url');
     return `postgres://${database}_rt:${password}@${host}${pathname}${search}`;
 }
-/** The entries of `defaults` whose key the app does not have yet. */
+/**
+ * The entries of `defaults` whose key the app does not have yet. A key held
+ * with a blank value counts as absent (#380), matching `filesRunnerEnvDrifted`,
+ * so one apply clears the drift instead of replanning every round (#377's loop
+ * class); a blank is never a valid setting, so the AI defaults share this.
+ */
 async function missingEnvs(coolify, appId, defaults) {
-    const present = new Set((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => e.key));
+    const present = new Set((await coolify.listEnvs(appId)).filter((e) => !e.is_preview && e.value).map((e) => e.key));
     return defaults.filter((d) => !present.has(d.key));
 }
 const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -3754,7 +3888,9 @@ async function resolvePlatformServer(coolify) {
  * the app was already running or starting; the caller deploys it when not.
  */
 async function findOrCreatePlatformApp(coolify, name, environment, create) {
-    const existing = await coolify.findApplicationByName(name, { environmentIds: [environment.id] });
+    const existing = await coolify.findApplicationByName(name, {
+        environmentIds: [environment.id],
+    });
     if (existing) {
         const live = await coolify.getApplication(existing.uuid);
         return {
@@ -3880,7 +4016,10 @@ export function brokerDeployNeeded(missingInputs, brokerAppId, authAppsRaw, reco
  * wrote there. Paired with {@link brokerDeployNeeded}, which reads it back.
  */
 export function brokerDeployRecordValue(brokerAppId, authAppsRaw) {
-    const record = { brokerAppId, authAppsHash: hashAuthApps(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. */
@@ -3982,6 +4121,20 @@ const FILES_DB = 'files';
 const FILES_RUNTIME_ROLE = `${FILES_DB}_rt`;
 const FILES_ZITADEL_PROJECT_NAME = 'files';
 const FILES_INTROSPECTION_APP_NAME = 'files-introspection';
+/**
+ * #380: written only when absent, never overwritten, the same
+ * {@link PLATFORM_AI_RUNNER_DEFAULTS} convention -- an operator's own limits
+ * survive every apply. Values are files' own `.env.example`. The runner
+ * needs all three: files' `ensureStarted()`
+ * (`apps/host/src/lib/authz/files-host.ts`) requires each with
+ * `required(...)`, and the health check fails without them -- the same gap
+ * #375 fixed for the AI host's `AI_WORKER_TIMEOUT_MS`.
+ */
+const PLATFORM_FILES_RUNNER_DEFAULTS = [
+    { key: 'FILES_MAX_FILE_BYTES', value: '26214400' },
+    { key: 'FILES_UPLOAD_TTL_SECONDS', value: '300' },
+    { key: 'FILES_SCRATCH_TTL_DAYS', value: '1' },
+];
 const PLATFORM_FILES_PROJECT_SCOPE_KEY = 'coolify_project_platform_files';
 const PLATFORM_FILES_DB_SCOPE_KEY = 'coolify_platform_files_database';
 const PLATFORM_FILES_MIGRATE_SCOPE_KEY = 'coolify_platform_files_migrate_app';
@@ -4033,12 +4186,17 @@ const PLATFORM_FILES_RUNNER_SCOPE_KEY = 'coolify_platform_files_runner_app';
  *   field for it. Not yet checked against a live Coolify.
  * - The runner is created without `domains`, like `platform:auth`'s apps.
  *   Whether Coolify adds a generated domain anyway is not yet checked.
- * - Foundry sets only the env it owns: the two database URLs, `APP_URL`,
- *   `AUTH_ISSUER`, `AUTH_PERSON_TOKEN_*`, `MANAGEMENT_*` and the two `KEYS_*`
- *   values the host supplies through {@link PlatformFilesDeps.keys}, which
- *   files-migrate needs to become healthy. The rest of files' `.env.example`
- *   (`R2_*`, `KEYS_VERIFY_KEYS`, `JOBS_*`, `AUTHZ_BOOTSTRAP_OPERATOR`, ...)
- *   is set by a person on the runner.
+ * - Foundry sets the env it owns: the two database URLs, `APP_URL`,
+ *   `AUTH_ISSUER`, `AUTH_PERSON_TOKEN_*`, `MANAGEMENT_*`, the `KEYS_*`
+ *   values the host supplies through {@link PlatformFilesDeps.keys} (#380
+ *   added `KEYS_VERIFY_KEYS`, required for the runner to become healthy,
+ *   and the optional `KEYS_AUDIT_TOKEN`), `R2_BUCKET`/`R2_ENDPOINT` from
+ *   {@link PlatformFilesDeps.r2} (#380, also required), the optional
+ *   `FILES_CLAMD_HOST`/`FILES_CLAMD_PORT`, `FILES_PUBLIC_HOSTS` and
+ *   `JOBS_SIGNING_SECRETS` the host may supply (#380), and the three
+ *   {@link PLATFORM_FILES_RUNNER_DEFAULTS} (#380, written only when absent).
+ *   `AUTHZ_BOOTSTRAP_OPERATOR` and the rest of files' `.env.example` are
+ *   still set by a person on the runner.
  * - The files project lives in the platform's `foundry` ZITADEL org. An
  *   org's Agora requests it as an audience scope from its own ZITADEL org;
  *   whether that needs a project grant per org is not decided here.
@@ -4055,7 +4213,15 @@ async function provisionPlatformFiles(context, deps) {
     const attempts = runtime.deliverAttempts ?? 3;
     const keys = filesKeys(deps);
     if (!keys) {
-        throw new Error('platform:files needs the keys worker URL and credential in its files dependencies (KEYS_WORKER_URL, KEYS_CREDENTIAL); files-migrate never becomes healthy without them');
+        throw new Error('platform:files needs the keys worker URL, credential and verify keys in its files dependencies (KEYS_WORKER_URL, KEYS_CREDENTIAL, KEYS_VERIFY_KEYS); files never becomes healthy without them');
+    }
+    // #380: R2_BUCKET/R2_ENDPOINT, the same "block the whole step" treatment
+    // as a missing `keys` above -- the runner's `ensureStarted()` requires
+    // both, and only this function's caller (`blockedSteps`, `planFiles`) ever
+    // has anything useful to report while they are unset.
+    const r2 = filesR2(deps);
+    if (!r2) {
+        throw new Error('platform:files needs the R2 bucket and endpoint in its files dependencies (R2_BUCKET, R2_ENDPOINT); files never becomes healthy without them');
     }
     // Never plan-and-throw: the planner reports a lost secret and plans
     // nothing; this is the same rule for a caller that reaches the step anyway.
@@ -4149,14 +4315,16 @@ async function provisionPlatformFiles(context, deps) {
     const runtimeUrl = await ensureFilesRuntimeUrl(deps.coolify, [migrateApp.appId, runnerApp.appId], db.internal_db_url);
     // The keys worker the migrate app needs to become healthy (files' README:
     // `DATABASE_URL_OWNER`, `DATABASE_URL`, `KEYS_WORKER_URL`, `KEYS_CREDENTIAL`).
-    const keysEnvs = [
+    // `files-migrate` never runs `ensureStarted()`, so it needs neither
+    // `KEYS_VERIFY_KEYS` nor the `files` runner's R2/optional settings below.
+    const migrateKeysEnvs = [
         { key: 'KEYS_WORKER_URL', value: keys.workerUrl },
         { key: 'KEYS_CREDENTIAL', value: keys.credential },
     ];
     await deps.coolify.bulkUpsertEnvs(migrateApp.appId, [
         { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
         { key: 'DATABASE_URL', value: runtimeUrl },
-        ...keysEnvs,
+        ...migrateKeysEnvs,
     ]);
     // ---- the files ZITADEL project, in the platform's sign-in ----------------
     const issuer = `https://${platform.auth.hostname}`;
@@ -4164,6 +4332,41 @@ async function provisionPlatformFiles(context, deps) {
     const { org } = await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
     const { project } = await zitadel.findOrCreateProject(org.id, FILES_ZITADEL_PROJECT_NAME);
     await record(PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, project.id);
+    // #380: the runner's own required settings -- `KEYS_VERIFY_KEYS` and
+    // `R2_BUCKET`/`R2_ENDPOINT` -- plus whatever optional ones the host
+    // supplies. `files-migrate` needs none of these (see `migrateKeysEnvs`
+    // above).
+    const runnerKeysEnvs = [
+        ...migrateKeysEnvs,
+        { key: 'KEYS_VERIFY_KEYS', value: keys.verifyKeys },
+    ];
+    if (deps.keys?.auditToken)
+        runnerKeysEnvs.push({
+            key: 'KEYS_AUDIT_TOKEN',
+            value: deps.keys.auditToken,
+        });
+    const runnerOptionalEnvs = [];
+    if (deps.clamd?.host) {
+        runnerOptionalEnvs.push({
+            key: 'FILES_CLAMD_HOST',
+            value: deps.clamd.host,
+        });
+        if (deps.clamd.port)
+            runnerOptionalEnvs.push({
+                key: 'FILES_CLAMD_PORT',
+                value: deps.clamd.port,
+            });
+    }
+    if (deps.publicHosts)
+        runnerOptionalEnvs.push({
+            key: 'FILES_PUBLIC_HOSTS',
+            value: deps.publicHosts,
+        });
+    if (deps.jobsSigningSecrets)
+        runnerOptionalEnvs.push({
+            key: 'JOBS_SIGNING_SECRETS',
+            value: deps.jobsSigningSecrets,
+        });
     const runnerEnvs = [
         { key: 'DATABASE_URL', value: runtimeUrl },
         // The management verifier's audience, which must be an HTTPS origin. The
@@ -4171,7 +4374,14 @@ async function provisionPlatformFiles(context, deps) {
         { key: 'APP_URL', value: `https://${platform.files.hostname}` },
         { key: 'AUTH_ISSUER', value: issuer },
         { key: 'AUTH_PERSON_TOKEN_AUDIENCE', value: project.id },
-        ...keysEnvs,
+        ...runnerKeysEnvs,
+        { key: 'R2_BUCKET', value: r2.bucket },
+        { key: 'R2_ENDPOINT', value: r2.endpoint },
+        ...runnerOptionalEnvs,
+        // #380: written only when absent, never overwriting an operator's own
+        // limit (`missingEnvs`'s own "written only when absent" contract, the
+        // same `provisionPlatformAi` uses for `PLATFORM_AI_RUNNER_DEFAULTS`).
+        ...(await missingEnvs(deps.coolify, runnerApp.appId, PLATFORM_FILES_RUNNER_DEFAULTS)),
     ];
     // Base env first, so a secret's own write below cannot be the only one
     // that lands, and a re-run with a changed hostname updates `APP_URL`.
@@ -4199,8 +4409,14 @@ async function provisionPlatformFiles(context, deps) {
         await record(PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, client.appId);
         await deliverWithRetry(deps.deliverSecret, FILES_INTROSPECTION_SECRET_REF, client.clientSecret, attempts, sleep, `the introspection client secret (ZITADEL app ${client.appId})`);
         await deps.coolify.bulkUpsertEnvs(runnerApp.appId, [
-            { key: 'AUTH_PERSON_TOKEN_INTROSPECTION_CLIENT_ID', value: client.clientId },
-            { key: 'AUTH_PERSON_TOKEN_INTROSPECTION_CLIENT_SECRET', value: client.clientSecret },
+            {
+                key: 'AUTH_PERSON_TOKEN_INTROSPECTION_CLIENT_ID',
+                value: client.clientId,
+            },
+            {
+                key: 'AUTH_PERSON_TOKEN_INTROSPECTION_CLIENT_SECRET',
+                value: client.clientSecret,
+            },
         ]);
         await record(PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, client.appId);
     }
@@ -4242,7 +4458,82 @@ function aiKeys(deps) {
 }
 function filesKeys(deps) {
     const keys = deps?.keys;
-    return keys?.workerUrl && keys.credential ? keys : null;
+    return keys?.workerUrl && keys.credential && keys.verifyKeys
+        ? {
+            workerUrl: keys.workerUrl,
+            credential: keys.credential,
+            verifyKeys: keys.verifyKeys,
+        }
+        : null;
+}
+/** #380: `R2_BUCKET`/`R2_ENDPOINT`, both `required(...)` by the files runner's `ensureStarted()`. */
+function filesR2(deps) {
+    const r2 = deps?.r2;
+    return r2?.bucket && r2.endpoint ? r2 : null;
+}
+/**
+ * #380: the files host's own checks on what the host supplies, mirrored from
+ * `apps/host/src/lib/authz/files-host.ts` (`R2_ENDPOINT`: a bare https origin)
+ * and `src/lib/keys/config.ts` (`KEYS_VERIFY_KEYS`: 1 or 2 comma-separated
+ * base64url values, each exactly 32 bytes), so a bad value blocks the step
+ * naming the field instead of deploying a host that never turns healthy.
+ * Never echoes the value.
+ */
+function filesDepsInvalid(deps) {
+    const r2 = filesR2(deps);
+    if (r2) {
+        let ok = false;
+        try {
+            const u = new URL(r2.endpoint);
+            ok =
+                u.protocol === 'https:' &&
+                    !u.username &&
+                    !u.password &&
+                    u.pathname === '/' &&
+                    !u.search &&
+                    !u.hash;
+        }
+        catch {
+            // Not a URL: ok stays false.
+        }
+        if (!ok)
+            return 'R2_ENDPOINT (r2.endpoint) must be an HTTPS origin, with no path, query or fragment';
+    }
+    const verifyKeys = filesKeys(deps)?.verifyKeys;
+    if (verifyKeys !== undefined) {
+        const parts = verifyKeys.split(',');
+        const valid = parts.length <= 2 &&
+            parts.every((part) => /^[A-Za-z0-9_-]+$/.test(part) &&
+                Buffer.from(part, 'base64url').length === 32 &&
+                Buffer.from(part, 'base64url').toString('base64url') === part);
+        if (!valid)
+            return 'KEYS_VERIFY_KEYS (keys.verifyKeys) must be 1 or 2 comma-separated base64url values, each decoding to exactly 32 bytes';
+    }
+    return null;
+}
+/**
+ * #380: whether the `files` runner's live env is missing a setting its own
+ * `ensureStarted()` (`apps/host/src/lib/authz/files-host.ts`) requires --
+ * every key `PLATFORM_FILES_RUNNER_DEFAULTS` writes, plus `R2_BUCKET`,
+ * `R2_ENDPOINT` and `KEYS_VERIFY_KEYS`, none of which this step's
+ * idempotency check (hostname/gitRef alone) could ever see. This is exactly
+ * the gap that left the platform's own files host `running:unhealthy` from
+ * the day it first deployed: the app was created and recorded applied, but
+ * nothing ever re-checked whether its env could actually pass a health
+ * check.
+ */
+async function filesRunnerEnvDrifted(coolify, recordedIds) {
+    const runnerAppId = recordedIds[`coolify:app:${PLATFORM_FILES_KEY}`];
+    if (!runnerAppId)
+        return false;
+    const present = new Set((await coolify.listEnvs(runnerAppId)).filter((e) => !e.is_preview && e.value).map((e) => e.key));
+    const required = [
+        'R2_BUCKET',
+        'R2_ENDPOINT',
+        'KEYS_VERIFY_KEYS',
+        ...PLATFORM_FILES_RUNNER_DEFAULTS.map((d) => d.key),
+    ];
+    return required.some((key) => !present.has(key));
 }
 /** Stops the app when Coolify reports it running; a stop on an app that is not running can fail. */
 async function stopIfRunning(coolify, appId) {
@@ -4333,9 +4624,18 @@ const INTEGRATIONS_REPO = 'wtfalch/integrations';
  * The three Coolify apps `apps/host/README.md`'s "Deploy: migrate, web,
  * worker" names, each with the root Dockerfile target it builds.
  */
-const INTEGRATIONS_MIGRATE_APP = { name: 'integrations-migrate', target: 'migration' };
-const INTEGRATIONS_RUNNER_APP = { name: 'integrations', target: 'runner' };
-const INTEGRATIONS_WORKER_APP = { name: 'integrations-worker', target: 'worker' };
+const INTEGRATIONS_MIGRATE_APP = {
+    name: 'integrations-migrate',
+    target: 'migration',
+};
+const INTEGRATIONS_RUNNER_APP = {
+    name: 'integrations',
+    target: 'runner',
+};
+const INTEGRATIONS_WORKER_APP = {
+    name: 'integrations-worker',
+    target: 'worker',
+};
 /** The runner's `EXPOSE 3000`; readiness is its own `HEALTHCHECK` on `/api/health`. */
 const INTEGRATIONS_RUNNER_PORT = '3000';
 const INTEGRATIONS_DB_NAME = 'integrations-db';
@@ -4535,13 +4835,19 @@ async function provisionPlatformIntegrations(action, context, deps) {
     const runnerEnvs = [
         ...sharedEnvs,
         ...(await envsIfAbsent(coolify, runnerApp.appId, [
-            { key: 'INTEGRATIONS_OPERATOR_TENANT_ID', value: INTEGRATIONS_OPERATOR_TENANT_ID },
+            {
+                key: 'INTEGRATIONS_OPERATOR_TENANT_ID',
+                value: INTEGRATIONS_OPERATOR_TENANT_ID,
+            },
         ])),
     ];
     const workerEnvs = [
         ...sharedEnvs,
         ...(await envsIfAbsent(coolify, workerApp.appId, [
-            { key: 'INTEGRATIONS_OPERATOR_TENANT_ID', value: INTEGRATIONS_OPERATOR_TENANT_ID },
+            {
+                key: 'INTEGRATIONS_OPERATOR_TENANT_ID',
+                value: INTEGRATIONS_OPERATOR_TENANT_ID,
+            },
             { key: 'INTEGRATIONS_WORKER_BATCH', value: INTEGRATIONS_WORKER_BATCH },
         ])),
     ];
@@ -5122,7 +5428,11 @@ export class ProvidersPlatformCloudflareReader {
                 system: 'cloudflare',
                 kind: 'zone',
                 key: platform.apex,
-                config: { id: zone.id, status: zone.status, name_servers: zone.name_servers },
+                config: {
+                    id: zone.id,
+                    status: zone.status,
+                    name_servers: zone.name_servers,
+                },
             },
         ];
     }