@wtfalch/foundry 0.62.0 → 0.64.0

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/org.d.ts

@@ -301,7 +301,7 @@ export type AccessRule = {
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export declare const APP_ENTRY_KEY = "app";
 /** Why a validator refused. `code` is stable and never reworded; `message` is for people. */
-export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
+export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'entry_image_invalid' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
 /**
  * One refusal: a stable `code`, the dotted `path` into {@link DeclaredOrg} it is about
  * (`hosting.entries.terminal.uses.auth.registration`) and the sentence for people.
@@ -311,6 +311,19 @@ export interface OrgRefusal {
     path: string;
     message: string;
 }
+/**
+ * A built image a server entry runs instead of building from a repository: `repository` is
+ * `<host>[:port]/<owner>/<name>`, `digest` is `sha256:` and 64 lowercase hex digits. Same shapes as a server
+ * `build.json` (`build-json.ts`).
+ */
+export interface EntryImage {
+    repository: string;
+    digest: `sha256:${string}`;
+}
+/** The registry path of an {@link EntryImage}: `<host>[:port]/<owner>/<name>`, any host. */
+export declare const ENTRY_IMAGE_REPOSITORY: RegExp;
+/** The digest of an {@link EntryImage}. */
+export declare const ENTRY_IMAGE_DIGEST: RegExp;
 /**
  * One app the org runs. `database` and `gates` are meaningless without
  * `HostingConfig.enabled`, so `validateHosting` requires it before either is
@@ -334,6 +347,11 @@ export interface HostingEntry {
     buildPack: HostingBuildPack;
     /** The port the app listens on. `null` is Coolify's default. */
     port: number | null;
+    /**
+     * A built image the app runs, pulled as `repository@digest`, instead of a build from `repo`. Then `folder` is `null`, `branch` and `buildPack` stay at their defaults;
+     * `validateEntryImage` states the rest. A new digest redeploys the app.
+     */
+    image?: EntryImage;
     /**
      * The app's live address on the platform's apps domain: `<hostedName>.companyincluded.app`. A
      * label {@link hostedLabelRefusal} accepts; unique within the org (the host checks it across orgs).

package/dist/org.js

@@ -16,6 +16,10 @@ export const APP_ENTRY_KEY = 'app';
 function refusal(code, path, message) {
     return { code, path, message };
 }
+/** The registry path of an {@link EntryImage}: `<host>[:port]/<owner>/<name>`, any host. */
+export const ENTRY_IMAGE_REPOSITORY = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[0-9]{1,5})?\/[a-z0-9]([a-z0-9-]*[a-z0-9])?\/[a-z0-9][a-z0-9._-]*$/;
+/** The digest of an {@link EntryImage}. */
+export const ENTRY_IMAGE_DIGEST = /^sha256:[0-9a-f]{64}$/;
 export const MAX_PRIVATE_PAGES = 20;
 export const MAX_PRIVATE_PAGE_ROLES = 50;
 export const MAX_PRIVATE_PAGE_PEOPLE = 200;
@@ -211,6 +215,9 @@ export function refuseHosting(hosting, names) {
             return refusal('entry_key_not_unique', `hosting.entries.${entry.key}.key`, `hosting.entries key '${entry.key}' is not unique`);
         }
         seenKeys.add(entry.key);
+        const invalidImage = validateEntryImage(entry);
+        if (invalidImage)
+            return invalidImage;
         const invalid = validateHostingEntry(entry, hosting.enabled, reserveKeys, hosting.github);
         if (invalid)
             return invalid;
@@ -513,8 +520,8 @@ export function companyGithubFor(hosting, repo) {
     const github = hosting.github;
     return github && repo !== null && repoUnderAccount(repo, github.account) ? github : undefined;
 }
-// The env names `pushAppEnv` and `pushDatabaseUrl` set themselves.
-const FOUNDRY_ENV_NAME = /^(APP_URL|LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$/;
+// The env names `pushAppEnv` and `pushDatabaseUrl` set themselves. `APP_URL` is also set, but only on the main entry.
+const FOUNDRY_ENV_NAME = /^(LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$/;
 // Set only on the colors of a blueGreen entry; any other entry may declare them.
 const BLUE_GREEN_ENV_NAME = /^(REPORTING_(COLOR|RELEASE|HEALTH_TOKEN)|NEXT_SERVER_ACTIONS_ENCRYPTION_KEY)$/;
 const SECRET_ENV_NAME = /_(KEY|SECRET|TOKEN|PASSWORD)$/;
@@ -626,6 +633,39 @@ function validateEntryPrivatePages(entry, at, hostingEnabled) {
     }
     return null;
 }
+/** Why an entry's `image` is refused, or `null`. Read wherever hosting is read, so a stored entry is checked too. */
+function validateEntryImage(entry) {
+    const value = entry.image;
+    if (value === undefined)
+        return null;
+    const path = `hosting.entries.${entry.key}.image`;
+    const at = `hosting.entries '${entry.key}'`;
+    const invalid = (message) => refusal('entry_image_invalid', path, `${at} ${message}`);
+    const isObject = typeof value === 'object' && value !== null && !Array.isArray(value);
+    const { repository, digest } = (isObject ? value : {});
+    if (!isObject ||
+        Object.keys(value).some((k) => k !== 'repository' && k !== 'digest') ||
+        typeof repository !== 'string' ||
+        !ENTRY_IMAGE_REPOSITORY.test(repository) ||
+        repository.split('/').some((part) => /^\.+$/.test(part)) ||
+        typeof digest !== 'string' ||
+        !ENTRY_IMAGE_DIGEST.test(digest)) {
+        return invalid('image must be { repository, digest }: a registry path like registry.example.com/owner/name, and a digest of sha256: and 64 lowercase letters a-f or digits');
+    }
+    if (entry.folder !== null || entry.branch !== 'main' || entry.buildPack !== 'nixpacks') {
+        return invalid("runs a built image, so it cannot also build from a repository: remove the image, or set folder to null and keep the default branch and build pack (repo may stay, as the app's source)");
+    }
+    if (entry.worker !== undefined || entry.workerApp !== undefined) {
+        return invalid('runs a built image on a server, so it cannot also be a Worker or a Worker app');
+    }
+    if (entry.blueGreen !== undefined ||
+        entry.workspace !== undefined ||
+        entry.live === false ||
+        entry.liveCommit !== undefined) {
+        return invalid('runs a built image, which does not support a workspace, blue/green releases or a promote yet: remove them, or build from a repository');
+    }
+    return null;
+}
 function validateHostingEntry(entry, enabled, reserveKeys, github) {
     const at = `hosting.entries '${entry.key}'`;
     if (!ENTRY_KEY.test(entry.key)) {
@@ -689,7 +729,9 @@ function validateHostingEntry(entry, enabled, reserveKeys, github) {
         if (!name) {
             return refusal('env_name_empty', `hosting.entries.${entry.key}.env`, `${at} env needs a non-empty env var name`);
         }
-        if (FOUNDRY_ENV_NAME.test(name) || (entry.blueGreen && BLUE_GREEN_ENV_NAME.test(name))) {
+        if (FOUNDRY_ENV_NAME.test(name) ||
+            (name === 'APP_URL' && isMainEntry(entry)) ||
+            (entry.blueGreen && BLUE_GREEN_ENV_NAME.test(name))) {
             return refusal('env_name_reserved', `hosting.entries.${entry.key}.env.${name}`, `${at} env '${name}' is set by foundry and cannot be declared`);
         }
         if (typeof value !== 'string') {

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) {