@wtfalch/foundry 0.39.6 → 0.41.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, EntryGate, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceSchema, ServicesConfig, VersionPin, VersionPinPart, } from './org.js';
-export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateVersionPin, validateSite, } from './org.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, EntryGate, EntryVolume, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, EnvHeldSecret, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceSchema, ServicesConfig, VersionPin, VersionPinPart, } from './org.js';
+export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateVersionPin, validateSite, } from './org.js';
 export type { DeclaredPlatform, PlatformService, PlatformServiceKey, PlatformSfuService, HeartbeatsProvider, } from './platform.js';
 export { PLATFORM_SERVICE_KEYS, HEARTBEATS_PROVIDERS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 import { type PinnedVersions } from './bootstrap/versions.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateVersionPin, validateSite, } from './org.js';
+export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateVersionPin, validateSite, } from './org.js';
 export { PLATFORM_SERVICE_KEYS, HEARTBEATS_PROVIDERS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 // archon#273: the pinned platform service versions the planner deploys, so a
 // host can show declared against running. Readonly: it is the planner's own

package/dist/org.d.ts

@@ -323,6 +323,12 @@ export interface HostingEntry {
      * restricted.
      */
     capabilities?: 'restricted' | 'standard';
+    /**
+     * Named volumes that survive a redeploy, each mounted at an absolute path in the app container. The app step
+     * creates each one once, found by mount path, and restarts an app that was already running. An apply never
+     * removes one. Absent means none besides the log volume.
+     */
+    volumes?: EntryVolume[];
     /** Deploy on every push to `branch`. A host should declare `false`; foundry creates every other app with auto-deploy off. */
     autoDeploy: boolean;
     /**
@@ -350,6 +356,15 @@ export interface HostingEntry {
      */
     worker?: WorkerConfig;
 }
+/** One named volume on a hosting entry's app. */
+export interface EntryVolume {
+    /** A DNS label, unique per entry. The volume is named `<app name>-<name>`. */
+    name: string;
+    /** An absolute path in the container. Never `/app/logs`, which the log volume holds. */
+    mountPath: string;
+}
+/** The most volumes one entry may declare. */
+export declare const MAX_ENTRY_VOLUMES = 8;
 /** One Cloudflare Access gate over some of an entry's `hostnames`. */
 export interface EntryGate {
     /** A DNS label, unique in the org. It names the plan step and the edge gate. */
@@ -472,8 +487,8 @@ export declare const EDGE_ENTRY_ENV_NAMES: readonly ["EDGE_URL", "EDGE_API_KEY"]
  * looks like a secret. `{ from }` names a value the plan already mints.
  */
 export type EnvValue = string | {
-    from: Exclude<AppEnvSource, 'sharedSecret'>;
-} | EnvSharedSecret;
+    from: Exclude<AppEnvSource, 'sharedSecret' | 'heldSecret'>;
+} | EnvSharedSecret | EnvHeldSecret;
 /**
  * A secret foundry generates once and holds under an org-scoped ref. Every
  * entry of the same org that names the same `name` gets the same value; an
@@ -484,6 +499,16 @@ export interface EnvSharedSecret {
     from: 'sharedSecret';
     name: string;
 }
+/**
+ * A secret the operator holds, written to the entry's env only. `name` is the
+ * env name it is declared under. The operator puts the value under
+ * {@link heldEnvRef}; foundry never generates it, and it never reaches a plan,
+ * a log or an error.
+ */
+export interface EnvHeldSecret {
+    from: 'heldSecret';
+    name: string;
+}
 /** The org's `app` entry: today's one app. */
 export declare function appEntry(hosting: HostingConfig): HostingEntry | undefined;
 /**
@@ -493,9 +518,9 @@ export declare function appEntry(hosting: HostingConfig): HostingEntry | undefin
  * sends from. Each is read from `StepExecutionContext.recordedIds()` in
  * `executor.ts`'s `pushAppEnv`, never minted again there.
  */
-export type AppEnvSource = 'filesOrganisationId' | 'aiOrganisationId' | 'mailDomain' | 'sharedSecret';
+export type AppEnvSource = 'filesOrganisationId' | 'aiOrganisationId' | 'mailDomain' | 'sharedSecret' | 'heldSecret';
 /**
- * `sharedSecret` is the one secret source: {@link EnvSharedSecret}. The
+ * `sharedSecret` ({@link EnvSharedSecret}) and `heldSecret` ({@link EnvHeldSecret}) are the secret sources. The
  * platform's Lettermint key is not a source any more (2026-10-11): each
  * company uses its own mail key.
  */
@@ -504,6 +529,13 @@ export declare const APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
 export declare const SECRET_APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
 /** The held-key ref of an org's shared secret. */
 export declare const sharedSecretRef: (orgId: string, name: string) => string;
+/**
+ * The held-key ref of an entry's `heldSecret` env: where the operator puts the
+ * value. Throws on an input the declaration would not accept. The org id is a
+ * canonical lowercase UUID: the host stores `:` as `-`, so an id that may hold `-`
+ * would let two refs share one stored entry.
+ */
+export declare const heldEnvRef: (orgId: string, entryKey: string, name: string) => string;
 /**
  * `null` when `hosting` is valid; otherwise the reason it is not (#71), same
  * shape as `validateBuyerIdentity` below.

package/dist/org.js

@@ -8,6 +8,8 @@ export const ACCESS_RULE_KINDS = new Set(['bypass', 'service-token']);
 export const DEFAULT_GATE_LIMIT = 3;
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export const APP_ENTRY_KEY = 'app';
+/** The most volumes one entry may declare. */
+export const MAX_ENTRY_VOLUMES = 8;
 /** What an entry's ai key may hold: the most the org's own key holds. */
 export const AI_ENTRY_PERMISSIONS = ['ai.offerings:invoke', 'ai.runs:create'];
 /** The env names `uses.ai` writes; `env` may not name them. */
@@ -41,7 +43,7 @@ export function appEntry(hosting) {
     return hosting.entries.find((entry) => entry.key === APP_ENTRY_KEY);
 }
 /**
- * `sharedSecret` is the one secret source: {@link EnvSharedSecret}. The
+ * `sharedSecret` ({@link EnvSharedSecret}) and `heldSecret` ({@link EnvHeldSecret}) are the secret sources. The
  * platform's Lettermint key is not a source any more (2026-10-11): each
  * company uses its own mail key.
  */
@@ -50,11 +52,41 @@ export const APP_ENV_SOURCES = new Set([
     'aiOrganisationId',
     'mailDomain',
     'sharedSecret',
+    'heldSecret',
 ]);
 /** The sources whose value is a secret: resolved at apply time, never recorded. */
-export const SECRET_APP_ENV_SOURCES = new Set(['sharedSecret']);
+export const SECRET_APP_ENV_SOURCES = new Set([
+    'sharedSecret',
+    'heldSecret',
+]);
 /** The held-key ref of an org's shared secret. */
 export const sharedSecretRef = (orgId, name) => `foundry:shared-secret:${orgId}:${name}`;
+const HELD_ENV_ORG_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The host maps `:` to `-` in a stored id and stores at most 128 characters; the ref's fixed part is 52. */
+const HELD_ENV_REF_MAX = 128;
+const HELD_ENV_REF_FIXED = 52;
+const HELD_ENV_ENTRY_KEY = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+const HELD_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * The held-key ref of an entry's `heldSecret` env: where the operator puts the
+ * value. Throws on an input the declaration would not accept. The org id is a
+ * canonical lowercase UUID: the host stores `:` as `-`, so an id that may hold `-`
+ * would let two refs share one stored entry.
+ */
+export const heldEnvRef = (orgId, entryKey, name) => {
+    if (!HELD_ENV_ORG_ID.test(orgId))
+        throw new Error('heldEnvRef: orgId is not a valid org id');
+    if (!HELD_ENV_ENTRY_KEY.test(entryKey)) {
+        throw new Error('heldEnvRef: entryKey must be a DNS label (lowercase letters, digits, hyphens)');
+    }
+    if (!HELD_ENV_NAME.test(name)) {
+        throw new Error('heldEnvRef: name must be an env var name (letters, digits, underscores)');
+    }
+    if (HELD_ENV_REF_FIXED + entryKey.length + name.length > HELD_ENV_REF_MAX) {
+        throw new Error(`heldEnvRef: the ref would be longer than ${HELD_ENV_REF_MAX} characters`);
+    }
+    return `org:${orgId}:entry:${entryKey}:env:${name}`;
+};
 const ISSUER_APP_KINDS = new Set(['web', 'native', 'api']);
 const HOSTING_BUILD_PACKS = new Set([
     'dockerfile',
@@ -297,11 +329,30 @@ function validateEntryHostnames(hosting, names) {
     return null;
 }
 const ENTRY_KEY = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+const VOLUME_MOUNT_PATH = /^(\/(?!\.\.?(\/|$))[A-Za-z0-9._-]+)+$/;
+/** The log volume's mount path; `executor.ts`'s `LOG_DIR` is the same value. */
+const LOG_DIR_PATH = '/app/logs';
+/** Paths a volume would hide or nest under: the app's code, and the system roots a container needs. */
+const VOLUME_FORBIDDEN_ROOTS = [
+    '/bin',
+    '/boot',
+    '/dev',
+    '/etc',
+    '/lib',
+    '/lib64',
+    '/proc',
+    '/run',
+    '/sbin',
+    '/sys',
+    '/usr',
+    '/var/run',
+];
+const VOLUME_MOUNT_PATH_MAX = 255;
 const REPO = /^wtfalch\/[A-Za-z0-9._-]+$/;
 // The env names `pushAppEnv` and `pushDatabaseUrl` set themselves.
 const FOUNDRY_ENV_NAME = /^(APP_URL|LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$/;
 const SECRET_ENV_NAME = /_(KEY|SECRET|TOKEN|PASSWORD)$/;
-const HELD_SECRETS = 'held secrets are not available yet';
+const HELD_SECRETS = "declare it as { from: 'heldSecret' }, not a plain value";
 /** The rules for one {@link HostingEntry}; `null` when it is valid. */
 function validateHostingEntry(entry, enabled) {
     const at = `hosting.entries '${entry.key}'`;
@@ -338,6 +389,9 @@ function validateHostingEntry(entry, enabled) {
     if (entry.database && !enabled) {
         return `${at} database requires hosting.enabled`;
     }
+    const invalidVolumes = validateEntryVolumes(entry, at);
+    if (invalidVolumes)
+        return invalidVolumes;
     for (const [name, value] of Object.entries(entry.env)) {
         if (!name) {
             return `${at} env needs a non-empty env var name`;
@@ -355,6 +409,14 @@ function validateHostingEntry(entry, enabled) {
             if (value.from === 'sharedSecret' && !ENTRY_KEY.test(value.name ?? '')) {
                 return `${at} env '${name}' sharedSecret needs a name (lowercase letters, digits and hyphens)`;
             }
+            if (value.from === 'heldSecret') {
+                if (value.name !== name) {
+                    return `${at} env '${name}' heldSecret name must be '${name}', the env name it is declared under`;
+                }
+                if (!HELD_ENV_NAME.test(name)) {
+                    return `${at} env '${name}' heldSecret needs an env name of letters, digits and underscores`;
+                }
+            }
         }
         else if (SECRET_ENV_NAME.test(name) || (name.endsWith('_URL') && urlHasPassword(value))) {
             return `${at} env '${name}' looks like a secret: ${HELD_SECRETS}`;
@@ -362,6 +424,49 @@ function validateHostingEntry(entry, enabled) {
     }
     return null;
 }
+/** `volumes`: a bounded list of named volumes at distinct absolute paths, none on the log volume's path or name,
+ * on `/app` or under a system path. */
+function validateEntryVolumes(entry, at) {
+    const volumes = entry.volumes;
+    if (volumes === undefined)
+        return null;
+    if (!Array.isArray(volumes))
+        return `${at} volumes must be a list`;
+    if (volumes.length > MAX_ENTRY_VOLUMES) {
+        return `${at} volumes holds at most ${MAX_ENTRY_VOLUMES} volumes`;
+    }
+    const names = new Set();
+    const paths = new Set();
+    for (const volume of volumes) {
+        const { name, mountPath } = volume ?? {};
+        if (typeof name !== 'string' || !ENTRY_KEY.test(name)) {
+            return `${at} volumes needs a name that is a DNS label (lowercase letters, digits and hyphens, 1-63 characters)`;
+        }
+        if (name === 'logs') {
+            return `${at} volumes name 'logs' is the log volume's, which every app already has`;
+        }
+        if (names.has(name))
+            return `${at} volumes name '${name}' is not unique`;
+        names.add(name);
+        if (typeof mountPath !== 'string' || !VOLUME_MOUNT_PATH.test(mountPath)) {
+            return `${at} volumes '${name}' mountPath must be an absolute path of letters, digits, '.', '_', '-' and '/', with no '..', no empty part and no trailing '/'`;
+        }
+        if (mountPath.length > VOLUME_MOUNT_PATH_MAX) {
+            return `${at} volumes '${name}' mountPath holds at most ${VOLUME_MOUNT_PATH_MAX} characters`;
+        }
+        if (mountPath === LOG_DIR_PATH || mountPath.startsWith(`${LOG_DIR_PATH}/`)) {
+            return `${at} volumes '${name}' mountPath ${LOG_DIR_PATH} is the log volume's, which every app already has`;
+        }
+        if (mountPath === '/app' ||
+            VOLUME_FORBIDDEN_ROOTS.some((root) => mountPath === root || mountPath.startsWith(`${root}/`))) {
+            return `${at} volumes '${name}' mountPath must not be /app or a system path (${VOLUME_FORBIDDEN_ROOTS.join(', ')})`;
+        }
+        if (paths.has(mountPath))
+            return `${at} volumes mountPath '${mountPath}' is not unique`;
+        paths.add(mountPath);
+    }
+    return null;
+}
 /**
  * `uses.auth`: its two switches are known values, sign-up is never open
  * into the staff organisation, the entry has an exact

package/dist/plan/diff.js

@@ -1,5 +1,5 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
-import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, ownerMailboxRecorded, ownerMailboxes, ownsServices, } from '../org.js';
+import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, heldEnvRef, ownerMailboxRecorded, ownerMailboxes, ownsServices, } from '../org.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
 import { BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_MAIL_TOKEN_ENV, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
@@ -19,7 +19,7 @@ import { hasAdoptedResources, networkMoveNeeded, planNetworkMove } from './netwo
 import { OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY, OWN_JOBS_BLOCKED_KEY, OWN_MAIL_BLOCKED_KEY, OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, OWN_SIGNIN_DB_MOVE_BLOCKED_KEY, planOwnAuth, planOwnFiles, planOwnFilesR2, planOwnJobs, planOwnMail, planOwnSfu, planSigninDbMove, } from './own-diff.js';
 import { ownDnsHostnames } from './own-dns.js';
 import { ownHostnames } from './own-hostnames.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, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, appEnvAppliedScopeKey, appFolderDiffers, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, serviceDbEnvAppliedScopeKey, versionNotAppliedLine, zitadelAppIdTokenUserinfoAppliedScopeKey, } 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, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, appEnvAppliedScopeKey, appFolderDiffers, appSecretAvailability, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, serviceDbEnvAppliedScopeKey, versionNotAppliedLine, zitadelAppIdTokenUserinfoAppliedScopeKey, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS, } from './platform-org.js';
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY, CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY, appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec, entryOikosHostnames, entryRoutes, entryRoutesMarker, } from './proxy-labels.js';
@@ -2674,6 +2674,13 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
  * from it, which it deletes instead of parking: nothing can redeploy it.
  */
 const RETIRED_DEFAULT_APP_REPO = 'wtfalch/foundry';
+/** What the provision step says about the entry's declared volumes; empty when it declares none. */
+function volumesNote(entry) {
+    const volumes = entry?.volumes ?? [];
+    return volumes.length === 0
+        ? ''
+        : ` with volumes ${volumes.map((v) => `${v.name} at ${v.mountPath}`).join(', ')}`;
+}
 /**
  * The org's own app on Coolify (`org.ts`'s `HostingConfig.enabled`, #71), a
  * per-org singleton resource modeled on {@link planSite}: park, not delete,
@@ -2713,11 +2720,9 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
     // other entry is named in them.
     const label = entryKey === APP_ENTRY_KEY ? 'app' : `${entryKey} app`;
     const blockedKey = (rest) => entryKey === APP_ENTRY_KEY ? `coolify:app:${rest}` : `coolify:app:${entryKey}:${rest}`;
-    const { marker: wantedEnv, unresolved, unresolvedSecrets, } = entry
-        ? resolveAppEnv(org, entry, recordedIds, {
-            sharedSecret: readiness.canHoldSecrets === true,
-        })
-        : { marker: {}, unresolved: [], unresolvedSecrets: [] };
+    const { marker: wantedEnv, unresolved, unresolvedSecrets, heldSecrets, unresolvedHeld, } = entry
+        ? resolveAppEnv(org, entry, recordedIds, appSecretAvailability(org, entry, readiness))
+        : { marker: {}, unresolved: [], unresolvedSecrets: [], heldSecrets: [], unresolvedHeld: [] };
     const stepKey = appStepKey(org, entryKey);
     const blocked = entry
         ? unresolved
@@ -2732,6 +2737,24 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
         unresolvedSecrets.map(([name, source]) => ({
             description: `${org.slug}'s ${label} env ${name} is blocked, not planned: ${`its source ${source} needs a held-key store that can put, and the host has none`}`,
             key: blockedKey(`env:${name}`),
+        })))
+            .concat(
+        // The ref to put the value under, never a value.
+        unresolvedHeld.map((name) => ({
+            description: `${org.slug}'s ${label} env ${name} is blocked, not planned: ${readiness.heldEnv?.invalid?.includes(`${entryKey}/${name}`)
+                ? `held secret ${name} of entry '${entryKey}' fits no held-key ref (the org id must be a lowercase UUID and the ref at most 128 characters)`
+                : readiness.heldEnv?.store
+                    ? `held secret ${name} of entry '${entryKey}' has no value held (ref ${heldEnvRef(org.id, entryKey, name)})`
+                    : `held secret ${name} of entry '${entryKey}' needs a held-key store, and the host has none`}`,
+            key: blockedKey(`env:${name}`),
+        })))
+            .concat(
+        // Held, but the live env could not be read: no step, so the plan can still end empty.
+        heldSecrets
+            .filter((name) => readiness.heldEnv?.unreadable?.includes(heldEnvRef(org.id, entryKey, name)))
+            .map((name) => ({
+            description: `${org.slug}'s ${label} env ${name} is blocked, not planned: the live value of held secret ${name} of entry '${entryKey}' could not be read`,
+            key: blockedKey(`env:${name}`),
         })))
         : [];
     // #491: the `app` entry's own Lettermint work (`executor.ts`'s
@@ -2781,7 +2804,7 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
         });
     }
     const refused = noRepo || composeBuilt;
-    const toggled = planHostingToggle('coolify', 'app', entry !== undefined && !refused, org, byKey, claimed, () => `provision ${org.slug}'s ${label}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
+    const toggled = planHostingToggle('coolify', 'app', entry !== undefined && !refused, org, byKey, claimed, () => `provision ${org.slug}'s ${label}${volumesNote(entry)}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
     // #447: only the live app's own `git_repository` decides, never the
     // declared entry (a `repo: null` entry can sit over a bespoke app, which is
     // parked as before). Only the `app` key ever held the default app, and an
@@ -2837,6 +2860,28 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             blocked,
         };
     }
+    // A declared volume the app does not hold yet is created by the same step. Never the reverse: a
+    // volume the entry no longer declares is left alone. A reader that did not list volumes
+    // (`volumeMounts` absent) reads as compliant, like `hasLogVolume`.
+    const mounted = live.config.volumeMounts;
+    const missingVolumes = Array.isArray(mounted)
+        ? (entry.volumes ?? []).filter((v) => !mounted.includes(v.mountPath))
+        : [];
+    if (missingVolumes.length > 0) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `create ${org.slug}'s ${label} volumes ${missingVolumes
+                        .map((v) => `${v.name} at ${v.mountPath}`)
+                        .join(', ')} and restart it`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
     // #543: a human turning the health check off in the Coolify UI (or an app
     // applied before this patch existed) is noticed the same way `hasLogVolume`
     // just above is -- `coolifyApp` already sends the quartet on every run, so
@@ -2911,6 +2956,23 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             blocked,
         };
     }
+    // A held secret is planned only while its live production value differs from the held one
+    // (the plan read that in memory), so a converged app plans nothing. `pushAppEnv` restarts the
+    // app only when the live value differs.
+    const staleHeld = heldSecrets.filter((name) => readiness.heldEnv?.differs?.includes(heldEnvRef(org.id, entryKey, name)));
+    if (staleHeld.length > 0) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `write ${org.slug}'s ${label} held secret env ${staleHeld.join(', ')} (values read at apply)`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
     // F5 (rule 3): who signs in, which client and which issuer reach an app
     // that is already live. `pushAppEnv` records what it pushed.
     if (entry.uses?.auth &&
@@ -3018,13 +3080,14 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, re
         // The same availability the plan's marker used: the executor records its
         // marker from this, never from its own port, so the two cannot disagree.
         const usesSecrets = org.hosting.entries.some((e) => e.key === key &&
-            Object.values(e.env).some((v) => typeof v !== 'string' && v.from === 'sharedSecret'));
+            Object.values(e.env).some((v) => typeof v !== 'string' && (v.from === 'sharedSecret' || v.from === 'heldSecret')));
         if (usesSecrets && app.step && app.step.action.desired.enabled !== false) {
+            const entry = org.hosting.entries.find((e) => e.key === key);
             app.step.action.desired = {
                 ...app.step.action.desired,
-                secretSources: {
-                    sharedSecret: readiness.canHoldSecrets === true,
-                },
+                secretSources: entry
+                    ? appSecretAvailability(org, entry, readiness)
+                    : { sharedSecret: readiness.canHoldSecrets === true },
             };
         }
         if (app.step && app.step.action.desired.enabled !== false) {

package/dist/plan/executor.d.ts

@@ -2138,6 +2138,14 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * one).
      */
     private ensureLogVolume;
+    /**
+     * The entry's declared `volumes`: each is created once, found by mount path
+     * like {@link ensureLogVolume}'s, and never removed or changed here. One
+     * restart after the last creation, only for an app that was already running.
+     * A failure part way leaves the volumes already created in place; the next
+     * apply finds them by path and creates the rest.
+     */
+    private ensureEntryVolumes;
     /**
      * F6: a nightly dump of one of the company's databases to the platform's
      * backup bucket. The schedule is found before it is created
@@ -2212,6 +2220,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * generates from `domains`. The router names use the app's own name, which is unique per company.
      */
     private routedLabels;
+    /**
+     * The value the operator holds for an entry's `heldSecret` env, registered for redaction before
+     * anything else can see it. The plan found it held; a value gone since stops the step, and the
+     * error names the ref, never a value.
+     */
+    private readHeldEnv;
     /**
      * The org's shared secret `name`: read from the held keys, else generated
      * and held first, so a crash after the `put` and before the env write

package/dist/plan/executor.js

@@ -4,7 +4,7 @@ import { URL } from 'node:url';
 import { coolifyImageFor } from '../bootstrap/versions.js';
 import { redactSecrets } from '../calls-sfu-deploy-support.js';
 import { resolveCallsSfuUrls } from '../calls-sfu.js';
-import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, ownerMailboxRecorded, ownerMailboxes, ownsServices, sharedSecretRef, } from '../org.js';
+import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, heldEnvRef, ownerMailboxRecorded, ownerMailboxes, ownsServices, sharedSecretRef, } from '../org.js';
 import { adoptedKeysUnreadable, parseAdoptSnapshot } from './adopt.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, AGORA_CLIENT_ID_SCOPE_KEY, AGORA_DEPLOYED_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, chatCallsApplied, chatHasUpstreams, chatIntrospectionAppName, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
 import { BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_DATABASE_SCOPE_KEY, BOULE_DEPLOYED_SCOPE_KEY, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, bouleEnvDrift, bouleHostnameFor, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
@@ -2515,6 +2515,7 @@ export class FoundryStepExecutor {
         // call -- see its own doc comment for why that decides whether to
         // restart it.
         await this.ensureLogVolume(appId, org, Boolean(existing), appNameFor(org, entry));
+        await this.ensureEntryVolumes(appId, entry, 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.
@@ -2624,6 +2625,31 @@ export class FoundryStepExecutor {
             await this.ports.coolify.restart(appId);
         }
     }
+    /**
+     * The entry's declared `volumes`: each is created once, found by mount path
+     * like {@link ensureLogVolume}'s, and never removed or changed here. One
+     * restart after the last creation, only for an app that was already running.
+     * A failure part way leaves the volumes already created in place; the next
+     * apply finds them by path and creates the rest.
+     */
+    async ensureEntryVolumes(appId, entry, wasAlreadyRunning, appName) {
+        if (!entry.volumes?.length)
+            return;
+        const storages = await this.ports.coolify.listStorages(appId);
+        const mounted = new Set((storages.persistent_storages ?? []).map((s) => s.mount_path));
+        let created = false;
+        for (const volume of entry.volumes) {
+            if (mounted.has(volume.mountPath))
+                continue;
+            await this.ports.coolify.createPersistentStorage(appId, {
+                name: `${appName}-${volume.name}`,
+                mount_path: volume.mountPath,
+            });
+            created = true;
+        }
+        if (created && wasAlreadyRunning)
+            await this.ports.coolify.restart(appId);
+    }
     /**
      * F6: a nightly dump of one of the company's databases to the platform's
      * backup bucket. The schedule is found before it is created
@@ -2866,6 +2892,17 @@ export class FoundryStepExecutor {
                 value: await this.ensureSharedSecret(org, source.name, recorded),
             });
         }
+        const heldEnvs = [];
+        for (const name of resolved.heldSecrets) {
+            heldEnvs.push({ key: name, value: await this.readHeldEnv(org, entry.key, name) });
+        }
+        envs.push(...heldEnvs);
+        // A held value has no version the plan can read, so the live env decides whether it changed.
+        let heldChanged = false;
+        if (heldEnvs.length > 0) {
+            const live = await this.ports.coolify.listEnvs(appId);
+            heldChanged = heldEnvs.some(({ key, value }) => !live.some((e) => e.key === key && !e.is_preview && e.value === value));
+        }
         await this.ports.coolify.bulkUpsertEnvs(appId, envs);
         // `coolifyApp` records `applied` once the restart succeeded, so `planApp`
         // replans this step when the declared map changes (rule 3). Ids and a
@@ -2876,6 +2913,7 @@ export class FoundryStepExecutor {
         const authApplied = JSON.stringify(authEnv);
         return {
             changed: applied !== (recorded[appEnvAppliedScopeKey(entry.key)] ?? '{}') ||
+                heldChanged ||
                 (Boolean(entry.uses?.auth) &&
                     authApplied !== (recorded[entryAuthEnvAppliedScopeKey(entry.key)] ?? '{}')),
             applied,
@@ -2916,6 +2954,20 @@ export class FoundryStepExecutor {
         }
         return { custom_labels: Buffer.from(labels).toString('base64') };
     }
+    /**
+     * The value the operator holds for an entry's `heldSecret` env, registered for redaction before
+     * anything else can see it. The plan found it held; a value gone since stops the step, and the
+     * error names the ref, never a value.
+     */
+    async readHeldEnv(org, entryKey, name) {
+        const ref = heldEnvRef(org.id, entryKey, name);
+        const value = await this.ports.heldKeys?.resolve(ref);
+        if (!value) {
+            throw new Error(`coolify:app for ${org.slug}: held secret ${name} of entry '${entryKey}' is no longer held (ref ${ref})`);
+        }
+        this.handledSecrets.add(value);
+        return value;
+    }
     /**
      * The org's shared secret `name`: read from the held keys, else generated
      * and held first, so a crash after the `put` and before the env write
@@ -5923,6 +5975,7 @@ export class FoundryStepExecutor {
             apex: ownHostnames(org).zone,
             version: action.desired.version,
             project: { ensure: () => this.ensureCoolifyProject(org, context) },
+            ...(context.serverIpv4 ? { serverIpv4: context.serverIpv4 } : {}),
         });
     }
     async jobsRegistration(action, org, context) {

package/dist/plan/live.d.ts

@@ -62,6 +62,13 @@ export interface ZitadelReader {
 }
 export interface CoolifyReader {
     listResources(orgId: OrgId): Promise<LiveResource[]>;
+    /**
+     * Whether the production env `name` of the org's entry app, as it is live now, equals `value`.
+     * Compared in memory and never returned or kept. False when the app is not recorded or has no
+     * such env; throws when the read fails. Optional: without it a held secret's live value cannot
+     * be read, and the plan blocks that env.
+     */
+    liveEnvEquals?(orgId: OrgId, appKey: string, name: string, value: string): Promise<boolean>;
     /**
      * Reads one Coolify project by its uuid, for an org that records none yet
      * (adopt, archon#271). Optional: without it nothing can be adopted.

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

@@ -45,6 +45,8 @@ export interface SfuAppInput {
     /** The pinned LiveKit release tag. */
     version: string;
     project: ProjectSource;
+    /** The platform's declared public IPv4: LiveKit's `node_ip`. Absent: the Coolify server's ip, when it is an IPv4. */
+    serverIpv4?: string;
 }
 /** The compose `ports` lines for a slot: the UDP range and the TCP fallback port, one to one. */
 export declare function sfuComposePorts(slot: number): string[];

package/dist/plan/own-sfu.js

@@ -1,3 +1,4 @@
+import { isIPv4 } from 'node:net';
 import { DIGESTS, VERSIONS } from '../bootstrap/versions.js';
 import { mintLivekitCredentials } from '../calls-sfu-keys.js';
 import { LIVEKIT_SIGNALLING_PORT, sfuSlotPorts } from '../calls-sfu.js';
@@ -132,8 +133,12 @@ export async function provisionSfuApp(scope, deps, target, input) {
     const server = servers.find((s) => s.is_usable && s.is_reachable) ?? servers[0];
     if (!server)
         throw new Error(`${label}: no usable Coolify server is registered`);
-    if (!server.ip)
-        throw new Error(`${label}: the Coolify server has no address to give LiveKit`);
+    // Coolify reports its localhost server as `host.docker.internal`, which LiveKit refuses as `node_ip`
+    // and then restarts forever; the declared address wins, the same rule as the platform's mail server.
+    const nodeIp = input.serverIpv4 ?? (server.ip && isIPv4(server.ip) ? server.ip : undefined);
+    if (!nodeIp) {
+        throw new Error(`${label}: no public IPv4 to give LiveKit; declare the server's public IPv4 as serverIpv4 in the platform config`);
+    }
     const compose = sfuCompose({
         serviceName: target.internal.sfu,
         slot: input.slot,
@@ -213,7 +218,7 @@ export async function provisionSfuApp(scope, deps, target, input) {
             keysJustSet = true;
         }
     }
-    const config = sfuConfig({ slot: input.slot, nodeIp: server.ip, keys });
+    const config = sfuConfig({ slot: input.slot, nodeIp, keys });
     deps.onSecret?.(config);
     const envChanged = liveConfig !== config;
     const pending = Boolean(scope.recordedIds()[OWN_SFU_DEPLOY_PENDING_SCOPE_KEY]) || changed || envChanged;

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

@@ -130,6 +130,12 @@ export interface StepExecutionContext {
      * platform's Docker network, not on `co-<slug>`, so Archon reaches its database. Absent: false.
      */
     readonly ownerCompany?: boolean;
+    /**
+     * The platform's declared public IPv4 (`DeclaredPlatform.serverIpv4`). A company's media server
+     * gives it to LiveKit as `node_ip`: Coolify reports its localhost server as `host.docker.internal`,
+     * which LiveKit refuses. Absent: none declared.
+     */
+    readonly serverIpv4?: string;
     /**
      * Every id foundry has recorded for this org so far — both `system:kind:key`
      * resource ids (`runSteps` records these itself from `execute`'s own return
@@ -753,6 +759,13 @@ export declare class FoundryPlanApply implements PlanApply {
      * org step that needs one is blocked.
      */
     private orgPlatformReadiness;
+    /**
+     * The org's `heldSecret` envs: the refs that hold a value now, which of those differ from the live
+     * production env, which could not be read, and which fit no ref. A resolver that throws counts as
+     * not held. The held value is compared in memory by the reader and dropped; a failed read keeps
+     * only the ref.
+     */
+    private heldEnvReadiness;
     /** An own org's Lettermint key is held. A resolver that throws counts as not held. */
     private ownMailKeyHeld;
     /** Which of an own org's undelivered-secret refs hold a value now, so a rerun resumes instead of blocking. */

package/dist/plan/plan-apply.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { sfuSlotPorts } from '../calls-sfu.js';
-import { ownsServices, validateHosting } from '../org.js';
+import { heldEnvRef, ownsServices, validateHosting } from '../org.js';
 import { PLATFORM_SERVICE_KEYS } from '../platform.js';
 import { AlreadyRunningError, StepFailedError } from '../runner/errors.js';
 import { StaleLeaseError, } from '../store.js';
@@ -908,10 +908,13 @@ export class FoundryPlanApply {
         const checkpoints = [];
         // Backed by the very `serviceIds` map this method persists once, at the
         // end — see `StepExecutionContext`'s doc comment for why.
-        const ownerCompany = (await this.platformDeps?.store.get())?.ownerOrgId === orgId;
+        const declaredPlatform = await this.platformDeps?.store.get();
+        const ownerCompany = declaredPlatform?.ownerOrgId === orgId;
+        const serverIpv4 = declaredPlatform?.serverIpv4 ?? undefined;
         const context = {
             org,
             ownerCompany,
+            ...(serverIpv4 ? { serverIpv4 } : {}),
             recordedIds: () => ({ ...serviceIds }),
             now: () => this.now().getTime(),
             recordScopeId: (key, id) => {
@@ -1163,7 +1166,10 @@ export class FoundryPlanApply {
      * org step that needs one is blocked.
      */
     async orgPlatformReadiness(org, orgRecordedIds) {
-        const base = await this.sharedPlatformReadiness();
+        const base = {
+            ...(await this.sharedPlatformReadiness()),
+            heldEnv: await this.heldEnvReadiness(org),
+        };
         if (!ownsServices(org))
             return base;
         const held = this.platformDeps?.heldKeys;
@@ -1173,6 +1179,57 @@ export class FoundryPlanApply {
             ? { ...readiness, serviceGitRefs: serviceGitRefsOf(platform, org.versionPin) }
             : readiness;
     }
+    /**
+     * The org's `heldSecret` envs: the refs that hold a value now, which of those differ from the live
+     * production env, which could not be read, and which fit no ref. A resolver that throws counts as
+     * not held. The held value is compared in memory by the reader and dropped; a failed read keeps
+     * only the ref.
+     */
+    async heldEnvReadiness(org) {
+        const heldKeys = this.platformDeps?.heldKeys;
+        const refs = [];
+        const differs = [];
+        const unreadable = [];
+        const invalid = [];
+        for (const entry of org.hosting.entries) {
+            for (const [name, value] of Object.entries(entry.env)) {
+                if (typeof value === 'string' || value.from !== 'heldSecret')
+                    continue;
+                let ref;
+                try {
+                    ref = heldEnvRef(org.id, entry.key, name);
+                }
+                catch {
+                    // Fits no ref: the plan blocks it by entry and name; the error text is fixed anyway.
+                    invalid.push(`${entry.key}/${name}`);
+                    continue;
+                }
+                let held;
+                try {
+                    held = await heldKeys?.resolve(ref);
+                }
+                catch {
+                    // Not held: the plan reports the ref, and the error is dropped.
+                    continue;
+                }
+                if (!held)
+                    continue;
+                refs.push(ref);
+                try {
+                    const equal = await this.readers.coolify.liveEnvEquals?.(org.id, appStepKey(org, entry.key), name, held);
+                    if (equal === undefined)
+                        unreadable.push(ref);
+                    else if (!equal)
+                        differs.push(ref);
+                }
+                catch {
+                    // Blocked, not planned: the plan names the env and the entry; the error is dropped.
+                    unreadable.push(ref);
+                }
+            }
+        }
+        return { store: Boolean(heldKeys), refs, differs, unreadable, invalid };
+    }
     /** An own org's Lettermint key is held. A resolver that throws counts as not held. */
     async ownMailKeyHeld(org) {
         const held = this.platformDeps?.heldKeys;

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

@@ -655,7 +655,17 @@ export declare function appliedAppDomains(org: DeclaredOrg, recorded: Readonly<R
 /** Whether the secret sources can be filled right now: a new shared secret can be held. */
 export interface AppSecretAvailability {
     sharedSecret: boolean;
+    /** The env names of the entry's `heldSecret` values that are held now. Absent: none. */
+    heldSecret?: readonly string[];
 }
+/** What the plan decided can be filled for `entry`: the held secrets whose ref holds a value now. */
+export declare function appSecretAvailability(org: DeclaredOrg, entry: HostingEntry, readiness: {
+    canHoldSecrets?: boolean;
+    heldEnv?: {
+        refs: readonly string[];
+        invalid?: readonly string[];
+    };
+}): AppSecretAvailability;
 /**
  * The entry's `env` values that have a value, in env-name order, and the env
  * names whose source has none yet. Shared by `planApp` and the executor's
@@ -675,6 +685,9 @@ export declare function resolveAppEnv(org: DeclaredOrg, entry: HostingEntry, rec
         source: EnvSharedSecret;
     }>;
     unresolvedSecrets: Array<[string, string]>;
+    /** The env names of `heldSecret` values that are held, and those that are not. */
+    heldSecrets: string[];
+    unresolvedHeld: string[];
     marker: Record<string, string>;
 };
 /**

package/dist/plan/platform-diff.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { VERSIONS } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY } from '../org.js';
+import { heldEnvRef } from '../org.js';
 import { VERSION_CHANGE_KIND, } from '../plan.js';
 import { buildDriftNotes } from './build-record.js';
 import { versionChangeNeedsConfirmation } from './confirm-upgrade.js';
@@ -737,6 +738,19 @@ export function appliedAppDomains(org, recorded, entryKey) {
         return JSON.parse(marker);
     return entryKey === APP_ENTRY_KEY ? [legacyAppHostname(org)] : [];
 }
+/** What the plan decided can be filled for `entry`: the held secrets whose ref holds a value now. */
+export function appSecretAvailability(org, entry, readiness) {
+    const refs = new Set(readiness.heldEnv?.refs ?? []);
+    return {
+        sharedSecret: readiness.canHoldSecrets === true,
+        heldSecret: Object.entries(entry.env)
+            .filter(([name, v]) => typeof v !== 'string' &&
+            v.from === 'heldSecret' &&
+            !readiness.heldEnv?.invalid?.includes(`${entry.key}/${name}`) &&
+            refs.has(heldEnvRef(org.id, entry.key, name)))
+            .map(([name]) => name),
+    };
+}
 /**
  * The entry's `env` values that have a value, in env-name order, and the env
  * names whose source has none yet. Shared by `planApp` and the executor's
@@ -758,8 +772,19 @@ export function resolveAppEnv(org, entry, recorded, available = { sharedSecret:
     const unresolved = [];
     const secrets = [];
     const unresolvedSecrets = [];
+    const heldSecrets = [];
+    const unresolvedHeld = [];
     const marker = {};
     for (const [name, declared] of Object.entries(entry.env).sort(([a], [b]) => (a < b ? -1 : 1))) {
+        if (typeof declared !== 'string' && declared.from === 'heldSecret') {
+            if (available.heldSecret?.includes(name)) {
+                heldSecrets.push(name);
+                marker[name] = `secret:heldSecret:${name}`;
+            }
+            else
+                unresolvedHeld.push(name);
+            continue;
+        }
         if (typeof declared !== 'string' && declared.from === 'sharedSecret') {
             const label = `sharedSecret ${declared.name}`;
             if (available.sharedSecret) {
@@ -778,7 +803,7 @@ export function resolveAppEnv(org, entry, recorded, available = { sharedSecret:
         else if (typeof declared !== 'string')
             unresolved.push([name, declared.from]);
     }
-    return { values, unresolved, secrets, unresolvedSecrets, marker };
+    return { values, unresolved, secrets, unresolvedSecrets, heldSecrets, unresolvedHeld, marker };
 }
 /**
  * #172: the resource key `planAi` plans under and `FoundryPlatformStepExecutor`

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

@@ -169,6 +169,20 @@ export interface OrgPlatformReadiness {
     mailKeyHeld?: boolean;
     /** The host's held keys can `put`, so an entry env from `sharedSecret` can be filled. Absent reads as false. */
     canHoldSecrets?: boolean;
+    /**
+     * The org's `heldSecret` env values. `store` is false when the host wired no held-keys reader;
+     * `refs` are the refs that hold a value now; `differs` are those whose live production env is not
+     * the held value (absent counts as different) and `unreadable` those whose live env could not be
+     * read; `invalid` are `<entryKey>/<NAME>` of envs that fit no ref. Refs and names only, never a
+     * value. Absent reads as no store.
+     */
+    heldEnv?: {
+        store: boolean;
+        refs: readonly string[];
+        differs?: readonly string[];
+        unreadable?: readonly string[];
+        invalid?: readonly string[];
+    };
     /**
      * True when the host wired no held-keys reader, so no key could be checked.
      * A missing key is then reported as "no reader given" instead of "not held".

package/dist/plan/providers-readers.d.ts

@@ -105,6 +105,7 @@ export declare class ProvidersCoolifyReader implements CoolifyReader {
     private readonly resolveRecordedIds;
     constructor(client: CoolifyReaderClient, resolveScope: ScopeResolver, resolveRecordedIds: RecordedIds);
     listResources(orgId: OrgId): Promise<LiveResource[]>;
+    liveEnvEquals(orgId: OrgId, appKey: string, name: string, value: string): Promise<boolean>;
     /** The project's resources as Coolify reports them, unmapped: what adopt checks against a declaration. */
     listProject(projectUuid: string): Promise<LiveResource[]>;
 }

package/dist/plan/providers-readers.js

@@ -140,8 +140,9 @@ async function withLogVolumeConfig(client, resource, recorded) {
     }
     try {
         const storages = await client.listStorages(resource.key);
-        const hasLogVolume = (storages.persistent_storages ?? []).some((s) => s.mount_path === LOG_DIR);
-        return { ...resource, config: { ...resource.config, hasLogVolume } };
+        const volumeMounts = (storages.persistent_storages ?? []).map((s) => s.mount_path);
+        const hasLogVolume = volumeMounts.includes(LOG_DIR);
+        return { ...resource, config: { ...resource.config, hasLogVolume, volumeMounts } };
     }
     catch {
         return resource;
@@ -320,6 +321,13 @@ export class ProvidersCoolifyReader {
         const withBouleConfig = await Promise.all(withAgoraConfig.map((r) => withBouleEnvConfig(this.client, r, recorded, liveKeys)));
         return applyRecordedIds(withBouleConfig, recorded);
     }
+    async liveEnvEquals(orgId, appKey, name, value) {
+        const recorded = await this.resolveRecordedIds(orgId);
+        const uuid = Object.entries(recorded).find(([, key]) => key === `app:${appKey}`)?.[0];
+        if (!uuid)
+            return false;
+        return (await this.client.listEnvs(uuid)).some((e) => e.key === name && !e.is_preview && e.value === value);
+    }
     /** The project's resources as Coolify reports them, unmapped: what adopt checks against a declaration. */
     async listProject(projectUuid) {
         return toFoundryResources('coolify', await this.client.listResources(projectUuid));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.39.6",
+  "version": "0.41.1",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",