@celilo/cli 0.4.1 → 0.5.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.4.1",
+  "version": "0.5.0-alpha.1",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/api-clients/proxmox.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'bun:test';
+import { findNodeForVmid } from './proxmox';
+
+describe('findNodeForVmid (ISS-0090 — Proxmox is source of truth for current location)', () => {
+  // A trimmed /cluster/resources payload: guest rows carry a vmid; node/storage
+  // rows do not (only a node name).
+  const resources = [
+    { node: 'node2' }, // node row — no vmid
+    { node: 'node3' }, // storage row — no vmid
+    { vmid: 200, node: 'node2' }, // caddy
+    { vmid: 201, node: 'node3' }, // authentik
+  ];
+
+  test('returns the node a vmid currently lives on', () => {
+    expect(findNodeForVmid(resources, 200)).toBe('node2');
+    expect(findNodeForVmid(resources, 201)).toBe('node3');
+  });
+
+  test('returns null when the vmid is absent — container not created yet (first deploy)', () => {
+    expect(findNodeForVmid(resources, 999)).toBeNull();
+  });
+
+  test('never matches a node/storage row that has no vmid', () => {
+    expect(findNodeForVmid([{ node: 'node2' }, { node: 'node3' }], 200)).toBeNull();
+  });
+
+  test('returns null for an empty inventory', () => {
+    expect(findNodeForVmid([], 200)).toBeNull();
+  });
+});

package/src/api-clients/proxmox.ts

@@ -114,6 +114,18 @@ async function makeProxmoxRequest<T>(
         });
       });
 
+      // Fail fast instead of hanging on an unreachable host (no implicit timeout
+      // on https.request). Callers treat a failed result as "couldn't reach
+      // Proxmox" and fall back accordingly.
+      req.setTimeout(15_000, () => {
+        req.destroy();
+        resolve({
+          success: false,
+          message: 'Request timed out',
+          details: { timeoutMs: 15_000 },
+        });
+      });
+
       req.end();
     } catch (error) {
       resolve({
@@ -486,6 +498,51 @@ export async function listNodeStorage(
   return makeProxmoxRequest(credentials, `/nodes/${nodeName}/storage`);
 }
 
+/**
+ * Find which Proxmox node a given VMID currently lives on.
+ *
+ * Queries the cluster resource inventory (`/cluster/resources`), which lists
+ * every guest across all nodes with its current node, and matches by VMID
+ * (unique cluster-wide). Returns the node name, or `null` if the VMID isn't
+ * present — i.e. the container hasn't been created yet (a first deploy).
+ *
+ * ISS-0090: this is celilo's source of truth for WHERE a system currently is.
+ * A redeploy must target the node Proxmox reports here, NOT re-derive placement
+ * from the service's `default_target_node` (which only governs new placement) —
+ * otherwise a changed default tries to relocate every running container.
+ */
+export async function getNodeForVmid(
+  credentials: ProxmoxCredentials,
+  vmid: number,
+): Promise<ProxmoxResult<string | null>> {
+  // makeProxmoxRequest sends only url.pathname, so a `?type=vm` filter would be
+  // dropped — fetch the full inventory and match by vmid client-side instead.
+  const result = await makeProxmoxRequest<Array<{ vmid?: number; node?: string }>>(
+    credentials,
+    '/cluster/resources',
+  );
+
+  if (!result.success) {
+    return result;
+  }
+
+  return { success: true, data: findNodeForVmid(result.data, vmid) };
+}
+
+/**
+ * Find the node a VMID lives on within a Proxmox cluster-resource list. Pure
+ * matching logic, split out from the network call for testability (Rule 10).
+ * Non-guest entries (storage/node rows) have no `vmid` and are skipped. Returns
+ * the node name, or `null` when the VMID isn't present.
+ */
+export function findNodeForVmid(
+  resources: Array<{ vmid?: number; node?: string }>,
+  vmid: number,
+): string | null {
+  const match = resources.find((r) => typeof r.vmid === 'number' && r.vmid === vmid);
+  return match?.node ?? null;
+}
+
 /**
  * List available LXC templates in storage
  */

package/src/cli/commands/module-show.ts

@@ -6,7 +6,7 @@
 import { eq } from 'drizzle-orm';
 import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
-import type { ModuleManifest } from '../../manifest/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../../manifest/schema';
 import { buildResolutionContext } from '../../variables/context';
 import { getArg, validateRequiredArgs } from '../parser';
 import type { CommandResult } from '../types';
@@ -60,7 +60,7 @@ export async function handleModuleShowConfig(args: string[]): Promise<CommandRes
 
     for (const [key, value] of Object.entries(context.selfConfig)) {
       // Skip internal/derived keys that aren't useful for display
-      if (key.startsWith('requires.machine.')) continue;
+      if (key.startsWith('requires.system.')) continue;
 
       const line = `  ${key} = ${value}`;
 
@@ -152,7 +152,7 @@ export async function handleModuleShowZone(args: string[]): Promise<CommandResul
     const context = await buildResolutionContext(moduleId, db);
     const manifest = module.manifestData as ModuleManifest;
 
-    const zone = context.selfConfig.zone || manifest.requires?.machine?.zone;
+    const zone = context.selfConfig.zone || getSingularSystemSpec(manifest)?.zone;
 
     if (!zone) {
       return {

package/src/cli/commands/status.ts

@@ -9,7 +9,7 @@ import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { getDb } from '../../db/client';
 import { capabilities, moduleConfigs, modules, systemConfig, systemSecrets } from '../../db/schema';
-import type { ModuleManifest } from '../../manifest/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../../manifest/schema';
 import type { CommandResult } from '../types';
 
 /**
@@ -131,7 +131,7 @@ export async function handleStatus(): Promise<CommandResult> {
         lines.push(`    Status: ${statusInfo.status}`);
 
         // Type: VPS or Container
-        const zone = manifest.requires?.machine?.zone;
+        const zone = getSingularSystemSpec(manifest)?.zone;
         if (zone) {
           lines.push(`    Type: Container (${zone.toUpperCase()})`);
 

package/src/hooks/capability-loader.ts

@@ -368,13 +368,24 @@ export async function loadCapabilityFunctions(
         // otherwise race the async reconcile.
         onRoutesChanged: async () => {
           const reconcile = await emitWebRoutesChangedAndWait(consumingModuleId);
+          // Authoritative (ISS-0081): a route the provider (caddy) never
+          // reconciled is a deploy FAILURE, not a warning. These used to be
+          // logger.warn while register_route returned success anyway, so a
+          // consumer could report "ready" while caddy never learned the
+          // hostname — no site block, no cert, TLS internal_error for clients.
+          if (reconcile.noDispatcher) {
+            throw new Error(
+              `public_web route for ${consumingModuleId} was persisted but NOT delivered to the provider (caddy): no event dispatcher is running, so caddy never reconciled and the hostname has no site block or cert. Run this through \`celilo module deploy\` (which runs the dispatcher) rather than a bare hook.`,
+            );
+          }
           if (reconcile.timedOut) {
-            logger.warn(
-              `public_web reconcile for ${consumingModuleId} did not finish within the deadline (${reconcile.succeeded} ok, ${reconcile.failed} failed of ${reconcile.events} change event(s)); the route is persisted and the provider will reconcile on its next run`,
+            throw new Error(
+              `public_web reconcile for ${consumingModuleId} did not finish within the deadline (${reconcile.succeeded} ok, ${reconcile.failed} failed of ${reconcile.events} change event(s)) — caddy did not confirm the route is live.`,
             );
-          } else if (reconcile.failed > 0) {
-            logger.warn(
-              `public_web reconcile for ${consumingModuleId}: ${reconcile.failed} delivery(ies) failed; the route is persisted but the provider config may be stale`,
+          }
+          if (reconcile.failed > 0) {
+            throw new Error(
+              `public_web reconcile for ${consumingModuleId}: ${reconcile.failed} delivery(ies) failed — caddy could not apply the route, so the hostname is not served.`,
             );
           }
         },

package/src/manifest/schema.ts

@@ -306,7 +306,7 @@ export const UpstreamPublishHookSchema = z.object({
  * Machine resource recommendations
  * Module declares recommended machine resources (CPU, memory, disk, storage)
  */
-export const MachineResourceSchema = z.object({
+export const SystemResourceSchema = z.object({
   cpu: z.number().int().positive().optional().describe('Recommended CPU cores'),
   memory: z.number().int().positive().optional().describe('Recommended memory in MB'),
   disk: z.number().int().positive().optional().describe('Recommended disk size in GB'),
@@ -328,7 +328,7 @@ export const SystemDeclarationSchema = z.object({
     .string()
     .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'system name must be kebab-case')
     .describe('Stable handle for this system; used in $infra:<name> and as the per-system key'),
-  resources: MachineResourceSchema,
+  resources: SystemResourceSchema,
 });
 
 /**
@@ -439,17 +439,17 @@ export const ModuleManifestSchema = z
         capabilities: z.array(CapabilityRequirementSchema).default([]),
         /**
          * The 0..N systems this module deploys (v2/MODULE_SYSTEMS_ADDRESSING.md).
-         * Preferred over the legacy singular `machine`. A module declaring
+         * Preferred over the singular `system`. A module declaring
          * `systems` gets one host per entry, each addressable as `$infra:<name>`.
          */
         systems: z.array(SystemDeclarationSchema).optional(),
         /**
-         * Legacy singular form — sugar for a single unnamed system. Normalized
-         * to one `systems` entry (name `main`) by `getDeclaredSystems`. Optional
-         * because config-only providers (e.g. namecheap) deploy no infrastructure.
-         * New modules should prefer `systems`.
+         * Singular form — sugar for a single unnamed system. Normalized to one
+         * `systems` entry (name `main`) by `getDeclaredSystems`. Optional because
+         * config-only providers (e.g. namecheap) deploy no infrastructure.
+         * Modules declaring more than one host should use `systems`.
          */
-        machine: MachineResourceSchema.optional(),
+        system: SystemResourceSchema.optional(),
       })
       .default({ capabilities: [] }),
 
@@ -730,25 +730,36 @@ export type LifecycleHook = z.infer<typeof LifecycleHookSchema>;
 export type VariableSource = z.infer<typeof VariableSourceSchema>;
 export type VariableType = z.infer<typeof VariableTypeSchema>;
 export type AnsibleCollection = z.infer<typeof AnsibleCollectionSchema>;
-export type MachineResource = z.infer<typeof MachineResourceSchema>;
+export type SystemResource = z.infer<typeof SystemResourceSchema>;
 export type SystemDeclaration = z.infer<typeof SystemDeclarationSchema>;
 export type BaseModuleAspect = NonNullable<ModuleManifest['base_module_aspect']>;
 export type BaseModuleAspectTrigger = BaseModuleAspect['triggers'][number];
 
 /**
  * Normalize a manifest's declared systems (v2/MODULE_SYSTEMS_ADDRESSING.md).
- * Returns `requires.systems` if present; else the legacy singular
- * `requires.machine` as one entry named `main`; else `[]` (config-only module
- * like namecheap). This is the single place the machine→systems sugar lives, so
- * the rest of the codebase only ever reasons about the 0..N collection.
+ * Returns `requires.systems` if present; else the singular `requires.system`
+ * as one entry named `main`; else `[]` (config-only module like namecheap).
+ * This is the single place the system→systems sugar lives, so the rest of the
+ * codebase only ever reasons about the 0..N collection.
  */
 export function getDeclaredSystems(manifest: ModuleManifest): SystemDeclaration[] {
   const requires = manifest.requires;
   if (requires?.systems && requires.systems.length > 0) {
     return requires.systems;
   }
-  if (requires?.machine) {
-    return [{ name: 'main', resources: requires.machine }];
+  const singular = getSingularSystemSpec(manifest);
+  if (singular) {
+    return [{ name: 'main', resources: singular }];
   }
   return [];
 }
+
+/**
+ * The singular system resource spec a module declares: `requires.system`. The
+ * one place callers read the single-system spec (zone, sizing, "does this module
+ * need infra?"). Returns undefined for config-only modules or those declaring the
+ * plural `requires.systems`.
+ */
+export function getSingularSystemSpec(manifest: ModuleManifest): SystemResource | undefined {
+  return manifest.requires?.system;
+}

package/src/manifest/template-validator.test.ts

@@ -14,7 +14,7 @@ function createTestManifest(overrides?: Partial<ModuleManifest>): ModuleManifest
     description: 'Test module',
     requires: {
       capabilities: [],
-      machine: {
+      system: {
         cpu: 2,
         memory: 2048,
         disk: 20,
@@ -54,16 +54,16 @@ function createTestManifest(overrides?: Partial<ModuleManifest>): ModuleManifest
 
 describe('template-validator', () => {
   describe('validateModuleTemplates - valid references', () => {
-    test('validates nested manifest paths (requires.machine.*)', async () => {
+    test('validates nested manifest paths (requires.system.*)', async () => {
       const manifest = createTestManifest();
 
-      // Test that requires.machine.cpu is valid
-      const machine = manifest.requires.machine;
+      // Test that requires.system.cpu is valid
+      const system = manifest.requires.system;
 
-      expect(machine?.cpu).toBe(2);
-      expect(machine?.memory).toBe(2048);
-      expect(machine?.disk).toBe(20);
-      expect(machine?.storage).toBe('local-lvm');
+      expect(system?.cpu).toBe(2);
+      expect(system?.memory).toBe(2048);
+      expect(system?.disk).toBe(20);
+      expect(system?.storage).toBe('local-lvm');
     });
 
     test('validates capability references', async () => {

package/src/manifest/template-validator.ts

@@ -26,7 +26,7 @@ export interface TemplateValidationResult {
  * Returns undefined if path doesn't exist
  *
  * @param obj - Object to traverse
- * @param path - Dot-separated path (e.g., 'requires.machine.cpu')
+ * @param path - Dot-separated path (e.g., 'requires.system.cpu')
  * @returns Value if found, undefined otherwise
  */
 function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
@@ -50,7 +50,7 @@ function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
  * Check if a path exists in the manifest
  *
  * @param manifest - Module manifest
- * @param path - Dot-separated path (e.g., 'requires.machine.cpu')
+ * @param path - Dot-separated path (e.g., 'requires.system.cpu')
  * @returns True if path exists in manifest
  */
 function pathExistsInManifest(manifest: ModuleManifest, path: string): boolean {
@@ -126,7 +126,7 @@ function validateSelfVariable(
     return `Self variable '${path}' not found in module configuration`;
   }
 
-  // Check if it's a nested path (e.g., $self:requires.machine.cpu)
+  // Check if it's a nested path (e.g., $self:requires.system.cpu)
   if (pathExistsInManifest(manifest, path)) {
     return null; // Valid
   }

package/src/manifest/validate.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from 'bun:test';
+import { getSingularSystemSpec } from './schema';
 import {
   validateCapabilityNames,
   validateCapabilityRequirements,
@@ -42,7 +43,7 @@ description: HomeKit bridge for smart home devices
 
 requires:
   capabilities: []
-  machine:
+  system:
     cpu: 1
     memory: 1024
     disk: 20
@@ -71,8 +72,8 @@ variables:
     if (result.success) {
       expect(result.data.id).toBe('homebridge');
       expect(result.data.variables.owns).toHaveLength(2);
-      expect(result.data.requires.machine?.cpu).toBe(1);
-      expect(result.data.requires.machine?.zone).toBe('app');
+      expect(result.data.requires.system?.cpu).toBe(1);
+      expect(result.data.requires.system?.zone).toBe('app');
     }
   });
 
@@ -442,7 +443,7 @@ build:
     }
   });
 
-  test('should validate manifest with VM resource recommendations under requires.machine', () => {
+  test('should validate manifest with VM resources under requires.system (canonical name)', () => {
     const yaml = `
 ${CONTRACT_LINE}
 id: grafana
@@ -451,7 +452,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     cpu: 2
     memory: 2048
     disk: 20
@@ -463,11 +464,11 @@ requires:
 
     expect(result.success).toBe(true);
     if (result.success) {
-      expect(result.data.requires.machine?.cpu).toBe(2);
-      expect(result.data.requires.machine?.memory).toBe(2048);
-      expect(result.data.requires.machine?.disk).toBe(20);
-      expect(result.data.requires.machine?.storage).toBe('local-lvm');
-      expect(result.data.requires.machine?.zone).toBe('app');
+      expect(result.data.requires.system?.cpu).toBe(2);
+      expect(result.data.requires.system?.memory).toBe(2048);
+      expect(result.data.requires.system?.zone).toBe('app');
+      // getSingularSystemSpec resolves the canonical field…
+      expect(getSingularSystemSpec(result.data)?.cpu).toBe(2);
     }
   });
 
@@ -480,7 +481,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     zone: dmz
 `;
 
@@ -488,9 +489,9 @@ requires:
 
     expect(result.success).toBe(true);
     if (result.success) {
-      expect(result.data.requires.machine?.zone).toBe('dmz');
-      expect(result.data.requires.machine?.cpu).toBeUndefined();
-      expect(result.data.requires.machine?.memory).toBeUndefined();
+      expect(result.data.requires.system?.zone).toBe('dmz');
+      expect(result.data.requires.system?.cpu).toBeUndefined();
+      expect(result.data.requires.system?.memory).toBeUndefined();
     }
   });
 
@@ -503,7 +504,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     cpu: -2
     zone: app
 `;
@@ -521,7 +522,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     zone: invalid
 `;
 
@@ -538,7 +539,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     cpu: 2.5
     zone: app
 `;

package/src/manifest/validate.ts

@@ -3,7 +3,7 @@ import { parse as parseYaml } from 'yaml';
 import type { ZodError } from 'zod';
 import { validateModuleZoneRequirements } from '../services/zone-policy';
 import { resolveContract, supportedContractVersions } from './contracts';
-import { ModuleManifestSchema } from './schema';
+import { ModuleManifestSchema, getSingularSystemSpec } from './schema';
 import type { ModuleManifest } from './schema';
 
 /**
@@ -304,16 +304,16 @@ export function validateVariableSources(manifest: ModuleManifest): ValidationErr
 export function validateZoneRequirements(manifest: ModuleManifest): ValidationError | null {
   const errors: Array<{ path: string; message: string }> = [];
 
-  // Check if module has infrastructure spec (requires.machine)
-  const hasInfrastructureSpec = manifest.requires?.machine;
+  // Check if module has infrastructure spec (requires.system)
+  const hasInfrastructureSpec = getSingularSystemSpec(manifest);
 
   // If module requires infrastructure, zone field is mandatory
   if (hasInfrastructureSpec) {
-    const zone = manifest.requires?.machine?.zone;
+    const zone = hasInfrastructureSpec.zone;
 
     if (!zone) {
       errors.push({
-        path: 'requires.machine.zone',
+        path: 'requires.system.zone',
         message: 'Zone field is required for modules with infrastructure requirements',
       });
       // Can't validate zone requirements without a zone
@@ -327,7 +327,7 @@ export function validateZoneRequirements(manifest: ModuleManifest): ValidationEr
 
       if (!zoneValidation.valid && zoneValidation.error) {
         errors.push({
-          path: 'requires.machine.zone',
+          path: 'requires.system.zone',
           message: zoneValidation.error,
         });
       }

package/src/module/import.ts

@@ -10,7 +10,7 @@ import { getModuleStoragePath } from '../config/paths';
 import { type DbClient, getDb } from '../db/client';
 import { capabilities, moduleIntegrity, modules } from '../db/schema';
 import type { NewModule, NewModuleIntegrity } from '../db/schema';
-import type { ModuleManifest } from '../manifest/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import {
   validateCapabilityNames,
   validateDeriveFromSources,
@@ -348,7 +348,7 @@ export async function validateWellKnownCapabilities(
     }
 
     // Check 2: Zone enforcement - module must be in the correct zone
-    const moduleZone = manifest.requires?.machine?.zone;
+    const moduleZone = getSingularSystemSpec(manifest)?.zone;
 
     if (wellKnown.zone_enforced && moduleZone) {
       if (moduleZone !== wellKnown.required_zone) {

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

@@ -217,7 +217,13 @@ describe('celilo lifecycle events', () => {
     it('returns immediately when the deploy changed no routes', async () => {
       const since = routesChangedHighWater();
       const result = await waitForRouteReconcile(since, { timeoutMs: 1000 });
-      expect(result).toEqual({ events: 0, succeeded: 0, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 0,
+        succeeded: 0,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: false,
+      });
     });
 
     it('skips the wait (no time-out) when no dispatcher is running', async () => {
@@ -226,7 +232,13 @@ describe('celilo lifecycle events', () => {
       emitWebRoutesChanged('celilo-website');
       // No heartbeat stamped → health() is no_dispatcher.
       const result = await waitForRouteReconcile(since, { timeoutMs: 5000, pollMs: 50 });
-      expect(result).toEqual({ events: 1, succeeded: 0, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 1,
+        succeeded: 0,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: true,
+      });
     });
 
     it('settles immediately when no provider subscribes (zero deliveries)', async () => {
@@ -234,7 +246,13 @@ describe('celilo lifecycle events', () => {
       const since = routesChangedHighWater();
       emitWebRoutesChanged('celilo-website');
       const result = await waitForRouteReconcile(since, { timeoutMs: 1000, pollMs: 50 });
-      expect(result).toEqual({ events: 1, succeeded: 0, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 1,
+        succeeded: 0,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: false,
+      });
     });
 
     it('times out while the provider delivery is still pending', async () => {
@@ -255,7 +273,13 @@ describe('celilo lifecycle events', () => {
       settleDelivery('succeed');
 
       const result = await waitForRouteReconcile(since, { timeoutMs: 1000, pollMs: 50 });
-      expect(result).toEqual({ events: 1, succeeded: 1, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 1,
+        succeeded: 1,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: false,
+      });
     });
 
     it('reports a failed delivery without timing out', async () => {
@@ -284,7 +308,13 @@ describe('celilo lifecycle events', () => {
       settleDelivery('succeed');
 
       const result = await pending;
-      expect(result).toEqual({ events: 1, succeeded: 1, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 1,
+        succeeded: 1,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: false,
+      });
     });
   });
 });

package/src/services/celilo-events.ts

@@ -222,6 +222,13 @@ export interface RouteReconcileWaitResult {
   succeeded: number;
   failed: number;
   timedOut: boolean;
+  /**
+   * True when no event dispatcher was running, so the `routes_changed` event
+   * was persisted but never DELIVERED to the provider (caddy). The route is
+   * therefore NOT live. Authoritative callers (ISS-0081) must treat this as a
+   * failure, not a benign "0 deliveries" success.
+   */
+  noDispatcher: boolean;
 }
 
 /**
@@ -283,14 +290,20 @@ export async function waitForRouteReconcile(
       .filter((e) => e.id > sinceEventId);
 
     if (events.length === 0) {
-      return { events: 0, succeeded: 0, failed: 0, timedOut: false };
+      return { events: 0, succeeded: 0, failed: 0, timedOut: false, noDispatcher: false };
     }
 
     if (b.health().status === 'no_dispatcher') {
       console.warn(
         `[celilo] route-reconcile: no dispatcher running — 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 };
+      return {
+        events: events.length,
+        succeeded: 0,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: true,
+      };
     }
 
     while (true) {
@@ -306,6 +319,7 @@ export async function waitForRouteReconcile(
           succeeded: settled('succeeded'),
           failed: settled('failed') + settled('abandoned'),
           timedOut: pending > 0,
+          noDispatcher: false,
         };
       }
 
@@ -314,7 +328,7 @@ 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 };
+    return { events: 0, succeeded: 0, failed: 0, timedOut: false, noDispatcher: false };
   } finally {
     bus?.close();
   }