@celilo/cli 2.0.0 → 2.1.0

package/src/hooks/jail.ts

@@ -21,22 +21,31 @@
  *     reads.
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import type { Dirent } from 'node:fs';
 import {
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
   readdirSync,
   realpathSync,
   renameSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from 'node:fs';
-import { hostname } from 'node:os';
+import { hostname, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { getDataDir } from '../config/paths';
-import { type MountSet, type MountSetRequest, toBwrapArgs } from './mount-set';
+import { HOOK_SOCKET_ENV } from './hook-protocol';
+import {
+  type MountSet,
+  type MountSetRequest,
+  deriveMountSet,
+  toBwrapArgs,
+  toSandboxProfile,
+} from './mount-set';
 import { JAIL_PROVIDED_PATHS } from './unjailed-lint';
 
 /**
@@ -130,6 +139,18 @@ export interface JailPlan {
    * where it becomes visible.
    */
   readonly skipped: readonly string[];
+  /**
+   * The directory to spawn the child in, when the backend cannot set it itself.
+   *
+   * bubblewrap takes `--chdir`, so its plans leave this absent and the child
+   * inherits celilo's cwd — which the jail has replaced anyway.
+   * `sandbox-exec` has no equivalent, so the child inherits the OPERATOR's cwd
+   * and the profile does not name it. Measured 2026-08-27: `bun` reads its
+   * working directory before running anything, so a cwd outside the profile
+   * kills it with `error: An unknown error occurred (Unexpected)` and no
+   * further diagnostic. Naming the mount set's `chdir` here is the fix.
+   */
+  readonly cwd?: string;
 }
 
 /**
@@ -186,6 +207,24 @@ const JAIL_NAMESPACE_ARGS = [
  */
 const BWRAP = 'bwrap';
 
+/**
+ * The macOS jail builder.
+ *
+ * Pinned absolute, unlike `BWRAP`. There is no AppArmor-style profile to miss
+ * here, so `PATH` buys nothing and costs the one thing that matters: a
+ * `sandbox-exec` earlier on `PATH` would be handed every hook's profile and
+ * could report a jail it never built. The probe below would catch that, and
+ * pinning means it never has to.
+ */
+const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
+
+/**
+ * The runner shim, named here as well as in the executor because the probe has
+ * to spawn the REAL one. A probe that starts a smaller program answers a
+ * question about a smaller program.
+ */
+const HOOK_RUNNER_PATH = join(import.meta.dir, 'hook-runner.ts');
+
 /** How long to wait for the probe before calling the backend unavailable. */
 const PROBE_TIMEOUT_MS = 10_000;
 
@@ -213,17 +252,7 @@ export function detectJailBackend(): JailAvailability {
 }
 
 function probeJailBackend(): JailAvailability {
-  if (process.platform === 'darwin') {
-    // `sandbox-exec` is measured working (D8) but the backend that generates
-    // its profile is task 4.8 and is not built. Claiming macOS is jailed
-    // because the tool exists would be the fail-open jail D8 calls worse than
-    // no jail at all.
-    return {
-      backend: 'none',
-      reason:
-        'macOS has no hook jail yet: the sandbox-exec backend is designed but not built (hook-process-boundary task 4.8). Hooks run unjailed on this host.',
-    };
-  }
+  if (process.platform === 'darwin') return probeSandboxExec();
   if (process.platform !== 'linux') {
     return {
       backend: 'none',
@@ -243,6 +272,118 @@ function probeJailBackend(): JailAvailability {
   }
 }
 
+/**
+ * What the probe plants and then tries to read. Its ABSENCE from the output is
+ * the evidence, so it is a string nothing else would print.
+ */
+const SANDBOX_PROBE_MARKER = 'celilo-jail-probe-reached-the-planted-file';
+
+/**
+ * Can this Mac jail? Measured by proving a DENIAL, never by finding the binary.
+ *
+ * This probe is shaped differently from bubblewrap's and the difference is the
+ * point. bubblewrap FAILS when it cannot build a namespace, loudly, with one of
+ * four distinct denials — so running it at all is the measurement.
+ * `sandbox-exec` does not fail. A profile it cannot apply to a path is simply
+ * not applied: the access succeeds and nothing anywhere reports an error (D8,
+ * measured, and re-measured 2026-08-27 in both directions — a rule naming
+ * `/tmp/x` where the kernel sees `/private/tmp/x` neither denies nor grants).
+ *
+ * So "sandbox-exec exists" is not evidence of anything, and neither is "the
+ * profile parsed". The only honest question is whether a file this probe
+ * planted, outside the profile, is actually unreachable from inside it. That is
+ * CLAUDE.md's reach probe applied to the jail itself: plant a marker, run the
+ * REAL machinery, and read which markers fired.
+ *
+ * Three outcomes, and the middle one is the one worth having:
+ *
+ *   - the read was refused          → `sandbox-exec`, the jail is real
+ *   - the read SUCCEEDED            → `none`, and the reason says fail-open.
+ *     A jail that is believed and absent is worse than no jail (D8).
+ *   - `sandbox-exec` never ran      → `none`, with its own message
+ */
+function probeSandboxExec(): JailAvailability {
+  let scratch: string | undefined;
+  try {
+    scratch = mkdtempSync(join(realpathOrSelf(tmpdir()), 'celilo-jail-probe-'));
+    const allowed = join(scratch, 'allowed');
+    const planted = join(scratch, 'planted');
+    mkdirSync(join(allowed, 'state'), { recursive: true });
+    writeFileSync(planted, SANDBOX_PROBE_MARKER);
+
+    // The REAL derivation, the REAL renderer, and the REAL shim path, so this
+    // clears the same bar the spawn does. Every shortcut here has already been
+    // measured to matter: a mount set built around `bun -e` omits the shim's
+    // `node_modules` rows, and the runtime then starts under the probe's
+    // profile and dies under the executor's.
+    const profile = toSandboxProfile(
+      deriveMountSet({
+        modulePath: allowed,
+        stateDir: join(allowed, 'state'),
+        socketDir: allowed,
+        runtimePath: process.execPath,
+        runnerPath: HOOK_RUNNER_PATH,
+        runtimeModulePaths: runtimeModulePathsFor(HOOK_RUNNER_PATH),
+        pathInputs: [],
+      }),
+    );
+    const run = (cmd: readonly string[]) =>
+      spawnSync(SANDBOX_EXEC, ['-p', profile, '--', ...cmd], {
+        cwd: allowed,
+        encoding: 'utf-8',
+        timeout: PROBE_TIMEOUT_MS,
+      });
+
+    // 1. Can the RUNTIME start? Spawn the actual shim with no socket in its
+    //    environment: it refuses immediately with a known message, having
+    //    already loaded itself, `@celilo/capabilities` and Zod. That is the
+    //    whole of the startup path, and it is where a jail that denies the
+    //    runtime something it needs shows up.
+    const started = run([process.execPath, HOOK_RUNNER_PATH]);
+    if (started.error) throw started.error;
+    if (!started.stderr?.includes(HOOK_SOCKET_ENV)) {
+      return {
+        backend: 'none',
+        reason: `sandbox-exec built a jail the hook runner cannot start in, so hooks run unjailed rather than failing one at a time. The runner exited ${started.status} saying: ${(started.stderr || started.stdout || '').trim().split('\n')[0] || '(nothing)'}`,
+      };
+    }
+
+    // 2. Does a DENIAL actually apply? `sandbox-exec` never fails on a rule it
+    //    cannot match — the access simply succeeds and nothing reports an
+    //    error (D8, measured). So the profile is not evidence; a file this
+    //    probe planted outside the mount set, and could not read, is.
+    const denied = run([
+      process.execPath,
+      '-e',
+      `try{require('node:fs').readFileSync(${JSON.stringify(planted)});console.log('${SANDBOX_PROBE_MARKER}')}catch{console.log('refused')}`,
+    ]);
+    if (denied.error) throw denied.error;
+    if ((denied.stdout ?? '').includes(SANDBOX_PROBE_MARKER)) {
+      return {
+        backend: 'none',
+        reason:
+          'sandbox-exec ran but did not enforce the profile: a file outside the mount set was still readable. Hooks run unjailed rather than appearing jailed and not being, which is the one outcome worse than no jail. This is usually an unresolved path in a rule — every path must be realpath()d before it is written.',
+      };
+    }
+
+    return { backend: 'sandbox-exec' };
+  } catch (error) {
+    const spawnFailure = (error as { code?: string } | null)?.code;
+    if (spawnFailure === 'ENOENT') {
+      return {
+        backend: 'none',
+        reason: `${SANDBOX_EXEC} is not on this macOS, so hooks run unjailed. It has carried a deprecation notice since 10.8; if Apple has removed it, this host has no hook jail backend.`,
+      };
+    }
+    return {
+      backend: 'none',
+      reason: `sandbox-exec could not run the probe, so hooks run unjailed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  } finally {
+    if (scratch) rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
 /**
  * Turn the probe's failure into something an operator can act on.
  *
@@ -467,21 +608,35 @@ export function planJailedSpawn(
   }
 
   // A tmpfs needs no source — bubblewrap creates it — so it is never dropped.
-  // @psbanka-agent note (ce-29z, 2026-09): with SANDBOX_EXEC_AUTO_JAIL_ENABLED
-  // still false, the only way to reach this line with a sandbox-exec
-  // availability is policy 'required', and task 4.8 owns the spawn arm that
-  // makes that real. Until it lands, do not flip the flag.
+  // The note below (ce-29z, 2026-09) is why 'required' is the only policy that
+  // reaches the sandbox-exec arm while SANDBOX_EXEC_AUTO_JAIL_ENABLED is
+  // false: the flag flip is D14's landing, never 4.8's.
   const present = set.entries.filter((e) => e.mode === 'tmpfs' || exists(e.path));
   const skipped = set.entries.filter((e) => !present.includes(e)).map((e) => e.path);
+  const applied: MountSet = { ...set, entries: present };
+
+  // Dropping an absent path is a bubblewrap NEED — it fails the whole jail on a
+  // bind with no source — and is merely tidy for `sandbox-exec`, which happily
+  // names a path that is not there. Both backends drop the same rows anyway,
+  // because a mount set that means two things on two platforms is exactly the
+  // drift task 4.7 exists to prevent.
+  if (availability.backend === 'sandbox-exec') {
+    // `-p` rather than a profile FILE: nothing to create, nothing to clean
+    // up, and nothing whose own readability has to be reasoned about.
+    // `sandbox-exec` reads the profile before it applies the sandbox, so a
+    // file would not have needed to be in the mount set — but it would have
+    // needed a lifetime, and this has none.
+    return {
+      cmd: [SANDBOX_EXEC, '-p', toSandboxProfile(applied), '--', ...cmd],
+      mode: 'jailed',
+      backend: availability.backend,
+      skipped,
+      cwd: set.chdir,
+    };
+  }
 
   return {
-    cmd: [
-      BWRAP,
-      ...JAIL_NAMESPACE_ARGS,
-      ...toBwrapArgs({ ...set, entries: present }),
-      '--',
-      ...cmd,
-    ],
+    cmd: [BWRAP, ...JAIL_NAMESPACE_ARGS, ...toBwrapArgs(applied), '--', ...cmd],
     mode: 'jailed',
     backend: availability.backend,
     skipped,

package/src/hooks/mount-set.test.ts

@@ -8,7 +8,13 @@
 
 import { describe, expect, test } from 'bun:test';
 import { BROWSER_ROOT } from '@celilo/capabilities';
-import { deriveMountSet, forbiddenPaths, isForbidden, toBwrapArgs } from './mount-set';
+import {
+  deriveMountSet,
+  forbiddenPaths,
+  isForbidden,
+  toBwrapArgs,
+  toSandboxProfile,
+} from './mount-set';
 
 const BASE = {
   modulePath: '/var/celilo/modules/caddy',
@@ -168,3 +174,84 @@ describe('the fleet browser is reachable, and only read-only (task 4.10)', () =>
     expect(pathsOf(BASE)).not.toContain('/var/lib/celilo');
   });
 });
+
+describe('the sandbox-exec profile renders the same set (task 4.8)', () => {
+  const profileOf = (r: Parameters<typeof deriveMountSet>[0] = BASE) =>
+    toSandboxProfile(deriveMountSet(r));
+
+  test('a read-only mount is denied write and allowed read, in that order', () => {
+    const lines = profileOf().split('\n');
+    const deny = lines.indexOf(`(deny file-write* (subpath "${BASE.modulePath}"))`);
+    const allow = lines.indexOf(`(allow file-read* (subpath "${BASE.modulePath}"))`);
+    expect(deny).toBeGreaterThan(-1);
+    // SBPL is last-match-wins, so the deny must come FIRST or it would revoke
+    // the read it is paired with.
+    expect(allow).toBeGreaterThan(deny);
+  });
+
+  test('a writable directory nested in the read-only tree comes after it', () => {
+    const lines = profileOf().split('\n');
+    expect(
+      lines.indexOf(`(allow file-read* file-write* (subpath "${BASE.stateDir}"))`),
+    ).toBeGreaterThan(lines.indexOf(`(allow file-read* (subpath "${BASE.modulePath}"))`));
+  });
+
+  test('the tmpfs row grants nothing: macOS has no tmpfs and deny-default covers it', () => {
+    // The row still appears, as a comment, so a reader of the profile can see
+    // that the derivation asked for something this backend cannot give.
+    const profile = profileOf();
+    expect(profile).toContain('; /tmp: no tmpfs backend');
+    expect(profile).not.toContain('(subpath "/tmp")');
+  });
+
+  test('every ancestor is a literal, never a subpath', () => {
+    // A `subpath` grant on an ancestor would expose everything beneath it —
+    // `/var/celilo` holds master.key. `literal` permits stat and readdir of the
+    // directory node alone. This is the difference between D9's acceptance
+    // criterion holding and not.
+    const profile = profileOf();
+    expect(profile).toContain('(allow file-read* (literal "/var/celilo"))');
+    expect(profile).not.toContain('(allow file-read* (subpath "/var/celilo"))');
+    expect(profile).not.toContain('(subpath "/"))');
+  });
+
+  test('a forbidden path never reaches the profile', () => {
+    const profile = profileOf({
+      ...BASE,
+      pathInputs: [{ name: 'evil', value: '/usr/bin/bwrap', access: 'write' as const }],
+    });
+    expect(profile).not.toContain('(subpath "/usr/bin/bwrap")');
+  });
+
+  test('a quote in a path cannot end the rule early', () => {
+    const profile = profileOf({ ...BASE, modulePath: '/var/celilo/modules/od"d' });
+    expect(profile).toContain('(subpath "/var/celilo/modules/od\\"d")');
+  });
+
+  test('the network is allowed, because D9 does not namespace it', () => {
+    expect(profileOf()).toContain('(allow network*)');
+  });
+});
+
+describe('name resolution inside the jail (celilo#1225)', () => {
+  test('the resolver config is bound read-only', () => {
+    // Without these a hook resolves no NAME. getaddrinfo finds no nameserver
+    // and the call dies as ETIMEOUT, which reads as the remote endpoint being
+    // down. Measured on namecheap's validate_config against an endpoint that
+    // was up.
+    const set = deriveMountSet(BASE);
+    for (const path of ['/etc/resolv.conf', '/etc/nsswitch.conf', '/etc/hosts']) {
+      const row = set.entries.find((e) => e.path === path);
+      expect(row).toBeDefined();
+      expect(row?.mode).toBe('ro');
+    }
+  });
+
+  test('binding the resolver does not bind the rest of /etc', () => {
+    // The acceptance criterion for this jail is absence. Naming three files
+    // must not become naming a directory.
+    const set = deriveMountSet(BASE);
+    expect(set.entries.some((e) => e.path === '/etc')).toBe(false);
+    expect(set.entries.some((e) => e.path === '/etc/shadow')).toBe(false);
+  });
+});

package/src/hooks/mount-set.ts

@@ -110,6 +110,29 @@ export interface MountSetRequest {
 /** Directories whose contents the runtime needs in order to start at all. */
 const RUNTIME_SUPPORT_DIRS = ['/usr/lib', '/lib', '/lib64', '/etc/ssl'] as const;
 
+/**
+ * What resolving a hostname needs. Read-only, and absent ones are dropped.
+ *
+ * Without these a jailed hook cannot resolve a NAME. `getaddrinfo` finds no
+ * nameserver, falls back to a loopback that answers nothing, and the call dies
+ * as `ETIMEOUT` — which reads as the remote endpoint being down rather than as
+ * the jail having no resolver. Measured on `namecheap`'s `validate_config`:
+ * `getaddrinfo ETIMEOUT dynamicdns.park-your-domain.com`, against an endpoint
+ * that was up and one the e2e topology answers for.
+ *
+ * This is not a widening of what a hook may reach. Design D12 already records
+ * as a residual that "a hook can still `fetch()` any HTTP endpoint directly;
+ * only `probeHttp` consults the target check" — so the network is already
+ * open, and a hook could always dial a literal IP. Withholding the resolver
+ * config did not close that door; it only made the door work for addresses and
+ * not for names, which is an accident rather than a policy.
+ *
+ * It sits beside `/etc/ssl` for the same reason that does: an outbound call
+ * needs a trust store AND a way to turn a name into an address, and binding
+ * one without the other leaves half a capability.
+ */
+const RESOLVER_FILES = ['/etc/resolv.conf', '/etc/nsswitch.conf', '/etc/hosts'] as const;
+
 /**
  * Paths that must NEVER appear in a mount set, whatever asks for them.
  *
@@ -172,6 +195,9 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   for (const dir of RUNTIME_SUPPORT_DIRS) {
     entries.push(entry(dir, 'ro', 'shared libraries and trust store'));
   }
+  for (const file of RESOLVER_FILES) {
+    entries.push(entry(file, 'ro', 'name resolution — see RESOLVER_FILES'));
+  }
   // The fleet browser, read-only (task 4.10).
   //
   // `BROWSER_ROOT` rather than `~/.cache/ms-playwright`, which is what task 4.10
@@ -270,3 +296,132 @@ export function toBwrapArgs(set: MountSet): string[] {
   args.push('--chdir', set.chdir);
   return args;
 }
+
+/**
+ * Render a mount set as a `sandbox-exec` profile, in order (task 4.8).
+ *
+ * The SECOND renderer of the same derivation, alongside `toBwrapArgs`. That is
+ * the property task 4.7 asks for and the reason both live here: one
+ * computation, several consumers, so a macOS jail and a Linux jail cannot come
+ * to different conclusions about what a hook may see.
+ *
+ * **Order is semantic here for the same reason it is in `toBwrapArgs`, by a
+ * different mechanism.** SBPL is last-match-wins, so a read-write directory
+ * nested inside a read-only tree works exactly as bubblewrap's later-`--bind`-
+ * wins does. Measured 2026-08-27: with `state/` emitted after the module tree,
+ * a write to the tree gives `EPERM` and a write to `state/` succeeds.
+ *
+ * Three rules are not derived from the mount set, and each is a parity
+ * statement rather than a convenience:
+ *
+ *   - `(import bsd.sb)` supplies what any process needs to start at all —
+ *     the dyld shared cache, `file-read-metadata` for symlink traversal, the
+ *     `logd`/`cfprefsd` lookups. Without it `bun` dies before `main` with no
+ *     diagnostic (`SIGABRT`, no stderr, because stderr is denied too).
+ *   - `(allow process*)` matches bubblewrap, which does not restrict `exec`
+ *     either. A hook can run whatever it can READ, and what it can read is the
+ *     mount set. Withholding the path is the boundary in both backends.
+ *   - `(allow network*)` is D9: the network is not namespaced. D12 scopes
+ *     reachability by withholding the credential, never by filtering packets.
+ *
+ * Everything else this profile does NOT say is deliberate. `/etc` is absent
+ * because it is absent from D9's table, so on macOS a hook that resolves a
+ * hostname is not stopped by THIS profile: `(allow network*)` lets it reach
+ * the system resolver, which answers out of process in mDNSResponder
+ * (measured 2026-08-30, task 4.13's suite). Withholding `/etc/resolv.conf`
+ * does withhold resolution on Linux, where the file is the resolver's
+ * configuration. Adding `/etc` here alone is the drift task 4.7 exists to
+ * prevent.
+ *
+ * @param set - Paths already resolved through `realpath`. Not optional: a rule
+ *   naming an unresolved path does not match, and the failure is silent in
+ *   both directions (D8). Measured: with the module tree named as `/tmp/…`
+ *   rather than `/private/tmp/…` the rule does not apply, and bun cannot read
+ *   the cwd it was handed.
+ */
+export function toSandboxProfile(set: MountSet): string {
+  const lines = [
+    '(version 1)',
+    '(import "/System/Library/Sandbox/Profiles/bsd.sb")',
+    '(deny default)',
+    '(allow process*)',
+    '(allow network*)',
+  ];
+
+  // Every ANCESTOR of every mount, as a directory node and nothing more.
+  //
+  // This row has no bubblewrap counterpart and that is exactly why it exists.
+  // bubblewrap builds a new filesystem: to bind `/a/b/c` it must CREATE `/a/b`
+  // inside the namespace, so the parents come for free. `sandbox-exec` filters
+  // the tree that is already there and grants nothing implicitly, so every
+  // parent stays denied.
+  //
+  // What breaks is module resolution, and it breaks in a way that names none of
+  // this. Bun resolves a bare import by walking UP from the importing file
+  // testing each `<ancestor>/node_modules`. The shim's own `node_modules` is
+  // bound, but the directories BETWEEN are not, so the walk dies early, bun
+  // falls back to auto-install, and it tries to create `node_modules` in the
+  // read-only module tree. The message is `bun is unable to write files:
+  // PermissionDenied` — a write error for what is really a read denial three
+  // steps earlier. Measured 2026-08-27 by A/B on one variable: with a writable
+  // working directory the shim starts, with a read-only one it does not.
+  //
+  // `literal`, never `subpath`. A literal grant on a directory permits `stat`
+  // and `readdir` of that directory ALONE and confers nothing on the files in
+  // it. So `/var/celilo` becomes listable, which reveals that a file named
+  // `master.key` exists, and reading its bytes stays denied. That is the
+  // difference between D9's criterion holding and not, so do not "simplify"
+  // this to a subpath.
+  for (const path of ancestorsOf(set.entries)) {
+    lines.push(`(allow file-read* (literal ${sbplString(path)}))`);
+  }
+
+  for (const e of set.entries) {
+    // No tmpfs on macOS, and none is needed: `deny default` already makes the
+    // path unreadable, which is the privacy half of the row. The usability
+    // half — a working scratch directory — is what macOS does not get, so a
+    // hook writing to /tmp gets EPERM here and a discarded success on Linux.
+    // Louder than Linux rather than weaker, and named so nobody has to guess.
+    if (e.mode === 'tmpfs') {
+      lines.push(`; ${e.path}: no tmpfs backend; denied by default (${e.reason})`);
+      continue;
+    }
+    lines.push(`; ${e.reason}`);
+    if (e.mode === 'rw') {
+      lines.push(`(allow file-read* file-write* (subpath ${sbplString(e.path)}))`);
+      continue;
+    }
+    // The explicit deny makes `ro` mean read-only whatever preceded it, rather
+    // than relying on nothing earlier having granted write to a parent. That
+    // is true of today's derivation order and is not a property anyone should
+    // have to re-verify after editing it.
+    lines.push(`(deny file-write* (subpath ${sbplString(e.path)}))`);
+    lines.push(`(allow file-read* (subpath ${sbplString(e.path)}))`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Every directory strictly above one of these mounts, nearest-first order
+ * irrelevant, deduplicated. Excludes the mount paths themselves, which carry
+ * their own rules.
+ */
+function ancestorsOf(entries: readonly MountEntry[]): string[] {
+  const own = new Set(entries.map((e) => e.path));
+  const found = new Set<string>();
+  for (const e of entries) {
+    let dir = dirname(e.path);
+    while (dir !== dirname(dir)) {
+      if (!own.has(dir)) found.add(dir);
+      dir = dirname(dir);
+    }
+    found.add('/');
+  }
+  return [...found];
+}
+
+/** A path as an SBPL string literal. */
+function sbplString(path: string): string {
+  return `"${path.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}

package/src/hooks/unjailed-lint.test.ts

@@ -188,7 +188,10 @@ describe('the lint inside a real hook run', () => {
       export default defineHook({
         requires: [] as const,
         handler: async () => {
-          try { readFileSync('/etc/hosts', 'utf-8'); } catch { /* the read is the point, not the bytes */ }
+          // A path outside the mount set. Not /etc/hosts — the resolver
+          // binding (celilo#1225) mounts that read-only on purpose, and the
+          // lint is right to stay silent about it.
+          try { readFileSync('/etc/passwd', 'utf-8'); } catch { /* the read is the point, not the bytes */ }
           return {};
         },
       });
@@ -196,7 +199,7 @@ describe('the lint inside a real hook run', () => {
 
     const warnings = advisories(messages);
     expect(warnings.length).toBe(1);
-    expect(warnings[0]).toContain('/etc/hosts');
+    expect(warnings[0]).toContain('/etc/passwd');
     expect(warnings[0]).toContain('on a jailed host');
     // The one sentence the task forbids losing: what it is, and what it is not.
     expect(warnings[0]).toContain('Advisory lint, not a security boundary');

package/src/services/alerting/coverage-source.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Health-coverage's view of the control plane (celilo#1225).
+ *
+ * `celilo-mgmt` declares no `health_check` hook, and that is deliberate: celilo
+ * runs `runFleetChecks` for it directly, which asks eight questions where the
+ * hook asked two. The hook was deleted because it could not answer them from
+ * inside the jail — it reported a present database missing and failed the
+ * deploy.
+ *
+ * Without the carve-out here, the module best observed by celilo would be the
+ * one celilo warns is unobservable. That warning would be both false and
+ * unfixable, since the fix it names — add a health_check hook — is the thing
+ * that was removed on purpose.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { DbClient } from '../../db/client';
+import { modules } from '../../db/schema';
+import { setupTestDatabaseAt } from '../../test-utils/database';
+import { CONTROL_PLANE_MODULE_ID } from '../deployed-systems';
+import { loadModuleCoverage } from './coverage-source';
+import { healthCoverageFailingKeys } from './health-coverage';
+
+describe('health coverage and the control plane', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'cov-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabaseAt(dbPath);
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function installModule(id: string, manifestData: Record<string, unknown>): void {
+    db.insert(modules)
+      .values({
+        id,
+        name: id,
+        version: '1.0.0',
+        state: 'INSTALLED',
+        sourcePath: `/modules/${id}`,
+        manifestData,
+      })
+      .run();
+  }
+
+  test('the control plane counts as verifiable despite declaring no hook', () => {
+    installModule(CONTROL_PLANE_MODULE_ID, { id: CONTROL_PLANE_MODULE_ID, hooks: {} });
+
+    const coverage = loadModuleCoverage(db);
+    const controlPlane = coverage.find((m) => m.id === CONTROL_PLANE_MODULE_ID);
+
+    expect(controlPlane?.hasHealthCheckHook).toBe(true);
+    // The finding that must NOT be raised — the one whose remedy is to add
+    // back the hook this change deleted.
+    const failing = healthCoverageFailingKeys(coverage);
+    const neverVerified = failing.filter((f) => f.message.includes('can never be verified'));
+    expect(neverVerified).toHaveLength(0);
+  });
+
+  test('an ordinary module with no hook is still reported unobservable', () => {
+    // The carve-out is for the control plane alone. If it leaked to every
+    // module, the check would stop finding anything and look healthy.
+    installModule('homebridge', { id: 'homebridge', hooks: {} });
+
+    const failing = healthCoverageFailingKeys(loadModuleCoverage(db));
+    const messages = failing.map((f) => f.message);
+    expect(
+      messages.some((m) => m.includes('homebridge') && m.includes('can never be verified')),
+    ).toBe(true);
+  });
+});

package/src/services/alerting/coverage-source.ts

@@ -9,6 +9,7 @@
 import type { DbClient } from '../../db/client';
 import { modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
+import { CONTROL_PLANE_MODULE_ID } from '../deployed-systems';
 import { loadModuleHealthCadences } from './health-cadence';
 import type { ModuleCoverageInput } from './health-coverage';
 
@@ -28,7 +29,16 @@ export function loadModuleCoverage(db: DbClient): ModuleCoverageInput[] {
       return {
         id: module.id,
         state: module.state,
-        hasHealthCheckHook: Boolean(manifest.hooks?.health_check),
+        // The control plane is verifiable without declaring a hook, and that
+        // is the point rather than an exemption: celilo runs `runFleetChecks`
+        // for it directly (`controlPlaneHealthChecks`), which asks eight
+        // questions where its old hook asked two. The hook was deleted because
+        // it could not answer them from inside the jail — it reported a
+        // present database missing (celilo#1225). Reading only the manifest
+        // here would raise a coverage warning about the best-observed module
+        // in the fleet.
+        hasHealthCheckHook:
+          Boolean(manifest.hooks?.health_check) || module.id === CONTROL_PLANE_MODULE_ID,
         cadence: cadences.get(module.id)?.cadence ?? null,
       };
     });