@wtfalch/foundry 0.20.0 → 0.21.0

package/dist/bootstrap/declare.d.ts

@@ -21,6 +21,19 @@ export declare const DEFAULT_GIT_REF = "main";
  * file's loader follows.
  */
 export declare const DEFAULT_MAIL_IMAGE_TAG: string;
+/**
+ * #540: the Healthchecks image tag the platform's `hc` step runs.
+ * `platform.hc.gitRef` is an image tag, the same overload `mail.gitRef`
+ * carries. #540 shipped this floating at `'latest'`, with no
+ * `versions.json` pin and no `floatingTagBlocked` guard at all -- a real
+ * reviewed gap, closed round 2 the same way Stalwart's own tag is pinned:
+ * `versions.json`'s `hc` entry, checked against `healthchecks/healthchecks`'s
+ * real GitHub releases and Docker Hub tags (2026-10, latest stable `v4.4`)
+ * rather than guessed, and `hcImageTagBlocked` (`platform-providers.ts`)
+ * refuses a floating one the way `mailImageTagBlocked` already does for
+ * Stalwart.
+ */
+export declare const DEFAULT_HC_IMAGE_TAG: string;
 export interface BootstrapCompany {
     name: string;
     slug: string;

package/dist/bootstrap/declare.js

@@ -22,6 +22,19 @@ export const DEFAULT_GIT_REF = 'main';
  * file's loader follows.
  */
 export const DEFAULT_MAIL_IMAGE_TAG = VERSIONS.stalwart;
+/**
+ * #540: the Healthchecks image tag the platform's `hc` step runs.
+ * `platform.hc.gitRef` is an image tag, the same overload `mail.gitRef`
+ * carries. #540 shipped this floating at `'latest'`, with no
+ * `versions.json` pin and no `floatingTagBlocked` guard at all -- a real
+ * reviewed gap, closed round 2 the same way Stalwart's own tag is pinned:
+ * `versions.json`'s `hc` entry, checked against `healthchecks/healthchecks`'s
+ * real GitHub releases and Docker Hub tags (2026-10, latest stable `v4.4`)
+ * rather than guessed, and `hcImageTagBlocked` (`platform-providers.ts`)
+ * refuses a floating one the way `mailImageTagBlocked` already does for
+ * Stalwart.
+ */
+export const DEFAULT_HC_IMAGE_TAG = VERSIONS.hc;
 /**
  * Every platform service except `sfu` is enabled, like the other steps: a
  * service whose dependencies the host did not supply is reported blocked,
@@ -30,6 +43,8 @@ export const DEFAULT_MAIL_IMAGE_TAG = VERSIONS.stalwart;
  * platform DNS record is written through it (F4.dns); its own Cloudflare API
  * token is a held key (`cloudflare:edge:apiToken`), and until a human holds
  * it the planner reports edge blocked, and auth, mail and archon with it.
+ * `hc` (#540) is on too: it needs no held key of its own, only edge's DNS,
+ * the same as mail and archon.
  */
 const SERVICES_ENABLED_BY_DEFAULT = new Set([
     'auth',
@@ -40,6 +55,7 @@ const SERVICES_ENABLED_BY_DEFAULT = new Set([
     'integrations',
     'archon',
     'edge',
+    'hc',
 ]);
 /**
  * The owner as `OwnerIdentity`, trimmed. Throws a plain error naming the
@@ -115,7 +131,13 @@ export function declaredPlatformFor(apex, serverIpv4) {
         services[key] = {
             enabled,
             hostname: defaultPlatformHostname(key, apex),
-            gitRef: !enabled ? '' : key === 'mail' ? DEFAULT_MAIL_IMAGE_TAG : DEFAULT_GIT_REF,
+            gitRef: !enabled
+                ? ''
+                : key === 'mail'
+                    ? DEFAULT_MAIL_IMAGE_TAG
+                    : key === 'hc'
+                        ? DEFAULT_HC_IMAGE_TAG
+                        : DEFAULT_GIT_REF,
         };
     }
     return {

package/dist/bootstrap/versions.d.ts

@@ -12,6 +12,7 @@ export interface PinnedVersions {
     livekit: string;
     cloudflared: string;
     stalwart: string;
+    hc: string;
 }
 export declare function loadVersions(): PinnedVersions;
 export declare const VERSIONS: PinnedVersions;

package/dist/index.d.ts

@@ -30,6 +30,8 @@ export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, LoginHostBinding, LoginHostBindingsPort, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
+export type { HealthTarget, HealthTargetDepth, HealthTargetExpect } from './plan/index.js';
+export { healthTargets, platformHealthTargets } from './plan/index.js';
 export type { ScopeResolver, RecordedIds } from './plan/index.js';
 export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
 export type { ZitadelListAppsRawApp } from './plan/index.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesF
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
+export { healthTargets, platformHealthTargets } from './plan/index.js';
 export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
 export { adaptZitadelListApps } from './plan/index.js';
 export { checkMailIdentityAudience } from './plan/index.js';

package/dist/migrations/0046_platform_hc.sql

@@ -0,0 +1,19 @@
+-- @wtfalch/foundry: #540 -- the platform's own heartbeat server (self-hosted
+-- Healthchecks), added to the declared platform the same way every other
+-- shared service here was (#165, #317). Mirrors `src/store/schema.ts`'s
+-- `foundryDeclaredPlatform` table additions. Backfills `hc_hostname` the
+-- same way `0043_platform_names.sql` backfilled `names_hostname`: the
+-- column must not be empty (`src/platform.ts`'s `validatePlatform`), and
+-- the table already carries its one live row by the time this runs.
+
+alter table foundry_declared_platform
+  add column if not exists hc_enabled boolean not null default false,
+  add column if not exists hc_hostname text,
+  add column if not exists hc_git_ref text not null default '';
+
+update foundry_declared_platform
+  set hc_hostname = 'hc.' || apex
+  where hc_hostname is null;
+
+alter table foundry_declared_platform
+  alter column hc_hostname set not null;

package/dist/plan/deploy-health.js

@@ -62,6 +62,8 @@
  */
 const DEFAULT_READY_TIMEOUT_MS = 300_000;
 const DEFAULT_READY_INTERVAL_MS = 5_000;
+/** One health request's own limit: a connection that accepts and never answers counts as not healthy yet, instead of blocking the whole wait. */
+const HEALTH_REQUEST_TIMEOUT_MS = 5_000;
 /** The one terminal `CoolifyDeploymentStatus` that means the new version landed. */
 const DEPLOYMENT_SUCCEEDED = 'finished';
 /**
@@ -135,7 +137,9 @@ export async function waitForNewDeployment(coolify, appId, health, runtime, slee
 }
 async function matchesHealth(fetchImpl, health) {
     try {
-        const response = await fetchImpl(health.url);
+        const response = await fetchImpl(health.url, {
+            signal: AbortSignal.timeout(HEALTH_REQUEST_TIMEOUT_MS),
+        });
         if (!response.ok)
             return false;
         if (health.kind === 'ready')

package/dist/plan/diff.js

@@ -1955,6 +1955,29 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             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
+    // replanning this one step (the same action, nothing extra) is the whole
+    // repair. A reader that did not check (`healthCheckEnabled` absent) reads
+    // as compliant, like `hasLogVolume`.
+    // Only for an entry `coolifyApp` would set the check on (a static entry,
+    // or one with a declared port): otherwise the repair could never land and
+    // every apply would replan it.
+    if (live.config.healthCheckEnabled === false &&
+        (entry.buildPack === 'static' || entry.port !== null)) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `turn Coolify's health check back on for ${org.slug}'s ${label} (#543)`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
     // #239 (rule 4), from live state: an app with a database but no
     // `DATABASE_URL_OWNER` env still has the pre-split superuser URL, or never
     // got the push. Names only, never values. A reader that did not list env

package/dist/plan/executor.d.ts

@@ -2,6 +2,7 @@ import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/p
 import type { DeclaredOrg, HostingBuildPack } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
 import { type BrokerPort } from './broker-entries.js';
+import { type DeployHealthRuntime } from './deploy-health.js';
 import { type StepAction } from './diff.js';
 import { type AccessPort, type EdgePlatformAccess } from './edge-access.js';
 import { type DnsPort, type EdgePlatformDns } from './edge-dns.js';
@@ -384,6 +385,8 @@ export interface CoolifyPort {
         enabled: boolean;
         save_s3: boolean;
         s3_storage_uuid?: string;
+        /** The databases this schedule dumps, comma separated. Empty means the resource's first database. */
+        databases_to_backup?: string | null;
     }>>;
     /**
      * #257: schedules dumps of a database to the registered S3 storage --
@@ -1451,6 +1454,17 @@ export interface FoundryStepExecutorPorts {
      * passes the same store instance it constructs `FoundryPlanApply` with.
      */
     declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone'>;
+    /**
+     * #543: clock, sleep and `fetch` for the health-check wait every company
+     * app's own redeploy now goes through (`deploy-health.ts`'s
+     * `waitForNewDeployment`) -- the same override shape `platform-providers.ts`'s
+     * own `PlatformMailDeps.runtime`/`PlatformArchonDeps.runtime` already take,
+     * here on one shared port instead of one per platform step since this
+     * executor is the one class every company-app step runs through. Optional:
+     * without it, {@link defaultSleep} (plain `setTimeout`) and the real
+     * `fetch`/`Date.now` are used.
+     */
+    runtime?: DeployHealthRuntime;
 }
 /**
  * Thrown by name for a step this executor deliberately does not implement:
@@ -1462,6 +1476,26 @@ export interface FoundryStepExecutorPorts {
 export declare class NotBuiltError extends Error {
     constructor(step: string, detail: string);
 }
+/**
+ * `cms.<domain>` -- the cms studio's own hostname (`cmsSite` below), apart
+ * from the public site itself at `org.domain` (used directly there). Called
+ * from `cmsSite` and from `zitadelApp` for the fixed `cms` client (#139),
+ * both of which only run once `org.site.enabled` is true, so `org.domain`
+ * is non-null by the same `validateSite` guarantee
+ * {@link tunnelIngressHostnames}'s own doc comment cites.
+ */
+export declare function cmsHostnameFor(org: DeclaredOrg): string;
+/**
+ * #145's "Decided" (2026-09-27): the calls service's own public hostname.
+ * `calls.usesDomain: false` (or no `domain`) is served flat, like
+ * `<slug>-stage.oikos.host` and `<slug>-pr-<n>.oikos.host` (`../slug.ts`) --
+ * the shared tunnel's wildcard `*.oikos.host` DNS record already reaches it,
+ * so nothing changes in `scripts/shared-ingress.mjs`. `calls.usesDomain: true`
+ * gets `calls.<domain>` instead, on its own per-org tunnel
+ * ({@link tunnelIngressHostnames}), the same subdomain-of-the-org's-own-domain
+ * shape {@link cmsHostnameFor} uses for `cms.<domain>`.
+ */
+export declare function callsHostnameFor(org: DeclaredOrg): string;
 /**
  * The health URLs an outside prober should call for this org (#43): one per
  * app foundry runs for it. A hosting org's app answers at its own hostname,

package/dist/plan/executor.js

@@ -9,6 +9,7 @@ import { MAS_IMAGE, MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, cal
 import { CHAT_REPO, CHAT_SERVICE_DOCKERFILE, CHAT_SERVICE_PORT, CHAT_SYNAPSE_DOCKERFILE, CHAT_SYNAPSE_PORT, chatInternalNames, chatMasConfigYaml, chatServiceEnvs, chatSynapseHomeserverYaml, chatUpstreams, } from './chat-matrix.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
 import { CORE_FILES_COLLECTION_NAME, FILES_CORE_COLLECTION_SCOPE_KEY, ZITADEL_FILES_PROJECT_SCOPE_KEY, } from './core-files.js';
+import { waitForNewDeployment, } from './deploy-health.js';
 import { DEFAULT_AI_LIMIT_MICROS } from './diff.js';
 import { createEdgeAccess, } from './edge-access.js';
 import { EDGE_DNS_WRITE_CONCURRENCY, createEdgeDns, limiter, } from './edge-dns.js';
@@ -18,6 +19,7 @@ import { createEdgeZones } from './edge-zones.js';
 import { AI_ENTRY_RENEW_WINDOW_DAYS, entryAiAppliedScopeKey, entryAiClampedScopeKey, entryAiExpiresScopeKey, entryAiPendingExpiresScopeKey, entryAiRetiredScopeKey, entryAiUndeliveredScopeKey, entryAiUnrevokedScopeKey, entryAiWebhookPendingScopeKey, entryAiWrittenScopeKey, parseIdList, } from './entry-ai-key.js';
 import { BOULE_EDGE_ENTRY_KEY, EDGE_ENTRY_KEY_DAYS, EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY, ENTRY_EDGE_KEY_DELIVERY_ATTEMPTS, edgeKeyAppRecordKey, entryEdgeMintedAtScopeKey, entryEdgeRetiredScopeKey, entryEdgeUndeliveredScopeKey, } from './entry-edge-key.js';
 import { FILES_AGORA_KEY_SCOPE_KEY, FILES_AGORA_UNDELIVERED_SCOPE_KEY, FILES_KEY_DAYS, FILES_KEY_RENEW_WINDOW_DAYS, FILES_ORG_OWNER_SCOPE_KEY, FILES_ROOT_EXPIRES_SCOPE_KEY, FILES_ROOT_PREVIOUS_SCOPE_KEY, FILES_ROOT_UNDELIVERED_SCOPE_KEY, FILES_ROOT_UNREVOKED_SCOPE_KEY, entryFilesAppliedScopeKey, entryFilesExpiresScopeKey, entryFilesMinterScopeKey, entryFilesPendingExpiresScopeKey, entryFilesRetiredScopeKey, entryFilesUndeliveredScopeKey, entryFilesUnrevokedScopeKey, entryFilesWrittenScopeKey, filesOwnerUserId, parseIdList as parseFilesIdList, } from './entry-files-key.js';
+import { healthCheckSettings } from './health-check-settings.js';
 import { appHostname, coolifyDomains, entryHostnames, tunnelDnsHostnames, tunnelIngressHostnames, } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY, LOGIN_HOST_SHARED_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';
@@ -84,7 +86,9 @@ function normalizedLoginBaseUri(uri) {
  * is non-null by the same `validateSite` guarantee
  * {@link tunnelIngressHostnames}'s own doc comment cites.
  */
-function cmsHostnameFor(org) {
+// #541: exported so `health-targets.ts` reuses this hostname rule rather
+// than restating it; nothing else about this function changes.
+export function cmsHostnameFor(org) {
     return `cms.${org.domain}`;
 }
 /**
@@ -97,7 +101,8 @@ function cmsHostnameFor(org) {
  * ({@link tunnelIngressHostnames}), the same subdomain-of-the-org's-own-domain
  * shape {@link cmsHostnameFor} uses for `cms.<domain>`.
  */
-function callsHostnameFor(org) {
+// #541: exported for the same reason `cmsHostnameFor` just above now is.
+export function callsHostnameFor(org) {
     return org.calls.usesDomain && org.domain
         ? `calls.${org.domain}`
         : `${org.slug}-calls.oikos.host`;
@@ -233,6 +238,14 @@ const DEFAULT_APP_DOCKERFILE = '/apps/hestia/Dockerfile';
 const CMS_REPO = 'wtfalch/cms';
 const CMS_APP_DOCKERFILE = '/Dockerfile';
 const CMS_SITE_APP_DOCKERFILE = '/apps/site/Dockerfile';
+/**
+ * #543: both of `wtfalch/cms`'s apps are Next.js hosts on the same
+ * app-template convention as Archon/edge/ai's runner/Boule -- port 3000,
+ * `/api/health` (`healthUrls`'s own default for a non-static entry). Neither
+ * create call below passes `ports_exposes` (unlike Agora's #506 fix), so
+ * this is the port Coolify's own default build already listens its proxy on.
+ */
+const CMS_APP_PORT = 3000;
 /**
  * #164: the repo `coolifyAgora` builds the org's Agora from
  * (https://github.com/wtfalch/agora) -- the issue's own "How" names this
@@ -266,6 +279,8 @@ const AGORA_APP_DOCKERFILE = '/apps/agora/Dockerfile';
  */
 const BOULE_REPO = 'wtfalch/boule';
 const BOULE_APP_DOCKERFILE = '/Dockerfile';
+/** Boule's own `EXPOSE 3000` (its doc comment just above) -- the port its health check (#543) probes. */
+const BOULE_PORT = 3000;
 /**
  * Every app foundry deploys keeps its own logs across a redeploy, so a
  * database outage does not also erase the only other copy of the evidence
@@ -597,6 +612,21 @@ const CALLS_SERVICE_DB_SCOPE_KEY = 'coolify_calls_service_database';
 const CALLS_SERVICE_REPO = 'wtfalch/calls';
 /** `packages/service/Dockerfile`, built from the repo root (that Dockerfile's own top comment). */
 const CALLS_SERVICE_DOCKERFILE = '/packages/service/Dockerfile';
+/**
+ * #543: the calls service's own health route. Restated, not imported, from
+ * `health-targets.ts`'s private `CALLS_HEALTH_PATH` of the same value --
+ * issue #543's own text keeps that issue's (#541) diff and this one
+ * independent of each other.
+ */
+const CALLS_HEALTH_CHECK_PATH = '/healthz';
+/**
+ * #543: the chat service's own health route, reached through Agora's proxy
+ * (`chat-matrix.ts`'s "NO PUBLIC HOSTNAME OF ITS OWN": Synapse and MAS have
+ * none, only this). Restated from `health-targets.ts`'s private
+ * `CHAT_SERVICE_HEALTH_PATH` of the same value, for the same reason as
+ * {@link CALLS_HEALTH_CHECK_PATH} above.
+ */
+const CHAT_SERVICE_HEALTH_CHECK_PATH = '/_chat/health';
 /**
  * Whether an application's own Coolify `status` (`` `running:healthy`,
  * `exited:unhealthy` `` -- `@wtfalch/providers`' own doc comment) means it is
@@ -642,6 +672,43 @@ export async function getDatabaseStarted(coolify, dbId) {
     await sleep(graceMs);
     return db;
 }
+/**
+ * #543: the plain `setTimeout`-based sleep every company-app deploy wait
+ * falls back to when `FoundryStepExecutorPorts.runtime.sleep` is not given --
+ * the same default `platform-providers.ts`'s own per-step `defaultSleep`
+ * constants use.
+ */
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * #543 review: a deploy waits with `'ready'` on a public url only when
+ * nothing still has to create or change the route to it. Otherwise it is
+ * `'deployment-only'`, so a fresh company is not failed for a tunnel, DNS
+ * record or Agora that a later step in the same plan creates. From
+ * `recorded`: a hostname under `org.domain` has a route once the tunnel step
+ * published its DNS record ({@link CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY});
+ * a hostname elsewhere is on the shared wildcard tunnel and already routed.
+ * `viaAgora` (the chat service, reached through Agora's proxy) also needs
+ * Agora deployed ({@link AGORA_DEPLOYED_SCOPE_KEY}). A hostname behind
+ * Cloudflare Access is never probed: with no credentials every answer is a
+ * redirect or 403.
+ */
+function publicHealthCheck(org, recorded, hostname, path, options = {}) {
+    const app = appEntry(org.hosting);
+    const behindAccess = (org.hosting.access ?? []).some((rule) => rule.hostname === hostname) ||
+        (app !== undefined &&
+            app.accessEmails.length > 0 &&
+            entryHostnames(org, app).includes(hostname));
+    if (behindAccess)
+        return { kind: 'deployment-only' };
+    const routed = (host) => !org.domain ||
+        !(host === org.domain || host.endsWith(`.${org.domain}`)) ||
+        (recorded[CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY] ?? '').split(',').includes(host);
+    const agoraReady = !options.viaAgora ||
+        (Boolean(recorded[AGORA_DEPLOYED_SCOPE_KEY]) && routed(agoraHostnameFor(org)));
+    if (!agoraReady || !routed(hostname))
+        return { kind: 'deployment-only' };
+    return { kind: 'ready', url: `https://${hostname}${path}` };
+}
 /** Timing for the wait in {@link getDatabaseStarted}; a test swaps `sleep` and `now` for a fake clock. */
 export const databaseStartWait = {
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -1682,6 +1749,20 @@ export class FoundryStepExecutor {
         }
         if (want.autoDeploy !== have.autoDeploy)
             patch.is_auto_deploy_enabled = want.autoDeploy;
+        // #543: the health-check quartet too, every run -- the same reason
+        // Archon's own doc comment gives (without one, Coolify's rolling update
+        // has nothing to wait on and stops the old container immediately). The
+        // port Coolify's own health probe reaches is whatever `ports_exposes`
+        // names: 80 for a static entry (Coolify's own web server), or the
+        // entry's declared `port`. An entry with neither (an arbitrary buildpack,
+        // no declared port) gets none here -- there is no port this executor
+        // could honestly name for Coolify to probe, the same "nothing to check
+        // instead" reasoning `platform:ai`'s worker and `platform:files`'
+        // migrate job are left out of #543's own quartet for.
+        const healthCheckPort = isStatic ? 80 : want.port;
+        if (healthCheckPort !== null) {
+            Object.assign(patch, healthCheckSettings(entry.healthPath ?? (isStatic ? '/' : '/api/health'), healthCheckPort));
+        }
         // 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.
@@ -1759,10 +1840,23 @@ export class FoundryStepExecutor {
         // declared appEnv changed.
         // A new folder needs a build, which a restart does not do, so a settings
         // change deploys instead (rule 3), and that carries the env too.
-        if (settingsNeedDeploy)
-            await this.ports.coolify.deploy(appId);
-        else if ((appEnv.changed || dbNeedsRestart) && existing)
+        if (settingsNeedDeploy) {
+            // #543: every deploy waits for health through the shared helper, never
+            // a fire-and-forget `deploy` call -- `names[0]` is the same hostname
+            // `healthUrls` probes for this entry; an internal entry (no hostname)
+            // has nothing this executor could reach from outside the app's own
+            // Docker network, so `'deployment-only'` is the honest fallback there
+            // (Coolify's own deployment record is still the whole check).
+            const [hostname] = names;
+            const healthPath = entry.healthPath ?? (isStatic ? '/' : '/api/health');
+            const runtime = this.ports.runtime ?? {};
+            await waitForNewDeployment(this.ports.coolify, appId, hostname
+                ? publicHealthCheck(org, context.recordedIds(), hostname, healthPath)
+                : { kind: 'deployment-only' }, runtime, runtime.sleep ?? defaultSleep, `coolify:app:${entry.key}`, `${org.slug}'s ${entry.key === APP_ENTRY_KEY ? 'app' : `${entry.key} app`} stays at its previous deploy`);
+        }
+        else if ((appEnv.changed || dbNeedsRestart) && existing) {
             await this.ports.coolify.restart(appId);
+        }
         // Recorded only after the redeploy succeeded: a failed one leaves the old
         // value, so the next plan replans (rule 3). The db marker is not a URL.
         // A port taken back to null was not patched, so the marker keeps the old
@@ -2602,6 +2696,21 @@ export class FoundryStepExecutor {
             dockerfileLocation: CMS_APP_DOCKERFILE,
             domain: cmsHostnameFor(org),
         });
+        // #543: the health-check quartet, every run, on both apps -- their own
+        // `/api/health` (`healthUrls`'s own default for site/cms), on the port
+        // {@link CMS_APP_PORT}'s own doc comment explains. Unlike every other
+        // company app in this file, neither app here is ever deployed through an
+        // explicit `coolify.deploy`/`waitForNewDeployment` call: `findOrCreateCmsApp`
+        // (below) never sets `instant_deploy` either, the same gap #504 found and
+        // fixed for Agora and Boule -- fixing that for cms/site is its own,
+        // separate issue (out of #543's scope: this issue adds waits to existing
+        // deploys, it does not add a deploy where none exists).
+        await this.ports.coolify.updateApplication(site.appId, {
+            ...healthCheckSettings('/api/health', CMS_APP_PORT),
+        });
+        await this.ports.coolify.updateApplication(cms.appId, {
+            ...healthCheckSettings('/api/health', CMS_APP_PORT),
+        });
         // Every app foundry deploys keeps its own logs (#75) -- reused as-is for
         // both of these two, the same unconditional call `coolifyApp` makes for
         // its own one app.
@@ -2979,10 +3088,21 @@ export class FoundryStepExecutor {
         // converges. A brand new app or a freshly minted secret set are the only
         // two reasons the file just written could differ from what the container
         // already has -- reusing existing secrets means byte-identical content.
-        if (!synapse.existed || secrets.changed)
-            await this.ports.coolify.deploy(synapse.appId);
-        if (!mas.existed || secrets.changed)
-            await this.ports.coolify.deploy(mas.appId);
+        //
+        // #543: both waits are `'deployment-only'` -- Synapse and MAS have their
+        // own health check off (just above: "Neither Synapse's nor MAS's health
+        // check can pass before the other is up"), so there is no url either
+        // could honestly be probed at; `coolify.deployAndWait` reaching Coolify's
+        // own deployment record is still the whole check, same as `platform:ai`'s
+        // worker.
+        const runtime = this.ports.runtime ?? {};
+        const sleep = runtime.sleep ?? defaultSleep;
+        if (!synapse.existed || secrets.changed) {
+            await waitForNewDeployment(this.ports.coolify, synapse.appId, { kind: 'deployment-only' }, runtime, sleep, 'coolify:calls', `${org.slug}'s calls Synapse stays at its previous deploy`);
+        }
+        if (!mas.existed || secrets.changed) {
+            await waitForNewDeployment(this.ports.coolify, mas.appId, { kind: 'deployment-only' }, runtime, sleep, 'coolify:calls', `${org.slug}'s calls MAS stays at its previous deploy`);
+        }
         return { resourceId: mas.appId };
     }
     /**
@@ -3198,6 +3318,15 @@ export class FoundryStepExecutor {
      */
     async coolifyChat(action, org, context) {
         const recorded = context.recordedIds();
+        // #543: every deploy below waits for health. The chat service answers
+        // `CHAT_SERVICE_HEALTH_CHECK_PATH` only through Agora's own proxy
+        // (`chat-matrix.ts`'s "NO PUBLIC HOSTNAME OF ITS OWN" -- the service has
+        // no domain of its own), so that is the url every `'ready'` check below
+        // probes; Synapse and MAS stay `'deployment-only'`, the same reason
+        // `coolifyCalls`'s own comment gives for its Synapse/MAS.
+        const runtime = this.ports.runtime ?? {};
+        const sleep = runtime.sleep ?? defaultSleep;
+        const chatServiceHealth = () => publicHealthCheck(org, context.recordedIds(), agoraHostnameFor(org), CHAT_SERVICE_HEALTH_CHECK_PATH, { viaAgora: true });
         if (recorded[`coolify:chat:${action.key}`]) {
             // #456: `planChat` plans this distinct, non-re-key action for a live
             // chat app that predates the owner/runtime database split (#239) --
@@ -3222,7 +3351,7 @@ export class FoundryStepExecutor {
                     throw new Error(`coolify:chat database split for ${org.slug}: the chat service's database (${serviceDbId}) has no internal_db_url -- it may have been deleted or is unreachable; this is not expected for an already-live chat`);
                 }
                 if (push.changed || !recorded[markerKey]) {
-                    await this.ports.coolify.deploy(serviceAppId);
+                    await waitForNewDeployment(this.ports.coolify, serviceAppId, chatServiceHealth(), runtime, sleep, 'coolify:chat', `${org.slug}'s chat service stays at its previous deploy`);
                 }
                 context.recordScopeId(markerKey, '1');
                 return { resourceId: serviceAppId };
@@ -3245,8 +3374,9 @@ export class FoundryStepExecutor {
                 ]);
                 // Deploy first, marker last: a failed deploy leaves the marker unset,
                 // so the next plan still carries this step and the container gets the env.
-                if (client.changed || !hadMarker)
-                    await this.ports.coolify.deploy(serviceAppId);
+                if (client.changed || !hadMarker) {
+                    await waitForNewDeployment(this.ports.coolify, serviceAppId, chatServiceHealth(), runtime, sleep, 'coolify:chat', `${org.slug}'s chat service stays at its previous deploy`);
+                }
                 context.recordScopeId(CHAT_INTROSPECTION_SCOPE_KEY, client.appId);
                 return { resourceId: serviceAppId };
             }
@@ -3348,6 +3478,8 @@ export class FoundryStepExecutor {
         });
         await this.ports.coolify.updateApplication(service.appId, {
             custom_internal_name: names.service,
+            // No Coolify health check on the chat service (#543 review): its image
+            // is node:22-alpine with no curl, which Coolify's container check runs.
         });
         context.recordScopeId(CHAT_SYNAPSE_SCOPE_KEY, synapse.appId);
         context.recordScopeId(CHAT_SERVICE_SCOPE_KEY, service.appId);
@@ -3414,7 +3546,11 @@ export class FoundryStepExecutor {
                 secrets.changed ||
                 (app === service && (serviceDbPush.changed || introspection.changed)) ||
                 !isRunningOrStarting((await this.ports.coolify.getApplication(app.appId)).status)) {
-                await this.ports.coolify.deploy(app.appId);
+                // #543: `'ready'` for the service (it has a real route, probed
+                // through Agora); `'deployment-only'` for Synapse/MAS, same as this
+                // function's two re-key paths above and `coolifyCalls`'s own
+                // Synapse/MAS.
+                await waitForNewDeployment(this.ports.coolify, app.appId, app === service ? chatServiceHealth() : { kind: 'deployment-only' }, runtime, sleep, 'coolify:chat', `${org.slug}'s chat ${app === service ? 'service' : app === synapse ? 'Synapse' : 'MAS'} stays at its previous deploy`);
             }
         }
         // After the write and the deploys, so a failure before them leaves the
@@ -3502,6 +3638,8 @@ export class FoundryStepExecutor {
         // step again for a live app whose marker is missing or stale, so an app
         // made before this existed gets its name here. The marker, recorded last,
         // tells `desiredAgoraEnv` that the name and the env are both in place.
+        // No Coolify health check on the calls service (#543 review): its image
+        // is node:24-alpine with no curl, which Coolify's container check runs.
         await this.ports.coolify.updateApplication(app.appId, { custom_internal_name: name });
         // Every app foundry deploys keeps its own logs (#75), reused as-is here.
         await this.ensureLogVolume(app.appId, org, app.existed);
@@ -3569,7 +3707,11 @@ export class FoundryStepExecutor {
         // existed, still pointed at a role nothing has created.
         const givesTokenEnv = token !== null && context.recordedIds()[CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY] !== tokenMarker;
         if (app.existed && dbSplitNeedsRefresh) {
-            await this.ports.coolify.deploy(app.appId);
+            // #543: every deploy waits for health -- the calls service's own
+            // public hostname and `/healthz`, the same path the quartet above
+            // just set on the app.
+            const runtime = this.ports.runtime ?? {};
+            await waitForNewDeployment(this.ports.coolify, app.appId, publicHealthCheck(org, context.recordedIds(), callsHostnameFor(org), CALLS_HEALTH_CHECK_PATH), runtime, runtime.sleep ?? defaultSleep, 'coolify:calls-service', `${org.slug}'s calls service stays at its previous deploy`);
         }
         else if (app.existed && (!callsServiceHasName(org, context.recordedIds()) || givesTokenEnv)) {
             await this.ports.coolify.restart(app.appId);
@@ -3783,11 +3925,14 @@ export class FoundryStepExecutor {
         const portDiffers = app.existed &&
             (await this.ports.coolify.getApplication(app.appId)).ports_exposes !==
                 AGORA_APP_PORTS_EXPOSES;
-        if (portDiffers) {
-            await this.ports.coolify.updateApplication(app.appId, {
-                ports_exposes: AGORA_APP_PORTS_EXPOSES,
-            });
-        }
+        // #543: the health-check quartet, every run, like Archon's own patch --
+        // Agora is static (Caddy on {@link AGORA_APP_PORTS_EXPOSES}), so the only
+        // health route available is a plain page load at `/` (the same depth
+        // `health-targets.ts` gives it: `'page'`, not an API).
+        await this.ports.coolify.updateApplication(app.appId, {
+            ...(portDiffers ? { ports_exposes: AGORA_APP_PORTS_EXPOSES } : {}),
+            ...healthCheckSettings('/', Number(AGORA_APP_PORTS_EXPOSES)),
+        });
         // #442: read before overwriting -- `bulkUpsertEnvs` below always leaves
         // Coolify's own env store matching `env`, which is why that store alone
         // can no longer tell a changed value from one already live.
@@ -3806,16 +3951,16 @@ export class FoundryStepExecutor {
         // confirmed (the marker never changes value once set), never again -- a
         // live app is only ever restarted from here on, unless #506's port fix
         // below needs its own deploy.
-        if (!context.recordedIds()[AGORA_DEPLOYED_SCOPE_KEY]) {
-            await this.ports.coolify.deploy(app.appId);
+        if (!context.recordedIds()[AGORA_DEPLOYED_SCOPE_KEY] || portDiffers) {
+            // #543/#506: every deploy waits for health -- Agora's own page at `/`.
+            // A first deploy and a port fix share this one wait (a port fix needs
+            // its own full deploy; env drift alone only needs the cheaper restart
+            // in the branch below, and this deploy already carries this run's env,
+            // pushed above, so the two never both run).
+            const runtime = this.ports.runtime ?? {};
+            await waitForNewDeployment(this.ports.coolify, app.appId, publicHealthCheck(org, context.recordedIds(), agoraHostnameFor(org), '/'), runtime, runtime.sleep ?? defaultSleep, 'coolify:agora', `${org.slug}'s Agora stays at its previous deploy`);
             context.recordScopeId(AGORA_DEPLOYED_SCOPE_KEY, '1');
         }
-        else if (portDiffers) {
-            // #506: a port fix needs its own full deploy -- env drift alone only
-            // needs the cheaper restart, and this deploy already carries this
-            // run's env (pushed above), so the two never both run.
-            await this.ports.coolify.deploy(app.appId);
-        }
         else if (app.existed && (envChanged || !alreadyActivated)) {
             await this.ports.coolify.restart(app.appId);
         }
@@ -3882,6 +4027,12 @@ export class FoundryStepExecutor {
         }));
         // Every app foundry deploys keeps its own logs (#75), reused as-is here.
         await this.ensureLogVolume(app.appId, org, app.existed);
+        // #543: the health-check quartet, every run, like Archon's own patch --
+        // Boule's own `/api/health` (`healthUrls`'s default) on its Dockerfile's
+        // `EXPOSE 3000` ({@link BOULE_PORT}'s own doc comment).
+        await this.ports.coolify.updateApplication(app.appId, {
+            ...healthCheckSettings('/api/health', BOULE_PORT),
+        });
         const liveEnv = new Map((await this.ports.coolify.listEnvs(app.appId))
             .filter((e) => !e.is_preview)
             .map((e) => [e.key, e.value]));
@@ -3906,7 +4057,9 @@ export class FoundryStepExecutor {
         // but never started. Deployed once this executor has confirmed, never
         // again -- a live app is only ever restarted from here on.
         if (!context.recordedIds()[BOULE_DEPLOYED_SCOPE_KEY]) {
-            await this.ports.coolify.deploy(app.appId);
+            // #543: every deploy waits for health -- Boule's own public hostname.
+            const runtime = this.ports.runtime ?? {};
+            await waitForNewDeployment(this.ports.coolify, app.appId, publicHealthCheck(org, context.recordedIds(), bouleHostnameFor(org), '/api/health'), runtime, runtime.sleep ?? defaultSleep, 'coolify:boule', `${org.slug}'s Boule stays at its previous deploy`);
             context.recordScopeId(BOULE_DEPLOYED_SCOPE_KEY, '1');
         }
         else if (app.existed &&