@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/plan/org-apps-admin.d.ts

@@ -0,0 +1,108 @@
+import { type DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+import type { CoolifyPort } from './executor.js';
+import { type JobRuntime } from './job-app.js';
+import type { StepScope } from './own-services.js';
+/** The role's name on the server: the org's slug plus `_apps_admin`. */
+export declare const appsAdminRoleName: (org: Pick<DeclaredOrg, "slug">) => string;
+/** The job app's name in Coolify. */
+export declare const appsAdminJobName: (org: Pick<DeclaredOrg, "slug">) => string;
+/** Recorded once the role is made, its password set, and the URL delivered. */
+export declare const ORG_APPS_ADMIN_SCOPE_KEY = "org_apps_admin";
+/**
+ * An opaque id, set once the password is minted and the job that sets it is about to run, until the URL is
+ * delivered. Never the password. A failure before that point leaves no id, so the next apply tries again.
+ */
+export declare const ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY = "org_apps_admin_undelivered";
+/** The job app's id while it exists. */
+export declare const ORG_APPS_ADMIN_JOB_APP_SCOPE_KEY = "org_apps_admin_job_app";
+/** Where the host holds the role's connection URL, once delivered -- `deliverSecret`'s own naming convention. */
+export declare const appsAdminUrlRef: (org: Pick<DeclaredOrg, "slug">) => string;
+/** How many times the URL is handed to `deliverSecret`. */
+export declare const ORG_APPS_ADMIN_DELIVERY_ATTEMPTS = 3;
+export interface PlanOrgAppsAdminOptions {
+    /** The host can store a secret under a ref (`deliverSecret`). Default true. */
+    canHoldSecrets?: boolean;
+}
+/**
+ * Pure. Plans `coolify:org-apps-admin` once, after the company's Postgres server is recorded
+ * (platform-step rule 2: blocked, not failing, while it is not). A lost mint -- an undelivered id
+ * with no done guard -- is reported blocked and never minted again (rule 1); the operator clears the
+ * recorded id once the role is confirmed gone from the server.
+ */
+export declare function planOrgAppsAdminStep(org: Pick<DeclaredOrg, 'id' | 'slug'>, recordedIds: Readonly<Record<string, string>>, options?: PlanOrgAppsAdminOptions): {
+    step: DraftStep | null;
+    blocked: string | null;
+};
+export interface PlanAppsAdminOptions {
+    canHoldSecrets: boolean;
+    /** `coolify:org-postgres` is planned in this same plan, ahead of this step. */
+    postgresPlanned: boolean;
+}
+/**
+ * Pure. F4 (#925): the wiring of {@link planOrgAppsAdminStep} to `org.boule.apps`. Apps on: the mint
+ * step, once Boule (which receives the URL) and the Postgres server are recorded or planned. Apps off with
+ * the role recorded (or a mint never delivered): the retire step, which needs no secret and drops nothing.
+ */
+export declare function planAppsAdmin(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], options: PlanAppsAdminOptions): {
+    steps: DraftStep[];
+    blocked: Array<{
+        description: string;
+        key: string;
+    }>;
+};
+/**
+ * The job's script: makes the role (idempotent, kept if it already exists), sets its password and grants
+ * it CONNECT on `postgres`. It revokes nothing from PUBLIC (see the file comment). Roles are made by
+ * `format('%I')` and the password by `format('%L')`, so no value is spliced into SQL by the shell. Setting
+ * the password again is harmless, so a mint that is repeated simply replaces it. It never prints a URL or a password: psql's output is discarded and the one
+ * error line names neither.
+ */
+export declare function orgAppsAdminScript(role: string, mode?: 'mint' | 'retire'): string[];
+/** The job: the same pinned image as the other Postgres jobs, so `psql` matches the server's major version. */
+export declare function orgAppsAdminDockerfile(role: string, mode?: 'mint' | 'retire'): string;
+type AppsAdminCoolify = Pick<CoolifyPort, 'findOrCreateEnvironment' | 'findApplicationByName' | 'getApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'deploy' | 'raw'>;
+/** Everything the step takes from the executor. New ones go here, never as positional arguments. */
+export interface OrgAppsAdminDeps {
+    coolify: AppsAdminCoolify;
+    ensureProject(): Promise<string>;
+    serverUuid(): Promise<string>;
+    /** Starts the company's Postgres server when it is not running and returns its live record. */
+    startDatabase(uuid: string): Promise<{
+        internal_db_url?: string;
+        status?: string;
+    }>;
+    deliverSecret(ref: string, secret: string): Promise<void>;
+    /** Registers a value for redaction. */
+    onSecret?(value: string): void;
+    /** Test seam: a password. Default: 24 random bytes, base64url. */
+    mintPassword?(): string;
+    /** Test seam: an opaque id. */
+    mintId?(): string;
+    runtime?: JobRuntime;
+}
+/**
+ * Makes the role true and delivers its connection URL. The password is minted in memory. The opaque id
+ * {@link ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY} is recorded and persisted only once the job that sets the
+ * password is about to be deployed ("password minted and role touched"); a failure before that leaves no
+ * id and the next apply simply retries, since setting a password again is harmless. The done guard is
+ * recorded only once the URL is delivered. A run that dies between the two finds the id and stops (the
+ * planner reports it blocked); retiring the role (apps off) clears it.
+ */
+export declare function provisionOrgAppsAdmin(scope: StepScope, deps: OrgAppsAdminDeps, org: DeclaredOrg): Promise<void>;
+/** What the retire form takes from the executor: the mint form's deps, and the held-key blanking. */
+export interface RetireOrgAppsAdminDeps extends Omit<OrgAppsAdminDeps, 'deliverSecret'> {
+    /** Blanks the held URL (the store has no delete: an empty value reads as not held). */
+    clearHeldUrl(ref: string): Promise<void>;
+    /** Takes `APPS_DATABASE_ADMIN_URL` out of Boule's env. A row already gone is not an error. */
+    removeBouleEnv(): Promise<void>;
+}
+/**
+ * Apps went off (F4, #925): the role stops logging in, the URL leaves Boule's env and the held store,
+ * and the recorded ids are cleared last so a failed run repeats. Never drops the role, a database or
+ * a role an app made (CLAUDE.md: never drop data); turning apps on again mints a new password for the
+ * same role. A recorded mint that was never delivered is retired the same way, which is also how an
+ * operator unblocks a lost mint. The job needs the server's admin URL and nothing else secret.
+ */
+export declare function retireOrgAppsAdmin(scope: StepScope, deps: RetireOrgAppsAdminDeps, org: DeclaredOrg): Promise<void>;
+export {};

package/dist/plan/org-apps-admin.js

@@ -0,0 +1,434 @@
+import { randomBytes } from 'node:crypto';
+import { pinnedRef } from '../bootstrap/versions.js';
+import { ORG_POSTGRES_SERVER_SCOPE_KEY, appsOn } from '../org.js';
+import { JobFailure, waitForJob } from './job-app.js';
+import { orgPostgresServerName } from './org-postgres.js';
+import { boundedCall, withCallTimeout } from './signin-db.js';
+/**
+ * estate#210: a narrow role on the company's one Postgres server (`org-postgres.ts`) that Boule uses
+ * to create a database per app copy itself -- `LOGIN CREATEDB CREATEROLE` only, never superuser,
+ * never able to touch another role's data or database (estate#215, tested on Postgres 16.15). Its
+ * connection URL is the one credential Boule is handed; it never sees the server's own admin URL.
+ *
+ * This step does NOT touch CONNECT on any database. `org-postgres-job.ts` deliberately leaves CONNECT open
+ * on PUBLIC (a template app creates its own runtime role on first boot and relies on it), so a server-wide
+ * `REVOKE CONNECT ... FROM PUBLIC` here would lock out every existing home. Isolation between app databases
+ * is done by Boule instead (contract with the Boule builder): on each `app_*` database it creates, Boule
+ * revokes CONNECT from PUBLIC and grants it to that database's own role only. The admin role holds CONNECT
+ * on `postgres` alone.
+ *
+ * Wired by F4 (#925): the step is planned only for a company whose Boule runs apps (`appsOn`,
+ * `org.boule.apps`), after the company's Postgres server and Boule are recorded or planned. The URL is
+ * held at {@link appsAdminUrlRef} and written to Boule's env as `APPS_DATABASE_ADMIN_URL`. Turning apps
+ * off plans the retire form ({@link retireOrgAppsAdmin}): the env row goes, the held URL is blanked, and
+ * the role is set NOLOGIN and its sessions ended. Nothing is dropped: the role, the `app_*` databases
+ * and their roles stay, so turning apps on again mints a new password for the same role.
+ */
+const NAME = /^[a-z][a-z0-9_]{0,62}$/;
+function checked(name) {
+    if (!NAME.test(name))
+        throw new Error(`Postgres name is not valid: ${name}`);
+    return name;
+}
+/** The role's name on the server: the org's slug plus `_apps_admin`. */
+export const appsAdminRoleName = (org) => `${org.slug}_apps_admin`;
+/** The job app's name in Coolify. */
+export const appsAdminJobName = (org) => `${org.slug}-apps-admin-job`;
+/** Recorded once the role is made, its password set, and the URL delivered. */
+export const ORG_APPS_ADMIN_SCOPE_KEY = 'org_apps_admin';
+/**
+ * An opaque id, set once the password is minted and the job that sets it is about to run, until the URL is
+ * delivered. Never the password. A failure before that point leaves no id, so the next apply tries again.
+ */
+export const ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY = 'org_apps_admin_undelivered';
+/** The job app's id while it exists. */
+export const ORG_APPS_ADMIN_JOB_APP_SCOPE_KEY = 'org_apps_admin_job_app';
+/** Where the host holds the role's connection URL, once delivered -- `deliverSecret`'s own naming convention. */
+export const appsAdminUrlRef = (org) => `org-apps-admin:${org.slug}:adminUrl`;
+/** How many times the URL is handed to `deliverSecret`. */
+export const ORG_APPS_ADMIN_DELIVERY_ATTEMPTS = 3;
+/**
+ * Pure. Plans `coolify:org-apps-admin` once, after the company's Postgres server is recorded
+ * (platform-step rule 2: blocked, not failing, while it is not). A lost mint -- an undelivered id
+ * with no done guard -- is reported blocked and never minted again (rule 1); the operator clears the
+ * recorded id once the role is confirmed gone from the server.
+ */
+export function planOrgAppsAdminStep(org, recordedIds, options = {}) {
+    if (recordedIds[ORG_APPS_ADMIN_SCOPE_KEY])
+        return { step: null, blocked: null };
+    if (!recordedIds[ORG_POSTGRES_SERVER_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s apps admin role is blocked, not planned: its Postgres server is not provisioned yet`,
+        };
+    }
+    const lost = recordedIds[ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY];
+    if (lost) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s apps admin role (note ${lost}): a run set a new password on the role but its connection URL was never saved. Nothing is lost. To start over, turn apps off and apply (that retires the role and clears this note), then turn apps on again`,
+        };
+    }
+    if (options.canHoldSecrets === false) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s apps admin role is blocked, not planned: the host cannot hold secrets`,
+        };
+    }
+    return {
+        step: {
+            action: { system: 'coolify', kind: 'org-apps-admin', key: org.id, desired: {} },
+            step: {
+                description: `mint ${org.slug}'s database admin role (${appsAdminRoleName(org)}); it can create databases and roles but touches no existing database`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
+/**
+ * Pure. F4 (#925): the wiring of {@link planOrgAppsAdminStep} to `org.boule.apps`. Apps on: the mint
+ * step, once Boule (which receives the URL) and the Postgres server are recorded or planned. Apps off with
+ * the role recorded (or a mint never delivered): the retire step, which needs no secret and drops nothing.
+ */
+export function planAppsAdmin(org, recordedIds, plannedSteps, options) {
+    const key = `coolify:org-apps-admin:${org.id}`;
+    const blocked = [];
+    if (!appsOn(org)) {
+        if (!recordedIds[ORG_APPS_ADMIN_SCOPE_KEY] &&
+            !recordedIds[ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY]) {
+            return { steps: [], blocked };
+        }
+        if (!recordedIds[ORG_POSTGRES_SERVER_SCOPE_KEY]) {
+            blocked.push({
+                description: `${org.slug}'s apps admin role is not retired, not planned: its Postgres server is not recorded`,
+                key,
+            });
+            return { steps: [], blocked };
+        }
+        return {
+            steps: [
+                {
+                    action: {
+                        system: 'coolify',
+                        kind: 'org-apps-admin',
+                        key: org.id,
+                        desired: { mode: 'retire' },
+                    },
+                    step: {
+                        description: `retire ${org.slug}'s database admin role (${appsAdminRoleName(org)}): no login, out of Boule's env; no database is dropped`,
+                        destroys: true,
+                        migrates: false,
+                    },
+                },
+            ],
+            blocked,
+        };
+    }
+    const bouleReady = Boolean(recordedIds[`coolify:boule:${org.id}`]) ||
+        plannedSteps.some((p) => p.action.system === 'coolify' && p.action.kind === 'boule' && p.action.key === org.id);
+    if (!bouleReady && !recordedIds[ORG_APPS_ADMIN_SCOPE_KEY]) {
+        blocked.push({
+            description: `${org.slug}'s apps admin role is blocked, not planned: Boule is not recorded yet`,
+            key,
+        });
+        return { steps: [], blocked };
+    }
+    const seen = options.postgresPlanned && !recordedIds[ORG_POSTGRES_SERVER_SCOPE_KEY]
+        ? { ...recordedIds, [ORG_POSTGRES_SERVER_SCOPE_KEY]: 'planned' }
+        : recordedIds;
+    const planned = planOrgAppsAdminStep(org, seen, { canHoldSecrets: options.canHoldSecrets });
+    if (planned.blocked)
+        blocked.push({ description: planned.blocked, key });
+    return { steps: planned.step ? [planned.step] : [], blocked };
+}
+/**
+ * The job's script: makes the role (idempotent, kept if it already exists), sets its password and grants
+ * it CONNECT on `postgres`. It revokes nothing from PUBLIC (see the file comment). Roles are made by
+ * `format('%I')` and the password by `format('%L')`, so no value is spliced into SQL by the shell. Setting
+ * the password again is harmless, so a mint that is repeated simply replaces it. It never prints a URL or a password: psql's output is discarded and the one
+ * error line names neither.
+ */
+export function orgAppsAdminScript(role, mode = 'mint') {
+    const owner = checked(role);
+    if (mode === 'retire')
+        return orgAppsAdminRetireScript(owner);
+    const JOB_DONE_FILE = '/tmp/done';
+    const JOB_FAILED_FILE = '/tmp/failed';
+    return [
+        '#!/bin/sh',
+        'set -eu',
+        `trap '[ -f ${JOB_DONE_FILE} ] || touch ${JOB_FAILED_FILE}' EXIT`,
+        "trap 'exit 1' HUP INT TERM",
+        `[ ! -f ${JOB_FAILED_FILE} ] || exit 1`,
+        `rm -f ${JOB_DONE_FILE}`,
+        'fail() { echo "org-apps-admin: $1 failed"; exit 1; }',
+        '[ -n "${PW:-}" ] || fail "role"',
+        'psql "$ADMIN_DATABASE_URL" -X -q -v ON_ERROR_STOP=1 > /dev/null 2>&1 <<\'SQL\' || fail "role"',
+        `\\set role '${owner}'`,
+        '\\getenv pw PW',
+        "SELECT format('CREATE ROLE %I LOGIN CREATEDB CREATEROLE', :'role') WHERE NOT EXISTS (SELECT FROM pg_roles WHERE rolname = :'role') \\gexec",
+        "SELECT format('ALTER ROLE %I LOGIN CREATEDB CREATEROLE PASSWORD %L', :'role', :'pw') \\gexec",
+        "SELECT format('GRANT CONNECT ON DATABASE postgres TO %I', :'role') \\gexec",
+        'SQL',
+        'echo "org-apps-admin: role ready"',
+        `touch ${JOB_DONE_FILE}`,
+        'exec sleep infinity',
+    ];
+}
+/**
+ * The retire script: the role stops being able to log in and its open sessions end. It drops nothing and
+ * grants nothing; CONNECT stays closed to PUBLIC. A role that is not there is left alone.
+ */
+function orgAppsAdminRetireScript(owner) {
+    const JOB_DONE_FILE = '/tmp/done';
+    const JOB_FAILED_FILE = '/tmp/failed';
+    return [
+        '#!/bin/sh',
+        'set -eu',
+        `trap '[ -f ${JOB_DONE_FILE} ] || touch ${JOB_FAILED_FILE}' EXIT`,
+        "trap 'exit 1' HUP INT TERM",
+        `[ ! -f ${JOB_FAILED_FILE} ] || exit 1`,
+        `rm -f ${JOB_DONE_FILE}`,
+        'fail() { echo "org-apps-admin: $1 failed"; exit 1; }',
+        'psql "$ADMIN_DATABASE_URL" -X -q -v ON_ERROR_STOP=1 > /dev/null 2>&1 <<\'SQL\' || fail "retire"',
+        `\\set role '${owner}'`,
+        "SELECT format('ALTER ROLE %I NOLOGIN', :'role') WHERE EXISTS (SELECT FROM pg_roles WHERE rolname = :'role') \\gexec",
+        "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE usename = :'role'",
+        'SQL',
+        'echo "org-apps-admin: role retired"',
+        `touch ${JOB_DONE_FILE}`,
+        'exec sleep infinity',
+    ];
+}
+/** The job: the same pinned image as the other Postgres jobs, so `psql` matches the server's major version. */
+export function orgAppsAdminDockerfile(role, mode = 'mint') {
+    const encoded = Buffer.from(`${orgAppsAdminScript(role, mode).join('\n')}\n`, 'utf8').toString('base64');
+    return [
+        `FROM postgres:${pinnedRef('postgres')}`,
+        `RUN echo '${encoded}' | base64 -d > /usr/local/bin/org-apps-admin && chmod 0755 /usr/local/bin/org-apps-admin`,
+        'ENTRYPOINT ["/usr/local/bin/org-apps-admin"]',
+        `HEALTHCHECK --interval=10s --timeout=5s --start-period=10s --retries=1 CMD ["test", "-f", "/tmp/done"]`,
+    ].join('\n');
+}
+const mint = () => randomBytes(24).toString('base64url');
+const mintOpaque = () => randomBytes(12).toString('hex');
+/**
+ * Makes the role true and delivers its connection URL. The password is minted in memory. The opaque id
+ * {@link ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY} is recorded and persisted only once the job that sets the
+ * password is about to be deployed ("password minted and role touched"); a failure before that leaves no
+ * id and the next apply simply retries, since setting a password again is harmless. The done guard is
+ * recorded only once the URL is delivered. A run that dies between the two finds the id and stops (the
+ * planner reports it blocked); retiring the role (apps off) clears it.
+ */
+export async function provisionOrgAppsAdmin(scope, deps, org) {
+    const label = `${org.slug}'s apps admin role`;
+    const coolify = withCallTimeout(deps.coolify);
+    const recorded = scope.recordedIds();
+    if (recorded[ORG_APPS_ADMIN_SCOPE_KEY])
+        return;
+    const serverId = recorded[ORG_POSTGRES_SERVER_SCOPE_KEY];
+    if (!serverId)
+        throw new Error(`${label}: the Postgres server is not recorded yet`);
+    if (recorded[ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY]) {
+        throw new Error(`${label}: an earlier run set a new password on the role but never saved its connection URL. Nothing is lost. To start over, turn apps off and apply (that retires the role and clears this note), then turn apps on again`);
+    }
+    const onSecret = (value) => deps.onSecret?.(value);
+    const server = await boundedCall(deps.startDatabase(serverId), 'Coolify startDatabase');
+    if (!server.internal_db_url || !URL.canParse(server.internal_db_url)) {
+        throw new Error(`${label}: the Postgres server has no usable internal URL`);
+    }
+    const adminUrl = server.internal_db_url;
+    onSecret(adminUrl);
+    const adminParsed = new URL(adminUrl);
+    const host = adminParsed.hostname;
+    const port = adminParsed.port || '5432';
+    if (!host)
+        throw new Error(`${label}: the Postgres server's internal URL has no host`);
+    const adminPassword = decodeURIComponent(adminParsed.password);
+    if (adminPassword)
+        onSecret(adminPassword);
+    const role = appsAdminRoleName(org);
+    const password = (deps.mintPassword ?? mint)();
+    onSecret(password);
+    const jobName = appsAdminJobName(org);
+    let jobAppId;
+    try {
+        const projectUuid = await deps.ensureProject();
+        const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const leftover = await coolify.findApplicationByName(jobName, {
+            environmentIds: [environment.id],
+        });
+        if (leftover)
+            await coolify.raw('DELETE', `/applications/${leftover.uuid}`);
+        const created = await coolify.createDockerfileApplication({
+            project_uuid: projectUuid,
+            server_uuid: await deps.serverUuid(),
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            dockerfile: orgAppsAdminDockerfile(role),
+            name: jobName,
+            description: `${org.slug}'s apps admin role job`,
+            instant_deploy: false,
+            autogenerate_domain: false,
+        });
+        jobAppId = created.uuid;
+        scope.recordScopeId(ORG_APPS_ADMIN_JOB_APP_SCOPE_KEY, jobAppId);
+        await scope.persist();
+        await coolify.updateApplication(jobAppId, { health_check_enabled: false });
+        await coolify.bulkUpsertEnvs(jobAppId, [
+            { key: 'ADMIN_DATABASE_URL', value: adminUrl },
+            { key: 'PW', value: password },
+        ]);
+        // From here the job can set the password: the marker is recorded now, not earlier.
+        scope.recordScopeId(ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY, (deps.mintId ?? mintOpaque)());
+        await scope.persist();
+        await coolify.deploy(jobAppId, true);
+        await waitForJob(coolify, jobAppId, deps.runtime ?? {}, {
+            job: 'the apps admin job',
+            stopped: 'the apps admin job stopped before it finished',
+        });
+    }
+    catch (error) {
+        const why = error instanceof JobFailure ? error.message : 'a Coolify call failed or timed out';
+        let cleaned = '';
+        if (jobAppId) {
+            const id = jobAppId;
+            try {
+                await boundedCall(coolify.raw('POST', `/applications/${id}/stop`), 'stop the job');
+            }
+            catch {
+                cleaned += '; the job app could not be stopped, stop it in Coolify';
+            }
+            try {
+                await boundedCall(coolify.bulkUpsertEnvs(id, [
+                    { key: 'ADMIN_DATABASE_URL', value: '' },
+                    { key: 'PW', value: '' },
+                ]), 'clear the job env');
+            }
+            catch {
+                cleaned +=
+                    '; its env could not be cleared, delete the app in Coolify (it holds the admin URL)';
+            }
+        }
+        throw new Error(`${label}: ${why}${jobAppId ? `; the job app ${jobAppId} is left stopped without secrets for inspection and the next apply replaces it${cleaned}` : ''}; apply again`);
+    }
+    try {
+        await coolify.raw('DELETE', `/applications/${jobAppId}`);
+    }
+    catch {
+        throw new Error(`${label}: the role was made, but its job app ${jobAppId} could not be deleted; delete it in Coolify (it holds the admin URL), then apply again`);
+    }
+    const url = `postgres://${encodeURIComponent(role)}:${encodeURIComponent(password)}@${host}:${port}/postgres`;
+    onSecret(url);
+    let delivered = false;
+    for (let attempt = 1; attempt <= ORG_APPS_ADMIN_DELIVERY_ATTEMPTS && !delivered; attempt++) {
+        try {
+            await boundedCall(deps.deliverSecret(appsAdminUrlRef(org), url), 'deliverSecret');
+            delivered = true;
+        }
+        catch {
+            // Retried; the cause may echo the secret and is dropped.
+        }
+    }
+    if (!delivered) {
+        throw new Error(`${label}: the role was made, but its connection URL could not be saved after ${ORG_APPS_ADMIN_DELIVERY_ATTEMPTS} attempts. Nothing is lost. Turn apps off and apply (that retires the role and clears the note), then turn apps on again`);
+    }
+    scope.recordScopeId(ORG_APPS_ADMIN_SCOPE_KEY, orgPostgresServerName(org));
+    scope.recordScopeId(ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY, '');
+    await scope.persist();
+    scope.recordScopeId(ORG_APPS_ADMIN_JOB_APP_SCOPE_KEY, '');
+}
+/**
+ * Apps went off (F4, #925): the role stops logging in, the URL leaves Boule's env and the held store,
+ * and the recorded ids are cleared last so a failed run repeats. Never drops the role, a database or
+ * a role an app made (CLAUDE.md: never drop data); turning apps on again mints a new password for the
+ * same role. A recorded mint that was never delivered is retired the same way, which is also how an
+ * operator unblocks a lost mint. The job needs the server's admin URL and nothing else secret.
+ */
+export async function retireOrgAppsAdmin(scope, deps, org) {
+    const label = `${org.slug}'s apps admin role`;
+    const coolify = withCallTimeout(deps.coolify);
+    const recorded = scope.recordedIds();
+    const serverId = recorded[ORG_POSTGRES_SERVER_SCOPE_KEY];
+    const hadRole = Boolean(recorded[ORG_APPS_ADMIN_SCOPE_KEY] || recorded[ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY]);
+    if (hadRole) {
+        if (!serverId)
+            throw new Error(`${label}: the Postgres server is not recorded; cannot retire it`);
+        const onSecret = (value) => deps.onSecret?.(value);
+        const server = await boundedCall(deps.startDatabase(serverId), 'Coolify startDatabase');
+        if (!server.internal_db_url || !URL.canParse(server.internal_db_url)) {
+            throw new Error(`${label}: the Postgres server has no usable internal URL`);
+        }
+        onSecret(server.internal_db_url);
+        const password = decodeURIComponent(new URL(server.internal_db_url).password);
+        if (password)
+            onSecret(password);
+        const jobName = appsAdminJobName(org);
+        let jobAppId;
+        try {
+            const projectUuid = await deps.ensureProject();
+            const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+            const leftover = await coolify.findApplicationByName(jobName, {
+                environmentIds: [environment.id],
+            });
+            if (leftover)
+                await coolify.raw('DELETE', `/applications/${leftover.uuid}`);
+            const created = await coolify.createDockerfileApplication({
+                project_uuid: projectUuid,
+                server_uuid: await deps.serverUuid(),
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                dockerfile: orgAppsAdminDockerfile(appsAdminRoleName(org), 'retire'),
+                name: jobName,
+                description: `${org.slug}'s apps admin role retire job`,
+                instant_deploy: false,
+                autogenerate_domain: false,
+            });
+            jobAppId = created.uuid;
+            scope.recordScopeId(ORG_APPS_ADMIN_JOB_APP_SCOPE_KEY, jobAppId);
+            await scope.persist();
+            await coolify.updateApplication(jobAppId, { health_check_enabled: false });
+            await coolify.bulkUpsertEnvs(jobAppId, [
+                { key: 'ADMIN_DATABASE_URL', value: server.internal_db_url },
+            ]);
+            await coolify.deploy(jobAppId, true);
+            await waitForJob(coolify, jobAppId, deps.runtime ?? {}, {
+                job: 'the apps admin retire job',
+                stopped: 'the apps admin retire job stopped before it finished',
+            });
+        }
+        catch (error) {
+            const why = error instanceof JobFailure ? error.message : 'a Coolify call failed or timed out';
+            let cleaned = '';
+            if (jobAppId) {
+                const id = jobAppId;
+                try {
+                    await boundedCall(coolify.raw('POST', `/applications/${id}/stop`), 'stop the job');
+                    await boundedCall(coolify.bulkUpsertEnvs(id, [{ key: 'ADMIN_DATABASE_URL', value: '' }]), 'clear the job env');
+                }
+                catch {
+                    cleaned = '; delete the job app in Coolify (it holds the admin URL)';
+                }
+            }
+            throw new Error(`${label}: ${why}${cleaned}; apply again`);
+        }
+        try {
+            await coolify.raw('DELETE', `/applications/${jobAppId}`);
+        }
+        catch {
+            throw new Error(`${label}: the role was retired, but its job app ${jobAppId} could not be deleted; delete it in Coolify (it holds the admin URL), then apply again`);
+        }
+    }
+    await deps.removeBouleEnv();
+    await deps.clearHeldUrl(appsAdminUrlRef(org));
+    for (const key of [
+        ORG_APPS_ADMIN_SCOPE_KEY,
+        ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY,
+        ORG_APPS_ADMIN_JOB_APP_SCOPE_KEY,
+    ]) {
+        scope.recordScopeId(key, '');
+    }
+    await scope.persist();
+}

package/dist/plan/org-names.d.ts

@@ -6,13 +6,13 @@ export type OrgNameSource = 'own' | 'hosting';
  * hosting entries: Agora, Boule, the tunnel and its connector, and chat,
  * calls and the cms site while they are on.
  */
-export declare function companyServiceNames(org: Pick<DeclaredOrg, 'slug' | 'chat' | 'calls' | 'site'>): string[];
+export declare function companyServiceNames(org: Pick<DeclaredOrg, 'slug' | 'chat' | 'calls' | 'site' | 'kosmos'>): string[];
 /**
  * Every container name, network alias, database, tunnel and bucket name that
  * foundry derives for an org: its own-service names when it owns services,
  * and its hosting-entry and database names.
  */
-export declare function orgDerivedNames(org: Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site'>): {
+export declare function orgDerivedNames(org: Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site' | 'kosmos'>): {
     name: string;
     source: OrgNameSource;
 }[];
@@ -26,5 +26,5 @@ export interface NameClash {
     source: OrgNameSource;
 }
 /** Every name `org` derives that another org or the platform also derives. */
-export declare function findNameClashes(org: Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site'>, others: readonly Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site'>[]): NameClash[];
+export declare function findNameClashes(org: Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site' | 'kosmos'>, others: readonly Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site' | 'kosmos'>[]): NameClash[];
 export declare function nameClashMessage(slug: string, clash: NameClash): string;

package/dist/plan/org-names.js

@@ -1,7 +1,7 @@
-import { ownsServices } from '../org.js';
+import { kosmosOn, ownsServices } from '../org.js';
 import { entryHasDatabase } from '../worker-app-config.js';
 import { chatInternalNames, chatRekeyedInternalNames } from './chat-matrix.js';
-import { workerAppHostname } from './hostnames.js';
+import { workerAppHostname, workspaceHost, workspaceInboxHost } from './hostnames.js';
 import { orgTarget, platformTarget } from './own-services.js';
 import { appNameFor } from './platform-diff.js';
 /**
@@ -20,6 +20,8 @@ export function companyServiceNames(org) {
         `${s}-tunnel`,
         `${s}-cloudflared`,
     ];
+    if (kosmosOn(org))
+        names.push(`${s}-kosmos`, `${s}-kosmos-db`);
     if (org.chat?.enabled) {
         names.push(...Object.values(chatInternalNames(s)), ...Object.values(chatRekeyedInternalNames(s)));
     }
@@ -61,6 +63,17 @@ export function orgDerivedNames(org) {
     if (org.hosting.entries.some(entryHasDatabase)) {
         names.push({ name: `${org.slug}-db`, source: 'hosting' });
     }
+    // A workspace's host and the test inbox's: one label under one zone, so it is compared across orgs like the names above.
+    if (org.hosting.enabled) {
+        for (const entry of org.hosting.entries) {
+            if (entry.workspace) {
+                names.push({ name: workspaceHost(org.slug, entry.key), source: 'hosting' });
+            }
+        }
+        if (org.hosting.entries.some((e) => e.workspace && !e.workerApp)) {
+            names.push({ name: workspaceInboxHost(org.slug), source: 'hosting' });
+        }
+    }
     return names;
 }
 /** Names the platform's own steps give apps, tunnels, connectors, databases and projects outside `platformTarget()`. */

package/dist/plan/org-postgres-migrate.js

@@ -64,6 +64,7 @@ export function parseMigrationConfirmation(raw) {
 const MIGRATION_ORDER = [
     'app',
     'cms',
+    'kosmos',
     'boule',
     'chat_service',
     'calls_service',

package/dist/plan/own-diff.d.ts

@@ -24,6 +24,29 @@ export declare function planOwnJobs(options: PlanOwnJobsOptions): {
     step: DraftStep | null;
     blocked: string | null;
 };
+/** `unmanaged` key of the one line `planOwnJobsRoute` reports. */
+export declare const OWN_JOBS_ROUTE_BLOCKED_KEY = "own-jobs-route";
+export interface PlanOwnJobsRouteOptions {
+    org: DeclaredOrg;
+    recordedIds: Readonly<Record<string, string>>;
+    readiness: OrgPlatformReadiness;
+    /** The executor was built with an `ownServices` port. */
+    ownServices: boolean;
+    /** The org's zone is live and active: none is planned and none is waiting. */
+    zoneActive: boolean;
+    /** The org's own scheduler step is planned in this same plan, so its address is recorded by the time the route runs. */
+    schedulerPlanned: boolean;
+}
+/**
+ * The public route of an own org's jobs scheduler: `jobs.<domain>`, serving only what an app calls. The
+ * owner company always publishes its scheduler, since every company on shared services registers there; any
+ * other own org publishes its own only while an entry declares `uses.jobs`. Planned again when the hostname
+ * moved. Every blocked line is fixed text: it is part of the stale-plan comparison.
+ */
+export declare function planOwnJobsRoute(options: PlanOwnJobsRouteOptions): {
+    step: DraftStep | null;
+    blocked: string | null;
+};
 /** `unmanaged` key of the one line `planOwnAuth` reports. */
 export declare const OWN_AUTH_BLOCKED_KEY = "own-auth";
 export { OWN_AUTH_APPLIED_HOSTNAME_SCOPE_KEY };