@celilo/cli 4.0.0 → 4.1.0

package/src/services/audit/server-bun-pin.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { auditServerBunPin, readPinnedBunVersion } from './server-bun-pin';
+
+const PIN = '/etc/celilo/mise.pin.toml';
+
+describe('server bun pin audit', () => {
+  test('silent when the running bun is the pinned bun', () => {
+    expect(
+      auditServerBunPin({ pinnedVersion: '1.4.2', runningVersion: '1.4.2', pinPath: PIN }),
+    ).toEqual([]);
+  });
+
+  test('reports drift naming both versions — the celilo#1379 shape', () => {
+    const [finding] = auditServerBunPin({
+      pinnedVersion: '1.4.2',
+      runningVersion: '1.3.3',
+      pinPath: PIN,
+    });
+    expect(finding?.code).toBe('server_bun_pin_drift');
+    expect(finding?.severity).toBe('drift');
+    expect(finding?.message).toContain('1.3.3');
+    expect(finding?.message).toContain('1.4.2');
+  });
+
+  test('an unreadable pin is unmeasured, never green', () => {
+    const [finding] = auditServerBunPin({
+      pinnedVersion: null,
+      runningVersion: '1.4.2',
+      pinPath: PIN,
+    });
+    expect(finding?.severity).toBe('unmeasured');
+  });
+
+  test('reads the bun line out of the shipped pin file', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-pin-'));
+    const path = join(dir, 'mise.pin.toml');
+    writeFileSync(path, '# comment\n[tools]\nbun = "1.4.2"\nterraform = "1.10.0"\n');
+    expect(readPinnedBunVersion(path)).toBe('1.4.2');
+    expect(readPinnedBunVersion(join(dir, 'absent.toml'))).toBeNull();
+  });
+});

package/src/services/audit/server-bun-pin.ts

@@ -0,0 +1,95 @@
+/**
+ * Server bun-pin drift (celilo#1379).
+ *
+ * The deb pins the bun celilo was built and tested against, and the CLI runs
+ * on whatever bun mise resolves at /var/celilo. Those can disagree: for three
+ * months celilo-mgr ran on bun 1.3.3 while the shipped pin said 1.4.2,
+ * because the postinst seeded the pin file once and an upgrade never
+ * rewrote it. 1.3.3's `Bun.YAML.parse` reads a bare `on:` key as `true`, so
+ * production was running a parser no gate had ever exercised.
+ *
+ * The postinst now rewrites the pin on every configure, which closes the way
+ * that drift arose. This check is what makes the drift VISIBLE if it arises
+ * some other way — an operator's `mise use`, a hand-edited config, a
+ * dispatcher still holding an old runtime.
+ *
+ * It compares the pin the deb shipped against the bun THIS process is
+ * running on. Not `mise which bun`, which answers what mise would resolve
+ * now rather than what is actually executing (measured 2026-09-10: mise
+ * named 1.4.2 and ran 1.3.3 on the same box).
+ */
+
+import { readFileSync } from 'node:fs';
+import type { DriftFinding } from './types';
+
+export interface ServerBunPinAuditDeps {
+  /** The bun version the installed deb pins, or `null` when unreadable. */
+  pinnedVersion: string | null;
+  /** The bun this process is running on, or `null` when not under bun. */
+  runningVersion: string | null;
+  /** Where `pinnedVersion` was read from — named in the finding. */
+  pinPath: string;
+}
+
+export function auditServerBunPin(deps: ServerBunPinAuditDeps): DriftFinding[] {
+  const { pinnedVersion, runningVersion, pinPath } = deps;
+
+  if (pinnedVersion === null || runningVersion === null) {
+    return [
+      {
+        category: 'server_bun_pin',
+        severity: 'unmeasured',
+        code: 'server_bun_pin_unmeasured',
+        subject: 'system',
+        message:
+          pinnedVersion === null
+            ? `No bun pin could be read from ${pinPath}, so the running bun was compared against nothing.`
+            : 'This process is not running under bun, so the running bun version is unknown.',
+        remediation:
+          pinnedVersion === null
+            ? `Confirm the celilo deb is installed and ${pinPath} exists (\`sudo apt install --reinstall celilo\`).`
+            : 'Run `celilo system audit` from the deb-installed celilo (/usr/local/bin/celilo).',
+        actionable: false,
+      },
+    ];
+  }
+
+  if (pinnedVersion === runningVersion) return [];
+
+  return [
+    {
+      category: 'server_bun_pin',
+      severity: 'drift',
+      code: 'server_bun_pin_drift',
+      subject: 'system',
+      message: `celilo is running on bun ${runningVersion}, but the installed deb pins bun ${pinnedVersion} (${pinPath}).`,
+      details:
+        'celilo is tested against the pinned bun only. A different runtime is not a version-number mismatch — bun 1.3.3 and 1.4.2 parse the same YAML differently, which is how a deploy shipped on an untested parser (celilo#1379).',
+      remediation:
+        'Reconcile the runtime: `sudo apt install --reinstall celilo` rewrites /var/celilo/mise.local.toml from the deb pin, then `celilo events restart-daemon` puts the dispatcher on it.',
+      actionable: false,
+    },
+  ];
+}
+
+/** The pin the deb ships. Read at audit time — never a copy in celilo's code. */
+export const DEB_PIN_PATH = '/etc/celilo/mise.pin.toml';
+
+export function readPinnedBunVersion(path: string = DEB_PIN_PATH): string | null {
+  try {
+    // One `bun = "x.y.z"` line under [tools]. A TOML parser for one key would
+    // be a dependency to read a file this file's own format gate keeps simple.
+    const match = readFileSync(path, 'utf-8').match(/^\s*bun\s*=\s*"([^"]+)"/m);
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function collectServerBunPinDeps(pinPath: string = DEB_PIN_PATH): ServerBunPinAuditDeps {
+  return {
+    pinnedVersion: readPinnedBunVersion(pinPath),
+    runningVersion: process.versions.bun ?? null,
+    pinPath,
+  };
+}

package/src/services/audit/types.ts

@@ -27,6 +27,8 @@ export type DriftCategory =
   | 'schema'
   | 'capability_abi'
   | 'browser_pin'
+  | 'server_bun_pin'
+  | 'reboot_pending'
   | 'terraform_plan'
   | 'module_versions'
   | 'module_configs'

package/src/services/capability-compat.test.ts

@@ -24,6 +24,28 @@ function provider(
 }
 
 describe('unservedCapabilityRequirements', () => {
+  /**
+   * celilo#1384. Optional in PRESENCE, not in contract: with no provider the
+   * module is fine, but an installed provider on another major is called by
+   * the module's hooks and fails there — as a warning, silently.
+   */
+  test('an optional capability with no provider is not a blocker', () => {
+    expect(
+      unservedCapabilityRequirements([], [], [{ name: 'external_web', version: '1.0.0' }]),
+    ).toEqual([]);
+  });
+
+  test('an optional capability whose installed provider is another major IS a blocker', () => {
+    const result = unservedCapabilityRequirements(
+      [],
+      [provider('external_web', 'generic-cpanel', '2.0.0')],
+      [{ name: 'external_web', version: '1.0.0' }],
+    );
+    expect(result).toHaveLength(1);
+    expect(result[0]?.capability).toBe('external_web');
+    expect(result[0]?.providerModuleId).toBe('generic-cpanel');
+  });
+
   test('a requirement any deployed provider serves is not a blocker', () => {
     const providers = [provider('public_web', 'caddy', '4.0.0')];
     expect(

package/src/services/capability-compat.ts

@@ -53,15 +53,27 @@ export interface UnservedCapability {
 export function unservedCapabilityRequirements(
   requirements: CapabilityRequirement[] | undefined,
   providers: DeployedCapabilityProvider[],
+  /**
+   * Capabilities the module uses only if present. Their provider may be
+   * absent, but an installed provider on another major breaks at runtime
+   * exactly as a required one would (celilo#1384), so they take the version
+   * check and skip the presence check.
+   */
+  optional: CapabilityRequirement[] | undefined = undefined,
 ): UnservedCapability[] {
   const unserved: UnservedCapability[] = [];
-  for (const cap of requirements ?? []) {
+  const consumed = [
+    ...(requirements ?? []).map((cap) => ({ cap, required: true })),
+    ...(optional ?? []).map((cap) => ({ cap, required: false })),
+  ];
+  for (const { cap, required } of consumed) {
     // Framework-granted privileges (e.g. cross_module_read) are not
     // provider-backed — the same skip `deploy-preflight` makes.
     if (isPrivilegedCapability(cap.name)) continue;
 
     const installed = providers.filter((p) => p.capabilityName === cap.name);
     if (installed.length === 0) {
+      if (!required) continue;
       unserved.push({
         capability: cap.name,
         required: cap.version,
@@ -119,10 +131,11 @@ export function readDeployedProviders(db: DbClient): DeployedCapabilityProvider[
  */
 export function capabilityBlockersForManifest(
   db: DbClient,
-  manifest: Pick<ModuleManifest, 'requires' | 'id'>,
+  manifest: Pick<ModuleManifest, 'requires' | 'optional' | 'id'>,
 ): UnservedCapability[] {
   return unservedCapabilityRequirements(
     manifest.requires?.capabilities as CapabilityRequirement[] | undefined,
     readDeployedProviders(db),
+    manifest.optional?.capabilities as CapabilityRequirement[] | undefined,
   );
 }

package/src/services/celilo-events.test.ts

@@ -208,6 +208,20 @@ describe('celilo lifecycle events', () => {
       bus.close();
     }
 
+    /** One failed attempt that will be retried — the delivery stays pending. */
+    function recordRetryingFailure(message: string): void {
+      const bus = openBus({ dbPath, events: defineEvents({}) });
+      const sub = bus.getSubscriberByName('caddy.reconcile-web-routes');
+      const event = bus.recentEvents({ type: 'public_web.routes_changed', limit: 1 })[0];
+      if (!sub || !event) {
+        throw new Error('expected a subscriber and an emitted event');
+      }
+      bus.markFailed({ eventId: event.id, subscriberId: sub.id }, message, {
+        retryAfter: Date.now() + 60_000,
+      });
+      bus.close();
+    }
+
     it('routesChangedHighWater is 0 with no events, then the latest id', () => {
       expect(routesChangedHighWater()).toBe(0);
       emitWebRoutesChanged('celilo-website');
@@ -222,6 +236,7 @@ describe('celilo lifecycle events', () => {
         succeeded: 0,
         failed: 0,
         timedOut: false,
+        lastError: null,
         noDispatcher: false,
       });
     });
@@ -237,6 +252,7 @@ describe('celilo lifecycle events', () => {
         succeeded: 0,
         failed: 0,
         timedOut: false,
+        lastError: null,
         noDispatcher: true,
       });
     });
@@ -251,6 +267,7 @@ describe('celilo lifecycle events', () => {
         succeeded: 0,
         failed: 0,
         timedOut: false,
+        lastError: null,
         noDispatcher: false,
       });
     });
@@ -265,6 +282,26 @@ describe('celilo lifecycle events', () => {
       expect(result.timedOut).toBe(true);
     });
 
+    /**
+     * celilo#1401. A handler that CRASHES is retried, so between attempts its
+     * delivery is `pending` with the error already recorded. The deadline hits
+     * in that window and the caller used to report a bare timeout — `0 ok, 0
+     * failed of 1` — which is what hid a caddy crash for days.
+     */
+    it('carries the crashing handler error out of a timeout', async () => {
+      markDispatcherAlive();
+      subscribeReconciler();
+      const since = routesChangedHighWater();
+      emitWebRoutesChanged('celilo-website');
+      // Failed but NOT abandoned: it goes back to pending for the next attempt.
+      recordRetryingFailure('{} is not iterable');
+
+      const result = await waitForRouteReconcile(since, { timeoutMs: 300, pollMs: 50 });
+      expect(result.timedOut).toBe(true);
+      expect(result.failed).toBe(0);
+      expect(result.lastError).toContain('{} is not iterable');
+    });
+
     it('completes once the provider delivery succeeds', async () => {
       markDispatcherAlive();
       subscribeReconciler();
@@ -278,6 +315,7 @@ describe('celilo lifecycle events', () => {
         succeeded: 1,
         failed: 0,
         timedOut: false,
+        lastError: null,
         noDispatcher: false,
       });
     });
@@ -313,6 +351,7 @@ describe('celilo lifecycle events', () => {
         succeeded: 1,
         failed: 0,
         timedOut: false,
+        lastError: null,
         noDispatcher: false,
       });
     });

package/src/services/celilo-events.ts

@@ -222,6 +222,17 @@ export interface RouteReconcileWaitResult {
   succeeded: number;
   failed: number;
   timedOut: boolean;
+  /**
+   * The handler's own error text from the most recent settled-or-retrying
+   * delivery, or null when no delivery has reported one.
+   *
+   * A handler that CRASHES is retried, so for `max_attempts` retries its
+   * delivery is back in `pending` with an error already recorded. The deadline
+   * can hit in that window, and the caller then reported a timeout for what was
+   * a crash — `0 ok, 0 failed of 1` with the real cause nowhere in sight
+   * (celilo#1401, which hid a caddy crash for days behind a deadline message).
+   */
+  lastError: string | null;
   /**
    * True when no event dispatcher was running, so the `routes_changed` event
    * was persisted but never DELIVERED to the provider (caddy). The route is
@@ -290,18 +301,36 @@ export async function waitForRouteReconcile(
       .filter((e) => e.id > sinceEventId);
 
     if (events.length === 0) {
-      return { events: 0, succeeded: 0, failed: 0, timedOut: false, noDispatcher: false };
+      return {
+        events: 0,
+        succeeded: 0,
+        failed: 0,
+        timedOut: false,
+        lastError: null,
+        noDispatcher: false,
+      };
     }
 
-    if (b.health().status === 'no_dispatcher') {
+    // Confirmed, not instant: a dispatcher starved by the deploy's own load looks
+    // exactly like a dead one for a single sample, and abandoning the reconcile on
+    // that reading is celilo#1399 — it failed consumers' re-registration during the
+    // one operation that generates route changes. `lagging` waits like any healthy
+    // bus; the deadline below still bounds it.
+    const health = await b.healthConfirmed();
+    if (health.status === 'no_dispatcher' || health.status === 'wedged') {
+      const why =
+        health.status === 'wedged'
+          ? `dispatcher heartbeat stale with nothing running (wedged, ${Math.round((health.lastHeartbeatAgeMs ?? 0) / 1000)}s)`
+          : 'no dispatcher running';
       console.warn(
-        `[celilo] route-reconcile: no dispatcher running — not waiting; ${events.length} change event(s) persisted, the provider will reconcile on its next run`,
+        `[celilo] route-reconcile: ${why} — not waiting; ${events.length} change event(s) persisted, the provider will reconcile on its next run`,
       );
       return {
         events: events.length,
         succeeded: 0,
         failed: 0,
         timedOut: false,
+        lastError: null,
         noDispatcher: true,
       };
     }
@@ -319,6 +348,7 @@ export async function waitForRouteReconcile(
           succeeded: settled('succeeded'),
           failed: settled('failed') + settled('abandoned'),
           timedOut: pending > 0,
+          lastError: deliveries.find((d) => d.lastError)?.lastError ?? null,
           noDispatcher: false,
         };
       }
@@ -328,7 +358,14 @@ export async function waitForRouteReconcile(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.warn(`[celilo] route-reconcile wait errored: ${msg}`);
-    return { events: 0, succeeded: 0, failed: 0, timedOut: false, noDispatcher: false };
+    return {
+      events: 0,
+      succeeded: 0,
+      failed: 0,
+      timedOut: false,
+      lastError: null,
+      noDispatcher: false,
+    };
   } finally {
     bus?.close();
   }

package/src/services/deploy-preflight.ts

@@ -112,8 +112,15 @@ export async function runPreflight(
   //    drift after deploy; this surface refuses up front so the
   //    operator gets an actionable error instead of a silent
   //    template-generation against an ABI the provider can't fulfil.
-  if (manifest.requires?.capabilities) {
-    for (const cap of manifest.requires.capabilities) {
+  // An OPTIONAL capability joins the version check but not the presence check:
+  // its provider may legitimately be absent, but when one IS installed the
+  // module's hooks call it, so another major breaks at runtime (celilo#1384).
+  {
+    const consumed = [
+      ...(manifest.requires?.capabilities ?? []).map((cap) => ({ cap, required: true })),
+      ...(manifest.optional?.capabilities ?? []).map((cap) => ({ cap, required: false })),
+    ];
+    for (const { cap, required } of consumed) {
       // Framework-granted privileges (e.g. cross_module_read) aren't
       // provider-backed — they're gated by the allow-list at import time,
       // not satisfied by deploying another module. Skip them here.
@@ -126,6 +133,7 @@ export async function runPreflight(
         .where(eq(capabilities.capabilityName, cap.name))
         .all();
       if (providers.length === 0) {
+        if (!required) continue;
         errors.push({
           category: 'missing-capability',
           message: `Required capability '${cap.name}' has no provider installed`,
@@ -154,7 +162,8 @@ export async function runPreflight(
       errors.push({
         category: 'capability-version-mismatch',
         message:
-          `Module '${moduleId}' requires ${cap.name}@${cap.version} but ` +
+          `Module '${moduleId}' ${required ? 'requires' : 'optionally uses'} ` +
+          `${cap.name}@${cap.version} but ` +
           `provider '${example.moduleId}' offers ${cap.name}@${example.version}`,
         suggestion:
           reason === 'caller_minor_too_old'

package/src/services/deploy-validation.test.ts

@@ -19,11 +19,15 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { type DbClient, getDb } from '../db/client';
-import { modules, secrets } from '../db/schema';
+import { capabilities, modules, secrets } from '../db/schema';
 import type { ModuleManifest } from '../manifest/schema';
 import { resetTestDbPath } from '../test-utils/db-path';
 import { findMissingSecrets } from './config-interview';
-import { findMissingBuildArtifacts, findMissingRequiredVariables } from './deploy-validation';
+import {
+  findMissingBuildArtifacts,
+  findMissingRequiredVariables,
+  validateAndPrepareDeployment,
+} from './deploy-validation';
 
 function manifestWithStringMapSecret(): ModuleManifest {
   return {
@@ -366,3 +370,78 @@ describe('findMissingBuildArtifacts (deploy build-gate)', () => {
     expect(findMissingBuildArtifacts(manifest, dir)).toEqual(['dist/index.html', 'dist/db.sqlite']);
   });
 });
+
+/**
+ * celilo#1384. An OPTIONAL capability is optional in its PRESENCE, not in its
+ * contract: with a provider installed the module's hooks call it, so a
+ * provider on another major fails at runtime — and `on_install` failing is
+ * only a warning, so it fails silently. Measured: generic-cpanel 0.4.1+2
+ * (external_web 2.0.0) against tango-nexus 0.8.0 (optional external_web
+ * 1.0.0); nothing published, the site kept serving, nothing said so.
+ */
+describe('validateAndPrepareDeployment (optional capability version gate)', () => {
+  let tempDir: string;
+  let db: DbClient;
+
+  function seed(optionalVersion: string, providerVersion: string | null) {
+    db.insert(modules)
+      .values({
+        id: 'consumer',
+        name: 'Consumer',
+        sourcePath: tempDir,
+        version: '1.0.0',
+        manifestData: {
+          celilo_contract: '1.0',
+          id: 'consumer',
+          name: 'Consumer',
+          version: '1.0.0',
+          description: 'fixture',
+          optional: { capabilities: [{ name: 'external_web', version: optionalVersion }] },
+        },
+      })
+      .run();
+    if (providerVersion === null) return;
+    db.insert(modules)
+      .values({
+        id: 'provider',
+        name: 'Provider',
+        sourcePath: tempDir,
+        version: '1.0.0',
+        manifestData: {},
+      })
+      .run();
+    db.insert(capabilities)
+      .values({
+        moduleId: 'provider',
+        capabilityName: 'external_web',
+        version: providerVersion,
+        data: {},
+      })
+      .run();
+  }
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-optional-cap-'));
+    process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+    db = getDb();
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    resetTestDbPath();
+  });
+
+  test('refuses the deploy when the installed provider is another major', async () => {
+    seed('1.0.0', '2.0.0');
+    const result = await validateAndPrepareDeployment('consumer', db);
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('external_web');
+    expect(result.error).toContain('provider');
+  });
+
+  test('does not refuse when nobody provides the optional capability', async () => {
+    seed('1.0.0', null);
+    const result = await validateAndPrepareDeployment('consumer', db);
+    expect(result.error).toBeUndefined();
+  });
+});

package/src/services/deploy-validation.ts

@@ -113,6 +113,25 @@ export async function validateAndPrepareDeployment(
     }
   }
 
+  // An OPTIONAL capability is optional in its PRESENCE, not in its contract.
+  // When a provider is installed the module's hooks will call it, so a provider
+  // on another major breaks at runtime exactly as a required one would — except
+  // an `on_install` failure is only a warning, so it breaks silently
+  // (celilo#1384). No provider installed is still fine: the version check below
+  // skips a capability nobody provides.
+  if (manifest.optional?.capabilities) {
+    const optionalMismatches = await findCapabilityVersionMismatches(
+      manifest.optional.capabilities,
+      db,
+    );
+    if (optionalMismatches.length > 0) {
+      return {
+        success: false,
+        error: formatVersionMismatchError(moduleId, optionalMismatches),
+      };
+    }
+  }
+
   // Check for missing required variables BEFORE generating — if any are missing
   // we return them for the caller to interview, then the caller re-invokes deploy
   // after the user has answered. This prevents generation from failing mid-way

package/src/services/fleet-checks.ts

@@ -19,7 +19,7 @@
 
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { type Bus, describeError } from '@celilo/event-bus';
+import { type Bus, type BusHealth, describeError } from '@celilo/event-bus';
 import { desc, eq, inArray } from 'drizzle-orm';
 import { parse as parseYaml } from 'yaml';
 import { ProxmoxClient, type ProxmoxCredentials } from '../api-clients/proxmox';
@@ -203,6 +203,12 @@ export interface DispatcherCheckOptions {
    * Injected so the crash-loop aspect is testable without launchd.
    */
   launchdProbe?: (scope: SupervisorScope) => LaunchdUnitStatus | null;
+  /**
+   * A verdict already taken, normally `await bus.healthConfirmed()`. Callers
+   * that can await pass it so a load-starved dispatcher reads `lagging` rather
+   * than the `wedged` a single sample cannot distinguish it from (celilo#1399).
+   */
+  health?: BusHealth;
 }
 
 /**
@@ -214,7 +220,7 @@ export interface DispatcherCheckOptions {
  */
 export function checkDispatcher(bus: Bus, opts: DispatcherCheckOptions = {}): FleetFinding {
   const now = opts.now ?? Date.now();
-  const health = bus.health();
+  const health = opts.health ?? bus.health();
   const hb = bus.db
     .query<HeartbeatRow, []>(
       'SELECT dispatcher_id, last_heartbeat, started_at, pid, version FROM dispatcher_heartbeat ORDER BY last_heartbeat DESC LIMIT 1',
@@ -227,14 +233,25 @@ export function checkDispatcher(bus: Bus, opts: DispatcherCheckOptions = {}): Fl
 
   // (1) running — a fresh heartbeat. health() already classifies a
   // stale/absent heartbeat as no_dispatcher.
-  if (health.status === 'no_dispatcher' || !hb) {
+  if (health.status === 'no_dispatcher' || health.status === 'wedged' || !hb) {
     statuses.push('fail');
-    detail.push(
-      'no live dispatcher — heartbeat absent or stale (events are queueing, not delivered)',
-    );
-    remediations.push(
-      'start the dispatcher: `systemctl --user enable --now celilo-events.service` (or `celilo events install-daemon` then enable it)',
-    );
+    if (health.status === 'wedged') {
+      // Registered, process alive, heartbeat stale, nothing running: it is present
+      // but dead, so "start the dispatcher" is the wrong instruction (celilo#1398).
+      detail.push(
+        `dispatcher WEDGED — pid ${hb?.pid ?? '?'} is alive and registered but its heartbeat is ${Math.round((health.lastHeartbeatAgeMs ?? 0) / 1000)}s old with nothing running (events are queueing, not delivered)`,
+      );
+      remediations.push(
+        health.remedy ?? 'restart the dispatcher: `celilo events restart-daemon --system`',
+      );
+    } else {
+      detail.push(
+        'no live dispatcher — heartbeat absent or stale (events are queueing, not delivered)',
+      );
+      remediations.push(
+        'start the dispatcher: `systemctl --user enable --now celilo-events.service` (or `celilo events install-daemon` then enable it)',
+      );
+    }
     // A unit can be INSTALLED and still dead: the supervisor respawns a
     // program that cannot start in the unit's environment and it dies again,
     // forever. On macOS the classic cause is a PATH-less
@@ -274,6 +291,15 @@ export function checkDispatcher(bus: Bus, opts: DispatcherCheckOptions = {}): Fl
   detail.push(
     `running (pid ${hb.pid}, heartbeat ${Math.round(ageMs / 1000)}s ago, code v${hb.version})`,
   );
+  if (health.status === 'lagging') {
+    // Confirmed alive by a second beat: slow, not dead. Worth saying — an operator
+    // reading a 60s heartbeat wants to know it was checked — but not a failure,
+    // and explicitly not a restart (celilo#1399).
+    statuses.push('warn');
+    detail.push(
+      'heartbeat is stale but still advancing — the dispatcher is alive and starved for CPU, not wedged; it recovers when load drops',
+    );
+  }
   if (health.status === 'stuck') {
     statuses.push('warn');
     detail.push(
@@ -1395,7 +1421,11 @@ export async function runFleetChecks(
   const hostLiveness = opts.hostLiveness ?? (() => collectHostLiveness(db));
   return [
     checkSchemaDrift(db),
-    checkDispatcher(bus, { now: opts.now, installedCodeMtimeMs: opts.installedCodeMtimeMs }),
+    checkDispatcher(bus, {
+      now: opts.now,
+      installedCodeMtimeMs: opts.installedCodeMtimeMs,
+      health: await bus.healthConfirmed(),
+    }),
     checkBuildBusPublishing(bus, db, { now: opts.now }),
     checkSubscribers(bus, db),
     checkCapabilityProviders(db),