@wtfalch/foundry 0.46.0 → 0.48.0

package/dist/plan/blue-green.js

@@ -1,9 +1,13 @@
 import { createHash } from 'node:crypto';
 import { VERSIONS, pinnedRef } from '../bootstrap/versions.js';
+import { agoraHostnameFor } from './agora.js';
+import { bouleHostnameFor } from './boule.js';
 import { serverConnectorScopeKey } from './cloudflared-connector.js';
 import { entryHostnames, tunnelIngressHostnames, wildcardHostname } from './hostnames.js';
 import { appNameFor, appStepKey } from './platform-diff.js';
 import { remoteDatabaseAppliedFor } from './remote-database.js';
+import { buildStageEnv } from './stage-env.js';
+import { assertStageIsolated, envClass } from './stage-isolation.js';
 export const COLORS = ['blue', 'green'];
 /** The name of `base`'s copy in `color`: `<base>-blue`. */
 export function colorAppName(base, color) {
@@ -43,11 +47,21 @@ export const bgKey = {
     app: (id, server, part) => `bg.${id}.app.${server}.${part}`,
     /** The cloudflared connector app of the tunnel on a non-primary `server`. */
     connector: (id, server) => `bg.${id}.connector.${server}`,
+    /** The held ref of the server actions key, recorded and persisted as soon as it is minted (no `:`: undelivered). */
+    actionsKey: (id) => `bg.${id}.actionskey`,
     stageDatabase: (id) => `bg.${id}.stagedb`,
+    /** `ok`, `unhealthy` (build or health check failed) or `blocked:<reason names>` (a guard refused; stage was not written to). */
+    stageState: (id) => `bg.${id}.stagestate`,
     /** The Coolify name of the blue app on the primary: the adopted single app's name, or `<base>-blue`. */
     blueName: (id) => `bg.${id}.bluename`,
     /** The pin key of the balancer's header routers. Not a credential: it only pins a color. */
     pinKey: (id) => `bg.${id}.pinkey`,
+    /** The hash of the stage env name set and resource set that passed the isolation check. */
+    stageIsolation: (id) => `bg.${id}.stageisolation`,
+    /** The id of the Access gate over the stage host: staff only, no bypass, no service-token rule. */
+    stageGate: (id) => `bg.${id}.stagegate`,
+    /** `ok:<hash>` once every apply-time probe was rejected; `notrun:<names>` or `failed:<names>` otherwise. */
+    stageProbes: (id) => `bg.${id}.stageprobes`,
 };
 /** The three env names the reporting health read uses (contract C1). */
 export const REPORTING_ENV = {
@@ -55,6 +69,32 @@ export const REPORTING_ENV = {
     release: 'REPORTING_RELEASE',
     healthToken: 'REPORTING_HEALTH_TOKEN',
 };
+/** Next.js server action ids differ between builds unless every color is built with the same key. */
+export const ACTIONS_KEY_ENV = 'NEXT_SERVER_ACTIONS_ENCRYPTION_KEY';
+/** The held-key name of a subject's server actions key: one mint per subject, shared by blue and green only. */
+export const actionsKeyName = (id) => `server-actions-key-${id}`;
+/**
+ * One mint of the server actions key (CLAUDE.md, Platform steps, rule 1). The key goes to the held store, then its
+ * ref is recorded under {@link bgKey.actionsKey} and persisted, and only then is it returned for any env. A later
+ * apply reuses the held key; when the ref is recorded but the key is no longer held it stops, never mints again.
+ * The error names the ref only.
+ */
+export async function mintActionsKey(input) {
+    const held = await input.heldKeys.resolve(input.ref);
+    if (held) {
+        input.secret(held);
+        return held;
+    }
+    if (input.recorded()[bgKey.actionsKey(input.id)]) {
+        throw new Error(`server actions key ${input.ref} was minted but is no longer held; restore the held value`);
+    }
+    const key = input.generate();
+    input.secret(key);
+    await input.heldKeys.put(input.ref, key);
+    input.record(bgKey.actionsKey(input.id), input.ref);
+    await input.persist();
+    return key;
+}
 /** The held-key name of an entry's health token (`sharedSecretRef(org.id, name)`): one mint per entry. */
 export const healthTokenName = (id) => `reporting-health-${id}`;
 /** What a color's container gets for the reporting health read. The release is left out until a digest is known. */
@@ -65,6 +105,27 @@ export function reportingEnv(input) {
         { key: REPORTING_ENV.healthToken, value: input.healthToken },
     ];
 }
+export const BUILTIN_APPS = ['boule', 'agora'];
+/** What foundry builds each built-in app from; `executor.ts` creates the app from the same values. */
+export const BUILTIN_APP = {
+    boule: {
+        repo: 'wtfalch/boule',
+        dockerfile: '/Dockerfile',
+        port: 3000,
+        healthPath: '/api/health',
+        database: true,
+        reporting: true,
+    },
+    agora: {
+        repo: 'wtfalch/agora',
+        dockerfile: '/apps/agora/Dockerfile',
+        // Equal to `AGORA_APP_PORTS_EXPOSES` (a test holds them together); importing it here would be a cycle.
+        port: 8080,
+        healthPath: '/',
+        database: false,
+        reporting: false,
+    },
+};
 /**
  * A hosting entry that declares `blueGreen`, as a subject; `null` when it does not or cannot run.
  * `recorded` names the blue app: an app that ran before blue/green keeps its own name (see {@link liveAppNameFor}).
@@ -87,8 +148,57 @@ export function entrySubject(org, entry, recorded) {
         database: entry.database,
         hostnames: entryHostnames(org, entry),
         config: entry.blueGreen,
+        blueAppKey: `coolify:app:${appStepKey(org, entry.key)}`,
+        reporting: true,
     };
 }
+/**
+ * The company's Boule or Agora as a subject; `null` when it does not declare blue/green. The running app keeps
+ * its name `<slug>-<app>` and is blue, like platform-archon. Both run on the primary server only.
+ */
+export function builtinSubject(org, app, recorded = {}) {
+    const config = org[app]?.blueGreen;
+    if (!config)
+        return null;
+    const spec = BUILTIN_APP[app];
+    const base = `${org.slug}-${app}`;
+    return {
+        id: app,
+        base,
+        primaryBlueName: recorded[bgKey.blueName(app)] ?? base,
+        port: spec.port,
+        repo: spec.repo,
+        folder: null,
+        branch: 'main',
+        buildPack: 'dockerfile',
+        healthPath: spec.healthPath,
+        database: spec.database,
+        hostnames: [app === 'boule' ? bouleHostnameFor(org) : agoraHostnameFor(org)],
+        config,
+        blueAppKey: `coolify:${app}:${org.id}`,
+        dockerfileLocation: spec.dockerfile,
+        reporting: spec.reporting,
+        builtin: app,
+    };
+}
+/** Every blue/green subject of an org: the hosting entries that declare it, then Boule and Agora. */
+export function blueGreenSubjects(org, recorded) {
+    const subjects = [];
+    for (const entry of org.hosting.entries) {
+        const subject = entrySubject(org, entry, recorded);
+        if (subject)
+            subjects.push(subject);
+    }
+    for (const app of BUILTIN_APPS) {
+        const subject = builtinSubject(org, app, recorded);
+        if (subject)
+            subjects.push(subject);
+    }
+    return subjects;
+}
+/** Whether the org declares blue/green for any of its apps. */
+export const declaresBlueGreen = (org) => org.hosting.entries.some((entry) => entry.blueGreen) ||
+    BUILTIN_APPS.some((app) => org[app]?.blueGreen);
 /**
  * The Coolify name of the entry's app on the primary. A blue/green entry's app is its blue copy: the recorded
  * name; else the entry's own name when its app is already recorded (it ran before blue/green and is adopted as
@@ -218,6 +328,59 @@ export function structureHash(subject, input) {
         .digest('hex')
         .slice(0, 16);
 }
+/** The kind of stage app a subject has: platform-archon, else a customer app. */
+export const stageKindOf = (subject) => subject.id === ARCHON_SUBJECT_ID ? 'archon' : 'customer';
+/** The names stage can collide on. */
+export function stageResources(subject) {
+    const database = `${subject.base}-stage-db`;
+    return {
+        app: stageAppName(subject.base),
+        ...(subject.database ? { database, databaseName: database.replace(/-/g, '_') } : {}),
+    };
+}
+/** The names of the subject's live parts: stage must equal none of them. */
+export function prodResources(subject) {
+    return {
+        blue: subject.primaryBlueName,
+        green: colorAppName(subject.base, 'green'),
+        lb: lbAppName(subject.base),
+        base: subject.base,
+    };
+}
+/** The address of a stage app inside its network: it has no hostname. */
+export const stageAppUrl = (subject) => `http://${stageAppName(subject.base)}:${subject.port}`;
+/**
+ * The violations of stage isolation that need no live values: the stage env names the builder gives, and the
+ * names stage and the org's other apps hold. Names only.
+ */
+export function stagePlanViolations(subject, otherApps) {
+    const { env } = buildStageEnv({
+        kind: stageKindOf(subject),
+        appUrl: stageAppUrl(subject),
+        logDir: '',
+        database: subject.database
+            ? [
+                { key: 'DATABASE_URL_OWNER', value: '' },
+                { key: 'DATABASE_URL', value: '' },
+            ]
+            : [],
+        prod: [],
+        existing: [],
+        mint: () => '',
+    });
+    const stage = {
+        env: env.map((e) => ({ name: e.key, class: envClass(e.key) })),
+        resources: stageResources(subject),
+    };
+    const prod = {
+        env: [],
+        resources: {
+            ...prodResources(subject),
+            ...Object.fromEntries(otherApps.map((name, i) => [`other${i}`, name])),
+        },
+    };
+    return assertStageIsolated({ kind: stageKindOf(subject), prod, stage });
+}
 /** Hostnames of the tunnel that no blue/green entry serves; a connector on a second server cannot answer them. */
 export function namesNotBlueGreen(org) {
     const served = new Set();
@@ -232,6 +395,11 @@ export function namesNotBlueGreen(org) {
                 served.add(wildcard);
         }
     }
+    for (const subject of blueGreenSubjects(org)) {
+        if (subject.builtin)
+            for (const name of subject.hostnames)
+                served.add(name);
+    }
     return tunnelIngressHostnames(org).filter((name) => !served.has(name));
 }
 const MAX_NAME = 63;
@@ -246,21 +414,25 @@ export function planBlueGreen(input) {
     const { org, recordedIds } = input;
     const steps = [];
     const unmanaged = [];
-    for (const entry of org.hosting.entries) {
-        const subject = entrySubject(org, entry, recordedIds);
-        if (!subject)
-            continue;
+    for (const subject of blueGreenSubjects(org, recordedIds)) {
+        const entry = org.hosting.entries.find((e) => e.key === subject.id);
+        const builtin = subject.builtin !== undefined;
         const id = subject.id;
         const blocked = (why, part = 'blocked') => unmanaged.push({
             description: `${org.slug}'s ${id} app blue/green is blocked, not planned: ${why}`,
             key: `bg:${id}:${part}`,
         });
-        if (entry.buildPack === 'dockercompose')
+        if (entry?.buildPack === 'dockercompose')
             continue;
         if (colorAppName(subject.base, 'green').length > MAX_NAME) {
             blocked('its app name is too long for the green copy; shorten the slug or the entry key');
             continue;
         }
+        const stageViolations = stagePlanViolations(subject, org.hosting.entries.filter((e) => e.key !== subject.id).map((e) => appNameFor(org, e)));
+        if (stageViolations.length > 0) {
+            blocked(`its stage would not be isolated from production (${stageViolations.join(', ')})`, 'stageisolation');
+            continue;
+        }
         if (!input.servers) {
             blocked('the host cannot list Coolify servers');
             continue;
@@ -274,8 +446,14 @@ export function planBlueGreen(input) {
             blocked(`the recorded weights are not 'blue:<n>,green:<n>' summing to 100`, 'weights');
             continue;
         }
-        if (!recordedIds[`coolify:app:${appStepKey(org, id)}`] && !input.appPlanned(id)) {
-            blocked('its blue copy is not recorded and no app step is planned to make it');
+        if (builtin && !org.domain) {
+            blocked('its address is on the shared tunnel, which cannot route to a balancer; give the company a domain');
+            continue;
+        }
+        if (!recordedIds[subject.blueAppKey] && (builtin || !input.appPlanned(id))) {
+            blocked(builtin
+                ? 'its app is not recorded yet; apply the company once first'
+                : 'its blue copy is not recorded and no app step is planned to make it');
             continue;
         }
         const { up, down } = splitServers(input.servers);
@@ -285,13 +463,13 @@ export function planBlueGreen(input) {
             blocked(`the primary Coolify server ${primary ?? '(none)'} is not usable and reachable`);
             continue;
         }
-        for (const uuid of down) {
+        for (const uuid of builtin ? [] : down) {
             unmanaged.push({
                 description: `${org.slug}'s ${id} app has no blue/green copies on Coolify server ${uuid}: the server is not usable or not reachable right now`,
                 key: `bg:${id}:down:${uuid}`,
             });
         }
-        const others = up.filter((uuid) => uuid !== primary);
+        const others = builtin ? [] : up.filter((uuid) => uuid !== primary);
         const unrouted = namesNotBlueGreen(org);
         const useOthers = others.length > 0 && unrouted.length === 0;
         if (others.length > 0 && !useOthers) {
@@ -313,6 +491,19 @@ export function planBlueGreen(input) {
                 }
             }
         }
+        const stageState = recordedIds[bgKey.stageState(id)];
+        if (stageState === 'unhealthy') {
+            unmanaged.push({
+                description: `${org.slug}'s ${id} app: stage is not healthy yet`,
+                key: `bg:${id}:stage`,
+            });
+        }
+        else if (stageState?.startsWith('blocked:')) {
+            unmanaged.push({
+                description: `${org.slug}'s ${id} app: stage is blocked and was not written to (${stageState.slice('blocked:'.length)})`,
+                key: `bg:${id}:stage`,
+            });
+        }
         for (const server of targets) {
             const isPrimary = server === primary;
             const key = `${org.id}:${id}:${server}`;
@@ -324,19 +515,27 @@ export function planBlueGreen(input) {
                 });
                 continue;
             }
-            if (recordedIds[bgKey.applied(id, server)] !== hash) {
+            // A stage that was not healthy is retried by running the structure again.
+            const stageRetry = isPrimary && (stageState === 'unhealthy' || stageState?.startsWith('blocked:') === true);
+            if (recordedIds[bgKey.applied(id, server)] !== hash || stageRetry) {
                 steps.push({
                     kind: 'bluegreen',
-                    phase: 'before',
+                    phase: builtin ? 'last' : 'before',
                     key,
                     description: `run ${org.slug}'s ${id} app as blue and green behind a load balancer on Coolify server ${server}${isPrimary ? ', with a stage copy' : ''}`,
-                    desired: { entry: id, server, primary, weights: formatWeights(weights) },
+                    desired: {
+                        entry: id,
+                        server,
+                        primary,
+                        weights: formatWeights(weights),
+                        ...(input.accessProviderId ? { accessProviderId: input.accessProviderId } : {}),
+                    },
                 });
             }
             else if (recordedIds[bgKey.lb(id, server)] !== formatWeights(weights)) {
                 steps.push({
                     kind: 'bluegreen-lb',
-                    phase: 'before',
+                    phase: builtin ? 'last' : 'before',
                     key,
                     description: `set ${org.slug}'s ${id} app traffic to ${formatWeights(weights)} on Coolify server ${server}`,
                     desired: { entry: id, server, primary, weights: formatWeights(weights) },
@@ -374,6 +573,8 @@ export function archonSubject(platform, repo) {
         database: true,
         hostnames: [archon.hostname],
         config: archon.blueGreen,
+        blueAppKey: ARCHON_APP_RECORD,
+        reporting: true,
     };
 }
 /**

package/dist/plan/database-dump.d.ts

@@ -0,0 +1,37 @@
+import type { CoolifyPort } from './executor.js';
+/** The dump {@link dumpNow} started, and where it is saved. */
+export interface DatabaseDump {
+    /** Coolify's uuid of the execution this call started. */
+    executionId: string;
+    location: {
+        /** The S3 storage (`platform-backups`) the dump was saved to. */
+        storageUuid: string;
+        /** The dump's file as Coolify records it: its path in that storage's bucket. */
+        filename: string;
+    };
+}
+/** An error of {@link dumpNow}: fixed text and the database's key, never a Coolify message, uuid or body. */
+export declare class DumpError extends Error {
+    constructor(message: string);
+}
+/**
+ * Takes a fresh dump of one database now and returns where it is saved. Coolify has no
+ * run-now route: `PATCH /databases/{uuid}/backups/{backup}` with `backup_now: true` queues the
+ * schedule's job, so the dump goes through the database's existing schedule. The execution it
+ * started is the first one not listed before the call; an older one is never returned. Every
+ * failure is an error naming `databaseKey`, never a uuid, a Coolify message or a body. Nothing is
+ * retried. The dump is subject to the schedule's own retention.
+ */
+export declare function dumpNow(coolify: Pick<CoolifyPort, 'listDatabaseBackups' | 'raw'> & Partial<Pick<CoolifyPort, 'listDatabaseBackupExecutions'>>, input: {
+    /** The database's name in `companyDatabaseKeys`, e.g. `app.shop`. Goes into every error. */
+    databaseKey: string;
+    databaseUuid: string;
+    /** The uuid of the database's schedule. */
+    backupUuid: string;
+    /** The registered `platform-backups` storage the schedule saves to. */
+    storageUuid: string;
+    /** Milliseconds to wait for the dump to finish. Default: 10 minutes. */
+    timeoutMs?: number;
+    /** Milliseconds between two reads of the executions. Default: 3 seconds. */
+    intervalMs?: number;
+}): Promise<DatabaseDump>;

package/dist/plan/database-dump.js

@@ -0,0 +1,101 @@
+const DUMP_NOW_TIMEOUT_MS = 600_000;
+const DUMP_NOW_INTERVAL_MS = 3_000;
+const DUMP_CALL_TIMEOUT_MS = 30_000;
+/** An error of {@link dumpNow}: fixed text and the database's key, never a Coolify message, uuid or body. */
+export class DumpError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DumpError';
+    }
+}
+async function dumpCall(label, call) {
+    let timer;
+    try {
+        return await Promise.race([
+            call(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new DumpError(`dump of ${label}: Coolify did not answer within ${DUMP_CALL_TIMEOUT_MS / 1000} seconds`)), DUMP_CALL_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    catch (error) {
+        if (error instanceof DumpError)
+            throw error;
+        throw new DumpError(`dump of ${label}: a Coolify call failed`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function dumpExecutions(coolify, label, databaseUuid, backupUuid) {
+    const body = await dumpCall(label, () => coolify.listDatabaseBackupExecutions
+        ? coolify.listDatabaseBackupExecutions(databaseUuid, backupUuid)
+        : coolify.raw('GET', `/databases/${databaseUuid}/backups/${backupUuid}/executions`));
+    const rows = Array.isArray(body) ? body : body?.executions;
+    if (!Array.isArray(rows)) {
+        throw new DumpError(`dump of ${label}: Coolify's executions had an unexpected shape`);
+    }
+    return rows.map((row) => {
+        const r = row;
+        if (!r || typeof r.uuid !== 'string' || typeof r.status !== 'string') {
+            throw new DumpError(`dump of ${label}: Coolify's executions had an unexpected shape`);
+        }
+        return {
+            uuid: r.uuid,
+            status: r.status,
+            ...(typeof r.filename === 'string' ? { filename: r.filename } : {}),
+        };
+    });
+}
+/**
+ * Takes a fresh dump of one database now and returns where it is saved. Coolify has no
+ * run-now route: `PATCH /databases/{uuid}/backups/{backup}` with `backup_now: true` queues the
+ * schedule's job, so the dump goes through the database's existing schedule. The execution it
+ * started is the first one not listed before the call; an older one is never returned. Every
+ * failure is an error naming `databaseKey`, never a uuid, a Coolify message or a body. Nothing is
+ * retried. The dump is subject to the schedule's own retention.
+ */
+export async function dumpNow(coolify, input) {
+    const { databaseKey: label, databaseUuid, backupUuid, storageUuid } = input;
+    for (const [name, value] of Object.entries({
+        databaseKey: label,
+        databaseUuid,
+        backupUuid,
+        storageUuid,
+    })) {
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new DumpError(`dump: ${name} must be a non-empty string`);
+        }
+    }
+    const timeoutMs = input.timeoutMs ?? DUMP_NOW_TIMEOUT_MS;
+    const intervalMs = input.intervalMs ?? DUMP_NOW_INTERVAL_MS;
+    if (!(timeoutMs > 0) || !(intervalMs > 0)) {
+        throw new DumpError(`dump of ${label}: timeoutMs and intervalMs must be positive`);
+    }
+    const schedule = (await dumpCall(label, () => coolify.listDatabaseBackups(databaseUuid))).find((s) => s.uuid === backupUuid);
+    if (!schedule || schedule.enabled === false || !schedule.save_s3) {
+        throw new DumpError(`dump of ${label}: its schedule is missing, disabled or does not save to S3`);
+    }
+    if (schedule.s3_storage_uuid !== undefined && schedule.s3_storage_uuid !== storageUuid) {
+        throw new DumpError(`dump of ${label}: its schedule saves to another storage than the backup bucket`);
+    }
+    const before = new Set((await dumpExecutions(coolify, label, databaseUuid, backupUuid)).map((e) => e.uuid));
+    await dumpCall(label, () => coolify.raw('PATCH', `/databases/${databaseUuid}/backups/${backupUuid}`, { backup_now: true }));
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const started = (await dumpExecutions(coolify, label, databaseUuid, backupUuid)).find((e) => !before.has(e.uuid));
+        if (started?.status === 'success') {
+            if (!started.filename) {
+                throw new DumpError(`dump of ${label}: Coolify recorded no file for the finished dump`);
+            }
+            return { executionId: started.uuid, location: { storageUuid, filename: started.filename } };
+        }
+        if (started && started.status !== 'running') {
+            throw new DumpError(`dump of ${label} failed`);
+        }
+        if (Date.now() >= deadline) {
+            throw new DumpError(`dump of ${label}: no finished dump within ${Math.round(timeoutMs / 1000)} seconds`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}

package/dist/plan/diff.js

@@ -1,5 +1,5 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
-import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, heldEnvRef, ownerMailboxRecorded, ownerMailboxes, ownerNameProblem, ownsServices, } from '../org.js';
+import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, heldEnvRef, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownerNameProblem, ownsServices, } from '../org.js';
 import { entryHasDatabase } from '../worker-app-config.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
 import { planBlueGreen } from './blue-green.js';
@@ -490,6 +490,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         recordedIds,
         servers: options.blueGreenServers,
         canHoldSecrets: platformReadiness.canHoldSecrets === true,
+        accessProviderId: platformReadiness.accessProviderId ?? null,
         appPlanned: (entryKey) => plannedSteps.some((p) => p.action.system === 'coolify' &&
             p.action.kind === 'app' &&
             p.action.key === appStepKey(org, entryKey)),
@@ -566,6 +567,8 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null, platformReadiness, bouleCredentials.wants);
     if (boule.step)
         plannedSteps.push(boule.step);
+    // Boule's and Agora's blue/green: after their own steps, which make the app it copies.
+    plannedSteps.push(...blueGreen.steps.filter((x) => x.phase === 'last').map(blueGreenDraft()));
     // Boule owners, after the Boule step: needs the app deployed and the seeding secret in its env.
     const bouleOwners = planBouleOwners(org, recordedIds, (byKey.get(resourceKey('coolify', 'boule', org.id))?.config.env ?? null));
     if (bouleOwners.seed.length > 0) {
@@ -3161,7 +3164,7 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
     // right now, and gating this on `mailHost` let a platform-apex org with an
     // already-recorded domain take the unprotected path the moment platform
     // mail went back to off.
-    if (entryKey === APP_ENTRY_KEY) {
+    if (entryKey === mainEntry(org.hosting)?.key) {
         const mailDomain = recordedIds[MAIL_DOMAIN_SCOPE_KEY];
         const platformApex = readiness.platformApex;
         const platformLettermintProjectId = readiness.platformLettermintProjectId;
@@ -3473,6 +3476,7 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, re
         .map((id) => id.slice(`coolify:app:${org.id}:`.length));
     const declared = new Set([APP_ENTRY_KEY, ...org.hosting.entries.map((e) => e.key)]);
     const keys = new Set([...declared, ...recordedKeys]);
+    const mainKey = mainEntry(org.hosting)?.key;
     for (const key of keys) {
         if (!declared.has(key)) {
             // The reader gives a parked app no `enabled` field, so only a running
@@ -3508,14 +3512,14 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, re
                 app.step.action.desired = { ...app.step.action.desired, authIssuer };
         }
         // #491: only the `app` entry's own step runs `ensureAppLettermintMail`
-        // (`executor.ts`'s own `entry.key === APP_ENTRY_KEY` gate). Unlike
+        // (`executor.ts`'s own `isMainEntry(entry)` gate). Unlike
         // `secretSources`/`authIssuer` above, these two are set unconditionally
         // -- `null` when no platform is declared, never omitted -- because
         // `executor.ts` treats the key being *absent* as a stale plan predating
         // this field and refuses to run (review round 2, finding 3): an omitted
         // key here would read identically to a stale plan and silently fall
         // back to the unprotected pre-#491 path instead.
-        if (key === APP_ENTRY_KEY && app.step && app.step.action.desired.enabled !== false) {
+        if (key === mainKey && app.step && app.step.action.desired.enabled !== false) {
             app.step.action.desired = {
                 ...app.step.action.desired,
                 platformApex: readiness.platformApex,
@@ -3527,7 +3531,7 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, re
         // edge: blocked, not planned, while edge is not applied.
         const appReason = edgeNeeded(readiness, ['zones', 'dns']);
         if (appReason &&
-            key === APP_ENTRY_KEY &&
+            key === mainKey &&
             app.step &&
             app.step.action.desired.enabled !== false &&
             recordedIds[MAIL_DOMAIN_SCOPE_KEY]) {

package/dist/plan/executor.d.ts

@@ -19,6 +19,7 @@ import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor }
 import type { EdgePortName } from './platform-org.js';
 import type { RequestHeaderPort } from './platform-providers.js';
 import { type ReleaseContext, type ReleaseHost } from './release-host.js';
+import { type StageProbePort } from './stage-guards.js';
 import type { WorkerAppDatabasePort } from './worker-app-database.js';
 import { type KeysCustodyPort, type WorkerAppPort } from './worker-app.js';
 export declare function coolifyProjectMark(org: Pick<DeclaredOrg, 'id'>): string;
@@ -1731,6 +1732,11 @@ export interface FoundryStepExecutorPorts {
      * `edge.access` (see {@link EdgePort.access}). Kept for a host or a test that supplies its own.
      */
     access?: AccessPort;
+    /**
+     * The calls that prove a stage credential does not work against production (`plan/stage-guards.ts`). Without
+     * one the probes are reported as not run, and the stage copy stays blocked.
+     */
+    stageProbes?: StageProbePort;
     /**
      * F4.ratelimits: overrides the rate limiting rule calls, which otherwise go through
      * `edge.ratelimits` (see {@link EdgePort.ratelimits}). Kept for a host or a test that supplies its own.
@@ -1909,6 +1915,41 @@ export declare function healthUrls(org: DeclaredOrg): string[];
 export declare const COOLIFY_PROXY_ORIGIN = "http://coolify-proxy:80";
 /** The one Access policy foundry puts on a platform Access app (#84). */
 export declare const ACCESS_POLICY_NAME = "foundry: allowed emails";
+/**
+ * #164: the repo `coolifyAgora` builds the org's Agora from
+ * (https://github.com/wtfalch/agora) -- the issue's own "How" names this
+ * exact Dockerfile, and it is the only build strategy any app this file
+ * provisions ever uses ({@link CMS_APP_DOCKERFILE}/
+ * `CALLS_SERVICE_DOCKERFILE` below are all `dockerfile_location` into a
+ * `createGithubAppApplication` build-from-repo call, never a registry
+ * image): "Coolify builds each org's Agora from the agora repo" is not a
+ * fresh product choice here, it is this file's one established convention,
+ * followed rather than reopened (#164 "Decide" 1). The agora repo's own
+ * Dockerfile (`apps/agora/Dockerfile`) already `EXPOSE`s 8080 and serves
+ * from a build built at the repository root, the same one-repo shape
+ * `CMS_REPO`'s own two apps use. This comment used to claim that needed no
+ * `ports_exposes` of its own, on the theory that Coolify's github-app build
+ * reads a Dockerfile's `EXPOSE` the same way it does for `cmsSite`'s two
+ * apps above -- wrong (#506): Coolify never reads `EXPOSE` for a build it
+ * runs itself, so without an explicit `agora.ts`'s `AGORA_APP_PORTS_EXPOSES`,
+ * Traefik is left routing to a port nothing listens on, and a company's
+ * Agora answers 502 behind the tunnel. Seen live on Company Included,
+ * 2026-10-05.
+ */
+export declare const AGORA_REPO = "wtfalch/agora";
+export declare const AGORA_APP_DOCKERFILE = "/apps/agora/Dockerfile";
+/**
+ * #161 (Boule part): the repo `coolifyBoule` builds the org's Boule from
+ * (https://github.com/wtfalch/boule), by the same convention as
+ * {@link AGORA_REPO}: Coolify's github-app build from the repo, never a
+ * registry image. Boule's own Dockerfile is at the repository root, serves on
+ * 3000 (`EXPOSE 3000`) and runs `scripts/migrate-and-start.sh`, which applies
+ * its migrations as the owner and then serves as the `<database>_rt` role.
+ */
+export declare const BOULE_REPO = "wtfalch/boule";
+export declare const BOULE_APP_DOCKERFILE = "/Dockerfile";
+/** Boule's own `EXPOSE 3000` (its doc comment just above) -- the port its health check (#543) probes. */
+export declare const BOULE_PORT = 3000;
 export declare const LOG_DIR = "/app/logs";
 /** The company's Coolify destination (its Docker network `co-<slug>`), recorded when its first resource is created. */
 export declare const COOLIFY_DESTINATION_SCOPE_KEY = "coolify_destination";
@@ -2342,6 +2383,13 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * a step for it fails, which the next plan reports instead.
      */
     private coolifyBlueGreen;
+    /**
+     * Stage's guards (`plan/stage-guards.ts`): the probe port the host supplied, and the Access gate over the stage
+     * host. The gate is offered only when everything it needs is in hand (a domain, the platform's Access provider,
+     * the company's sign-in organisation, an owner, an Access port) and no `hosting.access` rule names the host: a
+     * bypass or service-token rule there would open stage, so no gate is made and the guard stays unrecorded.
+     */
+    private stageGuards;
     private coolifyApp;
     /**
      * #75: mounts a persistent volume at {@link LOG_DIR} on the app, unless one