@wtfalch/foundry 0.76.1 → 0.77.0

package/dist/plan/executor.js

@@ -6,17 +6,20 @@ import { coolifyImageFor } from '../bootstrap/versions.js';
 import { redactSecrets } from '../calls-sfu-deploy-support.js';
 import { resolveCallsSfuUrls } from '../calls-sfu.js';
 import { NATIVE_BUILD_KEY_ENV } from '../native-build.js';
-import { AI_ENTRY_PERMISSIONS, APPS_DOMAIN, APP_ENTRY_KEY, FILES_ENTRY_PERMISSIONS, FULL_COMMIT_SHA, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, filesCollectionEnvName, heldEnvRef, isLiveEntry, isMainEntry, kosmosOn, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownsServices, sharedSecretRef, } from '../org.js';
+import { AI_ENTRY_PERMISSIONS, APPS_DOMAIN, APP_ENTRY_KEY, FILES_ENTRY_PERMISSIONS, FILES_SETTINGS_ENV_NAMES, FULL_COMMIT_SHA, MAIL_APP_KEY_ENV, MAIL_SETTINGS_ENV_NAMES, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, filesCollectionEnvName, heldEnvRef, isLiveEntry, isMainEntry, kosmosOn, mailAppKeyOf, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownsServices, sendsMail, sharedSecretRef, signsInBoth, signsInCustomers, } from '../org.js';
 import { adoptedKeysUnreadable, parseAdoptSnapshot } from './adopt.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, AGORA_CLIENT_ID_SCOPE_KEY, AGORA_DEPLOYED_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, DESKTOP_AUTH_PORT, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, chatCallsApplied, chatHasUpstreams, chatIntrospectionAppName, desiredAgoraEnv, desktopAuthInternalName, entryClientIdScopeKey, } from './agora.js';
+import { ensureAiBouleKey } from './ai-boule-key-apply.js';
+import { AI_KEY_PERMISSIONS_SCOPE_KEY, AI_KEY_PREVIOUS_SCOPE_KEY, AI_OFFERS_SCOPE_KEY, parseIds as parseAiIds, } from './ai-boule-key.js';
 import { ANALYTICS_BOULE_APPLIED_SCOPE_KEY, ANALYTICS_BOULE_ENV_NAMES, analyticsBouleMarker, } from './analytics-boule.js';
-import { ANALYTICS_DATABASE_SCOPE_KEY, ANALYTICS_DEPLOYED_SCOPE_KEY, ANALYTICS_OPERATOR_KEY_ENV, analyticsEnvDrift, analyticsHostnameFor, analyticsUrlFor, desiredAnalyticsEnv, } from './analytics.js';
+import { ANALYTICS_DATABASE_SCOPE_KEY, ANALYTICS_DEPLOYED_SCOPE_KEY, ANALYTICS_OPERATOR_KEY_ENV, ANALYTICS_PERSON_KEY_BYTES, ANALYTICS_PERSON_KEY_ENV, analyticsEnvDrift, analyticsHostnameFor, analyticsUrlFor, desiredAnalyticsEnv, } from './analytics.js';
 import { APPS_DATABASE_ADMIN_URL_ENV, applyAppsDbRoute, retireAppsDbRoute, } from './apps-db-route.js';
 import { appsDbAdminUrl, provisionAppsDb } from './apps-db.js';
 import { APPS_ZONES_APPLIED_SCOPE_KEY, applyAppsZones, retireAppsZones } from './apps-zones.js';
 import { applyBlueGreenConnectors, applyBlueGreenServer, applyBlueGreenWeights, applyWorkspaceServer, } from './blue-green-apply.js';
 import { actionsKeyName, bgKey, blueGreenSubjects, colorAppName, healthTokenName, liveAppNameFor, mintActionsKey, mintPinKey, parseGuards, pinKeyName, splitServers, } from './blue-green.js';
 import { BouleOwnersError, httpBouleOwners } from './boule-owners-http.js';
+import { registrarUrl } from './boule.js';
 import { BOULE_ARCHON_CREDENTIAL_ENV, BOULE_ARCHON_PUSHED_AT_SCOPE_KEY, BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_CUSTOMERS_CREDENTIAL_ENV, BOULE_CUSTOMERS_ORG_ENV, BOULE_DATABASE_SCOPE_KEY, BOULE_DEPLOYED_SCOPE_KEY, BOULE_OWNER_SEED_SECRET_ENV, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, BOULE_TEST_CUSTOMERS_ORG_ENV, CUSTOMERS_DIRECTORY_ROLES_SCOPE_KEY, CUSTOMERS_DIRECTORY_ROLES_VERSION, CUSTOMERS_DIRECTORY_USER_SCOPE_KEY, CUSTOMERS_POLICY_SCOPE_KEY, CUSTOMERS_POLICY_VERSION, CUSTOMERS_ROOM_METADATA_KEY, CUSTOMERS_ROOM_SCOPE_KEY, CUSTOMERS_SIGN_IN_METADATA_KEY, CUSTOMERS_SIGN_IN_SCOPE_KEY, CUSTOMERS_SIGN_UP_SCOPE_KEY, archonCredentialRenewDue, bouleArchonCredentialRef, bouleEnvDrift, bouleHostnameFor, bouleMailWanted, bouleOwnerRefusedScopeKey, bouleOwnerSeededScopeKey, bouleOwnerSeeds, customersDirectoryRef, customersOrgIdOf, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, entryMcp, entryMcpProjectScopeKey, mcpCallbackUri, removeBrokerEntry, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { REGISTRAR_TOKEN_ORGS_SCOPE_KEY, REGISTRAR_TOKEN_USER_NAME, registrarOrgIdsOf, registrarOrgsMarker, } from './broker-registrar-token.js';
@@ -47,10 +50,13 @@ import { applyEntryAudit } from './entry-audit.js';
 import { AUTH_EVENTS_ENV, authEventsAppliedScopeKey, authEventsMarker, authEventsWanted, ensureAuthEventsSecret, heldAuthEventsSecret, } from './entry-auth-events.js';
 import { CUSTOMER_GRANTS_CREDENTIAL_ENV, CUSTOMER_GRANTS_ENV, CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY, customerGrantsEntries, customerGrantsJson, customerGrantsMintedScopeKey, customerGrantsRef, customerGrantsToDrop, ensureCustomerGrantsCredential, wantedCustomerGrants, } from './entry-customer-grants.js';
 import { BOULE_EDGE_ENTRY_KEY, EDGE_ENTRY_KEY_DAYS, EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY, EDGE_SLUG_APPLIED_SCOPE_KEY, ENTRY_EDGE_KEY_DELIVERY_ATTEMPTS, bouleEdgeKeyWanted, edgeKeyAppRecordKey, edgeKeyDomain, entryEdgeMintedAtScopeKey, entryEdgeRetiredScopeKey, entryEdgeUndeliveredScopeKey, } from './entry-edge-key.js';
-import { FILES_AGORA_KEY_SCOPE_KEY, FILES_AGORA_UNDELIVERED_SCOPE_KEY, FILES_KEY_DAYS, FILES_KEY_RENEW_WINDOW_DAYS, FILES_ORG_OWNER_SCOPE_KEY, FILES_ROOT_EXPIRES_SCOPE_KEY, FILES_ROOT_PREVIOUS_SCOPE_KEY, FILES_ROOT_UNDELIVERED_SCOPE_KEY, FILES_ROOT_UNREVOKED_SCOPE_KEY, entryFilesAppliedScopeKey, entryFilesExpiresScopeKey, entryFilesMinterScopeKey, entryFilesPendingExpiresScopeKey, entryFilesRetiredScopeKey, entryFilesUndeliveredScopeKey, entryFilesUnrevokedScopeKey, entryFilesWrittenScopeKey, filesOwnerUserId, parseIdList as parseFilesIdList, } from './entry-files-key.js';
+import { FILES_AGORA_KEY_SCOPE_KEY, FILES_AGORA_UNDELIVERED_SCOPE_KEY, FILES_KEY_DAYS, FILES_KEY_RENEW_WINDOW_DAYS, FILES_ORG_OWNER_SCOPE_KEY, FILES_ROOT_EXPIRES_SCOPE_KEY, FILES_ROOT_PERMISSIONS_SCOPE_KEY, FILES_ROOT_PREVIOUS_SCOPE_KEY, FILES_ROOT_UNDELIVERED_SCOPE_KEY, FILES_ROOT_UNREVOKED_SCOPE_KEY, bouleKeyBelow, entryFilesAppliedScopeKey, entryFilesCollectionsScopeKey, entryFilesExpiresScopeKey, entryFilesMinterScopeKey, entryFilesPendingExpiresScopeKey, entryFilesRetiredScopeKey, entryFilesUndeliveredScopeKey, entryFilesUnrevokedScopeKey, entryFilesWrittenScopeKey, filesOwnerUserId, knownCollectionNames, parseIdList as parseFilesIdList, } from './entry-files-key.js';
+import { ensureJobsBouleKey, retireJobsBouleKey } from './entry-jobs-boule-key-apply.js';
 import { entryJobsAppliedScopeKey, entryJobsRefs, entryJobsUndeliveredScopeKey, entryJobsWantMarker, } from './entry-jobs.js';
 import { ensureRepoKey, removeRepoKey } from './entry-repo-key-apply.js';
+import { ENTRY_REPORTING_KEY_DELIVERY_ATTEMPTS, entryReportingAppliedScopeKey, entryReportingRetiredScopeKey, entryReportingUndeliveredScopeKey, stageReportingKeyName, } from './entry-reporting-key.js';
 import { BROKER_WORKSPACES_DATABASE_ENV, ensureWorkspacesKey, heldWorkspacesDatabase, heldWorkspacesKey, workspacesDatabaseRef, workspacesKeyHash, workspacesKeyRef, } from './entry-workspaces.js';
+import { ensureFilesBouleKey, retireFilesBouleKey } from './files-boule-key-apply.js';
 import { GATE_CLAIM_NAME, gateHostnamesScopeKey, gateIdRecordKey, isBehindGate } from './gates.js';
 import { GITHUB_SOURCE_INSTALLATION_SCOPE_KEY, GITHUB_SOURCE_TIMEOUT_MS, ensureGithubSource, githubSourceResourceKey, } from './github-source.js';
 import { IMAGE_HEALTHCHECK_SETTINGS, commandHealthCheckSettings, healthCheckSettings, wgetProbe, } from './health-check-settings.js';
@@ -78,8 +84,12 @@ import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_
 import { AUTH_LOGIN_PORT, PLATFORM_AUTH_BROKER_MAIL_KEY_REF, PLATFORM_AUTH_LOGIN_INTERNAL_NAME, PLATFORM_AUTH_LOGIN_SCOPE_KEY, PLATFORM_AUTH_ORG_NAME, PLATFORM_AUTH_PROJECT, PLATFORM_MAIL_SERVER_SCOPE_KEY, defaultStalwartForInstance, filesDepsInvalid, filesShareDomains, provisionAuthStack, provisionDatabaseBackup, provisionFilesHost, provisionJobsHost, provisionMailServer, resolveOwnFilesKeys, } from './platform-providers.js';
 import { companyAppPostLogoutUris, postLogoutAppliedValue, postLogoutUrisFor, zitadelAppPostLogoutAppliedScopeKey, } from './post-logout-uris.js';
 import { CLOUDFLARE_TUNNEL_APPS_HOSTNAMES_SCOPE_KEY, CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY, CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY, ENTRY_CONTAINER_LABELS, appLabelsAppliedScopeKey, builtinRoutes, entryAppsHostnames, entryLabelHash, entryLabelSpec, entryOikosHostnames, entryProxyLabels, entryRoutes, entryRoutesMarker, ownsAppsZoneName, ownsOikosName, routesWithoutToken, sameLabelSets, } from './proxy-labels.js';
+import { liveRegisteredClientIds, registeredAppAppliedScopeKey, registeredAppEnvScopeKey, } from './registered-app-env.js';
+import { REGISTERED_APP_KIND, copyClientKey, registeredCopies, sendRegistration, wantedRegisteredApp, } from './registered-app.js';
 import { STAGE_DEPLOY_ATTEMPTS, STAGE_DEPLOY_INTERVAL_MS, createReleaseHost, } from './release-host.js';
 import { TUNNEL_HTTP_INGRESS_SCOPE_KEY, applyRemoteDatabase, mergeTcpIngress, recordedTcpRoutes, } from './remote-database.js';
+import { REPORTING_BOULE_APPLIED_SCOPE_KEY, REPORTING_BOULE_ENV_NAMES, reportingBouleMarker, } from './reporting-boule.js';
+import { REPORTING_DATABASE_SCOPE_KEY, REPORTING_DEPLOYED_SCOPE_KEY, REPORTING_OPERATOR_KEY_ENV, desiredReportingEnv, reportingEnvDrift, reportingHostnameFor, reportingUrlFor, } from './reporting.js';
 import { editSignInBindings } from './sign-in-bindings.js';
 import { ZITADEL_ORG_DOMAIN_SCOPE_KEY, ZITADEL_ORG_REGISTRATION_CLOSED_SCOPE_KEY, closeSignInOrgRegistration, ensureSignInOrg, inviteOwnerWithLink, registerSignInDomainOrBlock, signInOrgDomain, } from './sign-in-org.js';
 import { SIGN_IN_BASE_PATH, SIGN_IN_ENV_LIVE_SCOPE_PREFIX, SIGN_IN_IN_APP_SCOPE_KEY, SIGN_IN_LOGIN_APP_SCOPE_KEY, SIGN_IN_RATE_LIMIT_DESCRIPTION, SIGN_IN_RATE_LIMIT_EXPRESSION, SIGN_IN_RATE_LIMIT_SCOPE_KEY, SIGN_IN_TRUSTED_SCOPE_KEY, SIGN_IN_UPSTREAM_ENV, inAppBindingFor, inAppSignIn, inAppStateHosts, inAppStatePairs, inAppTargets, signInEnvLiveHosts, } from './sign-in.js';
@@ -416,6 +426,13 @@ export const KOSMOS_PORT = 3000;
 export const ANALYTICS_REPO = 'wtfalch/analytics';
 export const ANALYTICS_APP_DOCKERFILE = '/Dockerfile';
 export const ANALYTICS_PORT = 3000;
+/**
+ * The company's reporting backend (https://github.com/wtfalch/reporting, `apps/host`): root Dockerfile, serves
+ * on 3000 and answers `/api/health`, migrates in its own start script, as the analytics host does.
+ */
+export const REPORTING_REPO = 'wtfalch/reporting';
+export const REPORTING_APP_DOCKERFILE = '/Dockerfile';
+export const REPORTING_PORT = 3000;
 /**
  * Every app foundry deploys keeps its own logs across a redeploy, so a
  * database outage does not also erase the only other copy of the evidence
@@ -965,6 +982,7 @@ function limitProfileOf(action) {
             return undefined;
         case 'coolify:broker-entry':
         case 'coolify:workspace-broker-entry':
+        case `coolify:${REGISTERED_APP_KIND}`:
         case 'coolify:workspaces-database':
             return LIMITS.brokerEntry;
         case 'cms:site':
@@ -985,6 +1003,8 @@ function limitProfileOf(action) {
             return LIMITS.kosmos;
         case 'coolify:analytics':
             return LIMITS.analytics;
+        case 'coolify:reporting':
+            return LIMITS.reporting;
         case 'coolify:broker-registrar':
             return LIMITS.brokerEntry;
         case 'coolify:keys-registrar':
@@ -1372,6 +1392,8 @@ export class FoundryStepExecutor {
                 return this.coolifyBrokerEntry(action, org, context);
             case 'coolify:workspace-broker-entry':
                 return this.coolifyWorkspaceBrokerEntry(action, org, context);
+            case `coolify:${REGISTERED_APP_KIND}`:
+                return this.coolifyRegisteredApp(action, org, context);
             case 'coolify:workspaces-database':
                 return this.coolifyWorkspacesDatabase(org, context);
             case 'coolify:database':
@@ -1417,13 +1439,17 @@ export class FoundryStepExecutor {
             }
             case 'files:organisation':
                 return this.filesOrganisation(action, org, context);
+            case 'files:boule-key':
+                return this.filesBouleKey(action, org, context);
             case 'files:key':
                 // The org's own key is keyed `<orgId>`, an entry's `<orgId>:<entry>` (F6b).
                 return action.key.includes(':')
                     ? this.filesEntryKey(action, org, context)
                     : this.filesRootKey(action, org, context);
             case 'ai:organisation':
-                return this.aiOrganisation(action, org);
+                return this.aiOrganisation(action, org, context);
+            case 'ai:boule-key':
+                return this.aiBouleKey(action, org, context);
             case 'ai:budget':
                 return this.aiBudget(action, org, context);
             case 'ai:key':
@@ -1439,6 +1465,8 @@ export class FoundryStepExecutor {
                 return this.edgeSlug(action, org, context);
             case 'jobs:project':
                 return this.jobsProject(action, org, context);
+            case 'jobs:boule-key':
+                return this.jobsBouleKey(action, org, context);
             case 'github:deploy-key':
                 return this.githubDeployKey(action, org, context);
             case 'audit:ledger':
@@ -1469,6 +1497,12 @@ export class FoundryStepExecutor {
                 return this.analyticsBoule(action, org, context);
             case 'analytics:key':
                 return this.analyticsEntryKey(action, org, context);
+            case 'coolify:reporting':
+                return this.coolifyReporting(action, org, context);
+            case 'coolify:reporting-boule':
+                return this.reportingBoule(action, org, context);
+            case 'reporting:key':
+                return this.reportingEntryKey(action, org, context);
             case 'coolify:broker-registrar':
                 return this.brokerRegistrar(org, context);
             case 'coolify:keys-registrar':
@@ -3460,7 +3494,7 @@ export class FoundryStepExecutor {
             isRunning: isRunningOrStarting,
             stageGuards: this.stageGuards(org, subject, recorded(), action.desired.accessProviderId, context),
             guardInputs: parseGuards(action.desired.guards),
-            stageSink: { slug: org.slug },
+            stageSink: stageSinkFor(org, subject.builtin ? undefined : subject.id),
         };
         if (action.kind === 'bluegreen-lb') {
             await applyBlueGreenWeights(deps, subject, { uuid: serverUuid, primaryUuid });
@@ -3520,7 +3554,7 @@ export class FoundryStepExecutor {
             logDir: LOG_DIR,
             isRunning: isRunningOrStarting,
             stageGuards: guards,
-            stageSink: { slug: org.slug },
+            stageSink: stageSinkFor(org, entry.key),
             stageAppUrl: `https://${host}`,
             ...(signIn ? { signIn } : {}),
         }, subject, serverUuid);
@@ -3599,13 +3633,14 @@ export class FoundryStepExecutor {
         const liveMcp = org.hosting.entries.filter((live) => live.uses?.auth?.mcp);
         return {
             env,
-            customers: auth.users === 'customers',
+            customers: signsInCustomers(auth),
             redirectUri: `https://${workspaceClientHosts(org, entry)[0]}/auth/callback`,
             live: {
                 ...(recorded[`zitadel:customers:${org.id}`]
                     ? { customersOrgId: recorded[`zitadel:customers:${org.id}`] }
                     : {}),
                 clientIds: liveClientIds(org, recorded),
+                teamClientIds: liveRegisteredClientIds(org, recorded).teamClientIds,
                 workspacesKeys,
                 mcpAudiences: liveMcp.flatMap((m) => recorded[entryMcpProjectScopeKey(m.key)] ?? []),
                 mcpResources: liveMcp.flatMap((m) => entryMcp(org, m, recorded)?.resource ?? []),
@@ -3646,6 +3681,101 @@ export class FoundryStepExecutor {
         });
         return {};
     }
+    /**
+     * `coolify:registered-app` (`plan/registered-app.ts`, ADR 0003): one copy of an entry whose customers and team
+     * both sign in, registered at the sign-in broker through the company's registrar with
+     * `users: ['customers', 'staff']`. The answer (the customers' and the team's clients, both organisations and a
+     * new `AUTH_APP_KEY`) goes to the copy's app (the entry's app, or the workspace's stage), which restarts. The
+     * ids are recorded after the env is written, the want last, so a failure anywhere registers again on the next
+     * apply (the broker keeps the key it replaced valid for a window). The registrar key and the app key are
+     * registered for redaction and never recorded; errors name the copy and a status at most.
+     */
+    async coolifyRegisteredApp(action, org, context) {
+        const at = `coolify:${REGISTERED_APP_KIND} for ${org.slug}`;
+        const api = this.ports.registrarApi;
+        if (!api)
+            throw new Error(`${at}: the registrar API port is not wired`);
+        const copy = action.desired.copy;
+        const entry = org.hosting.entries.find((e) => e.key === String(action.desired.entry ?? '') && signsInBoth(e.uses?.auth));
+        if (!entry || !registeredCopies(entry).includes(copy)) {
+            throw new Error(`${at}: no entry both sign in to for ${action.key}`);
+        }
+        const authIssuer = action.desired.authIssuer ?? null;
+        if (!authIssuer)
+            throw new Error(`${at}: the sign-in issuer is not known yet`);
+        const recorded = context.recordedIds();
+        const wanted = wantedRegisteredApp(org, entry, copy, recorded);
+        if ('missing' in wanted) {
+            throw new Error(`${at}: ${wanted.missing.map((m) => m.what).join(', ')} not recorded yet`);
+        }
+        const clientKey = copyClientKey(entry, copy);
+        let appId;
+        if (copy === 'live') {
+            appId = recorded[`coolify:app:${appStepKey(org, entry.key)}`];
+        }
+        else {
+            const stagePrefix = `bg.${entry.key}.app.`;
+            appId = Object.entries(recorded).find(([key, id]) => id && key.startsWith(stagePrefix) && key.endsWith('.stage'))?.[1];
+        }
+        if (!appId)
+            throw new Error(`${at}: the app of ${clientKey} is not recorded yet`);
+        const held = this.ports.heldKeys;
+        const ref = registrarRef(org.id);
+        const registrarKey = held
+            ? await withLabelledTimeout('held key read', HELD_KEY_READ_TIMEOUT_MS, () => held.resolve(ref)).catch(() => {
+                throw new Error(`${at}: the registrar key could not be read (ref ${ref})`);
+            })
+            : null;
+        if (!registrarKey)
+            throw new Error(`${at}: the registrar key is not held (ref ${ref})`);
+        this.handledSecrets.add(registrarKey);
+        const { env, appKey } = await sendRegistration({
+            want: wanted.want,
+            registrarUrl: registrarUrl(authIssuer),
+            registrarKey,
+            api,
+            secret: (value) => void this.handledSecrets.add(value),
+            // A workspace copy must hold none of the live app's clients.
+            refusedClientIds: copy === 'workspace' ? liveClientIds(org, recorded) : [],
+            label: `${at} (${clientKey})`,
+        });
+        const envs = [
+            { key: 'AUTH_ISSUER', value: authIssuer },
+            { key: 'AUTH_ORGANIZATION_ID', value: env.AUTH_ORGANIZATION_ID },
+            { key: 'AUTH_CLIENT_ID', value: env.AUTH_CLIENT_ID },
+            { key: 'AUTH_TEAM_CLIENT_ID', value: env.AUTH_TEAM_CLIENT_ID },
+            { key: 'AUTH_TEAM_ORGANIZATION_ID', value: env.AUTH_TEAM_ORGANIZATION_ID },
+            { key: 'AUTH_APP_KEY', value: appKey },
+        ];
+        let written = false;
+        for (let attempt = 0; attempt < 3 && !written; attempt++) {
+            try {
+                await this.ports.coolify.bulkUpsertEnvs(appId, envs);
+                written = true;
+            }
+            catch {
+                // Tried again below; the error that leaves names the copy only.
+            }
+        }
+        if (!written) {
+            throw new Error(`${at}: the sign-in env of ${clientKey} could not be written; the next apply registers it again`);
+        }
+        await this.ports.coolify.restart(appId);
+        context.recordScopeId(registeredAppEnvScopeKey(clientKey), JSON.stringify(env));
+        // What the app step and the workspace step compare against, so neither pushes the same env again.
+        const now = context.recordedIds();
+        if (copy === 'live') {
+            context.recordScopeId(entryAuthEnvAppliedScopeKey(entry.key), JSON.stringify(entryAuthEnv(org, entry, now, authIssuer)));
+        }
+        else {
+            const marker = workspaceSignInMarker(org, entry, now, authIssuer);
+            if (marker)
+                context.recordScopeId(wsKey.signIn(entry.key), marker);
+        }
+        context.recordScopeId(registeredAppAppliedScopeKey(clientKey), JSON.stringify(wanted.want));
+        await context.persistScopeIds();
+        return {};
+    }
     /**
      * `coolify:workspaces-database` (`plan/broker-workspaces-database.ts`): the broker's workspaces database, made
      * beside the broker (the platform's project and network, or the company's own for an org that owns its services)
@@ -3984,8 +4114,43 @@ export class FoundryStepExecutor {
                 };
             },
         };
+        const reporting = {
+            held: held('reporting'),
+            available: async () => canHold &&
+                Boolean(this.ports.reporting) &&
+                Boolean(context.recordedIds()[`coolify:reporting:${org.id}`]) &&
+                entry?.uses?.reporting === true,
+            create: async () => {
+                const port = this.ports.reporting;
+                if (!port)
+                    throw new Error('no reporting port');
+                const operatorKey = await this.reportingOperatorKey(org, context);
+                const name = stageReportingKeyName(org, subject.id);
+                // Site = the entry key, as the live key's: Boule reads the workspace's errors with environment `stage`.
+                const minted = await port.mintSiteKey({
+                    baseUrl: reportingUrlFor(org),
+                    operatorKey,
+                    name,
+                    site: subject.id,
+                    environment: 'stage',
+                });
+                return {
+                    id: minted.id,
+                    name,
+                    keyIds: [minted.id],
+                    secrets: [{ env: 'REPORTING_SITE_KEY', value: minted.secret }],
+                };
+            },
+        };
         const prodJobsProjectId = context.recordedIds()[`jobs:registration:${org.id}`];
-        return { files, ai, jobs, analytics, ...(prodJobsProjectId ? { prodJobsProjectId } : {}) };
+        return {
+            files,
+            ai,
+            jobs,
+            analytics,
+            reporting,
+            ...(prodJobsProjectId ? { prodJobsProjectId } : {}),
+        };
     }
     /**
      * Stage's own sign-in (`plan/stage-signin.ts`): a client named `<production client>-stage` on production's
@@ -5027,6 +5192,11 @@ export class FoundryStepExecutor {
             // #75 "What belongs where") once `ensureLogVolume` has mounted the
             // matching volume.
             { key: 'LOG_DIR', value: LOG_DIR },
+            // An entry that sends mail tags each send with its key (`@wtfalch/mailer` 0.10.0), so Archon's mail reads
+            // split mail per app. Not in the appEnv marker: `planApp` plans it from the live env names, once.
+            ...(sendsMail(entry)
+                ? [{ key: MAIL_APP_KEY_ENV, value: mailAppKeyOf(entry.key, 'live') }]
+                : []),
         ];
         // An entry with `uses.auth` signs in one organisation, with its own client
         // and the issuer; any other entry keeps the org's staff organisation and
@@ -5035,7 +5205,7 @@ export class FoundryStepExecutor {
         if (entry.uses?.auth) {
             // A customers entry never falls back to the staff organisation's id.
             if (!authEnv.AUTH_ORGANIZATION_ID) {
-                throw new Error(`coolify:app for ${org.slug}: entry '${entry.key}' signs in ${entry.uses.auth.users}, whose organisation id is not recorded yet`);
+                throw new Error(`coolify:app for ${org.slug}: entry '${entry.key}' signs in ${signsInCustomers(entry.uses.auth) ? 'customers' : 'staff'}, whose organisation id is not recorded yet`);
             }
             for (const [key, value] of Object.entries(authEnv))
                 envs.push({ key, value });
@@ -5135,7 +5305,14 @@ export class FoundryStepExecutor {
             const live = await this.ports.coolify.listEnvs(appId);
             heldChanged = heldEnvs.some(({ key, value }) => !live.some((e) => e.key === key && !e.is_preview && e.value === value));
         }
+        // `MAIL_APP_KEY` is not in the marker either: a running app that lacks it, or holds another, restarts once.
+        let mailKeyChanged = false;
+        if (sendsMail(entry)) {
+            const want = mailAppKeyOf(entry.key, 'live');
+            mailKeyChanged = !(await this.ports.coolify.listEnvs(appId)).some((e) => e.key === MAIL_APP_KEY_ENV && !e.is_preview && e.value === want);
+        }
         await this.ports.coolify.bulkUpsertEnvs(appId, envs);
+        await this.dropUnsetSettingsEnv(appId, entry, recorded, resolved.marker);
         // `coolifyApp` records `applied` once the restart succeeded, so `planApp`
         // replans this step when the declared map changes (rule 3). Ids and a
         // domain, never a secret.
@@ -5146,6 +5323,7 @@ export class FoundryStepExecutor {
         return {
             changed: applied !== (recorded[appEnvAppliedScopeKey(entry.key)] ?? '{}') ||
                 heldChanged ||
+                mailKeyChanged ||
                 (Boolean(entry.uses?.auth) &&
                     (authApplied !== (recorded[entryAuthEnvAppliedScopeKey(entry.key)] ?? '{}') ||
                         authEventsMarker(entry) !== (recorded[authEventsAppliedScopeKey(entry.key)] ?? ''))),
@@ -5154,6 +5332,37 @@ export class FoundryStepExecutor {
             eventsApplied: authEventsMarker(entry),
         };
     }
+    /**
+     * #1116: takes a module setting's env name (`MAIL_REPLY_TO`, ...) out of the app's env once the setting is
+     * unset or its module is off. Only a name the last applied env wrote (the recorded marker) and the entry's
+     * own `env` does not declare, so a value the company set by hand stays.
+     */
+    async dropUnsetSettingsEnv(appId, entry, recorded, marker) {
+        let last = {};
+        try {
+            const parsed = JSON.parse(recorded[appEnvAppliedScopeKey(entry.key)] ?? '{}');
+            if (parsed && typeof parsed === 'object')
+                last = parsed;
+        }
+        catch {
+            return;
+        }
+        const gone = [...FILES_SETTINGS_ENV_NAMES, ...MAIL_SETTINGS_ENV_NAMES].filter((name) => name in last && !(name in marker) && !(name in (entry.env ?? {})));
+        if (gone.length === 0)
+            return;
+        const rows = await this.ports.coolify.listEnvs(appId);
+        for (const row of rows) {
+            if (!gone.includes(row.key) || !row.uuid)
+                continue;
+            try {
+                await this.ports.coolify.deleteEnv(appId, row.uuid);
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+        }
+    }
     /** Takes `AUTH_EVENTS_SECRET` out of the app's env once the entry stops declaring events. The held value stays: the held store has no delete. */
     async dropAuthEventsEnv(appId) {
         const rows = await this.ports.coolify.listEnvs(appId);
@@ -5416,12 +5625,12 @@ export class FoundryStepExecutor {
      * third, bare copy of this check (foundry#970, thermo note 1 in #957). Omitted, the three existing
      * callers below keep their original behaviour.
      */
-    async mintIfAbsent(appId, key, bytes, minLength) {
+    async mintIfAbsent(appId, key, bytes, minLength, encoding = 'base64url') {
         const envs = await this.ports.coolify.listEnvs(appId);
         const already = envs.some((e) => e.key === key &&
             !e.is_preview &&
             (minLength === undefined || (e.value ?? '').length >= minLength));
-        return already ? null : randomBytes(bytes).toString('base64url');
+        return already ? null : randomBytes(bytes).toString(encoding);
     }
     /**
      * foundry#987: nothing reads `NATIVE_BUILD_KEY` any more -- Boule calls Archon's org build
@@ -5629,6 +5838,8 @@ export class FoundryStepExecutor {
                 add(recorded[`coolify:app:${appStepKey(org, entry.key)}`]);
             }
         }
+        // The company's reporting backend sends its alerts with the same token (foundry#1128).
+        add(recorded[`coolify:reporting:${org.id}`]);
         add(self.id);
         const envsOf = (id) => id === self.id
             ? this.ports.coolify.listEnvs(id)
@@ -5669,6 +5880,7 @@ export class FoundryStepExecutor {
             allProjects = [...projects, created.project];
             token = created.token;
         }
+        this.handledSecrets.add(token);
         // A healthy company: this step writes only its own env; a peer that lacks
         // the token gets it in its own step. A re-mint kills the old token, so it
         // reaches every live consumer here.
@@ -8076,7 +8288,9 @@ export class FoundryStepExecutor {
      *
      * `ANALYTICS_OPERATOR_KEY` is made once here (`mintIfAbsent`) and written only to this app's env. No outside
      * service shows it once, so no undelivered marker is needed: a failed write leaves nothing live to mint twice.
-     * Steps that call the backend's operator API read it back from this env.
+     * Steps that call the backend's operator API read it back from this env. `ANALYTICS_PERSON_KEY` (64 hex
+     * characters, analytics#109: the per-site key that counts a signed-in person once) is made the same way and
+     * never rotated: a value already in the env, made here or by hand, is kept.
      *
      * A brand new app is deployed once ({@link ANALYTICS_DEPLOYED_SCOPE_KEY}), as for Boule (#504).
      */
@@ -8122,13 +8336,20 @@ export class FoundryStepExecutor {
             this.handledSecrets.add(operatorKey);
             envs.push({ key: ANALYTICS_OPERATOR_KEY_ENV, value: operatorKey });
         }
+        // foundry#1137: rotating this key would count every signed-in person twice, so a held value is kept.
+        const personKey = await this.mintIfAbsent(app.appId, ANALYTICS_PERSON_KEY_ENV, ANALYTICS_PERSON_KEY_BYTES, undefined, 'hex');
+        if (personKey) {
+            this.handledSecrets.add(personKey);
+            envs.push({ key: ANALYTICS_PERSON_KEY_ENV, value: personKey });
+        }
+        const minted = [operatorKey, personKey].filter((k) => k !== null);
         try {
             await this.ports.coolify.bulkUpsertEnvs(app.appId, envs);
         }
         catch (error) {
-            if (!operatorKey)
+            if (minted.length === 0)
                 throw error;
-            throw new Error(redactSecrets(error instanceof Error ? error.message : String(error), [operatorKey]));
+            throw new Error(redactSecrets(error instanceof Error ? error.message : String(error), minted));
         }
         const dbPush = await this.pushDatabaseUrl(app.appId, dbId, dbName);
         if (!dbPush.pushed) {
@@ -8140,7 +8361,7 @@ export class FoundryStepExecutor {
             await recordBuiltCommit(this.ports.coolify, { appId: app.appId, deploymentUuid: built.deploymentUuid, name: 'analytics' }, (key, value) => context.recordScopeId(key, value));
             context.recordScopeId(ANALYTICS_DEPLOYED_SCOPE_KEY, '1');
         }
-        else if (app.existed && (envChanged || operatorKey !== null || dbPush.changed)) {
+        else if (app.existed && (envChanged || minted.length > 0 || dbPush.changed)) {
             await this.ports.coolify.restart(app.appId);
         }
         return { resourceId: app.appId };
@@ -8314,6 +8535,264 @@ export class FoundryStepExecutor {
         }
         throw new Error(`${at}: key ${minted.id} was minted but could not be written to the app's env after ${ENTRY_ANALYTICS_KEY_DELIVERY_ATTEMPTS} attempts (${lastError instanceof Error ? lastError.name : 'error'})`);
     }
+    // ---- reporting backend (wtfalch/reporting ADR 0002) ----------------------
+    /**
+     * `plan/diff.ts`'s `planReportingBackend`: the company's reporting backend as one more Coolify application
+     * from https://github.com/wtfalch/reporting's root Dockerfile ({@link REPORTING_REPO}), with a database of its
+     * own, a copy of {@link coolifyAnalytics}. Its start script migrates as the owner role and then serves as the
+     * runtime role, so `pushDatabaseUrl` gives it both URLs. It needs no sign-in client: it reads only
+     * `AUTH_ORGANIZATION_ID` (the tenant id derives from it), `APP_URL` and the operator key.
+     *
+     * `REPORTING_OPERATOR_KEY` is made once here (`mintIfAbsent`) and written only to this app's env. No outside
+     * service shows it once, so no undelivered marker is needed: a failed write leaves nothing live to mint twice.
+     * Steps that call the backend's operator API read it back from this env.
+     *
+     * A brand new app is deployed once ({@link REPORTING_DEPLOYED_SCOPE_KEY}), as for Boule (#504).
+     */
+    async coolifyReporting(action, org, context) {
+        // Mail only when the plan showed it (`desired.mail`), from the recorded domain.
+        const mailDomain = action.desired.mail === true ? (context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY] ?? null) : null;
+        const { env, missing } = desiredReportingEnv(org, context.recordedIds(), mailDomain);
+        if (missing.length > 0) {
+            throw new Error(`the reporting backend for ${org.slug} cannot be configured: missing ${missing.join(', ')}. Nothing was written.`);
+        }
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const name = `${org.slug}-reporting`;
+        const dbName = `${org.slug}-reporting-db`.replace(/-/g, '_');
+        const dbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, `${org.slug}-reporting-db`, dbName, REPORTING_DATABASE_SCOPE_KEY);
+        context.recordScopeId(REPORTING_DATABASE_SCOPE_KEY, dbId);
+        const server = await this.resolveServer(org, context);
+        const githubApp = await this.ports.coolify.requireGithubApp();
+        const app = await this.findOrCreateCallsApp(name, environment.id, () => this.ports.coolify.createGithubAppApplication({
+            is_preview_deployments_enabled: false,
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: REPORTING_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name,
+            domains: coolifyTunnelDomains([reportingHostnameFor(org)]),
+            dockerfile_location: REPORTING_APP_DOCKERFILE,
+        }));
+        await this.ensureLogVolume(app.appId, org, app.existed);
+        await this.ports.coolify.updateApplication(app.appId, {
+            ...healthCheckSettings('/api/health', REPORTING_PORT),
+            ...(await this.routedLabels(name, reportingHostnameFor(org), REPORTING_PORT)),
+        });
+        const liveEnv = Object.fromEntries((await this.ports.coolify.listEnvs(app.appId))
+            .filter((e) => !e.is_preview)
+            .map((e) => [e.key, e.value]));
+        const envChanged = reportingEnvDrift(env, liveEnv).length > 0;
+        const envs = Object.entries(env).map(([key, value]) => ({ key, value }));
+        const operatorKey = await this.mintIfAbsent(app.appId, REPORTING_OPERATOR_KEY_ENV, 32);
+        if (operatorKey) {
+            this.handledSecrets.add(operatorKey);
+            envs.push({ key: REPORTING_OPERATOR_KEY_ENV, value: operatorKey });
+        }
+        try {
+            await this.ports.coolify.bulkUpsertEnvs(app.appId, envs);
+        }
+        catch (error) {
+            if (!operatorKey)
+                throw error;
+            throw new Error(redactSecrets(error instanceof Error ? error.message : String(error), [operatorKey]));
+        }
+        const dbPush = await this.pushDatabaseUrl(app.appId, dbId, dbName);
+        if (!dbPush.pushed) {
+            throw new Error(`the reporting backend for ${org.slug}: its database has no internal_db_url yet -- retry this apply once Coolify reports one`);
+        }
+        // The company's `<slug>-app` Lettermint token, joined as a consumer before the first deploy, so the
+        // backend starts with it. `MAIL_FROM` went in with the env above.
+        const mail = mailDomain
+            ? await this.ensureBouleMail(app.appId, org, context, action, app.existed && Boolean(context.recordedIds()[REPORTING_DEPLOYED_SCOPE_KEY]), 'reporting')
+            : { changed: false, restarted: false };
+        if (!context.recordedIds()[REPORTING_DEPLOYED_SCOPE_KEY]) {
+            const runtime = this.ports.runtime ?? {};
+            const built = await waitForNewDeployment(this.ports.coolify, app.appId, publicHealthCheck(org, context.recordedIds(), reportingHostnameFor(org), '/api/health'), runtime, runtime.sleep ?? defaultSleep, 'coolify:reporting', `${org.slug}'s reporting backend stays at its previous deploy`);
+            await recordBuiltCommit(this.ports.coolify, { appId: app.appId, deploymentUuid: built.deploymentUuid, name: 'reporting' }, (key, value) => context.recordScopeId(key, value));
+            context.recordScopeId(REPORTING_DEPLOYED_SCOPE_KEY, '1');
+        }
+        else if (app.existed &&
+            !mail.restarted &&
+            (envChanged || operatorKey !== null || dbPush.changed || mail.changed)) {
+            await this.ports.coolify.restart(app.appId);
+        }
+        return { resourceId: app.appId };
+    }
+    /** The backend's operator key, read from its own env. Fixed text when the backend or the key is not there. */
+    async reportingOperatorKey(org, context) {
+        const appId = context.recordedIds()[`coolify:reporting:${org.id}`];
+        if (!appId)
+            throw new Error(`the reporting backend for ${org.slug} is not recorded yet`);
+        const rows = await this.ports.coolify.listEnvs(appId);
+        const key = rows.find((e) => e.key === REPORTING_OPERATOR_KEY_ENV && !e.is_preview)?.value;
+        if (!key)
+            throw new Error(`the reporting backend for ${org.slug} has no operator key yet`);
+        this.handledSecrets.add(key);
+        return key;
+    }
+    /**
+     * `coolify:reporting-boule` (`plan/reporting-boule.ts`): the backend's address and operator key into
+     * Boule's env, then Boule restarts. `reporting_boule_applied` is recorded last. Retire takes both names away.
+     */
+    async reportingBoule(action, org, context) {
+        const at = `coolify:reporting-boule for ${org.slug}`;
+        const recorded = context.recordedIds();
+        const bouleId = recorded[`coolify:boule:${org.id}`];
+        if (!bouleId)
+            throw new Error(`${at}: Boule is not recorded yet`);
+        if (action.desired.mode === 'retire') {
+            const rows = await this.ports.coolify.listEnvs(bouleId);
+            for (const name of REPORTING_BOULE_ENV_NAMES) {
+                const row = rows.find((e) => e.key === name && !e.is_preview);
+                if (row?.uuid) {
+                    try {
+                        await this.ports.coolify.deleteEnv(bouleId, row.uuid);
+                    }
+                    catch (error) {
+                        if (!isNotFoundError(error))
+                            throw error;
+                    }
+                }
+            }
+            await this.ports.coolify.restart(bouleId);
+            context.recordScopeId(REPORTING_BOULE_APPLIED_SCOPE_KEY, '');
+            return {};
+        }
+        if (!appsOn(org))
+            throw new Error(`${at}: the company's Boule runs no apps (org.boule.apps)`);
+        const backendId = recorded[`coolify:reporting:${org.id}`];
+        if (!backendId)
+            throw new Error(`${at}: the reporting backend is not recorded yet`);
+        const operatorKey = await this.reportingOperatorKey(org, context);
+        try {
+            await this.ports.coolify.bulkUpsertEnvs(bouleId, [
+                { key: 'REPORTING_URL', value: reportingUrlFor(org), literal: true },
+                { key: REPORTING_OPERATOR_KEY_ENV, value: operatorKey, literal: true },
+            ]);
+            await this.ports.coolify.restart(bouleId);
+        }
+        catch (error) {
+            throw new Error(redactSecrets(error instanceof Error ? error.message : String(error), [operatorKey]));
+        }
+        context.recordScopeId(REPORTING_BOULE_APPLIED_SCOPE_KEY, reportingBouleMarker(org, backendId));
+        return {};
+    }
+    /**
+     * `plan/entry-reporting-key.ts`: one server entry's site key (CLAUDE.md "Platform steps" rule 1). Mint: the
+     * key's id is recorded as undelivered and persisted before anything is written; the env write is tried 3
+     * times with the same secret; the applied address and the cleared marker come last; every try failing leaves
+     * the marker, and the error names the id only. `url` rewrites the address. Retire revokes the key and the
+     * env names. The operator key is read from the backend's env and never recorded.
+     */
+    async reportingEntryKey(action, org, context) {
+        const entryKey = action.key.slice(org.id.length + 1);
+        const at = `reporting:key for ${org.slug} entry '${entryKey}'`;
+        const reporting = this.ports.reporting;
+        if (!reporting)
+            throw new Error(`${at}: this executor was built without an reporting port`);
+        const desired = action.desired;
+        const recorded = context.recordedIds();
+        const appId = recorded[`coolify:app:${action.key}`];
+        const baseUrl = reportingUrlFor(org);
+        const tolerate = async (call, gone) => {
+            try {
+                return await call();
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+                return gone;
+            }
+        };
+        if (desired.mode === 'retire') {
+            const mainId = recorded[`reporting:key:${action.key}`];
+            const undelivered = recorded[entryReportingUndeliveredScopeKey(entryKey)];
+            const ids = [...new Set([mainId, undelivered].filter((id) => Boolean(id)))];
+            if (ids.length > 0) {
+                const operatorKey = await this.reportingOperatorKey(org, context);
+                for (const keyId of ids) {
+                    await tolerate(() => reporting.revokeSiteKey({ baseUrl, operatorKey, keyId }), undefined);
+                }
+            }
+            if (appId) {
+                const rows = await tolerate(() => this.ports.coolify.listEnvs(appId), []);
+                let removed = false;
+                for (const name of ['REPORTING_URL', 'REPORTING_SITE_KEY']) {
+                    const row = rows.find((e) => e.key === name && !e.is_preview);
+                    if (row?.uuid) {
+                        const uuid = row.uuid;
+                        await tolerate(() => this.ports.coolify.deleteEnv(appId, uuid), undefined);
+                        removed = true;
+                    }
+                }
+                if (removed)
+                    await tolerate(() => this.ports.coolify.restart(appId), undefined);
+            }
+            context.recordScopeId(entryReportingUndeliveredScopeKey(entryKey), '');
+            context.recordScopeId(entryReportingAppliedScopeKey(entryKey), '');
+            if (mainId ?? undelivered) {
+                context.recordScopeId(entryReportingRetiredScopeKey(entryKey), (mainId ?? undelivered));
+            }
+            return {};
+        }
+        if (!org.hosting.entries.some((e) => e.key === entryKey && e.uses?.reporting)) {
+            throw new Error(`${at}: the entry no longer declares uses.reporting`);
+        }
+        if (!appId)
+            throw new Error(`${at}: the entry's app is not recorded yet`);
+        if (desired.mode === 'url') {
+            await this.ports.coolify.bulkUpsertEnvs(appId, [
+                { key: 'REPORTING_URL', value: baseUrl, literal: true },
+            ]);
+            await this.ports.coolify.restart(appId);
+            context.recordScopeId(entryReportingAppliedScopeKey(entryKey), baseUrl);
+            return {};
+        }
+        if (recorded[entryReportingUndeliveredScopeKey(entryKey)]) {
+            throw new Error(`${at}: a key was minted and never delivered; it is not minted again`);
+        }
+        const operatorKey = await this.reportingOperatorKey(org, context);
+        let minted;
+        try {
+            minted = await reporting.mintSiteKey({
+                baseUrl,
+                operatorKey,
+                name: desired.name,
+                site: entryKey,
+                environment: 'production',
+            });
+        }
+        catch (error) {
+            const status = error?.status;
+            throw new Error(`${at}: the backend did not mint a key${typeof status === 'number' ? ` (status ${status})` : ''}`);
+        }
+        this.handledSecrets.add(minted.secret);
+        context.recordScopeId(entryReportingUndeliveredScopeKey(entryKey), minted.id);
+        await context.persistScopeIds();
+        const rows = [
+            { key: 'REPORTING_URL', value: baseUrl, literal: true },
+            { key: 'REPORTING_SITE_KEY', value: minted.secret, literal: true },
+        ];
+        let lastError;
+        for (let attempt = 1; attempt <= ENTRY_REPORTING_KEY_DELIVERY_ATTEMPTS; attempt++) {
+            try {
+                await this.ports.coolify.bulkUpsertEnvs(appId, rows);
+                await this.ports.coolify.restart(appId);
+                context.recordScopeId(entryReportingAppliedScopeKey(entryKey), baseUrl);
+                context.recordScopeId(entryReportingUndeliveredScopeKey(entryKey), '');
+                return { resourceId: minted.id };
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw new Error(`${at}: key ${minted.id} was minted but could not be written to the app's env after ${ENTRY_REPORTING_KEY_DELIVERY_ATTEMPTS} attempts (${lastError instanceof Error ? lastError.name : 'error'})`);
+    }
     // ---- kosmos (foundry#949) --------------------------------------------------
     /**
      * `plan/diff.ts`'s `planKosmos`: provisions the org's own kosmos
@@ -8849,8 +9328,11 @@ export class FoundryStepExecutor {
      * Boule's env. Returns whether Boule's token changed, so the caller
      * restarts a running Boule, unless `restarted`: the shared rule then already
      * restarted it (`running`), before it deleted the old project.
+     *
+     * The company's reporting backend (foundry#1128) takes its token the same
+     * way, as `role: 'reporting'`. The token is registered for redaction.
      */
-    async ensureBouleMail(appId, org, context, action, running) {
+    async ensureBouleMail(appId, org, context, action, running, role = 'boule') {
         const none = { changed: false, restarted: false };
         const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
         if (!mailDomain)
@@ -8860,8 +9342,9 @@ export class FoundryStepExecutor {
         if (platformApex && mailDomain.toLowerCase() === platformApex.toLowerCase()) {
             const heldToken = (await this.ports.heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF)) ?? null;
             if (!heldToken) {
-                throw new Error(`coolify:boule for ${org.slug}: the platform's own Lettermint token is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`);
+                throw new Error(`coolify:${role} for ${org.slug}: the platform's own Lettermint token is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`);
             }
+            this.handledSecrets.add(heldToken);
             const current = (await this.ports.coolify.listEnvs(appId)).find((e) => e.key === 'LETTERMINT_API_TOKEN' && !e.is_preview)?.value;
             if (current === heldToken)
                 return none;
@@ -8874,7 +9357,7 @@ export class FoundryStepExecutor {
             org,
             context,
             mailDomain,
-            self: { role: 'boule', id: appId, restart: running },
+            self: { role, id: appId, restart: running },
             mailFrom: null,
             platformApex,
             platformLettermintProjectId,
@@ -9586,6 +10069,55 @@ export class FoundryStepExecutor {
         context.recordScopeId(entryJobsAppliedScopeKey(entryKey), entryJobsWantMarker(want));
         return { resourceId: want.name };
     }
+    /**
+     * foundry#1119, `plan/entry-jobs-boule-key.ts`: Boule's key for one entry's jobs project, minted under rule 1,
+     * held, and written to Boule's `JOBS_PROJECTS`; or, in the retire form, revoked and taken out. See
+     * `entry-jobs-boule-key-apply.ts`.
+     */
+    async jobsBouleKey(action, org, context) {
+        const entryKey = action.key.slice(org.id.length + 1);
+        const at = `jobs:boule-key for ${org.slug} entry '${entryKey}'`;
+        const desired = action.desired;
+        const port = await this.jobsPort(org);
+        const mint = port.mintProjectKey?.bind(port);
+        const revoke = port.revokeProjectKey?.bind(port);
+        if (!mint || !revoke) {
+            throw new Error(`${at}: the jobs scheduler port cannot mint or revoke project keys`);
+        }
+        const held = this.ports.heldKeys;
+        const put = held?.put?.bind(held);
+        if (!held || !put)
+            throw new Error(`${at}: the held keys cannot hold Boule's key`);
+        const deps = {
+            scheduler: { mintProjectKey: mint, revokeProjectKey: revoke },
+            heldKeys: { resolve: held.resolve.bind(held), put },
+            coolify: this.ports.coolify,
+            org: { id: org.id, slug: org.slug },
+            entryKey,
+            project: desired.name,
+            bouleAppId: context.recordedIds()[`coolify:boule:${org.id}`],
+            recorded: () => context.recordedIds(),
+            record: (key, value) => context.recordScopeId(key, value),
+            forget: (key) => forgetScopeId(context, key),
+            persist: () => context.persistScopeIds(),
+            secret: (value) => void this.handledSecrets.add(value),
+        };
+        if (desired.mode === 'retire') {
+            if (org.hosting.enabled &&
+                org.hosting.entries.some((e) => e.key === entryKey && e.uses?.jobs && e.live !== false)) {
+                throw new Error(`${at}: the entry declares uses.jobs again; nothing was revoked`);
+            }
+            await retireJobsBouleKey(deps);
+            return {};
+        }
+        if (!org.hosting.entries.some((e) => e.key === entryKey && e.uses?.jobs)) {
+            throw new Error(`${at}: the entry no longer declares uses.jobs`);
+        }
+        if (!desired.url)
+            throw new Error(`${at}: the scheduler's public address is not in the step`);
+        await ensureJobsBouleKey(deps, desired.url);
+        return {};
+    }
     /** `plan/entry-audit.ts`: makes the platform signer if none exists and registers one entry's ledger for sealing. */
     async auditLedger(action, org, context) {
         const entryKey = action.key.slice(org.id.length + 1);
@@ -10747,13 +11279,16 @@ export class FoundryStepExecutor {
      * on their own (`AiOrganisationPort`'s doc comment), so both are called
      * every time regardless of whether they already ran.
      */
-    async aiOrganisation(action, org) {
+    async aiOrganisation(action, org, context) {
         const ai = await this.aiPort();
         const provisioned = await ai.provisionOrganisation({
             organisationId: org.id,
             limitMicros: action.desired.limitMicros ?? null,
         });
-        await ai.setOrganisationOffers(org.id, action.desired.offers ?? []);
+        const offers = action.desired.offers ?? [];
+        await ai.setOrganisationOffers(org.id, offers);
+        // foundry#1122: what is offered now, so a narrower set is offered again (`planAiOrganisation`).
+        context.recordScopeId(AI_OFFERS_SCOPE_KEY, JSON.stringify(offers));
         return { resourceId: provisioned.organisationId };
     }
     async aiBudget(action, org, context) {
@@ -10801,6 +11336,16 @@ export class FoundryStepExecutor {
         for (let attempt = 1; attempt <= AI_KEY_DELIVERY_ATTEMPTS; attempt++) {
             try {
                 await this.ports.deliverSecret(`ai:key:${org.slug}`, issued.secret);
+                // foundry#1122: what the key holds, so a narrower one is minted again (`planAiKey`). A key it
+                // replaced stays live until it expires (no revoke route yet, ai#157); the plan lists it.
+                context.recordScopeId(AI_KEY_PERMISSIONS_SCOPE_KEY, JSON.stringify(action.desired.permissions ?? []));
+                const replaced = context.recordedIds()[`ai:key:${org.id}`];
+                if (replaced && replaced !== issued.id) {
+                    const previous = parseAiIds(context.recordedIds()[AI_KEY_PREVIOUS_SCOPE_KEY]);
+                    if (!previous.includes(replaced))
+                        previous.push(replaced);
+                    context.recordScopeId(AI_KEY_PREVIOUS_SCOPE_KEY, JSON.stringify(previous));
+                }
                 return { resourceId: issued.id };
             }
             catch (e) {
@@ -10916,6 +11461,9 @@ export class FoundryStepExecutor {
                     name: d.name,
                     expiresDays: d.expiresDays,
                     permissions: d.permissions,
+                    // foundry#1122: the key's runs belong to this app's live copy (ai#190). A key minted before this
+                    // joins its app at its next renewal.
+                    app: { key: entryKey, copy: 'live' },
                 });
                 context.recordScopeId(entryAiUndeliveredScopeKey(entryKey), minted.id);
                 context.recordScopeId(entryAiPendingExpiresScopeKey(entryKey), minted.expiresAt);
@@ -10955,6 +11503,35 @@ export class FoundryStepExecutor {
         }
         return { resourceId };
     }
+    /**
+     * foundry#1122, `plan/ai-boule-key.ts`: Boule's ai key, minted below the org's own ai key under rule 1, held,
+     * and written to Boule's `AI_URL`, `AI_ORGANISATION_ID` and `AI_API_KEY`. See `ai-boule-key-apply.ts`.
+     */
+    async aiBouleKey(action, org, context) {
+        const at = `ai:boule-key for ${org.slug}`;
+        const ai = await this.aiPort();
+        const held = this.ports.heldKeys;
+        const put = held?.put?.bind(held);
+        if (!held || !put)
+            throw new Error(`${at}: the held keys cannot hold Boule's key`);
+        await ensureAiBouleKey({
+            ai: {
+                mintNestedKey: ai.mintNestedKey.bind(ai),
+                ...(ai.revokeKey ? { revokeKey: ai.revokeKey.bind(ai) } : {}),
+            },
+            heldKeys: { resolve: held.resolve.bind(held), put },
+            coolify: this.ports.coolify,
+            org: { id: org.id, slug: org.slug },
+            bouleAppId: context.recordedIds()[`coolify:boule:${org.id}`],
+            recorded: () => context.recordedIds(),
+            record: (key, value) => context.recordScopeId(key, value),
+            forget: (key) => forgetScopeId(context, key),
+            persist: () => context.persistScopeIds(),
+            secret: (value) => void this.handledSecrets.add(value),
+            now: () => context.now?.() ?? Date.now(),
+        }, action.desired);
+        return {};
+    }
     /**
      * REVOKE SEAM (ai#157): revokes through `revokeKey` when the port has one.
      * Without it, or when it fails, the id joins the entry's list of keys left
@@ -11332,7 +11909,8 @@ export class FoundryStepExecutor {
                 .every((e) => recorded[`files:key:${org.id}:${e.key}`] &&
                 recorded[entryFilesMinterScopeKey(e.key)] === rootId &&
                 !recorded[entryFilesUndeliveredScopeKey(e.key)]);
-            if (!ready)
+            // foundry#1121: Boule's files key too, or Boule's Files page would lose its key.
+            if (!ready || !bouleKeyBelow(recorded, rootId))
                 return {};
             const unrevoked = parseFilesIdList(recorded[FILES_ROOT_UNREVOKED_SCOPE_KEY]);
             for (const id of previous) {
@@ -11374,6 +11952,8 @@ export class FoundryStepExecutor {
                 // The expiry and the replaced id follow the delivery: before it, the
                 // recorded key is still the one in use.
                 context.recordScopeId(FILES_ROOT_EXPIRES_SCOPE_KEY, issued.expiresAt);
+                // foundry#1121: what the key holds, so a narrower one is renewed (`planFilesKeys`).
+                context.recordScopeId(FILES_ROOT_PERMISSIONS_SCOPE_KEY, JSON.stringify(action.desired.permissions));
                 const replaced = recorded[`files:key:${org.id}`];
                 if (mode === 'renew' && replaced) {
                     const previous = parseFilesIdList(recorded[FILES_ROOT_PREVIOUS_SCOPE_KEY]);
@@ -11458,7 +12038,11 @@ export class FoundryStepExecutor {
                 { key: 'FILES_ORGANISATION_ID', value: org.id },
                 ...(d.shareOrigin ? [{ key: 'FILES_SHARE_ORIGIN', value: d.shareOrigin }] : []),
             ];
-            for (const name of d.collections) {
+            // foundry#1121: each app's collections are named apart in files; one the entry already had keeps its
+            // name. The app's env names the label and holds the id, as before.
+            const names = knownCollectionNames(entryKey, recorded);
+            for (const label of d.collections) {
+                const name = d.collectionNames?.[label] ?? names[label] ?? label;
                 let collection;
                 try {
                     collection = await files.ensureCollection(org.id, name);
@@ -11466,7 +12050,12 @@ export class FoundryStepExecutor {
                 catch (error) {
                     throw new Error(`${at}: collection ${name} could not be ensured (${filesErrorCause(error)})`);
                 }
-                envs.push({ key: filesCollectionEnvName(name), value: collection.id });
+                names[label] = name;
+                envs.push({ key: filesCollectionEnvName(label), value: collection.id });
+            }
+            if (d.collections.length > 0 || recorded[entryFilesAppliedScopeKey(entryKey)]) {
+                context.recordScopeId(entryFilesCollectionsScopeKey(entryKey), JSON.stringify(names));
+                await context.persistScopeIds();
             }
             if (d.mode !== 'settings') {
                 const minterId = recorded[`files:key:${org.id}`];
@@ -11524,12 +12113,59 @@ export class FoundryStepExecutor {
             collections: d.collections,
             filesUrl: d.filesUrl,
             ...(d.shareOrigin ? { shareOrigin: d.shareOrigin } : {}),
+            collectionNames: d.collectionNames ?? {},
         }));
         if (expiresAt && previousKeyId && previousKeyId !== resourceId) {
             await this.revokeFilesEntryKey(files, org, entryKey, previousKeyId, context);
         }
         return { resourceId };
     }
+    /**
+     * foundry#1121, `plan/files-boule-key.ts`: Boule's files key, minted below the org's own files key under rule
+     * 1, held, and written to Boule's `FILES_BOULE_KEYS`; or, in the retire form, revoked and taken out. See
+     * `files-boule-key-apply.ts`.
+     */
+    async filesBouleKey(action, org, context) {
+        const at = `files:boule-key for ${org.slug}`;
+        const files = await this.filesPort();
+        const held = this.ports.heldKeys;
+        const put = held?.put?.bind(held);
+        const desired = action.desired;
+        const deps = {
+            files: {
+                issueKeyBelow: files.issueKeyBelow.bind(files),
+                revokeOrganisationKey: files.revokeOrganisationKey.bind(files),
+            },
+            heldKeys: {
+                resolve: async (ref) => (held ? held.resolve(ref) : null),
+                put: async (ref, value) => {
+                    if (!put)
+                        throw new Error('the held keys cannot put');
+                    await put(ref, value);
+                },
+            },
+            coolify: this.ports.coolify,
+            org: { id: org.id, slug: org.slug },
+            bouleAppId: context.recordedIds()[`coolify:boule:${org.id}`],
+            recorded: () => context.recordedIds(),
+            record: (key, value) => context.recordScopeId(key, value),
+            forget: (key) => forgetScopeId(context, key),
+            persist: () => context.persistScopeIds(),
+            secret: (value) => void this.handledSecrets.add(value),
+            now: () => context.now?.() ?? Date.now(),
+        };
+        if (desired.mode === 'retire') {
+            if (org.hosting.enabled && org.hosting.entries.some((e) => e.uses?.files)) {
+                throw new Error(`${at}: an entry declares uses.files again; nothing was revoked`);
+            }
+            await retireFilesBouleKey(deps);
+            return {};
+        }
+        if (!held || !put)
+            throw new Error(`${at}: the held keys cannot hold Boule's key`);
+        await ensureFilesBouleKey(deps, action.desired);
+        return {};
+    }
     /**
      * Revokes one entry key. When the call fails the id joins the entry's list
      * of keys left live, which the plan shows, and the step goes on: the app
@@ -12096,6 +12732,16 @@ export async function setOidcAppLoginBaseUri(zitadel, orgId, projectId, appId, l
     }
 }
 /** A recorded stage service key (`bg.<id>.stage<service>keys` or `...org`) with its last part swapped. */
+/**
+ * The stage mail sink of `org`, with the `MAIL_APP_KEY` its stage copy of entry `entryKey` sends as (`<key>-work`)
+ * when that entry sends mail. Boule, Agora and kosmos are not entries: their stage gets the sink alone.
+ */
+function stageSinkFor(org, entryKey) {
+    const entry = entryKey ? org.hosting.entries.find((e) => e.key === entryKey) : undefined;
+    return entry && sendsMail(entry)
+        ? { slug: org.slug, mailAppKey: mailAppKeyOf(entry.key, 'work') }
+        : { slug: org.slug };
+}
 function stageServiceKey(key, part) {
     const match = /^(bg\..+\.stage(?:files|ai|jobs))(?:keys|org)$/.exec(key);
     if (!match?.[1])