@celilo/cli 0.26.1 → 1.0.0

package/src/hooks/capability-loader.ts

@@ -113,6 +113,16 @@ export const CAPABILITY_MODULE_MAP: Record<string, { script: string; legacyFacto
       script: 'scripts/control-plane-vpn-functions.ts',
       legacyFactoryName: 'default',
     },
+    // MODULE-provided, unlike its sibling public_web above, which the framework
+    // implements (createPublicWeb) against celilo's `web_routes` table. The
+    // asymmetry is deliberate: a private route stored in `web_routes` would be
+    // picked up by the PUBLIC caddy, which derives its served hostnames from
+    // every row of that table — so the provider keeps its own routes and celilo
+    // core holds no private-ingress business at all (celilo#846).
+    private_web: {
+      script: 'scripts/private-web-functions.ts',
+      legacyFactoryName: 'default',
+    },
   };
 
 /**
@@ -247,7 +257,7 @@ export async function loadCapabilityFunctions(
     // buildFirewallChain handles the per-layer wrap with auto-logging
     // internally, so we don't need to wrap the result here.
     if (capName === 'firewall' && allProviders.length > 1) {
-      const firewallInterface = await buildFirewallChain(
+      const { chain, self } = await buildFirewallChain(
         allProviders,
         moduleInfo,
         masterKey,
@@ -256,8 +266,15 @@ export async function loadCapabilityFunctions(
         debugLog,
         consumingModuleId,
       );
-      if (firewallInterface) {
-        result[capName] = firewallInterface;
+      if (chain) {
+        result[capName] = chain;
+      }
+      // The chain hands a CONSUMER the innermost layer, which is not this
+      // provider's own layer when it sits further out. `on_consumer_removed`
+      // must converge THIS firewall, so it gets its own layer by name.
+      if (self) {
+        result.firewall_registry = self;
+        debugLog(`firewall_registry: provider view injected for ${consumingModuleId}`);
       }
       continue;
     }
@@ -332,6 +349,11 @@ export async function loadCapabilityFunctions(
           secrets: providerSecrets,
           systems: getModuleSystems(capability.moduleId, db),
           logger,
+          // WHO IS CALLING, so a provider can scope per-consumer state to them.
+          // `createPublicWeb` has always had this; compiled factories did not,
+          // which made a module-provided capability structurally unable to
+          // offer `unregisterRoutes()`-style methods.
+          consumerModuleId: consumingModuleId,
         });
         // Stamp here too, not only on the legacy path: a consumer that cannot
         // get what it needs must be able to name WHICH provider could not give
@@ -354,7 +376,7 @@ export async function loadCapabilityFunctions(
         providerSecrets,
         // Single firewall provider (no upstream chain) still needs the injected
         // port-forward store — the chain path isn't taken when there's one provider.
-        capName === 'firewall' ? buildPortForwardStore(db) : undefined,
+        capName === 'firewall' ? buildPortForwardStore(db, consumingModuleId) : undefined,
         capName === 'firewall' ? loadFirewallZones(db) : undefined,
         // Bound to the CONSUMING module so a trusted-source registration is
         // attributable — reach into every tier must never be anonymous.
@@ -367,6 +389,12 @@ export async function loadCapabilityFunctions(
           wrapWithLogging(capabilityInterface as object, logger, capName),
         );
         debugLog(`${capName}: loaded via legacy factory`);
+        // Sole firewall provider running its OWN hook: the interface just built
+        // IS its layer, so hand it back under the provider-view name too.
+        if (capName === 'firewall' && consumingModuleId === capability.moduleId) {
+          result.firewall_registry = result[capName];
+          debugLog(`firewall_registry: provider view injected for ${consumingModuleId}`);
+        }
       }
     } catch (error) {
       debugLog(
@@ -972,6 +1000,20 @@ function parseInterfaceBaseline(raw: unknown): string[] | undefined {
   return names.length > 0 ? names : undefined;
 }
 
+/**
+ * What a firewall build hands back.
+ *
+ * `chain` is the layer a CONSUMER talks to (the innermost). `self` is the layer
+ * belonging to the module currently running a hook, and is null unless that
+ * module is itself one of the providers — it is what `on_consumer_removed`
+ * converges, and it differs from `chain` whenever the provider sits further out
+ * than the innermost layer.
+ */
+interface FirewallChain {
+  chain: unknown;
+  self: unknown | null;
+}
+
 async function buildFirewallChain(
   allProviders: Array<{
     id: number;
@@ -986,11 +1028,12 @@ async function buildFirewallChain(
   logger: HookLogger,
   debugLog: (msg: string) => void,
   consumingModuleId: string,
-): Promise<unknown> {
+): Promise<FirewallChain> {
   // The shared-core port-forward registry, injected into every firewall provider
   // in the chain so exposeService/converge reconcile against the one canonical
-  // store (openspec/changes/unified-management-no-ssh/proposal.md).
-  const store = buildPortForwardStore(db);
+  // store (openspec/changes/unified-management-no-ssh/proposal.md). Bound to the
+  // CONSUMING module so every forward it declares is attributable (D2).
+  const store = buildPortForwardStore(db, consumingModuleId);
   // Trusted-source registry, bound to the CONSUMING module so a registration is
   // attributable. Only the layers that render their own ruleset receive it.
   const trustedSourceStore = buildTrustedSourceStore(db, consumingModuleId);
@@ -1006,17 +1049,17 @@ async function buildFirewallChain(
 
   if (!hasExternal) {
     debugLog('firewall chain: no provider with external interface found');
-    return null;
+    return { chain: null, self: null };
   }
 
   // Build the leaf (external) firewall first
   const leafModule = db.select().from(modules).where(eq(modules.id, hasExternal.moduleId)).get();
-  if (!leafModule) return null;
+  if (!leafModule) return { chain: null, self: null };
 
   const leafModulePath = join(leafModule.sourcePath, moduleInfo.script);
   if (!existsSync(leafModulePath)) {
     debugLog(`firewall chain: leaf module not found at ${leafModulePath}`);
-    return null;
+    return { chain: null, self: null };
   }
 
   const leafConfig = await loadModuleConfig(hasExternal.moduleId, db);
@@ -1025,7 +1068,7 @@ async function buildFirewallChain(
   const leafExported =
     typeof leafMod.default === 'function' ? leafMod.default : leafMod[moduleInfo.legacyFactoryName];
 
-  if (typeof leafExported !== 'function') return null;
+  if (typeof leafExported !== 'function') return { chain: null, self: null };
 
   // Branded compiled factory (Phase 8 path): call with the canonical
   // context. wrapWithLogging is applied internally so the leaf interface
@@ -1037,6 +1080,7 @@ async function buildFirewallChain(
       secrets: leafSecrets,
       systems: getModuleSystems(hasExternal.moduleId, db),
       logger,
+      consumerModuleId: consumingModuleId,
     });
     leafFirewall = stampProvider(leafFirewall, hasExternal.moduleId);
     debugLog(
@@ -1065,8 +1109,15 @@ async function buildFirewallChain(
   // doesn't fit defineCapabilityFunction's single-context shape.
   const downstream = allProviders.filter((p) => p.moduleId !== hasExternal.moduleId);
 
+  // Each layer as its OWN provider sees it, so `on_consumer_removed` converges
+  // the firewall that declares the hook rather than whichever layer a consumer
+  // happens to talk to.
+  const selfLayer = (id: string, iface: unknown): unknown | null =>
+    id === consumingModuleId ? iface : null;
+  let self = selfLayer(hasExternal.moduleId, leafFirewall);
+
   if (downstream.length === 0) {
-    return leafFirewall;
+    return { chain: leafFirewall, self };
   }
 
   let currentUpstream = leafFirewall;
@@ -1141,9 +1192,10 @@ async function buildFirewallChain(
       wrapWithLogging(downstreamFirewall as object, logger, 'firewall'),
       provider.moduleId,
     );
+    self = self ?? selfLayer(provider.moduleId, currentUpstream);
   }
 
-  return currentUpstream;
+  return { chain: currentUpstream, self };
 }
 
 /**

package/src/hooks/define-hook.test.ts

@@ -46,6 +46,7 @@ function makeContext(overrides: Partial<HookContext> = {}): HookContext {
     secrets: {},
     systems: [],
     logger: makeLogger(),
+    consumerModuleId: 'test-consumer',
     debug: false,
     screenshotDir: '',
     capabilities: {},
@@ -69,9 +70,6 @@ const fakePublicWeb: PublicWebCapability = {
   async upload_static_assets() {
     return { success: true, filesUploaded: 0, contentHash: 'fake' };
   },
-  async unregister_routes() {
-    return undefined;
-  },
   async getServerIp() {
     return '10.0.10.10';
   },
@@ -297,9 +295,6 @@ describe('defineCapabilityFunction', () => {
         async upload_static_assets() {
           return { success: true, filesUploaded: 0, contentHash: 'x' };
         },
-        async unregister_routes() {
-          return undefined;
-        },
         async getServerIp() {
           return '10.0.10.10';
         },
@@ -350,6 +345,7 @@ describe('defineCapabilityFunction', () => {
       secrets: { token: 'abc' },
       systems: [],
       logger: makeLogger(),
+      consumerModuleId: 'test-consumer',
     });
 
     expect(typeof methods.create_oidc_client).toBe('function');
@@ -376,6 +372,7 @@ describe('defineCapabilityFunction', () => {
       secrets: {},
       systems: [],
       logger: makeLogger(),
+      consumerModuleId: 'test-consumer',
     });
 
     const result = await methods.registerHost({ fqdn: 'www.example.com' });
@@ -404,6 +401,7 @@ describe('defineCapabilityFunction', () => {
       secrets: {},
       systems: [],
       logger: makeLogger(),
+      consumerModuleId: 'test-consumer',
     });
 
     const result = await methods.exposeService({

package/src/hooks/executor.ts

@@ -28,6 +28,7 @@ import {
 } from '@celilo/capabilities';
 import {
   type ContractHookSignature,
+  contractHookSignature,
   resolveContract,
   supportedContractVersions,
 } from '../manifest/contracts';
@@ -435,7 +436,7 @@ export async function invokeHook(
     };
   }
 
-  const signature = contract.hooks[hookName];
+  const signature = contractHookSignature(contract.hooks, hookName);
   if (!signature) {
     return {
       success: false,

package/src/hooks/types.ts

@@ -104,25 +104,17 @@ export interface HookResult {
 }
 
 /**
- * Supported lifecycle hook names.
+ * Supported lifecycle hook names — re-exported from `@celilo/capabilities`,
+ * which owns the one list (celilo#821).
  *
- * Must stay in sync with the canonical hook list in
- * `apps/celilo/src/manifest/contracts/v1.ts` and with the schema's
- * `hooks` block in `apps/celilo/src/manifest/schema.ts`.
+ * This was a second hand-maintained copy, and it had already drifted: it was
+ * missing `reconcile_routes`, so caddy's public_web reconcile hook was a hook
+ * the celilo side of the codebase did not believe in.
  */
-export type HookName =
-  | 'container_created'
-  | 'on_install'
-  | 'on_uninstall'
-  | 'health_check'
-  | 'validate_config'
-  | 'on_backup'
-  | 'on_backup_analyze'
-  | 'on_restore'
-  | 'on_system_event'
-  | 'refresh_registrations'
-  | 'reassert_dhcp_dns'
-  | 'reconcile_clients';
+export type { HookName } from '@celilo/capabilities';
+export { HOOK_NAMES } from '@celilo/capabilities';
+
+import type { HookName } from '@celilo/capabilities';
 
 /**
  * Hook manifest section - maps hook names to definitions

package/src/infrastructure/property-extractor.test.ts

@@ -26,7 +26,6 @@ describe('extractMachineProperties', () => {
       zone: 'external',
       role: 'host',
       interfaces: [],
-      assignedModuleIds: [],
       createdAt: new Date(),
       updatedAt: new Date(),
     };
@@ -51,7 +50,6 @@ describe('extractMachineProperties', () => {
       zone: 'internal',
       role: 'host',
       interfaces: [],
-      assignedModuleIds: [],
       createdAt: new Date(),
       updatedAt: new Date(),
     };

package/src/manifest/contracts/index.ts

@@ -15,6 +15,26 @@ import type { ContractHookSignature, ContractHooks } from './v1';
 
 export type { ContractHooks, ContractHookSignature };
 
+/**
+ * Look up a hook signature by an UNTRUSTED name.
+ *
+ * `ContractHooks` is keyed by `HookName` (celilo#821), which is what makes a
+ * missing or unknown entry a compile error. The executor's `hookName` is a
+ * plain `string` on purpose — it comes from a module manifest, and deciding
+ * whether it names a real hook is precisely what the caller is asking. This
+ * helper is the one place that crossing is expressed, so every other use of
+ * `ContractHooks` stays exact.
+ *
+ * Returns `undefined` for a name the contract does not define; the caller
+ * turns that into "Hook 'x' is not part of celilo_contract 1.0".
+ */
+export function contractHookSignature(
+  hooks: ContractHooks,
+  name: string,
+): ContractHookSignature | undefined {
+  return (hooks as Record<string, ContractHookSignature | undefined>)[name];
+}
+
 /**
  * The shape of a registered contract.
  */

package/src/manifest/contracts/v1.ts

@@ -22,6 +22,8 @@
  * change and requires a v2.0 contract.
  */
 
+import type { HookName } from '@celilo/capabilities';
+
 /**
  * Per-input/output metadata.
  *
@@ -47,8 +49,21 @@ export interface ContractHookSignature {
  * Full contract for a version: a map of canonical hook name → signature.
  * Only hook names listed here are valid; declaring a hook not in this map is
  * a manifest validation error.
+ *
+ * Keyed by `HookName` rather than `string` (celilo#821). That single change is
+ * what turns this table from a fourth hand-maintained list into a derivation:
+ * a name added to `HOOK_NAMES` without an entry here is a type error, and an
+ * entry here for a name that is not a hook is one too. It was `Record<string,
+ * …>`, which is why the drift went unnoticed for months.
+ *
+ * `on_upstream_publish` is named explicitly because it is NOT a `HookName` — an
+ * array of build-bus match rules rather than an invokable hook. It has a
+ * signature here because the executor passes its payload as env vars and the
+ * contract is where that is written down.
  */
-export type ContractHooks = Record<string, ContractHookSignature>;
+export type ContractHooks = Record<HookName, ContractHookSignature> & {
+  on_upstream_publish: ContractHookSignature;
+};
 
 /**
  * Contract v1.0 — current canonical hook signatures.
@@ -70,6 +85,23 @@ export const V1_HOOKS: ContractHooks = {
     inputs: {},
     outputs: {},
   },
+  /**
+   * A module that CONSUMED one of this module's capabilities is being removed.
+   * The provider withdraws whatever it minted on that consumer's behalf
+   * (openspec/changes/consumer-removal-cleanup, D1).
+   *
+   * `consumer` is the only input and there are no outputs. Deliberately NOT
+   * accompanied by the list of capabilities the consumer used: a provider that
+   * cannot answer "what do I hold for this module" without being told has a
+   * different defect — the consumer's id was never recorded at the point of the
+   * call — and telling it at removal time only papers over that.
+   */
+  on_consumer_removed: {
+    inputs: {
+      consumer: { required: true },
+    },
+    outputs: {},
+  },
   health_check: {
     inputs: {},
     outputs: {},

package/src/manifest/schema.ts

@@ -1,3 +1,4 @@
+import type { HookName } from '@celilo/capabilities';
 import { z } from 'zod';
 import { NETWORK_ZONES } from '../db/schema';
 import {
@@ -332,6 +333,52 @@ export const UpstreamPublishHookSchema = z.object({
   timeout: z.number().positive().optional(),
 });
 
+/**
+ * The manifest schema for every invokable lifecycle hook, derived from the one
+ * list (celilo#821).
+ *
+ * `satisfies Record<HookName, …>` is doing the enforcement, in both directions:
+ * a name in `HOOK_NAMES` with no entry here is a type error, and an entry here
+ * that is not a `HookName` is a type error too. That is why this is a literal
+ * rather than something built with `Object.fromEntries` — a computed object
+ * would widen the keys to `string` and take `ModuleManifest['hooks']` down with
+ * it, trading one silent drift for another.
+ *
+ * Per-hook prose lives in `contracts/v1.ts`, which documents the same names.
+ * Two copies of that commentary is how they came to disagree.
+ */
+const LIFECYCLE_HOOK_SCHEMAS = {
+  container_created: LifecycleHookSchema.optional(),
+  on_install: LifecycleHookSchema.optional(),
+  on_uninstall: LifecycleHookSchema.optional(),
+  on_consumer_removed: LifecycleHookSchema.optional(),
+  health_check: HealthCheckHookSchema.optional().describe(
+    "Health check hook. `interval` is the module's SUGGESTED monitoring cadence; the operator's monitor row is the effective schedule and always wins.",
+  ),
+  validate_config: LifecycleHookSchema.optional(),
+  on_backup: LifecycleHookSchema.optional(),
+  on_backup_analyze: LifecycleHookSchema.optional(),
+  on_restore: LifecycleHookSchema.optional(),
+  on_system_event: LifecycleHookSchema.optional(),
+  reconcile_routes: LifecycleHookSchema.optional(),
+  refresh_registrations: LifecycleHookSchema.optional(),
+  reassert_dhcp_dns: LifecycleHookSchema.optional(),
+  reconcile_clients: LifecycleHookSchema.optional(),
+} satisfies Record<HookName, z.ZodTypeAny>;
+
+/**
+ * What `manifest.hooks` accepts: every lifecycle hook, plus
+ * `on_upstream_publish`, which is deliberately not a `HookName` — an ARRAY of
+ * build-bus match rules dispatched by the receiver daemon rather than a hook
+ * `runNamedHook` can invoke. It is spread in here rather than living in
+ * `LIFECYCLE_HOOK_SCHEMAS` so the `satisfies` above stays exact.
+ * See [[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4.
+ */
+const HOOK_SCHEMAS = {
+  ...LIFECYCLE_HOOK_SCHEMAS,
+  on_upstream_publish: z.array(UpstreamPublishHookSchema).optional(),
+};
+
 /**
  * Machine resource recommendations
  * Module declares recommended machine resources (CPU, memory, disk, storage)
@@ -626,64 +673,7 @@ export const ModuleManifestSchema = z
       })
       .optional(),
 
-    hooks: z
-      .object({
-        container_created: LifecycleHookSchema.optional(),
-        on_install: LifecycleHookSchema.optional(),
-        on_uninstall: LifecycleHookSchema.optional(),
-        health_check: HealthCheckHookSchema.optional().describe(
-          "Health check hook. `interval` is the module's SUGGESTED monitoring cadence; the operator's monitor row is the effective schedule and always wins.",
-        ),
-        validate_config: LifecycleHookSchema.optional(),
-        on_backup: LifecycleHookSchema.optional(),
-        on_backup_analyze: LifecycleHookSchema.optional(),
-        on_restore: LifecycleHookSchema.optional(),
-        /**
-         * Per-system lifecycle hook. A dns_internal provider declares this
-         * to (de)register a single host's A records when celilo's bridge
-         * delivers a system.created/destroyed event. Inputs (hostname,
-         * target_ip, op) come from the contract — see contracts/v1.ts and
-         * [[openspec/specs/internal-dns-split-horizon/spec.md]] D5.
-         */
-        on_system_event: LifecycleHookSchema.optional(),
-        /**
-         * Reconcile the provider's running config from a celilo registry on a
-         * change event. The caddy `public_web` provider declares this to
-         * re-render its Caddyfile from web_routes when a consumer registers or
-         * unregisters a route (ISS-0035). See
-         * [[openspec/specs/public-web-provider-reconcile/spec.md]].
-         */
-        reconcile_routes: LifecycleHookSchema.optional(),
-        /**
-         * Periodic re-assertion of a dns_registrar provider's registered
-         * records. The framework injects the provider's dns_registrations
-         * ledger rows as the `registrations` input; the hook re-sends each
-         * one to the underlying DNS API and fails loudly if any cannot be
-         * re-asserted. Providers subscribe it to a `timer.tick.*` event.
-         * Part of the dns_registrar capability contract — see
-         * designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B3).
-         */
-        refresh_registrations: LifecycleHookSchema.optional(),
-        /**
-         * Periodic re-assertion of the resolver a dns_internal provider
-         * hands out over DHCP. Some routers regenerate that value from
-         * their own upstream list on a timer, silently undoing what
-         * on_install set. The hook reads the device before writing, so a
-         * quiet minute costs one query. Subscribe it to `timer.tick.1m` —
-         * the tick interval IS the worst-case window in which a renewing
-         * client can be handed the wrong resolver. See celilo#739.
-         */
-        reassert_dhcp_dns: LifecycleHookSchema.optional(),
-        reconcile_clients: LifecycleHookSchema.optional(),
-        /**
-         * Build-bus upstream publish hooks. Array (a module can react
-         * to multiple upstream packages with different actions). See
-         * [[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4.
-         */
-        on_upstream_publish: z.array(UpstreamPublishHookSchema).optional(),
-      })
-      .strict()
-      .optional(),
+    hooks: z.object(HOOK_SCHEMAS).strict().optional(),
 
     build: z
       .object({

package/src/services/alerting/sweep-runner.test.ts

@@ -329,7 +329,11 @@ describe('runSweep', () => {
 
       expect(report.notified).toBe(0);
       expect(report.noPolicy).toEqual([]);
-      expect(report.skipped.within_grace).toBe(1);
+      // The alert is named, not just counted — an operator asking "why was I
+      // not paged" is asking about a specific alert (#450).
+      expect(report.skipped).toEqual([
+        { alertKey: 'module:homebridge/check:port', reason: 'within_grace' },
+      ]);
     });
 
     test('a transport that cannot be loaded records the error, not just a count', async () => {

package/src/services/alerting/sweep-runner.ts

@@ -78,14 +78,20 @@ export interface SweepReport {
    */
   noPolicy: { alertKey: string; monitor: string }[];
   /**
-   * Deliveries escalation declined, keyed by its reason (`within_grace`,
-   * `no_eligible_route`, …).
+   * Deliveries escalation declined — the reason AND the alert it applies to.
    *
-   * `notifyAlert` returns the reason precisely so the caller can record it — its
-   * own contract says a silent skip is indistinguishable from a bug. Dropping it
-   * here is what made a firing-but-undelivered alert undebuggable (#450).
+   * `notifyAlert` returns the reason precisely so the caller can record it: its
+   * own contract says a silent skip is indistinguishable from a bug, and
+   * dropping it here is what made a firing-but-undelivered alert undebuggable
+   * (#450).
+   *
+   * The alert key is carried too, because a bare `within_grace×2` still does not
+   * answer "why was I not paged" for the alert the operator is actually looking
+   * at — they cannot tell which of their live alerts each count refers to. Same
+   * reasoning `noPolicy` already applies, and the same failure it was fixing.
+   * Counts are derived at render time so there is one source for both.
    */
-  skipped: Record<string, number>;
+  skipped: { alertKey: string; reason: string }[];
   /**
    * Why each failed delivery failed, as `<alert key>: <error>`.
    *
@@ -121,7 +127,7 @@ export async function runSweep(
     deferredDelivered: 0,
     failed: 0,
     noPolicy: [],
-    skipped: {},
+    skipped: [],
     failures: [],
   };
 
@@ -282,7 +288,7 @@ export async function runSweep(
       report.failed++;
       report.failures.push(`${alert.key}: ${outcome.error}`);
     } else if (outcome.result === 'skipped') {
-      report.skipped[outcome.reason] = (report.skipped[outcome.reason] ?? 0) + 1;
+      report.skipped.push({ alertKey: alert.key, reason: outcome.reason });
     }
   }
 

package/src/services/aspect-runner.test.ts

@@ -54,7 +54,6 @@ async function seedMachine(opts: {
     sshUser: 'root',
     sshKey: 'ssh-key-placeholder',
     hardware: { cpu_cores: 1, memory_mb: 512, disk_gb: 5, arch: 'amd64' },
-    assignedModuleIds: [],
     earmarkedModule: null,
   });
   if (opts.apiOnly) {

package/src/services/audit/undeployed-modules.ts

@@ -19,6 +19,17 @@ export interface UndeployedModule {
   id: string;
   /** Lifecycle state from the modules table (IMPORTED, VALIDATED, …). */
   state: string;
+  /**
+   * Why it is in ERROR, verbatim from the modules table.
+   *
+   * Surfaced because the headline used to be the hardcoded "previous deploy
+   * failed", and that became a FALSE statement once a provider could be marked
+   * ERROR for failing to withdraw a removed consumer's state
+   * (openspec/changes/consumer-removal-cleanup, D6) — no deploy was involved,
+   * and the operator reading the finding has no other way to learn which
+   * consumer it was.
+   */
+  errorMessage?: string | null;
 }
 
 export interface UndeployedModulesAuditDeps {
@@ -40,11 +51,17 @@ export async function auditUndeployedModules(
     if (TRANSIENT_STATES.has(m.state)) continue;
 
     if (m.state === 'ERROR') {
+      const reason = m.errorMessage?.trim();
       findings.push({
         category: 'undeployed_modules',
         severity: 'blocked',
         code: 'module_in_error_state',
-        message: `${m.id}: previous deploy failed (state: ERROR)`,
+        // The recorded reason when there is one. A module reaches ERROR from
+        // more than one place now, and naming the wrong cause sends the
+        // operator to the wrong evidence.
+        message: reason
+          ? `${m.id}: ${reason} (state: ERROR)`
+          : `${m.id}: previous deploy failed (state: ERROR)`,
         details:
           'Investigate the prior failure (check `celilo module status` and the' +
           ' module logs) before retrying — re-deploying without diagnosing the' +