@celilo/cli 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^3.0.0",
+    "@celilo/capabilities": "^3.1.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.9.1",
     "@celilo/event-bus": "^0.6.0",

package/src/hooks/broker.test.ts

@@ -55,6 +55,7 @@ async function runCapabilityHook(): Promise<Record<string, unknown>> {
       logger: createCapturingLogger().logger,
       debug: false,
       screenshotDir: dir,
+      stateDir: dir,
       capabilities: demoCapabilities(),
     };
     return await executeHookScript(

package/src/hooks/define-hook.test.ts

@@ -49,6 +49,7 @@ function makeContext(overrides: Partial<HookContext> = {}): HookContext {
     consumerModuleId: 'test-consumer',
     debug: false,
     screenshotDir: '',
+    stateDir: '',
     capabilities: {},
     ...overrides,
   };

package/src/hooks/executor.test.ts

@@ -118,6 +118,7 @@ describe('Hook Executor', () => {
         logger,
         debug: false,
         screenshotDir: '/tmp',
+        stateDir: '/tmp',
         capabilities: {},
         vps_ip: '10.0.0.1',
       });
@@ -138,6 +139,7 @@ describe('Hook Executor', () => {
           logger,
           debug: false,
           screenshotDir: '/tmp',
+          stateDir: '/tmp',
           capabilities: {},
         }),
       ).rejects.toThrow('Hook script not found');
@@ -155,6 +157,7 @@ describe('Hook Executor', () => {
           logger,
           debug: false,
           screenshotDir: '/tmp',
+          stateDir: '/tmp',
           capabilities: {},
         }),
       ).rejects.toThrow('must export a default function');
@@ -176,6 +179,7 @@ describe('Hook Executor', () => {
           logger,
           debug: false,
           screenshotDir: '/tmp',
+          stateDir: '/tmp',
           capabilities: {},
         }),
       ).rejects.toThrow('does not use defineHook()');
@@ -192,6 +196,7 @@ describe('Hook Executor', () => {
         logger,
         debug: false,
         screenshotDir: '/tmp',
+        stateDir: '/tmp',
         capabilities: {},
       });
 
@@ -210,6 +215,7 @@ describe('Hook Executor', () => {
           logger,
           debug: false,
           screenshotDir: '/tmp',
+          stateDir: '/tmp',
           capabilities: {},
         }),
       ).rejects.toThrow('Hook execution failed: simulated error');
@@ -229,6 +235,7 @@ describe('Hook Executor', () => {
         logger,
         debug: false,
         screenshotDir: '/tmp',
+        stateDir: '/tmp',
         capabilities: {},
       };
 

package/src/hooks/executor.ts

@@ -39,6 +39,7 @@ import {
   type DeployedSystem,
   isMissingProviderInputError,
   moduleArtifactDir,
+  moduleStateDir,
 } from '@celilo/capabilities';
 import {
   type ContractHookSignature,
@@ -628,6 +629,10 @@ export async function invokeHook(
   // below — the capability pre-flight is one — and nothing ever cleans
   // those up, so a module accrues one per affected run forever.
   const screenshotDir = moduleArtifactDir(modulePath, `${hookName}-${startTime}`);
+  // Unlike the artifact directory, this one is NOT per-run and is created
+  // unconditionally: a hook must be able to write state on its first ever run,
+  // and should never have to mkdir its own sanctioned location (celilo#1000).
+  const stateDir = moduleStateDir(modulePath);
 
   // Build context
   const loadedCapabilities = options.capabilities ?? {};
@@ -639,6 +644,7 @@ export async function invokeHook(
     logger,
     debug,
     screenshotDir,
+    stateDir,
     capabilities: loadedCapabilities,
   };
 
@@ -673,6 +679,11 @@ export async function invokeHook(
   // Create the artifact directory only once every early return is behind
   // us, so the `finally` below is guaranteed to run and reclaim it.
   mkdirSync(screenshotDir, { recursive: true });
+  // Created every run and reclaimed on none. An empty `state/` is not litter
+  // the way an empty per-run artifact directory is: there is one of them, it is
+  // where the module is told to write, and deleting it between runs would make
+  // its existence depend on whether the last hook happened to use it.
+  mkdirSync(stateDir, { recursive: true });
   // Prune on write, so retention needs no scheduler of its own and cannot
   // fall behind a module that runs often.
   pruneModuleArtifacts(dirname(screenshotDir));

package/src/hooks/hook-state-dir.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { moduleStateDir } from '@celilo/capabilities';
+import { classifyModulePath } from '../module/packaging/package-rules';
+import { invokeHook } from './executor';
+import type { HookLogger } from './types';
+
+/**
+ * celilo#1000's FIRST acceptance criterion, which #1091 did not meet:
+ * "a hook has a documented, framework-provided place to write."
+ *
+ * The classification landed without the surface, so `module audit` tolerated
+ * `state/` while a hook had no way to ask where it was. Every assertion below
+ * is about the hook LEARNING the path, never about the path's spelling. A test
+ * that asserts `ctx.stateDir === join(root, 'state')` would pass just as well
+ * with no surface at all, because it computes the answer it is checking.
+ */
+
+const silent: HookLogger = {
+  info() {},
+  warn() {},
+  error() {},
+  success() {},
+};
+
+function scratchModule(script: string): string {
+  const root = mkdtempSync(join(tmpdir(), 'celilo-statedir-'));
+  Bun.write(join(root, 'hook.ts'), script);
+  return root;
+}
+
+describe('celilo#1000: a hook is TOLD where its state directory is', () => {
+  test('the hook receives a usable stateDir it did not construct', async () => {
+    const root = scratchModule(`
+      import { defineHook } from '@celilo/capabilities';
+      import { writeFileSync } from 'node:fs';
+      import { join } from 'node:path';
+      export default defineHook({
+        requires: [] as const,
+        handler: async (ctx) => {
+          // The hook builds NOTHING. It writes where it was told.
+          writeFileSync(join(ctx.stateDir as string, 'cursor'), 'run-1');
+          return { received: ctx.stateDir };
+        },
+      });
+    `);
+    try {
+      const result = await invokeHook(
+        root,
+        'on_install',
+        '1.0',
+        { script: 'hook.ts' },
+        {},
+        {},
+        {},
+        silent,
+      );
+      expect(result.error).toBeUndefined();
+      expect(result.success).toBe(true);
+
+      // The framework's own answer, not this test's guess.
+      const expected = moduleStateDir(root);
+      expect(result.outputs.received).toBe(expected);
+      expect(readFileSync(join(expected, 'cursor'), 'utf-8')).toBe('run-1');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('it exists before the hook runs, on a module that never wrote state', async () => {
+    const root = scratchModule(`
+      import { defineHook } from '@celilo/capabilities';
+      import { existsSync } from 'node:fs';
+      export default defineHook({
+        requires: [] as const,
+        handler: async (ctx) => ({ existed: existsSync(ctx.stateDir as string) }),
+      });
+    `);
+    try {
+      // Nothing has ever written here. A hook must not have to mkdir -p its
+      // own sanctioned location.
+      expect(existsSync(moduleStateDir(root))).toBe(false);
+      const result = await invokeHook(
+        root,
+        'on_install',
+        '1.0',
+        { script: 'hook.ts' },
+        {},
+        {},
+        {},
+        silent,
+      );
+      expect(result.outputs.existed).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('what the hook was told to use is what the audit tolerates', () => {
+    // The two halves of celilo#1000 agree by construction rather than by
+    // someone remembering to keep them in step.
+    const root = '/tmp/some-module';
+    const told = moduleStateDir(root);
+    const relative = told.slice(root.length + 1);
+    expect(classifyModulePath(`${relative}/anything.db`)).toBe('derived');
+  });
+});

package/src/hooks/hook-timeout.test.ts

@@ -46,6 +46,7 @@ function contextFor(config: Record<string, unknown>): HookContext {
     logger: createCapturingLogger().logger,
     debug: false,
     screenshotDir: scratch(),
+    stateDir: scratch(),
     capabilities: {},
   };
 }

package/src/hooks/hook-trespass.test.ts

@@ -117,6 +117,7 @@ async function runTrespass(): Promise<{ report: TrespassReport; lines: string[]
     logger,
     debug: false,
     screenshotDir: mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-')),
+    stateDir: mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-')),
     capabilities: {},
   };
 

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

@@ -0,0 +1,148 @@
+/**
+ * Hermetic guards on the hook jail's mount set (design D9).
+ *
+ * `deriveMountSet` is pure, so every property D9 asserts is checkable here
+ * without spawning anything. The two that matter most are absence properties:
+ * what the jail does NOT contain is the acceptance criterion.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { deriveMountSet, forbiddenPaths, isForbidden, toBwrapArgs } from './mount-set';
+
+const BASE = {
+  modulePath: '/var/celilo/modules/caddy',
+  stateDir: '/var/celilo/modules/caddy/state',
+  socketDir: '/tmp/celilo-hook-a1b2c3',
+  runtimePath: '/usr/local/bin/bun',
+  runnerPath: '/opt/celilo/src/hooks/hook-runner.ts',
+  pathInputs: [],
+};
+
+const pathsOf = (r: Parameters<typeof deriveMountSet>[0]) =>
+  deriveMountSet(r).entries.map((e) => e.path);
+
+describe('bwrap is never in the mount set', () => {
+  // The AppArmor profile grants userns to /usr/bin/bwrap for anyone on the
+  // box. A jailed hook that could exec it would be uid 0 with CAP_SYS_ADMIN in
+  // its own namespace. bwrap runs OUTSIDE the jail because it creates the
+  // jail, so withholding it costs nothing.
+  test('is absent from an ordinary derivation', () => {
+    expect(pathsOf(BASE).filter(isForbidden)).toEqual([]);
+  });
+
+  test('is dropped even when a contract input names it', () => {
+    // The realistic route back in is a developer debugging `bwrap: command not
+    // found` and adding it. This asserts the derivation refuses, rather than
+    // trusting nobody will ask.
+    const set = deriveMountSet({
+      ...BASE,
+      pathInputs: [{ name: 'evil', value: '/usr/bin/bwrap', access: 'read' }],
+    });
+    expect(set.entries.map((e) => e.path)).not.toContain('/usr/bin/bwrap');
+  });
+
+  test('every forbidden path is actually recognised', () => {
+    for (const p of forbiddenPaths()) expect(isForbidden(p)).toBe(true);
+  });
+});
+
+describe('what the jail must not contain', () => {
+  test("celilo's data directory and its secrets are absent", () => {
+    const paths = pathsOf(BASE);
+    // Absence, not a check. These simply do not exist inside the jail.
+    expect(paths).not.toContain('/var/celilo');
+    expect(paths).not.toContain('/var/celilo/master.key');
+    expect(paths).not.toContain('/var/celilo/celilo.db');
+  });
+
+  test("a sibling module's tree is absent", () => {
+    const paths = pathsOf(BASE);
+    expect(paths).not.toContain('/var/celilo/modules');
+    expect(paths.some((p) => p.includes('/modules/technitium'))).toBe(false);
+  });
+
+  test('the celilo CLI is absent, so a hook cannot re-enter it (celilo#1121)', () => {
+    expect(pathsOf(BASE)).not.toContain('/usr/local/bin/celilo');
+  });
+});
+
+describe('ordering is semantic', () => {
+  test('the tmpfs leads, so it cannot erase the socket or a staged input', () => {
+    // Every staged contract input and the broker socket live under os.tmpdir().
+    // Bind them before the tmpfs and they vanish — and a hook whose backup_dir
+    // is silently empty SUCCEEDS and produces a backup containing nothing.
+    const set = deriveMountSet({
+      ...BASE,
+      pathInputs: [
+        { name: 'backup_dir', value: '/tmp/celilo-backup-9f/envelope/data', access: 'write' },
+      ],
+    });
+    const tmpfsAt = set.entries.findIndex((e) => e.mode === 'tmpfs' && e.path === '/tmp');
+    const socketAt = set.entries.findIndex((e) => e.path === BASE.socketDir);
+    const inputAt = set.entries.findIndex((e) => e.path.startsWith('/tmp/celilo-backup-'));
+
+    expect(tmpfsAt).toBeGreaterThanOrEqual(0);
+    expect(socketAt).toBeGreaterThan(tmpfsAt);
+    expect(inputAt).toBeGreaterThan(tmpfsAt);
+  });
+
+  test('writable directories come after the read-only module tree', () => {
+    const set = deriveMountSet({ ...BASE, screenshotDir: `${BASE.modulePath}/screenshots/run1` });
+    const treeAt = set.entries.findIndex((e) => e.path === BASE.modulePath && e.mode === 'ro');
+    for (const carved of ['state', 'generated', 'screenshots/run1']) {
+      const at = set.entries.findIndex((e) => e.path === `${BASE.modulePath}/${carved}`);
+      expect(at).toBeGreaterThan(treeAt);
+      expect(set.entries[at]?.mode).toBe('rw');
+    }
+  });
+});
+
+describe('contract inputs are bound at their declared access', () => {
+  test("'write' is read-write and 'read' is read-only", () => {
+    const set = deriveMountSet({
+      ...BASE,
+      pathInputs: [
+        { name: 'backup_dir', value: '/tmp/stage/data', access: 'write' },
+        { name: 'artifact_path', value: '/tmp/stage/db.sqlite', access: 'read' },
+      ],
+    });
+    expect(set.entries.find((e) => e.path === '/tmp/stage/data')?.mode).toBe('rw');
+    expect(set.entries.find((e) => e.path === '/tmp/stage/db.sqlite')?.mode).toBe('ro');
+  });
+
+  test('an undeclared input contributes nothing', () => {
+    // db_path was passed for months without being declared. A derivation that
+    // walks declarations cannot see it, which is the correct outcome here and
+    // the reason the contract has to declare what it passes (celilo#1118).
+    expect(pathsOf(BASE)).not.toContain('/var/celilo/celilo.db');
+  });
+});
+
+describe('paths are identical inside and outside', () => {
+  test('no entry is remapped', () => {
+    const args = toBwrapArgs(deriveMountSet(BASE));
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--bind' || args[i] === '--ro-bind') {
+        expect(args[i + 1]).toBe(args[i + 2] as string);
+      }
+    }
+  });
+
+  test('the jail names its own working directory', () => {
+    // The spawn sets no cwd, so the child inherits celilo's — a directory that
+    // usually does not exist inside the jail.
+    expect(deriveMountSet(BASE).chdir).toBe(BASE.modulePath);
+    expect(toBwrapArgs(deriveMountSet(BASE))).toContain('--chdir');
+  });
+});
+
+describe('~/.ssh is stage 2 only', () => {
+  test('bound read-only when supplied', () => {
+    const set = deriveMountSet({ ...BASE, sshDir: '/var/celilo/.ssh' });
+    expect(set.entries.find((e) => e.path === '/var/celilo/.ssh')?.mode).toBe('ro');
+  });
+
+  test('absent when not supplied, which is what stage 3 does', () => {
+    expect(pathsOf(BASE).some((p) => p.endsWith('/.ssh'))).toBe(false);
+  });
+});

package/src/hooks/mount-set.ts

@@ -0,0 +1,234 @@
+/**
+ * The hook jail's mount set (openspec/changes/hook-process-boundary, D9).
+ *
+ * A jailed hook sees exactly the paths listed here and nothing else. Not
+ * "denied" — ABSENT. A hook reaching for celilo's master key gets `ENOENT`,
+ * because inside the jail there is no such file. That is the acceptance
+ * criterion, and it is satisfied by absence rather than by a check.
+ *
+ * The set is DERIVED, never declared by the module. A module cannot ask for
+ * more, which is the whole point.
+ *
+ * This file is pure. It computes a description of a filesystem view and
+ * touches nothing. That is what lets `bwrap` is never in the mount set be a
+ * hermetic test rather than an integration one, and what lets the unjailed
+ * advisory lint (task 4.7) consume the same computation instead of a second
+ * one that can drift from it.
+ */
+
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import type { PathAccess } from '@celilo/capabilities';
+
+/**
+ * `tmpfs` is not an access level, it is "put a fresh empty filesystem here".
+ * It has to be its own mode because ORDER matters and a tmpfs erases whatever
+ * the jail would otherwise see at that path.
+ */
+export type MountMode = 'ro' | 'rw' | 'tmpfs';
+
+export interface MountEntry {
+  /**
+   * The path, IDENTICAL inside and outside the jail. Never remapped.
+   *
+   * Paths cross the capability boundary as strings: a hook hands the broker a
+   * path it wrote to, and the broker has to be able to read it. A remapped
+   * mount would make those two names disagree and the failure would look like
+   * a missing file rather than a translation bug.
+   */
+  readonly path: string;
+  readonly mode: MountMode;
+  /** Why this row exists. Surfaced by the unjailed lint and by `system doctor`. */
+  readonly reason: string;
+}
+
+export interface MountSet {
+  /**
+   * ORDER IS SEMANTIC. bubblewrap applies these in sequence and a later entry
+   * wins over an earlier one, which is what lets a read-write directory sit
+   * inside a read-only tree. Do not sort this list.
+   */
+  readonly entries: readonly MountEntry[];
+  /**
+   * The jail's working directory.
+   *
+   * The spawn does not set `cwd`, so a hook child inherits celilo's — whatever
+   * directory the operator's shell happened to be in. Inside the jail that
+   * directory usually does not exist, and bubblewrap fails on a path nobody
+   * chose. So the jail names one explicitly.
+   */
+  readonly chdir: string;
+}
+
+/** A path input the contract declared, paired with the value the framework resolved. */
+export interface DeclaredPathInput {
+  readonly name: string;
+  readonly value: string;
+  readonly access: PathAccess;
+}
+
+export interface MountSetRequest {
+  /**
+   * The module's own tree. Comes from the DB as `module.sourcePath`, which is
+   * NOT guaranteed to sit under the module store — a restored database carries
+   * the absolute paths of the box it was taken from (ISS-0052). Resolved below
+   * before it becomes a bind-mount argument.
+   */
+  readonly modulePath: string;
+  /** `<module>/state`, celilo#1000's sanctioned writable directory. */
+  readonly stateDir: string;
+  /** `<module>/screenshots/<run>`, this run only. Absent when the hook takes none. */
+  readonly screenshotDir?: string;
+  /** The directory holding the broker's unix socket. */
+  readonly socketDir: string;
+  /** The interpreter celilo spawns (`process.execPath`). */
+  readonly runtimePath: string;
+  /** The runner shim, which lives in celilo's tree rather than the module's. */
+  readonly runnerPath: string;
+  /** Contract-declared path inputs, already resolved to values. */
+  readonly pathInputs: readonly DeclaredPathInput[];
+  /**
+   * The operator's `~/.ssh`, read-only, STAGE 2 ONLY.
+   *
+   * `remote.ts` still runs inside the hook and needs the key. Stage 3 brokers
+   * those calls and drops this row, which is what turns D12's target check
+   * from a convention into a boundary. Dropping it before stage 3 lands
+   * hardens nothing — it just stops every hook reaching its own systems.
+   */
+  readonly sshDir?: string;
+}
+
+/** Directories whose contents the runtime needs in order to start at all. */
+const RUNTIME_SUPPORT_DIRS = ['/usr/lib', '/lib', '/lib64', '/etc/ssl'] as const;
+
+/**
+ * Paths that must NEVER appear in a mount set, whatever asks for them.
+ *
+ * `bwrap` is the load-bearing entry and the reason this list exists rather
+ * than being a comment. celilo ships an AppArmor profile granting `userns` to
+ * `/usr/bin/bwrap` so the jail can be built at all, and that grant applies to
+ * anyone on the box who runs it. A jailed hook that could exec `bwrap` would
+ * get a namespace of its own, be uid 0 inside it with `CAP_SYS_ADMIN`, and
+ * reach kernel surface an unprivileged user cannot otherwise touch — which is
+ * the entire reason Ubuntu restricts unprivileged user namespaces.
+ *
+ * `bwrap` runs OUTSIDE the jail because it is what creates the jail. It does
+ * not need to exist inside one, so leaving it out costs nothing.
+ *
+ * Task 4.10 already predicts how this gets undone: a browser hook fails with
+ * `bwrap: command not found`, a developer reads a missing binary and adds it,
+ * the suite goes green, and the escape path is open with nothing to read. The
+ * test on this constant is that missing thing to read.
+ */
+const NEVER_MOUNT = ['/usr/bin/bwrap', '/usr/local/bin/bwrap', '/bin/bwrap'] as const;
+
+function entry(path: string, mode: MountMode, reason: string): MountEntry {
+  return { path, mode, reason };
+}
+
+/**
+ * Compute the filesystem view a hook gets.
+ *
+ * Pure: resolves paths lexically and reads nothing from disk. `resolve` is not
+ * `realpath` — it cannot follow a symlink, because following one is I/O. The
+ * caller supplies already-real paths; on macOS that distinction is the
+ * difference between a rule that applies and one that silently does not
+ * (task 4.8), so the caller's `realpath` is not optional.
+ */
+export function deriveMountSet(request: MountSetRequest): MountSet {
+  const modulePath = resolve(request.modulePath);
+  const entries: MountEntry[] = [];
+
+  // 1. A private /tmp FIRST, because it erases everything beneath it.
+  //
+  // This has to lead. The broker's socket directory is an `mkdtemp` under
+  // `os.tmpdir()`, and every staged contract input (backup_dir, restore_dir,
+  // the cross-module roots) comes from `stagingDirFor`, also under
+  // `os.tmpdir()`. Bind those first and the tmpfs wipes them.
+  //
+  // The failure that causes is not a crash. A hook whose `backup_dir` is
+  // silently an empty tmpfs directory writes into it, returns success, and
+  // produces a backup containing NOTHING. It is found at restore. So the gate
+  // on this asserts the artifact is non-empty, never that the hook exited zero.
+  entries.push(entry('/tmp', 'tmpfs', 'private scratch, per run'));
+
+  // 2. The runtime. Without it nothing runs, so it is not really a policy row.
+  entries.push(entry(request.runtimePath, 'ro', 'the interpreter'));
+  entries.push(entry(dirname(request.runnerPath), 'ro', 'the runner shim celilo spawns'));
+  for (const dir of RUNTIME_SUPPORT_DIRS) {
+    entries.push(entry(dir, 'ro', 'shared libraries and trust store'));
+  }
+
+  // 3. The module's own tree, read-only, then its writable directories carved
+  //    on top. bubblewrap resolves that in the right order, which is why the
+  //    order here is not cosmetic.
+  //
+  //    D9 says "the module's own tree is bound read-only". These are the
+  //    carved exceptions to that sentence, and there are three of them rather
+  //    than the one D9's prose implies.
+  entries.push(entry(modulePath, 'ro', "the module's own tree"));
+  entries.push(
+    entry(resolve(request.stateDir), 'rw', 'ctx.stateDir, the sanctioned writable directory'),
+  );
+  entries.push(
+    entry(join(modulePath, 'generated'), 'rw', "celilo's generated output the hook may amend"),
+  );
+  if (request.screenshotDir) {
+    entries.push(entry(resolve(request.screenshotDir), 'rw', 'ctx.screenshotDir, this run only'));
+  }
+
+  // 4. The broker channel. Bound AFTER the tmpfs, per the note above.
+  entries.push(entry(resolve(request.socketDir), 'rw', 'the capability broker socket'));
+
+  // 5. Contract-declared path inputs, at the access the contract declares.
+  //    Never inferred from the name — see ContractField.path.
+  for (const input of request.pathInputs) {
+    entries.push(
+      entry(
+        resolve(input.value),
+        input.access === 'write' ? 'rw' : 'ro',
+        `contract input '${input.name}' (${input.access})`,
+      ),
+    );
+  }
+
+  // 6. Stage 2 only. See MountSetRequest.sshDir.
+  if (request.sshDir) {
+    entries.push(
+      entry(
+        resolve(request.sshDir),
+        'ro',
+        'remote.ts needs the key until the broker holds it (D12)',
+      ),
+    );
+  }
+
+  return {
+    entries: entries.filter((e) => !isForbidden(e.path)),
+    // The module's own tree is the only directory guaranteed to exist inside
+    // the jail and to mean something to the hook.
+    chdir: modulePath,
+  };
+}
+
+/** Is this path one nothing may ever mount? See NEVER_MOUNT. */
+export function isForbidden(path: string): boolean {
+  const resolved = isAbsolute(path) ? resolve(path) : path;
+  return NEVER_MOUNT.some((forbidden) => resolved === forbidden);
+}
+
+/** The forbidden list, for the test that asserts it is honoured. */
+export function forbiddenPaths(): readonly string[] {
+  return NEVER_MOUNT;
+}
+
+/** Render a mount set as bubblewrap arguments, in order. */
+export function toBwrapArgs(set: MountSet): string[] {
+  const args: string[] = [];
+  for (const e of set.entries) {
+    if (e.mode === 'tmpfs') args.push('--tmpfs', e.path);
+    else if (e.mode === 'rw') args.push('--bind', e.path, e.path);
+    else args.push('--ro-bind', e.path, e.path);
+  }
+  args.push('--chdir', set.chdir);
+  return args;
+}

package/src/manifest/contracts/v1.ts

@@ -22,7 +22,7 @@
  * change and requires a v2.0 contract.
  */
 
-import type { HookName } from '@celilo/capabilities';
+import type { HookName, PathAccess } from '@celilo/capabilities';
 
 /**
  * Per-input/output metadata.
@@ -33,6 +33,21 @@ import type { HookName } from '@celilo/capabilities';
  */
 export interface ContractField {
   required: boolean;
+  /**
+   * Set when the framework supplies a filesystem path in this field, and the
+   * access the hook is given to it. Absent means "not a path".
+   *
+   * The hook jail derives its bind mounts from this (design D9). Path-ness is
+   * NEVER inferred from the field name at runtime: a name heuristic silently
+   * changes behaviour the day somebody adds an input called `workspace`, and
+   * the symptom is an ENOENT on a path that visibly exists on the box.
+   *
+   * A field carrying a path-shaped value with no annotation here is a defect.
+   * `db_path` was one for months — passed by `backup-create.ts` and declared
+   * nowhere, so anything reasoning from this table was wrong about what a
+   * backup hook receives.
+   */
+  path?: { access: PathAccess };
 }
 
 /**
@@ -112,7 +127,7 @@ export const V1_HOOKS: ContractHooks = {
   },
   on_backup: {
     inputs: {
-      backup_dir: { required: true },
+      backup_dir: { required: true, path: { access: 'write' } },
       /**
        * Path to a directory containing read-only mirrors of OTHER modules'
        * `generated/terraform/` trees, plus an `index.json` enumerating
@@ -136,7 +151,7 @@ export const V1_HOOKS: ContractHooks = {
        *           terraform.tfstate
        *           terraform.tfstate.backup
        */
-      cross_module_root: { required: false },
+      cross_module_root: { required: false, path: { access: 'read' } },
     },
     outputs: {
       artifact_count: { required: true },
@@ -146,7 +161,7 @@ export const V1_HOOKS: ContractHooks = {
   },
   on_backup_analyze: {
     inputs: {
-      artifact_path: { required: true },
+      artifact_path: { required: true, path: { access: 'read' } },
     },
     outputs: {
       artifact_count: { required: true },
@@ -156,7 +171,7 @@ export const V1_HOOKS: ContractHooks = {
   },
   on_restore: {
     inputs: {
-      restore_dir: { required: true },
+      restore_dir: { required: true, path: { access: 'read' } },
       schema_version: { required: true },
       /**
        * Path to a writable staging directory the framework atomically
@@ -170,7 +185,7 @@ export const V1_HOOKS: ContractHooks = {
        * a single rename + cleanup of any stale files, so a partial
        * write (hook crashed mid-restore) leaves the live state intact.
        */
-      cross_module_write_root: { required: false },
+      cross_module_write_root: { required: false, path: { access: 'write' } },
     },
     outputs: {
       restored_items: { required: true },
@@ -296,6 +311,30 @@ export const V1_HOOKS: ContractHooks = {
     inputs: {},
     outputs: {},
   },
+  /**
+   * Reclaim disk a module's own store has accumulated and has no way to
+   * release on its own.
+   *
+   * Distinct from `on_backup`'s retention, which prunes copies celilo itself
+   * made and records. This is for state the module's SERVICE owns and celilo
+   * never sees — a registry's package store, a cache, an artifact directory —
+   * where the only thing that knows what is superseded is the service.
+   *
+   * Deliberately not a converge hook: convergence re-asserts a desired state
+   * and is safe to run constantly, while this DELETES and its mistakes are not
+   * recoverable. So it declares its retention policy in config, supports a dry
+   * run, and is expected to be conservative — the celilo-registry sweep never
+   * removes the last revision of a release, which is what makes running it
+   * unattended defensible.
+   *
+   * Driven on demand (`celilo module run-hook <module> sweep_revisions`) and,
+   * where the store grows without an operator, by a `timer.tick.*`
+   * subscription.
+   */
+  sweep_revisions: {
+    inputs: {},
+    outputs: {},
+  },
   /**
    * Build-bus upstream publish hook. The executor passes the
    * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,

package/src/manifest/schema.ts

@@ -366,6 +366,7 @@ const LIFECYCLE_HOOK_SCHEMAS = {
   reconcile_clients: LifecycleHookSchema.optional(),
   list_peers: LifecycleHookSchema.optional(),
   reconcile_peers: LifecycleHookSchema.optional(),
+  sweep_revisions: LifecycleHookSchema.optional(),
 } satisfies Record<HookName, z.ZodTypeAny>;
 
 /**

package/src/module/packaging/module-state-directory.test.ts

@@ -2,6 +2,7 @@ import { 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 { moduleStateDir } from '@celilo/capabilities';
 import { moduleIntegrity, modules } from '../../db/schema';
 import { cleanupTestDatabase, setupTestDatabase } from '../../test-utils/database';
 import { auditModule } from './audit';
@@ -78,9 +79,14 @@ describe('celilo#1000: state/ is the hook-writable directory', () => {
       const before = await auditModule('state-gate', db);
       expect(before.violations).toEqual([]);
 
-      // Now a hook runs and writes something nobody declared.
-      mkdirSync(join(root, 'state'), { recursive: true });
-      writeFileSync(join(root, 'state', unanticipatedName(42)), 'whatever the hook needed');
+      // Now a hook runs and writes something nobody declared. The path comes
+      // from the framework, NOT from this test: a gate that hand-rolls
+      // `join(root, 'state')` proves the audit tolerates a directory while
+      // saying nothing about whether a module can find it, which is exactly
+      // how the surface half of celilo#1000 shipped missing.
+      const stateDir = moduleStateDir(root);
+      mkdirSync(stateDir, { recursive: true });
+      writeFileSync(join(stateDir, unanticipatedName(42)), 'whatever the hook needed');
 
       const after = await auditModule('state-gate', db);
       expect(after.violations).toEqual([]);

package/src/policy/module-dep-reachability.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Every module's bundled `@celilo/*` range must be able to resolve the version
+ * the workspace is about to publish.
+ *
+ * The failure this exists to catch has no symptom. A module bundles its own
+ * copy of `@celilo/capabilities` and runs THAT copy (celilo#173), so when the
+ * workspace publishes a new major, a module still pinned to the old caret
+ * range keeps installing the old copy. Everything typechecks. Every test
+ * passes. The new export is simply unreachable to every module in the fleet,
+ * and nothing anywhere says so.
+ *
+ * That is not hypothetical. `firewall_registry` was registered in
+ * `CapabilityRegistry` and npm's published `@celilo/capabilities@2.6.0`
+ * contains zero occurrences of it. Every module bundled `^2.6.0`, and a caret
+ * range never crosses a major, so the registration reached nothing. It was
+ * found by a person reading the diff (celilo#1089), not by a gate.
+ *
+ * `npm-consumer-smoke` cannot see it: it installs from locally-packed tarballs
+ * and never consults a registry, which is exactly why this class drifts unseen.
+ * `check:modules` cannot see it either — it installs each module's DECLARED
+ * range and typechecks, so a module that does not yet USE the new export is
+ * perfectly happy on the old copy. Both gates are green while the thing is
+ * broken.
+ *
+ * ## THIS GATE IS DELIBERATELY NARROW. READ THIS BEFORE TRUSTING IT.
+ *
+ * Its name invites a stronger reading than it earns. It compares the WORKSPACE
+ * version against each module's range. It does NOT consult a registry, so it
+ * cannot see a gap between what is PUBLISHED and what a module bundles.
+ *
+ * Measured, not assumed: run against `00c12ec2^1` — the commit immediately
+ * before the Version Packages PR that shipped capabilities 3.0.0 — this gate
+ * passes 3/0. At that commit the workspace was 2.6.0 and every module was
+ * `^2.6.0`, which satisfies, while npm's published 2.6.0 contained zero
+ * occurrences of `firewall_registry`. **So it would not have caught
+ * celilo#1089, the bug it was written for.** Nor `hello-trespass` sitting at
+ * `^2.3.0`, because `satisfies('2.6.0', '^2.3.0')` is true: a caret crosses
+ * minors freely and stops only at a major.
+ *
+ * If you are here because a published export turned out to be unreachable and
+ * you are wondering why this was green: it never looked. That check needs a
+ * registry query, which is network-bound and therefore does not belong beside
+ * hermetic checks in `ci/validate` — a flaky gate gets disabled. Its home is
+ * the release pipeline or a scheduled job.
+ *
+ * And one limitation no in-repo gate can ever close, however it is written:
+ * out-of-repo modules. `lunacycle` lives outside this checkout and no sweep
+ * here can see its pin at all (lunacycle#64).
+ *
+ * What this DOES catch is a module whose pin is out of lockstep with the
+ * workspace, which happens when a module is added or edited outside the
+ * release sweep's window: the Version Packages PR is open with everything at
+ * `^3.0.0`, a new module merges to main at `^2.6.0`, the version PR merges,
+ * and nothing re-runs the sweep until the next release.
+ *
+ * `scripts/sync-consumer-pins.ts` is what normally keeps these aligned, and it
+ * runs inside the version-PR phase of `release.yml`. This gate is the check
+ * that it RAN and covered everything — a module added between releases carries
+ * whatever range its author typed until the next release sweeps it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { repoRoot } from './capability-shape';
+
+interface PackageJson {
+  name?: string;
+  version?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+function readJson(path: string): PackageJson {
+  return JSON.parse(readFileSync(path, 'utf-8')) as PackageJson;
+}
+
+/** `@celilo/*` package name → the version this checkout would publish. */
+function workspaceVersions(root: string): Map<string, string> {
+  const versions = new Map<string, string>();
+  for (const dir of ['packages', 'apps']) {
+    const base = join(root, dir);
+    if (!existsSync(base)) continue;
+    for (const entry of readdirSync(base)) {
+      const manifest = join(base, entry, 'package.json');
+      if (!existsSync(manifest)) continue;
+      const pkg = readJson(manifest);
+      if (pkg.name?.startsWith('@celilo/') && pkg.version) versions.set(pkg.name, pkg.version);
+    }
+  }
+  return versions;
+}
+
+interface ModuleDep {
+  module: string;
+  dep: string;
+  range: string;
+}
+
+/** Every `@celilo/*` dependency declared by any module's `scripts/` package. */
+function moduleDeps(root: string): ModuleDep[] {
+  const out: ModuleDep[] = [];
+  const modulesDir = join(root, 'modules');
+  for (const module of readdirSync(modulesDir)) {
+    const manifest = join(modulesDir, module, 'scripts', 'package.json');
+    if (!existsSync(manifest)) continue;
+    const pkg = readJson(manifest);
+    for (const [dep, range] of Object.entries({
+      ...(pkg.dependencies ?? {}),
+      ...(pkg.devDependencies ?? {}),
+    })) {
+      if (dep.startsWith('@celilo/')) out.push({ module, dep, range });
+    }
+  }
+  return out;
+}
+
+describe('a module can reach what the workspace publishes', () => {
+  const root = repoRoot();
+  const versions = workspaceVersions(root);
+  const deps = moduleDeps(root);
+
+  test('the scan found the workspace packages and the module deps', () => {
+    // An empty scan passes every assertion below while checking nothing, which
+    // is the failure mode that makes a green gate worse than no gate.
+    expect(versions.size).toBeGreaterThan(0);
+    expect(deps.length).toBeGreaterThan(0);
+    expect(versions.has('@celilo/capabilities')).toBe(true);
+  });
+
+  test('every module range resolves the version this checkout would publish', () => {
+    const unreachable = deps
+      .filter(({ dep, range }) => {
+        const version = versions.get(dep);
+        // A dep on a package this checkout does not build is out of scope: it
+        // resolves from the registry like any third-party dependency.
+        if (!version) return false;
+        return !Bun.semver.satisfies(version, range);
+      })
+      .map(
+        ({ module, dep, range }) =>
+          `${module} pins ${dep}@${range}, which cannot resolve the workspace's ${versions.get(dep)}`,
+      )
+      .sort();
+
+    const guidance = [
+      'A module bundles its own copy and runs THAT copy (celilo#173). A range that',
+      'cannot reach the version about to be published means every export added',
+      'since is unreachable to that module, silently.',
+      '',
+      'Fix: bun scripts/sync-consumer-pins.ts   (then commit the rewritten pins)',
+      '',
+      ...unreachable,
+    ].join('\n');
+
+    expect(unreachable, guidance).toEqual([]);
+  });
+
+  test('PROVE IT FAILS: a caret range does not cross a major', () => {
+    // The exact shape of celilo#1089: modules on ^2.6.0, workspace at 3.0.0.
+    expect(Bun.semver.satisfies('3.0.0', '^2.6.0')).toBe(false);
+    // And the near-miss that makes it easy to believe you are covered: a caret
+    // DOES cross a minor, so a lagging pin looks harmless right up until the
+    // major.
+    expect(Bun.semver.satisfies('2.6.0', '^2.3.0')).toBe(true);
+  });
+});

package/src/test-utils/module-fixtures.ts

@@ -8,6 +8,7 @@
  */
 
 import { CLIContext } from './cli-context';
+import { getModuleTestConfig } from './fixtures';
 import { type IntegrationTestContext, setupIntegrationTest } from './integration';
 
 /**
@@ -38,6 +39,52 @@ interface HomebridgeModuleOptions extends BaseFixtureOptions {
   withMockInfrastructure?: boolean;
 }
 
+/**
+ * A verified container service covering every allocatable zone, so a fixture
+ * can reach `module generate`.
+ *
+ * Extracted rather than copied: generation refuses without infrastructure, so
+ * every fixture that generates needs this, and a second inline copy would drift
+ * from the first the moment `containerServices` gains a column.
+ */
+async function insertMockContainerService(dbPath: string): Promise<void> {
+  const { getDb } = await import('../db/client');
+  const { containerServices } = await import('../db/schema');
+  const originalDbPath = process.env.CELILO_DB_PATH;
+  process.env.CELILO_DB_PATH = dbPath;
+  try {
+    const db = getDb();
+    await db.insert(containerServices).values({
+      id: 'test-proxmox',
+      serviceId: 'test-proxmox',
+      name: 'Test Proxmox',
+      providerName: 'proxmox',
+      zones: ['internal', 'dmz', 'app', 'secure'],
+      apiCredentialsEncrypted: JSON.stringify({
+        encryptedValue: 'dummy',
+        iv: 'dummy',
+        authTag: 'dummy',
+      }),
+      providerConfig: {
+        default_target_node: 'pve',
+        lxc_template: 'local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst',
+        storage: 'local-lvm',
+      },
+      verified: true,
+      verifiedAt: new Date(),
+      verificationError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+  } finally {
+    if (originalDbPath) {
+      process.env.CELILO_DB_PATH = originalDbPath;
+    } else {
+      process.env.CELILO_DB_PATH = undefined;
+    }
+  }
+}
+
 /**
  * Homebridge module fixture result
  */
@@ -83,41 +130,7 @@ export async function homebridgeModule(
 
   // Setup mock infrastructure if requested (needed for generation)
   if (options.withMockInfrastructure) {
-    const { getDb } = await import('../db/client');
-    const { containerServices } = await import('../db/schema');
-    const originalDbPath = process.env.CELILO_DB_PATH;
-    process.env.CELILO_DB_PATH = ctx.dbPath;
-    try {
-      const db = getDb();
-      await db.insert(containerServices).values({
-        id: 'test-proxmox',
-        serviceId: 'test-proxmox',
-        name: 'Test Proxmox',
-        providerName: 'proxmox',
-        zones: ['internal', 'dmz', 'app', 'secure'],
-        apiCredentialsEncrypted: JSON.stringify({
-          encryptedValue: 'dummy',
-          iv: 'dummy',
-          authTag: 'dummy',
-        }),
-        providerConfig: {
-          default_target_node: 'pve',
-          lxc_template: 'local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst',
-          storage: 'local-lvm',
-        },
-        verified: true,
-        verifiedAt: new Date(),
-        verificationError: null,
-        createdAt: new Date(),
-        updatedAt: new Date(),
-      });
-    } finally {
-      if (originalDbPath) {
-        process.env.CELILO_DB_PATH = originalDbPath;
-      } else {
-        process.env.CELILO_DB_PATH = undefined;
-      }
-    }
+    await insertMockContainerService(ctx.dbPath);
   }
 
   // Create CLI context with integration test env
@@ -195,6 +208,105 @@ export async function homebridgeModule(
   };
 }
 
+/**
+ * `dnsmasq-dhcp` fixture, for the golden comparison.
+ *
+ * ⚠️ IMPORTS THE REAL MODULE, `../../modules/dnsmasq-dhcp`, and not a copy under
+ * `test-fixtures/modules/`. That is the whole point of it.
+ *
+ * `homebridgeModule` imports a copy, and the copy has drifted 29 lines in the
+ * manifest and 6 in the Terraform template. So the golden gate compares
+ * generated-from-a-copy against golden-from-the-same-copy: both sides move
+ * together, and the shipped module is on neither. Worse, the copy is frozen at
+ * `version: 1.0.0` with the container-infrastructure variables `required: true`
+ * — the pre-fix state of a real bug (marking them required made homebridge
+ * container-only). The gate still passes against that shape and cannot notice
+ * it returning. Tracked as celilo#1084.
+ *
+ * Pointing at the shipped module means this golden fails when the generator's
+ * output for the shipped module changes, which is the only version worth having.
+ */
+export interface DnsmasqDhcpModuleFixture {
+  cli: CLIContext;
+  moduleId: string;
+  config: Record<string, unknown>;
+  context: IntegrationTestContext;
+  cleanup: () => Promise<void>;
+}
+
+export interface DnsmasqDhcpModuleOptions extends BaseFixtureOptions {
+  /** Seed a container service, without which generation has no infrastructure. */
+  withMockInfrastructure?: boolean;
+  /** Set the `network.internal.*` system config the templates resolve against. */
+  withSystemConfig?: boolean;
+}
+
+export async function dnsmasqDhcpModule(
+  options: DnsmasqDhcpModuleOptions = {},
+): Promise<DnsmasqDhcpModuleFixture> {
+  const ctx = await setupIntegrationTest();
+
+  if (options.withMockInfrastructure) {
+    await insertMockContainerService(ctx.dbPath);
+  }
+
+  const cli = await CLIContext.create('src/cli/index.ts', {
+    CELILO_DB_PATH: ctx.dbPath,
+    CELILO_DATA_DIR: ctx.dataDir,
+  });
+
+  const moduleId = 'dnsmasq-dhcp';
+
+  if (options.withSystemConfig) {
+    // `internal` only — it is the single zone this module declares, and adding
+    // others would put values in the golden that nothing generated from.
+    (await cli.run('system config set network.bridge vmbr0')).expectSuccess();
+    (await cli.run('system config set network.internal.vlan 1')).expectSuccess();
+    (await cli.run('system config set network.internal.gateway 10.99.1.1')).expectSuccess();
+    (await cli.run('system config set network.internal.subnet 10.99.1.0/24')).expectSuccess();
+    (
+      await cli.run(
+        'system config set ssh.public_key ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC... test@celilo',
+      )
+    ).expectSuccess();
+  }
+
+  // Read from `test-fixtures/test-values.yml` rather than written out here, so
+  // that file's entry for this module is load-bearing rather than decorative. A
+  // golden generated from values nothing else references would drift from the
+  // canonical set with nothing noticing.
+  //
+  // That entry carries EVERY `required: true` variable, including the ones with
+  // defaults: celilo asks for a required variable whether or not it has one,
+  // and an unanswered ask has no headless answer, so the command blocks until
+  // its timeout naming no variable.
+  const config = await getModuleTestConfig(moduleId);
+  if (Object.keys(config).length === 0) {
+    throw new Error(
+      `test-values.yml carries no entry for '${moduleId}', so this fixture would generate from an empty config and the golden would record that. Add one.`,
+    );
+  }
+
+  (await cli.run(`module import ../../modules/${moduleId}`)).expectSuccess();
+
+  for (const [key, value] of Object.entries(config)) {
+    // An array has to reach the CLI as JSON; a scalar is quoted as-is.
+    const encoded = Array.isArray(value) ? `'${JSON.stringify(value)}'` : `"${value}"`;
+    (await cli.run(`module config set ${moduleId} ${key} ${encoded}`)).expectSuccess();
+  }
+
+  if (options.generated) {
+    (await cli.run(`module generate ${moduleId}`)).expectSuccess();
+  }
+
+  const cleanup = async () => {
+    await cli.dispose();
+    await ctx.cleanup();
+  };
+
+  return { cli, moduleId, config, context: ctx, cleanup };
+}
+
 /**
  * Caddy module fixture options
  */