@celilo/cli 1.1.0 → 1.2.0

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',
+    });
+  });
+});

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

@@ -0,0 +1,185 @@
+/**
+ * Browser pin-drift check (managed-browser-runtime D9).
+ *
+ * A module bundles its own `playwright-core`, and celilo provisions the
+ * browser binary. Under D2 the consumer passes an explicit
+ * `executablePath`, so a client bump can no longer move the browser out
+ * from under it — the hard failure that started that change cannot recur.
+ * What remains is softer: a client several minor versions from the binary's
+ * build drives it over a protocol the two were versioned together. Usually
+ * fine; not guaranteed.
+ *
+ * So this WARNS and never blocks (D9 / task 4.2).
+ *
+ * **It compares REVISIONS, not version strings.** The revision is what
+ * actually has to match a build, and each `playwright-core` states its own
+ * in the `browsers.json` inside the package — which is where 1193 and 1223
+ * came from. Reading it out of the bundle is what keeps this honest and
+ * means nobody maintains a version→revision table that will rot.
+ *
+ * Like `system doctor` (D4), it reads the bundle and the descriptor and
+ * never asks Playwright which executable it would use: that reports the
+ * full browser regardless of what a headless launch would open.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { resolveBrowser } from '@celilo/capabilities';
+import type { ModuleManifest } from '../../manifest/schema';
+import type { DriftFinding } from './types';
+
+/** What a module bundles, already read off disk. */
+export interface BundledBrowserClient {
+  moduleId: string;
+  /** The bundled `playwright-core` version, e.g. `1.60.0`. */
+  clientVersion: string;
+  /** The chromium-headless-shell revision that client expects, e.g. `1223`. */
+  expectedRevision: string;
+}
+
+export interface BrowserPinAuditDeps {
+  /**
+   * Modules that bundle a browser client. A module with none contributes
+   * nothing — most modules never launch a browser.
+   */
+  consumers: BundledBrowserClient[];
+  /**
+   * The provisioned browser, or `null` when this host has none.
+   *
+   * Null means silence, not a finding: installation is opt-in, so a host
+   * without a browser is the normal case and `system doctor` is already
+   * the place that reports its absence.
+   */
+  provisioned: { revision: string; playwrightVersion: string } | null;
+}
+
+export async function auditBrowserPin(deps: BrowserPinAuditDeps): Promise<DriftFinding[]> {
+  const { provisioned } = deps;
+  if (!provisioned) return [];
+
+  const findings: DriftFinding[] = [];
+  for (const consumer of deps.consumers) {
+    if (consumer.expectedRevision === provisioned.revision) continue;
+
+    // Any difference is reported. A "how far apart is too far" threshold
+    // would be a tuning knob with no evidence behind it — the revision is
+    // the thing that has to match a build, so it either does or it does not.
+    findings.push({
+      category: 'browser_pin',
+      severity: 'drift',
+      code: 'browser_client_revision_drift',
+      subject: consumer.moduleId,
+      message:
+        `${consumer.moduleId} bundles playwright-core ${consumer.clientVersion}, which expects ` +
+        `chromium revision ${consumer.expectedRevision}, but this host has revision ` +
+        `${provisioned.revision} (installed for playwright ${provisioned.playwrightVersion}).`,
+      details:
+        'Not a failure: the module passes an explicit executablePath, so it launches the ' +
+        'installed browser regardless of which revision its client expects. The risk is ' +
+        'protocol skew — a client far from its browser build drives it over a protocol the ' +
+        'two were versioned together.',
+      remediation:
+        `Align them: either republish ${consumer.moduleId} against playwright-core ` +
+        `${provisioned.playwrightVersion}, or set celilo-mgmt's playwright_version to ` +
+        `${consumer.clientVersion} and redeploy it.`,
+      actionable: false,
+    });
+  }
+  return findings;
+}
+
+/**
+ * Read the browser client a module bundles, or `null` when it bundles none.
+ *
+ * Searches beside each hook script rather than walking the module tree:
+ * `scripts/node_modules` is where a module's hook runtime is bundled, and
+ * the manifest's own hook list is the authoritative statement of where its
+ * hook code lives. A module laying its hooks out differently
+ * (`celilo/scripts/…`, as the one real browser consumer does) is therefore
+ * found without hardcoding either layout.
+ */
+export function readBundledBrowserClient(
+  moduleId: string,
+  sourcePath: string,
+  hookScripts: string[],
+): BundledBrowserClient | null {
+  const searched = new Set<string>([join(sourcePath, 'scripts')]);
+  for (const script of hookScripts) {
+    searched.add(dirname(join(sourcePath, script)));
+  }
+
+  for (const dir of searched) {
+    const pkgRoot = join(dir, 'node_modules', 'playwright-core');
+    const browsers = join(pkgRoot, 'browsers.json');
+    if (!existsSync(browsers)) continue;
+
+    const expectedRevision = revisionFor(browsers, 'chromium-headless-shell');
+    if (!expectedRevision) continue;
+
+    return {
+      moduleId,
+      clientVersion: packageVersion(join(pkgRoot, 'package.json')) ?? 'unknown',
+      expectedRevision,
+    };
+  }
+  return null;
+}
+
+/**
+ * The revision a `playwright-core` states for a browser, from the
+ * `browsers.json` inside the package. Never a lookup table — the package
+ * is the only thing that knows, and a table would rot silently.
+ */
+function revisionFor(browsersJsonPath: string, browserName: string): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(browsersJsonPath, 'utf-8')) as {
+      browsers?: Array<{ name?: string; revision?: string | number }>;
+    };
+    const entry = parsed.browsers?.find((b) => b.name === browserName);
+    return entry?.revision === undefined ? null : String(entry.revision);
+  } catch {
+    return null;
+  }
+}
+
+function packageVersion(packageJsonPath: string): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as { version?: string };
+    return parsed.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gather this check's inputs from the module store and the provisioned
+ * browser's descriptor.
+ *
+ * Lives here rather than in the CLI so the two `AuditDeps` builders stay
+ * one line each and cannot drift apart — they already each carry their own
+ * copy of every other category's wiring.
+ */
+export function collectBrowserPinDeps(
+  modules: Array<{ id: string; sourcePath: string; manifestData: unknown }>,
+): BrowserPinAuditDeps {
+  const consumers: BundledBrowserClient[] = [];
+  for (const module of modules) {
+    const manifest = module.manifestData as ModuleManifest | undefined;
+    const hookScripts = Object.values(manifest?.hooks ?? {})
+      .map((hook) => (hook as { script?: string } | undefined)?.script)
+      .filter((script): script is string => typeof script === 'string');
+    const bundled = readBundledBrowserClient(module.id, module.sourcePath, hookScripts);
+    if (bundled) consumers.push(bundled);
+  }
+
+  let provisioned: BrowserPinAuditDeps['provisioned'] = null;
+  try {
+    const browser = resolveBrowser();
+    provisioned = { revision: browser.revision, playwrightVersion: browser.playwrightVersion };
+  } catch {
+    // No browser on this host — the check stays silent. `system doctor`
+    // is where an absent browser is reported, not here.
+  }
+
+  return { consumers, provisioned };
+}

package/src/services/audit/index.test.ts

@@ -15,6 +15,7 @@ const emptyDeps = {
     applied: () => [],
     db: fakeDb,
   },
+  browserPin: { consumers: [], provisioned: null },
   capabilityAbi: { modules: [] },
   terraformPlan: {
     modules: [],

package/src/services/audit/index.ts

@@ -15,6 +15,7 @@ import {
   auditAbandonedOperations,
 } from './abandoned-operations';
 import { type BackupsAuditDeps, auditBackups } from './backups';
+import { type BrowserPinAuditDeps, auditBrowserPin } from './browser-pin';
 import { type CapabilityAbiAuditDeps, auditCapabilityAbi } from './capability-abi';
 import { type CliVersionAuditDeps, auditCliVersion } from './cli-version';
 import { type HealthAuditDeps, auditHealth } from './health';
@@ -48,6 +49,7 @@ export interface AuditDeps {
   cliVersion: CliVersionAuditDeps;
   schema: SchemaAuditDeps;
   capabilityAbi: CapabilityAbiAuditDeps;
+  browserPin: BrowserPinAuditDeps;
   terraformPlan: TerraformPlanAuditDeps;
   moduleVersions: ModuleVersionsAuditDeps;
   moduleConfigs: ModuleConfigsAuditDeps;
@@ -101,6 +103,7 @@ export async function runAudit(
     wrap('cli_version', auditCliVersion(deps.cliVersion)),
     wrap('schema', auditSchema(deps.schema)),
     wrap('capability_abi', auditCapabilityAbi(deps.capabilityAbi)),
+    wrap('browser_pin', auditBrowserPin(deps.browserPin)),
     wrap('terraform_plan', auditTerraformPlan(deps.terraformPlan)),
     wrap('module_versions', auditModuleVersions(deps.moduleVersions)),
     wrap('module_configs', auditModuleConfigs(deps.moduleConfigs)),

package/src/services/audit/types.ts

@@ -25,6 +25,7 @@ export type DriftCategory =
   | 'cli_version'
   | 'schema'
   | 'capability_abi'
+  | 'browser_pin'
   | 'terraform_plan'
   | 'module_versions'
   | 'module_configs'

package/src/services/health-runner.ts

@@ -31,6 +31,16 @@ export interface HealthCheckResult {
   status: 'healthy' | 'degraded' | 'unhealthy' | 'no-checks' | 'error';
   checks: HealthCheckItem[];
   error?: string;
+  /**
+   * Files the hook wrote to its per-run artifact directory.
+   *
+   * This path is the one that runs UNATTENDED every fifteen minutes, and
+   * it used to drop `HookResult`'s artifacts on the floor entirely — the
+   * on-demand paths (`module run-hook`, deploy) surfaced them and this one
+   * did not, so the artifacts were discarded exactly when nobody was
+   * watching to re-run the check by hand.
+   */
+  artifactPaths?: string[];
 }
 
 export interface HealthCheckOptions {
@@ -191,11 +201,15 @@ export async function runModuleHealthCheck(
   presentation.finish(hookResult.success);
 
   if (!hookResult.success) {
+    // Artifacts matter MOST here: the hook died, so there are no named
+    // checks to explain why, and whatever it managed to write is all the
+    // operator gets.
     return {
       moduleId,
       status: 'error',
       checks: [],
       error: hookResult.error,
+      artifactPaths: hookResult.artifactPaths,
     };
   }
 
@@ -220,7 +234,7 @@ export async function runModuleHealthCheck(
     db.update(modules).set({ state: nextState }).where(eq(modules.id, moduleId)).run();
   }
 
-  return { moduleId, status, checks };
+  return { moduleId, status, checks, artifactPaths: hookResult.artifactPaths };
 }
 
 /**

package/src/services/module-deploy.ts

@@ -15,6 +15,7 @@ import { capabilities, machines, modules } from '../db/schema';
 import { loadCapabilityFunctions } from '../hooks/capability-loader';
 import { invokeHook } from '../hooks/executor';
 import { createGaugeLogger } from '../hooks/logger';
+import { describeArtifacts } from '../hooks/types';
 import type { HookDefinition, HookLogger, HookResult } from '../hooks/types';
 import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
@@ -624,10 +625,9 @@ async function deployModuleImpl(
 
         if (!hookResult.success) {
           gauge.stop(false);
-          let errorMsg = hookResult.error || 'Configuration validation failed';
-          if (hookResult.screenshotPath) {
-            errorMsg += `\n\nScreenshot saved: ${hookResult.screenshotPath}`;
-          }
+          const errorMsg =
+            (hookResult.error || 'Configuration validation failed') +
+            describeArtifacts(hookResult.artifactPaths);
           return {
             success: false,
             error: errorMsg,

package/src/services/update/orchestrator.test.ts

@@ -72,6 +72,7 @@ const cleanAudit: AuditDeps = {
   cliVersion: { installedVersion: '0.1.5', fetcher: async () => '0.1.5' },
   schema: { journal: () => null, applied: () => [], db: fakeDb },
   capabilityAbi: { modules: [] },
+  browserPin: { consumers: [], provisioned: null },
   terraformPlan: { modules: [], run: async () => ({ exitCode: 0, stdout: '', stderr: '' }) },
   moduleVersions: { installed: [], fetcher: async () => ({ latest: null }) },
   moduleConfigs: { modules: [] },

package/src/system/browser-provisioning.test.ts

@@ -0,0 +1,67 @@
+/**
+ * The browser runtime is described in two languages: an Ansible role
+ * installs it, and TypeScript reads it back. Nothing in either language
+ * can see the other, so these are the assertions that keep them agreeing.
+ *
+ * Both facts here have already drifted in other pairs of files in this
+ * repo; neither drift is visible in a diff.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  BROWSER_DESCRIPTOR_PATH,
+  BROWSER_EXECUTABLE_PATH,
+  BROWSER_ROOT,
+} from '@celilo/capabilities';
+
+const MODULE_ROOT = join(import.meta.dir, '../../../../modules/celilo-mgmt');
+
+function read(relativePath: string): string {
+  return readFileSync(join(MODULE_ROOT, relativePath), 'utf-8');
+}
+
+describe('celilo-mgmt browser provisioning', () => {
+  test('the playbook stamps the module version the manifest declares', () => {
+    // The descriptor records which celilo-mgmt wrote it. No template prefix
+    // exposes a module's own version ($self: resolves module CONFIG), so
+    // the playbook carries a literal — and this is what stops it rotting.
+    const manifestVersion = read('manifest.yml').match(/^version:\s*(\S+)$/m)?.[1];
+    const playbookVersion = read('ansible/playbook.yml.tpl').match(
+      /celilo_mgmt_version:\s*"([^"]+)"/,
+    )?.[1];
+
+    expect(manifestVersion).toBeTruthy();
+    expect(playbookVersion).toBe(manifestVersion as string);
+  });
+
+  test('the role installs into the tree the resolver reads', () => {
+    const debian = read('ansible/roles/celilo-mgmt/tasks/debian.yml');
+
+    expect(BROWSER_EXECUTABLE_PATH).toBe(`${BROWSER_ROOT}/current/chrome`);
+    expect(debian).toContain(`PLAYWRIGHT_BROWSERS_PATH: ${BROWSER_ROOT}`);
+    expect(debian).toContain(`dest: ${BROWSER_EXECUTABLE_PATH}`);
+    expect(debian).toContain(`dest: ${BROWSER_DESCRIPTOR_PATH}`);
+  });
+
+  test('the install is gated, so a default host downloads nothing', () => {
+    const debian = read('ansible/roles/celilo-mgmt/tasks/debian.yml');
+    const manifest = read('manifest.yml');
+
+    expect(debian).toContain('when: celilo_install_browser | bool');
+    // The gate is worthless if the flag defaults on: the e2e topology has
+    // no real internet, and the browser comes from an external CDN.
+    expect(manifest).toMatch(/name: install_browser[\s\S]*?default: false/);
+  });
+
+  test('the role provisions the headless shell, not full Chromium', () => {
+    // Reversed after measuring celilo-mgr: both builds there are headless
+    // shells and chromium.launch() has been driving one in production all
+    // along. Provisioning the full browser would change what works.
+    const debian = read('ansible/roles/celilo-mgmt/tasks/debian.yml');
+
+    expect(debian).toContain('install chromium-headless-shell');
+    expect(debian).toContain("'flavor': 'headless-shell'");
+  });
+});

package/src/system/prereqs.test.ts

@@ -14,6 +14,8 @@
  */
 
 import { describe, expect, test } from 'bun:test';
+import { unlinkSync, writeFileSync } from 'node:fs';
+import { BROWSER_EXECUTABLE_PATH } from '@celilo/capabilities';
 import {
   PREREQUISITES,
   checkPrerequisite,
@@ -52,6 +54,8 @@ describe('PREREQUISITES table', () => {
     expect(names).toContain('git');
     expect(names).toContain('curl');
     expect(names).toContain('unzip');
+    expect(names).toContain('browser');
+    expect(names).toContain('fonts');
   });
 });
 
@@ -313,6 +317,75 @@ describe('checkPrerequisite', () => {
   });
 });
 
+// ── Absolute-path prerequisites (the browser) ─────────────────────────
+
+describe('absolute-path prerequisites', () => {
+  test('a real executable at an absolute path is present, with its version', () => {
+    // `bun --version` prints a bare semver, and Bun.which finds a real path
+    // for it — so this exercises the absolute-path branch end to end.
+    const bunPath = Bun.which('bun');
+    if (!bunPath) throw new Error('bun is not on PATH');
+    const result = checkPrerequisite({
+      name: 'browser',
+      description: 'stand-in for the provisioned browser',
+      command: bunPath,
+      versionFlag: '--version',
+      versionRegex: /(\d+\.\d+\.\d+)/,
+      minVersion: null,
+    });
+    expect(result.present).toBe(true);
+    expect(result.binaryPath).toBe(bunPath);
+    expect(result.version).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  test('a DIRECTORY at the declared path is not present', () => {
+    // The case that motivates the whole check: a build directory with no
+    // binary in it satisfies a path test and then fails at launch.
+    const result = checkPrerequisite({
+      name: 'browser',
+      description: 'stand-in for the provisioned browser',
+      command: '/tmp',
+      versionFlag: '--version',
+      versionRegex: /(\d+\.\d+\.\d+)/,
+      minVersion: null,
+    });
+    expect(result.present).toBe(false);
+    expect(result.binaryPath).toBeNull();
+  });
+
+  test('a non-executable file at the declared path is not present', () => {
+    const path = `/tmp/celilo-prereq-not-executable-${process.pid}`;
+    writeFileSync(path, 'not a browser', { mode: 0o644 });
+    try {
+      const result = checkPrerequisite({
+        name: 'browser',
+        description: 'stand-in for the provisioned browser',
+        command: path,
+        versionFlag: '--version',
+        versionRegex: /(\d+\.\d+\.\d+)/,
+        minVersion: null,
+      });
+      expect(result.present).toBe(false);
+    } finally {
+      unlinkSync(path);
+    }
+  });
+
+  test('the browser row names install_browser as its remedy', () => {
+    const spec = PREREQUISITES.find((p) => p.name === 'browser');
+    if (!spec) throw new Error('browser spec missing');
+    expect(spec.command).toBe(BROWSER_EXECUTABLE_PATH);
+    expect(getInstallHint('browser', 'apt')).toContain('install_browser');
+  });
+
+  test('fc-match output yields the resolved font family', () => {
+    const spec = PREREQUISITES.find((p) => p.name === 'fonts');
+    if (!spec) throw new Error('fonts spec missing');
+    const sample = 'DejaVuSans.ttf: "DejaVu Sans" "Book"';
+    expect(sample.match(spec.versionRegex)?.[1]).toBe('DejaVu Sans');
+  });
+});
+
 // ── failingPrerequisites ──────────────────────────────────────────────
 
 describe('failingPrerequisites', () => {