@wtfalch/foundry 0.62.0 → 0.63.0

package/dist/bootstrap/declare.js

@@ -53,6 +53,7 @@ const SERVICES_ENABLED_BY_DEFAULT = new Set([
     'archon',
     'edge',
     'hc',
+    'registry',
 ]);
 /**
  * The services every company deploys its own copy of. Their platform entries
@@ -153,7 +154,9 @@ export function declaredPlatformFor(apex, serverIpv4) {
                     ? DEFAULT_MAIL_IMAGE_TAG
                     : key === 'hc'
                         ? DEFAULT_HC_IMAGE_TAG
-                        : DEFAULT_GIT_REF,
+                        : key === 'registry'
+                            ? VERSIONS.registry
+                            : DEFAULT_GIT_REF,
         };
     }
     return {

package/dist/bootstrap/versions.d.ts

@@ -12,6 +12,8 @@ export interface PinnedVersions {
     cloudflared: string;
     stalwart: string;
     hc: string;
+    /** The platform's image registry (`registry:3`, Docker's `distribution`). */
+    registry: string;
     /** The mail relay's base image (an exact Alpine release); Postfix comes from its package repository. */
     alpine: string;
     /** A static busybox, copied into the MAS image so its health check has an HTTP client. */

package/dist/index.d.ts

@@ -15,8 +15,8 @@ export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export type { Checkpoint, LastApplied, AppliedState, DestroyRecord, DestroyStepRecord, } from './state.js';
 export type { PlanStep, UnmanagedItem, PlanNote, Plan, VersionChangeItem } from './plan.js';
-export type { NativeBuildDispatchDeps, NativeBuildKeyEnvPort, } from './native-build.js';
-export { NATIVE_BUILD_REPO, NATIVE_BUILD_WORKFLOW_FILE, NATIVE_BUILD_WORKFLOW_REF, NATIVE_BUILD_DISPATCH_TIMEOUT_MS, NATIVE_BUILD_KEY_ENV, NATIVE_BUILD_KEY_BYTES, NativeBuildDispatchError, dispatchNativeBuild, mintNativeBuildKey, } from './native-build.js';
+export type { NativeBuildDispatchDeps } from './native-build.js';
+export { NATIVE_BUILD_REPO, NATIVE_BUILD_WORKFLOW_FILE, NATIVE_BUILD_WORKFLOW_REF, NATIVE_BUILD_DISPATCH_TIMEOUT_MS, NATIVE_BUILD_KEY_ENV, NATIVE_BUILD_KEY_BYTES, NativeBuildDispatchError, dispatchNativeBuild, } from './native-build.js';
 export type { AppliedVersion, AppliedVersionsStore, DeclaredOrgStore, HeldLease, MutationLease, PlatformStore, RequestedChangeStore, StaleUpdate, UpdateOptions, } from './store.js';
 export { StaleLeaseError } from './store.js';
 export type { PlanApply, DestroyProgress } from './apply.js';
@@ -40,6 +40,8 @@ export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError
 export type { StageCopyInput, StageCopyPort, StageCopyProduction, StageCopyRunRecord, UndoStageCopyInput, } from './plan/index.js';
 export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './plan/index.js';
 export type { Runner, StageCopyPortDeps } from './plan/index.js';
+export type { PlatformRegistryDeps, PlatformRegistryRuntime } from './plan/index.js';
+export { PLATFORM_REGISTRY_PULL_PASSWORD_REF, PLATFORM_REGISTRY_PUSH_PASSWORD_REF, PLATFORM_REGISTRY_PUSH_USER, platformRegistryPushCredential, } from './plan/index.js';
 export { InvalidMigrationConfirmationError, ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY, OrgPostgresMigrationBackupMissingError, OrgPostgresMigrationNotConfirmedError, } from './plan/index.js';
 export type { OrgPostgresMigrationConfirmation } from './plan/index.js';
 export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';
@@ -59,6 +61,8 @@ export type { PlanOwnSfuOptions, SfuAppDeps, SfuAppInput } from './plan/index.js
 export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu, provisionSfuApp, sfuConfig, sfuCompose, } from './plan/index.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, KeysRegistrarPort, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, LoginHostBinding, LoginHostBindingsPort, LoginHostDiscoveryPort, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
+export type { StageProbePort, ReleasePreviewMembers } from './plan/stage-guards.js';
+export type { StageCopyHostConfig } from './plan/stage-copy-host.js';
 export { NO_DOMAIN_ZONE, entryMachinePaths, ownHostnames, privatePageGateKey, workspaceHost, } from './plan/index.js';
 export type { PrivatePageScope } from './plan/index.js';
 export type { HostedLabelRefusal } from './hosted-label.js';

package/dist/index.js

@@ -10,7 +10,7 @@ export const PINNED_VERSIONS = VERSIONS;
 export { buildJsonSchema, parseBuildJson, BuildJsonError } from './build-json.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
-export { NATIVE_BUILD_REPO, NATIVE_BUILD_WORKFLOW_FILE, NATIVE_BUILD_WORKFLOW_REF, NATIVE_BUILD_DISPATCH_TIMEOUT_MS, NATIVE_BUILD_KEY_ENV, NATIVE_BUILD_KEY_BYTES, NativeBuildDispatchError, dispatchNativeBuild, mintNativeBuildKey, } from './native-build.js';
+export { NATIVE_BUILD_REPO, NATIVE_BUILD_WORKFLOW_FILE, NATIVE_BUILD_WORKFLOW_REF, NATIVE_BUILD_DISPATCH_TIMEOUT_MS, NATIVE_BUILD_KEY_ENV, NATIVE_BUILD_KEY_BYTES, NativeBuildDispatchError, dispatchNativeBuild, } from './native-build.js';
 export { StaleLeaseError } from './store.js';
 export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
@@ -24,6 +24,7 @@ export { DumpError, dumpNow } from './plan/index.js';
 export { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_IMAGE_REF, stageMailEnv, stageSinkAppName, } from './plan/index.js';
 export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError, stageCopy, tableExcluded, undoStageCopy, } from './plan/index.js';
 export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './plan/index.js';
+export { PLATFORM_REGISTRY_PULL_PASSWORD_REF, PLATFORM_REGISTRY_PUSH_PASSWORD_REF, PLATFORM_REGISTRY_PUSH_USER, platformRegistryPushCredential, } from './plan/index.js';
 export { InvalidMigrationConfirmationError, ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY, OrgPostgresMigrationBackupMissingError, OrgPostgresMigrationNotConfirmedError, } from './plan/index.js';
 export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';

package/dist/migrations/0067_requested_changes_kosmos.sql

@@ -0,0 +1,6 @@
+-- @wtfalch/foundry: a company's Boule can request `kosmos` (turn `org.kosmos.enabled` on or off).
+alter table foundry_requested_changes
+  drop constraint if exists foundry_requested_changes_field_check;
+alter table foundry_requested_changes
+  add constraint foundry_requested_changes_field_check
+    check (field in ('calls', 'customers', 'storageLimit', 'aiLimit', 'domain', 'mailTier', 'app', 'build', 'bouleApps', 'kosmos'));

package/dist/migrations/0068_platform_registry.sql

@@ -0,0 +1,17 @@
+-- @wtfalch/foundry: the platform's image registry (`registry:3`), declared with the rest of the
+-- platform. Mirrors `src/store/schema.ts`'s `foundryDeclaredPlatform` additions. Off for the
+-- platform that already exists: foundry deploys nothing new until it is declared on. Backfills
+-- `registry_hostname` the way `0047_platform_coolify.sql` backfilled `coolify_hostname`: the
+-- column must not be empty (`src/platform.ts`'s `validatePlatform`).
+
+alter table foundry_declared_platform
+  add column if not exists registry_enabled boolean not null default false,
+  add column if not exists registry_hostname text,
+  add column if not exists registry_git_ref text not null default '';
+
+update foundry_declared_platform
+  set registry_hostname = 'registry.' || apex
+  where registry_hostname is null;
+
+alter table foundry_declared_platform
+  alter column registry_hostname set not null;

package/dist/native-build.d.ts

@@ -7,15 +7,14 @@
  * workflow, and the key Boule presents when it asks the host (Archon) to
  * dispatch it.
  *
- * Neither function here is wired into `plan/diff.ts` or `plan/executor.ts`:
  * `dispatchNativeBuild` runs inside Archon's own `/api/native/builds`
- * route, not foundry's apply loop, and `mintNativeBuildKey` is left for the
- * host to call from wherever it writes Boule's env (`executor.ts`'s
- * `coolifyBoule`, the same way it already calls `mintIfAbsent` for
- * `BOULE_OWNER_SEED_SECRET_ENV`) once that wiring has its own review --
- * adding it here would touch every one of this package's Boule-convergence
- * fixtures for one new env var, which is a larger change than this issue
- * asks for.
+ * route, not foundry's apply loop. The key itself is minted by
+ * `plan/executor.ts`'s `coolifyBoule` (`ensureNativeBuildKey`), reusing the
+ * same `mintIfAbsent` path every other per-company Boule secret goes
+ * through (foundry#970) -- this file keeps only the env name and the byte
+ * length, not a second mint function (foundry#957 review note 2 and
+ * thermo note 1: the earlier `mintNativeBuildKey` was a third, buggy copy
+ * of that same check).
  */
 export declare const NATIVE_BUILD_REPO = "wtfalch/shell";
 export declare const NATIVE_BUILD_WORKFLOW_FILE = "build-app.yml";
@@ -49,22 +48,3 @@ export declare function dispatchNativeBuild(deps: NativeBuildDispatchDeps, run:
 /** The env name Boule presents this key under, to Archon's native-build route. */
 export declare const NATIVE_BUILD_KEY_ENV = "NATIVE_BUILD_KEY";
 export declare const NATIVE_BUILD_KEY_BYTES = 32;
-/** The one thing {@link mintNativeBuildKey} needs from Coolify: a live app's env, to check whether it already has a key. */
-export interface NativeBuildKeyEnvPort {
-    listEnvs(appId: string): Promise<ReadonlyArray<{
-        key: string;
-        value: string;
-        is_preview: boolean;
-    }>>;
-}
-/**
- * Mints the per-company key Boule presents to Archon's native-build route
- * (estate#262), the same way every other per-company key in this codebase is
- * minted (estate#207): a random value, written to Boule's env once and never
- * rotated, kept unchanged on every later apply once it is there. Returns
- * `null` when Boule's env already holds one -- the caller then writes
- * nothing, so the live value stands. `onSecret`, when given, is told the
- * minted value so the caller can keep it out of its own logs and error
- * messages.
- */
-export declare function mintNativeBuildKey(coolify: NativeBuildKeyEnvPort, appId: string, onSecret?: (value: string) => void): Promise<string | null>;

package/dist/native-build.js

@@ -1,4 +1,3 @@
-import { randomBytes } from 'node:crypto';
 /**
  * `wtfalch/shell`'s `build-app.yml`: the one GitHub Actions workflow that
  * builds and signs a company's native app shell (estate
@@ -8,15 +7,14 @@ import { randomBytes } from 'node:crypto';
  * workflow, and the key Boule presents when it asks the host (Archon) to
  * dispatch it.
  *
- * Neither function here is wired into `plan/diff.ts` or `plan/executor.ts`:
  * `dispatchNativeBuild` runs inside Archon's own `/api/native/builds`
- * route, not foundry's apply loop, and `mintNativeBuildKey` is left for the
- * host to call from wherever it writes Boule's env (`executor.ts`'s
- * `coolifyBoule`, the same way it already calls `mintIfAbsent` for
- * `BOULE_OWNER_SEED_SECRET_ENV`) once that wiring has its own review --
- * adding it here would touch every one of this package's Boule-convergence
- * fixtures for one new env var, which is a larger change than this issue
- * asks for.
+ * route, not foundry's apply loop. The key itself is minted by
+ * `plan/executor.ts`'s `coolifyBoule` (`ensureNativeBuildKey`), reusing the
+ * same `mintIfAbsent` path every other per-company Boule secret goes
+ * through (foundry#970) -- this file keeps only the env name and the byte
+ * length, not a second mint function (foundry#957 review note 2 and
+ * thermo note 1: the earlier `mintNativeBuildKey` was a third, buggy copy
+ * of that same check).
  */
 export const NATIVE_BUILD_REPO = 'wtfalch/shell';
 export const NATIVE_BUILD_WORKFLOW_FILE = 'build-app.yml';
@@ -72,21 +70,3 @@ export async function dispatchNativeBuild(deps, run) {
 /** The env name Boule presents this key under, to Archon's native-build route. */
 export const NATIVE_BUILD_KEY_ENV = 'NATIVE_BUILD_KEY';
 export const NATIVE_BUILD_KEY_BYTES = 32;
-/**
- * Mints the per-company key Boule presents to Archon's native-build route
- * (estate#262), the same way every other per-company key in this codebase is
- * minted (estate#207): a random value, written to Boule's env once and never
- * rotated, kept unchanged on every later apply once it is there. Returns
- * `null` when Boule's env already holds one -- the caller then writes
- * nothing, so the live value stands. `onSecret`, when given, is told the
- * minted value so the caller can keep it out of its own logs and error
- * messages.
- */
-export async function mintNativeBuildKey(coolify, appId, onSecret) {
-    const envs = await coolify.listEnvs(appId);
-    if (envs.some((e) => e.key === NATIVE_BUILD_KEY_ENV && !e.is_preview))
-        return null;
-    const value = randomBytes(NATIVE_BUILD_KEY_BYTES).toString('base64url');
-    onSecret?.(value);
-    return value;
-}

package/dist/plan/archon-blue-green.d.ts

@@ -2,6 +2,7 @@ import { type BlueGreenApplyDeps } from './blue-green-apply.js';
 import { type BlueGreenSubject } from './blue-green.js';
 import type { DeployHealthRuntime } from './deploy-health.js';
 import type { PlatformTunnelPort } from './platform-providers.js';
+import type { StageGuardDeps } from './stage-guards.js';
 export interface ArchonBlueGreenRun {
     subject: BlueGreenSubject;
     /** The owner company's id: the health token's held ref is `sharedSecretRef(ownerOrgId, ...)` like an entry's. */
@@ -42,6 +43,10 @@ export interface ArchonBlueGreenRun {
     sleep: (ms: number) => Promise<void>;
     logDir: string;
     isRunning: (status: string | undefined) => boolean;
+    /** Stage's probe port and Access gate, the same guards an entry's stage gets. Absent: the guards read "not run". */
+    stageGuards?: StageGuardDeps;
+    /** The guard names the plan counted (`desired.guards`); they go into the applied hash. */
+    guardInputs?: readonly string[];
 }
 /**
  * platform-archon on the blue/green path (`platform.archon.blueGreen`): the archon app keeps its name and is

package/dist/plan/archon-blue-green.js

@@ -70,6 +70,8 @@ export async function applyArchonBlueGreen(run) {
             generate: () => randomBytes(32).toString('hex'),
             secret: run.secret,
         }),
+        ...(run.stageGuards ? { stageGuards: run.stageGuards } : {}),
+        ...(run.guardInputs ? { guardInputs: run.guardInputs } : {}),
         actionsKey: async () => {
             const key = await mintActionsKey({
                 id,

package/dist/plan/blue-green-apply.d.ts

@@ -54,6 +54,11 @@ export interface BlueGreenApplyDeps {
      * guard unrecorded ("not run", never passed), so `stageGuardsReady` stays false and the copy does not start.
      */
     stageGuards?: StageGuardDeps;
+    /**
+     * The guard names the plan counted ({@link stageGuardInputs}, from `desired.guards`). They go into the
+     * applied structure hash, so the next plan sees the same hash until a guard becomes possible.
+     */
+    guardInputs?: readonly string[];
     /**
      * The company the stage mail sink belongs to (its name is `<slug>-stage-sink`). Absent: no sink is made and
      * stage holds no mail env at all, so the copy stays refused.

package/dist/plan/blue-green-apply.js

@@ -10,6 +10,8 @@ import { remoteDatabaseAddress, remoteDatabaseHost } from './remote-database.js'
 import { STAGE_SIGN_IN_NAMES, buildStageEnv } from './stage-env.js';
 import { buildStageProbes, runStageProbes, stageProbesRecord, } from './stage-guards.js';
 import { assertStageIsolated, envClass, stageIsolationHash, } from './stage-isolation.js';
+import { StageServiceError, ensureStageServices } from './stage-services.js';
+import { STAGE_SIGNIN_NONE, StageSignInError, ensureStagePublicClient, ensureStageSignIn, } from './stage-signin.js';
 import { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_APP_SCOPE_KEY, STAGE_SINK_HTTP_PORT, STAGE_SINK_IMAGE_TAG, STAGE_SINK_REPOSITORY, stageMailEnv, stageSinkAppName, } from './stage-sink.js';
 import { readWorkspaceCommit, wsKey } from './workspace.js';
 /** How long one Coolify call of the sink may take. */
@@ -95,7 +97,10 @@ export async function applyBlueGreenServer(deps, subject, server) {
             await deps.persist();
         }
     }
-    deps.record(bgKey.applied(id, server.uuid), structureHash(subject, { primary: isPrimary }));
+    deps.record(bgKey.applied(id, server.uuid), structureHash(subject, {
+        primary: isPrimary,
+        ...(deps.guardInputs ? { guards: deps.guardInputs } : {}),
+    }));
     await deps.persist();
 }
 /**
@@ -481,30 +486,92 @@ export async function ensureStage(deps, subject, serverUuid) {
     const stageHas = new Map((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
     const mailChanged = [...mail, ...signInEnv].some((e) => stageHas.get(e.key) !== e.value);
     stageEnv.push(...mail);
-    const stageSurface = {
+    const stageSurfaceOf = () => ({
         env: stageEnv.map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
         resources: stageResources(subject),
+    });
+    const prodSurface = {
+        env: [...prodEnv, ...greenEnv]
+            .filter((e) => !e.is_preview && e.value !== undefined)
+            .map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
+        resources: prodResources(subject),
+        internalHosts: Object.values(prodResources(subject)),
     };
-    const violations = assertStageIsolated({
+    const sinkMail = Object.fromEntries(mail.map((e) => [e.key, e.value]));
+    const signInIsolation = deps.signIn
+        ? { signIn: { customers: deps.signIn.customers, live: deps.signIn.live } }
+        : {};
+    const isolationViolations = (surface) => assertStageIsolated({
         kind,
-        prod: {
-            env: [...prodEnv, ...greenEnv]
-                .filter((e) => !e.is_preview && e.value !== undefined)
-                .map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
-            resources: prodResources(subject),
-            internalHosts: Object.values(prodResources(subject)),
-        },
-        stage: stageSurface,
-        sinkMail: Object.fromEntries(mail.map((e) => [e.key, e.value])),
-        ...(deps.signIn
-            ? { signIn: { customers: deps.signIn.customers, live: deps.signIn.live } }
-            : {}),
+        prod: prodSurface,
+        stage: surface,
+        sinkMail,
+        ...signInIsolation,
     });
+    // The env written this run, and the env stage already holds (put there by an earlier apply, an older
+    // builder or a hand): a forbidden name or a production value already on the live stage app is refused too.
+    // A name this run writes again is replaced, so only the other live names are checked here.
+    const written = new Set(stageEnv.map((e) => e.key));
+    const liveStage = {
+        env: [...stageHas]
+            .filter(([name, value]) => value !== undefined && !written.has(name))
+            .map(([name, value]) => ({ name, class: envClass(name), value })),
+        resources: {},
+    };
+    let stageSurface = stageSurfaceOf();
+    const violations = [
+        ...new Set([
+            ...isolationViolations(stageSurface),
+            ...assertStageIsolated({
+                kind,
+                prod: prodSurface,
+                stage: liveStage,
+                sinkMail,
+                ...signInIsolation,
+            }),
+        ]),
+    ].sort();
     if (violations.length > 0) {
         // Stage fails closed for itself: nothing is written to it, production's structure goes on.
         await stageFailed(deps, subject, `blocked:${violations.join(',')}`);
         return;
     }
+    // Stage's own files, ai and jobs organisations and keys, for the services production's app uses. They are made
+    // before the probes, which need the keys; nothing is written to the stage app until the probes were rejected.
+    const prodValues = new Map(prodEnv
+        .filter((e) => !e.is_preview && e.value !== undefined)
+        .map((e) => [e.key, e.value]));
+    let servicesRecord;
+    try {
+        const made = await ensureStageServices({
+            id: subject.id,
+            kind,
+            prod: prodValues,
+            port: deps.stageGuards?.services,
+            recorded: deps.recorded,
+            record: deps.record,
+            persist: deps.persist,
+            secret: deps.secret,
+            log: (line) => console.info(`${deps.label}: ${line}`),
+        });
+        stageEnv.push(...made.env);
+        servicesRecord = made.record;
+    }
+    catch (error) {
+        // A StageServiceError holds ids and refs only; any other cause can echo a credential.
+        if (error instanceof StageServiceError)
+            console.error(`${deps.label}: ${error.message}`);
+        await stageFailed(deps, subject, 'blocked:services', error);
+        return;
+    }
+    if (servicesRecord !== 'none') {
+        stageSurface = stageSurfaceOf();
+        const withServices = isolationViolations(stageSurface);
+        if (withServices.length > 0) {
+            await stageFailed(deps, subject, `blocked:${withServices.join(',')}`);
+            return;
+        }
+    }
     // Stage's credentials are tried against production before they are written; one that production accepts
     // blocks stage (nothing is written to it), and what was tried is recorded by name so the copy slice sees it.
     const stageValues = new Map((await coolify.listEnvs(appId))
@@ -512,7 +579,7 @@ export async function ensureStage(deps, subject, serverUuid) {
         .map((e) => [e.key, e.value]));
     for (const e of stageEnv)
         stageValues.set(e.key, e.value);
-    const isolationHash = stageIsolationHash(stageSurface);
+    let isolationHash = stageIsolationHash(stageSurface);
     let probeResult;
     try {
         probeResult = await runStageProbes(buildStageProbes({
@@ -524,9 +591,12 @@ export async function ensureStage(deps, subject, serverUuid) {
                 ? { liveCustomersOrgId: deps.signIn.live.customersOrgId }
                 : {}),
             ...(deps.signIn ? { signInRedirectUri: deps.signIn.redirectUri } : {}),
-            prod: new Map(prodEnv
-                .filter((e) => !e.is_preview && e.value !== undefined)
-                .map((e) => [e.key, e.value])),
+            prod: new Map([
+                ...prodValues,
+                ...(deps.stageGuards?.services?.prodJobsProjectId
+                    ? [['JOBS_PROJECT_ID', deps.stageGuards.services.prodJobsProjectId]]
+                    : []),
+            ]),
         }));
     }
     catch (error) {
@@ -534,7 +604,7 @@ export async function ensureStage(deps, subject, serverUuid) {
         await stageFailed(deps, subject, 'blocked:database', error);
         return;
     }
-    const probes = stageProbesRecord(probeResult, isolationHash, stageValues);
+    let probes = stageProbesRecord(probeResult, isolationHash, stageValues);
     if (probeResult.failed.length > 0) {
         deps.record(bgKey.stageProbes(subject.id), probes.value);
         await stageFailed(deps, subject, `blocked:${probeResult.failed.join(',')}`);
@@ -544,9 +614,108 @@ export async function ensureStage(deps, subject, serverUuid) {
         await stageFailed(deps, subject, 'blocked:gate');
         return;
     }
+    // Stage's own sign-in: made only now, after the isolation check, the probes and the gate. Its credentials are
+    // added to the env and the isolation check runs once more over the whole of it.
+    const signIn = deps.stageGuards?.signIn;
+    let signInGuard;
+    if (signIn?.required === true && signIn.public === true) {
+        // A static SPA (Agora): a client and nothing secret. Its config is built from production's with the stage
+        // client id, then the isolation check runs once more over the whole env.
+        try {
+            const made = await ensureStagePublicClient({
+                id: subject.id,
+                port: signIn,
+                recorded: deps.recorded,
+                record: deps.record,
+                persist: deps.persist,
+            });
+            const rebuilt = buildStageEnv({
+                kind,
+                appUrl: stageAppUrl(subject),
+                logDir: deps.logDir,
+                database,
+                prod: prodEnv,
+                existing: [],
+                mint: () => '',
+                stageClientId: made.clientId,
+            });
+            const config = rebuilt.env.find((e) => e.key === 'AGORA_CONFIG');
+            if (config)
+                stageEnv.push(config);
+            signInGuard = made.guard;
+        }
+        catch (error) {
+            if (error instanceof StageSignInError)
+                console.error(`${deps.label}: ${error.message}`);
+            deps.record(bgKey.stageSignIn(subject.id), '');
+            await stageFailed(deps, subject, 'blocked:signin', error);
+            return;
+        }
+        for (const e of stageEnv)
+            stageValues.set(e.key, e.value);
+        stageSurface = stageSurfaceOf();
+        const again = isolationViolations(stageSurface);
+        if (again.length > 0) {
+            deps.record(bgKey.stageSignIn(subject.id), '');
+            await stageFailed(deps, subject, `blocked:${again.join(',')}`);
+            return;
+        }
+        isolationHash = stageIsolationHash(stageSurface);
+        probes = stageProbesRecord(probeResult, isolationHash, stageValues);
+    }
+    else if (signIn?.required === true) {
+        try {
+            const made = await ensureStageSignIn({
+                id: subject.id,
+                port: signIn,
+                recorded: deps.recorded,
+                record: deps.record,
+                persist: deps.persist,
+                secret: deps.secret,
+                generate: () => randomBytes(32).toString('base64url'),
+                sleep: deps.sleep,
+            });
+            stageEnv.push(...made.env);
+            signInGuard = made.guard;
+        }
+        catch (error) {
+            // A StageSignInError holds ids and refs only; any other cause can echo a credential.
+            if (error instanceof StageSignInError)
+                console.error(`${deps.label}: ${error.message}`);
+            deps.record(bgKey.stageSignIn(subject.id), '');
+            await stageFailed(deps, subject, 'blocked:signin', error);
+            return;
+        }
+        if (!stageEnv.some((e) => e.key === 'AUTH_COOKIE_SECRET')) {
+            // A cookie secret of stage's own, kept across applies; never a copy of production's.
+            const have = stageHas.get('AUTH_COOKIE_SECRET') || randomBytes(32).toString('base64url');
+            deps.secret(have);
+            stageEnv.push({ key: 'AUTH_COOKIE_SECRET', value: have });
+        }
+        for (const e of stageEnv)
+            stageValues.set(e.key, e.value);
+        stageSurface = stageSurfaceOf();
+        const again = isolationViolations(stageSurface);
+        if (again.length > 0) {
+            deps.record(bgKey.stageSignIn(subject.id), '');
+            await stageFailed(deps, subject, `blocked:${again.join(',')}`);
+            return;
+        }
+        isolationHash = stageIsolationHash(stageSurface);
+        probes = stageProbesRecord(probeResult, isolationHash, stageValues);
+    }
+    else if (signIn?.required === false) {
+        signInGuard = STAGE_SIGNIN_NONE;
+    }
+    else {
+        console.info(`${deps.label}: stage sign-in was not set up: the host gave no sign-in for this subject, so ${bgKey.stageSignIn(subject.id)} stays unrecorded`);
+    }
     await upsertEnv(deps, appId, stageEnv);
+    if (signInGuard)
+        deps.record(bgKey.stageSignIn(subject.id), signInGuard);
     if (mail.length > 0)
         deps.record(bgKey.stageSink(subject.id), 'applied');
+    deps.record(bgKey.stageServices(subject.id), servicesRecord);
     deps.record(bgKey.stageIsolation(subject.id), isolationHash);
     deps.record(bgKey.stageProbes(subject.id), probes.value);
     await deps.persist();
@@ -589,8 +758,11 @@ async function ensureStageGate(deps, subject) {
     if (!gate || deps.recorded()[bgKey.stageGate(subject.id)])
         return true;
     let id;
+    let membersHash;
     try {
-        id = (await gate.create()).id;
+        const created = await gate.create();
+        id = created.id;
+        membersHash = created.membersHash;
     }
     catch (error) {
         // An Access error can echo the request, which names the people allowed in: only its name is logged.
@@ -598,6 +770,8 @@ async function ensureStageGate(deps, subject) {
         return false;
     }
     deps.record(bgKey.stageGate(subject.id), id);
+    if (membersHash)
+        deps.record(bgKey.stageGateMembers(subject.id), membersHash);
     await deps.persist();
     return true;
 }
@@ -607,7 +781,8 @@ async function stageAppId(deps, subject, name, serverUuid) {
         name,
         server: serverUuid,
         branch: subject.branch,
-        autoDeploy: true,
+        // Stage deploys only when a person promotes a commit to it (`deploy_stage`); a merge never reaches it.
+        autoDeploy: false,
     });
 }
 function isNotFound(error) {

package/dist/plan/blue-green.d.ts

@@ -29,6 +29,8 @@ export declare const bgKey: {
     digest: (id: string, color: Color) => string;
     weights: (id: string) => string;
     stage: (id: string) => string;
+    /** The last `deploy_stage`: `<ISO time>|ok|<commit>` or `<ISO time>|failed|<step>`. */
+    stageDeploy: (id: string) => string;
     window: (id: string) => string;
     held: (id: string, digest: string) => string;
     /** The weights the load balancer on `server` was last written with. */
@@ -55,8 +57,29 @@ export declare const bgKey: {
     stageIsolation: (id: string) => string;
     /** The id of the Access gate over the stage host: staff only, no bypass, no service-token rule. */
     stageGate: (id: string) => string;
+    /** The hash of the sorted email list last written to the stage gate (owners plus the people holding `releases:preview`). */
+    stageGateMembers: (id: string) => string;
     /** `ok:<hash>` once every apply-time probe was rejected; `notrun:<names>` or `failed:<names>` otherwise. */
     stageProbes: (id: string) => string;
+    /** Stage's own sign-in client: its ZITADEL app id, and its client id (public, not a secret). */
+    stageClient: (id: string) => string;
+    stageClientId: (id: string) => string;
+    /** The held ref of stage's app key, recorded and persisted as soon as it is minted (no `:`: undelivered). */
+    stageSignInKey: (id: string) => string;
+    /** `{name, organizationId}` of stage's broker entry, so org destroy can remove it. No key. */
+    stageBroker: (id: string) => string;
+    /** `ok:<hash of the client, app and broker entry ids>` or `none`; the copy waits for it. */
+    stageSignIn: (id: string) => string;
+    /** `none` (production's app uses no files, ai or jobs) or `ok:<hash>` once every service it uses is held by stage or listed absent. */
+    stageServices: (id: string) => string;
+    /** `ok:<hash of the ids>` or `absent:<service>:<reason>` for one service (`files`, `ai` or `jobs`). */
+    stageService: (id: string, service: string) => string;
+    /** The id of stage's own organisation (files, ai) or project (jobs). An id, not a secret. */
+    stageServiceOrg: (id: string, service: string) => string;
+    /** The name stage's project or organisation was made under, when the service is deleted by name (jobs). */
+    stageServiceName: (id: string, service: string) => string;
+    /** `{ids, refs}` of stage's keys in that service: key ids and held refs, never a value. */
+    stageServiceKeys: (id: string, service: string) => string;
     /** `applied` once the stage app holds the sink's mail env. The copy refuses without it. */
     stageSink: (id: string) => string;
     /** `<ISO time>|<dump execution id>|ok`, written by a finished copy of production into stage. */
@@ -293,9 +316,38 @@ export interface BlueGreenPlanStep {
 /** A short hash of what decides the shape of a server's apps, so a change replans the server. */
 export declare function structureHash(subject: BlueGreenSubject, input: {
     primary: boolean;
+    guards?: readonly string[];
 }): string;
-/** The kind of stage app a subject has: platform-archon, else a customer app. */
-export declare const stageKindOf: (subject: Pick<BlueGreenSubject, "id">) => StageKind;
+/**
+ * The kind of stage app a subject has: Boule and Agora by `builtin` (a hosting entry that happens to be keyed
+ * `boule` is still a customer app), platform-archon by its id, else a customer app (kosmos included: it has no lists of its own).
+ */
+export declare const stageKindOf: (subject: Pick<BlueGreenSubject, "id" | "builtin">) => StageKind;
+/** What decides which stage guards can be made. Each is a fact the planner and the executor both hold. */
+export interface StageGuardFacts {
+    /** The host supplied the probe port. */
+    probesPort: boolean;
+    /** The host has an Access port. */
+    accessPort: boolean;
+    /** The platform's recorded Access provider. */
+    providerId?: string | null | undefined;
+    /** The domain the stage host is under. */
+    domain?: string | null | undefined;
+    /** The company's sign-in organisation, the claim the gate requires. */
+    claimValue?: string | null | undefined;
+    /** How many owner emails the gate admits. */
+    emails: number;
+    /** A `hosting.access` rule already names the stage host: no gate is made over it. */
+    hostRuled: boolean;
+}
+/**
+ * The stage guards that can be made now, by name. The names go into the applied structure hash, so a guard
+ * that becomes possible after the first apply changes the hash and plans the structure step once more.
+ */
+export declare function stageGuardInputs(facts: StageGuardFacts): string[];
+/** The guard names as the plan's `desired.guards` carries them, and back. */
+export declare const formatGuards: (guards: readonly string[]) => string;
+export declare const parseGuards: (value: unknown) => string[];
 /** The names stage can collide on. */
 export declare function stageResources(subject: BlueGreenSubject): Record<string, string>;
 /** The names of the subject's live parts: stage must equal none of them. */
@@ -322,6 +374,11 @@ export interface PlanBlueGreenInput {
     accessProviderId?: string | null;
     /** The company's stage mail sink is recorded and its live app is stopped or gone (read from Coolify at plan time). */
     stageSinkDown?: boolean;
+    /** Which stage-guard ports the host has. Absent: neither, so no guard input is counted. */
+    stageGuardPorts?: {
+        probes: boolean;
+        access: boolean;
+    };
 }
 /**
  * Plans the blue/green parts of an org: per usable server, one structure step (the apps, the balancer, the
@@ -371,6 +428,8 @@ export declare function planArchonBlueGreen(input: {
     servers: readonly BlueGreenServer[] | undefined;
     /** Why the executor cannot run it (no way to hold the health token), or absent. */
     executorBlocked?: string | undefined;
+    /** The stage guards that can be made now ({@link stageGuardInputs}); they go into the applied hash. */
+    guards?: readonly string[];
 }): {
     step: BlueGreenPlanStep | null;
     unmanaged: UnmanagedLine[];