@celilo/cli 1.13.0 → 1.14.0

package/src/manifest/contracts/v1.ts

@@ -45,7 +45,8 @@ export interface ContractField {
    * 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.
+   * backup hook receives. It is gone: design D9b replaced it with the staged
+   * `system_state_root` below, which is declared and annotated.
    */
   path?: { access: PathAccess };
 }
@@ -152,6 +153,26 @@ export const V1_HOOKS: ContractHooks = {
        *           terraform.tfstate.backup
        */
       cross_module_root: { required: false, path: { access: 'read' } },
+      /**
+       * Path to a directory holding copies of celilo's OWN state: a
+       * WAL-correct `celilo.db` snapshot, `master.key`, the fleet `ssh/`
+       * keypair, and `module_src/<id>/` for every module's lean source.
+       * Populated by the framework under the same `cross_module_read`
+       * allow-list as `cross_module_root`; only celilo-mgmt receives it.
+       *
+       * This input is what makes celilo's own backup possible WITHOUT
+       * exempting celilo-mgmt from the hook jail (design D9b). The hook
+       * never read those bytes — it copied them into `backup_dir` — so the
+       * framework copies them into a directory it creates and hands over,
+       * and the data directory itself stays out of every mount set.
+       *
+       * It replaces `db_path`, which `backup-create.ts` passed for months
+       * while the contract declared nothing about it. That is the omission
+       * the docblock on `ContractField.path` names: anything reasoning from
+       * this table was wrong about what a backup hook receives, and a
+       * mount-set derivation walking the declared inputs could not see it.
+       */
+      system_state_root: { required: false, path: { access: 'read' } },
     },
     outputs: {
       artifact_count: { required: true },

package/src/manifest/validate.ts

@@ -202,14 +202,35 @@ const PRIVILEGED_CAPABILITY_ALLOW_LIST: Record<string, readonly string[]> = {
   cross_module_read: ['celilo-mgmt'],
 };
 
+/**
+ * Framework-granted capabilities that any module may declare.
+ *
+ * Same satisfaction path as the allow-list above — celilo supplies them, so no
+ * module provides them and the resolver must not go looking for one — but a
+ * different authorization story, and the two were welded together while
+ * `cross_module_read` was the only entry.
+ *
+ * `cross_module_read` hands a module every OTHER module's terraform state, so
+ * who may hold it is a per-module trust decision and the list is the gate.
+ * `control_plane_api` mints a principal whose grants are derived from
+ * `readOnlyGrants(COMMANDS)` and cannot be widened by the caller, so the worst
+ * a wrongly-declared consumer obtains is celilo's own read verbs. The gate is
+ * the `requires` line, which a reviewer reads before the module is ever
+ * imported (web-ui-console D7b).
+ *
+ * An allow-list here was considered and rejected: it would put consumer module
+ * ids in core, so every new console-shaped consumer would need a core change
+ * and a `.deb` release before it could be imported at all.
+ */
+const FRAMEWORK_GRANTED_CAPABILITIES: ReadonlySet<string> = new Set(['control_plane_api']);
+
 /**
  * Whether `name` is a framework-granted privilege rather than a normal
- * provider-backed capability. Privileges are satisfied by the framework
- * (gated by the allow-list above), so the capability-provider resolver
- * must NOT expect a module to "provide" them.
+ * provider-backed capability. Privileges are satisfied by the framework, so
+ * the capability-provider resolver must NOT expect a module to "provide" them.
  */
 export function isPrivilegedCapability(name: string): boolean {
-  return name in PRIVILEGED_CAPABILITY_ALLOW_LIST;
+  return name in PRIVILEGED_CAPABILITY_ALLOW_LIST || FRAMEWORK_GRANTED_CAPABILITIES.has(name);
 }
 
 /**

package/src/module/web-root.ts

@@ -0,0 +1,35 @@
+/**
+ * Where a module's built web site lives on this host.
+ *
+ * ONE application of the `site/dist` convention. It is deliberately not applied
+ * inside the providers: `public_web` is framework-provided, but `private_web`
+ * and `external_web` are implemented by modules (`caddy-internal`,
+ * `generic-cpanel-hosting-provider`), and three copies of one convention is how
+ * the copies drift.
+ *
+ * Core is also the only party that CAN resolve it in the case that matters.
+ * When the `public_web` provider converges a rebuilt host, no consumer is
+ * running to be asked where its bytes are (design D10). So the path has to come
+ * from the module id, and `modules.source_path` is what core already holds.
+ */
+
+import { join } from 'node:path';
+import { MODULE_WEB_ROOT } from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { modules } from '../db/schema';
+
+/**
+ * Absolute path to `<module root>/site/dist`, or undefined when no such module
+ * is installed.
+ *
+ * Does NOT check that the directory exists. Resolving a path and deciding
+ * whether it is usable are different jobs, and the second one belongs where the
+ * error can name the caller (Rule 10.1). `createPublicWeb`'s `requireWebRoot`
+ * does the existence check and says what to ship.
+ */
+export function resolveModuleWebRoot(moduleId: string, db: DbClient): string | undefined {
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) return undefined;
+  return join(module.sourcePath, MODULE_WEB_ROOT);
+}

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

@@ -255,6 +255,18 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: "PERMANENT — validating a manifest's declared capability names against the registry is core's job",
   },
+  {
+    file: 'apps/celilo/src/manifest/validate.ts',
+    capability: 'control_plane_api',
+    count: 1,
+    why: 'PERMANENT — framework-granted, so celilo satisfies it and no module provides it; the resolver has to be told that by name (web-ui-console D7b)',
+  },
+  {
+    file: 'apps/celilo/src/hooks/capability-loader.ts',
+    capability: 'control_plane_api',
+    count: 4,
+    why: "PERMANENT — framework-granted like web_routes above; core builds the method table because enrolment writes celilo's own api_principals row, which no module script can reach (web-ui-console D7b)",
+  },
   {
     file: 'apps/celilo/src/services/alerting/inbound-poller.ts',
     capability: 'notification',
@@ -420,8 +432,8 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
   {
     file: 'packages/capabilities/src/firewall.ts',
     capability: 'firewall',
-    count: 2,
-    why: 'PERMANENT — X10, the firewall capability contract',
+    count: 3,
+    why: 'PERMANENT — X10, the firewall capability contract. The third is FIREWALL_CAPABILITY_NAME, exported so core queries the provider registry without spelling the literal; it moved a name OUT of apps/celilo/src/console/projection.ts rather than adding one',
   },
   {
     file: 'packages/capabilities/src/public-web.ts',

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

@@ -38,6 +38,28 @@ describe('module script scan — SSH rules', () => {
   });
 });
 
+describe('module script scan — namespace tools (hygiene, not a boundary)', () => {
+  const NS = 'namespace escape (bwrap/unshare/nsenter)';
+
+  // Each token asserted separately and by name. An alternation that silently
+  // loses one leg still passes a test that only ever exercises the first.
+  it.each([
+    ['bwrap', 'run(`bwrap --dev-bind / / ${cmd}`);'],
+    ['unshare', "run('unshare --user --map-root-user id');"],
+    ['nsenter', "run('nsenter -t 1 -m -- ls /');"],
+    ['CLONE_NEWUSER', 'const flags = CLONE_NEWUSER | CLONE_NEWNS;'],
+  ])('catches %s', (_token, src) => {
+    expect(rules(src)).toContain(NS);
+  });
+
+  // The word boundaries are the whole of this rule's false-positive defence, so
+  // the negative case has to be a word that CONTAINS a token. `buildSharedConfig`
+  // would pass whether or not the `\b`s are there, which makes it no test at all.
+  it('does not fire on an identifier that merely contains a token', () => {
+    expect(rules('const unshared = pending.filter((p) => !p.shared);')).toEqual([]);
+  });
+});
+
 describe('module script scan — raw-exec escape hatch', () => {
   it('flags a runAppCommand call with no justification', () => {
     expect(rules('const r = runAppCommand(system, "rm -f /tmp/x", run);')).toContain(

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. */

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,7 @@ import {
   refuseIfInFlight,
   startOperation,
 } from './module-operations';
+import { stageSystemState } from './system-state-stage';
 
 export interface BackupCreateOptions {
   storageId?: string;
@@ -345,19 +346,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/)

package/src/services/celilo-mgmt-hooks.test.ts

@@ -1,19 +1,3 @@
-/**
- * Behavior tests for the celilo-mgmt module's on_backup / on_restore
- * hooks (Phase 3 of openspec/specs/management-server-backup/spec.md).
- *
- * We import the hook scripts directly and call their handlers with a
- * synthesized HookContext, then assert on the side-effects (files
- * written to backup_dir / restore staging dirs). This catches
- * regressions in the hook bodies without spinning up the full
- * deploy/backup pipeline.
- *
- * What this DOESN'T test: invokeHook validation, end-to-end backup
- * envelope round-trip. Those live in backup-envelope-roundtrip.test.ts
- * and (eventually) a fresh-box e2e.
- */
-
-import { Database } from 'bun:sqlite';
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -82,13 +66,13 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
   let dir: string;
   let backupDir: string;
   let crossModuleRoot: string;
-  let dbPath: string;
-  let keyPath: string;
+  let systemStateRoot: string;
 
   beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), 'celilo-mgmt-backup-test-'));
     backupDir = join(dir, 'backup-dir');
     mkdirSync(backupDir, { recursive: true });
+
     crossModuleRoot = join(dir, 'cross-module-root');
     mkdirSync(join(crossModuleRoot, 'modules', 'caddy', 'terraform'), { recursive: true });
     writeFileSync(
@@ -104,25 +88,20 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
       }),
     );
 
-    dbPath = join(dir, 'celilo.db');
-    // A REAL (minimal) SQLite DB. on_backup snapshots it via bun:sqlite
-    // serialize(), which requires a valid database file — a plain byte blob
-    // makes the serializer read a garbage page count and OOM. One table with a
-    // row is enough to exercise the snapshot path.
-    const seed = new Database(dbPath);
-    seed.run('CREATE TABLE backup_probe (id INTEGER PRIMARY KEY, v TEXT)');
-    seed.run("INSERT INTO backup_probe (v) VALUES ('hello')");
-    seed.close();
-    process.env.CELILO_DB_PATH = dbPath;
-
-    keyPath = join(dir, 'master.key');
-    writeFileSync(keyPath, 'fake-master-key-32-bytes-padding!');
-    process.env.CELILO_MASTER_KEY_PATH = keyPath;
+    // celilo's own state, as the framework stages it before invoking the hook
+    // (services/system-state-stage.ts). The hook reads nothing outside this
+    // directory and cross_module_root — that is what design D9b bought, and
+    // it is why there is no CELILO_DB_PATH or master.key on disk here.
+    systemStateRoot = join(dir, 'system-state');
+    mkdirSync(join(systemStateRoot, 'ssh'), { recursive: true });
+    mkdirSync(join(systemStateRoot, 'module_src', 'caddy'), { recursive: true });
+    writeFileSync(join(systemStateRoot, 'celilo.db'), 'SQLite format 3\u0000snapshot');
+    writeFileSync(join(systemStateRoot, 'master.key'), 'fake-master-key-32-bytes-padding!');
+    writeFileSync(join(systemStateRoot, 'ssh', 'id_ed25519'), 'PRIVATE');
+    writeFileSync(join(systemStateRoot, 'module_src', 'caddy', 'manifest.yml'), 'id: caddy');
   });
 
   afterEach(() => {
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {
@@ -130,16 +109,20 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
     }
   });
 
-  it('writes celilo.db, master.key, machine-pool.json, and cross_module_state into backup_dir', async () => {
+  it('lays the staged celilo state into backup_dir alongside the cross-module state', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
-    const ctx = buildContext({
-      backup_dir: backupDir,
-      cross_module_root: crossModuleRoot,
-    });
-    const result = (await hook(ctx)) as BackupHookOutput;
+    const result = (await hook(
+      buildContext({
+        backup_dir: backupDir,
+        cross_module_root: crossModuleRoot,
+        system_state_root: systemStateRoot,
+      }),
+    )) as BackupHookOutput;
 
     expect(existsSync(join(backupDir, 'celilo.db'))).toBe(true);
     expect(existsSync(join(backupDir, 'master.key'))).toBe(true);
+    expect(existsSync(join(backupDir, 'ssh', 'id_ed25519'))).toBe(true);
+    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'manifest.yml'))).toBe(true);
     expect(existsSync(join(backupDir, 'machine-pool.json'))).toBe(true);
     expect(
       existsSync(
@@ -153,39 +136,27 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
     expect(result.size_bytes).toBeGreaterThan(0);
   });
 
-  it('captures LEAN module source (excludes generated/, node_modules/, large build artifacts)', async () => {
-    // stateDir = dirname(db_path) = dir; on_backup reads dir/modules/<id>.
-    const modSrc = join(dir, 'modules', 'caddy');
-    mkdirSync(join(modSrc, 'scripts', 'node_modules', '@celilo'), { recursive: true });
-    mkdirSync(join(modSrc, 'generated', 'terraform'), { recursive: true });
-    mkdirSync(join(modSrc, 'ansible', 'files'), { recursive: true });
-    writeFileSync(join(modSrc, 'manifest.yml'), 'id: caddy');
-    writeFileSync(join(modSrc, 'scripts', 'hook.ts'), '// hook');
-    writeFileSync(join(modSrc, 'generated', 'terraform', 'main.tf'), 'resource {}');
-    writeFileSync(join(modSrc, 'scripts', 'node_modules', '@celilo', 'dep.js'), '// vendored');
-    // A >2MB "compiled binary" sitting in source — must be skipped by size.
-    writeFileSync(join(modSrc, 'ansible', 'files', 'server-bin'), Buffer.alloc(3 * 1024 * 1024));
-
+  it('refuses when the framework did not stage celilo state', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
-    await hook(buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot }));
 
-    // Source files captured...
-    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'manifest.yml'))).toBe(true);
-    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'scripts', 'hook.ts'))).toBe(true);
-    // ...but build/vendored content excluded (keeps the backup small enough to
-    // not OOM the in-memory tar+encrypt — turnip's full dirs were ~1.6GB).
-    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'generated'))).toBe(false);
-    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'scripts', 'node_modules'))).toBe(
-      false,
-    );
+    // Silence is the dangerous outcome here. Without the DB and the master
+    // key an envelope restores to nothing, and a hook that shrugged and
+    // returned success would report artifact_count > 0 for the machine-pool
+    // and cross-module files alone. Found at restore, which is too late.
     expect(
-      existsSync(join(backupDir, 'module_src', 'caddy', 'ansible', 'files', 'server-bin')),
-    ).toBe(false);
+      hook(buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot })),
+    ).rejects.toThrow(/system_state_root was not provided/);
   });
 
   it('machine-pool.json is valid JSON (array)', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
-    await hook(buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot }));
+    await hook(
+      buildContext({
+        backup_dir: backupDir,
+        cross_module_root: crossModuleRoot,
+        system_state_root: systemStateRoot,
+      }),
+    );
 
     const machinePool = JSON.parse(readFileSync(join(backupDir, 'machine-pool.json'), 'utf-8'));
     expect(Array.isArray(machinePool)).toBe(true);
@@ -194,25 +165,13 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
   it('proceeds (with a warning) when cross_module_root is missing', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
     const result = (await hook(
-      buildContext({ backup_dir: backupDir }), // no cross_module_root
+      buildContext({ backup_dir: backupDir, system_state_root: systemStateRoot }),
     )) as BackupHookOutput;
 
     expect(existsSync(join(backupDir, 'celilo.db'))).toBe(true);
     expect(existsSync(join(backupDir, 'cross_module_state'))).toBe(false);
     expect(result.schema_version).toBe('1.1');
   });
-
-  it('proceeds (with a warning) when master.key is missing on disk', async () => {
-    rmSync(keyPath);
-    const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
-    const result = (await hook(
-      buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot }),
-    )) as BackupHookOutput;
-
-    expect(existsSync(join(backupDir, 'master.key'))).toBe(false);
-    expect(existsSync(join(backupDir, 'celilo.db'))).toBe(true);
-    expect(result.artifact_count).toBeGreaterThan(0);
-  });
 });
 
 describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_restore', () => {