@wtfalch/foundry 0.70.0 → 0.71.0

package/dist/plan/platform-diff.js

@@ -75,6 +75,22 @@ export const PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY = 'zitadel_platform_aut
 export const AUTH_TUNNEL_ROUTES_VERSION = '2';
 /** The {@link AUTH_TUNNEL_ROUTES_VERSION} the sign-in tunnel was last written with. */
 export const PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY = 'auth_tunnel_routes_applied';
+/**
+ * The version of the env `provisionAuthStack` writes to the login apps (`LOGIN_MAIL_FROM`,
+ * `LETTERMINT_API_TOKEN`). Raise it when a key is added or its meaning changes, so an applied
+ * sign-in plans its step once more and the apps get the env. Never holds a value.
+ * 1: the login apps send their own invite and verification mail (auth 0.35.0, foundry 0.68.0).
+ */
+export const AUTH_LOGIN_ENV_VERSION = '1';
+/**
+ * What the login apps' env is written for: the version and the sender address (`LOGIN_MAIL_FROM`).
+ * The address is no secret; a new mail domain gives a new marker, so the step is planned again.
+ */
+export function authLoginEnvMarker(smtpSender) {
+    return `${AUTH_LOGIN_ENV_VERSION}:${smtpSender}`;
+}
+/** The {@link authLoginEnvMarker} the login apps' env was last written with, once live on them. */
+export const PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY = 'auth_login_env_applied';
 /**
  * `'1'` once the broker holds `MCP_DATABASE_URL` and `MCP_OAUTH_SECRET` (auth ADR 0002), recorded by the
  * sign-in step when an entry of that broker declares `uses.auth.mcp`. A broker entry with `mcp` is not
@@ -1112,6 +1128,8 @@ export const PLATFORM_EDGE_PLATFORM_KEY_SET_SCOPE_KEY = 'edge_platform_key_set';
  */
 export const PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY = 'edge_applied_hostname';
 export const PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY = 'edge_applied_git_ref';
+/** foundry#1024: what `provisionPlatformEdge` last wrote for {@link usageTailEdgeEnv}; see {@link usageTailEdgeEnvValue}. */
+export const PLATFORM_EDGE_APPLIED_USAGE_TAIL_SCOPE_KEY = 'edge_applied_usage_tail';
 /**
  * F4.dns: where edge answers on the Coolify network
  * (`http://<custom_internal_name>:3000`), recorded by the edge step once the
@@ -1396,6 +1414,56 @@ export function uptimeRecorded(recordedIds) {
         Boolean(recordedIds[PLATFORM_UPTIME_ACCESS_TOKEN_ID_SCOPE_KEY]) ||
         Boolean(recordedIds[PLATFORM_UPTIME_ACCESS_UNDELIVERED_SCOPE_KEY]));
 }
+/**
+ * foundry#1024: the usage tail Worker that meters every company Worker's
+ * use, one `cloudflare:worker` step keyed {@link PLATFORM_USAGE_TAIL_KEY}.
+ * `runPlatformSteps` records the script name under
+ * `cloudflare:worker:platform:usage-tail` once it succeeds, which is what
+ * stops `planUsageTail` planning it again.
+ */
+export const PLATFORM_USAGE_TAIL_KEY = 'platform:usage-tail';
+/** The Worker script's name at Cloudflare. */
+export const PLATFORM_USAGE_TAIL_SCRIPT_NAME = 'platform-usage-tail';
+/**
+ * The held ref of the Worker's one secret, `EDGE_USAGE_KEY` -- the narrow
+ * `usage:ingest` credential edge's ingest route accepts. Minted once (rule
+ * 1): the hash is never secret, so (the same pattern `provisionPlatformEdge`
+ * uses for `EDGE_PLATFORM_KEY_HASH`) it doubles as both the undelivered
+ * marker and the final recorded value, with nothing extra to compute or a
+ * live read that could fall back to a blank value.
+ */
+export const PLATFORM_USAGE_TAIL_KEY_REF = 'usage-tail:worker:key';
+export const PLATFORM_USAGE_TAIL_KEY_UNDELIVERED_SCOPE_KEY = 'usage_tail_key_undelivered';
+export const PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY = 'usage_tail_key_set';
+export const PLATFORM_USAGE_TAIL_APPLIED_TAG_SCOPE_KEY = 'usage_tail_applied_tag';
+export const PLATFORM_USAGE_TAIL_APPLIED_SHA256_SCOPE_KEY = 'usage_tail_applied_sha256';
+export const PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY = 'usage_tail_removed';
+/**
+ * What `platform:edge`'s own env should hold for the usage tail Worker
+ * (`USAGE_TAIL_WORKER`, `EDGE_USAGE_KEY_HASH`), or `null` while the Worker is
+ * not deployed or its key is not held yet. `provisionPlatformEdge` writes
+ * these two names on every run alongside `EDGE_PLATFORM_KEY_HASH`; `planEdge`
+ * reads {@link usageTailEdgeEnvValue} to replan edge once this changes.
+ */
+export function usageTailEdgeEnv(recordedIds) {
+    const deployed = Boolean(recordedIds[resourceKey('cloudflare', 'worker', PLATFORM_USAGE_TAIL_KEY)]) &&
+        !recordedIds[PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY];
+    const hash = recordedIds[PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY];
+    if (!deployed || !hash)
+        return null;
+    return { USAGE_TAIL_WORKER: PLATFORM_USAGE_TAIL_SCRIPT_NAME, EDGE_USAGE_KEY_HASH: hash };
+}
+/** The value `provisionPlatformEdge` records once it has written {@link usageTailEdgeEnv} to edge's env; empty while there is nothing to write. */
+export function usageTailEdgeEnvValue(recordedIds) {
+    const env = usageTailEdgeEnv(recordedIds);
+    return env ? `${env.USAGE_TAIL_WORKER}|${env.EDGE_USAGE_KEY_HASH}` : '';
+}
+/** Whether anything of the usage tail Worker is recorded that disabling it must remove. */
+export function usageTailRecorded(recordedIds) {
+    return ((Boolean(recordedIds[resourceKey('cloudflare', 'worker', PLATFORM_USAGE_TAIL_KEY)]) &&
+        !recordedIds[PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY]) ||
+        Boolean(recordedIds[PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY]));
+}
 /**
  * #167: the platform's own diff engine, mirroring `diff.ts`'s
  * `computePlanDetail` for the one shared {@link DeclaredPlatform} record
@@ -1449,6 +1517,11 @@ export function planPlatform(platform, live, options = {}) {
     // write, so while edge is neither applied nor planned in this plan they are
     // blocked, not planned (rule 2), naming edge as the cause.
     const edgeApplied = Boolean(recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]);
+    // foundry#1024: after edge, which it uploads the script through and whose
+    // env takes the key's hash.
+    const usageTail = planUsageTail(platform, recordedIds, blocked.usageTail, edgeApplied);
+    if (usageTail.step)
+        plannedSteps.push(usageTail.step);
     const dnsBlocked = edgeApplied || edge.step
         ? undefined
         : (service) => `the platform's ${service} is blocked, not planned: every DNS record is written through edge, and edge is neither applied nor planned (${platform.edge.enabled
@@ -1480,7 +1553,7 @@ export function planPlatform(platform, live, options = {}) {
     // reconcile below can be planned in the *same* round hc first comes up,
     // the same way files/mail/archon are planned in auth's own first round.
     const hcReady = hc.step !== null || Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_HC_KEY)]);
-    const auth = planAuth(platform, recordedIds, blocked.auth ?? dnsBlocked?.('sign-in'), blocked.authExecutorMissing ?? false, drifted.auth ?? false, blocked.authOtherInputsMissing ?? [], blocked.authOwnerInvite, drifted.authApps ?? false);
+    const auth = planAuth(platform, recordedIds, blocked.auth ?? dnsBlocked?.('sign-in'), blocked.authExecutorMissing ?? false, drifted.auth ?? false, blocked.authOtherInputsMissing ?? [], blocked.authOwnerInvite, drifted.authApps ?? false, blocked.authMailKeyHeld ?? true);
     if (auth.step)
         plannedSteps.push(auth.step);
     // #174: the integrations host. Planned after auth; neither step reads the
@@ -1718,6 +1791,9 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: heartbeats.blocked, key: 'heartbeats' });
     for (const description of uptime.blocked)
         unmanaged.push({ description, key: 'uptime' });
+    for (const description of usageTail.blocked) {
+        unmanaged.push({ description, key: 'usage-tail' });
+    }
     if (releaseHook.blocked) {
         unmanaged.push({ description: releaseHook.blocked, key: 'github-release-hook' });
     }
@@ -2153,7 +2229,7 @@ function planSfu(platform, callsOrgSlugs, recordedIds) {
  * promising "this apply re-mints" while one of those is still missing would
  * be wrong the moment it is read.
  */
-function planAuth(platform, recordedIds, executorBlocked, executorMissing, authDrifted, otherInputsMissing = [], ownerInviteBlocked, appsDown = false) {
+function planAuth(platform, recordedIds, executorBlocked, executorMissing, authDrifted, otherInputsMissing = [], ownerInviteBlocked, appsDown = false, mailKeyHeld = true) {
     if (!platform.auth.enabled)
         return { step: null, blocked: null };
     // C3/S2: standing notes. The invite and the domain wait on a person; they hold nothing else back.
@@ -2211,6 +2287,11 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
         // step's redeploy, so a platform recorded before them still plans it.
         recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS &&
         recordedIds[PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY] === AUTH_TUNNEL_ROUTES_VERSION &&
+        // The login apps' mail env: a platform from before it, or with a new apex, is written again.
+        // Without the held key the apply cannot record it, so it is asked for only once the key is held.
+        (!mailKeyHeld ||
+            recordedIds[PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY] ===
+                authLoginEnvMarker(`noreply@${platform.apex}`)) &&
         recordedIds[PLATFORM_AUTH_APPLIED_GIT_REF_SCOPE_KEY] === platform.auth.gitRef) {
         return { step: null, blocked: standingNote };
     }
@@ -2686,7 +2767,10 @@ function planFiles(platform, recordedIds, executorBlocked, authReady, drifted) {
  *
  * `drifted` (the host's own `driftedSteps`: edge holds an older Cloudflare
  * token) plans the same step on an applied edge. The step writes the held
- * token into edge's env and redeploys it.
+ * token into edge's env and redeploys it. foundry#1024: a usage tail Worker
+ * key minted after edge's last deploy plans the step again the same way,
+ * through {@link usageTailEdgeEnvValue} rather than a separate `drifted`
+ * flag, since the planner can read it straight from `recordedIds`.
  *
  * Blocked, not planned: a platform key minted but never delivered (lost,
  * `ServiceError`-free the way {@link planFiles}'s own management-key check
@@ -2708,7 +2792,11 @@ function planEdge(platform, recordedIds, executorBlocked, drifted) {
         recordedIds[PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY] === platform.edge.hostname &&
         recordedIds[PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY] === platform.edge.gitRef &&
         // F4.dns: an edge applied before its address was recorded runs once more to record it.
-        Boolean(recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]);
+        Boolean(recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]) &&
+        // foundry#1024: a usage tail Worker key minted after edge's last deploy
+        // has not reached edge's env yet; replan to write it and redeploy.
+        (recordedIds[PLATFORM_EDGE_APPLIED_USAGE_TAIL_SCOPE_KEY] ?? '') ===
+            usageTailEdgeEnvValue(recordedIds);
     if (applied && !drifted)
         return { step: null, blocked: null };
     if (executorBlocked)
@@ -3303,6 +3391,79 @@ function planUptime(platform, recordedIds, executorBlocked, heldOptional, archon
         notes,
     };
 }
+/**
+ * foundry#1024: the usage tail Worker, one `cloudflare:worker` step. Blocked,
+ * not planned (rule 2), while no artifact is pinned, edge is not applied, or
+ * the executor lacks its dependencies. Planned again when the pinned tag or
+ * sha256 changed, or a half-made deploy never recorded its applied values; it
+ * mints nothing that is already held. When the platform no longer enables
+ * the Worker, a destructive step removes whatever of it is recorded.
+ */
+function planUsageTail(platform, recordedIds, executorBlocked, edgeApplied) {
+    const { usageTail } = platform;
+    const deployed = Boolean(recordedIds[resourceKey('cloudflare', 'worker', PLATFORM_USAGE_TAIL_KEY)]) &&
+        !recordedIds[PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY];
+    const action = (desired) => ({
+        system: 'cloudflare',
+        kind: 'worker',
+        key: PLATFORM_USAGE_TAIL_KEY,
+        desired,
+    });
+    if (!usageTail.enabled) {
+        if (!usageTailRecorded(recordedIds))
+            return { step: null, blocked: [] };
+        if (executorBlocked)
+            return { step: null, blocked: [executorBlocked] };
+        return {
+            step: {
+                action: action({ remove: true }),
+                step: {
+                    description: `remove the usage tail Worker ${PLATFORM_USAGE_TAIL_SCRIPT_NAME} and its held key`,
+                    destroys: true,
+                    migrates: false,
+                },
+            },
+            blocked: [],
+        };
+    }
+    if (!usageTail.tag || !usageTail.sha256) {
+        return {
+            step: null,
+            blocked: [
+                'the usage tail Worker is blocked, not planned: no artifact is pinned; declare usageTail.tag (an edge release tag) and usageTail.sha256 (the digest of usage-tail-worker.js at that tag)',
+            ],
+        };
+    }
+    if (!edgeApplied) {
+        return {
+            step: null,
+            blocked: [
+                'the usage tail Worker is blocked, not planned: platform:edge has not been applied yet',
+            ],
+        };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: [executorBlocked] };
+    // Applied only once a run got to its end and recorded these: a Worker that
+    // was uploaded and then failed has its key but none of the applied values.
+    const applied = deployed &&
+        Boolean(recordedIds[PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY]) &&
+        recordedIds[PLATFORM_USAGE_TAIL_APPLIED_TAG_SCOPE_KEY] === usageTail.tag &&
+        recordedIds[PLATFORM_USAGE_TAIL_APPLIED_SHA256_SCOPE_KEY] === usageTail.sha256;
+    if (applied)
+        return { step: null, blocked: [] };
+    return {
+        step: {
+            action: action({ gitRef: usageTail.tag, sha256: usageTail.sha256 }),
+            step: {
+                description: `deploy the usage tail Worker ${PLATFORM_USAGE_TAIL_SCRIPT_NAME} from edge release ${usageTail.tag}, with its held key`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: [],
+    };
+}
 /**
  * #172: the platform's AI host (https://github.com/wtfalch/ai) -- a Coolify
  * Postgres plus three apps built from that repo's root Dockerfile, one per

package/dist/plan/platform-providers.d.ts

@@ -28,6 +28,7 @@ export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
 import { type PlatformGithubReleaseHookDeps } from './github-release-hook.js';
 import { type CallsSfuPlatformDeps } from './platform-sfu.js';
 import { type PlatformUptimeDeps } from './uptime-worker.js';
+import { type PlatformUsageTailDeps } from './usage-tail-worker.js';
 /** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
 export declare function apexZoneKey(apex: string): string;
 /**
@@ -326,6 +327,12 @@ export interface FoundryPlatformStepExecutorOptions {
      * the same reason as `auth`; without it the step is reported blocked.
      */
     uptime?: PlatformUptimeDeps;
+    /**
+     * foundry#1024: dependencies for the usage tail Worker step
+     * (`cloudflare:worker` keyed {@link PLATFORM_USAGE_TAIL_KEY}) -- optional
+     * for the same reason as `auth`; without it the step is reported blocked.
+     */
+    usageTail?: PlatformUsageTailDeps;
     /**
      * #604: dependencies for the `cloudflare:access-provider` step -- optional
      * for the same reason as `auth`; edge and sign-in applied with this unset
@@ -362,6 +369,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly registry?;
     private readonly heartbeats?;
     private readonly uptime?;
+    private readonly usageTail?;
     private readonly accessProvider?;
     private readonly oikosIngress?;
     private readonly githubReleaseHook?;
@@ -401,6 +409,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         auth?: string;
         authExecutorMissing?: boolean;
         authOtherInputsMissing?: string[];
+        authMailKeyHeld?: boolean;
         authOwnerInvite?: string;
         files?: string;
         integrations?: string;
@@ -427,6 +436,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
             pending: boolean;
             blocked?: string;
         };
+        usageTail?: string;
         githubReleaseHook?: string;
         githubReleaseHookReady?: boolean;
         githubReleaseHookHash?: string;
@@ -449,6 +459,12 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
      * they hold.
      */
     private uptimeBlocked;
+    /**
+     * foundry#1024: why the usage tail Worker cannot run yet. A lost key is
+     * not a block here: the step mints a new one. The planner checks the pin
+     * and edge first, so none of the reads here happens before they hold.
+     */
+    private usageTailBlocked;
     /**
      * 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

package/dist/plan/platform-providers.js

@@ -33,7 +33,7 @@ import { MAIL_APP_SCOPE_KEY, MAIL_DATABASE_NAME, MAIL_DATABASE_PASSWORD_ENV, MAI
 import { OIKOS_INGRESS_BLOCKED, PLATFORM_OIKOS_INGRESS_KEY, oikosIngressApplied, oikosIngressZoneBlocked, provisionOikosIngress, } from './oikos-ingress.js';
 import { recordOwnDnsHostname } from './own-dns.js';
 import { platformNetwork, platformTarget, scopeFromPlatform, } from './own-services.js';
-import { AUTH_TUNNEL_ROUTES_VERSION, AUTH_ZITADEL_RUN_OPTIONS, GITHUB_RELEASE_HOOK_DEPS_MISSING, GITHUB_RELEASE_WEBHOOK_SECRET_ENV, JOBS_DEPLOY_PENDING_SCOPE_KEY, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_AUTH_DOMAIN_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_UNDELIVERED_SCOPE_KEY, PLATFORM_ACCESS_ZITADEL_APP_SCOPE_KEY, PLATFORM_ACCESS_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_CONNECTOR_APP_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_AI_TUNNEL_SCOPE_KEY, PLATFORM_ARCHON_ACCESS_PIN_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_AUTH_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_CI_ORG_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_FIRST_OWNER_LINK_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY, PLATFORM_ARCHON_APP_KEY_ORG_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF, PLATFORM_ARCHON_DEPLOYMENT_SCOPE_KEY, PLATFORM_ARCHON_DESKTOP_CALLBACK_APPLIED_SCOPE_KEY, PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_ID_TOKEN_USERINFO_APPLIED_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_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY, PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY, PLATFORM_ARCHON_ORG_POLICY_SCOPE_KEY, PLATFORM_ARCHON_ORG_REGISTRATION_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_ORG_SCOPE_KEY, PLATFORM_ARCHON_OWNER_INVITE_ORG_SCOPE_KEY, PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY, PLATFORM_ARCHON_POST_LOGOUT_APPLIED_SCOPE_KEY, PLATFORM_ARCHON_RETIRED_CLIENT_SCOPE_KEY, PLATFORM_ARCHON_UPTIME_TICKS_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_UPTIME_TOKEN_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_WEBHOOK_SECRET_DEPLOYED_SCOPE_KEY, PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY, PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_APPLIED_GIT_REF_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_MCP_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_ORG_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY, PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_TUNNEL_ROUTES_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_EDGE_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_PLATFORM_KEY_SET_SCOPE_KEY, PLATFORM_EDGE_PLATFORM_KEY_UNDELIVERED_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_GITHUB_RELEASE_HOOK_KEY, PLATFORM_HC_ACCESS_SCOPE_KEY, PLATFORM_HC_API_KEY_REF, PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_HC_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_HC_KEY, PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY, PLATFORM_HEARTBEATS_HOSTED_API_KEY_REF, 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_HOST_PORTS_DIRECT, PLATFORM_MAIL_HOST_PORTS_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_RELAY_KEY, PLATFORM_MAIL_ROLE_CHECK_SCOPE_KEY, PLATFORM_MAIL_ROLE_ENSURED_SCOPE_KEY, PLATFORM_MAIL_ROLE_GRANTED_SCOPE_KEY, PLATFORM_MAIL_ROUTE_SCOPE_KEY, PLATFORM_MAIL_ROUTE_WANTED, PLATFORM_MAIL_USER_ROLE, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_OWNER_ORG_DOMAIN_BLOCKED_SCOPE_KEY, PLATFORM_OWNER_ORG_DOMAIN_SCOPE_KEY, PLATFORM_OWNER_ORG_SCOPE_KEY, PLATFORM_SFU_APPLIED_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_CLIENT_ID_REF, PLATFORM_UPTIME_ACCESS_CLIENT_SECRET_REF, PLATFORM_UPTIME_ACCESS_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_TOKEN_NAME, PLATFORM_UPTIME_ACCESS_UNDELIVERED_SCOPE_KEY, PLATFORM_UPTIME_AUDIT_SEAL_TICK_ID_SCOPE_KEY, PLATFORM_UPTIME_AUDIT_SEAL_TICK_TOKEN_REF, PLATFORM_UPTIME_CHAT_ROOM_ID_SCOPE_KEY, PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME, PLATFORM_UPTIME_KEY, PLATFORM_UPTIME_RELEASE_TICK_ID_SCOPE_KEY, PLATFORM_UPTIME_RELEASE_TICK_TOKEN_REF, PLATFORM_UPTIME_REMOVED_SCOPE_KEY, PLATFORM_UPTIME_SCRIPT_NAME, PLATFORM_UPTIME_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_TOKEN_REF, PLATFORM_ZITADEL_ORG_SCOPE_KEY, archonFilesMarker, archonFirstOwnerLink, archonOrgDomain, archonOrgName, desiredHeartbeatCheckNames, heartbeatCheckUrlRef, orgDeclaresMcp, parseBrokerDeployRecord, parseLoginClientRecord, platformBackupHeartbeatCheckName, platformMailHostPorts, platformMailMxHost, uptimeAccessTokenConflict, uptimeEffectiveVars, uptimeRecorded, uptimeTicksSyncValue, uptimeVarsDigest, } from './platform-diff.js';
+import { AUTH_TUNNEL_ROUTES_VERSION, AUTH_ZITADEL_RUN_OPTIONS, GITHUB_RELEASE_HOOK_DEPS_MISSING, GITHUB_RELEASE_WEBHOOK_SECRET_ENV, JOBS_DEPLOY_PENDING_SCOPE_KEY, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_AUTH_DOMAIN_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_UNDELIVERED_SCOPE_KEY, PLATFORM_ACCESS_ZITADEL_APP_SCOPE_KEY, PLATFORM_ACCESS_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_CONNECTOR_APP_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_AI_TUNNEL_SCOPE_KEY, PLATFORM_ARCHON_ACCESS_PIN_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_AUTH_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_CI_ORG_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_FIRST_OWNER_LINK_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY, PLATFORM_ARCHON_APP_KEY_ORG_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF, PLATFORM_ARCHON_DEPLOYMENT_SCOPE_KEY, PLATFORM_ARCHON_DESKTOP_CALLBACK_APPLIED_SCOPE_KEY, PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_ID_TOKEN_USERINFO_APPLIED_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_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY, PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY, PLATFORM_ARCHON_ORG_POLICY_SCOPE_KEY, PLATFORM_ARCHON_ORG_REGISTRATION_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_ORG_SCOPE_KEY, PLATFORM_ARCHON_OWNER_INVITE_ORG_SCOPE_KEY, PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY, PLATFORM_ARCHON_POST_LOGOUT_APPLIED_SCOPE_KEY, PLATFORM_ARCHON_RETIRED_CLIENT_SCOPE_KEY, PLATFORM_ARCHON_UPTIME_TICKS_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_UPTIME_TOKEN_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_WEBHOOK_SECRET_DEPLOYED_SCOPE_KEY, PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY, PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_APPLIED_GIT_REF_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_LOGIN_ENV_SCOPE_KEY, PLATFORM_AUTH_MCP_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_ORG_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY, PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_TUNNEL_ROUTES_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_EDGE_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_EDGE_APPLIED_USAGE_TAIL_SCOPE_KEY, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_PLATFORM_KEY_SET_SCOPE_KEY, PLATFORM_EDGE_PLATFORM_KEY_UNDELIVERED_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_GITHUB_RELEASE_HOOK_KEY, PLATFORM_HC_ACCESS_SCOPE_KEY, PLATFORM_HC_API_KEY_REF, PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_HC_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_HC_KEY, PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY, PLATFORM_HEARTBEATS_HOSTED_API_KEY_REF, 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_HOST_PORTS_DIRECT, PLATFORM_MAIL_HOST_PORTS_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_RELAY_KEY, PLATFORM_MAIL_ROLE_CHECK_SCOPE_KEY, PLATFORM_MAIL_ROLE_ENSURED_SCOPE_KEY, PLATFORM_MAIL_ROLE_GRANTED_SCOPE_KEY, PLATFORM_MAIL_ROUTE_SCOPE_KEY, PLATFORM_MAIL_ROUTE_WANTED, PLATFORM_MAIL_USER_ROLE, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_OWNER_ORG_DOMAIN_BLOCKED_SCOPE_KEY, PLATFORM_OWNER_ORG_DOMAIN_SCOPE_KEY, PLATFORM_OWNER_ORG_SCOPE_KEY, PLATFORM_SFU_APPLIED_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_CLIENT_ID_REF, PLATFORM_UPTIME_ACCESS_CLIENT_SECRET_REF, PLATFORM_UPTIME_ACCESS_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_TOKEN_NAME, PLATFORM_UPTIME_ACCESS_UNDELIVERED_SCOPE_KEY, PLATFORM_UPTIME_AUDIT_SEAL_TICK_ID_SCOPE_KEY, PLATFORM_UPTIME_AUDIT_SEAL_TICK_TOKEN_REF, PLATFORM_UPTIME_CHAT_ROOM_ID_SCOPE_KEY, PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME, PLATFORM_UPTIME_KEY, PLATFORM_UPTIME_RELEASE_TICK_ID_SCOPE_KEY, PLATFORM_UPTIME_RELEASE_TICK_TOKEN_REF, PLATFORM_UPTIME_REMOVED_SCOPE_KEY, PLATFORM_UPTIME_SCRIPT_NAME, PLATFORM_UPTIME_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_TOKEN_REF, PLATFORM_USAGE_TAIL_KEY, PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY, PLATFORM_USAGE_TAIL_SCRIPT_NAME, PLATFORM_ZITADEL_ORG_SCOPE_KEY, archonFilesMarker, archonFirstOwnerLink, archonOrgDomain, archonOrgName, authLoginEnvMarker, desiredHeartbeatCheckNames, heartbeatCheckUrlRef, orgDeclaresMcp, parseBrokerDeployRecord, parseLoginClientRecord, platformBackupHeartbeatCheckName, platformMailHostPorts, platformMailMxHost, uptimeAccessTokenConflict, uptimeEffectiveVars, uptimeRecorded, uptimeTicksSyncValue, uptimeVarsDigest, usageTailEdgeEnv, usageTailEdgeEnvValue, usageTailRecorded, } from './platform-diff.js';
 import { PLATFORM_REGISTRY_KEY, PLATFORM_REGISTRY_LOGINS_KEY, PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY, PLATFORM_REGISTRY_PULL_PASSWORD_REF, registryImageTagBlocked, } from './platform-registry-keys.js';
 import { ensureRegistryLogins, provisionPlatformRegistry, registryLoginsDrifted, } from './platform-registry.js';
 import { PLATFORM_ARCHON_IN_APP_SCOPE_KEY, archonInAppBack, archonInAppBind, archonInAppHost, archonInAppPoint, archonInAppUnbind, } from './sign-in-archon.js';
@@ -47,6 +47,7 @@ export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
 import { githubReleaseHookPlanInputs, provisionGithubReleaseHook, } from './github-release-hook.js';
 import { applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
 import { heldUptimeValues, provisionPlatformUptime, } from './uptime-worker.js';
+import { provisionPlatformUsageTail } from './usage-tail-worker.js';
 import { CreateInstanceError, createZitadelInstance, generateSystemApiKeypair, instanceWithoutBearerMessage, systemApiUsersEnv, waitForSystemApi, } from './zitadel-system-api.js';
 /** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
 export function apexZoneKey(apex) {
@@ -152,6 +153,7 @@ export class FoundryPlatformStepExecutor {
     registry;
     heartbeats;
     uptime;
+    usageTail;
     accessProvider;
     oikosIngress;
     githubReleaseHook;
@@ -174,6 +176,7 @@ export class FoundryPlatformStepExecutor {
         this.registry = options.registry;
         this.heartbeats = options.heartbeats;
         this.uptime = options.uptime;
+        this.usageTail = options.usageTail;
         this.accessProvider = options.accessProvider;
         this.oikosIngress = options.oikosIngress;
         this.githubReleaseHook = options.githubReleaseHook;
@@ -407,7 +410,7 @@ export class FoundryPlatformStepExecutor {
             blocked.authExecutorMissing = true;
         }
         else if (platform.auth.enabled && this.auth) {
-            const { reason: authBlocked, otherInputsMissing } = await authBrokerBlockedReason(this.auth, recordedIds);
+            const { reason: authBlocked, otherInputsMissing, mailKeyHeld, } = await authBrokerBlockedReason(this.auth, recordedIds);
             if (authBlocked) {
                 blocked.auth = authBlocked;
             }
@@ -424,6 +427,9 @@ export class FoundryPlatformStepExecutor {
             // #216 round 5: see `PlanPlatformOptions.blocked.authOtherInputsMissing`.
             if (otherInputsMissing.length > 0)
                 blocked.authOtherInputsMissing = otherInputsMissing;
+            // Without the held key `provisionAuthStack` never records the login env marker, so the plan must not ask for it.
+            if (mailKeyHeld !== undefined)
+                blocked.authMailKeyHeld = mailKeyHeld;
             // C3: the owner's invite needs a work address and the host's mail port. Without them it is
             // a blocked item, never a throw on every apply.
             const ownerCompany = await this.declaredOrgStore.get(platform.ownerOrgId);
@@ -612,6 +618,7 @@ export class FoundryPlatformStepExecutor {
                 blocked.heartbeatsApiKeyMissing = true;
         }
         await this.uptimeBlocked(platform, recordedIds, blocked, owner);
+        await this.usageTailBlocked(platform, recordedIds, blocked);
         if (platform.archon.enabled && !this.githubReleaseHook) {
             blocked.githubReleaseHook = GITHUB_RELEASE_HOOK_DEPS_MISSING;
         }
@@ -797,6 +804,38 @@ export class FoundryPlatformStepExecutor {
             }
         }
     }
+    /**
+     * foundry#1024: why the usage tail Worker cannot run yet. A lost key is
+     * not a block here: the step mints a new one. The planner checks the pin
+     * and edge first, so none of the reads here happens before they hold.
+     */
+    async usageTailBlocked(platform, recordedIds, blocked) {
+        const deployed = Boolean(recordedIds[`cloudflare:worker:${PLATFORM_USAGE_TAIL_KEY}`]) &&
+            !recordedIds[PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY];
+        if (!platform.usageTail.enabled && !usageTailRecorded(recordedIds))
+            return;
+        const deps = this.usageTail;
+        if (!deps) {
+            blocked.usageTail =
+                'the usage tail Worker is blocked, not planned: the host built the platform executor without its usage-tail dependencies';
+            return;
+        }
+        if (!platform.usageTail.enabled)
+            return;
+        const edgeUrl = recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY];
+        if (!deployed && edgeUrl && platform.usageTail.tag) {
+            try {
+                const workers = await deps.workers(edgeUrl);
+                if (await workers.scriptExists(PLATFORM_USAGE_TAIL_SCRIPT_NAME)) {
+                    blocked.usageTail = `the usage tail Worker is blocked, not planned: a Worker named ${PLATFORM_USAGE_TAIL_SCRIPT_NAME} already exists at Cloudflare and foundry did not make it; remove it by hand`;
+                }
+            }
+            catch {
+                blocked.usageTail =
+                    'the usage tail Worker is blocked, not planned: edge could not be asked whether the Worker exists';
+            }
+        }
+    }
     /**
      * 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
@@ -1156,6 +1195,14 @@ export class FoundryPlatformStepExecutor {
             }
             return provisionPlatformUptime(context, this.uptime);
         }
+        if (action.system === 'cloudflare' &&
+            action.kind === 'worker' &&
+            action.key === PLATFORM_USAGE_TAIL_KEY) {
+            if (!this.usageTail) {
+                throw new Error('platform:usage-tail needs FoundryPlatformStepExecutor to be constructed with its usage-tail dependencies (foundry#1024)');
+            }
+            return provisionPlatformUsageTail(context, this.usageTail);
+        }
         if (action.system === 'coolify' &&
             action.kind === 'app' &&
             action.key === PLATFORM_OIKOS_INGRESS_KEY) {
@@ -2239,7 +2286,16 @@ export async function provisionAuthStack(scope, deps, target, input) {
         await waitHealthy(withCallTimeout(deps.coolify), zitadelAppId, runtime, label, 'ZITADEL');
         await record(SIGNIN_DB_ZITADEL_PENDING_SCOPE_KEY, '');
     }
-    if (loginApp.justCreated || !loginApp.running || loginEnvsChanged || authRefChanged) {
+    // The mail env counts as live only once the login apps were deployed after it was written: a run that
+    // died between the write and the deploy leaves the marker unset, and the next run sees no env diff.
+    const loginEnvUnconfirmed = Boolean(heldMailKey &&
+        input.smtpSender &&
+        recorded[PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY] !== authLoginEnvMarker(input.smtpSender));
+    if (loginApp.justCreated ||
+        !loginApp.running ||
+        loginEnvsChanged ||
+        loginEnvUnconfirmed ||
+        authRefChanged) {
         await deps.coolify.deploy(loginAppId);
     }
     // The key counts as live only once the app was deployed after it was written: a crash between the write
@@ -2251,11 +2307,17 @@ export async function provisionAuthStack(scope, deps, target, input) {
             signInEnvsChanged ||
             bindKeyWritten ||
             bindKeyUnconfirmed ||
+            loginEnvUnconfirmed ||
             authRefChanged)) {
         await deps.coolify.deploy(signInApp.appId);
         if (input.signInLogin)
             await record(SIGN_IN_BIND_KEY_SCOPE_KEY, '1');
     }
+    // The mail env is live on the login apps: written above and deployed with them. Without the held
+    // key the marker stays unset, so the step is planned again once the key is held.
+    if (heldMailKey && input.smtpSender) {
+        await record(PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY, authLoginEnvMarker(input.smtpSender));
+    }
     // #211: the broker's own `server.ts` refuses to start without
     // `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `LETTERMINT_API_TOKEN` --
     // deploying it without them only produces a container that crash-loops
@@ -4022,8 +4084,9 @@ async function authBrokerBlockedReason(auth, recordedIds) {
     // #210: and `LETTERMINT_API_TOKEN`, once held -- see this function's own
     // doc comment.
     const otherInputsMissing = missing.filter((m) => m !== 'ZITADEL_SERVICE_USER_TOKEN' && !(m === 'LETTERMINT_API_TOKEN' && heldMailKey));
+    const mailKeyHeld = Boolean(heldMailKey);
     if (missing.length === 0)
-        return { reason: null, otherInputsMissing };
+        return { reason: null, otherInputsMissing, mailKeyHeld };
     // #210: say where the operator seals the Lettermint key, not only its env name.
     const named = (names) => names.map((m) => m === 'LETTERMINT_API_TOKEN'
         ? `LETTERMINT_API_TOKEN (seal it under the held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`
@@ -4036,6 +4099,7 @@ async function authBrokerBlockedReason(auth, recordedIds) {
         return {
             reason: `the platform's sign-in broker ${brokerAppId} is blocked, not deployed: its AUTH_APPS is malformed${otherSuffix}`,
             otherInputsMissing,
+            mailKeyHeld,
         };
     }
     // AUTH_APPS isn't gated on #209/#210 the way the two tokens are; only cite
@@ -4044,6 +4108,7 @@ async function authBrokerBlockedReason(auth, recordedIds) {
     return {
         reason: `the platform's sign-in broker is created but not deployed, blocked: it has no ${named(missing).join(' and no ')} yet${suffix}`,
         otherInputsMissing,
+        mailKeyHeld,
     };
 }
 /** Polls until Coolify reports the mail app stopped, so a healthy answer read afterwards is the new deployment's. */
@@ -8119,6 +8184,12 @@ async function edgeBlockedReason(names) {
  * - `EDGE_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.
+ *
+ * foundry#1024: `USAGE_TAIL_WORKER` and `EDGE_USAGE_KEY_HASH` ({@link usageTailEdgeEnv})
+ * are written on every run too, once the usage tail Worker step has deployed
+ * and holds its key; `planEdge` replans this step while the recorded
+ * {@link PLATFORM_EDGE_APPLIED_USAGE_TAIL_SCOPE_KEY} differs from what is
+ * now desired, the same way a changed hostname or `gitRef` does.
  */
 async function provisionPlatformEdge(context, deps) {
     const { platform } = context;
@@ -8228,6 +8299,10 @@ async function provisionPlatformEdge(context, deps) {
         await record(PLATFORM_EDGE_PLATFORM_KEY_SET_SCOPE_KEY, keyHash);
     }
     // ---- base env, written on every run --------------------------------------
+    // foundry#1024: the usage tail Worker's name and the hash of its key, so
+    // every company script can name it as its tail consumer and edge's ingest
+    // route can accept the key. Absent while the Worker is not deployed yet.
+    const usageTailEnv = usageTailEdgeEnv(recorded);
     await deps.coolify.bulkUpsertEnvs(appId, [
         { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
         { key: 'DATABASE_URL', value: runtimeUrl },
@@ -8237,6 +8312,12 @@ async function provisionPlatformEdge(context, deps) {
         { key: 'EDGE_TRUST_CF_CONNECTING_IP', value: 'true' },
         { key: 'NODE_ENV', value: 'production' },
         { key: 'EDGE_PLATFORM_KEY_HASH', value: keyHash },
+        ...(usageTailEnv
+            ? [
+                { key: 'USAGE_TAIL_WORKER', value: usageTailEnv.USAGE_TAIL_WORKER },
+                { key: 'EDGE_USAGE_KEY_HASH', value: usageTailEnv.EDGE_USAGE_KEY_HASH },
+            ]
+            : []),
         ...(await missingEnvs(deps.coolify, appId, PLATFORM_EDGE_RUNNER_DEFAULTS)),
     ]);
     // ---- deploy and wait, on edge's own address ---------------------------------
@@ -8297,6 +8378,7 @@ async function provisionPlatformEdge(context, deps) {
     }
     // Last: a run that failed anywhere above is planned again.
     context.recordScopeId(PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    context.recordScopeId(PLATFORM_EDGE_APPLIED_USAGE_TAIL_SCOPE_KEY, usageTailEdgeEnvValue(recorded));
     await record(PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY, gitRef);
     return { resourceId: appId };
 }

package/dist/plan/usage-tail-worker.d.ts

@@ -0,0 +1,29 @@
+import type { PlatformStepExecutionContext } from './plan-apply.js';
+import type { PlatformWorkersFactory } from './uptime-worker.js';
+/**
+ * Dependencies of the usage tail Worker step. `deliverSecret` and
+ * `heldKeys` are the host's: the minted key goes only to `deliverSecret`,
+ * and it is read back only to hand it to edge, which never returns one.
+ */
+export interface PlatformUsageTailDeps {
+    workers: PlatformWorkersFactory;
+    deliverSecret: (ref: string, secret: string) => Promise<void>;
+    heldKeys: {
+        resolve(ref: string): Promise<string | null>;
+    };
+    /** Tries per key delivery (rule 1), 3 by default. */
+    deliverAttempts?: number;
+    /** Waits between delivery tries; a real timer by default. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * foundry#1024: makes the usage tail Worker true. Upload the pinned edge
+ * release (the host fetches and verifies it) and record the script at once,
+ * so a later failure is a half-made Worker foundry owns. Then hold the key
+ * (minted once, its guard recorded as soon as its value is held) and set it
+ * on the Worker. The applied values are recorded only when all of it
+ * succeeded.
+ */
+export declare function provisionPlatformUsageTail(context: PlatformStepExecutionContext, deps: PlatformUsageTailDeps): Promise<{
+    resourceId?: string;
+}>;