@wtfalch/foundry 0.10.0 → 0.12.0

package/dist/plan/executor.js

@@ -1,15 +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 { 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 { 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, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, 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
@@ -293,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
@@ -526,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
 // ---------------------------------------------------------------------------
@@ -547,6 +671,8 @@ 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':
@@ -1088,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 = org.hosting.entries.find((e) => appStepKey(org, e.key) === action.key);
         if (!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 };
@@ -1120,9 +1738,9 @@ 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
@@ -1132,6 +1750,7 @@ export class FoundryStepExecutor {
         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;
@@ -1143,14 +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({
@@ -1182,26 +1805,39 @@ export class FoundryStepExecutor {
         // recorded below leaves the old one, so the retry patches the same
         // difference again.
         const want = appSettingsOf(entry);
-        const patch = {};
-        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)
+        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(patch.base_directory ||
+        const settingsNeedDeploy = Boolean((entry.adopt && context.recordedIds()[pendingKey]) ||
+            patch.base_directory ||
             patch.publish_directory ||
             patch.ports_exposes ||
             patch.domains !== undefined ||
@@ -1212,7 +1848,8 @@ export class FoundryStepExecutor {
         // 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, '_'));
@@ -1229,7 +1866,10 @@ 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), appNameFor(org, entry));
+        // 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.
@@ -1249,6 +1889,8 @@ export class FoundryStepExecutor {
         // 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);
@@ -1262,7 +1904,7 @@ export class FoundryStepExecutor {
         // actually resolved a mail domain for this org.
         // 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) {
+        if (entry.key === APP_ENTRY_KEY && !entry.adopt) {
             await this.ensureAppLettermintMail(appId, org, context, Boolean(existing));
         }
         return { resourceId: appId };
@@ -1307,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 {
@@ -1343,7 +1997,7 @@ export class FoundryStepExecutor {
         // before app on the same apply -- `diff.ts`'s `computePlanDetail`).
         const dbEntry = org.hosting.entries.find((e) => e.database);
         const appId = dbEntry && context.recordedIds()[`coolify:app:${appStepKey(org, dbEntry.key)}`];
-        if (dbEntry && appId) {
+        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) {
@@ -1442,16 +2096,7 @@ export class FoundryStepExecutor {
      */
     async pushAppEnv(appId, org, entry, context, authIssuer) {
         const recorded = context.recordedIds();
-        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 },
-        ];
+        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.
@@ -1461,27 +2106,10 @@ export class FoundryStepExecutor {
             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`);
             }
-            for (const [key, value] of Object.entries(authEnv))
-                envs.push({ key, value });
             const appKey = await this.ensureAuthAppKey(appId);
             if (appKey)
                 envs.push({ key: 'AUTH_APP_KEY', value: appKey });
         }
-        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 });
         // 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
@@ -1498,7 +2126,22 @@ 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.
@@ -1700,9 +2343,13 @@ export class FoundryStepExecutor {
      */
     async ensureOrgLettermintRelay(org, mailOrg, mailDomain, context) {
         const relayName = `${org.slug}-relay`;
+        // #345: `mailOrg.domain` is absent for a level-1 org -- `mailDomain` is
+        // `applyOrgMail`'s own resolved result, the one domain `MailPort`'s
+        // relay methods ever need.
+        const relayOrg = { ...mailOrg, domain: mailDomain };
         const [projects, hasRelay] = await Promise.all([
             this.ports.lettermint.listProjects(),
-            this.ports.mail.hasOrgRelay(mailOrg),
+            this.ports.mail.hasOrgRelay(relayOrg),
         ]);
         // The recorded project, not "the only one": a leftover duplicate whose
         // delete keeps failing must not force a fresh mint on every apply.
@@ -1725,7 +2372,7 @@ export class FoundryStepExecutor {
                 // The restriction covers old and new projects, so the old one keeps
                 // sending until the route switches.
                 await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects);
-                await this.ports.mail.applyOrgRelay(mailOrg, created.token);
+                await this.ports.mail.applyOrgRelay(relayOrg, created.token);
             }
             catch (err) {
                 await this.discardLettermintProject(created.project.id);
@@ -2636,11 +3283,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, {
@@ -2661,6 +3314,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
@@ -2669,8 +3333,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);
@@ -2693,13 +3360,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
@@ -2707,22 +3379,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
@@ -2755,12 +3445,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.
@@ -2770,9 +3462,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(','));
@@ -2800,6 +3496,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
@@ -2841,7 +3611,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;
@@ -2855,7 +3625,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);
             }
         }
@@ -2929,12 +3699,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 = 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');
@@ -2955,6 +3728,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`);
@@ -2975,13 +3753,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) {
@@ -3005,7 +3813,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));
@@ -3104,9 +3915,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 };
     }
     /**
@@ -3147,7 +3958,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;
@@ -3158,7 +3969,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);
     }
     /**
@@ -3171,7 +3982,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;
@@ -3183,7 +3994,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
@@ -3254,7 +4065,9 @@ export class FoundryStepExecutor {
         const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
         if (!mailDomain)
             return;
-        await this.ports.mail.removeOrgRelay(mailOrg);
+        // #345: `mailOrg.domain` is absent for a level-1 org -- the previously
+        // recorded mail domain is the one `MailPort.removeOrgRelay` needs.
+        await this.ports.mail.removeOrgRelay({ ...mailOrg, domain: mailDomain });
         const names = new Set([`${org.slug}-app`, `${org.slug}-relay`]);
         const projects = await this.ports.lettermint.listProjects();
         for (const project of projects) {
@@ -3445,12 +4258,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);
                         }
@@ -3535,9 +4352,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': {
@@ -3598,3 +4419,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);
+}