@celilo/cli 1.1.0 → 1.3.0

package/src/services/aspect-runner.ts

@@ -47,7 +47,7 @@ import {
   EVENT_TYPES,
   busInterviewGuarded,
 } from './bus-interview';
-import { executeAnsible } from './deploy-ansible';
+import { type AnsibleHostRecap, executeAnsible, parseAnsibleRecap } from './deploy-ansible';
 import { getContainerSystemsInZones } from './deployed-systems';
 import { getSystemsByZone } from './machine-pool';
 import { executeProxmoxReconcile, planProxmoxReconcile } from './proxmox-reconcile';
@@ -89,6 +89,12 @@ export interface AspectRunResult {
   error?: string;
   /** The plan that was executed, for caller logging / event emission. */
   plan: AspectFanOutPlan;
+  /**
+   * Per-host `PLAY RECAP` counters. Empty when Ansible produced no recap — a
+   * state callers must NOT read as success. `verifyAspectCoverage` classifies
+   * from this.
+   */
+  recap: AnsibleHostRecap[];
 }
 
 export interface AspectRunOptions {
@@ -101,6 +107,21 @@ export interface AspectRunOptions {
    * they want it, the framework doesn't force a skip).
    */
   excludeHostnames?: string[];
+  /**
+   * Restrict the fan-out to exactly these hostnames, intersected with the
+   * zone-derived target set. Used by the inbound reconcile
+   * (`reconcileAspectsForSystems`), which applies an aspect to the systems a
+   * deploy just created rather than to the whole fleet. Narrows only — a
+   * hostname the aspect's zones do not cover is still not a target.
+   */
+  onlyHostnames?: string[];
+  /**
+   * Run Ansible in CHECK mode: evaluate the role against each target without
+   * changing anything. Used by `verifyAspectCoverage` to ask the HOST whether
+   * an aspect is applied, rather than consulting a stored claim that it once
+   * ran (celilo#902 design D6).
+   */
+  check?: boolean;
   /**
    * Override for noInteractive mode passed to executeAnsible.
    * Defaults to `true` because aspect fan-outs run as part of
@@ -117,8 +138,12 @@ export interface AspectRunOptions {
  */
 export async function planAspectFanOut(
   aspect: BaseModuleAspect,
-  options: Pick<AspectRunOptions, 'excludeHostnames'> = {},
+  options: Pick<AspectRunOptions, 'excludeHostnames' | 'onlyHostnames'> = {},
 ): Promise<AspectFanOutPlan> {
+  // `onlyHostnames` narrows, never widens: it is intersected with the
+  // zone-derived set below rather than replacing it, so an inbound reconcile
+  // cannot apply an aspect to a system outside its `applicable_zones`.
+  const only = options.onlyHostnames ? new Set(options.onlyHostnames) : undefined;
   // Machine-pool systems in the zones (api_only recorded as skips for
   // observability). excludeHostnames is applied by getSystemsByZone.
   const allInZones = await getSystemsByZone(aspect.applicable_zones, {
@@ -134,6 +159,7 @@ export async function planAspectFanOut(
       skipped.push({ machine: m, reason: 'api_only' });
       continue;
     }
+    if (only && !only.has(m.hostname)) continue;
     targetSystems.push({
       hostname: m.hostname,
       ipAddress: m.ipAddress,
@@ -151,6 +177,7 @@ export async function planAspectFanOut(
   const exclude = new Set(options.excludeHostnames ?? []);
   for (const sys of getContainerSystemsInZones(aspect.applicable_zones, getDb())) {
     if (exclude.has(sys.hostname) || seen.has(sys.hostname)) continue;
+    if (only && !only.has(sys.hostname)) continue;
     targetSystems.push({
       hostname: sys.hostname,
       ipAddress: sys.ipv4_address,
@@ -326,13 +353,14 @@ export async function runAspectFanOut(args: {
 
   const plan = await planAspectFanOut(aspect, {
     excludeHostnames: options.excludeHostnames,
+    onlyHostnames: options.onlyHostnames,
   });
 
   if (plan.targetSystems.length === 0) {
     log.info(
       `Aspect fan-out for '${moduleId}' (${options.trigger}): no eligible systems in zones [${aspect.applicable_zones.join(', ')}]`,
     );
-    return { success: true, output: '', plan };
+    return { success: true, output: '', plan, recap: [] };
   }
 
   log.info(
@@ -351,6 +379,7 @@ export async function runAspectFanOut(args: {
 
     const result = await executeAnsible(workDir, {
       noInteractive: options.noInteractive ?? true,
+      check: options.check,
     });
 
     // Proxmox reconciliation (D5): if the aspect declares
@@ -386,6 +415,7 @@ export async function runAspectFanOut(args: {
       output: result.output,
       error: result.error,
       plan,
+      recap: parseAnsibleRecap(result.output),
     };
   } finally {
     if (workDir) {
@@ -458,6 +488,61 @@ export interface AspectGlueResult {
   runResult?: AspectRunResult;
 }
 
+/**
+ * The consent gate, shared by both fan-out directions.
+ *
+ * Already-approved → run. Already-DENIED → skip silently: the operator made a
+ * durable decision and re-prompting every deploy would be nagging (ISS-0027).
+ * Only the undecided ('no_approval') and stale ('scope_changed') states warrant
+ * an interview, and the decision is persisted either way so a denial isn't
+ * re-asked next deploy.
+ *
+ * Extracted so `reconcileAspectsForSystems` cannot drift from
+ * `maybeRunAspectForTrigger`: an inbound reconcile that skipped this would
+ * apply an aspect the operator never approved, or one they refused.
+ */
+async function ensureAspectConsent(args: {
+  moduleId: string;
+  version: string;
+  aspect: BaseModuleAspect;
+  trigger: BaseModuleAspectTrigger;
+  db: DbClient;
+  requestConsent?: AspectConsentRequest;
+}): Promise<{ consented: true } | { consented: false; reason: AspectSkipReason }> {
+  const { moduleId, version, aspect, trigger, db } = args;
+  const approvalStatus = checkAspectApproval(moduleId, version, aspect, db);
+
+  if (approvalStatus === 'denied') {
+    return { consented: false, reason: 'denied' };
+  }
+  if (approvalStatus === 'no_approval' || approvalStatus === 'scope_changed') {
+    // ISS-0027: don't silently skip a declared aspect. Interview the operator
+    // for consent on the bus and WAIT. A responder (terminal, `events reply`,
+    // the celilo-deploy skill) approves or denies.
+    const requestConsent = args.requestConsent ?? requestAspectConsentViaBus;
+    const consented = await requestConsent({
+      moduleId,
+      version,
+      aspect,
+      trigger,
+      reason: approvalStatus,
+    });
+    recordAspectConsent({
+      moduleId,
+      version,
+      scopeHash: computeAspectScopeHash(aspect),
+      approver: process.env.USER ?? null,
+      consented,
+      db,
+    });
+    if (!consented) {
+      log.warn(`Aspect for '${moduleId}' consent refused; aspect skipped (will not re-prompt).`);
+      return { consented: false, reason: 'denied' };
+    }
+  }
+  return { consented: true };
+}
+
 /**
  * Deploy-flow glue (SC4): consulted by `module-deploy.ts` after a
  * primary deploy successfully completes. Decides whether to fan an
@@ -517,40 +602,16 @@ export async function maybeRunAspectForTrigger(args: {
     return { ran: false, reason: 'no_approval' };
   }
 
-  const approvalStatus = checkAspectApproval(moduleId, moduleRow.version, aspect, db);
-
-  // Already-approved → run. Already-DENIED → skip silently: the operator
-  // made a durable decision; re-prompting every deploy would be nagging
-  // (ISS-0027). Only the undecided ('no_approval') and stale ('scope_changed')
-  // states warrant an interview.
-  if (approvalStatus === 'denied') {
-    return { ran: false, reason: 'denied' };
-  }
-  if (approvalStatus === 'no_approval' || approvalStatus === 'scope_changed') {
-    // ISS-0027: don't silently skip a declared aspect. Interview the operator
-    // for consent on the bus and WAIT. A responder (terminal, `events reply`,
-    // the celilo-deploy skill) approves or denies. We persist the decision —
-    // either way — so a denial isn't re-asked next deploy.
-    const requestConsent = args.requestConsent ?? requestAspectConsentViaBus;
-    const consented = await requestConsent({
-      moduleId,
-      version: moduleRow.version,
-      aspect,
-      trigger,
-      reason: approvalStatus,
-    });
-    recordAspectConsent({
-      moduleId,
-      version: moduleRow.version,
-      scopeHash: computeAspectScopeHash(aspect),
-      approver: process.env.USER ?? null,
-      consented,
-      db,
-    });
-    if (!consented) {
-      log.warn(`Aspect for '${moduleId}' consent refused; aspect skipped (will not re-prompt).`);
-      return { ran: false, reason: 'denied' };
-    }
+  const consent = await ensureAspectConsent({
+    moduleId,
+    version: moduleRow.version,
+    aspect,
+    trigger,
+    db,
+    requestConsent: args.requestConsent,
+  });
+  if (!consent.consented) {
+    return { ran: false, reason: consent.reason };
   }
 
   const runner = args.runner ?? runAspectFanOut;
@@ -566,3 +627,313 @@ export async function maybeRunAspectForTrigger(args: {
   });
   return { ran: true, success: runResult.success, runResult };
 }
+
+/**
+ * A system the inbound reconcile may apply aspects to. Deliberately just a
+ * hostname and a zone: the reconcile decides eligibility from the zone and
+ * hands the hostname to `planAspectFanOut`, which already knows how to reach
+ * both a pool machine and a container_service LXC.
+ */
+export interface AspectReconcileSystem {
+  hostname: string;
+  /**
+   * `string`, not `NetworkZone`, to match what everything on this path already
+   * uses: `aspect.applicable_zones` is `string[]` from the manifest schema,
+   * `getSystemsByZone` takes `string[]`, and `DeployedSystem.zone` — the
+   * capability contract this is fed from — is `string`. Narrowing here would
+   * only add a cast at every call site.
+   */
+  zone: string;
+}
+
+/** One provider's aspect, applied (or not) to the systems it covered. */
+export interface AspectReconcileOutcome {
+  /** The module whose aspect this is — NOT the module being deployed. */
+  providerModuleId: string;
+  role: string;
+  /** The subset of the offered systems this aspect's zones actually cover. */
+  hostnames: string[];
+  ran: boolean;
+  success: boolean;
+  error?: string;
+  /** Set when `ran === false`. */
+  reason?: AspectSkipReason | 'paused' | 'not_deployed' | 'no_covered_systems';
+}
+
+export interface AspectReconcileResult {
+  outcomes: AspectReconcileOutcome[];
+  /** The subset that ran and failed — what a caller decides fatality on. */
+  failures: AspectReconcileOutcome[];
+}
+
+/**
+ * The INBOUND direction: given systems that have just come into existence,
+ * apply every approved aspect the fleet already provides that covers their
+ * zones.
+ *
+ * This is the fix for celilo#902. `maybeRunAspectForTrigger` is provider-scoped
+ * — one module's aspect across the whole fleet, enumerated at that instant —
+ * and nothing re-runs it, so a system provisioned later never receives an
+ * aspect and nothing reports the gap.
+ *
+ * TWO THINGS ARE DELIBERATELY NOT CONSULTED HERE, and both are load-bearing:
+ *
+ *  1. `aspect.triggers` (design D2). Eligibility is `applicable_zones` plus
+ *     operator approval, full stop. `triggers` declares which PROVIDER-side
+ *     events cause a fleet-wide fan-out; a system joining a zone is a framework
+ *     event, not a provider event, and the spec's scenario does not condition
+ *     on it either ("every approved aspect whose `applicable_zones` includes
+ *     that zone SHALL run on the new system"). Requiring modules to declare
+ *     `on_new_system_in_zone` would change every aspect's scope hash — raising
+ *     a re-approval interview on the live fleet as a side effect of a bug fix —
+ *     and would make correct convergence opt-in, so the next module that forgot
+ *     the declaration would reintroduce this bug quietly.
+ *  2. The deploying module's own aspect. `on_install` already fans that one out
+ *     across the whole fleet, so the caller passes it in `excludeModuleIds`.
+ *
+ * PAUSED PROVIDERS ARE SKIPPED (design D4a), and that is the documented escape
+ * hatch: an inbound aspect failure is fatal to the deploy that created the
+ * system, so an operator whose non-essential aspect is wedging every deploy
+ * pauses its provider, deploys, and unpauses.
+ *
+ * Consent is checked exactly as the outbound direction checks it, through the
+ * shared `ensureAspectConsent`.
+ */
+export async function reconcileAspectsForSystems(args: {
+  systems: AspectReconcileSystem[];
+  db: DbClient;
+  /** Providers to skip — the deploying module, whose own aspect already ran. */
+  excludeModuleIds?: string[];
+  runner?: typeof runAspectFanOut;
+  requestConsent?: AspectConsentRequest;
+}): Promise<AspectReconcileResult> {
+  const { systems, db } = args;
+  const outcomes: AspectReconcileOutcome[] = [];
+  if (systems.length === 0) return { outcomes, failures: [] };
+
+  const exclude = new Set(args.excludeModuleIds ?? []);
+  const runner = args.runner ?? runAspectFanOut;
+
+  for (const moduleRow of db.select().from(modules).all()) {
+    if (exclude.has(moduleRow.id)) continue;
+
+    const manifest = moduleRow.manifestData as ModuleManifest | null;
+    const aspect = manifest?.base_module_aspect;
+    if (!aspect) continue;
+
+    const base = { providerModuleId: moduleRow.id, role: aspect.ansible_role };
+
+    // A module that never deployed has nothing to fan out FROM — its
+    // ansible_vars resolve against infrastructure that does not exist.
+    if (moduleRow.state !== 'INSTALLED' && moduleRow.state !== 'VERIFIED') {
+      if (moduleRow.state === 'PAUSED') {
+        // Reported rather than silent: pausing to get past a wedged aspect is
+        // legitimate, but it must not quietly become permanent.
+        log.warn(
+          `Aspect '${aspect.ansible_role}' from paused module '${moduleRow.id}' NOT applied to ${systems.map((s) => s.hostname).join(', ')}. Unpause and redeploy it to converge them.`,
+        );
+        outcomes.push({ ...base, hostnames: [], ran: false, success: true, reason: 'paused' });
+        continue;
+      }
+      outcomes.push({ ...base, hostnames: [], ran: false, success: true, reason: 'not_deployed' });
+      continue;
+    }
+
+    const zones = new Set<string>(aspect.applicable_zones);
+    const covered = systems.filter((s) => zones.has(s.zone));
+    if (covered.length === 0) {
+      outcomes.push({
+        ...base,
+        hostnames: [],
+        ran: false,
+        success: true,
+        reason: 'no_covered_systems',
+      });
+      continue;
+    }
+
+    const consent = await ensureAspectConsent({
+      moduleId: moduleRow.id,
+      version: moduleRow.version,
+      aspect,
+      trigger: 'on_new_system_in_zone',
+      db,
+      requestConsent: args.requestConsent,
+    });
+    if (!consent.consented) {
+      outcomes.push({
+        ...base,
+        hostnames: covered.map((s) => s.hostname),
+        ran: false,
+        success: true,
+        reason: consent.reason,
+      });
+      continue;
+    }
+
+    const hostnames = covered.map((s) => s.hostname);
+    log.info(
+      `Applying aspect '${aspect.ansible_role}' from '${moduleRow.id}' to newly created system(s): ${hostnames.join(', ')}`,
+    );
+    const runResult = await runner({
+      moduleId: moduleRow.id,
+      aspect,
+      moduleSourcePath: moduleRow.sourcePath,
+      options: { trigger: 'on_new_system_in_zone', onlyHostnames: hostnames },
+      db,
+    });
+    outcomes.push({
+      ...base,
+      hostnames,
+      ran: true,
+      success: runResult.success,
+      error: runResult.error,
+    });
+  }
+
+  return { outcomes, failures: outcomes.filter((o) => o.ran && !o.success) };
+}
+
+/**
+ * How an aspect stands on one system, as MEASURED against that system.
+ *
+ * `unknown` is not a hedge and must not be collapsed into `applied`. Ansible's
+ * check mode does not evaluate a task that cannot support it — it SKIPS it —
+ * so a role built from `command:` / `shell:` tasks can finish a check run with
+ * `changed=0` having never been applied to the host at all. A two-state answer
+ * would report that as applied: a confidently clean verdict about an
+ * unconverged system, which is the same failure this whole approach exists to
+ * avoid (celilo#902 design D6). Absence of a change is not evidence of
+ * convergence when nothing was assessed.
+ */
+export type AspectCoverageState = 'applied' | 'missing' | 'unknown' | 'unreachable';
+
+export interface AspectCoverageFinding {
+  providerModuleId: string;
+  role: string;
+  hostname: string;
+  state: AspectCoverageState;
+  /** Why, in operator-facing words. Always set for anything but 'applied'. */
+  detail?: string;
+}
+
+/**
+ * Ask every system the fleet's approved aspects entitle it to whether it
+ * actually has them (celilo#902 design D6/D7).
+ *
+ * NOTHING IS STORED AND NOTHING IS READ FROM A RECORD. Both halves of the
+ * question are answered from live state:
+ *
+ *  - "should have" is `planAspectFanOut(aspect)` — literally the code that
+ *    performs the fan-out, so the entitlement set cannot disagree with it. No
+ *    separate query to drift.
+ *  - "does have" is the aspect evaluated against the host in check mode. A row
+ *    saying "applied" would be a claim about a remote host, and celilo has been
+ *    burned by trusting exactly that (celilo#626: `dns_registrations` rows held
+ *    a pinned `ip` and the refresher republished a dead address over correct
+ *    public DNS, with every in-fleet check green).
+ *
+ * This SSHes to every entitled system, so it is not cheap and must not run in a
+ * default `system doctor` pass — it is gated behind `--deep`.
+ *
+ * Consent is checked but never REQUESTED: a read-only diagnostic must not raise
+ * an interview. An aspect that is unapproved, denied, or whose scope changed is
+ * simply not verified.
+ */
+export async function verifyAspectCoverage(args: {
+  db: DbClient;
+  /** Restrict to one provider — `doctor --deep <module>`. */
+  onlyModuleId?: string;
+  /** Injected in tests, exactly as the other entry points here do it. */
+  runner?: typeof runAspectFanOut;
+}): Promise<AspectCoverageFinding[]> {
+  const { db } = args;
+  const runner = args.runner ?? runAspectFanOut;
+  const findings: AspectCoverageFinding[] = [];
+
+  for (const moduleRow of db.select().from(modules).all()) {
+    if (args.onlyModuleId && moduleRow.id !== args.onlyModuleId) continue;
+
+    const manifest = moduleRow.manifestData as ModuleManifest | null;
+    const aspect = manifest?.base_module_aspect;
+    if (!aspect) continue;
+    if (moduleRow.state !== 'INSTALLED' && moduleRow.state !== 'VERIFIED') {
+      // A paused provider's entitled systems are still reported (D4a) — pausing
+      // to get past a wedged aspect is legitimate, but it must not quietly
+      // become permanent. Reported without a probe: the provider is not running
+      // and re-running its role against every host would be a change, not a read.
+      if (moduleRow.state === 'PAUSED') {
+        const plan = await planAspectFanOut(aspect);
+        for (const target of plan.targetSystems) {
+          findings.push({
+            providerModuleId: moduleRow.id,
+            role: aspect.ansible_role,
+            hostname: target.hostname,
+            state: 'unknown',
+            detail: `'${moduleRow.id}' is PAUSED, so its aspect is not being applied to new systems. Unpause and redeploy it to converge.`,
+          });
+        }
+      }
+      continue;
+    }
+    if (checkAspectApproval(moduleRow.id, moduleRow.version, aspect, db) !== 'approved') continue;
+
+    const plan = await planAspectFanOut(aspect);
+    if (plan.targetSystems.length === 0) continue;
+
+    const result = await runner({
+      moduleId: moduleRow.id,
+      aspect,
+      moduleSourcePath: moduleRow.sourcePath,
+      options: { trigger: 'on_new_system_in_zone', check: true, noInteractive: true },
+      db,
+    });
+
+    const byHost = new Map(result.recap.map((r) => [r.host, r]));
+    for (const target of plan.targetSystems) {
+      const base = {
+        providerModuleId: moduleRow.id,
+        role: aspect.ansible_role,
+        hostname: target.hostname,
+      };
+      const recap = byHost.get(target.hostname);
+      if (!recap) {
+        findings.push({
+          ...base,
+          state: 'unknown',
+          detail:
+            'Ansible produced no recap line for this host, so nothing was measured. Absence of a recap is not evidence the aspect is applied.',
+        });
+        continue;
+      }
+      if (recap.unreachable > 0 || recap.failed > 0) {
+        findings.push({
+          ...base,
+          state: 'unreachable',
+          detail: 'The host could not be evaluated — it did not answer, or the role errored on it.',
+        });
+        continue;
+      }
+      if (recap.skipped > 0) {
+        // THE CASE THAT MUST NOT READ AS APPLIED. See AspectCoverageState.
+        findings.push({
+          ...base,
+          state: 'unknown',
+          detail: `The role has ${recap.skipped} task(s) check mode cannot evaluate, so convergence was not measured. Prefer check-capable Ansible modules (copy, template, lineinfile, file, package, service) in aspect roles, or give a command/shell task an honest changed_when:.`,
+        });
+        continue;
+      }
+      if (recap.changed > 0) {
+        findings.push({
+          ...base,
+          state: 'missing',
+          detail: `The aspect would change ${recap.changed} thing(s) on this host, so it is not applied. Run \`celilo module deploy ${moduleRow.id}\` to converge it.`,
+        });
+        continue;
+      }
+      findings.push({ ...base, state: 'applied' });
+    }
+  }
+
+  return findings;
+}

package/src/services/audit/browser-pin.test.ts

@@ -0,0 +1,167 @@
+/**
+ * The two assertions that matter here are both about STAYING QUIET.
+ *
+ * A host with no browser provisioned is the NORMAL case — installation is
+ * opt-in — so a check that fired there would put a finding on every default
+ * host in the fleet forever. And a module that bundles no browser client is
+ * almost every module. Getting either wrong turns a guardrail into noise
+ * that trains an operator to ignore the audit.
+ *
+ * The revision is read from the bundle's own `browsers.json`, never from a
+ * version→revision table, so the reader tests use real files.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { auditBrowserPin, readBundledBrowserClient } from './browser-pin';
+
+const PROVISIONED = { revision: '1223', playwrightVersion: '1.60.0' };
+
+describe('auditBrowserPin', () => {
+  test('says nothing when no browser is provisioned', async () => {
+    // The opt-in default. `system doctor` reports the absence; this must not,
+    // or every host that never wanted a browser carries a permanent finding.
+    const findings = await auditBrowserPin({
+      consumers: [{ moduleId: 'lunacycle', clientVersion: '1.55.1', expectedRevision: '1193' }],
+      provisioned: null,
+    });
+
+    expect(findings).toEqual([]);
+  });
+
+  test('says nothing when no module bundles a browser client', async () => {
+    expect(await auditBrowserPin({ consumers: [], provisioned: PROVISIONED })).toEqual([]);
+  });
+
+  test('says nothing when the bundled client expects the installed revision', async () => {
+    const findings = await auditBrowserPin({
+      consumers: [{ moduleId: 'lunacycle', clientVersion: '1.60.0', expectedRevision: '1223' }],
+      provisioned: PROVISIONED,
+    });
+
+    expect(findings).toEqual([]);
+  });
+
+  test('reports drift — never blocked — when the revisions differ', async () => {
+    const findings = await auditBrowserPin({
+      consumers: [{ moduleId: 'lunacycle', clientVersion: '1.55.1', expectedRevision: '1193' }],
+      provisioned: PROVISIONED,
+    });
+
+    expect(findings).toHaveLength(1);
+    const finding = findings[0];
+    // Task 4.2: it warns, it never blocks. Under D2 the consumer passes an
+    // explicit executablePath, so this is a soft protocol risk, not a
+    // failure — blocking a deploy on it would be wrong.
+    expect(finding?.severity).toBe('drift');
+    expect(finding?.category).toBe('browser_pin');
+    expect(finding?.subject).toBe('lunacycle');
+    expect(finding?.actionable).toBe(false);
+    // Both revisions named, so the operator can tell which end to move.
+    expect(finding?.message).toContain('1193');
+    expect(finding?.message).toContain('1223');
+    expect(finding?.remediation).toContain('1.60.0');
+  });
+
+  test('reports one finding per drifting module', async () => {
+    const findings = await auditBrowserPin({
+      consumers: [
+        { moduleId: 'lunacycle', clientVersion: '1.55.1', expectedRevision: '1193' },
+        { moduleId: 'aligned', clientVersion: '1.60.0', expectedRevision: '1223' },
+        { moduleId: 'other', clientVersion: '1.50.0', expectedRevision: '1150' },
+      ],
+      provisioned: PROVISIONED,
+    });
+
+    expect(findings.map((f) => f.subject)).toEqual(['lunacycle', 'other']);
+  });
+});
+
+describe('readBundledBrowserClient', () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'celilo-browser-pin-'));
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  /** Write a bundled playwright-core under `<root>/<bundleDir>/node_modules`. */
+  function bundle(bundleDir: string, version: string, revision: number | string): void {
+    const pkg = join(root, bundleDir, 'node_modules', 'playwright-core');
+    mkdirSync(pkg, { recursive: true });
+    writeFileSync(join(pkg, 'package.json'), JSON.stringify({ version }));
+    writeFileSync(
+      join(pkg, 'browsers.json'),
+      JSON.stringify({
+        browsers: [
+          { name: 'chromium', revision: 9999 },
+          { name: 'chromium-headless-shell', revision },
+        ],
+      }),
+    );
+  }
+
+  test('finds a bundle under the conventional scripts/ directory', () => {
+    bundle('scripts', '1.60.0', 1223);
+
+    expect(readBundledBrowserClient('m', root, ['./scripts/health-check.ts'])).toEqual({
+      moduleId: 'm',
+      clientVersion: '1.60.0',
+      expectedRevision: '1223',
+    });
+  });
+
+  test('finds a bundle beside a hook script in a non-standard layout', () => {
+    // The one real browser consumer keeps its hooks in celilo/scripts/,
+    // so a hardcoded scripts/ would have missed exactly the module this
+    // check exists for.
+    bundle('celilo/scripts', '1.55.1', 1193);
+
+    const found = readBundledBrowserClient('lunacycle', root, ['./celilo/scripts/health-check.ts']);
+
+    expect(found?.expectedRevision).toBe('1193');
+    expect(found?.clientVersion).toBe('1.55.1');
+  });
+
+  test('reads the revision as a STRING even though the file holds a number', () => {
+    // browsers.json stores it unquoted; comparing a number to the
+    // descriptor's string would never match and the check would be silent.
+    bundle('scripts', '1.60.0', 1223);
+
+    expect(readBundledBrowserClient('m', root, [])?.expectedRevision).toBe('1223');
+  });
+
+  test('returns null when the module bundles no browser client', () => {
+    expect(readBundledBrowserClient('m', root, ['./scripts/on_install.ts'])).toBeNull();
+  });
+
+  test('returns null when browsers.json is unreadable rather than throwing', () => {
+    const pkg = join(root, 'scripts', 'node_modules', 'playwright-core');
+    mkdirSync(pkg, { recursive: true });
+    writeFileSync(join(pkg, 'browsers.json'), 'not json {');
+
+    expect(readBundledBrowserClient('m', root, [])).toBeNull();
+  });
+
+  test('a bundle without a readable package.json still reports its revision', () => {
+    // The revision is the load-bearing half; a missing version should not
+    // suppress a real drift finding.
+    const pkg = join(root, 'scripts', 'node_modules', 'playwright-core');
+    mkdirSync(pkg, { recursive: true });
+    writeFileSync(
+      join(pkg, 'browsers.json'),
+      JSON.stringify({ browsers: [{ name: 'chromium-headless-shell', revision: 1223 }] }),
+    );
+
+    expect(readBundledBrowserClient('m', root, [])).toEqual({
+      moduleId: 'm',
+      clientVersion: 'unknown',
+      expectedRevision: '1223',
+    });
+  });
+});