@wtfalch/foundry 0.20.0 → 0.21.0

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

@@ -674,6 +674,104 @@ export declare const PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY = "edge_applied_git
  * (the {@link PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY} pattern). Not a secret.
  */
 export declare const PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY = "edge_platform_internal_url";
+/**
+ * #540: the resource key `planHc` plans under and `FoundryPlatformStepExecutor`
+ * dispatches on -- the {@link PLATFORM_EDGE_KEY} shape for the platform's own
+ * heartbeat server (self-hosted Healthchecks). `runPlatformSteps` records
+ * the app's uuid under `coolify:app:platform:hc` once the step succeeds,
+ * which is what stops `planHc` planning it again.
+ */
+export declare const PLATFORM_HC_KEY = "platform:hc";
+/**
+ * #540: the hostname and `gitRef` (a Docker image tag, like `mail.gitRef`)
+ * the last successful `hc` run applied. `planHc` plans the step again when
+ * either differs from the declared value; a re-run patches the image tag
+ * and redeploys, and mints nothing new (`SECRET_KEY` is generated once and
+ * read back, never regenerated -- see `ensureGeneratedEnv`).
+ */
+export declare const PLATFORM_HC_APPLIED_HOSTNAME_SCOPE_KEY = "hc_applied_hostname";
+export declare const PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY = "hc_applied_git_ref";
+/**
+ * #540 round 2: the held-key ref a human puts hc's first project API key
+ * under -- `deliverSecret`'s naming convention (`EDGE_URL`'s own pattern),
+ * `<service>:<scope>:<name>` like {@link PLATFORM_EDGE_KEY_REF}. Nothing in
+ * this package mints this key: `provisionPlatformHc` stands up an empty
+ * Healthchecks instance with no user, no project and so no key, and neither
+ * a `manage.py` command nor a documented API mints a project's own API key
+ * (confirmed against `healthchecks/healthchecks`'s own source, 2026-10) --
+ * only its web UI does, after a first superuser signs in by hand. Until a
+ * human does that and holds the key here, `FoundryPlatformStepExecutor
+ * .blockedSteps` (`platform-providers.ts`) reports the heartbeat checks
+ * blocked (`PlanPlatformOptions.blocked.heartbeatsApiKeyMissing`) rather
+ * than let `planHeartbeats` plan a step that would call hc's real
+ * Management API with no account and no key behind it -- see issue #540's
+ * own "Human steps" note. This package never reads the value back: whoever
+ * implements {@link HeartbeatsPort} against hc's real HTTP API is the host,
+ * and that implementation is where the key is actually used.
+ */
+export declare const PLATFORM_HC_API_KEY_REF = "hc:platform:apiKey";
+/**
+ * #540: the heartbeat check named after the uptime Worker (foundry#542,
+ * which is what actually pings it -- blocked today on edge#26, so nothing
+ * pings this check yet; it still exists so the Worker has a URL to deliver
+ * to the moment it can). `platformBackupHeartbeatCheckName` is the matching
+ * name for each platform database backup (`PLATFORM_BACKUP_SERVICE_KEYS`).
+ * Both names are also the prefix `provisionPlatformHeartbeats`
+ * (`platform-providers.ts`) uses to recognise which live Healthchecks
+ * checks are its own to delete when they are no longer wanted -- it never
+ * touches a check outside this naming scheme.
+ */
+export declare const PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME = "uptime-worker";
+/** #540: see {@link PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME}'s own doc comment. */
+export declare function platformBackupHeartbeatCheckName(service: PlatformBackupServiceKey): string;
+/**
+ * #540: the held-key ref each heartbeat check's own ping URL is recorded
+ * under, once created -- `deliverSecret`'s ref-naming convention
+ * (`EDGE_URL`'s own pattern), read back by whoever owns that piece of
+ * scheduled work. `platformBackupHeartbeatUrlRef` is the per-service
+ * counterpart. Unlike a minted credential (CLAUDE.md platform-step rule 1),
+ * a ping URL is not retried-and-guarded the same way: it is closer to a
+ * resource id, so `provisionPlatformHeartbeats` simply records it again
+ * every time the check it names is (re)created.
+ */
+export declare const PLATFORM_UPTIME_HEARTBEAT_URL_REF = "uptime:heartbeatUrl";
+/** #540: see {@link PLATFORM_UPTIME_HEARTBEAT_URL_REF}'s own doc comment. */
+export declare function platformBackupHeartbeatUrlRef(service: PlatformBackupServiceKey): string;
+/**
+ * #540: every heartbeat check name foundry currently wants -- the uptime
+ * Worker's own, plus one per platform database backup that already has a
+ * recorded database id (`PLATFORM_BACKUP_SERVICE_KEYS`, the same "nothing to
+ * report yet" gate {@link planBackups} itself uses for a service with no
+ * database). Shared by {@link planHeartbeats} (to tell whether anything
+ * declared has changed since the last successful reconcile) and
+ * `provisionPlatformHeartbeats` (`platform-providers.ts`, to decide what to
+ * create or delete live) so the two can never compute a different desired
+ * set from each other.
+ */
+export declare function desiredHeartbeatCheckNames(recordedIds: Readonly<Record<string, string>>): readonly string[];
+/**
+ * #540: the held-key ref a check named `name` (one {@link desiredHeartbeatCheckNames}
+ * produced) records its ping URL under -- `platform-providers.ts`'s
+ * `provisionPlatformHeartbeats` looks this up rather than re-deriving it
+ * inline, so the two name-to-ref mappings ({@link PLATFORM_UPTIME_HEARTBEAT_URL_REF}
+ * and {@link platformBackupHeartbeatUrlRef}) stay reachable from the name
+ * alone. Throws on a name this module did not itself produce -- a
+ * programmer error, never a live value.
+ */
+export declare function heartbeatCheckUrlRef(name: string): string;
+/**
+ * #540: the sorted, comma-joined {@link desiredHeartbeatCheckNames} as of the
+ * last successful reconcile -- recorded by `provisionPlatformHeartbeats`
+ * once it has created every missing check and deleted every stale one.
+ * {@link planHeartbeats} plans the reconcile step again only when the
+ * declared desired set has since changed (a backup service's database
+ * arrived, say), not on every apply: `driveApply`'s bootstrap loop
+ * (`bootstrap/drive.ts`) only ever terminates once a plan has zero steps, so
+ * a step planned unconditionally on every round -- as this one once was --
+ * never lets a platform with `hc` enabled (the default, #540) finish
+ * bootstrapping at all.
+ */
+export declare const PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY = "heartbeats_applied_desired";
 /**
  * Options for {@link planPlatform}, replacing four positional arguments that
  * shifted on every merge that added a platform service (#186, #187, #188) --
@@ -721,6 +819,26 @@ export interface PlanPlatformOptions {
          * "executor missing" shape {@link authExecutorMissing} has for auth.
          */
         backupExecutorMissing?: boolean;
+        /** #540: why `hc` is blocked, or absent when it is not. */
+        hc?: string;
+        /**
+         * #540: true once `hc` is applied but the host built the platform
+         * executor with no heartbeats dependencies -- the heartbeat-checks step
+         * is blocked, not planned, the same "executor missing" shape
+         * {@link backupExecutorMissing} has for a backup.
+         */
+        heartbeatsExecutorMissing?: boolean;
+        /**
+         * #540 round 2: true while the heartbeats dependencies are wired but no
+         * value is held under {@link PLATFORM_HC_API_KEY_REF} -- there is no
+         * bootstrap that mints hc's first superuser and project API key yet
+         * (issue #540's own "Decide"), so a fresh platform's heartbeats step
+         * would otherwise call hc's real Management API with no account and no
+         * key behind it. Blocked, not planned, until a human creates both by
+         * hand and holds the key under that ref; see this flag's own "Human
+         * steps" note in `platform-providers.ts`'s `FoundryPlatformStepExecutor.blockedSteps`.
+         */
+        heartbeatsApiKeyMissing?: boolean;
     };
     /**
      * Steps whose live state differs from the declared one in a way the recorded

package/dist/plan/platform-diff.js

@@ -750,6 +750,124 @@ export const PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY = 'edge_applied_git_ref';
  * (the {@link PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY} pattern). Not a secret.
  */
 export const PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY = 'edge_platform_internal_url';
+/**
+ * #540: the resource key `planHc` plans under and `FoundryPlatformStepExecutor`
+ * dispatches on -- the {@link PLATFORM_EDGE_KEY} shape for the platform's own
+ * heartbeat server (self-hosted Healthchecks). `runPlatformSteps` records
+ * the app's uuid under `coolify:app:platform:hc` once the step succeeds,
+ * which is what stops `planHc` planning it again.
+ */
+export const PLATFORM_HC_KEY = 'platform:hc';
+/**
+ * #540: the hostname and `gitRef` (a Docker image tag, like `mail.gitRef`)
+ * the last successful `hc` run applied. `planHc` plans the step again when
+ * either differs from the declared value; a re-run patches the image tag
+ * and redeploys, and mints nothing new (`SECRET_KEY` is generated once and
+ * read back, never regenerated -- see `ensureGeneratedEnv`).
+ */
+export const PLATFORM_HC_APPLIED_HOSTNAME_SCOPE_KEY = 'hc_applied_hostname';
+export const PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY = 'hc_applied_git_ref';
+/**
+ * #540 round 2: the held-key ref a human puts hc's first project API key
+ * under -- `deliverSecret`'s naming convention (`EDGE_URL`'s own pattern),
+ * `<service>:<scope>:<name>` like {@link PLATFORM_EDGE_KEY_REF}. Nothing in
+ * this package mints this key: `provisionPlatformHc` stands up an empty
+ * Healthchecks instance with no user, no project and so no key, and neither
+ * a `manage.py` command nor a documented API mints a project's own API key
+ * (confirmed against `healthchecks/healthchecks`'s own source, 2026-10) --
+ * only its web UI does, after a first superuser signs in by hand. Until a
+ * human does that and holds the key here, `FoundryPlatformStepExecutor
+ * .blockedSteps` (`platform-providers.ts`) reports the heartbeat checks
+ * blocked (`PlanPlatformOptions.blocked.heartbeatsApiKeyMissing`) rather
+ * than let `planHeartbeats` plan a step that would call hc's real
+ * Management API with no account and no key behind it -- see issue #540's
+ * own "Human steps" note. This package never reads the value back: whoever
+ * implements {@link HeartbeatsPort} against hc's real HTTP API is the host,
+ * and that implementation is where the key is actually used.
+ */
+export const PLATFORM_HC_API_KEY_REF = 'hc:platform:apiKey';
+/**
+ * #540: the heartbeat check named after the uptime Worker (foundry#542,
+ * which is what actually pings it -- blocked today on edge#26, so nothing
+ * pings this check yet; it still exists so the Worker has a URL to deliver
+ * to the moment it can). `platformBackupHeartbeatCheckName` is the matching
+ * name for each platform database backup (`PLATFORM_BACKUP_SERVICE_KEYS`).
+ * Both names are also the prefix `provisionPlatformHeartbeats`
+ * (`platform-providers.ts`) uses to recognise which live Healthchecks
+ * checks are its own to delete when they are no longer wanted -- it never
+ * touches a check outside this naming scheme.
+ */
+export const PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME = 'uptime-worker';
+/** #540: see {@link PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME}'s own doc comment. */
+export function platformBackupHeartbeatCheckName(service) {
+    return `backup-${service}`;
+}
+/**
+ * #540: the held-key ref each heartbeat check's own ping URL is recorded
+ * under, once created -- `deliverSecret`'s ref-naming convention
+ * (`EDGE_URL`'s own pattern), read back by whoever owns that piece of
+ * scheduled work. `platformBackupHeartbeatUrlRef` is the per-service
+ * counterpart. Unlike a minted credential (CLAUDE.md platform-step rule 1),
+ * a ping URL is not retried-and-guarded the same way: it is closer to a
+ * resource id, so `provisionPlatformHeartbeats` simply records it again
+ * every time the check it names is (re)created.
+ */
+export const PLATFORM_UPTIME_HEARTBEAT_URL_REF = 'uptime:heartbeatUrl';
+/** #540: see {@link PLATFORM_UPTIME_HEARTBEAT_URL_REF}'s own doc comment. */
+export function platformBackupHeartbeatUrlRef(service) {
+    return `backup:${service}:heartbeatUrl`;
+}
+/**
+ * #540: every heartbeat check name foundry currently wants -- the uptime
+ * Worker's own, plus one per platform database backup that already has a
+ * recorded database id (`PLATFORM_BACKUP_SERVICE_KEYS`, the same "nothing to
+ * report yet" gate {@link planBackups} itself uses for a service with no
+ * database). Shared by {@link planHeartbeats} (to tell whether anything
+ * declared has changed since the last successful reconcile) and
+ * `provisionPlatformHeartbeats` (`platform-providers.ts`, to decide what to
+ * create or delete live) so the two can never compute a different desired
+ * set from each other.
+ */
+export function desiredHeartbeatCheckNames(recordedIds) {
+    const names = [PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME];
+    for (const service of PLATFORM_BACKUP_SERVICE_KEYS) {
+        if (recordedIds[PLATFORM_BACKUP_DATABASE_SCOPE_KEYS[service]]) {
+            names.push(platformBackupHeartbeatCheckName(service));
+        }
+    }
+    return names;
+}
+/**
+ * #540: the held-key ref a check named `name` (one {@link desiredHeartbeatCheckNames}
+ * produced) records its ping URL under -- `platform-providers.ts`'s
+ * `provisionPlatformHeartbeats` looks this up rather than re-deriving it
+ * inline, so the two name-to-ref mappings ({@link PLATFORM_UPTIME_HEARTBEAT_URL_REF}
+ * and {@link platformBackupHeartbeatUrlRef}) stay reachable from the name
+ * alone. Throws on a name this module did not itself produce -- a
+ * programmer error, never a live value.
+ */
+export function heartbeatCheckUrlRef(name) {
+    if (name === PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME)
+        return PLATFORM_UPTIME_HEARTBEAT_URL_REF;
+    for (const service of PLATFORM_BACKUP_SERVICE_KEYS) {
+        if (name === platformBackupHeartbeatCheckName(service))
+            return platformBackupHeartbeatUrlRef(service);
+    }
+    throw new Error(`heartbeatCheckUrlRef: unrecognised heartbeat check name '${name}'`);
+}
+/**
+ * #540: the sorted, comma-joined {@link desiredHeartbeatCheckNames} as of the
+ * last successful reconcile -- recorded by `provisionPlatformHeartbeats`
+ * once it has created every missing check and deleted every stale one.
+ * {@link planHeartbeats} plans the reconcile step again only when the
+ * declared desired set has since changed (a backup service's database
+ * arrived, say), not on every apply: `driveApply`'s bootstrap loop
+ * (`bootstrap/drive.ts`) only ever terminates once a plan has zero steps, so
+ * a step planned unconditionally on every round -- as this one once was --
+ * never lets a platform with `hc` enabled (the default, #540) finish
+ * bootstrapping at all.
+ */
+export const PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY = 'heartbeats_applied_desired';
 /**
  * #167: the platform's own diff engine, mirroring `diff.ts`'s
  * `computePlanDetail` for the one shared {@link DeclaredPlatform} record
@@ -808,6 +926,17 @@ export function planPlatform(platform, live, options = {}) {
         : (service) => `the platform's ${service} is blocked, not planned: every DNS record is written through edge, and edge is neither applied nor planned (${platform.edge.enabled
             ? (edge.blocked ?? 'its step is not planned')
             : 'the platform does not enable edge'})`;
+    // #540: hc needs only edge's DNS, the same as mail and archon -- no
+    // auth/ZITADEL client, so it is planned here rather than after `authReady`
+    // further down.
+    const hc = planHc(platform, recordedIds, blocked.hc ?? dnsBlocked?.('heartbeat server'));
+    if (hc.step)
+        plannedSteps.push(hc.step);
+    // #540: the `authReady` pattern, for hc -- true once hc is either already
+    // applied or about to run earlier in this very plan, so the heartbeats
+    // reconcile below can be planned in the *same* round hc first comes up,
+    // the same way files/mail/archon are planned in auth's own first round.
+    const hcReady = hc.step !== null || Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_HC_KEY)]);
     const auth = planAuth(platform, recordedIds, blocked.auth ?? dnsBlocked?.('sign-in'), blocked.authExecutorMissing ?? false, drifted.auth ?? false, blocked.authOtherInputsMissing ?? []);
     if (auth.step)
         plannedSteps.push(auth.step);
@@ -841,6 +970,12 @@ export function planPlatform(platform, live, options = {}) {
     // recorded is already visible to `recordedIds` on this same plan.
     const backups = planBackups(byKey, claimed, recordedIds, blocked.backupExecutorMissing ?? false, drifted.backupStorage ?? false, drifted.backupStorageBlocked);
     plannedSteps.push(...backups.steps);
+    // #540: last of all, so the backup databases `planBackups` just saw above
+    // are the same set this reconcile sees too -- one check per platform
+    // database backup, plus the uptime Worker's own.
+    const heartbeats = planHeartbeats(platform, recordedIds, hcReady, blocked.heartbeatsExecutorMissing ?? false, blocked.heartbeatsApiKeyMissing ?? false);
+    if (heartbeats.step)
+        plannedSteps.push(heartbeats.step);
     // #251: one line per service whose recorded applied ref no longer matches
     // what the next apply would use (or, for zitadel, what is actually live).
     // Never pushed into `plannedSteps` -- see `VersionChangeItem`'s own doc
@@ -867,6 +1002,9 @@ export function planPlatform(platform, live, options = {}) {
         edge.blocked
             ? null
             : versionChangeLine('edge', recordedIds[PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY], platform.edge.gitRef, 'git ref, redeploy'),
+        hc.blocked
+            ? null
+            : versionChangeLine('hc', recordedIds[PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY], platform.hc.gitRef, 'image, redeploy'),
         auth.blocked
             ? null
             : versionNotAppliedLine('zitadel', Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_AUTH_KEY)]), recordedIds[PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY], VERSIONS.zitadel),
@@ -900,6 +1038,8 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: ai.blocked, key: 'ai' });
     if (edge.blocked)
         unmanaged.push({ description: edge.blocked, key: 'edge' });
+    if (hc.blocked)
+        unmanaged.push({ description: hc.blocked, key: 'hc' });
     if (archon.blocked)
         unmanaged.push({ description: archon.blocked, key: 'archon' });
     // #398: the old integrations key stays pinned until Archon holds the new
@@ -914,6 +1054,8 @@ export function planPlatform(platform, live, options = {}) {
         });
     }
     unmanaged.push(...backups.blocked);
+    if (heartbeats.blocked)
+        unmanaged.push({ description: heartbeats.blocked, key: 'heartbeats' });
     return { plannedSteps: plannedSteps.map(withStepSystem), unmanaged, versionChanges };
 }
 /**
@@ -1826,6 +1968,136 @@ function planEdge(platform, recordedIds, executorBlocked) {
         blocked: null,
     };
 }
+/**
+ * #540: a self-hosted heartbeat server (Healthchecks) for the platform, for
+ * now -- a Coolify Postgres plus one Docker-image app
+ * (`healthchecks/healthchecks`), reached through edge's tunnel and DNS at
+ * `platform.hc.hostname`, the {@link planEdge} bundling shape minus any
+ * auth/ZITADEL client: `hc` is an internal operational tool, not something
+ * an organisation member signs into. Whether this stays the platform's
+ * heartbeat server long-term, instead of or alongside the hand-set-up
+ * `hc.wtfalch.dev` instance, and what happens to that instance's own data,
+ * are both still open "Decide" items on issue #540's own thread -- not
+ * settled by this code.
+ *
+ * Idempotent on the recorded app id plus the applied hostname and `gitRef`,
+ * for {@link planAuth}'s own reason: no platform reader reports this
+ * Coolify app. A changed hostname or `gitRef` plans the step again (a
+ * redeploy, no new secret -- `SECRET_KEY` is generated once by
+ * `provisionPlatformHc` and read back, never regenerated).
+ *
+ * Blocked, not planned: `executorBlocked`, from `dnsBlocked` (edge neither
+ * applied nor planned) or the host building no `hc` dependencies.
+ */
+function planHc(platform, recordedIds, executorBlocked) {
+    if (!platform.hc.enabled)
+        return { step: null, blocked: null };
+    const { hostname, gitRef } = platform.hc;
+    const applied = Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_HC_KEY)]) &&
+        recordedIds[PLATFORM_HC_APPLIED_HOSTNAME_SCOPE_KEY] === hostname &&
+        recordedIds[PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY] === gitRef;
+    if (applied)
+        return { step: null, blocked: null };
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_HC_KEY,
+                desired: { hostname, gitRef },
+            },
+            step: {
+                description: `provision the heartbeat server (Healthchecks) at ${hostname}, with its own database`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
+/**
+ * #540: one reconcile step for every heartbeat check foundry owns -- the
+ * uptime Worker's own check plus one per platform database backup
+ * (`PLATFORM_BACKUP_SERVICE_KEYS`, filtered the same way {@link planBackups}
+ * is to "has a recorded database", so a service with no database yet gets
+ * no standing check either). The actual create-missing/delete-stale
+ * reconciling against the live Healthchecks list (`HeartbeatsPort.listChecks`,
+ * `platform-providers.ts`) happens inside `provisionPlatformHeartbeats`
+ * itself, not here -- this function only decides *whether* that step runs
+ * at all: never before `hc` is ready (`hcReady`, the {@link planPlatform}
+ * own `authReady` pattern -- already applied, or about to be, earlier in
+ * this same plan), never with no heartbeats dependencies wired, and never
+ * again once {@link desiredHeartbeatCheckNames} already matches
+ * {@link PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY}'s recorded value.
+ *
+ * That last check is the point: an earlier version of this function planned
+ * the step unconditionally every round, on the theory that
+ * `provisionPlatformHeartbeats` listing live checks first was idempotency
+ * enough. It is, for what it creates -- but `bootstrap/drive.ts`'s
+ * `driveApply` (the loop `bootstrapPlatform` runs to actually stand a
+ * platform up) only stops once a round's plan has zero steps, and `hc` is
+ * enabled by default (`bootstrap/declare.ts`), so a platform that never
+ * recorded "nothing left to reconcile" could never finish bootstrapping at
+ * all -- it would hit `driveApply`'s round cap on every single run. Compare
+ * against the planner's own recorded desired-set marker, declared-to-declared,
+ * so a plan with nothing left to do actually has nothing left to do.
+ *
+ * #540 round 2: also withheld while `apiKeyMissing` -- no human has held a
+ * project API key under {@link PLATFORM_HC_API_KEY_REF} yet, so there is
+ * nothing for the host's own `HeartbeatsPort` to authenticate a real call
+ * with. Without this, a fresh platform's heartbeats step is ready
+ * (`hcReady`) the same round `hc` is merely *planned*, long before anyone
+ * has signed in to it to create that key.
+ */
+function planHeartbeats(platform, recordedIds, hcReady, executorMissing, apiKeyMissing) {
+    if (!platform.hc.enabled) {
+        // Removing checks is not planned. The recorded marker names the checks
+        // foundry's last reconcile wanted, so they are foundry's own; report
+        // them rather than leave them unseen.
+        const left = recordedIds[PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY];
+        return {
+            step: null,
+            blocked: left
+                ? `the heartbeat server is not enabled, but checks foundry created remain on it (${left}); removing them is not planned, delete them in Healthchecks by hand`
+                : null,
+        };
+    }
+    if (!hcReady) {
+        return {
+            step: null,
+            blocked: 'the heartbeat checks are blocked, not planned: platform:hc has not been applied yet',
+        };
+    }
+    if (executorMissing) {
+        return {
+            step: null,
+            blocked: 'the heartbeat checks are blocked, not planned: the host built the platform executor without its heartbeats dependencies',
+        };
+    }
+    if (apiKeyMissing) {
+        return {
+            step: null,
+            blocked: `the heartbeat checks are blocked, not planned: no project API key is held yet for hc (${PLATFORM_HC_API_KEY_REF}); a human must sign in to hc, create the first superuser account and a project, mint that project's API key, and hold it under that ref (issue #540 "Human steps") before this step can call hc's check-creation API`,
+        };
+    }
+    const desired = [...desiredHeartbeatCheckNames(recordedIds)].sort().join(',');
+    if (recordedIds[PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY] === desired) {
+        return { step: null, blocked: null };
+    }
+    return {
+        step: {
+            action: { system: 'heartbeats', kind: 'reconcile', key: 'platform', desired: {} },
+            step: {
+                description: 'reconcile heartbeat checks for the uptime Worker and every platform backup service',
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 /**
  * #172: the platform's AI host (https://github.com/wtfalch/ai) -- a Coolify
  * Postgres plus three apps built from that repo's root Dockerfile, one per

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

@@ -182,6 +182,18 @@ export interface FoundryPlatformStepExecutorOptions {
      * planned.
      */
     backup?: PlatformBackupDeps;
+    /**
+     * #540: dependencies for `coolify:app` keyed {@link PLATFORM_HC_KEY} --
+     * optional for the same reason as `auth`; a host that declares
+     * `platform.hc.enabled` without it gets the step reported as blocked.
+     */
+    hc?: PlatformHcDeps;
+    /**
+     * #540: dependencies for the `heartbeats:reconcile` step -- optional for
+     * the same reason as `auth`; `hc` applied with this unset gets the
+     * heartbeat checks reported as blocked rather than planned.
+     */
+    heartbeats?: PlatformHeartbeatsDeps;
 }
 /**
  * The real {@link PlatformStepExecutor} for the two steps built so far:
@@ -261,6 +273,8 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly edge?;
     private readonly archon?;
     private readonly backup?;
+    private readonly hc?;
+    private readonly heartbeats?;
     constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone' | 'list' | 'get'>, options?: FoundryPlatformStepExecutorOptions);
     blockedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         auth?: string;
@@ -273,6 +287,9 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         archon?: string;
         mail?: string;
         backupExecutorMissing?: boolean;
+        hc?: string;
+        heartbeatsExecutorMissing?: boolean;
+        heartbeatsApiKeyMissing?: boolean;
     }>;
     /**
      * Whether Archon's live Access policy lets through anyone but the declared
@@ -676,6 +693,17 @@ export interface PlatformAiRuntime {
     migrateIntervalMs?: number;
     /** Tries at handing a secret to the host (default 3): the management key and the signing key both use this. */
     deliverAttempts?: number;
+    /**
+     * #543: injected for tests, against a fake runner host -- the runner's own
+     * deploy wait now does a `'ready'` probe of its `/api/health`, the same
+     * `DeployHealthRuntime.fetch` field `provisionPlatformMail`/
+     * `provisionPlatformArchon` already take. Defaults to the global `fetch`.
+     */
+    fetch?: typeof fetch;
+    /** How long to wait for the runner to answer ready (default 5 minutes). */
+    readyTimeoutMs?: number;
+    /** Pause between readiness polls (default 5 seconds). */
+    readyIntervalMs?: number;
 }
 /** The ref the AI management key is delivered under; the host's `AiOrganisationPort` adapter reads it back. */
 export declare const PLATFORM_AI_MANAGEMENT_KEY_REF = "ai:platform:managementKey";
@@ -849,6 +877,17 @@ export interface PlatformFilesRuntime {
     migrateIntervalMs?: number;
     /** Tries at handing each secret to the host (default 3). */
     deliverAttempts?: number;
+    /**
+     * #543: injected for tests, against a fake runner host -- the runner's own
+     * deploy wait now does a `'ready'` probe of its `/api/health`, same as
+     * `provisionPlatformMail`/`provisionPlatformArchon` already take. Defaults
+     * to the global `fetch`.
+     */
+    fetch?: typeof fetch;
+    /** How long to wait for the runner to answer ready (default 5 minutes). */
+    readyTimeoutMs?: number;
+    /** Pause between readiness polls (default 5 seconds). */
+    readyIntervalMs?: number;
 }
 /**
  * #171: how the host signs a files management request with the key this step
@@ -903,6 +942,30 @@ export interface PlatformEdgeDeps {
     /** Clock, sleep and fetch for the readiness wait and delivery retries; real ones by default. */
     runtime?: PlatformEdgeRuntime;
 }
+export interface PlatformHcRuntime {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    readyTimeoutMs?: number;
+    readyIntervalMs?: number;
+}
+/**
+ * #540: dependencies for `coolify:app` keyed {@link PLATFORM_HC_KEY} -- the
+ * {@link PlatformEdgeDeps} bundling shape minus a Cloudflare token of its
+ * own: `hc` writes its tunnel and DNS record through edge the same way
+ * mail and archon do, and needs no `heldKeys`/`deliverSecret` at all --
+ * `SECRET_KEY` (Django's session-signing key) is generated once by
+ * {@link provisionPlatformHc} itself and never leaves this Coolify app.
+ */
+export interface PlatformHcDeps {
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'raw'>;
+    /** F4.dns: every DNS record call, through edge at its recorded address (see {@link PlatformDnsFactory}). */
+    dns: PlatformDnsFactory;
+    /** F4.tunnels: every tunnel call, through edge at its recorded address (see {@link PlatformTunnelsFactory}). */
+    tunnels: PlatformTunnelsFactory;
+    /** Clock, sleep and fetch for the readiness wait; real ones by default. */
+    runtime?: PlatformHcRuntime;
+}
 /**
  * #174: everything {@link provisionPlatformIntegrations} needs beyond
  * {@link PlatformStepExecutionContext} -- a bundle, like
@@ -977,6 +1040,91 @@ export interface PlatformBackupDeps {
     /** A cron string or one of Coolify's names (`daily`, `weekly`, ...). Default `'daily'`. */
     frequency?: string;
 }
+/** One check as self-hosted Healthchecks' own Management API reports it. */
+export interface HeartbeatCheck {
+    id: string;
+    name: string;
+    pingUrl: string;
+}
+/**
+ * #540: the heartbeat server's own Management API -- a project API key in a
+ * header, `POST /api/v3/checks/` with `name`/`unique: ['name']` to upsert a
+ * check idempotently by name, `GET /api/v3/checks/` to list every one,
+ * `DELETE /api/v3/checks/<uuid>` to remove one -- restated here as the port
+ * `provisionPlatformHeartbeats` plans and provisions against, never a real
+ * HTTP client: this package never connects itself (`README.md`), so the
+ * host implements this against its own running `hc` instance and its own
+ * project API key, the same seam every other real I/O in this file crosses.
+ */
+export interface HeartbeatsPort {
+    listChecks(): Promise<HeartbeatCheck[]>;
+    /** Creates a check named `name`, or returns the existing one of that name -- the Management API's own upsert. */
+    createCheck(name: string): Promise<HeartbeatCheck>;
+    /**
+     * #540 round 2: pauses a check (`POST /api/v3/checks/<uuid>/pause/`) so it
+     * reads "paused" rather than "down" while nothing actually pings it yet --
+     * both the uptime Worker's own check and every backup check (see this
+     * file's own doc comment on `PlatformHeartbeatsDeps` for why). Sending a
+     * check a ping resumes it automatically (Healthchecks' own documented
+     * behaviour), so foundry never has to call the reverse of this: once a
+     * real pinger exists, the check un-pauses itself on its first ping.
+     * `provisionPlatformHeartbeats` calls this exactly once, right after
+     * `createCheck`, and never again on a check it merely finds already live
+     * -- a check already being pinged, or one an operator unpaused by hand,
+     * must never be paused again by a reconcile run.
+     */
+    pauseCheck(id: string): Promise<void>;
+    deleteCheck(id: string): Promise<void>;
+}
+/**
+ * #540: dependencies for the `heartbeats:reconcile` step
+ * (`platform-diff.ts`'s `planHeartbeats`).
+ *
+ * #540 round 2: `resolve` is new. It guards only the *delete* half of
+ * {@link provisionPlatformHeartbeats} -- a live check is only ever deleted
+ * when foundry itself holds a ping URL for its exact name
+ * (`heartbeatCheckUrlRef`, `platform-diff.ts`), proof this run or an
+ * earlier one created it. Without that guard, a hand-made check sharing
+ * foundry's naming scheme (an operator's own `uptime-worker`, say, made
+ * before foundry ever ran) could be deleted the moment that name was not
+ * yet desired -- a backup service with no recorded database yet is in
+ * `provisionPlatformHeartbeats`'s own `ownedNames` but not `desiredSet`.
+ * `resolve` is never consulted on the *create* half: a check already live
+ * under a desired name is always treated as foundry's, the way it always
+ * was, and (the round-2 fix for a second bug) its ping address is now
+ * always re-saved rather than only on the create that first makes it live
+ * -- see `put`'s own doc comment below for why that half carries no
+ * adoption risk the way deleting does.
+ *
+ * `put` records a check's own ping URL -- on every create, and (new this
+ * round) on every run that finds a desired check already live, not only
+ * the run that created it. Before this fix, a save that failed once, or a
+ * run that died between create and save, or a host that wired `heldKeys`
+ * only after the original create, lost that address for good: the next run
+ * found the check already live and never saved anything, despite this very
+ * doc comment already claiming the step "can simply ask the live check
+ * again." Required whenever an address actually needs saving -- optional
+ * only so a host without one still compiles, in which case nothing here
+ * can ever be created or re-confirmed, and the step throws rather than
+ * silently drop an address: CLAUDE.md platform-step rule 1 is written for a
+ * minted credential, not a ping URL (a lost one is simply re-asked from the
+ * live check, never re-minted), but the rule's "never silently lose it"
+ * half applies just as well here.
+ *
+ * Both fields are optional only so a host without either still compiles;
+ * while `PlatformHeartbeatsDeps` is wired at all, `FoundryPlatformStepExecutor
+ * .blockedSteps`'s own `heartbeatsApiKeyMissing` check blocks the step
+ * until a project API key is held under {@link PLATFORM_HC_API_KEY_REF}, so
+ * the live Healthchecks calls below are never reached with nothing behind
+ * them.
+ */
+export interface PlatformHeartbeatsDeps {
+    heartbeats: HeartbeatsPort;
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null>;
+        put?(ref: string, value: string): Promise<void>;
+    };
+}
 /**
  * The real {@link PlatformCloudflareReader}: the platform's apex zone as
  * `planApexZone` expects to see it, and nothing else. The zone's DNS records
@@ -1006,7 +1154,7 @@ export declare class ProvidersPlatformCloudflareReader implements PlatformCloudf
 export declare class ProvidersPlatformCoolifyReader implements PlatformCoolifyReader {
     private readonly client;
     private readonly platformStore;
-    constructor(client: Pick<CoolifyPort, 'getApplication' | 'getDatabase' | 'listDatabaseBackups'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
+    constructor(client: Pick<CoolifyPort, 'getApplication' | 'getDatabase' | 'listDatabaseBackups' | 'raw'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
     listResources(): Promise<LiveResource[]>;
 }
 /** Scope id (no `:`): the share domains the runner's Coolify `domains` was last set to, comma-joined. */