@celilo/cli 1.13.0 → 2.0.0

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

@@ -3,6 +3,11 @@
  * **modules never hand-build SSH, and the one sanctioned raw-exec path is
  * always justified in writing.**
  *
+ * It carries a second, weaker rule class as well — the namespace-tool rule
+ * below. Read that rule's own comment before touching it: it is hygiene and it
+ * is **not** a boundary, and the two classes in this file are not the same kind
+ * of thing.
+ *
  * ONE definition of the rules, used by both enforcement points:
  *
  *   - `apps/celilo/src/policy/no-hand-built-ssh.test.ts` — every in-repo module,
@@ -63,6 +68,33 @@ const PATTERN_RULES: Array<{ rule: string; re: RegExp; hint: string }> = [
     re: /(?:from|require\()\s*['"]ssh2['"]/,
     hint: 'Modules never open their own SSH connection — use the primitives. See MODULE_PRIMITIVES.md.',
   },
+  /**
+   * HYGIENE, NOT A MITIGATION (openspec/changes/hook-process-boundary, task 4.2e,
+   * design D9). The boundary is the jail; this line is a courtesy to an honest
+   * author, and describing it as a security control would be a lie in three
+   * separate ways:
+   *
+   *   - a hook runs arbitrary code, so anything this pattern catches can be
+   *     spelled another way by anyone who wants to;
+   *   - the scan walks in-repo `scripts/` and staged `.netapp` payloads, so it
+   *     never sees a registry module or an out-of-repo one at all;
+   *   - celilo#1014 is a live example of an exemption in this very file reading
+   *     wider than its author intended.
+   *
+   * What it is for: a module that shells out to `bwrap`/`unshare`/`nsenter`
+   * gets a namespace it is uid 0 in, and under the jail that either fails or
+   * nests badly. Telling the author at package time beats a confusing runtime
+   * failure on the fleet. Task 4.2d is the related-but-different guarantee, and
+   * it IS load-bearing: `bwrap` is never in the derived mount set.
+   */
+  {
+    rule: 'namespace escape (bwrap/unshare/nsenter)',
+    re: /\b(?:bwrap|unshare|nsenter)\b|CLONE_NEWUSER/,
+    hint:
+      'Hooks already run inside a namespace celilo builds; a module creating its own is ' +
+      'not supported and will not survive the jail. This is a hygiene check, not a security ' +
+      'boundary. If you need isolation the framework does not give you, say what for.',
+  },
 ];
 
 /** A `runAppCommand(` / `runAppCommandWithSecret(` CALL — not the import. */
@@ -110,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 [];
@@ -141,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');
+  });
+});

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

@@ -0,0 +1,70 @@
+/**
+ * Hook-jail regression — a host that used to jail its hooks and has stopped.
+ *
+ * Design D8's three states want three different things (see
+ * openspec/changes/hook-process-boundary/design.md): jailed is normal and
+ * raises nothing; a host that never jailed (a Mac) is a configuration fact
+ * that `celilo system doctor` reports and is NOT an event; a host that ran
+ * hooks jailed yesterday and runs them unjailed today is a kernel upgrade, an
+ * AppArmor policy change, or a changed container profile, and is exactly the
+ * failure that looks like nothing. Only the third state raises here.
+ *
+ * The state this reads is `hook-jail-mode.json`, written by `recordJailMode`
+ * on every real module-hook run. The transition survives the record being
+ * overwritten because an unjailed record carries `lastJailed` — the jailed
+ * record it replaced on the same host.
+ *
+ * The monitor scheduling this check is a SELF-monitor: `celilo monitor add
+ * hook_jail` creates it `suppressible: false`, so per
+ * openspec/specs/alerting/spec.md no ancestor alert and no deploy window can
+ * silence it. Losing confinement during a broad outage is precisely when it
+ * must still page.
+ *
+ * Deliberately cheap: one local file read, no remote contact, safe on every
+ * sweep.
+ */
+
+import type { AlertSeverity } from '../../db/schema';
+import type { JailModeRecord } from '../../hooks/jail';
+import { type FailingKey, builtinAlertKey } from './keys';
+
+export const HOOK_JAIL_CHECK = 'hook_jail';
+
+export interface HookJailState {
+  /** The recorded mode, or undefined when no hook has recorded one yet. */
+  record: JailModeRecord | undefined;
+  /** The host this check runs on, compared against the record's own. */
+  host: string;
+}
+
+/**
+ * One failing key when this host used to jail and has stopped; empty
+ * otherwise. The message names the host and the reason, which is what the
+ * security-model spec requires the alert to carry.
+ *
+ * A record written by another host is ignored rather than compared: a database
+ * or data directory restored onto a new box is a move, not a regression, and
+ * the new box has its own history to make.
+ */
+export function hookJailFailingKeys(state: HookJailState, severity: AlertSeverity): FailingKey[] {
+  const { record, host } = state;
+  if (!record || record.host !== host) return [];
+  if (record.mode !== 'unjailed' || !record.lastJailed) return [];
+
+  return [
+    {
+      key: builtinAlertKey(HOOK_JAIL_CHECK, 'host', host),
+      severity,
+      message:
+        `Hooks on ${host} ran jailed (${record.lastJailed.backend}) until ` +
+        `${record.lastJailed.recordedAt} and now run unjailed: ` +
+        `${record.reason ?? 'no reason was recorded'}`,
+      details:
+        'A host that quietly stops confining hooks is a failure that otherwise\n' +
+        'looks like nothing — the usual causes are a kernel upgrade, an AppArmor\n' +
+        'policy change, or a changed container profile. `celilo system doctor`\n' +
+        'reports what the host can do right now. The alert resolves when a hook\n' +
+        'runs jailed on this host again.',
+    },
+  ];
+}

package/src/services/alerting/run-monitor.test.ts

@@ -7,6 +7,7 @@ import type { DbClient } from '../../db/client';
 import { type Monitor, alerts, monitorRuns, monitors } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
 import type { HealthCheckResult } from '../health-runner';
+import { HOOK_JAIL_CHECK, type HookJailState } from './hook-jail';
 import { moduleAlertKey, moduleCheckAlertKey } from './keys';
 import { type MonitorRunDeps, runOneMonitor } from './run-monitor';
 import { loadLiveAlerts, markUnsuppressed } from './store';
@@ -40,6 +41,7 @@ describe('runOneMonitor', () => {
       runModuleCheck: async () => result,
       runBuiltinCheck: async () => [],
       loadModuleCoverage: () => [],
+      loadJailState: () => ({ record: undefined, host: 'test-host' }),
       now: () => now,
       graceMs: 60_000,
     };
@@ -182,4 +184,64 @@ describe('runOneMonitor', () => {
     expect(summary.outcome).toBe('success');
     expect(liveKeys()).toEqual([]);
   });
+
+  describe('the hook-jail self-monitor (hook-process-boundary task 4.4)', () => {
+    const HOST = 'celilo-mgr';
+    const regressed: HookJailState = {
+      host: HOST,
+      record: {
+        mode: 'unjailed',
+        backend: 'none',
+        reason: 'bubblewrap is installed but could not build a namespace',
+        host: HOST,
+        recordedAt: NOW.toISOString(),
+        lastJailed: { backend: 'bubblewrap', recordedAt: '2026-07-27T03:00:00.000Z' },
+      },
+    };
+    const healed: HookJailState = {
+      host: HOST,
+      record: {
+        mode: 'jailed',
+        backend: 'bubblewrap',
+        host: HOST,
+        recordedAt: LATER.toISOString(),
+      },
+    };
+
+    let jailMonitor: Monitor;
+
+    beforeEach(() => {
+      db.insert(monitors)
+        .values({
+          id: 'mon-jail',
+          kind: 'builtin_check',
+          target: HOOK_JAIL_CHECK,
+          intervalMinutes: 15,
+          severity: 'critical',
+          suppressible: false,
+        })
+        .run();
+      jailMonitor = db.select().from(monitors).where(eq(monitors.id, 'mon-jail')).get() as Monitor;
+    });
+
+    const jailDeps = (state: HookJailState, now: Date = NOW): MonitorRunDeps => ({
+      ...deps(healthy, now),
+      loadJailState: () => state,
+    });
+
+    test('a jailed-to-unjailed transition fires an alert naming the host', async () => {
+      const summary = await runOneMonitor(db, jailMonitor, jailDeps(regressed));
+      expect(summary.outcome).toBe('success');
+      const live = loadLiveAlerts(db, jailMonitor.id);
+      expect(live.map((a) => a.key)).toEqual([`builtin:hook_jail/host:${HOST}`]);
+      const row = db.select().from(alerts).where(eq(alerts.monitorId, jailMonitor.id)).get();
+      expect(row?.message).toContain(HOST);
+    });
+
+    test('re-jailing resolves it by set difference', async () => {
+      await runOneMonitor(db, jailMonitor, jailDeps(regressed));
+      await runOneMonitor(db, jailMonitor, jailDeps(healed, LATER));
+      expect(loadLiveAlerts(db, jailMonitor.id)).toEqual([]);
+    });
+  });
 });

package/src/services/alerting/run-monitor.ts

@@ -19,6 +19,7 @@ import type { HealthCheckResult } from '../health-runner';
 import { failingKeysFromFindings } from './builtin-monitors';
 import { HEALTH_COVERAGE_CHECK, healthCoverageFailingKeys } from './health-coverage';
 import type { ModuleCoverageInput } from './health-coverage';
+import { HOOK_JAIL_CHECK, type HookJailState, hookJailFailingKeys } from './hook-jail';
 import {
   type FailingKey,
   builtinMonitorKey,
@@ -35,6 +36,8 @@ export interface MonitorRunDeps {
   runBuiltinCheck(category: DriftCategory): Promise<DriftFinding[]>;
   /** Module roster for the health-coverage check. */
   loadModuleCoverage(): ModuleCoverageInput[];
+  /** Recorded jail mode and current host, for the hook-jail self-monitor. */
+  loadJailState(): HookJailState;
   now(): Date;
   /** Grace window before a new alert may notify. */
   graceMs: number;
@@ -95,6 +98,15 @@ async function runCheck(
     };
   }
 
+  // Same shape: one local file read. This is the self-monitor for D8's third
+  // state — a host that used to jail its hooks and has stopped.
+  if (monitor.target === HOOK_JAIL_CHECK) {
+    return {
+      outcome: 'success',
+      failingKeys: hookJailFailingKeys(deps.loadJailState(), severity),
+    };
+  }
+
   const category = monitor.target as DriftCategory;
   try {
     const findings = await deps.runBuiltinCheck(category);

package/src/services/alerting/sweep-runner.test.ts

@@ -42,6 +42,7 @@ describe('runSweep', () => {
       runModuleCheck: async () => result,
       runBuiltinCheck: async () => [],
       loadModuleCoverage: () => [],
+      loadJailState: () => ({ record: undefined, host: 'test-host' }),
       now: () => now,
       graceMs: 60_000,
     };

package/src/services/api-principal-enrolment.test.ts

@@ -18,6 +18,7 @@ import { COMMANDS, readOnlyGrants } from '@celilo/core';
 import { closeDb } from '../db/client';
 import { getPrincipalByName, isAuthorized } from './api-access';
 import {
+  buildControlPlaneApi,
   controlPlaneReadGrants,
   enrolControlPlanePrincipal,
   revokeControlPlanePrincipal,
@@ -177,3 +178,75 @@ describe('revocation', () => {
     expect(await revokeControlPlanePrincipal('never-existed')).toBe(false);
   });
 });
+
+describe('the capability handed to a consuming module', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-cpa-'));
+    process.env.CELILO_DB_PATH = join(dir, 'test.db');
+    closeDb();
+  });
+
+  afterEach(() => {
+    closeDb();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('enrols the caller and reports the grants it may use', async () => {
+    const api = buildControlPlaneApi('celilo-web-console');
+    const result = await api.enrol_principal({
+      name: 'celilo-web-console',
+      publicKey: PUBLIC_KEY,
+    });
+
+    expect(result.created).toBe(true);
+    expect(result.grants).toEqual(controlPlaneReadGrants());
+    expect(await getPrincipalByName('celilo-web-console')).not.toBeNull();
+  });
+
+  test('a module may NOT enrol under a neighbour’s name', async () => {
+    // Otherwise any module holding this capability rotates the console's key by
+    // presenting its own public half under the console's name — the console then
+    // holds a principal whose authorized_keys entry it cannot log in with, and
+    // the attacker holds one that works.
+    const api = buildControlPlaneApi('hello-foo');
+
+    await expect(
+      api.enrol_principal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY }),
+    ).rejects.toThrow(/only enrol its own principal/);
+    expect(await getPrincipalByName('celilo-web-console')).toBeNull();
+  });
+
+  test('a module may NOT revoke a neighbour’s principal', async () => {
+    // The denial-of-service half of the same hole: revocation is idempotent and
+    // returns false for a name that never existed, so an unguarded revoke gives
+    // no signal at all that a module just deleted someone else's access.
+    await enrolControlPlanePrincipal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+    const api = buildControlPlaneApi('hello-foo');
+
+    await expect(api.revoke_principal({ name: 'celilo-web-console' })).rejects.toThrow(
+      /only revoke its own principal/,
+    );
+    expect(await getPrincipalByName('celilo-web-console')).not.toBeNull();
+  });
+
+  test('withdraws its own principal, and finding nothing is not an error', async () => {
+    const api = buildControlPlaneApi('celilo-web-console');
+    await api.enrol_principal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+
+    expect(await api.revoke_principal({ name: 'celilo-web-console' })).toEqual({ revoked: true });
+    expect(await api.revoke_principal({ name: 'celilo-web-console' })).toEqual({ revoked: false });
+  });
+
+  test('what it enrols cannot write, whatever the caller asked for', async () => {
+    // The grant set is not a parameter, so there is nothing to ask for. This
+    // asserts the consequence rather than the absence: the principal the
+    // capability produces is refused a deploy.
+    const api = buildControlPlaneApi('celilo-web-console');
+    await api.enrol_principal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+
+    expect(await isAuthorized('celilo-web-console', 'module', 'list')).toBe(true);
+    expect(await isAuthorized('celilo-web-console', 'module', 'deploy')).toBe(false);
+  });
+});

package/src/services/api-principal-enrolment.ts

@@ -40,6 +40,7 @@
  * into a negotiation with the caller.
  */
 
+import type { ControlPlaneApiCapability } from '@celilo/capabilities';
 import { COMMANDS, readOnlyGrants } from '@celilo/core';
 import { grantPrincipal, revokePrincipal } from './api-access';
 
@@ -101,3 +102,57 @@ export async function enrolControlPlanePrincipal(params: {
 export async function revokeControlPlanePrincipal(name: string): Promise<boolean> {
   return revokePrincipal(name);
 }
+
+/**
+ * The `control_plane_api` method table handed to one consuming module.
+ *
+ * ## Why celilo builds this and no module provides it
+ *
+ * Every other function capability is implemented by a provider module's script,
+ * which the loader imports and calls. That is structurally impossible here.
+ * Enrolment writes celilo's own `api_principals` row and derives its grants from
+ * celilo's own command registry, and a module script may import nothing but
+ * `@celilo/capabilities` — its scripts are copied to a data directory at deploy,
+ * so a relative import into the backend breaks. celilo-mgmt has exactly the same
+ * limit as any other module here; being the management server's module does not
+ * give its SCRIPTS a database handle.
+ *
+ * The only shape that would let celilo-mgmt "provide" it is core injecting
+ * enrol/revoke into a factory context so the module's script forwards them
+ * unchanged. Core would still do all the work, and the enrolment would newly
+ * depend on the deployed copy of that script being current — a way to fail that
+ * does not exist today. So this is framework-granted, like `cross_module_read`.
+ *
+ * ## Why the caller cannot name someone else's principal
+ *
+ * `name` is on the request because the contract puts it there, and the only
+ * value accepted is the calling module's id. Without that check any module with
+ * the capability could rotate another module's key by enrolling under its name,
+ * or delete it outright by revoking it — the console's read access removed by a
+ * module that has nothing to do with the console.
+ *
+ * The parameter should come off the contract entirely, the same argument that
+ * kept `grants` off it: a caller that can negotiate WHOSE authority this is has
+ * the same problem as one that can negotiate how much. That is a breaking change
+ * to `@celilo/capabilities`' exported types, so it waits for the next major
+ * rather than forcing one (celilo#1196).
+ */
+export function buildControlPlaneApi(consumerModuleId: string): ControlPlaneApiCapability {
+  function requireOwnPrincipal(name: string, verb: string): void {
+    if (name === consumerModuleId) return;
+    throw new Error(
+      `Module '${consumerModuleId}' tried to ${verb} the API principal '${name}'. A module may only ${verb} its own principal, named for its module id.`,
+    );
+  }
+
+  return {
+    async enrol_principal(request) {
+      requireOwnPrincipal(request.name, 'enrol');
+      return enrolControlPlanePrincipal(request);
+    },
+    async revoke_principal(request) {
+      requireOwnPrincipal(request.name, 'revoke');
+      return { revoked: await revokeControlPlanePrincipal(request.name) };
+    },
+  };
+}

package/src/services/backup-create.ts

@@ -6,7 +6,7 @@
 import { copyFileSync, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
-import { getDbPath } from '../config/paths';
+import { getDbPath, getMasterKeyPath } from '../config/paths';
 import { getDb } from '../db/client';
 import { moduleConfigs, modules, secrets as secretsTable } from '../db/schema';
 import { invokeHook } from '../hooks/executor';
@@ -41,6 +41,8 @@ import {
   refuseIfInFlight,
   startOperation,
 } from './module-operations';
+import { remoteAccessPolicy } from './remote-access';
+import { stageSystemState } from './system-state-stage';
 
 export interface BackupCreateOptions {
   storageId?: string;
@@ -345,19 +347,44 @@ export async function createModuleBackup(
     const { configMap, secretMap } = await buildModuleContext(moduleId);
     const logger = createConsoleLogger(moduleId, 'on_backup');
 
-    // Inject the framework-resolved DB path so the hook need not re-derive the
-    // data dir from an env var the CLI may not export (ISS-0014). getDbPath()
-    // is celilo's single source of truth for where the DB lives, regardless of
-    // CELILO_DATA_DIR / XDG / explicit override; the hook derives the data dir
-    // (master.key, fleet .ssh) as dirname(db_path) from this.
     const hookInputs: Record<string, unknown> = {
       backup_dir: dataDir,
-      db_path: getDbPath(),
     };
+    // Both privileged inputs ride the same allow-list. `cross_module_root`
+    // mirrors OTHER modules' terraform state; `system_state_root` stages
+    // celilo's own — the DB snapshot, master.key, the fleet key, and every
+    // module's lean source.
+    //
+    // Staging is what lets celilo back ITSELF up without exempting
+    // celilo-mgmt from the hook jail (design D9b). The hook used to receive
+    // `db_path` and walk out from `dirname(db_path)` into celilo's data
+    // directory; it never read those bytes, it copied them, so the framework
+    // does the copying and the data directory stays out of the mount set.
     if (moduleHasCrossModuleRead(manifest)) {
       const crossModuleRoot = join(tempDir, 'cross-module-read');
       materializeCrossModuleRoot(crossModuleRoot, moduleId);
       hookInputs.cross_module_root = crossModuleRoot;
+
+      const staged = stageSystemState(join(tempDir, 'system-state'));
+      hookInputs.system_state_root = staged.root;
+      if (!staged.masterKeyStaged) {
+        logger.warn(
+          `master.key not found at ${getMasterKeyPath()} — secrets in the DB snapshot will be unreadable on restore.`,
+        );
+      }
+      if (!staged.fleetSshStaged) {
+        logger.info(
+          'No fleet SSH keypair on this box — none staged (celilo-mgmt may not have been deployed yet).',
+        );
+      }
+      logger.info(`Staged celilo state: ${staged.moduleSourceCount} module source tree(s)`);
+      if (staged.skippedLarge.length > 0) {
+        // No silent caps: name what was dropped. These are build artifacts the
+        // target rebuilds on deploy.
+        logger.info(
+          `Skipped ${staged.skippedLarge.length} large/non-source file(s) (rebuilt on deploy): ${staged.skippedLarge.join(', ')}`,
+        );
+      }
     }
 
     // Execute on_backup hook — it writes artifacts to dataDir (envelope/data/)
@@ -373,6 +400,7 @@ export async function createModuleBackup(
       {
         debug: false,
         systems: getModuleSystems(moduleId, db),
+        remoteAccess: remoteAccessPolicy(moduleId, db),
       },
     );
 
@@ -537,6 +565,7 @@ export async function importModuleBackup(
         {
           debug: false,
           systems: getModuleSystems(moduleId, db),
+          remoteAccess: remoteAccessPolicy(moduleId, db),
         },
       );