@wtfalch/foundry 0.16.15 → 0.17.0

package/dist/plan/deploy-health.d.ts

@@ -0,0 +1,136 @@
+/**
+ * #252: the one shared helper every platform step calls between deploying a
+ * new version and recording it as the applied ref.
+ *
+ * Before this, a step that records `platform:*`'s applied hostname/gitRef
+ * called `CoolifyPort.deploy` -- fire-and-forget by design (see its own doc
+ * comment) -- and recorded the new ref right after, with nothing in between
+ * proving the new version had actually landed. A failed deploy leaves the
+ * previous container running and healthy (`@wtfalch/providers`'
+ * `CoolifyDeploymentRecord` doc comment: "`status` reports on the container
+ * that is *running*, and a failed build leaves the previous one running and
+ * healthy"), so the old container's healthy status was being read as the
+ * new deployment's -- exactly what `CLAUDE.md`'s platform-step rule 5 ("no
+ * waiting forever... an old healthy status is never read as the new one")
+ * exists to forbid.
+ *
+ * {@link waitForNewDeployment} closes that gap in two steps, always in this
+ * order:
+ *
+ * 1. `coolify.deployAndWait` -- blocks until *Coolify's own deployment
+ *    record* (not `getApplication`'s live container status) reaches a
+ *    terminal state. Anything but `'finished'` throws immediately: a build
+ *    or deploy failure is a hard stop no health check below could ever
+ *    paper over, and it is the step that actually catches "the old
+ *    container stays healthy while the deployment fails" -- the container's
+ *    own status never moves in that scenario, so only the deployment record
+ *    itself tells the two apart.
+ * 2. The health check named by `health.kind`, decided per call site and
+ *    stated there (#252's own decision):
+ *    - `'version'` -- the service's health response carries a version
+ *      string this service actually exposes; polled until it matches
+ *      `health.expected` exactly. Unambiguous proof it is the *new*
+ *      version specifically, but only usable where the service has one.
+ *    - `'ready'` -- the health url answers 2xx. Works for every service
+ *      with a url this helper's caller can actually reach, including ones
+ *      with no version field (the fallback, not the preferred mode), and
+ *      the old-container loophole this mode alone cannot close ("can be
+ *      fooled by the old container staying up") is already closed by step
+ *      1 having confirmed Coolify's own deployment record finished first.
+ *    - `'deployment-only'` -- no health check at all; step 1 is the whole
+ *      answer. For a step whose app has nothing public wired (no Coolify
+ *      `domains`, tunnel, DNS record -- `platform:ai`/`platform:files`'
+ *      own doc comments say so explicitly) there is no url this helper's
+ *      caller, running outside that app's own Docker network, could ever
+ *      reach, so inventing one to poll would just be a slower, flakier way
+ *      of saying "I called deployAndWait". A step that can only use this
+ *      mode is not unverified the way `'ready'` is *within* `'ready'`'s own
+ *      guarantee -- it is strictly weaker than the other two (a deployment
+ *      that "finished" with a crash-looping container is read as success),
+ *      but it is the one honest answer this helper can give it, and it is
+ *      still what catches #252's named failure (the old container staying
+ *      healthy while the deployment record itself fails), since that
+ *      record is exactly what step 1 reads.
+ *
+ * Throws on any failure -- the deployment itself, or the health check
+ * timing out -- naming `appliedRefDescription` (what is still live, for
+ * whoever reads the error) so the caller's own "record applied ref" line is
+ * never reached. Rule 1 from `CLAUDE.md` applies here too: never call this
+ * from inside a retry loop that could mint a one-time secret again, since a
+ * failed wait is meant to be repaired by re-running the whole step, not
+ * silently retried from inside it.
+ */
+export interface DeployAndWaitPort {
+    deployAndWait(uuid: string, options?: {
+        force?: boolean;
+        attempts?: number;
+        intervalMs?: number;
+    }): Promise<{
+        deploymentUuid: string;
+        status: string;
+    }>;
+}
+/**
+ * How a call site proves the new version is the one that answers (or that
+ * there is nothing for it to reach at all). See this module's own doc
+ * comment for why there are exactly three and no "pick one per call"
+ * default.
+ */
+export type DeployHealthCheck = {
+    readonly kind: 'version';
+    readonly url: string;
+    /** Exact match against the health body's version field. */
+    readonly expected: string;
+    /** Field name in the parsed JSON body (default `'version'`). */
+    readonly field?: string;
+} | {
+    readonly kind: 'ready';
+    readonly url: string;
+} | {
+    /** No reachable url; `coolify.deployAndWait` alone is the check. See this module's doc comment. */
+    readonly kind: 'deployment-only';
+};
+export interface DeployHealthRuntime {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Passed through to `deployAndWait` (default: its own, 90 * 10s = 15 minutes). */
+    deployAttempts?: number;
+    deployIntervalMs?: number;
+    /** `deployAndWait`'s own `force` (default `true` -- see this module's doc comment). */
+    deployForce?: boolean;
+    /** How long to wait for the health check to confirm the new version (default 5 minutes). */
+    readyTimeoutMs?: number;
+    /** Pause between health polls (default 5 seconds). */
+    readyIntervalMs?: number;
+}
+/**
+ * Phase 1 alone: deploys `appId` and blocks until Coolify's own deployment
+ * record reaches a terminal state, throwing unless it is `'finished'`. Split
+ * out of {@link waitForNewDeployment} for a step whose health url only
+ * resolves once *later* work in the same step (archon's/mail's own tunnel
+ * and DNS wiring) has run -- that work must happen between this call and
+ * {@link waitForHealthyVersion}, so the two cannot be one call there. A step
+ * with no such ordering constraint calls {@link waitForNewDeployment}
+ * instead, never this plus {@link waitForHealthyVersion} by hand.
+ */
+export declare function waitForDeploymentFinished(coolify: DeployAndWaitPort, appId: string, runtime: DeployHealthRuntime, label: string, appliedRefDescription: string): Promise<void>;
+/**
+ * Phase 2 alone: the health check named by `health.kind`, with no deploy and
+ * no Coolify polling -- see {@link waitForDeploymentFinished}'s own doc
+ * comment for when a step calls this separately instead of
+ * {@link waitForNewDeployment}. A `'deployment-only'` check is a no-op here
+ * by design: phase 1 was already the whole answer for it.
+ */
+export declare function waitForHealthyVersion(appId: string, health: DeployHealthCheck, runtime: DeployHealthRuntime, sleep: (ms: number) => Promise<void>, label: string, appliedRefDescription: string): Promise<void>;
+/**
+ * Deploys `appId` and does not return until Coolify's own deployment record
+ * says it finished *and* `health` confirms the new version is answering --
+ * {@link waitForDeploymentFinished} then {@link waitForHealthyVersion}, in
+ * that order, for a step with no reason to run anything between them. See
+ * this module's own doc comment for why each half exists; `label` names the
+ * step in every error (`platform:mail`, …) and `appliedRefDescription` names
+ * what is still live so a caller's error is actionable without the helper
+ * itself knowing any step's scope keys.
+ */
+export declare function waitForNewDeployment(coolify: DeployAndWaitPort, appId: string, health: DeployHealthCheck, runtime: DeployHealthRuntime, sleep: (ms: number) => Promise<void>, label: string, appliedRefDescription: string): Promise<void>;

package/dist/plan/deploy-health.js

@@ -0,0 +1,153 @@
+/**
+ * #252: the one shared helper every platform step calls between deploying a
+ * new version and recording it as the applied ref.
+ *
+ * Before this, a step that records `platform:*`'s applied hostname/gitRef
+ * called `CoolifyPort.deploy` -- fire-and-forget by design (see its own doc
+ * comment) -- and recorded the new ref right after, with nothing in between
+ * proving the new version had actually landed. A failed deploy leaves the
+ * previous container running and healthy (`@wtfalch/providers`'
+ * `CoolifyDeploymentRecord` doc comment: "`status` reports on the container
+ * that is *running*, and a failed build leaves the previous one running and
+ * healthy"), so the old container's healthy status was being read as the
+ * new deployment's -- exactly what `CLAUDE.md`'s platform-step rule 5 ("no
+ * waiting forever... an old healthy status is never read as the new one")
+ * exists to forbid.
+ *
+ * {@link waitForNewDeployment} closes that gap in two steps, always in this
+ * order:
+ *
+ * 1. `coolify.deployAndWait` -- blocks until *Coolify's own deployment
+ *    record* (not `getApplication`'s live container status) reaches a
+ *    terminal state. Anything but `'finished'` throws immediately: a build
+ *    or deploy failure is a hard stop no health check below could ever
+ *    paper over, and it is the step that actually catches "the old
+ *    container stays healthy while the deployment fails" -- the container's
+ *    own status never moves in that scenario, so only the deployment record
+ *    itself tells the two apart.
+ * 2. The health check named by `health.kind`, decided per call site and
+ *    stated there (#252's own decision):
+ *    - `'version'` -- the service's health response carries a version
+ *      string this service actually exposes; polled until it matches
+ *      `health.expected` exactly. Unambiguous proof it is the *new*
+ *      version specifically, but only usable where the service has one.
+ *    - `'ready'` -- the health url answers 2xx. Works for every service
+ *      with a url this helper's caller can actually reach, including ones
+ *      with no version field (the fallback, not the preferred mode), and
+ *      the old-container loophole this mode alone cannot close ("can be
+ *      fooled by the old container staying up") is already closed by step
+ *      1 having confirmed Coolify's own deployment record finished first.
+ *    - `'deployment-only'` -- no health check at all; step 1 is the whole
+ *      answer. For a step whose app has nothing public wired (no Coolify
+ *      `domains`, tunnel, DNS record -- `platform:ai`/`platform:files`'
+ *      own doc comments say so explicitly) there is no url this helper's
+ *      caller, running outside that app's own Docker network, could ever
+ *      reach, so inventing one to poll would just be a slower, flakier way
+ *      of saying "I called deployAndWait". A step that can only use this
+ *      mode is not unverified the way `'ready'` is *within* `'ready'`'s own
+ *      guarantee -- it is strictly weaker than the other two (a deployment
+ *      that "finished" with a crash-looping container is read as success),
+ *      but it is the one honest answer this helper can give it, and it is
+ *      still what catches #252's named failure (the old container staying
+ *      healthy while the deployment record itself fails), since that
+ *      record is exactly what step 1 reads.
+ *
+ * Throws on any failure -- the deployment itself, or the health check
+ * timing out -- naming `appliedRefDescription` (what is still live, for
+ * whoever reads the error) so the caller's own "record applied ref" line is
+ * never reached. Rule 1 from `CLAUDE.md` applies here too: never call this
+ * from inside a retry loop that could mint a one-time secret again, since a
+ * failed wait is meant to be repaired by re-running the whole step, not
+ * silently retried from inside it.
+ */
+const DEFAULT_READY_TIMEOUT_MS = 300_000;
+const DEFAULT_READY_INTERVAL_MS = 5_000;
+/** The one terminal `CoolifyDeploymentStatus` that means the new version landed. */
+const DEPLOYMENT_SUCCEEDED = 'finished';
+/**
+ * Phase 1 alone: deploys `appId` and blocks until Coolify's own deployment
+ * record reaches a terminal state, throwing unless it is `'finished'`. Split
+ * out of {@link waitForNewDeployment} for a step whose health url only
+ * resolves once *later* work in the same step (archon's/mail's own tunnel
+ * and DNS wiring) has run -- that work must happen between this call and
+ * {@link waitForHealthyVersion}, so the two cannot be one call there. A step
+ * with no such ordering constraint calls {@link waitForNewDeployment}
+ * instead, never this plus {@link waitForHealthyVersion} by hand.
+ */
+export async function waitForDeploymentFinished(coolify, appId, runtime, label, appliedRefDescription) {
+    let result;
+    try {
+        result = await coolify.deployAndWait(appId, {
+            force: runtime.deployForce ?? true,
+            attempts: runtime.deployAttempts,
+            intervalMs: runtime.deployIntervalMs,
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`${label}: the deployment of ${appId} did not finish (${reason}); ${appliedRefDescription}. Apply again`);
+    }
+    const { status, deploymentUuid } = result;
+    if (status !== DEPLOYMENT_SUCCEEDED) {
+        throw new Error(`${label}: the deployment (${deploymentUuid}) of ${appId} did not finish (status: ${status}); ${appliedRefDescription}. Apply again`);
+    }
+}
+/**
+ * Phase 2 alone: the health check named by `health.kind`, with no deploy and
+ * no Coolify polling -- see {@link waitForDeploymentFinished}'s own doc
+ * comment for when a step calls this separately instead of
+ * {@link waitForNewDeployment}. A `'deployment-only'` check is a no-op here
+ * by design: phase 1 was already the whole answer for it.
+ */
+export async function waitForHealthyVersion(appId, health, runtime, sleep, label, appliedRefDescription) {
+    if (health.kind === 'deployment-only')
+        return;
+    const fetchImpl = runtime.fetch ?? globalThis.fetch;
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    const interval = runtime.readyIntervalMs ?? DEFAULT_READY_INTERVAL_MS;
+    const deadline = now() + timeout;
+    for (;;) {
+        if (await matchesHealth(fetchImpl, health))
+            return;
+        if (now() >= deadline) {
+            const detail = health.kind === 'version'
+                ? `never answered version "${health.expected}" at ${health.url}`
+                : `never answered 2xx at ${health.url}`;
+            throw new Error(`${label}: ${appId} ${detail} within ${Math.round(timeout / 1000)}s; ${appliedRefDescription}. Apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/**
+ * Deploys `appId` and does not return until Coolify's own deployment record
+ * says it finished *and* `health` confirms the new version is answering --
+ * {@link waitForDeploymentFinished} then {@link waitForHealthyVersion}, in
+ * that order, for a step with no reason to run anything between them. See
+ * this module's own doc comment for why each half exists; `label` names the
+ * step in every error (`platform:mail`, …) and `appliedRefDescription` names
+ * what is still live so a caller's error is actionable without the helper
+ * itself knowing any step's scope keys.
+ */
+export async function waitForNewDeployment(coolify, appId, health, runtime, sleep, label, appliedRefDescription) {
+    await waitForDeploymentFinished(coolify, appId, runtime, label, appliedRefDescription);
+    await waitForHealthyVersion(appId, health, runtime, sleep, label, appliedRefDescription);
+}
+async function matchesHealth(fetchImpl, health) {
+    try {
+        const response = await fetchImpl(health.url);
+        if (!response.ok)
+            return false;
+        if (health.kind === 'ready')
+            return true;
+        const body = await response.json().catch(() => undefined);
+        const value = body && typeof body === 'object'
+            ? body[health.field ?? 'version']
+            : undefined;
+        return value === health.expected;
+    }
+    catch {
+        // Not up yet: DNS, the tunnel, the container, or a transient network error.
+        return false;
+    }
+}

package/dist/plan/diff.d.ts

@@ -26,6 +26,15 @@ export interface PlannedStep {
     step: PlanStep;
     action: StepAction;
 }
+/**
+ * A {@link PlannedStep} before `system` is set. Planners build these; the one
+ * place a plan is returned (`withStepSystem`, `step-system.ts`) sets `system`
+ * from the action, so no planner names it by hand.
+ */
+export interface DraftStep {
+    step: Omit<PlanStep, 'system'>;
+    action: StepAction;
+}
 /**
  * Facts about the host's executor ports that an org's plan needs, so a step
  * whose port is not wired is reported blocked instead of planned (rule 2).
@@ -70,9 +79,8 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * `hosting.issuerApps[]` entry rather than a single singleton, since an org
  * can declare more than one ZITADEL app. #80 adds two more singletons,
  * modeled on {@link planIssuer}: `planFilesOrganisation` and
- * `planAiOrganisation`, each planned before its own system's limit step
- * ({@link planStorage}, {@link planAiBudget}) so an org has somewhere for a
- * limit to land, and AI use is switched on, before either limit is ever set.
+ * `planAiOrganisation`, the second planned before {@link planAiBudget} so AI
+ * use is switched on before its own limit is ever set.
  * `planOwners` below adds one more singleton, in a different shape from the
  * rest: the org's owner, invited by ZITADEL email, idempotent on the
  * *recorded* resource id (`recordedIds`, sourced from

package/dist/plan/diff.js

@@ -1,6 +1,6 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
-import { CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
+import { AGORA_ACTIVATED_ENV_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
 import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
@@ -10,7 +10,9 @@ import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHo
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } 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, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, versionNotAppliedLine, } 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 { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec } from './proxy-labels.js';
+import { withStepSystem } from './step-system.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
     return {
@@ -41,9 +43,8 @@ function resourceKey(system, kind, key) {
  * `hosting.issuerApps[]` entry rather than a single singleton, since an org
  * can declare more than one ZITADEL app. #80 adds two more singletons,
  * modeled on {@link planIssuer}: `planFilesOrganisation` and
- * `planAiOrganisation`, each planned before its own system's limit step
- * ({@link planStorage}, {@link planAiBudget}) so an org has somewhere for a
- * limit to land, and AI use is switched on, before either limit is ever set.
+ * `planAiOrganisation`, the second planned before {@link planAiBudget} so AI
+ * use is switched on before its own limit is ever set.
  * `planOwners` below adds one more singleton, in a different shape from the
  * rest: the org's owner, invited by ZITADEL email, idempotent on the
  * *recorded* resource id (`recordedIds`, sourced from
@@ -82,7 +83,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const issuer = planIssuer(org, byKey, claimed, platformReadiness.authReady);
     if (issuer.step)
         plannedSteps.push(issuer.step);
-    plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady));
+    plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady, 'error' in agoraHost ? null : agoraHost.issuer));
     // #267: after the ZITADEL org step, before any app's own issuer
     // application. Apps created later in this run are not in the binding yet;
     // the next run replans this step and repoints them.
@@ -141,9 +142,6 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const filesOrganisation = planFilesOrganisation(org, byKey, claimed, platformReadiness.filesReady, platformReadiness.missingKeys.files, platformReadiness.noKeyReader);
     if (filesOrganisation.step)
         plannedSteps.push(filesOrganisation.step);
-    const storage = planStorage(org, byKey, claimed, platformReadiness.filesReady, platformReadiness.missingKeys.files, platformReadiness.noKeyReader);
-    if (storage.step)
-        plannedSteps.push(storage.step);
     const aiOrganisation = planAiOrganisation(org, byKey, claimed, platformReadiness.aiReady, platformReadiness.missingKeys.ai, platformReadiness.noKeyReader);
     if (aiOrganisation.step)
         plannedSteps.push(aiOrganisation.step);
@@ -188,7 +186,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     if (database)
         plannedSteps.push(database);
     const authIssuer = 'error' in agoraHost ? null : agoraHost.issuer;
-    const app = planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer);
+    const app = planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, platformReadiness);
     plannedSteps.push(...app.steps);
     // After the apps: the broker entry's key is minted into each app's env.
     const brokerEntries = planBrokerEntries(org, recordedIds, plannedSteps, options.broker ?? false);
@@ -312,8 +310,6 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     if (aiOrganisation.blocked) {
         unmanaged.push({ description: aiOrganisation.blocked, key: 'ai:organisation' });
     }
-    if (storage.blocked)
-        unmanaged.push({ description: storage.blocked, key: 'files:storage' });
     if (aiBudget.blocked)
         unmanaged.push({ description: aiBudget.blocked, key: 'ai:budget' });
     // #238: a pending zone, reported here with its nameservers rather than
@@ -325,7 +321,12 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     unmanaged.push(...app.blocked);
     unmanaged.push(...brokerEntries.blocked);
     unmanaged.push(...bouleBroker.blocked);
-    return { orgId: org.id, plannedSteps, unmanaged, versionChanges };
+    return {
+        orgId: org.id,
+        plannedSteps: plannedSteps.map(withStepSystem),
+        unmanaged,
+        versionChanges,
+    };
 }
 /**
  * The org's own ZITADEL org (issuer), a per-org singleton like every other
@@ -433,7 +434,7 @@ function planIssuer(org, byKey, claimed, authReady) {
  * nothing here puts it anywhere beyond what audit already records for the
  * org.
  */
-function planOwners(org, recordedIds, authReady) {
+function planOwners(org, recordedIds, authReady, authIssuer) {
     // #177: nothing to invite into yet -- `planIssuer` already reports the
     // platform's sign-in as blocked, so these steps stay silent rather than
     // repeating it.
@@ -455,6 +456,8 @@ function planOwners(org, recordedIds, authReady) {
                     email: owner.email,
                     givenName: owner.givenName,
                     familyName: owner.familyName,
+                    // The platform's login app, where the invite link must land (it serves `/verify`).
+                    ...(authIssuer ? { authIssuer } : {}),
                 },
             },
             step: {
@@ -987,11 +990,8 @@ function notReadyReason(service, keyName, missingKeyRef, noKeyReader) {
         : `the platform's ${service} host is off or not yet applied`;
 }
 /**
- * #80: every org's own organisation on Files, a per-org singleton resource
- * planned before {@link planStorage} -- `setQuota`/`setBudget` 404 against an
- * org Files has never provisioned (`files/packages/sdk/src/client.ts`'s
- * tenant routes need the row `provisionOrganisation` creates). Modeled on
- * {@link planIssuer}: nothing to diff once it exists -- Files' own
+ * #80: every org's own organisation on Files, a per-org singleton resource.
+ * Modeled on {@link planIssuer}: nothing to diff once it exists -- Files' own
  * `provisionOrganisation` is safely repeatable (`executor.ts`'s
  * `filesOrganisation` calls it every time regardless), so the only planned
  * state is "not provisioned yet". The operator-driven `ceilingBytes`/
@@ -1004,6 +1004,16 @@ function notReadyReason(service, keyName, missingKeyRef, noKeyReader) {
  * own files host (#171) is off or not yet applied, so there is nothing here
  * for `FilesOrganisationPort.provisionOrganisation` to reach.
  *
+ * F6b: `shareHost` is `share.<domain>` when any entry declares
+ * `uses.files.shareHost`, else `null`. It is passed to the provision call
+ * every time, so files always knows the name an org wants. The route and
+ * DNS come from `tunnelIngressHostnames`; `planFilesKeys` warns that the
+ * platform files runner must serve the host too. Computed once, at the only point `provisionOrganisation`
+ * is ever planned (nothing to diff once the organisation is live, same as
+ * `ceilingBytes`/`ceilingMicros` above): a `shareHost` declared after the
+ * organisation already exists needs its own follow-up, matching every other
+ * field on this singleton step.
+ *
  * #273: `desired.agoraOrigin` is every org's own Agora origin (#164's
  * `agoraHostnameFor`, always on, never blocked on anything this step
  * doesn't already wait for) -- `executor.ts`'s `filesOrganisation` adds it
@@ -1026,6 +1036,9 @@ function planFilesOrganisation(org, byKey, claimed, filesReady, missingKeyRef, n
             blocked: `${org.slug}'s Files organisation is blocked, not planned: ${notReadyReason('files', 'files management key', missingKeyRef, noKeyReader)}`,
         };
     }
+    const shareHost = org.domain && org.hosting.entries.some((e) => e.uses?.files?.shareHost)
+        ? `share.${org.domain}`
+        : null;
     return {
         step: {
             action: {
@@ -1036,6 +1049,7 @@ function planFilesOrganisation(org, byKey, claimed, filesReady, missingKeyRef, n
                     provision: true,
                     ceilingBytes: null,
                     ceilingMicros: null,
+                    shareHost,
                     agoraOrigin: `https://${agoraHostnameFor(org)}`,
                 },
             },
@@ -1100,53 +1114,9 @@ function planAiOrganisation(org, byKey, claimed, aiReady, missingKeyRef, noKeyRe
         blocked: null,
     };
 }
-/**
- * #27: the org's own spend limit on Files, a per-org singleton resource in
- * the same shape as issuer/mail/chat above. Setting a limit is a config
- * write, never destructive or migrating (#27 "Notes": "safe, idempotent and
- * reversible"). A missing live resource reads as uncapped (`null`), the same
- * value a freshly-declared org's `storage` starts at, so a brand new org with
- * no limits declared produces no step.
- *
- * #177: silently plans nothing while there is no organisation to size a limit
- * on yet and `filesReady` is false -- {@link planFilesOrganisation} already
- * reports the platform's files host as missing once.
- */
-function planStorage(org, byKey, claimed, filesReady, missingKeyRef, noKeyReader = false) {
-    const key = resourceKey('files', 'storage', org.id);
-    const live = byKey.get(key);
-    if (live)
-        claimed.add(key);
-    if (!filesReady && !live)
-        return { step: null, blocked: null };
-    const desired = { limitBytes: org.storage.limitBytes, limitMicros: org.storage.limitMicros };
-    const liveLimitBytes = live ? (live.config.limitBytes ?? null) : null;
-    const liveLimitMicros = live ? (live.config.limitMicros ?? null) : null;
-    if (liveLimitBytes === desired.limitBytes && liveLimitMicros === desired.limitMicros) {
-        return { step: null, blocked: null };
-    }
-    // A live resource with drift needs the platform's key to change; blocked, not planned to throw at apply.
-    if (!filesReady) {
-        return {
-            step: null,
-            blocked: `${org.slug}'s storage limit change is blocked, not planned: ${notReadyReason('files', 'files management key', missingKeyRef, noKeyReader)}`,
-        };
-    }
-    return {
-        blocked: null,
-        step: {
-            action: { system: 'files', kind: 'storage', key: org.id, desired },
-            step: {
-                description: `set ${org.slug}'s storage limit to ${desired.limitBytes ?? 'uncapped'} bytes / ${desired.limitMicros ?? 'uncapped'} micros`,
-                destroys: false,
-                migrates: false,
-            },
-        },
-    };
-}
 /**
  * #27: the org's own spend limit on AI, a per-org singleton resource in the
- * same shape as {@link planStorage}. Planned after {@link planAiOrganisation}
+ * same singleton shape as issuer/mail/chat above. Planned after {@link planAiOrganisation}
  * (#80), which already seeds a brand new org's first budget row from this
  * same `org.ai.limitMicros` -- this planner only fires again once that row's
  * live value has drifted from what is declared.
@@ -1452,13 +1422,25 @@ function planAgora(org, byKey, claimed, recordedIds, reading) {
     if (liveEnv.AGORA_CONFIG === undefined && !drift.includes('AGORA_CONFIG')) {
         drift.push('AGORA_CONFIG');
     }
-    if (drift.length === 0)
+    // #442: `drift` alone, once this step has ever run, is comparing `env`
+    // against Coolify's own env store -- which the executor's `bulkUpsertEnvs`
+    // leaves matching `env` the moment the write succeeds, restarted or not.
+    // So once applied, drift reads empty forever even if the running process
+    // was never restarted onto it (a crash between the write and the restart,
+    // or simply never restarting at all). `AGORA_ACTIVATED_ENV_SCOPE_KEY` is
+    // the executor's own record that a restart confirmed the process is
+    // actually serving this exact `env`; while it disagrees, the step stays
+    // planned no matter what Coolify's env store already shows.
+    const activated = recordedIds[AGORA_ACTIVATED_ENV_SCOPE_KEY] === agoraEnvRevision(env);
+    if (drift.length === 0 && activated)
         return { step: null, blocked: null };
     return {
         step: {
             action,
             step: {
-                description: `update ${org.slug}'s Agora config (${drift.join(', ')} missing or different)`,
+                description: drift.length > 0
+                    ? `update ${org.slug}'s Agora config (${drift.join(', ')} missing or different)`
+                    : `activate ${org.slug}'s Agora config -- written but not yet confirmed restarted`,
                 destroys: false,
                 migrates: false,
             },
@@ -1636,7 +1618,7 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
  * resource's `enabled` field -- a live resource nothing has actually
  * checked yet is assumed fine rather than replanned every time.
  */
-function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
+function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authIssuer, readiness) {
     // #243: an `appEnv` source with no recorded value and no step planned to
     // record one this run has nothing to push, now or after this apply.
     const sourceStep = {
@@ -1651,9 +1633,12 @@ 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 { values: wantedEnv, unresolved } = entry
-        ? resolveAppEnv(org, entry, recordedIds)
-        : { values: {}, unresolved: [] };
+    const { marker: wantedEnv, unresolved, unresolvedSecrets, } = entry
+        ? resolveAppEnv(org, entry, recordedIds, {
+            platformMailKey: readiness.mailKeyHeld === true,
+            sharedSecret: readiness.canHoldSecrets === true,
+        })
+        : { marker: {}, unresolved: [], unresolvedSecrets: [] };
     const stepKey = appStepKey(org, entryKey);
     const blocked = entry
         ? unresolved
@@ -1663,6 +1648,14 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             description: `${org.slug}'s ${label} env ${name} is blocked, not planned: its source ${source} has no recorded value yet`,
             key: blockedKey(`env:${name}`),
         }))
+            .concat(
+        // Never a value: the ref of the missing key, or what the host lacks.
+        unresolvedSecrets.map(([name, source]) => ({
+            description: `${org.slug}'s ${label} env ${name} is blocked, not planned: ${source === 'platformMailKey'
+                ? `the platform's Lettermint key is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`
+                : `its source ${source} needs a held-key store that can put, and the host has none`}`,
+            key: blockedKey(`env:${name}`),
+        })))
         : [];
     const toggled = planHostingToggle('coolify', 'app', entry !== undefined, 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);
     if (toggled)
@@ -1825,7 +1818,7 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
  * {@link planApp} once per hosting entry. A key with no declared entry still
  * runs for `app`, so an org that turns hosting off parks the app it has live.
  */
-function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
+function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, readiness) {
     const steps = [];
     const blocked = [];
     // An entry removed from the list while its app is recorded is parked like a
@@ -1846,8 +1839,21 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
             if (!resource || (typeof status === 'string' && /^(exited|stopped)/.test(status)))
                 continue;
         }
-        const app = planApp(org, key, byKey, claimed, recordedIds, plannedSteps, authIssuer);
+        const app = planApp(org, key, byKey, claimed, recordedIds, plannedSteps, authIssuer, readiness);
         // The executor pushes the issuer the plan read, the way Agora gets its host values.
+        // 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' || v.from === 'platformMailKey')));
+        if (usesSecrets && app.step && app.step.action.desired.enabled !== false) {
+            app.step.action.desired = {
+                ...app.step.action.desired,
+                secretSources: {
+                    platformMailKey: readiness.mailKeyHeld === true,
+                    sharedSecret: readiness.canHoldSecrets === true,
+                },
+            };
+        }
         if (app.step && app.step.action.desired.enabled !== false) {
             const signsIn = org.hosting.entries.some((e) => e.key === key && e.uses?.auth);
             if (signsIn)

package/dist/plan/entry-ai-key.d.ts

@@ -1,5 +1,5 @@
 import { type DeclaredOrg, type HostingEntry } from '../org.js';
-import type { PlannedStep } from './diff.js';
+import type { DraftStep } from './diff.js';
 import type { OrgPlatformReadiness } from './platform-org.js';
 /**
  * F6a: one ai key per entry with `uses.ai`, minted below the org's own ai key
@@ -49,8 +49,8 @@ export type EntryAiMode = 'mint' | 'renew' | 'settings' | 'finish' | 'retire';
  * entry's app or the ai address is not recorded, or after a mint whose
  * delivery failed: a second mint would leave two live keys.
  */
-export declare function planEntryAiKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly PlannedStep[], readiness: OrgPlatformReadiness, now: number): {
-    steps: PlannedStep[];
+export declare function planEntryAiKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: OrgPlatformReadiness, now: number): {
+    steps: DraftStep[];
     blocked: Array<{
         description: string;
         key: string;