@celilo/cli 1.14.0 → 2.0.0

package/src/hooks/unjailed-lint.ts

@@ -0,0 +1,395 @@
+/**
+ * The unjailed advisory lint (hook-process-boundary task 4.7, design D8).
+ *
+ * On a host with no jail backend the hook runs with ambient filesystem
+ * access, so a hook that reads outside its tree works on that host and fails
+ * on the fleet — a divergence otherwise found in production one deploy at a
+ * time. This file closes the gap by making the runner shim check each
+ * filesystem access against the SAME mount set the jail would have enforced.
+ * It is the derivation's second consumer, which is the point: one computation
+ * and two consumers cannot drift the way a consumer and a hand-maintained
+ * list can.
+ *
+ * **This is a lint, not a security boundary, and neither the code nor its
+ * output may describe it as one.** It observes `node:fs` calls from inside
+ * the hook's own process, and module code bypasses it trivially — a `Bun.file`
+ * call, a `dlopen`, or a subprocess never crosses a wrapper. What it claims,
+ * and all it claims, is: on a jailed host, this access would have failed.
+ *
+ * **Channel.** The mount set arrives in the child's environment
+ * (`HOOK_MOUNT_SET_ENV`), set only when the run is unjailed — presence is the
+ * signal to install, so a jailed run carries nothing and installs nothing.
+ *
+ * **WHY THIS MODULE SELF-INSTALLS AT EVALUATION, AND WHY IT MUST STAY A
+ * LEAF.** Measured on Bun 1.3: the first ESM import of `node:fs` anywhere in
+ * a process resolves the builtin's named exports and never revisits them, so
+ * a wrapper planted on `require('node:fs')` AFTER that first import is
+ * invisible to every later `import { readFileSync } from 'node:fs'`. The
+ * shim's other imports (`jail.ts`, `@celilo/capabilities`) ESM-import
+ * `node:fs`, so the wrappers must be in place before any of them load. Hence
+ * `hook-runner-entry.ts`: the executor spawns IT, its first statement forces
+ * this module's evaluation and the install, and only then does the real
+ * runner load. Import order inside the runner is therefore irrelevant — but
+ * this module still imports nothing but `node:path`, `zod` (through
+ * `hook-protocol.ts`, which pulls no other builtins), and type-only imports,
+ * because the entry's guarantee is only as good as this file's graph is
+ * shallow. Importing `jail.ts` from here would silently disarm the lint; the
+ * integration tests in `unjailed-lint.test.ts` go red if that happens (they
+ * did, while this was being landed).
+ *
+ * The self-install is guarded on the runner shim's own environment variable,
+ * so a parent celilo process that imports this module for
+ * `mountSetEnvValue` never wraps its own filesystem.
+ */
+
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+import {
+  HOOK_MOUNT_SET_ENV,
+  HOOK_SOCKET_ENV,
+  type MountSetWire,
+  MountSetWireSchema,
+} from './hook-protocol';
+import type { MountSet } from './mount-set';
+
+/**
+ * The two paths the jail's namespace itself provides — bubblewrap's
+ * `--proc /proc` and `--dev /dev` (`jail.ts`'s JAIL_NAMESPACE_ARGS is built
+ * from this constant, so the two cannot drift) — rather than derivation
+ * rows. Counting them absent would be a false warning on every hook that
+ * touched either.
+ */
+export const JAIL_PROVIDED_PATHS = ['/proc', '/dev'] as const;
+
+/**
+ * `realpathSync` captured at module load, before the wrappers go in.
+ * `classifyAccess` runs from INSIDE a wrapped call (a wrapper reports, report
+ * classifies), so reaching for the module property here would re-enter the
+ * wrapper and classify forever.
+ */
+const PRISTINE_REALPATH = (require('node:fs') as typeof import('node:fs')).realpathSync;
+
+/** The verdict for one access, against one mount set. */
+export type AccessVerdict = 'allowed' | 'absent' | 'read-only';
+
+/**
+ * Distinct paths warned about before the lint stops listing and summarises.
+ * A hook walking a directory outside the set would otherwise emit one line
+ * per file; after this many distinct paths the reader has the point.
+ */
+const WARN_CAP = 25;
+
+/**
+ * Serialise a derived mount set for `HOOK_MOUNT_SET_ENV`.
+ *
+ * The executor calls this with the set it just derived; `parseLintMountSet`
+ * is the only thing on the reading side.
+ */
+export function mountSetEnvValue(set: MountSet): string {
+  return JSON.stringify(set);
+}
+
+/**
+ * Read and validate the mount set out of the child's environment.
+ *
+ * `undefined` when the variable is absent — the jailed case, and every
+ * invocation with no module tree. A value that fails validation is reported
+ * to stderr (the executor forwards it through the logger) and the run
+ * proceeds WITHOUT the lint rather than failing the hook over a diagnostic:
+ * the lint must never be the reason a deploy breaks. A silent skip would be
+ * the one thing worse than that, hence the stderr line.
+ */
+export function parseLintMountSet(value: string | undefined): MountSetWire | undefined {
+  if (value === undefined || value === '') return undefined;
+  let json: unknown;
+  try {
+    json = JSON.parse(value);
+  } catch (error) {
+    process.stderr.write(
+      `hook runner: ${HOOK_MOUNT_SET_ENV} is not valid JSON (${error instanceof Error ? error.message : String(error)}); the unjailed advisory lint is off this run.\n`,
+    );
+    return undefined;
+  }
+  const parsed = MountSetWireSchema.safeParse(json);
+  if (parsed.success) return parsed.data;
+  process.stderr.write(
+    `hook runner: ${HOOK_MOUNT_SET_ENV} failed validation; the unjailed advisory lint is off this run.\n`,
+  );
+  return undefined;
+}
+
+/**
+ * Warnings emitted before the hook's logger exists are buffered here and
+ * flushed by `forwardLintWarnings`. In practice there are none — the shim
+ * does no filesystem work between load and hook start — but the lint must
+ * never assume that.
+ */
+const buffered: string[] = [];
+let emit: ((message: string) => void) | undefined;
+let installed = false;
+
+/**
+ * Install the wrappers now, if this process is an unjailed hook runner.
+ *
+ * Idempotent, and called from TWO places by design: this module's own
+ * evaluation, and `hook-runner-entry.ts`'s first statement. Which one lands
+ * first depends on Bun's import evaluation order, which is not a thing to
+ * reason about twice — the guard makes both orders correct, and the entry
+ * makes one of them certain before any other module in the child process can
+ * ESM-load `node:fs` (see the docblock at the top). No-op everywhere else: no
+ * runner socket in the environment means this is not a hook runner process.
+ */
+export function installUnjailedLintIfUnjailed(): void {
+  if (installed) return;
+  if (process.env[HOOK_SOCKET_ENV] === undefined) return;
+  const set = parseLintMountSet(process.env[HOOK_MOUNT_SET_ENV]);
+  if (!set) return;
+  installed = true;
+  install(set, (message) => (emit ? emit(message) : buffered.push(message)));
+}
+
+/**
+ * Hand the lint's output to the hook's logger, draining anything buffered.
+ * Call once the shim's logger exists, before the hook script is imported.
+ */
+export function forwardLintWarnings(to: (message: string) => void): void {
+  emit = to;
+  for (const message of buffered.splice(0)) to(message);
+}
+
+/**
+ * Classify one access against the mount set.
+ *
+ * Last matching row wins, in `entries` order — that is bubblewrap's own rule
+ * (`--ro-bind` then a later `--bind` overrides), and the derivation emits its
+ * rows in exactly that order. A path under no row is absent, which is what
+ * the jail actually produces (mount-set.ts: not "denied", ABSENT).
+ *
+ * Relative paths resolve against `set.chdir`, because that is the working
+ * directory the jailed hook runs in (`--chdir`, task 4.2i) — the child's real
+ * cwd is celilo's, which is a directory the jail does not contain.
+ */
+export function classifyAccess(set: MountSetWire, path: string, write: boolean): AccessVerdict {
+  const absolute = isAbsolute(path) ? path : resolve(set.chdir, path);
+  const candidates = realpathCandidates(absolute);
+  let verdict: AccessVerdict = 'absent';
+  for (const candidate of candidates) {
+    verdict = strongest(verdict, classifyOne(set, candidate, write));
+  }
+  return verdict;
+}
+
+/**
+ * The lexical path plus, when it can be resolved, its realpath.
+ *
+ * The mount set the lint compares against is the REALPATHED one
+ * (`realpathRequest`, task 4.2k — the jail binds real paths). A dev checkout
+ * on macOS reaches the hook through symlinked prefixes (`/tmp` →
+ * `/private/tmp`, `/var` → `/private/var`), so a hook writing the path celilo
+ * handed it and the same path as bound can disagree lexically. The lint
+ * accepts either form as "inside": the lint runs only where there is no jail
+ * to match byte-for-byte, and the alternative is a warning on every state
+ * write on a Mac.
+ *
+ * The realpath of the FULL path usually does not exist — the check fires
+ * before a create, and `realpathSync` fails on the file being created. So
+ * this resolves the longest existing ancestor and reattaches whatever is
+ * left: for `<state>/cursor`, where only `<state>` exists, the second
+ * candidate is the realpath of `<state>` plus `/cursor`.
+ */
+function realpathCandidates(path: string): string[] {
+  const candidates = [path];
+  let suffix = '';
+  let current = path;
+  for (;;) {
+    try {
+      const real = PRISTINE_REALPATH(current) + suffix;
+      if (!candidates.includes(real)) candidates.push(real);
+      return candidates;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return candidates;
+      suffix = `/${basename(current)}${suffix}`;
+      current = parent;
+    }
+  }
+}
+
+function classifyOne(set: MountSetWire, absolute: string, write: boolean): AccessVerdict {
+  let verdict: AccessVerdict = 'absent';
+  for (const entry of set.entries) {
+    if (!covers(entry.path, absolute)) continue;
+    verdict = entry.mode === 'ro' && write ? 'read-only' : 'allowed';
+  }
+  for (const provided of JAIL_PROVIDED_PATHS) {
+    if (covers(provided, absolute)) verdict = 'allowed';
+  }
+  return verdict;
+}
+
+function covers(root: string, path: string): boolean {
+  const prefix = root.endsWith('/') ? root : `${root}/`;
+  return path === root || path.startsWith(prefix);
+}
+
+/** The more informative of two verdicts, for the realpath candidate pair. */
+function strongest(a: AccessVerdict, b: AccessVerdict): AccessVerdict {
+  if (a === 'allowed' || b === 'allowed') return 'allowed';
+  if (a === 'read-only' || b === 'read-only') return 'read-only';
+  return 'absent';
+}
+
+/**
+ * Wrap every path-taking function this file knows about on both `node:fs`
+ * and `node:fs/promises`. The wrap fires BEFORE the underlying call, so it
+ * observes attempts — including attempts that succeed locally only because
+ * there is no jail, which is exactly the divergence it exists to surface.
+ *
+ * Warnings dedupe per (verdict, path) and are capped at WARN_CAP distinct
+ * paths, with one notice when the cap bites.
+ */
+function install(set: MountSetWire, warn: (message: string) => void): void {
+  const warned = new Set<string>();
+  let suppressed = 0;
+
+  const report = (rawPath: string, write: boolean): void => {
+    if (typeof rawPath !== 'string' || rawPath === '') return;
+    const absolute = isAbsolute(rawPath) ? rawPath : resolve(set.chdir, rawPath);
+    const verdict = classifyAccess(set, absolute, write);
+    if (verdict === 'allowed') return;
+    const key = `${verdict}:${absolute}`;
+    if (warned.has(key)) return;
+    if (warned.size >= WARN_CAP) {
+      suppressed += 1;
+      if (suppressed === 1) {
+        warn(
+          `Hook advisory: further path(s) outside the hook's mount set will be suppressed after ${WARN_CAP}.`,
+        );
+      }
+      return;
+    }
+    warned.add(key);
+    warn(advisoryMessage(verdict, absolute));
+  };
+
+  for (const moduleId of ['node:fs', 'node:fs/promises'] as const) {
+    const mod = require(moduleId) as Record<string, unknown>;
+    for (const [name, pathArgsFor] of Object.entries(PATH_ARGS)) {
+      const original = mod[name];
+      if (typeof original !== 'function') continue;
+      mod[name] = function (this: unknown, ...call: unknown[]) {
+        const pathArgs = typeof pathArgsFor === 'function' ? pathArgsFor(call) : pathArgsFor;
+        for (const [index, write] of pathArgs) {
+          const value = call[index];
+          if (typeof value === 'string') report(value, write);
+          else if (value instanceof URL && value.protocol === 'file:') {
+            report(value.pathname, write);
+          }
+        }
+        return (original as (...args: unknown[]) => unknown).apply(this, call);
+      };
+    }
+  }
+}
+
+function advisoryMessage(verdict: AccessVerdict, path: string): string {
+  if (verdict === 'read-only') {
+    return [
+      `Hook advisory: '${path}' is read-only in the hook's mount set,`,
+      'so on a jailed host this write would fail.',
+      'Advisory lint, not a security boundary; module code bypasses it trivially.',
+    ].join(' ');
+  }
+  return [
+    `Hook advisory: '${path}' is outside the hook's mount set,`,
+    'so on a jailed host this access would fail (the path is absent there, ENOENT).',
+    'Advisory lint, not a security boundary; module code bypasses it trivially.',
+  ].join(' ');
+}
+
+/**
+ * Which arguments of which functions carry a path, and whether the access is
+ * a write. Read and write variants share the table; a name missing from a
+ * given module is simply skipped, so one table covers `node:fs`, its `Sync`
+ * variants and `node:fs/promises`.
+ *
+ * Deliberately a table of the common calls rather than an exhaustive census:
+ * a function missed here is a warning not emitted, never a behaviour change.
+ * The lint is advisory and module code bypasses it trivially (design D8);
+ * exhaustive coverage would buy a boundary-shaped guarantee it cannot keep.
+ */
+const READ0: readonly (readonly [number, boolean])[] = [[0, false]];
+const WRITE0: readonly (readonly [number, boolean])[] = [[0, true]];
+const TWO_PATH: readonly (readonly [number, boolean])[] = [
+  [0, false],
+  [1, true],
+];
+
+const PATH_ARGS: Record<
+  string,
+  | readonly (readonly [number, boolean])[]
+  | ((call: unknown[]) => readonly (readonly [number, boolean])[])
+> = {
+  // Reads.
+  readFile: READ0,
+  readFileSync: READ0,
+  readdir: READ0,
+  readdirSync: READ0,
+  stat: READ0,
+  statSync: READ0,
+  lstat: READ0,
+  lstatSync: READ0,
+  access: READ0,
+  accessSync: READ0,
+  existsSync: READ0,
+  realpath: READ0,
+  realpathSync: READ0,
+  readlink: READ0,
+  readlinkSync: READ0,
+  createReadStream: READ0,
+  opendir: READ0,
+  opendirSync: READ0,
+  // Writes.
+  writeFile: WRITE0,
+  writeFileSync: WRITE0,
+  appendFile: WRITE0,
+  appendFileSync: WRITE0,
+  mkdir: WRITE0,
+  mkdirSync: WRITE0,
+  mkdtemp: WRITE0,
+  mkdtempSync: WRITE0,
+  rm: WRITE0,
+  rmSync: WRITE0,
+  rmdir: WRITE0,
+  rmdirSync: WRITE0,
+  unlink: WRITE0,
+  unlinkSync: WRITE0,
+  chmod: WRITE0,
+  chmodSync: WRITE0,
+  chown: WRITE0,
+  chownSync: WRITE0,
+  truncate: WRITE0,
+  truncateSync: WRITE0,
+  utimes: WRITE0,
+  utimesSync: WRITE0,
+  createWriteStream: WRITE0,
+  symlink: [[1, true]],
+  // Both ends are paths.
+  rename: TWO_PATH,
+  renameSync: TWO_PATH,
+  copyFile: TWO_PATH,
+  copyFileSync: TWO_PATH,
+  cp: TWO_PATH,
+  cpSync: TWO_PATH,
+  // Flag-dependent: 'r' reads, everything else writes.
+  open: OPEN_FLAGS,
+  openSync: OPEN_FLAGS,
+};
+
+/** `open`'s flags argument decides read from write. */
+function OPEN_FLAGS(call: unknown[]): readonly (readonly [number, boolean])[] {
+  const flags = call[1];
+  const flag = typeof flags === 'string' ? flags : 'r';
+  return [[0, flag !== 'r']];
+}
+
+installUnjailedLintIfUnjailed();

package/src/policy/module-business-baseline.ts

@@ -309,6 +309,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 2,
     why: "S16 — two more copies of S15's decision; fixing S15 removes all three (#938)",
   },
+  {
+    file: 'apps/celilo/src/services/module-deploy.ts',
+    capability: 'public_web',
+    count: 1,
+    why: "D10 (capability-owned-tables stage 4): the public_web PROVIDER's own deploy writes the static-content release set into its generated inventory, so a rebuilt host recovers with no consumer involvement. The branch checks the deploying module's manifest `provides`, not a module name; the capability-loader callback is the other half of the same seam.",
+  },
   {
     file: 'apps/celilo/src/services/zone-policy.ts',
     capability: 'public_web',
@@ -488,7 +494,13 @@ export const PROVIDER_LITERAL_BASELINE: readonly ProviderLiteralRow[] = [
   {
     file: 'packages/capabilities/src/public-web.ts',
     literal: '/srv/www',
-    count: 4,
+    count: 3,
     why: "X8 — the Caddyfile generator knows caddy's on-disk asset layout (#940)",
   },
+  {
+    file: 'apps/celilo/src/services/static-content-converge.ts',
+    literal: '/srv/www',
+    count: 1,
+    why: "D10 (capability-owned-tables stage 4): the converge's slug-collision error names the on-disk release path an operator must fix. The role under modules/caddy owns the real path handling; this is message text, not path logic.",
+  },
 ];

package/src/policy/module-script-scan.ts

@@ -142,7 +142,10 @@ export function scanModuleScriptSource(file: string, source: string): ScanViolat
  * `@celilo/capabilities`, whose `remote.ts` builds the `ssh … root@` string
  * that every one of these rules exists to keep OUT of module code. Scanning it
  * would fail every module in the fleet on the implementation of the primitives
- * they were told to use.
+ * they were told to use. The package itself is NOT exempt —
+ * `scanCapabilityPackageSource` scans it everywhere except those primitive
+ * files (celilo#1014), which is how `public-web.ts`'s hand-built ssh came to
+ * light.
  */
 export function moduleScriptFiles(scriptsDir: string): string[] {
   if (!existsSync(scriptsDir) || !statSync(scriptsDir).isDirectory()) return [];
@@ -173,3 +176,59 @@ export function scanModuleDirectory(moduleDir: string): ScanViolation[] {
 export function formatViolations(violations: ScanViolation[]): string {
   return violations.map((v) => `  ${v.file}:${v.line}\n    → ${v.rule}. ${v.hint}`).join('\n');
 }
+
+/**
+ * The files inside `@celilo/capabilities` that implement the remote-exec
+ * primitives themselves. `remote.ts` is the ONE sanctioned place the
+ * `ssh … root@` string is built (its own header says so), so the narrowed
+ * scan exempts these files and nothing else.
+ *
+ * celilo#1014: the old exemption was the whole package — `moduleScriptFiles`
+ * skipped `node_modules` entirely, on the reasoning that scanning the bundle
+ * would fail every module on `remote.ts`. The whole-package shape also
+ * exempted `public-web.ts`, which was hand-building the same ssh string, and
+ * no gate could see it. Naming the primitive files instead of skipping the
+ * package is the fix for that class.
+ */
+export const REMOTE_PRIMITIVE_FILES: readonly string[] = ['remote.ts'];
+
+/**
+ * The narrowed file set: every production `.ts` in the package source EXCEPT
+ * the primitive-implementation files. Returned separately from the violations
+ * so a gate can prove its own reach — an empty violation list must never be
+ * indistinguishable from "scanned nothing".
+ */
+export function capabilityPackageSourceFiles(srcDir: string): string[] {
+  if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) return [];
+  return readdirSync(srcDir)
+    .filter(
+      (entry) =>
+        entry.endsWith('.ts') &&
+        !entry.endsWith('.test.ts') &&
+        !REMOTE_PRIMITIVE_FILES.includes(entry),
+    )
+    .sort();
+}
+
+/**
+ * Scan the `@celilo/capabilities` source tree under the exemption's narrowed
+ * shape: every production `.ts` EXCEPT the files implementing the primitive.
+ *
+ * Takes the directory rather than finding it, so the same function serves both
+ * copies of the package the fleet actually runs: the workspace source
+ * (`packages/capabilities/src`, where the code is authored) and, once the next
+ * version publishes, each module's bundled copy
+ * (`modules/<m>/scripts/node_modules/@celilo/capabilities/src`). The bundled
+ * copies on a checkout made before that publish still carry the pre-fix code,
+ * so the in-repo gate reads the workspace source until then — scanning a
+ * snapshot no commit in this repo can fix would leave the gate red in exactly
+ * the PR that repairs the defect.
+ */
+export function scanCapabilityPackageSource(srcDir: string): ScanViolation[] {
+  return capabilityPackageSourceFiles(srcDir).flatMap((entry) =>
+    scanModuleScriptSource(
+      join('@celilo/capabilities/src', entry),
+      readFileSync(join(srcDir, entry), 'utf-8'),
+    ),
+  );
+}

package/src/policy/no-hand-built-ssh.test.ts

@@ -14,7 +14,14 @@
 import { describe, expect, test } from 'bun:test';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { formatViolations, moduleScriptFiles, scanModuleDirectory } from './module-script-scan';
+import {
+  REMOTE_PRIMITIVE_FILES,
+  capabilityPackageSourceFiles,
+  formatViolations,
+  moduleScriptFiles,
+  scanCapabilityPackageSource,
+  scanModuleDirectory,
+} from './module-script-scan';
 
 /** Walk up from this test to the repo root (the dir holding both modules/ and apps/). */
 function repoRoot(): string {
@@ -48,3 +55,34 @@ describe('recurrence gate: modules never hand-build SSH', () => {
     );
   });
 });
+
+describe('recurrence gate: @celilo/capabilities itself never hand-builds SSH', () => {
+  // The workspace source — where the package is authored, and the only copy a
+  // commit in this repo can fix. Each module's bundled copy is an npm snapshot
+  // that refreshes on the next publish, so the gate reads the source of truth.
+  const capabilitiesSrc = join(repoRoot(), 'packages', 'capabilities', 'src');
+
+  test('scans the package source except the remote-primitive file, and the exclusion engaged', () => {
+    // Reach probe, not reasoning: the primitive file must exist and be absent
+    // from the scanned set, or the narrowing below is proving nothing.
+    const primitivePresent = REMOTE_PRIMITIVE_FILES.every((f) =>
+      existsSync(join(capabilitiesSrc, f)),
+    );
+    expect(primitivePresent).toBe(true);
+
+    const scannedFiles = capabilityPackageSourceFiles(capabilitiesSrc);
+    for (const primitive of REMOTE_PRIMITIVE_FILES) {
+      expect(scannedFiles).not.toContain(primitive);
+    }
+    expect(scannedFiles.length).toBeGreaterThan(10);
+    expect(scannedFiles).toContain('public-web.ts');
+  });
+
+  test('no file outside the remote-primitive seam hand-builds SSH', () => {
+    const violations = scanCapabilityPackageSource(capabilitiesSrc);
+    expect(
+      violations,
+      `Capability package policy violations:\n${formatViolations(violations)}`,
+    ).toEqual([]);
+  });
+});

package/src/policy/no-module-business-in-core.test.ts

@@ -299,7 +299,7 @@ describe('recurrence gate: celilo core holds no module business — Scan A (tabl
       measured,
       baseline,
       (table, capability) => `table '${table}' is owned by capability '${capability}'`,
-      "A new table modelling one capability's domain belongs in that provider's module_configs\n           (the wireguard-manager D2 precedent), not in core's schema. If core genuinely must\n           hold it, add it to CAPABILITY_OWNED_TABLES with the reason.",
+      "A new table modelling one capability's domain is DECLARED by that capability, beside its\n           interface in packages/capabilities/src/<name>.ts, and registered in\n           CAPABILITY_DECLARED_TABLES (declared-tables.ts). The CREATE TABLE still lives in\n           core's drizzle migrations: a declaration is metadata and a version anchor, not a\n           second way to ship schema. It does NOT go in the provider's module_configs. That\n           destination was superseded on 2026-08-22 and ruled out by peba on 2026-09-01\n           (openspec/changes/capability-owned-tables, ruling 5). If core genuinely must hold\n           the table, add it to CAPABILITY_OWNED_TABLES with the reason.",
     );
     expect(
       problems,

package/src/services/alerting/hook-jail.test.ts

@@ -0,0 +1,66 @@
+/**
+ * D8's three states, asserted one branch at a time: only "used to jail and has
+ * stopped" raises. Steady-state unjailed — a Mac that never jailed — is a
+ * configuration fact the doctor reports, never an alert.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { JailModeRecord } from '../../hooks/jail';
+import { hookJailFailingKeys } from './hook-jail';
+
+const HOST = 'celilo-mgr';
+
+const regressed: JailModeRecord = {
+  mode: 'unjailed',
+  backend: 'none',
+  reason: 'bubblewrap is installed but could not build a namespace, so hooks run unjailed.',
+  host: HOST,
+  recordedAt: '2026-08-28T09:00:00.000Z',
+  lastJailed: { backend: 'bubblewrap', recordedAt: '2026-08-27T09:00:00.000Z' },
+};
+
+describe('hookJailFailingKeys', () => {
+  test('a host that used to jail and has stopped raises, naming the host and the reason', () => {
+    const failing = hookJailFailingKeys({ record: regressed, host: HOST }, 'critical');
+    expect(failing).toHaveLength(1);
+    expect(failing[0]?.key).toBe(`builtin:hook_jail/host:${HOST}`);
+    expect(failing[0]?.severity).toBe('critical');
+    expect(failing[0]?.message).toContain(HOST);
+    expect(failing[0]?.message).toContain('until 2026-08-27T09:00:00.000Z');
+    expect(failing[0]?.message).toContain('could not build a namespace');
+  });
+
+  test('steady-state unjailed is not an event', () => {
+    const neverJailed: JailModeRecord = {
+      mode: 'unjailed',
+      backend: 'none',
+      reason: 'macOS has no hook jail yet',
+      host: HOST,
+      recordedAt: '2026-08-28T09:00:00.000Z',
+    };
+    expect(hookJailFailingKeys({ record: neverJailed, host: HOST }, 'critical')).toEqual([]);
+  });
+
+  test('a jailed host raises nothing, which is also how the alert resolves', () => {
+    const healthy: JailModeRecord = {
+      mode: 'jailed',
+      backend: 'bubblewrap',
+      host: HOST,
+      recordedAt: '2026-08-28T09:00:00.000Z',
+    };
+    expect(hookJailFailingKeys({ record: healthy, host: HOST }, 'critical')).toEqual([]);
+  });
+
+  test('no record yet raises nothing', () => {
+    expect(hookJailFailingKeys({ record: undefined, host: HOST }, 'critical')).toEqual([]);
+  });
+
+  test("a record written by another host is a move, not this host's regression", () => {
+    expect(hookJailFailingKeys({ record: regressed, host: 'a-new-box' }, 'critical')).toEqual([]);
+  });
+
+  test("the monitor's severity is the alert's severity", () => {
+    const failing = hookJailFailingKeys({ record: regressed, host: HOST }, 'warning');
+    expect(failing[0]?.severity).toBe('warning');
+  });
+});