@celilo/cli 3.1.0 → 4.1.0

package/src/services/audit/machine-interface-zones.ts

@@ -0,0 +1,43 @@
+/**
+ * Stored machine interface zone labels that no longer match the zone model.
+ *
+ * A label written at `machine add` is never revisited, so a zone-model change
+ * leaves every earlier machine describing a topology that no longer exists.
+ * Nothing said so until this check: celilo#1382 surfaced only as an upgrade
+ * failing with "no non-loopback interface in zone 'secure-mgmt'", on a machine
+ * that had one.
+ *
+ * `drift`, not `blocked`: a stale label breaks a deploy only when something
+ * resolves by zone, and the remediation is one command.
+ *
+ * Pure over a pre-computed diff — see services/machine-interface-zones.ts.
+ */
+
+import type { ZoneReclassification } from '../machine-interface-zones';
+import type { DriftFinding } from './types';
+
+export interface MachineInterfaceZonesAuditDeps {
+  /** One entry per machine, carrying only the labels that disagree. */
+  machines: Array<{ hostname: string; changes: ZoneReclassification[] }>;
+}
+
+export function auditMachineInterfaceZones(deps: MachineInterfaceZonesAuditDeps): DriftFinding[] {
+  return deps.machines
+    .filter((m) => m.changes.length > 0)
+    .map(({ hostname, changes }) => {
+      const named = changes
+        .map((c) => `${c.name} (${c.ipAddress}): ${c.from} → ${c.to}`)
+        .join(', ');
+      return {
+        category: 'interface_classification',
+        severity: 'drift',
+        code: 'stale_interface_zone_labels',
+        subject: hostname,
+        message: `${hostname}: ${changes.length} stored interface zone label(s) predate the current zone model — ${named}`,
+        details:
+          'Interface zones are decided once, at `machine add`, and never re-checked. When a zone is added or a subnet is declared for one that had none, every machine added earlier keeps the old label. Anything resolving a machine by zone then reports the interface as absent rather than as mislabelled.',
+        remediation: `celilo machine reclassify ${hostname} --apply`,
+        actionable: true,
+      };
+    });
+}

package/src/services/audit/reboot-pending.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'bun:test';
+import { auditRebootPending } from './reboot-pending';
+
+const CLEAN = { pending: false, unmeasured: false, reasons: [] };
+const NOW = 1_700_000_000_000;
+
+describe('auditRebootPending', () => {
+  it('reports a pending reboot as drift, carrying the reason', () => {
+    const [finding] = auditRebootPending({
+      verdict: {
+        pending: true,
+        unmeasured: false,
+        reasons: ['the running kernel is 6.8.0-1063-raspi'],
+      },
+      marker: null,
+      now: () => NOW,
+    });
+
+    expect(finding.severity).toBe('drift');
+    expect(finding.code).toBe('reboot_pending');
+    expect(finding.message).toContain('6.8.0-1063-raspi');
+    expect(finding.remediation).toContain('celilo system reboot');
+  });
+
+  it('reports an unverified reboot as BLOCKED — a control plane may not have come back', () => {
+    const [finding] = auditRebootPending({
+      verdict: CLEAN,
+      marker: { bootIdBefore: 'a', requestedAt: NOW - 3 * 60 * 60 * 1000, reason: 'kernel' },
+      now: () => NOW,
+    });
+
+    expect(finding.severity).toBe('blocked');
+    expect(finding.code).toBe('reboot_unverified');
+    expect(finding.message).toContain('3h ago');
+  });
+
+  it('is silent on a host that is current and has no reboot outstanding', () => {
+    expect(auditRebootPending({ verdict: CLEAN, marker: null, now: () => NOW })).toEqual([]);
+  });
+
+  it('reports UNMEASURED rather than clean when the host could not be asked', () => {
+    const [finding] = auditRebootPending({
+      verdict: { pending: false, unmeasured: true, reasons: [] },
+      marker: null,
+      now: () => NOW,
+    });
+
+    expect(finding.severity).toBe('unmeasured');
+    expect(finding.actionable).toBe(false);
+  });
+
+  it('still reports the unverified reboot when the host itself is unmeasurable', () => {
+    // The two facts are independent: not being able to read the kernel does
+    // not make an outstanding reboot request go away.
+    const findings = auditRebootPending({
+      verdict: { pending: false, unmeasured: true, reasons: [] },
+      marker: { bootIdBefore: 'a', requestedAt: NOW, reason: '' },
+      now: () => NOW,
+    });
+
+    expect(findings.map((f) => f.code)).toEqual(['reboot_unverified', 'reboot_pending_unmeasured']);
+  });
+});

package/src/services/audit/reboot-pending.ts

@@ -0,0 +1,85 @@
+/**
+ * Pending reboot on the management server (celilo#1378).
+ *
+ * `apt-upgrade` printed needrestart's pending-kernel block and that was the
+ * only place the condition was ever visible — so it was visible exactly when
+ * an operator happened to run an upgrade, and invisible the rest of the time.
+ * celilo-mgr sat on a kernel it was not running for days that way.
+ *
+ * Two findings, and they are different facts:
+ *
+ *   reboot_pending    — the host needs a reboot and has not had one.
+ *   reboot_unverified — celilo ASKED for a reboot and nothing has confirmed
+ *                       the host came back. That is the more serious of the
+ *                       two: it is the shape of a control plane that went
+ *                       down and did not return, or returned without its
+ *                       dispatcher.
+ */
+
+import type { RebootMarker, RebootPendingVerdict } from '../system-reboot';
+import type { DriftFinding } from './types';
+
+export interface RebootPendingAuditDeps {
+  verdict: RebootPendingVerdict;
+  /** A reboot celilo requested that `verifyReturn` has not yet cleared. */
+  marker: RebootMarker | null;
+  /** Defaults to `Date.now()`. */
+  now?: () => number;
+}
+
+const HOUR = 60 * 60 * 1000;
+
+export function auditRebootPending(deps: RebootPendingAuditDeps): DriftFinding[] {
+  const findings: DriftFinding[] = [];
+  const now = (deps.now ?? Date.now)();
+
+  if (deps.marker !== null) {
+    const ageHours = Math.round((now - deps.marker.requestedAt) / HOUR);
+    findings.push({
+      category: 'reboot_pending',
+      severity: 'blocked',
+      code: 'reboot_unverified',
+      subject: 'system',
+      message: `celilo requested a reboot ${ageHours}h ago and nothing has confirmed the host came back.`,
+      details:
+        'The process that asks for a reboot goes down with the host, so the return is verified by a second call. An uncleared marker means that call never succeeded — either the host did not reboot, or it came back without its dispatcher.',
+      remediation:
+        'Run `celilo system reboot --verify`. It passes only once the boot id has changed and the dispatcher and CLI answer, and it names which of those is missing.',
+      actionable: true,
+    });
+  }
+
+  if (deps.verdict.unmeasured) {
+    findings.push({
+      category: 'reboot_pending',
+      severity: 'unmeasured',
+      code: 'reboot_pending_unmeasured',
+      subject: 'system',
+      message:
+        'Neither the reboot-required marker nor a kernel pair could be read, so nothing was compared.',
+      details:
+        'An absent /var/run/reboot-required is not evidence of a current kernel — a host without that path simply never writes one.',
+      remediation:
+        'Run `celilo system audit` on the management server itself (Debian/Ubuntu), where /var/run/reboot-required and `uname -r` are readable.',
+      actionable: false,
+    });
+    return findings;
+  }
+
+  if (deps.verdict.pending) {
+    findings.push({
+      category: 'reboot_pending',
+      severity: 'drift',
+      code: 'reboot_pending',
+      subject: 'system',
+      message: `The management server needs a reboot: ${deps.verdict.reasons.join('; ')}.`,
+      details:
+        'A kernel or service the host has installed is not the one it is running. Until it reboots, an upgrade that has been applied on disk has not taken effect.',
+      remediation:
+        'Reboot through celilo: `celilo system reboot --allow-reboot`. It refuses while a module operation is in flight, and `--verify` confirms the host came back.',
+      actionable: true,
+    });
+  }
+
+  return findings;
+}

package/src/services/audit/recurrence-gate.test.ts

@@ -38,7 +38,9 @@ import { auditInterfaceClassification } from './interface-classification';
 import { auditModuleIntegrity } from './module-integrity';
 import { auditModuleVersions } from './module-versions';
 import { auditPublicDns } from './public-dns';
+import { auditRebootPending } from './reboot-pending';
 import { auditSchema } from './schema';
+import { auditServerBunPin } from './server-bun-pin';
 import { auditTerraformPlan } from './terraform-plan';
 import { auditTrustedSources } from './trusted-sources';
 import type { DriftCategory, DriftFinding, DriftSeverity } from './types';
@@ -68,6 +70,25 @@ const GATE: Record<DriftCategory, GateEntry> = {
     because:
       'compares capability versions claimed in installed module manifests against the framework registry and deployed providers, all read from celilo own DB and local manifests — the subject is celilo itself and is always reachable',
   },
+  reboot_pending: {
+    probe: () =>
+      auditRebootPending({
+        verdict: { pending: false, unmeasured: true, reasons: [] },
+        marker: null,
+      }),
+    because:
+      'probed: a host with no /var/run/reboot-required and no readable kernel pair was not measured, and an absent marker is not a current kernel',
+  },
+  server_bun_pin: {
+    probe: () =>
+      auditServerBunPin({
+        pinnedVersion: null,
+        runningVersion: '1.4.2',
+        pinPath: '/etc/celilo/mise.pin.toml',
+      }),
+    because:
+      'probed: the deb pin file can be absent (a non-deb install), and then nothing was compared',
+  },
   browser_pin: {
     because:
       'compares a bundled client playwright revision against the locally provisioned browser binary, both on this machine — always reachable',

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'