@celilo/cli 3.1.0 → 4.1.0

package/src/services/provider-arrival.test.ts

@@ -21,6 +21,9 @@ function manifest(input: { requires?: string[]; optional?: string[] }): ModuleMa
   } as unknown as ModuleManifest;
 }
 
+/** What the arriving provider registered. Consumers in these tests declare 1.0.0. */
+const provides = (...names: string[]) => names.map((name) => ({ name, version: '1.0.0' }));
+
 const consumer = (
   moduleId: string,
   caps: { requires?: string[]; optional?: string[] },
@@ -29,14 +32,10 @@ const consumer = (
 
 describe('planProviderBackfill', () => {
   it('re-runs consumers of the capabilities the arriving provider actually provides', () => {
-    const plan = planProviderBackfill(
-      'iptables',
-      ['firewall'],
-      [
-        consumer('caddy', { requires: ['firewall'] }),
-        consumer('forgejo', { requires: ['public_web'] }),
-      ],
-    );
+    const plan = planProviderBackfill('iptables', provides('firewall'), [
+      consumer('caddy', { requires: ['firewall'] }),
+      consumer('forgejo', { requires: ['public_web'] }),
+    ]);
 
     expect(plan.map((t) => t.consumerId)).toEqual(['caddy']);
   });
@@ -48,11 +47,9 @@ describe('planProviderBackfill', () => {
    * provider appears. Counting only `requires` would leave it unregistered.
    */
   it('includes an OPTIONAL dependent, not only a required one', () => {
-    const plan = planProviderBackfill(
-      'technitium',
-      ['dns_internal'],
-      [consumer('caddy-internal', { optional: ['dns_internal'] })],
-    );
+    const plan = planProviderBackfill('technitium', provides('dns_internal'), [
+      consumer('caddy-internal', { optional: ['dns_internal'] }),
+    ]);
 
     expect(plan.map((t) => t.consumerId)).toEqual(['caddy-internal']);
     expect(plan[0]?.skip).toBeUndefined();
@@ -61,14 +58,10 @@ describe('planProviderBackfill', () => {
   it('never treats the provider as its own consumer', () => {
     // A module that both provides and requires a capability would otherwise
     // have its on_install run a second time inside the deploy that just ran it.
-    const plan = planProviderBackfill(
-      'caddy',
-      ['public_web'],
-      [
-        consumer('caddy', { requires: ['public_web', 'firewall'] }),
-        consumer('forgejo', { requires: ['public_web'] }),
-      ],
-    );
+    const plan = planProviderBackfill('caddy', provides('public_web'), [
+      consumer('caddy', { requires: ['public_web', 'firewall'] }),
+      consumer('forgejo', { requires: ['public_web'] }),
+    ]);
 
     expect(plan.map((t) => t.consumerId)).toEqual(['forgejo']);
   });
@@ -76,52 +69,75 @@ describe('planProviderBackfill', () => {
   it('skips a consumer in a pre-deploy state, and says so rather than dropping it', () => {
     // Capabilities are registered at IMPORT, not deploy, so an imported module
     // has never resolved anything and has nothing to re-register.
-    const plan = planProviderBackfill(
-      'iptables',
-      ['firewall'],
-      [
-        consumer('imported', { requires: ['firewall'] }, 'IMPORTED'),
-        consumer('validated', { requires: ['firewall'] }, 'VALIDATED'),
-        consumer('configured', { requires: ['firewall'] }, 'CONFIGURED'),
-      ],
-    );
+    const plan = planProviderBackfill('iptables', provides('firewall'), [
+      consumer('imported', { requires: ['firewall'] }, 'IMPORTED'),
+      consumer('validated', { requires: ['firewall'] }, 'VALIDATED'),
+      consumer('configured', { requires: ['firewall'] }, 'CONFIGURED'),
+    ]);
 
     expect(plan.map((t) => t.skip)).toEqual(['not-deployed', 'not-deployed', 'not-deployed']);
   });
 
   it('skips a PAUSED consumer separately from a never-deployed one', () => {
-    const plan = planProviderBackfill(
-      'iptables',
-      ['firewall'],
-      [consumer('paused', { requires: ['firewall'] }, 'PAUSED')],
-    );
+    const plan = planProviderBackfill('iptables', provides('firewall'), [
+      consumer('paused', { requires: ['firewall'] }, 'PAUSED'),
+    ]);
 
     expect(plan[0]?.skip).toBe('paused');
   });
 
   it('names every capability the consumer takes from this provider, once', () => {
-    const plan = planProviderBackfill(
-      'greenwave',
-      ['firewall', 'dhcp_server'],
-      [consumer('caddy', { requires: ['firewall'], optional: ['dhcp_server'] })],
-    );
+    const plan = planProviderBackfill('greenwave', provides('firewall', 'dhcp_server'), [
+      consumer('caddy', { requires: ['firewall'], optional: ['dhcp_server'] }),
+    ]);
 
     expect(plan).toHaveLength(1);
     expect(plan[0]?.capabilityNames).toEqual(['dhcp_server', 'firewall']);
   });
 
+  /**
+   * celilo#1384. An OPTIONAL consumer built against external_web@1.0.0 was
+   * re-run against a provider serving 2.0.0; the hook failed inside
+   * `on_install`, which is only a warning, so nothing published and no surface
+   * said so. A consumer on another major is skipped and REPORTED instead.
+   */
+  it('skips a consumer whose declared version the arriving provider no longer serves', () => {
+    const plan = planProviderBackfill(
+      'generic-cpanel',
+      [{ name: 'external_web', version: '2.0.0' }],
+      [
+        consumer('tango-nexus', { optional: ['external_web'] }),
+        consumer('required-too', { requires: ['external_web'] }),
+      ],
+    );
+
+    expect(plan.map((t) => [t.consumerId, t.skip])).toEqual([
+      ['required-too', 'incompatible'],
+      ['tango-nexus', 'incompatible'],
+    ]);
+  });
+
+  it('re-runs a consumer the provider is merely NEWER in minor than', () => {
+    const plan = planProviderBackfill(
+      'generic-cpanel',
+      [{ name: 'external_web', version: '1.4.0' }],
+      [consumer('tango-nexus', { optional: ['external_web'] })],
+    );
+
+    expect(plan[0]?.skip).toBeUndefined();
+  });
+
   it('is empty for a module that provides nothing', () => {
     expect(
-      planProviderBackfill('forgejo', [], [consumer('caddy', { requires: ['firewall'] })]),
+      planProviderBackfill('forgejo', provides(), [consumer('caddy', { requires: ['firewall'] })]),
     ).toEqual([]);
   });
 
   it('is ordered by consumer id, so a failure is reproducible', () => {
-    const plan = planProviderBackfill(
-      'iptables',
-      ['firewall'],
-      [consumer('zulu', { requires: ['firewall'] }), consumer('alpha', { requires: ['firewall'] })],
-    );
+    const plan = planProviderBackfill('iptables', provides('firewall'), [
+      consumer('zulu', { requires: ['firewall'] }),
+      consumer('alpha', { requires: ['firewall'] }),
+    ]);
 
     expect(plan.map((t) => t.consumerId)).toEqual(['alpha', 'zulu']);
   });

package/src/services/provider-arrival.ts

@@ -27,6 +27,7 @@
  * happened".
  */
 
+import { compareConsumerToProvider } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { capabilities, modules } from '../db/schema';
@@ -36,7 +37,13 @@ import type { HookLogger } from '../hooks/types';
 import { type ModuleManifest, ModuleManifestSchema } from '../manifest/schema';
 import { PRE_DEPLOY_STATES } from './consumer-cleanup';
 
-export type BackfillSkipReason = 'paused' | 'not-deployed';
+export type BackfillSkipReason = 'paused' | 'not-deployed' | 'incompatible';
+
+/** A capability as the arriving provider registered it. */
+export interface ProvidedCapability {
+  name: string;
+  version: string;
+}
 
 export interface BackfillTarget {
   /** The consumer module to re-run. */
@@ -70,23 +77,42 @@ export interface ConsumerCandidate {
  */
 export function planProviderBackfill(
   provider: string,
-  providedCapabilities: Iterable<string>,
+  providedCapabilities: Iterable<ProvidedCapability>,
   candidates: ConsumerCandidate[],
 ): BackfillTarget[] {
-  const provided = new Set(providedCapabilities);
+  const provided = new Map([...providedCapabilities].map((c) => [c.name, c.version]));
   if (provided.size === 0) return [];
 
   const targets: BackfillTarget[] = [];
   for (const candidate of candidates) {
     if (candidate.moduleId === provider) continue;
 
-    const consumed = new Set([
-      ...(candidate.manifest.requires?.capabilities ?? []).map((c) => c.name),
-      ...(candidate.manifest.optional?.capabilities ?? []).map((c) => c.name),
-    ]);
-    const capabilityNames = [...consumed].filter((name) => provided.has(name)).sort();
+    const consumed = new Map<string, string>();
+    for (const c of [
+      ...(candidate.manifest.optional?.capabilities ?? []),
+      ...(candidate.manifest.requires?.capabilities ?? []),
+    ]) {
+      consumed.set(c.name, c.version);
+    }
+    const capabilityNames = [...consumed.keys()].filter((name) => provided.has(name)).sort();
     if (capabilityNames.length === 0) continue;
 
+    // The consumer was built against a contract the arriving provider no
+    // longer speaks. Re-running its `on_install` would call methods that are
+    // gone (celilo#1384: tango-nexus 0.8.0's optional external_web@1.0.0 was
+    // re-run against generic-cpanel's 2.0.0 and failed inside the hook, which
+    // is only a warning — so nothing published and nothing said so).
+    if (
+      capabilityNames.some(
+        (name) =>
+          // biome-ignore lint/style/noNonNullAssertion: name came from `consumed`/`provided`.
+          !compareConsumerToProvider(consumed.get(name)!, provided.get(name)!).compatible,
+      )
+    ) {
+      targets.push({ consumerId: candidate.moduleId, capabilityNames, skip: 'incompatible' });
+      continue;
+    }
+
     if (candidate.state === 'PAUSED') {
       targets.push({ consumerId: candidate.moduleId, capabilityNames, skip: 'paused' });
       continue;
@@ -111,11 +137,11 @@ export function planProviderBackfill(
  */
 export function loadProviderBackfillPlan(provider: string, db: DbClient): BackfillTarget[] {
   const provided = db
-    .select({ capabilityName: capabilities.capabilityName })
+    .select({ capabilityName: capabilities.capabilityName, version: capabilities.version })
     .from(capabilities)
     .where(eq(capabilities.moduleId, provider))
     .all()
-    .map((row) => row.capabilityName);
+    .map((row) => ({ name: row.capabilityName, version: row.version }));
   if (provided.length === 0) return [];
 
   const candidates: ConsumerCandidate[] = [];
@@ -174,6 +200,11 @@ export async function runProviderBackfill(
           `${target.consumerId} is paused, so it was not re-run against the new '${provider}' — it consumes ${target.capabilityNames.join(', ')} and will rebind on its next deploy.`,
         );
       }
+      if (target.skip === 'incompatible') {
+        logger.warn(
+          `${target.consumerId} was NOT re-run against the new '${provider}': it declares ${target.capabilityNames.join(', ')} on a version '${provider}' no longer serves. Rebuild ${target.consumerId} against the provider's current major, then redeploy it.`,
+        );
+      }
       continue;
     }
 

package/src/services/provider-converge.test.ts

@@ -138,6 +138,22 @@ describe('recordUnresolvedConsumers — the failure belongs to the consumer', ()
     return db.select().from(modules).where(eq(modules.id, id)).get();
   }
 
+  it('leaves a PAUSED consumer paused — a provider cannot render it by design', () => {
+    db.update(modules).set({ state: 'PAUSED' }).where(eq(modules.id, 'byoi')).run();
+
+    const recorded = recordUnresolvedConsumers(db, 'caddy', [
+      { moduleId: 'byoi', reason: "module 'byoi' is paused — its site is left as it is" },
+    ]);
+
+    // Pause preserves state, and that includes the module's own recorded
+    // state. A paused module is unresolvable on EVERY converge, so marking it
+    // ERROR here would mean an operator could not pause a module without the
+    // next publish reporting it failed.
+    expect(recorded).toEqual([]);
+    expect(stateOf('byoi')?.state).toBe('PAUSED');
+    expect(stateOf('byoi')?.errorMessage ?? null).toBeNull();
+  });
+
   it('records the consumer in ERROR with the reason it could not be rendered', () => {
     recordUnresolvedConsumers(db, 'caddy', [
       { moduleId: 'byoi', reason: 'no built site at /var/celilo/modules/byoi/site/dist' },

package/src/services/provider-converge.ts

@@ -15,14 +15,22 @@
  * against that consumer.
  */
 
-import { existsSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { eq } from 'drizzle-orm';
+import { and, eq } from 'drizzle-orm';
 import { stringify as stringifyYaml } from 'yaml';
 import type { DbClient } from '../db/client';
-import { modules } from '../db/schema';
-import { ansibleTreeMentions } from './static-content-converge';
+import { moduleConfigs, modules } from '../db/schema';
+import { parseStoredConfigValue } from './module-config';
+
+/**
+ * Retention when the operator has not set one. Mirrors the manifest default
+ * declared on the provider module (`static_release_retention`); the manifest
+ * is the operator-facing source of truth, this only covers a provider whose
+ * manifest predates the variable.
+ */
+const DEFAULT_STATIC_RELEASE_RETENTION = 5;
 
 /** One file the provider wants on its host, rendered by the provider. */
 export interface ProviderConfigFile {
@@ -121,6 +129,14 @@ export function recordUnresolvedConsumers(
     const existing = db.select().from(modules).where(eq(modules.id, consumer.moduleId)).get();
     if (!existing) continue;
 
+    // A PAUSED module is not broken, and pause preserves state — including the
+    // module's own recorded state. A provider legitimately cannot render a
+    // paused consumer (its site is deliberately left alone), so this path is
+    // reached on every converge while any module is paused; writing ERROR
+    // there would mean an operator could not pause a module without the next
+    // publish marking it failed.
+    if (existing.state === 'PAUSED') continue;
+
     db.update(modules)
       .set({
         state: 'ERROR',
@@ -239,3 +255,89 @@ export async function convergeProviderConfig(
   rmSync(generatedPath, { recursive: true, force: true });
   return { success: true, varsPath, unresolved };
 }
+
+/**
+ * Resolve the retention count for the provider module.
+ *
+ * Operator config first (`static_release_retention` module config), then the
+ * manifest's declared default, then the constant above. ONE resolution — the
+ * role reads the variable bare and never carries a literal.
+ */
+export function resolveStaticContentRetention(db: DbClient, providerModuleId: string): number {
+  const configRow = db
+    .select()
+    .from(moduleConfigs)
+    .where(
+      and(
+        eq(moduleConfigs.moduleId, providerModuleId),
+        eq(moduleConfigs.key, 'static_release_retention'),
+      ),
+    )
+    .get();
+  if (configRow) {
+    const parsed = parseStoredConfigValue(configRow);
+    const count = typeof parsed === 'number' ? parsed : Number.parseInt(String(parsed), 10);
+    if (Number.isInteger(count) && count >= 1) return count;
+    throw new Error(
+      `static_release_retention for ${providerModuleId} must be a positive integer, got: ${String(parsed)}`,
+    );
+  }
+
+  const module = db.select().from(modules).where(eq(modules.id, providerModuleId)).get();
+  if (module) {
+    const manifest = module.manifestData as {
+      variables?: { owns?: Array<{ name?: string; default?: unknown }> };
+    } | null;
+    const declared = manifest?.variables?.owns?.find((v) => v?.name === 'static_release_retention');
+    const fallback = typeof declared?.default === 'number' ? declared.default : undefined;
+    if (typeof fallback === 'number' && Number.isInteger(fallback) && fallback >= 1)
+      return fallback;
+  }
+
+  return DEFAULT_STATIC_RELEASE_RETENTION;
+}
+
+/**
+ * Build the release set from the declared `web_routes` rows.
+ *
+ * Pure: reads the DB, decides nothing on the host (Rule 10.4). Grouping is by
+ * slug, NOT by route — one slug is one release directory, and a slug can span
+ * hostnames (lunacycle's two routes, both at `/`). A group that spans modules
+ * or disagrees with itself about the hash is a contradiction the converge
+ * cannot express, so it fails here with both rows named rather than silently
+ * converging one of them.
+ */
+
+/**
+ * Whether any text file in a generated Ansible tree mentions `needle`.
+ *
+ * Scans the TREE rather than `playbook.yml`, because a provider's converge
+ * belongs in one of its role's task files and a generated `playbook.yml` is a
+ * thin hosts/vars/roles stanza that names no variable at all. caddy is the
+ * worked example: `static_releases` appears in
+ * `roles/caddy/tasks/static-content.yml`, `.../main.yml.tpl` and
+ * `.../converge-release.yml`, and zero times in its playbook.
+ *
+ * @psbanka - 2026-09: this used to read `ansible/playbook.yml` alone, which
+ * could not reach the string it was looking for. The guard below therefore
+ * refused EVERY provider that had the converge support, and its remedy told the
+ * operator to redeploy — which regenerates the same thin playbook and cannot
+ * help. Guard and role tasks landed in the same commit (1fd3595e), so it had
+ * never once passed, and it held three e2e suites red where nobody was looking.
+ * celilo#1248.
+ */
+export function ansibleTreeMentions(dir: string, needle: string): boolean {
+  if (!existsSync(dir)) return false;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (ansibleTreeMentions(full, needle)) return true;
+      continue;
+    }
+    // Text only. A generated tree can carry static assets, and reading those
+    // as utf-8 to look for a variable name is waste at best.
+    if (!/\.(ya?ml|j2|tpl|cfg|ini|conf)$/.test(entry.name)) continue;
+    if (readFileSync(full, 'utf-8').includes(needle)) return true;
+  }
+  return false;
+}

package/src/services/system-reboot.test.ts

@@ -0,0 +1,231 @@
+/**
+ * The recurrence gate celilo#1378 asks for: drive the reboot against a FAKE
+ * host, with an operation in flight (it must refuse and name it) and with
+ * nothing in flight (it must reboot, and the return must be verified rather
+ * than assumed).
+ *
+ * Every dependency is injected, so nothing here reboots anything.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import type { InFlightConflict } from './module-operations';
+import {
+  type RebootMarker,
+  collectRebootPendingFacts,
+  judgeRebootPending,
+  requestReboot,
+  verifyReturn,
+} from './system-reboot';
+
+const BOOT_A = '11111111-1111-1111-1111-111111111111';
+const BOOT_B = '22222222-2222-2222-2222-222222222222';
+
+function conflict(describe: string): InFlightConflict {
+  return { operation: {} as InFlightConflict['operation'], describe };
+}
+
+/** A fake host: records what was asked of it, answers what it was told to. */
+function fakeHost(opts: { conflicts?: string[]; bootId?: string | null } = {}) {
+  const state = { rebooted: 0, marker: null as RebootMarker | null };
+  return {
+    state,
+    deps: {
+      conflicts: () => (opts.conflicts ?? []).map(conflict),
+      bootId: () => (opts.bootId === undefined ? BOOT_A : opts.bootId),
+      issueReboot: () => {
+        state.rebooted += 1;
+        return { status: 0 };
+      },
+      writeMarker: (m: RebootMarker) => {
+        state.marker = m;
+      },
+      now: () => 1_700_000_000_000,
+    },
+  };
+}
+
+describe('requestReboot — refuses while the fleet is busy', () => {
+  it('refuses with an operation in flight, and names which one', () => {
+    const host = fakeHost({ conflicts: ['deploy of homebridge (pid 12345)'] });
+
+    const result = requestReboot(host.deps, 'pending kernel');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('deploy of homebridge (pid 12345)');
+    // The whole point: naming it is not enough if it rebooted anyway.
+    expect(host.state.rebooted).toBe(0);
+    expect(host.state.marker).toBe(null);
+  });
+
+  it('refuses when the boot id cannot be read, because the return could never be verified', () => {
+    const host = fakeHost({ bootId: null });
+
+    const result = requestReboot(host.deps);
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('could not be verified');
+    expect(host.state.rebooted).toBe(0);
+  });
+
+  it('reboots with nothing in flight, recording the boot id the return is checked against', () => {
+    const host = fakeHost();
+
+    const result = requestReboot(host.deps, 'pending kernel 6.8.0-1064-raspi');
+
+    expect(result.success).toBe(true);
+    expect(host.state.rebooted).toBe(1);
+    expect(host.state.marker?.bootIdBefore).toBe(BOOT_A);
+    expect(host.state.marker?.reason).toContain('6.8.0-1064-raspi');
+    // It reports the reboot as ISSUED, never as completed — the process
+    // asking for it dies in it (celilo#1378).
+    expect(result.message).toContain('--verify');
+  });
+
+  it('leaves the marker in place when the reboot command itself fails', () => {
+    const host = fakeHost();
+    const result = requestReboot(
+      { ...host.deps, issueReboot: () => ({ status: 1 }) },
+      'pending kernel',
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('was not rebooted');
+  });
+});
+
+describe('verifyReturn — only the host actually coming back is success', () => {
+  const marker: RebootMarker = { bootIdBefore: BOOT_A, requestedAt: 1, reason: 'kernel' };
+  const cameBack = {
+    bootId: () => BOOT_B,
+    readMarker: () => marker,
+    heartbeatLive: async () => true,
+    cliVersion: () => '3.0.1',
+  };
+
+  it('reports success once the boot id changed, the dispatcher is live and the CLI answers', async () => {
+    let cleared = 0;
+    const result = await verifyReturn({
+      ...cameBack,
+      clearMarker: () => {
+        cleared += 1;
+      },
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('3.0.1');
+    expect(cleared).toBe(1);
+  });
+
+  it('fails when the boot id is unchanged — the host never went down', async () => {
+    const result = await verifyReturn({ ...cameBack, bootId: () => BOOT_A, clearMarker: () => {} });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('has NOT rebooted');
+  });
+
+  it('fails when the box booted but the dispatcher did not, and says so', async () => {
+    const result = await verifyReturn({
+      ...cameBack,
+      heartbeatLive: async () => false,
+      clearMarker: () => {},
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('dispatcher');
+    expect(result.error).toContain('unverified');
+  });
+
+  it('fails when the CLI does not answer', async () => {
+    const result = await verifyReturn({
+      ...cameBack,
+      cliVersion: () => null,
+      clearMarker: () => {},
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('--version');
+  });
+
+  it('keeps the marker when verification fails, so the audit still sees it', async () => {
+    let cleared = 0;
+    await verifyReturn({
+      ...cameBack,
+      heartbeatLive: async () => false,
+      clearMarker: () => {
+        cleared += 1;
+      },
+    });
+
+    expect(cleared).toBe(0);
+  });
+
+  it('says so plainly when no reboot was ever requested', async () => {
+    const result = await verifyReturn({ ...cameBack, readMarker: () => null });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('No reboot is pending');
+  });
+});
+
+describe('judgeRebootPending — two independent tells', () => {
+  const none = {
+    markerPresent: false,
+    deferredPackages: [],
+    runningKernel: '6.8.0-1064-raspi',
+    installedKernel: '6.8.0-1064-raspi',
+  };
+
+  it('is the #1378 case: a running kernel older than the installed one', () => {
+    const verdict = judgeRebootPending({ ...none, runningKernel: '6.8.0-1063-raspi' });
+
+    expect(verdict.pending).toBe(true);
+    expect(verdict.reasons[0]).toContain('6.8.0-1063-raspi');
+    expect(verdict.reasons[0]).toContain('6.8.0-1064-raspi');
+  });
+
+  it("reports Debian's own marker, naming the packages that deferred", () => {
+    const verdict = judgeRebootPending({
+      ...none,
+      markerPresent: true,
+      deferredPackages: ['docker.service', 'dbus.service'],
+    });
+
+    expect(verdict.pending).toBe(true);
+    expect(verdict.reasons.join(' ')).toContain('docker.service');
+  });
+
+  it('is clean when the kernel matches and nothing deferred', () => {
+    expect(judgeRebootPending(none)).toEqual({ pending: false, unmeasured: false, reasons: [] });
+  });
+
+  it('is UNMEASURED, not clean, when the host could not be asked', () => {
+    // An absent /var/run/reboot-required on a host that has no /var/run is not
+    // evidence of a healthy kernel. Reporting it clean is the #1326 shape.
+    const verdict = judgeRebootPending({
+      markerPresent: false,
+      deferredPackages: [],
+      runningKernel: null,
+      installedKernel: null,
+    });
+
+    expect(verdict).toEqual({ pending: false, unmeasured: true, reasons: [] });
+  });
+});
+
+describe('collectRebootPendingFacts', () => {
+  it('reads the marker and splits the deferred package list', () => {
+    const facts = collectRebootPendingFacts(
+      (path) => (path.endsWith('.pkgs') ? 'docker\n\ndbus\n' : ''),
+      '6.8.0-1063-raspi',
+      '6.8.0-1064-raspi',
+    );
+
+    expect(facts.markerPresent).toBe(true);
+    expect(facts.deferredPackages).toEqual(['docker', 'dbus']);
+    expect(facts.runningKernel).toBe('6.8.0-1063-raspi');
+  });
+
+  it('reports no marker when the file is absent', () => {
+    expect(collectRebootPendingFacts(() => null).markerPresent).toBe(false);
+  });
+});