@wtfalch/foundry 0.20.0 → 0.21.1

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

@@ -577,6 +577,12 @@ export declare const PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY = "ai_platform_migrat
  * that throws) is repaired by the next one.
  */
 export declare const PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY = "ai_platform_deploy_pending";
+/**
+ * Set before the `coolify:jobs` step writes the scheduler's env and cleared
+ * once its deploy finished, so a run that dies in between is repaired by the
+ * next one. The planner plans the step while it is set.
+ */
+export declare const JOBS_DEPLOY_PENDING_SCOPE_KEY = "jobs_deploy_pending";
 /**
  * #171: the resource key `planFiles` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the {@link PLATFORM_AUTH_KEY} shape for the files host.
@@ -674,6 +680,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 +825,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

@@ -653,6 +653,12 @@ export const PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY = 'ai_platform_migrate_blocke
  * that throws) is repaired by the next one.
  */
 export const PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY = 'ai_platform_deploy_pending';
+/**
+ * Set before the `coolify:jobs` step writes the scheduler's env and cleared
+ * once its deploy finished, so a run that dies in between is repaired by the
+ * next one. The planner plans the step while it is set.
+ */
+export const JOBS_DEPLOY_PENDING_SCOPE_KEY = 'jobs_deploy_pending';
 /**
  * #171: the resource key `planFiles` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the {@link PLATFORM_AUTH_KEY} shape for the files host.
@@ -750,6 +756,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
@@ -782,7 +906,7 @@ export function planPlatform(platform, live, options = {}) {
         plannedSteps.push(zone);
     // #173: the jobs scheduler, second of the eight services this frame leaves
     // open (this file's own doc comment above).
-    const jobs = planJobs(platform, byKey, claimed, jobsObservable);
+    const jobs = planJobs(platform, byKey, claimed, jobsObservable, recordedIds);
     if (jobs.step)
         plannedSteps.push(jobs.step);
     // A blocked SFU is reported in `unmanaged`, not planned: a step the
@@ -808,6 +932,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 +976,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 +1008,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 +1044,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 +1060,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 };
 }
 /**
@@ -972,7 +1120,7 @@ export const JOBS_SCHEDULER_KEY = 'jobs';
  * (`diff.ts`'s eventual `jobs:registration`) has nothing to register against
  * before this exists.
  */
-function planJobs(platform, byKey, claimed, observable) {
+function planJobs(platform, byKey, claimed, observable, recordedIds) {
     const key = resourceKey('coolify', 'jobs', JOBS_SCHEDULER_KEY);
     const live = byKey.get(key);
     if (live)
@@ -983,8 +1131,14 @@ function planJobs(platform, byKey, claimed, observable) {
         // The step also starts the scheduler's database (0.16.3), so a live app
         // whose database the reader saw stopped plans it again. A status the
         // reader could not read is absent, and plans nothing.
+        // An app without `DATABASE_URL_OWNER` also plans it again: the step
+        // sets the owner and runtime URLs the scheduler's migrate stage needs.
+        // So does a recorded pending deploy: the step wrote its env and died
+        // before the deploy finished.
         const databaseStatus = live.config.databaseStatus;
-        if (typeof databaseStatus !== 'string' || databaseStatus.startsWith('running')) {
+        if (live.config.ownerUrlMissing !== true &&
+            !recordedIds[JOBS_DEPLOY_PENDING_SCOPE_KEY] &&
+            (typeof databaseStatus !== 'string' || databaseStatus.startsWith('running'))) {
             return { step: null, blocked: null };
         }
     }
@@ -1826,6 +1980,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