@wtfalch/foundry 0.9.0 → 0.11.0

package/dist/plan/executor.js

@@ -1,13 +1,17 @@
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { URL } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
 import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
 import { APP_ENTRY_KEY, appEntry } from '../org.js';
-import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, agoraHostnameFor, desiredAgoraEnv, } from './agora.js';
+import { adoptedAppPatch, adoptedConnectorKey, adoptedPatchDetails, adoptedResources, adoptedTunnelKey, adoptionVaultRef, declaredAdoptUuids, foreignRoutes, isActiveSnapshot, mergeIngress, normalizeHostname, protectsKey, removedNames, replacedNames, restoreAppPatch, restoreIngress, snapshotAppSettings, } from './adopt.js';
+import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, agoraHostnameFor, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
+import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { MAS_IMAGE, MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
-import { ensureCloudflaredConnector } from './cloudflared-connector.js';
+import { ensureCloudflaredConnector, } from './cloudflared-connector.js';
+import { appHostname, entryHostnames, tunnelDnsHostnames, tunnelIngressHostnames, } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY, loginBindingState, loginHostClientIds, pendingRemovalHosts, pendingRemovalState, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
-import { APP_ENV_APPLIED_SCOPE_KEY, CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, DB_ENV_APPLIED_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appStepKey, resolveAppEnv, } from './platform-diff.js';
+import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appDeployPendingScopeKey, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, } from './platform-diff.js';
 /**
  * #274 fix round 4: bridges `@wtfalch/providers`' real `ZitadelClient.
  * listApps` -- a plain array, with no `loginBaseUri` or completeness signal
@@ -48,25 +52,6 @@ export class NotBuiltError extends Error {
 // ---------------------------------------------------------------------------
 // Hostnames
 // ---------------------------------------------------------------------------
-/**
- * The Coolify name of a hosting entry's app: `<slug>` for the `app` entry, so
- * the move to a list finds the app that runs today, `<slug>-<key>` for any
- * other.
- */
-function appNameFor(org, entry) {
-    return entry.key === APP_ENTRY_KEY ? org.slug : `${org.slug}-${entry.key}`;
-}
-/**
- * `<slug>.oikos.host` (`../slug.ts`), or `DeclaredOrg.domain` once
- * `hosting.usesDomain` is true — the same rule `diff.ts`'s `planApp` and
- * `planSite` document, reused here for the org's own hosted app, its
- * Cloudflare tunnel ingress and its ZITADEL issuer apps' redirect URIs
- * (task brief: "Hostnames: `<slug>.oikos.host` ... or `DeclaredOrg.domain`
- * when `hosting.usesDomain`").
- */
-function hostnameFor(org) {
-    return org.hosting.usesDomain && org.domain ? org.domain : `${org.slug}.oikos.host`;
-}
 /**
  * #274 fix round 3 point 4: `zitadelLoginHost`'s own comparison between a
  * live app's ZITADEL-reported login base URI and the one this step itself
@@ -104,36 +89,6 @@ function callsHostnameFor(org) {
         ? `calls.${org.domain}`
         : `${org.slug}-calls.oikos.host`;
 }
-/**
- * The hostnames `cloudflareTunnel` routes to `COOLIFY_PROXY_ORIGIN`
- * (https://github.com/wtfalch/foundry/issues/115). A site-enabled org
- * (`org.ts`'s `SiteConfig.enabled`) has no single app hostname to reuse -- it
- * needs both its public site at `org.domain` and its cms studio (the sign-in
- * and editing surface, `@wtfalch/cms`) at `cms.<domain>`, so both are named
- * here; `org.domain` is non-null in that branch, guaranteed by `org.ts`'s
- * `validateSite` ("site.enabled requires domain"). Every other org --
- * concretely a hosting org, whose one app hostname this served before #115
- * ever existed -- keeps exactly the prior single-hostname behavior
- * ({@link hostnameFor}), unchanged.
- *
- * #145: an own-domain calls service adds `calls.<domain>` on top of whichever
- * of those a site/hosting org already gets, since calls can run alongside
- * either (or neither).
- */
-function tunnelIngressHostnames(org) {
-    const hostnames = org.site.enabled && org.domain ? [org.domain, `cms.${org.domain}`] : [hostnameFor(org)];
-    if (org.calls.enabled && org.calls.usesDomain && org.domain) {
-        hostnames.push(`calls.${org.domain}`);
-    }
-    // #164: Agora always moves onto `agora.<domain>` once `org.domain` is set
-    // -- no toggle to gate this on. A level-1 org (no domain) adds nothing
-    // here: `<slug>-agora.oikos.host` rides the shared `*.oikos.host` wildcard
-    // tunnel (`scripts/shared-ingress.mjs`), not a per-org tunnel.
-    if (org.domain) {
-        hostnames.push(agoraHostnameFor(org));
-    }
-    return hostnames;
-}
 /**
  * The health URLs an outside prober should call for this org (#43): one per
  * app foundry runs for it. A hosting org's app answers at its own hostname,
@@ -143,8 +98,17 @@ function tunnelIngressHostnames(org) {
  * this file's hostname rules.
  */
 export function healthUrls(org) {
-    if (org.hosting.enabled)
-        return [`https://${hostnameFor(org)}/api/health`];
+    // One URL per entry that has a public name; an internal entry has none.
+    if (org.hosting.enabled && appEntry(org.hosting)) {
+        return org.hosting.entries.flatMap((entry) => {
+            const [hostname] = entryHostnames(org, entry);
+            if (!hostname)
+                return [];
+            return [
+                `https://${hostname}${entry.healthPath ?? (entry.buildPack === 'static' ? '/' : '/api/health')}`,
+            ];
+        });
+    }
     if (org.site.enabled && org.domain) {
         return [`https://${org.domain}/api/health`, `https://${cmsHostnameFor(org)}/api/health`];
     }
@@ -166,7 +130,7 @@ function mailOrgFor(org, usesDomain, mode) {
 /**
  * Every app on the Coolify box shares one Traefik reverse proxy, and Coolify
  * itself points that proxy's routing at whatever `domains` an application
- * declares (`coolifyApp`'s `hostnameFor(org)`) -- so a tunnel's ingress only
+ * declares (`coolifyApp`'s `appHostname(org)`) -- so a tunnel's ingress only
  * has to reach the proxy, never a specific app container.
  * `wtfalch/app-template`'s bootstrap (`bootstrap/steps/cf-tunnel.ts`, prior
  * art for the exact org this file's `cloudflareTunnel` implements, cited by
@@ -331,6 +295,34 @@ const CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY = 'cloudflare_tunnel_connector_a
  * already follows.
  */
 const CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY = 'cloudflare_tunnel_dns_domain';
+/**
+ * #312: the ingress hostnames foundry wrote on an adopted tunnel, kept in the
+ * tunnel row's `settings.written` for the life of the snapshot, so foundry's
+ * routes are told from a person's by this record, never by guessing. A name is
+ * added only after the write that carried it succeeded: a crash in between
+ * leaves a route taken as foreign and kept.
+ */
+function writtenIngressNames(row) {
+    const written = row?.settings.written;
+    return new Set(Array.isArray(written) ? written.filter((n) => typeof n === 'string') : []);
+}
+/** The names the row says a put may have carried (`writing`): restore treats one as written if its live route is exactly foundry's. */
+function writingIngressNames(row) {
+    const writing = row?.settings.writing;
+    return Array.isArray(writing) ? writing.filter((n) => typeof n === 'string') : [];
+}
+/** {@link CreatedDnsRecord}s of the tunnel row's `settings`, ignoring any entry of another shape. */
+function createdDnsRecords(settings) {
+    const list = settings?.dnsRecords;
+    return (Array.isArray(list) ? list : []).filter((r) => typeof r?.zoneId === 'string' && typeof r?.id === 'string' && typeof r?.hostname === 'string');
+}
+/** The hostnames the tunnel row says foundry is about to create a record for. */
+const dnsCreatingNames = (settings) => {
+    const list = settings?.dnsCreating;
+    return (Array.isArray(list) ? list : []).filter((n) => typeof n === 'string');
+};
+/** The live `TUNNEL_TOKEN` row of a connector app, if Coolify lists one (#312). */
+const tunnelTokenRows = (envs) => envs.filter((e) => e.key === 'TUNNEL_TOKEN' && !e.is_preview);
 /**
  * #236 round 3: every hostname {@link FoundryStepExecutor.publishTunnelDnsRecords}
  * last wrote a CNAME for, joined by `,` (hostnames carry no `,`, the same
@@ -564,6 +556,100 @@ export function isRunningOrStarting(status) {
         return true;
     return !status.startsWith('exited') && !status.startsWith('stopped');
 }
+/**
+ * The env names `pushAppEnv` writes from what the plan already holds, before
+ * the cookie secret and the entry's declared `env`. `coolifyApp` and an
+ * adoption's plan lines read the same list, so what an adopted app is told
+ * "will change" is what the step writes (#311).
+ */
+function ownedAppEnv(org, entry, recorded, authIssuer = null) {
+    const envs = [
+        // Only the `app` entry has a public name; the others are internal.
+        ...(entry.key === APP_ENTRY_KEY
+            ? [{ key: 'APP_URL', value: `https://${appHostname(org)}` }]
+            : []),
+        // #75: read back by the package-side pino sink (not this repo's job,
+        // #75 "What belongs where") once `ensureLogVolume` has mounted the
+        // matching volume.
+        { key: 'LOG_DIR', value: LOG_DIR },
+    ];
+    if (entry.uses?.auth) {
+        // F5: an entry that signs in has its own client, organisation and issuer.
+        for (const [key, value] of Object.entries(entryAuthEnv(org, entry, recorded, authIssuer))) {
+            envs.push({ key, value });
+        }
+    }
+    else {
+        const zitadelOrgId = recorded.zitadel_org;
+        if (zitadelOrgId)
+            envs.push({ key: 'AUTH_ORGANIZATION_ID', value: zitadelOrgId });
+        const clientId = recorded[APP_CLIENT_ID_SCOPE_KEY];
+        if (clientId)
+            envs.push({ key: 'AUTH_CLIENT_ID', value: clientId });
+    }
+    // The invited owner's ZITADEL user id (gap P3): the app uses it to make
+    // them its own owner in authz on first sign-in. `runSteps` records this
+    // under the same `system:kind:key` shape every step's `resourceId` uses
+    // (`zitadelOwner`'s own doc comment), not a scope id.
+    const ownerUserId = recorded[`zitadel:owner:${org.id}`];
+    if (ownerUserId)
+        envs.push({ key: 'OWNER_USER_ID', value: ownerUserId });
+    return envs;
+}
+/** Every env name foundry writes on an adopted app: what restore may touch (#311). */
+function ownedEnvNames(org, entry, recorded) {
+    return new Set([
+        ...ownedAppEnv(org, entry, recorded).map((e) => e.key),
+        ...Object.keys(entry.env),
+        'AUTH_COOKIE_SECRET',
+        // An entry that signs in also gets the issuer and a minted broker key.
+        ...(entry.uses?.auth ? ['AUTH_ISSUER', 'AUTH_APP_KEY'] : []),
+    ]);
+}
+/** Owned names whose live non-preview row Coolify hid: no value to snapshot (#311). */
+function hiddenOwnedEnv(owned, envs) {
+    return envs
+        .filter((e) => !e.is_preview && owned.has(e.key) && typeof e.value !== 'string')
+        .map((e) => e.key);
+}
+/**
+ * The app uuid and the env rows a snapshot's vault entry holds, for restore.
+ * Refuses, naming the resource only, when the uuid or the entry is missing or
+ * the entry is not a list of env rows (#311).
+ */
+async function readEnvSnapshot(vault, row) {
+    const { uuid } = row.settings;
+    const { vaultRef } = row;
+    const document = vaultRef && typeof uuid === 'string'
+        ? await restoreStep(row.resourceKey, uuid, 'vault read', () => vault.resolve(vaultRef))
+        : null;
+    if (typeof uuid !== 'string' || document === null) {
+        throw new Error(`restore ${row.resourceKey}: the snapshot's vault entry or app uuid is missing; nothing was changed`);
+    }
+    let snapshot;
+    try {
+        snapshot = JSON.parse(document);
+    }
+    catch {
+        throw new Error(`restore ${row.resourceKey}: the vault entry is unreadable; nothing was changed`);
+    }
+    if (!Array.isArray(snapshot) ||
+        !snapshot.every((r) => r !== null && typeof r === 'object' && typeof r.key === 'string')) {
+        throw new Error(`restore ${row.resourceKey}: the vault entry is not a list of env rows; nothing was changed`);
+    }
+    return { uuid, envs: snapshot };
+}
+/** A sha256 hex digest: what the row keeps in place of a token. */
+const sha256Hex = (value) => createHash('sha256').update(value).digest('hex');
+/** Runs one restore call; a failure names the resource and the operation, never the cause (rule 6). */
+async function restoreStep(resourceKey, uuid, operation, call) {
+    try {
+        return await call();
+    }
+    catch {
+        throw new Error(`restore ${resourceKey} (${uuid}): ${operation} failed`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Executor
 // ---------------------------------------------------------------------------
@@ -585,8 +671,12 @@ export class FoundryStepExecutor {
                 return this.zitadelApp(action, org, context);
             case 'zitadel:customers':
                 return this.zitadelCustomers(org, context);
+            case 'coolify:adopt':
+                return this.coolifyAdopt(action, org, context.recordedIds());
             case 'coolify:app':
                 return this.coolifyApp(action, org, context);
+            case 'coolify:broker-entry':
+                return this.coolifyBrokerEntry(action, org, context);
             case 'coolify:database':
                 return this.coolifyDatabase(action, org, context);
             case 'coolify:calls':
@@ -637,7 +727,12 @@ export class FoundryStepExecutor {
      * any policy but foundry's, since that policy could let others in.
      */
     async cloudflareAccess(org) {
-        const domain = hostnameFor(org);
+        // Only the `app` entry has a public name (`planAccess`); per-entry
+        // hostnames are issue 309.
+        const entry = appEntry(org.hosting);
+        if (!entry)
+            throw new Error(`cloudflare:access for ${org.slug}: no '${APP_ENTRY_KEY}' hosting entry`);
+        const domain = appHostname(org);
         const name = `foundry:${org.id}`;
         const cf = this.ports.cloudflare;
         const onDomain = (await cf.listAccessApps()).filter((a) => a.domain === domain);
@@ -655,7 +750,7 @@ export class FoundryStepExecutor {
             await cf.createAccessPolicy(app.id, {
                 name: ACCESS_POLICY_NAME,
                 decision: 'allow',
-                include: (appEntry(org.hosting)?.accessEmails ?? []).map((email) => ({ email: { email } })),
+                include: entry.accessEmails.map((email) => ({ email: { email } })),
             });
         }
         return { resourceId: app.id };
@@ -842,6 +937,9 @@ export class FoundryStepExecutor {
             ...(recorded[APP_CLIENT_ID_SCOPE_KEY]
                 ? org.hosting.issuerApps.filter((a) => a.kind === 'web').map((a) => a.name)
                 : []),
+            ...Object.keys(recorded)
+                .filter((key) => key.startsWith(ENTRY_CLIENT_ID_SCOPE_PREFIX))
+                .map((key) => key.slice(ENTRY_CLIENT_ID_SCOPE_PREFIX.length)),
             ...(recorded[CMS_CLIENT_ID_SCOPE_KEY] ? ['cms'] : []),
             ...(recorded[AGORA_CLIENT_ID_SCOPE_KEY] ? ['agora'] : []),
         ].map((name) => recorded[`zitadel:app:${name}`]));
@@ -1025,7 +1123,7 @@ export class FoundryStepExecutor {
             ? cmsHostnameFor(org)
             : isAgoraClient
                 ? agoraHostnameFor(org)
-                : hostnameFor(org);
+                : appHostname(org);
         // Native apps sign in via device code, with no redirect of their own
         // (auth/scripts/provision.mjs:475-497, prior art cited in the decisions
         // file) -- empty arrays rather than a web app's callback/logout URLs.
@@ -1037,11 +1135,23 @@ export class FoundryStepExecutor {
         const redirectUri = isAgoraClient
             ? `https://${hostname}/callback`
             : `https://${hostname}/auth/callback`;
+        // An entry with `uses.auth` signs in at its own exact hostnames, one pair
+        // of addresses each; a `*` adds none (`entryHostnames`).
+        const authEntry = org.hosting.entries.find((e) => e.key === action.key && e.uses?.auth);
+        const hosts = authEntry ? entryHostnames(org, authEntry) : null;
         const created = await this.ports.zitadel.createOidcApp(zitadelOrgId, projectId, {
             name: action.key,
             appType,
-            redirectUris: appType === 'native' ? [] : [redirectUri],
-            postLogoutRedirectUris: appType === 'native' ? [] : [`https://${hostname}/`],
+            redirectUris: appType === 'native'
+                ? []
+                : hosts
+                    ? hosts.map((host) => `https://${host}/auth/callback`)
+                    : [redirectUri],
+            postLogoutRedirectUris: appType === 'native'
+                ? []
+                : hosts
+                    ? hosts.map((host) => `https://${host}/`)
+                    : [`https://${hostname}/`],
         });
         if (appType === 'web') {
             // `coolifyApp`'s own `pushAppEnv` reads `APP_CLIENT_ID_SCOPE_KEY` to
@@ -1056,7 +1166,9 @@ export class FoundryStepExecutor {
                 ? CMS_CLIENT_ID_SCOPE_KEY
                 : isAgoraClient
                     ? AGORA_CLIENT_ID_SCOPE_KEY
-                    : APP_CLIENT_ID_SCOPE_KEY, created.clientId);
+                    : authEntry
+                        ? entryClientIdScopeKey(action.key)
+                        : APP_CLIENT_ID_SCOPE_KEY, created.clientId);
         }
         return { resourceId: created.appId };
     }
@@ -1102,29 +1214,521 @@ export class FoundryStepExecutor {
             throw new Error('no usable Coolify server is registered on this instance');
         return server;
     }
+    /** The live app Coolify holds under `uuid`. The error names the id only (rule 6). */
+    async readLiveApp(uuid) {
+        try {
+            return (await this.ports.coolify.raw('GET', `/applications/${uuid}`));
+        }
+        catch {
+            throw new Error(`adopt: the live app ${uuid} could not be read`);
+        }
+    }
+    /** The live ingress routes of the adopted tunnel `id`. The error names the id only (rule 6). */
+    async readAdoptedIngress(id) {
+        try {
+            const { config } = await this.ports.cloudflare.getTunnelConfig(id);
+            const ingress = config?.ingress ?? [];
+            if (!Array.isArray(ingress))
+                throw new Error('not a list');
+            return ingress;
+        }
+        catch {
+            throw new Error(`adopt: the live tunnel ${id} could not be read`);
+        }
+    }
+    /**
+     * #311: for each adopted resource, the lines its `coolify:adopt` step shows
+     * (a setting with old value beside new; an env var by name only) and what
+     * is blocked. Read from the live app on every plan. No value of an env var
+     * leaves this method (rule 6).
+     */
+    async adoptionReport(org, recorded) {
+        const details = {};
+        const blocked = [];
+        const withheld = [];
+        for (const resource of adoptedResources(org)) {
+            // A uuid that cannot be read blocks that resource, not the whole plan (rule 2).
+            let live = {};
+            let envs = [];
+            let routes = [];
+            try {
+                if (resource.kind === 'database')
+                    await this.ports.coolify.getDatabase(resource.uuid);
+                else if (resource.kind === 'tunnel')
+                    routes = await this.readAdoptedIngress(resource.uuid);
+                else {
+                    live = await this.readLiveApp(resource.uuid);
+                    envs = await this.ports.coolify.listEnvs(resource.uuid);
+                }
+            }
+            catch {
+                withheld.push(resource.resourceKey);
+                blocked.push({
+                    description: `${org.slug}'s adoption of ${resource.resourceKey} is blocked, not planned: the live resource ${resource.uuid} could not be read`,
+                    key: `coolify:adopt:${resource.resourceKey}`,
+                });
+                continue;
+            }
+            if (resource.kind === 'database') {
+                details[resource.resourceKey] = [
+                    'the database is taken over as it is; nothing in it changes',
+                ];
+                continue;
+            }
+            if (resource.kind === 'tunnel') {
+                // Hostnames only: a service address may carry credentials (rule 6).
+                const declared = tunnelIngressHostnames(org);
+                const row = await this.ports.adoptionStore?.get(org.id, adoptedTunnelKey(org));
+                const written = new Set([...writtenIngressNames(row), ...writingIngressNames(row)]);
+                const kept = foreignRoutes(routes, declared, COOLIFY_PROXY_ORIGIN, written);
+                details[resource.resourceKey] = [
+                    ...kept
+                        .filter((r) => r.hostname !== undefined)
+                        .map((r) => `kept, not managed: ${r.hostname}`),
+                    ...(kept.some((r) => r.hostname === undefined)
+                        ? ['kept, not managed: (no hostname)']
+                        : []),
+                    ...replacedNames(routes, declared, COOLIFY_PROXY_ORIGIN).map((h) => `will replace: ${h}`),
+                    ...removedNames(routes, declared, COOLIFY_PROXY_ORIGIN, written).map((h) => `will remove: ${h}`),
+                ];
+                continue;
+            }
+            if (resource.kind === 'connector') {
+                if (hiddenOwnedEnv(new Set(['TUNNEL_TOKEN']), envs).length > 0) {
+                    withheld.push(resource.resourceKey);
+                    blocked.push({
+                        description: `${org.slug}'s adoption of ${resource.resourceKey} is blocked, not planned: Coolify hides the value of TUNNEL_TOKEN, so it cannot be snapshotted`,
+                        key: `coolify:adopt:${resource.resourceKey}`,
+                    });
+                    continue;
+                }
+                details[resource.resourceKey] = [];
+                // The token is compared and never shown; a failed read adds no line.
+                try {
+                    const token = await this.ports.cloudflare.getTunnelToken(org.hosting.adopt?.tunnel ?? '');
+                    if (tunnelTokenRows(envs).every((e) => e.value !== token)) {
+                        details[resource.resourceKey]?.push('will change: TUNNEL_TOKEN');
+                    }
+                }
+                catch { }
+                continue;
+            }
+            const { entry } = resource;
+            const hidden = hiddenOwnedEnv(ownedEnvNames(org, entry, recorded), envs);
+            if (hidden.length > 0) {
+                withheld.push(resource.resourceKey);
+                blocked.push({
+                    description: `${org.slug}'s adoption of ${resource.resourceKey} is blocked, not planned: Coolify hides the value of ${hidden.sort().join(', ')}, so it cannot be snapshotted`,
+                    key: `coolify:adopt:${resource.resourceKey}`,
+                });
+                continue;
+            }
+            const liveEnv = new Map(envs.filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
+            const owned = new Map([
+                ...ownedAppEnv(org, entry, recorded).map((e) => [e.key, e.value]),
+                ...Object.entries(resolveAppEnv(org, entry, recorded).values),
+            ]);
+            const lines = adoptedPatchDetails(adoptedAppPatch(entry, entryHostnames(org, entry), live), live);
+            for (const [key, value] of owned) {
+                if (!liveEnv.has(key))
+                    lines.push(`will add: ${key}`);
+                else if (liveEnv.get(key) !== value)
+                    lines.push(`will change: ${key}`);
+            }
+            // The issuer's value is read at apply time, so only its presence shows here.
+            if (entry.uses?.auth) {
+                for (const key of ['AUTH_ISSUER', 'AUTH_APP_KEY']) {
+                    owned.set(key, liveEnv.get(key) ?? '');
+                    if (!liveEnv.has(key))
+                        lines.push(`will add: ${key}`);
+                }
+            }
+            if (!liveEnv.has('AUTH_COOKIE_SECRET') && !owned.has('AUTH_COOKIE_SECRET')) {
+                lines.push('will add: AUTH_COOKIE_SECRET');
+            }
+            for (const key of [...liveEnv.keys()].sort()) {
+                if (!owned.has(key) && key !== 'AUTH_COOKIE_SECRET')
+                    lines.push(`not managed: ${key}`);
+            }
+            details[resource.resourceKey] = lines;
+            // Choice A of #311's "Decide": an adopted app with no runtime role
+            // address is reported, never given one.
+            if (entry.database) {
+                const address = liveEnv.get('DATABASE_URL');
+                const ownerAddresses = [liveEnv.get('DATABASE_URL_OWNER')];
+                const databaseUuid = org.hosting.adopt?.database;
+                if (databaseUuid) {
+                    ownerAddresses.push(await this.ports.coolify.getDatabase(databaseUuid).then((db) => db.internal_db_url, () => undefined));
+                }
+                if (!address || ownerAddresses.includes(address)) {
+                    withheld.push(resource.resourceKey);
+                    const label = entry.key === APP_ENTRY_KEY ? 'app' : `${entry.key} app`;
+                    blocked.push({
+                        description: `${org.slug}'s ${label} runtime database address is blocked, not planned: DATABASE_URL is missing or is the owner address, so set DATABASE_URL on the app; foundry leaves its env alone`,
+                        key: entry.key === APP_ENTRY_KEY
+                            ? 'coolify:app:database-url'
+                            : `coolify:app:${entry.key}:database-url`,
+                    });
+                }
+            }
+        }
+        return { details, blocked, withheld };
+    }
+    /**
+     * #311: puts each adopted app back as its snapshot recorded it, touching
+     * only what foundry writes: the settings it patches and the env names it
+     * owns (an edit a person made to anything else stays). Owned names the
+     * snapshot has are written back with its value and flags; owned names it
+     * lacks are deleted; preview rows are left alone. Every vault entry and
+     * live read happens first, so a missing entry or a row that cannot be
+     * deleted refuses before any Coolify write. Errors name ids only, and the
+     * vault's env values go to `bulkUpsertEnvs` and nowhere else (rule 6).
+     */
+    async restoreAdoption(org, recorded, rows) {
+        const vault = this.ports.adoptionVault;
+        if (!vault)
+            throw new Error(`restore for ${org.slug}: no adoption vault is wired`);
+        const apps = [];
+        for (const row of rows.filter((r) => r.kind === 'app')) {
+            // The row names the app: a declaration that changed or went away since
+            // does not move the restore onto another app.
+            const { uuid, envs: snapshot } = await readEnvSnapshot(vault, row);
+            const entry = org.hosting.entries.find((e) => `coolify:app:${appStepKey(org, e.key)}` === row.resourceKey);
+            // Without an entry, the names foundry writes with no declaration.
+            const owned = ownedEnvNames(org, entry ?? {
+                key: row.resourceKey.slice(`coolify:app:${org.id}:`.length),
+                env: {},
+                uses: undefined,
+            }, recorded);
+            const old = snapshot.filter((e) => !e.is_preview);
+            const oldNames = new Set(old.map((e) => e.key));
+            const live = (await restoreStep(row.resourceKey, uuid, 'env read', () => this.ports.coolify.listEnvs(uuid))).filter((e) => !e.is_preview);
+            const liveApp = await restoreStep(row.resourceKey, uuid, 'settings read', () => this.readLiveApp(uuid));
+            const patch = restoreAppPatch(entry, entry ? entryHostnames(org, entry) : [], row.settings, liveApp);
+            const upserts = [];
+            for (const e of old.filter((r) => owned.has(r.key))) {
+                if (typeof e.value !== 'string') {
+                    throw new Error(`restore ${row.resourceKey}: the snapshot has no value for ${e.key}; nothing was changed`);
+                }
+                upserts.push({
+                    key: e.key,
+                    value: e.value,
+                    buildTime: Boolean(e.is_buildtime),
+                    literal: Boolean(e.is_literal),
+                    multiline: Boolean(e.is_multiline),
+                });
+            }
+            const deletes = [];
+            for (const e of live.filter((l) => owned.has(l.key) && !oldNames.has(l.key))) {
+                if (!e.uuid) {
+                    throw new Error(`restore ${row.resourceKey}: the live env ${e.key} has no uuid, so it is not deleted; nothing was changed`);
+                }
+                deletes.push({ key: e.key, uuid: e.uuid });
+            }
+            apps.push({ row, uuid, patch, upserts, deletes });
+        }
+        // #312: the tunnel's ingress with foundry's routes swapped for the snapshot's,
+        // read live now so a route a person added since stays.
+        const cf = this.ports.cloudflare;
+        const tunnels = [];
+        for (const row of rows.filter((r) => r.kind === 'tunnel')) {
+            const { uuid: id, ingress } = row.settings;
+            if (typeof id !== 'string' || !Array.isArray(ingress)) {
+                throw new Error(`restore ${row.resourceKey}: the snapshot's tunnel id or ingress is missing; nothing was changed`);
+            }
+            const { config } = await restoreStep(row.resourceKey, id, 'ingress read', () => cf.getTunnelConfig(id));
+            const live = config?.ingress ?? [];
+            // The names the row says foundry wrote: the declaration may have changed or gone since.
+            const written = new Set([...writtenIngressNames(row), ...writingIngressNames(row)]);
+            const restored = restoreIngress(live, ingress, COOLIFY_PROXY_ORIGIN, written);
+            const swapped = removedNames(live, [], COOLIFY_PROXY_ORIGIN, written).map(normalizeHostname);
+            // A name with a live route that is not exactly foundry's keeps its CNAME, or that route stops resolving.
+            const leftAlone = (hostname) => live.filter((r) => r.hostname !== undefined &&
+                normalizeHostname(r.hostname) === normalizeHostname(hostname)).length > (swapped.includes(normalizeHostname(hostname)) ? 1 : 0);
+            tunnels.push({
+                row,
+                id,
+                config: isDeepStrictEqual(restored, live) ? null : { ...config, ingress: restored },
+                dnsRecords: createdDnsRecords(row.settings).filter((r) => !leftAlone(r.hostname)),
+            });
+        }
+        // #312: the old TUNNEL_TOKEN back on the connector; a token the snapshot lacks is deleted.
+        // Only a live token that is the one foundry wrote (its digest is in the row) is changed.
+        const tokenLeft = [];
+        const connectors = [];
+        for (const row of rows.filter((r) => r.kind === 'connector')) {
+            const { uuid, envs: snapshot } = await readEnvSnapshot(vault, row);
+            const [old] = tunnelTokenRows(snapshot);
+            const [live] = tunnelTokenRows(await restoreStep(row.resourceKey, uuid, 'env read', () => this.ports.coolify.listEnvs(uuid)));
+            if (old && typeof old.value !== 'string') {
+                throw new Error(`restore ${row.resourceKey}: the snapshot has no value for TUNNEL_TOKEN; nothing was changed`);
+            }
+            const foundrys = row.settings.tokenWritten === true &&
+                typeof live?.value === 'string' &&
+                row.settings.tokenDigest === sha256Hex(live.value);
+            if (old && live?.value !== old.value && foundrys) {
+                connectors.push({
+                    row,
+                    uuid,
+                    upsert: {
+                        key: 'TUNNEL_TOKEN',
+                        value: old.value ?? '',
+                        buildTime: Boolean(old.is_buildtime),
+                        literal: Boolean(old.is_literal),
+                        multiline: Boolean(old.is_multiline),
+                    },
+                });
+            }
+            else if (!old && live && foundrys) {
+                if (!live.uuid) {
+                    throw new Error(`restore ${row.resourceKey}: the live TUNNEL_TOKEN has no uuid, so it is not deleted; nothing was changed`);
+                }
+                connectors.push({ row, uuid, del: { uuid: live.uuid } });
+            }
+            else if (live &&
+                !foundrys &&
+                row.settings.tokenWritten === true &&
+                (!old || live.value !== old.value)) {
+                tokenLeft.push(row.resourceKey);
+            }
+            else if (old && !live && row.settings.tokenWritten === true) {
+                // A person deleted the token: a redeploy would start the connector with none.
+                tokenLeft.push(row.resourceKey);
+            }
+            else if (row.settings.tokenWritten === true) {
+                // Foundry rewrote the token: a retry after a failed deploy still deploys.
+                connectors.push({ row, uuid });
+            }
+        }
+        const envDeleted = [];
+        for (const { row, uuid, patch, upserts, deletes } of apps) {
+            const key = row.resourceKey;
+            if (Object.keys(patch).length > 0) {
+                await restoreStep(key, uuid, 'settings update', () => this.ports.coolify.updateApplication(uuid, patch));
+            }
+            if (upserts.length > 0) {
+                await restoreStep(key, uuid, 'env write', () => this.ports.coolify.bulkUpsertEnvs(uuid, upserts));
+            }
+            for (const del of deletes) {
+                await restoreStep(key, uuid, 'env delete', () => this.ports.coolify.raw('DELETE', `/applications/${uuid}/envs/${del.uuid}`));
+                if (!envDeleted.includes(del.key))
+                    envDeleted.push(del.key);
+            }
+            // A container reads env and domains only at start, a folder only at build (rule 4).
+            // Decided from the snapshot, not from live: a retry after a failed deploy
+            // finds live already written and must still deploy.
+            if (Object.keys(patch).length > 0) {
+                await restoreStep(key, uuid, 'deploy', () => this.ports.coolify.deploy(uuid));
+            }
+            else {
+                await restoreStep(key, uuid, 'restart', () => this.ports.coolify.restart(uuid));
+            }
+        }
+        for (const { row, id, config, dnsRecords } of tunnels) {
+            if (config) {
+                await restoreStep(row.resourceKey, id, 'ingress write', () => cf.putTunnelConfig(id, config));
+            }
+            // Only the records foundry created, and only while each is still a CNAME
+            // to this tunnel: one a person repointed, or one already gone, is left.
+            for (const record of dnsRecords) {
+                await restoreStep(row.resourceKey, id, 'dns delete', async () => {
+                    const live = (await cf.findDnsRecord(record.zoneId, record.hostname, 'CNAME')).find((r) => r.id === record.id);
+                    if (live?.content !== `${id}.cfargotunnel.com`)
+                        return;
+                    try {
+                        await cf.deleteDnsRecord(record.zoneId, record.id);
+                    }
+                    catch (error) {
+                        if (!isNotFoundError(error))
+                            throw error;
+                    }
+                });
+            }
+        }
+        for (const { row, uuid, upsert, del } of connectors) {
+            const key = row.resourceKey;
+            if (upsert) {
+                await restoreStep(key, uuid, 'env write', () => this.ports.coolify.bulkUpsertEnvs(uuid, [upsert]));
+            }
+            if (del) {
+                await restoreStep(key, uuid, 'env delete', () => this.ports.coolify.raw('DELETE', `/applications/${uuid}/envs/${del.uuid}`));
+            }
+            // The container reads its token only at start.
+            await restoreStep(key, uuid, 'deploy', () => this.ports.coolify.deploy(uuid));
+        }
+        return { envDeleted, tokenLeft };
+    }
+    /**
+     * #311: records what a live app or database looked like before foundry
+     * first writes to it, in this order: the env values to the vault, the
+     * non-secret settings to the row, then both read back and compared. The
+     * step writes nothing to Coolify, so a snapshot that fails stops the apply
+     * before any later step does. Every error names ids only (rule 6).
+     */
+    async coolifyAdopt(action, org, recorded) {
+        const { adoptionVault: vault, adoptionStore: store } = this.ports;
+        if (!vault || !store) {
+            throw new Error(`coolify:adopt for ${org.slug}: no adoption vault is wired`);
+        }
+        const resource = adoptedResources(org).find((r) => r.resourceKey === action.key);
+        if (!resource)
+            throw new Error(`coolify:adopt for ${org.slug}: nothing declared for ${action.key}`);
+        // Snapshotting another uuid now would record foundry's own earlier writes.
+        const held = await store.get(org.id, action.key);
+        if (held?.state === 'adopted' && held.settings.uuid !== resource.uuid) {
+            throw new Error(`coolify:adopt ${action.key}: restore the adopted ${resource.kind} first (${String(held.settings.uuid)} is adopted, not ${resource.uuid}); nothing was changed`);
+        }
+        // Another key's snapshot of this uuid holds the original; a second one would record foundry's own writes.
+        const holder = (await store.list(org.id)).find((r) => r.resourceKey !== action.key && protectsKey(r) && r.settings.uuid === resource.uuid);
+        if (holder) {
+            throw new Error(`coolify:adopt ${action.key}: ${resource.uuid} is already adopted under ${holder.resourceKey}; nothing was changed`);
+        }
+        let settings = { uuid: resource.uuid };
+        let vaultRef = null;
+        let envDocument = '';
+        if (resource.kind === 'app') {
+            settings = {
+                uuid: resource.uuid,
+                ...snapshotAppSettings(await this.readLiveApp(resource.uuid)),
+            };
+            vaultRef = adoptionVaultRef(org, resource);
+            let envs;
+            try {
+                envs = await this.ports.coolify.listEnvs(resource.uuid);
+            }
+            catch {
+                throw new Error(`adopt: the env of the live app ${resource.uuid} could not be read`);
+            }
+            const hidden = hiddenOwnedEnv(ownedEnvNames(org, resource.entry, recorded), envs);
+            if (hidden.length > 0) {
+                throw new Error(`coolify:adopt ${action.key}: Coolify hides the value of ${hidden.sort().join(', ')}; nothing was changed`);
+            }
+            envDocument = JSON.stringify(envs);
+        }
+        else if (resource.kind === 'tunnel') {
+            settings = {
+                uuid: resource.uuid,
+                ingress: await this.readAdoptedIngress(resource.uuid),
+                written: [],
+            };
+        }
+        else if (resource.kind === 'connector') {
+            await this.readLiveApp(resource.uuid);
+            vaultRef = adoptionVaultRef(org, resource);
+            let envs;
+            try {
+                envs = await this.ports.coolify.listEnvs(resource.uuid);
+            }
+            catch {
+                throw new Error(`adopt: the env of the live app ${resource.uuid} could not be read`);
+            }
+            if (hiddenOwnedEnv(new Set(['TUNNEL_TOKEN']), envs).length > 0) {
+                throw new Error(`coolify:adopt ${action.key}: Coolify hides the value of TUNNEL_TOKEN; nothing was changed`);
+            }
+            // The old token is a secret: it goes to the vault, never to `settings`.
+            envDocument = JSON.stringify(tunnelTokenRows(envs));
+        }
+        let sealed = false;
+        let written = false;
+        try {
+            if (vaultRef)
+                await vault.put(vaultRef, envDocument);
+            await store.put({
+                orgId: org.id,
+                resourceKey: action.key,
+                kind: resource.kind,
+                takenAt: (this.ports.now?.() ?? new Date()).toISOString(),
+                settings,
+                vaultRef,
+            });
+            written = true;
+            const row = await store.get(org.id, action.key);
+            sealed =
+                row !== null &&
+                    row.state === 'adopted' &&
+                    row.vaultRef === vaultRef &&
+                    isDeepStrictEqual(row.settings, settings) &&
+                    (vaultRef === null || (await vault.resolve(vaultRef)) === envDocument);
+        }
+        catch {
+            // The cause may quote a value; the message below names ids only.
+        }
+        if (!sealed) {
+            // A row left as `adopted` would make the retry skip the snapshot (#311).
+            if (written) {
+                try {
+                    await store.setState(org.id, action.key, 'released');
+                }
+                catch {
+                    throw new Error(`coolify:adopt ${action.key}: the snapshot could not be read back and its row could not be released; the row may still be active`);
+                }
+            }
+            throw new Error(`coolify:adopt ${action.key}: the snapshot could not be written and read back; nothing was changed`);
+        }
+        return undefined;
+    }
+    /** #311: whether the resource was adopted: its row is `adopted` or `confirmed`, or `id` is a declared adopt uuid. */
+    async isAdopted(org, resourceKey, id) {
+        const row = await this.ports.adoptionStore?.get(org.id, resourceKey);
+        return protectsKey(row) || declaredAdoptUuids(org).has(id);
+    }
+    /** #311: refuses to manage as foundry's own a resource whose row protects its key and whose declaration has no `adopt`. */
+    async refuseTakeover(org, resourceKey) {
+        if (protectsKey(await this.ports.adoptionStore?.get(org.id, resourceKey))) {
+            throw new Error(`${resourceKey}: adopted, so it needs adopt declared; nothing was changed`);
+        }
+    }
+    /** #311: refuses to write to a declared adopt uuid that has no active snapshot. */
+    async requireSnapshot(org, resourceKey, uuid) {
+        const row = await this.ports.adoptionStore?.get(org.id, resourceKey);
+        if (!isActiveSnapshot(row, uuid)) {
+            throw new Error(`${resourceKey}: no active adoption snapshot; nothing was changed`);
+        }
+    }
     async coolifyApp(action, org, context) {
         const recordedAppId = context.recordedIds()[`coolify:app:${action.key}`];
         if (action.desired.enabled === false) {
             if (!recordedAppId) {
                 throw new Error(`coolify:app for ${org.slug}: no live app recorded, nothing to park`);
             }
+            if (await this.isAdopted(org, `coolify:app:${action.key}`, recordedAppId)) {
+                throw new Error(`coolify:app ${action.key}: adopted, not stopped`);
+            }
             await this.ports.coolify.raw('POST', `/applications/${recordedAppId}/stop`);
             return { resourceId: recordedAppId };
         }
-        const entry = appEntry(org.hosting);
+        const entry = org.hosting.entries.find((e) => appStepKey(org, e.key) === action.key);
         if (!entry)
-            throw new Error(`coolify:app for ${org.slug}: no '${APP_ENTRY_KEY}' hosting entry`);
+            throw new Error(`coolify:app for ${org.slug}: no hosting entry for ${action.key}`);
+        if (entry.adopt)
+            await this.requireSnapshot(org, `coolify:app:${action.key}`, entry.adopt.app);
+        else
+            await this.refuseTakeover(org, `coolify:app:${action.key}`);
         // A level-1 org with no bespoke app of its own gets the shared standard
         // app instead (gap P1, `.plans/2026-09-26-level-1-org-map.md`): an entry
         // with no `repo`.
         const appRepo = entry.repo ?? DEFAULT_APP_REPO;
-        const projectUuid = await this.ensureCoolifyProject(org, context);
-        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        // Read only by the name lookup and by create, so an adopted entry, which
+        // does neither, makes no project (#311).
+        let scoped;
+        const scope = async () => {
+            if (!scoped) {
+                const projectUuid = await this.ensureCoolifyProject(org, context);
+                const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+                scoped = { projectUuid, environment };
+            }
+            return scoped;
+        };
         // The recorded id first; the name when nothing is recorded, or when the
         // recorded app is gone.
         let existing = null;
         let live;
-        if (recordedAppId) {
+        // An adopted entry is the app it declares by uuid: never found by name,
+        // never created (#311).
+        if (entry.adopt) {
+            existing = { uuid: entry.adopt.app };
+        }
+        else if (recordedAppId) {
             try {
                 live = await this.ports.coolify.getApplication(recordedAppId);
                 existing = { uuid: recordedAppId };
@@ -1134,11 +1738,21 @@ export class FoundryStepExecutor {
                     throw error;
             }
         }
-        if (!existing) {
+        if (!existing && !entry.adopt) {
             existing = await this.ports.coolify.findApplicationByName(appNameFor(org, entry), {
-                environmentIds: [environment.id],
+                environmentIds: [(await scope()).environment.id],
             });
         }
+        // An entry with no names is internal: the other entries reach it as
+        // `<slug>-<key>`, and it gets no domain, route or DNS record.
+        const names = entryHostnames(org, entry);
+        const isStatic = entry.buildPack === 'static';
+        const folderField = isStatic ? 'publish_directory' : 'base_directory';
+        const settingsKey = appSettingsAppliedScopeKey(entry.key);
+        const domainsKey = appDomainsAppliedScopeKey(entry.key);
+        const pendingKey = appDeployPendingScopeKey(entry.key);
+        let haveNames;
+        let have;
         let appId;
         if (existing) {
             appId = existing.uuid;
@@ -1148,12 +1762,18 @@ export class FoundryStepExecutor {
             // stops the app without deleting it, so re-enabling found it here,
             // still stopped, and it stayed stopped forever despite `apply`
             // reporting success.
-            live ??= await this.ports.coolify.getApplication(existing.uuid);
-            if (!isRunningOrStarting(live.status)) {
-                await this.ports.coolify.raw('POST', `/applications/${existing.uuid}/start`);
+            // An adopted app is left as it runs: starting it is not declared.
+            if (!entry.adopt) {
+                live ??= await this.ports.coolify.getApplication(existing.uuid);
+                if (!isRunningOrStarting(live.status)) {
+                    await this.ports.coolify.raw('POST', `/applications/${existing.uuid}/start`);
+                }
             }
+            have = appliedAppSettings(context.recordedIds(), entry.key);
+            haveNames = appliedAppDomains(org, context.recordedIds(), entry.key);
         }
         else {
+            const { projectUuid, environment } = await scope();
             const server = await this.resolveServer();
             const githubApp = await this.ports.coolify.requireGithubApp();
             const created = await this.ports.coolify.createGithubAppApplication({
@@ -1166,20 +1786,70 @@ export class FoundryStepExecutor {
                 git_branch: entry.branch,
                 build_pack: entry.buildPack,
                 name: appNameFor(org, entry),
-                domains: hostnameFor(org),
+                domains: names.length > 0 ? names.join(',') : undefined,
+                autogenerate_domain: names.length > 0 ? undefined : false,
+                // A static site is served by Coolify's own web server on port 80.
+                ports_exposes: isStatic ? '80' : entry.port === null ? undefined : String(entry.port),
+                is_auto_deploy_enabled: entry.autoDeploy,
+                [folderField]: entry.folder === null ? undefined : `/${entry.folder}`,
                 // Only the shared standard app builds from this repo; a bespoke
                 // app's Dockerfile is at its own repo's root.
                 dockerfile_location: entry.repo ? undefined : DEFAULT_APP_DOCKERFILE,
             });
             appId = created.uuid;
+            // Create sent every setting, so nothing is left to patch.
+            have = appSettingsOf(entry);
+            haveNames = names;
+        }
+        // Patch what differs from what the app has. A crash before the marker is
+        // recorded below leaves the old one, so the retry patches the same
+        // difference again.
+        const want = appSettingsOf(entry);
+        let patch = {};
+        if (entry.adopt) {
+            patch = adoptedAppPatch(entry, names, await this.readLiveApp(entry.adopt.app));
+        }
+        else {
+            if (want.folder !== have.folder)
+                patch[folderField] = want.folder ? `/${want.folder}` : '/';
+            if (want.port !== have.port && want.port !== null && !isStatic) {
+                patch.ports_exposes = String(want.port);
+            }
+            if (want.autoDeploy !== have.autoDeploy)
+                patch.is_auto_deploy_enabled = want.autoDeploy;
+            // Create names the app after `domains`; a changed name reaches a live app
+            // here (rule 3). The internal name is set after create, as the calls
+            // stack's apps do.
+            if (JSON.stringify(names) !== JSON.stringify(haveNames))
+                patch.domains = names.join(',');
+            if (names.length === 0 && (!existing || patch.domains !== undefined)) {
+                patch.custom_internal_name = appNameFor(org, entry);
+            }
+        }
+        if (Object.keys(patch).length > 0) {
+            // An adopted app's patch is live from here, so a failed deploy must
+            // replan the app step (#311).
+            if (entry.adopt) {
+                context.recordScopeId(pendingKey, '1');
+                await context.persistScopeIds();
+            }
+            await this.ports.coolify.updateApplication(appId, patch);
         }
+        // The container builds and listens from these only at its next deploy.
+        const settingsNeedDeploy = Boolean((entry.adopt && context.recordedIds()[pendingKey]) ||
+            patch.base_directory ||
+            patch.publish_directory ||
+            patch.ports_exposes ||
+            patch.domains !== undefined ||
+            patch.custom_internal_name);
         // The database plans before the app (`diff.ts`'s `computePlanDetail`,
         // hosting-wiring campaign) so that, on the same apply, the database's
         // resource id is already recorded by the time this runs -- but this also
         // covers the database being turned on after the app already exists (the
         // app step still ran this apply, found the app by name, and lands here).
         let dbPush = { pushed: false, changed: false };
-        if (entry.database) {
+        // An adopted app keeps the database addresses it has (#311).
+        if (entry.database && !entry.adopt && !org.hosting.adopt?.database) {
             const dbId = context.recordedIds()[`coolify:database:${org.id}`];
             if (dbId) {
                 dbPush = await this.pushDatabaseUrl(appId, dbId, org.slug.replace(/-/g, '_'));
@@ -1188,7 +1858,7 @@ export class FoundryStepExecutor {
         // Restart when the push changed something, or when no earlier run got as
         // far as restarting after one (marker missing): a crash between the push
         // and the restart leaves the env right and the container stale.
-        const dbNeedsRestart = dbPush.pushed && (dbPush.changed || !context.recordedIds()[DB_ENV_APPLIED_SCOPE_KEY]);
+        const dbNeedsRestart = dbPush.pushed && (dbPush.changed || !context.recordedIds()[dbEnvAppliedScopeKey(entry.key)]);
         // Every app keeps its own logs across a redeploy (#75). Unconditional,
         // like the env push below: found by mount path before create, so a
         // re-run (or the drift step `diff.ts`'s `planApp` plans for an app that
@@ -1196,27 +1866,47 @@ export class FoundryStepExecutor {
         // `ensureLogVolume` whether this app was already running before this
         // call -- see its own doc comment for why that decides whether to
         // restart it.
-        await this.ensureLogVolume(appId, org, Boolean(existing));
+        // An adopted app gets no volume: the snapshot cannot undo one (#311).
+        if (!entry.adopt) {
+            await this.ensureLogVolume(appId, org, Boolean(existing), appNameFor(org, entry));
+        }
         // The app receives whatever it needs to sign in (gap P2). Unconditional,
         // unlike the database push above: every app has a hostname, and an
         // upsert of the same value on a later apply is a no-op, not a change.
-        const appEnv = await this.pushAppEnv(appId, org, entry, context);
+        const appEnv = await this.pushAppEnv(appId, org, entry, context, action.desired.authIssuer ?? null);
         // Rule 4 (#239, #243): a container reads its env only at start, so an app
         // that was already there is restarted, once, when its database URLs or its
         // declared appEnv changed.
-        if ((appEnv.changed || dbNeedsRestart) && existing)
+        // A new folder needs a build, which a restart does not do, so a settings
+        // change deploys instead (rule 3), and that carries the env too.
+        if (settingsNeedDeploy)
+            await this.ports.coolify.deploy(appId);
+        else if ((appEnv.changed || dbNeedsRestart) && existing)
             await this.ports.coolify.restart(appId);
-        // Recorded only after the restart succeeded: a failed restart leaves the
-        // old value, so the next plan replans (rule 3). The db marker is not a URL.
-        context.recordScopeId(APP_ENV_APPLIED_SCOPE_KEY, appEnv.applied);
+        // Recorded only after the redeploy succeeded: a failed one leaves the old
+        // value, so the next plan replans (rule 3). The db marker is not a URL.
+        // A port taken back to null was not patched, so the marker keeps the old
+        // one and `planApp` reports it instead of planning it.
+        context.recordScopeId(settingsKey, JSON.stringify({ ...want, port: want.port ?? have.port }));
+        context.recordScopeId(domainsKey, JSON.stringify(names));
+        if (entry.adopt)
+            context.recordScopeId(pendingKey, '');
+        context.recordScopeId(appEnvAppliedScopeKey(entry.key), appEnv.applied);
+        if (entry.uses?.auth) {
+            context.recordScopeId(entryAuthEnvAppliedScopeKey(entry.key), appEnv.authApplied);
+        }
         if (dbPush.pushed)
-            context.recordScopeId(DB_ENV_APPLIED_SCOPE_KEY, '1');
+            context.recordScopeId(dbEnvAppliedScopeKey(entry.key), '1');
         // #140 rework (2026-09-28 lettermint-org-mail swap): the hosted app's own
         // Lettermint project, domain restriction and `MAIL_FROM` (only the app
         // started by this same step, per the design's "only apps that send mail
         // get it" -- cms and calls do not). A no-op until `coolify:mail` has
         // actually resolved a mail domain for this org.
-        await this.ensureAppLettermintMail(appId, org, context, Boolean(existing));
+        // One Lettermint project, `<slug>-app`, belongs to the `app` entry; a
+        // second entry sharing the name would delete the first's live token.
+        if (entry.key === APP_ENTRY_KEY && !entry.adopt) {
+            await this.ensureAppLettermintMail(appId, org, context, Boolean(existing));
+        }
         return { resourceId: appId };
     }
     /**
@@ -1240,13 +1930,13 @@ export class FoundryStepExecutor {
      * `createGithubAppApplication`'s own instant-deploy path, so a restart
      * here would only be a redundant extra one).
      */
-    async ensureLogVolume(appId, org, wasAlreadyRunning) {
+    async ensureLogVolume(appId, org, wasAlreadyRunning, appName = org.slug) {
         const storages = await this.ports.coolify.listStorages(appId);
         const already = (storages.persistent_storages ?? []).some((s) => s.mount_path === LOG_DIR);
         if (already)
             return;
         await this.ports.coolify.createPersistentStorage(appId, {
-            name: `${org.slug}-logs`,
+            name: `${appName}-logs`,
             mount_path: LOG_DIR,
         });
         if (wasAlreadyRunning) {
@@ -1259,12 +1949,24 @@ export class FoundryStepExecutor {
             if (!dbId) {
                 throw new Error(`coolify:database for ${org.slug}: no live database recorded, nothing to park`);
             }
+            if (await this.isAdopted(org, `coolify:database:${action.key}`, dbId)) {
+                throw new Error(`coolify:database ${action.key}: adopted, not stopped`);
+            }
             await this.ports.coolify.raw('POST', `/databases/${dbId}/stop`);
             return { resourceId: dbId };
         }
         const existing = context.recordedIds()[`coolify:database:${action.key}`];
         let dbId;
-        if (existing) {
+        if (!org.hosting.adopt?.database) {
+            await this.refuseTakeover(org, `coolify:database:${action.key}`);
+        }
+        if (org.hosting.adopt?.database) {
+            // The declared uuid is the database, over any recorded id: never found by
+            // name or created (#311).
+            dbId = org.hosting.adopt.database;
+            await this.requireSnapshot(org, `coolify:database:${action.key}`, dbId);
+        }
+        else if (existing) {
             dbId = existing;
         }
         else {
@@ -1293,14 +1995,16 @@ export class FoundryStepExecutor {
         // Handles the database being provisioned after the app already exists
         // (`coolifyApp`'s own push handles the more common order, database
         // before app on the same apply -- `diff.ts`'s `computePlanDetail`).
-        const appId = context.recordedIds()[`coolify:app:${appStepKey(org)}`];
-        if (appId) {
+        const dbEntry = org.hosting.entries.find((e) => e.database);
+        const appId = dbEntry && context.recordedIds()[`coolify:app:${appStepKey(org, dbEntry.key)}`];
+        if (dbEntry && appId && !dbEntry.adopt && !org.hosting.adopt?.database) {
+            const markerKey = dbEnvAppliedScopeKey(dbEntry.key);
             const push = await this.pushDatabaseUrl(appId, dbId, org.slug.replace(/-/g, '_'));
             if (push.pushed) {
-                if (push.changed || !context.recordedIds()[DB_ENV_APPLIED_SCOPE_KEY]) {
+                if (push.changed || !context.recordedIds()[markerKey]) {
                     await this.ports.coolify.restart(appId);
                 }
-                context.recordScopeId(DB_ENV_APPLIED_SCOPE_KEY, '1');
+                context.recordScopeId(markerKey, '1');
             }
         }
         return { resourceId: dbId };
@@ -1390,28 +2094,22 @@ export class FoundryStepExecutor {
      * that call runs only once the `app` entry's `database` is declared and
      * provisioned, where this one is unconditional (#239).
      */
-    async pushAppEnv(appId, org, entry, context) {
+    async pushAppEnv(appId, org, entry, context, authIssuer) {
         const recorded = context.recordedIds();
-        const envs = [
-            { key: 'APP_URL', value: `https://${hostnameFor(org)}` },
-            // #75: read back by the package-side pino sink (not this repo's job,
-            // #75 "What belongs where") once `ensureLogVolume` has mounted the
-            // matching volume.
-            { key: 'LOG_DIR', value: LOG_DIR },
-        ];
-        const zitadelOrgId = recorded.zitadel_org;
-        if (zitadelOrgId)
-            envs.push({ key: 'AUTH_ORGANIZATION_ID', value: zitadelOrgId });
-        const clientId = recorded[APP_CLIENT_ID_SCOPE_KEY];
-        if (clientId)
-            envs.push({ key: 'AUTH_CLIENT_ID', value: clientId });
-        // The invited owner's ZITADEL user id (gap P3): the app uses it to make
-        // them its own owner in authz on first sign-in. `runSteps` records this
-        // under the same `system:kind:key` shape every step's `resourceId` uses
-        // (`zitadelOwner`'s own doc comment), not a scope id.
-        const ownerUserId = recorded[`zitadel:owner:${org.id}`];
-        if (ownerUserId)
-            envs.push({ key: 'OWNER_USER_ID', value: ownerUserId });
+        const envs = ownedAppEnv(org, entry, recorded, authIssuer);
+        // An entry with `uses.auth` signs in one organisation, with its own client
+        // and the issuer; any other entry keeps the org's staff organisation and
+        // the one hosted-app client.
+        const authEnv = entryAuthEnv(org, entry, recorded, authIssuer);
+        if (entry.uses?.auth) {
+            // A customers entry never falls back to the staff organisation's id.
+            if (!authEnv.AUTH_ORGANIZATION_ID) {
+                throw new Error(`coolify:app for ${org.slug}: entry '${entry.key}' signs in ${entry.uses.auth.users}, whose organisation id is not recorded yet`);
+            }
+            const appKey = await this.ensureAuthAppKey(appId);
+            if (appKey)
+                envs.push({ key: 'AUTH_APP_KEY', value: appKey });
+        }
         // Idempotent the same way `pushDatabaseUrl`'s credential is treated:
         // generated once, handed straight to `bulkUpsertEnvs` and nowhere else in
         // this class -- never returned, recorded, logged or interpolated into a
@@ -1428,12 +2126,86 @@ export class FoundryStepExecutor {
         const appEnv = resolveAppEnv(org, entry, recorded).values;
         for (const [key, value] of Object.entries(appEnv))
             envs.push({ key, value });
-        await this.ports.coolify.bulkUpsertEnvs(appId, envs);
+        // An omitted flag is written as false, so on an adopted app a name that
+        // exists live keeps the flags it has (#311).
+        const live = entry.adopt
+            ? (await this.ports.coolify.listEnvs(appId)).filter((e) => !e.is_preview)
+            : [];
+        await this.ports.coolify.bulkUpsertEnvs(appId, envs.map((env) => {
+            const row = live.find((e) => e.key === env.key);
+            return row
+                ? {
+                    ...env,
+                    buildTime: Boolean(row.is_buildtime),
+                    literal: Boolean(row.is_literal),
+                    multiline: Boolean(row.is_multiline),
+                }
+                : env;
+        }));
         // `coolifyApp` records `applied` once the restart succeeded, so `planApp`
         // replans this step when the declared map changes (rule 3). Ids and a
         // domain, never a secret.
         const applied = JSON.stringify(appEnv);
-        return { changed: applied !== (recorded[APP_ENV_APPLIED_SCOPE_KEY] ?? '{}'), applied };
+        // The sign-in values, recorded by `coolifyApp` the same way; the key is
+        // never part of them.
+        const authApplied = JSON.stringify(authEnv);
+        return {
+            changed: applied !== (recorded[appEnvAppliedScopeKey(entry.key)] ?? '{}') ||
+                (Boolean(entry.uses?.auth) &&
+                    authApplied !== (recorded[entryAuthEnvAppliedScopeKey(entry.key)] ?? '{}')),
+            applied,
+            authApplied,
+        };
+    }
+    /**
+     * F5: the app's `AUTH_APP_KEY`, minted once and only when the app has none
+     * of at least 32 characters (the broker refuses a shorter one). `null` once
+     * it has one: the app's env is where the key lives, and
+     * `coolifyBrokerEntry` reads it back from there. It goes to this env and
+     * the broker's, nowhere else.
+     */
+    async ensureAuthAppKey(appId) {
+        const envs = await this.ports.coolify.listEnvs(appId);
+        const already = envs.some((e) => e.key === 'AUTH_APP_KEY' && !e.is_preview && (e.value ?? '').length >= 32);
+        return already ? null : randomBytes(32).toString('base64url');
+    }
+    /**
+     * `plan/diff.ts`'s `planBrokerEntries` (F5): the entry's `AUTH_APPS` entry,
+     * written by `writeBrokerEntry` with the key `pushAppEnv` put in the app's
+     * env. Records what it wrote (never the key) and any foreign entry the
+     * broker would drop.
+     */
+    async coolifyBrokerEntry(action, org, context) {
+        const broker = this.ports.broker;
+        if (!broker)
+            throw new Error(`coolify:broker-entry for ${org.slug}: the broker port is not wired`);
+        const recorded = context.recordedIds();
+        const entry = org.hosting.entries.find((e) => appStepKey(org, e.key) === action.key);
+        if (!entry?.uses?.auth) {
+            throw new Error(`coolify:broker-entry for ${org.slug}: no uses.auth entry for ${action.key}`);
+        }
+        const wanted = wantedBrokerEntry(org, entry, recorded);
+        if ('missing' in wanted) {
+            throw new Error(`coolify:broker-entry for ${org.slug}: ${wanted.missing.map((m) => m.what).join(', ')} not recorded yet`);
+        }
+        const appId = recorded[`coolify:app:${action.key}`];
+        if (!appId) {
+            throw new Error(`coolify:broker-entry for ${org.slug}: app ${action.key} is not recorded yet`);
+        }
+        const appKey = (await this.ports.coolify.listEnvs(appId)).find((e) => e.key === 'AUTH_APP_KEY' && !e.is_preview)?.value;
+        if (!appKey || appKey.length < 32) {
+            throw new Error(`coolify:broker-entry for ${org.slug}: app ${appId} has no AUTH_APP_KEY yet`);
+        }
+        const previousRaw = recorded[brokerEntryAppliedScopeKey(entry.key)];
+        const result = await writeBrokerEntry(broker, {
+            want: wanted.want,
+            appKey,
+            previous: previousRaw ? JSON.parse(previousRaw) : null,
+        });
+        context.recordScopeId(brokerEntryWarningsScopeKey(entry.key), JSON.stringify(result.invalidForeign));
+        // Last: a run that failed above plans the step again.
+        context.recordScopeId(brokerEntryAppliedScopeKey(entry.key), JSON.stringify(wanted.want));
+        return {};
     }
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
@@ -2507,11 +3279,17 @@ export class FoundryStepExecutor {
     }
     // ---- cloudflare --------------------------------------------------------
     async cloudflareTunnel(action, org, context) {
+        const adoptedTunnel = org.hosting.adopt?.tunnel;
+        const connectorApp = org.hosting.adopt?.connectorApp;
         if (action.desired.enabled === false) {
             const tunnelId = context.recordedIds()[`cloudflare:tunnel:${action.key}`];
             if (!tunnelId) {
                 throw new Error(`cloudflare:tunnel for ${org.slug}: no live tunnel recorded, nothing to park`);
             }
+            // Parking clears the ingress and stops the connector: never for what was adopted (#312).
+            if (await this.isAdopted(org, adoptedTunnelKey(org), tunnelId)) {
+                throw new Error(`cloudflare:tunnel ${action.key}: adopted, not stopped`);
+            }
             // Cleared, not deleted (#7 corrections 1): an ingress with only the
             // mandatory catch-all routes nothing.
             await this.ports.cloudflare.putTunnelConfig(tunnelId, {
@@ -2532,6 +3310,17 @@ export class FoundryStepExecutor {
             }
             return { resourceId: tunnelId };
         }
+        // An adopted tunnel and connector are written to only under an active
+        // snapshot; one that was adopted and is no longer declared is not taken as
+        // foundry's own (#312).
+        if (adoptedTunnel)
+            await this.requireSnapshot(org, adoptedTunnelKey(org), adoptedTunnel);
+        else
+            await this.refuseTakeover(org, adoptedTunnelKey(org));
+        if (connectorApp)
+            await this.requireSnapshot(org, adoptedConnectorKey(org), connectorApp);
+        else
+            await this.refuseTakeover(org, adoptedConnectorKey(org));
         const tunnelName = `${org.slug}-tunnel`;
         // #236 round 5 finding 2 / round 6 finding 2: read, and (if it is about
         // to change) added to the accumulated replaced-id set, before
@@ -2540,8 +3329,11 @@ export class FoundryStepExecutor {
         // domain declared still leaves `destroy` a way to recognise the old
         // id's CNAMEs as this tunnel's own rather than a foreign record.
         const recordedTunnelId = context.recordedIds()[`cloudflare:tunnel:${action.key}`];
-        const existing = await this.ports.cloudflare.findTunnelByName(tunnelName);
-        const tunnel = existing ?? (await this.ports.cloudflare.createTunnel(tunnelName));
+        // An adopted tunnel is the one declared by id: never found by name, never created (#312).
+        const tunnel = adoptedTunnel
+            ? { id: adoptedTunnel }
+            : ((await this.ports.cloudflare.findTunnelByName(tunnelName)) ??
+                (await this.ports.cloudflare.createTunnel(tunnelName)));
         const previousIds = parseTunnelPreviousIds(context.recordedIds());
         if (recordedTunnelId && recordedTunnelId !== tunnel.id) {
             previousIds.add(recordedTunnelId);
@@ -2554,7 +3346,7 @@ export class FoundryStepExecutor {
         // offline.tf's bootstrap, cited by
         // https://github.com/wtfalch/foundry/issues/71): every app on the
         // Coolify box already gets a Traefik route from the `domains` its
-        // `coolify:app` step declared (`hostnameFor(org)`, this file's
+        // `coolify:app` step declared (`appHostname(org)`, this file's
         // `coolifyApp`), so a cloudflared connector joined to the same Docker
         // network only has to reach Traefik and let it route by Host header --
         // the connector never needs to know the app's own container name or
@@ -2564,13 +3356,18 @@ export class FoundryStepExecutor {
         // (#115) gets one ingress entry per hostname `tunnelIngressHostnames`
         // returns, all routed to the same proxy -- Traefik itself, not this list,
         // is what tells the public site apart from the cms studio.
-        const ingress = tunnelIngressHostnames(org).map((hostname) => ({
-            hostname,
-            service: COOLIFY_PROXY_ORIGIN,
-        }));
-        await this.ports.cloudflare.putTunnelConfig(tunnel.id, {
-            ingress: [...ingress, { service: 'http_status:404' }],
-        });
+        if (adoptedTunnel) {
+            await this.mergeAdoptedIngress(org, tunnel.id);
+        }
+        else {
+            const ingress = tunnelIngressHostnames(org).map((hostname) => ({
+                hostname,
+                service: COOLIFY_PROXY_ORIGIN,
+            }));
+            await this.ports.cloudflare.putTunnelConfig(tunnel.id, {
+                ingress: [...ingress, { service: 'http_status:404' }],
+            });
+        }
         // #235: a connector for this org's own tunnel, the same call every
         // platform tunnel step already makes (Decided, William, 2026-10-01:
         // one connector per org tunnel, never a shared tunnel with appended
@@ -2578,22 +3375,40 @@ export class FoundryStepExecutor {
         // nothing is dialed into it, so `hostname` answers with a Cloudflare
         // error -- #197's own gap, for an org's tunnel rather than a platform
         // one.
-        const projectUuid = await this.ensureCoolifyProject(org, context);
-        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
-        await ensureCloudflaredConnector({
+        // An adopted connector is the app declared by uuid: it needs no project to
+        // be found in or created under (#312).
+        let place;
+        if (!connectorApp) {
+            const projectUuid = await this.ensureCoolifyProject(org, context);
+            const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+            place = { projectUuid, environment };
+        }
+        else {
+            context.recordScopeId(CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY, connectorApp);
+        }
+        await this.guarded(Boolean(adoptedTunnel), `cloudflare:tunnel for ${org.slug}: updating the connector of tunnel ${tunnel.id}`, () => ensureCloudflaredConnector({
             coolify: this.ports.coolify,
             cloudflare: this.ports.cloudflare,
             tunnelId: tunnel.id,
             appName: `${org.slug}-cloudflared`,
-            projectUuid,
-            environment,
+            ...place,
+            adopted: Boolean(connectorApp),
+            // Restore redeploys a connector whose token foundry rewrote, so this is recorded first.
+            // The digest tells restore the live token is foundry's; the token itself is never stored.
+            beforeTokenWrite: connectorApp
+                ? (token) => this.updateAdoptionSettings(org, adoptedConnectorKey(org), (settings) => ({
+                    ...settings,
+                    tokenWritten: true,
+                    tokenDigest: sha256Hex(token),
+                }))
+                : undefined,
             resolveServer: () => this.resolveServer(),
             recordedConnectorAppId: context.recordedIds()[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY] ?? null,
             recordAppId: async (appId) => {
                 context.recordScopeId(CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY, appId);
                 await context.persistScopeIds();
             },
-        });
+        }));
         // #236: an org with no domain (a level-1 org whose app still serves off
         // the shared `*.oikos.host` wildcard tunnel, `scripts/shared-ingress.mjs`)
         // has no zone of its own and nothing here to publish -- `org.domain` is
@@ -2626,12 +3441,14 @@ export class FoundryStepExecutor {
         // failure leaves the *old* domain recorded, so a retry sees the same
         // domain change again and tries cleanup again.
         if (org.domain) {
+            const { domain } = org;
             const recordedBefore = context.recordedIds();
             const previousDomain = recordedBefore[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY];
             const previousHostnamesRaw = recordedBefore[CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY];
             const previousHostnames = previousHostnamesRaw ? previousHostnamesRaw.split(',') : [];
             const domainChanged = previousDomain !== undefined && previousDomain !== org.domain;
-            const publishedHostnames = await this.publishTunnelDnsRecords(org, org.domain, tunnel.id, 
+            const dnsFailed = `cloudflare:tunnel for ${org.slug}: publishing DNS for tunnel ${tunnel.id}`;
+            const publishedHostnames = await this.guarded(Boolean(adoptedTunnel), dnsFailed, () => this.publishTunnelDnsRecords(org, domain, tunnel.id, 
             // Round 6 finding 2: every id this step has ever replaced, not only
             // the one `recordedTunnelId` captured above -- see the scope key's
             // own doc comment.
@@ -2641,9 +3458,13 @@ export class FoundryStepExecutor {
             // needs the domain's own previous hostname list for that. A domain
             // change instead cleans the *whole* old domain below, so it gets an
             // empty list here rather than a second, redundant pass over it.
-            domainChanged ? [] : previousHostnames, context);
+            domainChanged ? [] : previousHostnames, context));
             if (domainChanged) {
-                await this.deleteStaleTunnelDnsRecords(tunnel.id, previousIds, previousDomain, previousHostnames, context);
+                await this.guarded(Boolean(adoptedTunnel), dnsFailed, async () => this.deleteStaleTunnelDnsRecords(tunnel.id, previousIds, previousDomain, previousHostnames, context, 
+                // An adopted tunnel's CNAME that foundry did not create is never deleted.
+                adoptedTunnel
+                    ? new Set(createdDnsRecords((await this.ports.adoptionStore?.get(org.id, adoptedTunnelKey(org)))?.settings).map((r) => r.id))
+                    : undefined));
             }
             context.recordScopeId(CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY, org.domain);
             context.recordScopeId(CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY, publishedHostnames.join(','));
@@ -2671,6 +3492,80 @@ export class FoundryStepExecutor {
         }
         return { resourceId: tunnel.id };
     }
+    /**
+     * Runs `call`; for an adopted resource a failure that is not one of this
+     * file's own messages (which name hostnames and record types only) is
+     * replaced by `label`, because a client's error text carries response
+     * bodies (rule 6, #312).
+     */
+    async guarded(adopted, label, call) {
+        if (!adopted)
+            return call();
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith('cloudflare:tunnel for '))
+                throw error;
+            throw new Error(`${label} failed`);
+        }
+    }
+    /**
+     * #312: writes the org's routes into the adopted tunnel's LIVE ingress list
+     * (`mergeIngress`), not the snapshot, so a route a person added since is
+     * kept too. The declared names go into the tunnel row's `written` only after
+     * the write that carried them succeeded, so a crash in between leaves a
+     * route taken as foreign and kept. Writes nothing when the merged list is the
+     * live one. Errors name the tunnel id and the operation only.
+     */
+    async mergeAdoptedIngress(org, tunnelId) {
+        const cf = this.ports.cloudflare;
+        const failed = (operation) => new Error(`cloudflare:tunnel for ${org.slug}: ${operation} of tunnel ${tunnelId} failed`);
+        let live;
+        try {
+            live = (await cf.getTunnelConfig(tunnelId)).config;
+            if (live && !Array.isArray(live.ingress))
+                throw new Error('not a list');
+        }
+        catch {
+            throw failed('reading the ingress');
+        }
+        const declared = tunnelIngressHostnames(org);
+        const row = await this.ports.adoptionStore?.get(org.id, adoptedTunnelKey(org));
+        // A name in `writing` may have been carried by a put whose row write never landed.
+        const written = new Set([...writtenIngressNames(row), ...writingIngressNames(row)]);
+        const snapshot = Array.isArray(row?.settings.ingress) ? row.settings.ingress : [];
+        const merged = mergeIngress(live?.ingress ?? [], declared, COOLIFY_PROXY_ORIGIN, written, snapshot);
+        try {
+            const put = !isDeepStrictEqual(merged, live?.ingress ?? []);
+            if (put) {
+                // Recorded before the put: a failed row write after it must not strand foundry's routes.
+                await this.updateAdoptionSettings(org, adoptedTunnelKey(org), (settings) => ({
+                    ...settings,
+                    writing: [...new Set([...writingIngressNames(row), ...declared])],
+                }));
+                await cf.putTunnelConfig(tunnelId, { ...live, ingress: merged });
+            }
+            if (put || declared.some((hostname) => !written.has(hostname))) {
+                await this.updateAdoptionSettings(org, adoptedTunnelKey(org), (settings) => ({
+                    ...settings,
+                    written: [...new Set([...written, ...declared])],
+                    writing: [],
+                }));
+            }
+        }
+        catch {
+            throw failed('writing the ingress');
+        }
+    }
+    /** #312: replaces the `settings` of an adoption row, read fresh so no other key is lost. The state and `takenAt` stay. */
+    async updateAdoptionSettings(org, resourceKey, update) {
+        const { adoptionStore: store } = this.ports;
+        const row = await store?.get(org.id, resourceKey);
+        if (!store || !row)
+            throw new Error('no adoption row to record in');
+        await store.setSettings(org.id, resourceKey, update(row.settings));
+    }
     /**
      * #236: when this tunnel's DNS was last published under a domain that
      * differs from the one `org` now declares, deletes every CNAME in the
@@ -2712,7 +3607,7 @@ export class FoundryStepExecutor {
      * hostnames) never added entries of its own to begin with, so there is
      * nothing of this domain's left in that set either way.
      */
-    async deleteStaleTunnelDnsRecords(tunnelId, previousIds, previousDomain, previousHostnames, context) {
+    async deleteStaleTunnelDnsRecords(tunnelId, previousIds, previousDomain, previousHostnames, context, onlyIds) {
         const zone = await this.ports.cloudflare.findZoneByApex(previousDomain);
         if (!zone)
             return;
@@ -2726,7 +3621,7 @@ export class FoundryStepExecutor {
             ? (await Promise.all(previousHostnames.map((hostname) => cf.findDnsRecord(zone.id, hostname, 'CNAME')))).flat()
             : await cf.listDnsRecords(zone.id, { type: 'CNAME' });
         for (const record of records) {
-            if (dnsTargets.has(record.content)) {
+            if (dnsTargets.has(record.content) && (!onlyIds || onlyIds.has(record.id))) {
                 await cf.deleteDnsRecord(zone.id, record.id);
             }
         }
@@ -2800,12 +3695,15 @@ export class FoundryStepExecutor {
         if (!zone) {
             throw new Error(`cloudflare:tunnel for ${org.slug}: no Cloudflare zone found for ${domain} to point its hostnames at -- cloudflare:zone must provision it first`);
         }
+        const adopted = Boolean(org.hosting.adopt?.tunnel);
+        const tunnelRow = () => this.ports.adoptionStore?.get(org.id, adoptedTunnelKey(org));
         const dnsTarget = `${tunnelId}.cfargotunnel.com`;
         const previousTargets = new Set([...previousIds].filter((id) => id !== tunnelId).map((id) => `${id}.cfargotunnel.com`));
-        const hostnames = tunnelIngressHostnames(org).filter((hostname) => hostname === domain || hostname.endsWith(`.${domain}`));
+        const hostnames = tunnelDnsHostnames(org, domain);
         const droppedHostnames = previousHostnames.filter((hostname) => !hostnames.includes(hostname));
         const conflicts = [];
         const toCreate = [];
+        const toClaim = [];
         const toRepoint = [];
         for (const hostname of hostnames) {
             const [a] = await cf.findDnsRecord(zone.id, hostname, 'A');
@@ -2826,6 +3724,11 @@ export class FoundryStepExecutor {
             }
             if (!cname)
                 toCreate.push(hostname);
+            // A crash after the create left a CNAME to the tunnel that is foundry's.
+            else if (adopted &&
+                dnsCreatingNames((await tunnelRow())?.settings).some((n) => normalizeHostname(n) === normalizeHostname(hostname))) {
+                toClaim.push({ hostname, recordId: cname.id });
+            }
         }
         if (conflicts.length > 0) {
             throw new Error(`cloudflare:tunnel for ${org.slug}: will not point its tunnel at every hostname -- ${conflicts.join('; ')}; remove the conflicting record first`);
@@ -2846,13 +3749,43 @@ export class FoundryStepExecutor {
         };
         for (const hostname of settled)
             recordTracked(hostname);
+        // The row learns of a record foundry made: `dnsCreating` first, then `dnsRecords` with its id.
+        const recordCreated = (hostname, recordId) => this.updateAdoptionSettings(org, adoptedTunnelKey(org), (settings) => ({
+            ...settings,
+            dnsRecords: [...createdDnsRecords(settings), { zoneId: zone.id, id: recordId, hostname }],
+            dnsCreating: dnsCreatingNames(settings).filter((n) => normalizeHostname(n) !== normalizeHostname(hostname)),
+        }));
+        for (const { hostname, recordId } of toClaim)
+            await recordCreated(hostname, recordId);
         for (const hostname of toCreate) {
-            await cf.createDnsRecord(zone.id, {
-                type: 'CNAME',
-                name: hostname,
-                content: dnsTarget,
-                proxied: true,
-            });
+            if (adopted) {
+                await this.updateAdoptionSettings(org, adoptedTunnelKey(org), (settings) => ({
+                    ...settings,
+                    dnsCreating: [...new Set([...dnsCreatingNames(settings), hostname])],
+                }));
+            }
+            let created;
+            try {
+                created = await cf.createDnsRecord(zone.id, {
+                    type: 'CNAME',
+                    name: hostname,
+                    content: dnsTarget,
+                    proxied: true,
+                });
+            }
+            catch (error) {
+                // The call answered with an error: no record of foundry's, so a later one is a person's.
+                // A timeout or network failure may have created it: `dnsCreating` stays for the claim.
+                if (adopted && isApiError(error)) {
+                    await this.updateAdoptionSettings(org, adoptedTunnelKey(org), (settings) => ({
+                        ...settings,
+                        dnsCreating: dnsCreatingNames(settings).filter((n) => normalizeHostname(n) !== normalizeHostname(hostname)),
+                    })).catch(() => { });
+                }
+                throw error;
+            }
+            if (adopted)
+                await recordCreated(hostname, created.id);
             recordTracked(hostname);
         }
         for (const { hostname, recordId } of toRepoint) {
@@ -2876,7 +3809,10 @@ export class FoundryStepExecutor {
         // way.
         for (const hostname of droppedHostnames) {
             const [cname] = await cf.findDnsRecord(zone.id, hostname, 'CNAME');
-            if (cname && (cname.content === dnsTarget || previousTargets.has(cname.content))) {
+            // An adopted tunnel's CNAME is deleted only if foundry created it.
+            const mine = !adopted ||
+                createdDnsRecords((await tunnelRow())?.settings).some((r) => r.id === cname?.id);
+            if (cname && mine && (cname.content === dnsTarget || previousTargets.has(cname.content))) {
                 await cf.deleteDnsRecord(zone.id, cname.id);
             }
             tracked.delete(trackedTunnelDnsEntry(domain, hostname));
@@ -2975,9 +3911,9 @@ export class FoundryStepExecutor {
         // #177: what this step wrote from the platform, so `planMail` can see a later change.
         context.recordScopeId(ORG_MAIL_APPLIED_APEX_SCOPE_KEY, options.apex);
         context.recordScopeId(ORG_MAIL_APPLIED_HOST_SCOPE_KEY, options.mailHost);
-        await this.ensureOwnerMailbox(org, mailOrg, context);
+        await this.ensureOwnerMailbox(org, mailOrg, options, context);
         await this.ensureOrgLettermintRelay(org, mailOrg, result.domain, context);
-        await this.ensureRoleMailboxes(org, mailOrg, result.domain, context);
+        await this.ensureRoleMailboxes(org, mailOrg, result.domain, options, context);
         return { resourceId: result.domain };
     }
     /**
@@ -3018,7 +3954,7 @@ export class FoundryStepExecutor {
      * so a second apply never calls `MailPort.createMailbox` again, rather
      * than relying on that port method's own duplicate refusal.
      */
-    async ensureOwnerMailbox(org, mailOrg, context) {
+    async ensureOwnerMailbox(org, mailOrg, options, context) {
         if (!org.owner)
             return;
         const address = org.mail.ownerMailboxAddress ?? null;
@@ -3029,7 +3965,7 @@ export class FoundryStepExecutor {
         await this.ports.mail.createMailbox(mailOrg, {
             address,
             name: `${org.owner.givenName} ${org.owner.familyName}`,
-        });
+        }, options);
         context.recordScopeId(MAIL_OWNER_MAILBOX_SCOPE_KEY, address);
     }
     /**
@@ -3042,7 +3978,7 @@ export class FoundryStepExecutor {
      * apply (or a retry after a crash) skips what exists rather than relying
      * on the mail server's own duplicate refusal.
      */
-    async ensureRoleMailboxes(org, mailOrg, domain, context) {
+    async ensureRoleMailboxes(org, mailOrg, domain, options, context) {
         const declared = org.mail.roleMailboxes ?? [];
         if (declared.length === 0)
             return;
@@ -3054,7 +3990,7 @@ export class FoundryStepExecutor {
             if (created.has(entry))
                 continue;
             try {
-                await this.ports.mail.createMailbox(mailOrg, { address, name: local });
+                await this.ports.mail.createMailbox(mailOrg, { address, name: local }, options);
             }
             catch (error) {
                 // A crash between create and record leaves the mailbox made but
@@ -3316,12 +4252,16 @@ export class FoundryStepExecutor {
                     return;
                 }
                 case 'cloudflare:tunnel': {
+                    // An adopted tunnel and connector are never deleted (#312).
+                    if (await this.isAdopted(org, adoptedTunnelKey(org), target.id))
+                        return;
                     // #235: the connector app first, its own 404 handled locally --
                     // a retry where this already succeeded must still reach
                     // `deleteTunnel` below, which the outer catch's own 404 handling
                     // would otherwise short-circuit before it ran.
                     const connectorAppId = recordedIds[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY];
-                    if (connectorAppId) {
+                    if (connectorAppId &&
+                        !(await this.isAdopted(org, adoptedConnectorKey(org), connectorAppId))) {
                         try {
                             await this.ports.coolify.deleteApplication(connectorAppId);
                         }
@@ -3406,9 +4346,13 @@ export class FoundryStepExecutor {
                     await this.ports.cloudflare.deleteAccessApp(target.id);
                     return;
                 case 'coolify:app':
+                    if (declaredAdoptUuids(org).has(target.id))
+                        return;
                     await this.ports.coolify.deleteApplication(target.id);
                     return;
                 case 'coolify:database':
+                    if (declaredAdoptUuids(org).has(target.id))
+                        return;
                     await this.ports.coolify.deleteDatabase(target.id);
                     return;
                 case 'zitadel:app': {
@@ -3469,3 +4413,10 @@ export function isNotFoundError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return /^\S+ \S+ \S+ → 404:/.test(message);
 }
+/** Whether the API answered with an error (a status), as opposed to a timeout or network failure. */
+function isApiError(error) {
+    if (typeof error?.status === 'number')
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /^\S+ \S+ \S+ → \d{3}:/.test(message);
+}